[Lazarus] FPDoc editor and document placement

[Hans-Peter Diettrich]

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