[Lazarus] FPDoc editor and document placement

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

>> Nonetheless most entries (I visited) are in poor state, not helpful and 
>> often wrong (outdated?). That's why I want to contribute myself, and 
>> want my documentation *never* overwritten automatically by SVN updates 
>> (merging of course will be acceptable).
> 
> svn does not simply overwrite modified files. It tries to merge updates.

Problems arise with branches.


>> Unfortunately the current help document (xml) management gets into the 
>> way very often. Here some problems:
>>
>> - How to share documentation across multiple Lazarus installations?
>> (including working with Lazarus/FPC branches)
> 
> 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.

> Normally the biggest part of the entries can be used for older versions
> and the newest version of a package contains the best fpdoc entries.
> Therefore it might be desirable to use an old version of a package for
> compiling and use the documentation of the newer version.

ACK.

> But this works only for the biggest part of the entries, and opens a
> can of worms for the rest, so I have not implemented such a system yet.

Version specific notes are desireable, but not a must. Such a feature 
can wait until the documentation is almost complete. In the meantime it 
may be more interesting to have changed features mentioned in the 
(unique) documentation, e.g. when upgrading projects.


>> - How to document IDE units? Error: not in a package...
> 
> I added the fpdoc search path docs/xml/ide to the lazarus.lpi, so that
> IDE sources can now be documented via fpdoc as well.
> I also added it to the IDE itself, so that you don't need to open the
> lazarus.lpi to document the IDE sources.

Okay, I'll test that new feature.


>> Most annoying is the inability to share updated help, in multiple 
>> Lazarus branches. This could be made possible by having FPDoc files on a 
>> machine only once, independently from working copies. Effectively the 
>> docs should reside in their own SVN repository, not in every Lazarus SVN 
>> branch.
> 
> No, this would not work with renamed/moved entries.

The current model doesn't work with such entries as well.


>> Currently the help system requires that all documented units belong to a 
>> package or project.
> 
> Technically a fpdoc file is associated with a unit.
> The fpdoc search path is stored in the package/project.
> Practically you want to create one help file per package, for example
> for the LCL.

You refer to the final (compiled) help?

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 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.


>> 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.


>> 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.

> 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.

DoDi