[Lazarus] FPDoc editor and document placement

[Mattias Gaertner]

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

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

For example?


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

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.

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

The current model works. It is only uncomfortable when renaming.


> >> 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 other words: If a package has help it is found, if a package has
no help, nothing is found.

 
> 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?
How should help files for third party packages be distributed?

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

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

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

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


Mattias