[Lazarus] FPDoc editor and document placement

[Mattias Gaertner]

On Sat, 12 Mar 2011 08:03:55 +0100
Hans-Peter Diettrich <DrDiettrich1 at aol.com> wrote:

> Preface: I know how much work a good documentation requires, and honor 
> the goodwill of all contributors :-)
> 
> 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.
This fails if your modifications and others modifications are on the
same lines. In this case svn gives you several choices. In any case
your modifications are never lost (unless you did a mistake).

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

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

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

 
> - How to update documents, when these reside in read-only (system) 
> directories?

The same as the ppu files.
Install a newer version or install lazarus in a writable directory.

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

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


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


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

See Environment options / FPDoc editor / FPDoc files path.

The fpdoc editor does not support to create new fpdoc files for such
units.


> The source filename could be 
> interpreted as <somepath>/projectdir/unit.pp, and the help be stored in 
> $(MyLazDocDir)/xml/projectdir/unit.xml.
> When the file resides in a subdirectory of the current project, that 
> part of the path can be used.

I see problems with this approach. See above.


Mattias