[Lazarus] FPDoc editor and document placement

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

>> Problems arise with branches.
> 
> For example?

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.


>>> The current fpdoc documentation is only for sources and is only valid
>>> for the associated version. A help entry may be wrong for an older
>>> version, or an identifier might be renamed or moved to another place.
>> Moved or renamed items will loose their associated documentation anyhow.
> 
> Not anyhow.
> When you rename an identifier the corresponding fpdoc entry must be
> renamed too. This could be done by the IDE. In fact I already started
> it.

Fine :-)


>> Let's assume a single help directory associated with every package. Then 
>> two search strategies for help files can be used:
>> 1) find the package containing the file, then search the help directory 
>> associtated with that package, or
>> 2) find the help directory containing the file.
>>
>> In the first case a list of packages has to be searched, then the 
>> associated help directories. Packages or units not in that list can not 
>> be found, e.g. when no package exists for the IDE project.
> 
> In other words: If a package has help it is found, if a package has
> no help, nothing is found.

If no package is found, *or* the package was found but does not have help...


>> In the second case a list of help directories is required, that can be 
>> maintained by the user or package system. A single machine-specific xml 
>> directory may be sufficient, with subdirectories for all packages, so 
>> that no existing help file can be missed in the search. A concrete unit 
>> owner is not required, the help directory name can be used for that 
>> purpose. E.g. the complete LCL help can be created from 
>> <helpdir/xml>/lcl/*.xml.
> 
> 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.

In fact a versioning system were nice for the documentation, where added 
or updated help can be applied either to common help or to version 
(branch...) specific help. Most entries apply to all versions, and it 
even does no harm to add version 2.0 specific extensions to the common 
lcl help - they will never be searched when working with 1.0 code.

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.

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.


> How should help files for third party packages be distributed?

Usually these are distributed as part of the package. As you suggested 
already, the user can add a symlink to that help after installation, or 
the help can be placed into the user/machine specific help directory on 
installation of the package.


>>>> I do not really understand this requirement, in 
>>>> detail when Lazarus.lpi is not detected/accepted as the owning project :-(
>>> I hope you understand now.
>> No, see above.
>>
>> 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? As already mentioned, a single LazDoc path may 
be sufficient, when all docs are installed into subdirectories of that 
directory. The package-specific location of the docs is required only at 
the time of installation of the package, later on the help system will 
know where to find all the installed docs.


> Do you have an example where the IDE can not find a fpdoc file?

When the FPDoc Editor denies to create an item, and requires to add the 
source file 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?

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.


>>>> IMO a default directory could be used to store help on source files, 
>>>> whose owner cannot be determined.
>>> Please check before writing.
>>> It exists since years.
>> Sorry, not in my time machine :-(
>>
>>> See Environment options / FPDoc editor / FPDoc files path.
>> These pathes do not specify unit owners, so I wonder in what situations 
>> these directories are searched at all.
> 
> For example when a user does no want to use the Lazarus package system.

I'm really confused now :-(

First FPDoc Editor requires that the source file is part of a package. 
Then you say that this is not (no more?) a requirement. So what's the 
use of added pathes?

When a help directory can be specified whenever a non-packaged file is 
documented, the help system (later) has no idea in which directory that 
help file has been created, and consequently must search the entire help 
path. Until here a single NonPackaged directory would be sufficient to 
hold all such help files. When multiple such directories are allowed, 
the help system still cannot know whether Unit1.xml should be loaded 
from directory X or Y :-(


>>> The fpdoc editor does not support to create new fpdoc files for such
>>> units.
>> That's why we should allow to create help for unowned files first, 
>> before we discuss how they can be found later again.
> 
> IMO finding help files is the most important thing. F1 must work out of
> the box with minimal setup.

ACK. The FPDoc Editor should also work with minimal setup, since it 
doesn't require to press F1 all the time, and does not require compiled 
(HTML) help.

> The current model is this: I download a
> package from the net, open it in the IDE and can press F1 on an
> identifier to get help. All details are up to the package maintainer.

Details are not (only) up to the package maintainer, but also are up to 
the package installer and help system.

As mentioned already in my preface, the FPDoc Editor is of my actual 
interest. As I could figure out till now, everything boils down to the 
(fragile) determination of the owner of an source file, based on only(?) 
the module name. When that module name is unique, knowledge of the owner 
is not required, it only can speed up the first search for the according 
help file. My impression is that all(?) registered packages are scanned 
at IDE startup, so that instead the registered help directories could be 
scanned as well.

DoDi