Mattias Gaertner schrieb:
When I work in a local branch, and find something worth to document,
then this documentation is added to the branch and removed when
switching back to another branch.
Why not merge the change to the other branches?
I'm using Git in my experiments, and switch branches frequently. After a
while it's hard to remember in which branch I've updated the
documentation, and into which other branches the updates have not yet
been merged. That's the most important argument for storing
documentation apart from source code.
How can help files for lcl version 1.0 and lcl version 2.0 be
distinguished?
When this matters, the user can create separate doc folders.
How should that work with the above search pattern
<helpdir/xml>/lcl/*.xml.
?
The helpdir is set in the Lazarus options, so that Lazarus1 uses lcl 1.0
and LazHelp1, and Lazarus2 uses lcl 2.0 and the LazHelp2 directory.
[...]
Only the final documentation may have to know about versions, so that
the proper overviews can be created for the 1.0 and 2.0 version. IMO
such overviews *always* should be created from the source code of the
proper version (like makeskel does), not from manually maintained lists
in help or topic files. The related entries then can be collected from
the separate help files, where every item can be tagged with the version
that introduced (moved, renamed...) that source code item.
AFAIK fpdoc does not support such tagging.
That's not a general problem - XML supports any number of tags ;-)
Since documentation is written only after the source code has been
created and committed, it doesn't make sense to have both in the same
versioning system. When help *on* r0815 source code is committed, the
help should become visible *starting* with r0815 as well, not only when
committed *as* r4711. Of course SVN doesn't allow to amend an older
commit, so that separate source and help repositories IMO are the only
viable solution.
True.
When can this change be expected?
@Graeme: can you split your Git repository accordingly?
Overriding the fpdoc search path for packages is needed.
It may be a good idea to move all help directories under docs/, and to
turn Lazarus/docs into an SVN (sub-)project.
[...]
Dedicated help directories are somewhat self-organizing, no chance for
missing help files in a search. But lists of packages and their
contained files can be incomplete.
If the file is not listed in any package the IDE searches in the unit
and src paths of all packages.
Why use search paths for packages, when it's easier to specify search
paths for documentation?
I understood the question as what happens when the lpk file does not list all
files of the
package.
This is one case that can never occur when the directories are searched
for the source and help files :-)
The IDE will fail to associate a unit that is in a
directory only used on another target. So the IDE does not know where
the help is for the w32wscontrols.pas under Linux.
The help is in the same place on all platforms.
Although with some
guesswork it could. Maybe this will be added, when the problem arises.
So far no one needed that.
I just found a lot of help for the gtk widgetset, so no general problem
seems to exist. I only couldn't make the FPDoc Editor display content of
these files (on Windows). It should not be a problem to find
<lazdocdir>/xml/lcl/interfaces/gtk/gtkdef.xml for
<lazdir>/lcl/interfaces/gtk/gtkdef.pp.
When Lazarus/lcl/ (currently) is associated with Lazarus/docs/xml/lcl/,
or ../docs/xml/lcl/, the remaining interfaces/gtk/ portion can be
applied to that root directory.
As already mentioned, a single LazDoc path may
be sufficient, when all docs are installed into subdirectories of that
directory.
Of what directory? The directory of the current unit or the global
override directory for fpdoc files?
All help files should reside in subdirectories of the global fpdoc
directory, i.e. currently in the Lazarus/docs/xml/ directory. No
difference to the current handling, only that the $(LazarusDir)/docs/
part should be replaced by $(LazarusDocs). Then the FPDoc search path
must not contain separate entries for all the subdirectories (lcl,
rtl...), as long as these reside in the same parent directory (as is).
Extra entries will be required only for third-party packages, whose help
resides in other directories, or a symlink to that directory can be put
into the default help directory.
The FPDoc editor is only a tool for the Lazarus way of fpdoc files. Its
big brother lazde can be used to create any kind of fpdoc files.
How does lazde make the created files known to the IDE?
And AFAIR lazde had the same problem, with files not belonging to a package.
As a concrete example, I couldn't add help on widgetset-specific units
like win32wscomctrls.pp. Why should help be available only for installed
packages, known to the IDE, when the IDE allows to *open* source files
without such a restriction?
The IDE allows to open a win32wscomctrls.pp, but many code features
only work under windows.
It's sufficient when the IDE (FPDoc Editor or F1) also shows the help
for the opened units.
The unit belongs to the package LCL, which has no fpdoc path set yet.
When I open the unit qtobjects.pas under Linux/QT, move cursor to
an identifier and click on "create" in the fpdoc editor the IDE asks me
to setup a fpdoc path first. I set it to "docs/xml/lcl" and a new fpdoc
file is created. It's pretty easy.
Again, how is that file (or directory) made known to the IDE?
When e.g. an index file is added to every source directory, that file
could contain all the information required to find the associated help
files. Such a file can be created automatically, or when not found the
parent directories can be searched. Then the help file for
$(LazDir)/lcl/interfaces/win32/someunit.pp could be found in
$(LazDoc)[/xml]/lcl/interfaces/win32/someunit.xml, with the only
required information that $(LazDir)/lcl/ is the root directory of
package lcl. For projects an existing .lpi file could be used as the
root-directory marker of the project, and similar conventions could
apply to package directories.
First of all, the lpk is an index. No need to invent another one.
It only is a manually created and maintained index, which does not
necessarily contain all files of the package (etc.).
Searching the lpk/lpi file when opening a unit is a good idea.
But an lpi or lpk file is not always placed in the root
directory of a package/project. In fact many ported Delphi
packages/projects put the Lazarus stuff into a sub directory. A more
sophisticated search is needed.
Fourth, a special solution for the packages in the Lazarus sources can
be done.
And all this is why I suggested an independent/additional file, that can
be added to every package source directory. Such a file is required only
when the IDE can not otherwise locate the root directory of a package or
project. The IDE can e.g. search for an '*.lp?' file, in the directory
of the source file and all parent directories. Once such a file is
found, its name specifies the project or package name, and the default
location (directory name) of the associated documentation in the LazDoc
path. In so far I don't understand why the lcl package file is named
lclbase.lpk, and not lcl.lpk :-(
DoDi
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
