[Lazarus] FPDoc editor and document placement

[Mattias Gaertner]

On Sun, 13 Mar 2011 08:59:34 +0100
Hans-Peter Diettrich <DrDiettrich1 at aol.com> wrote:

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

Why not merge the change to the other branches?

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

How should that work with the above search pattern
<helpdir/xml>/lcl/*.xml.
?


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

 
> 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.
Overriding the fpdoc search path for packages is needed.

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

ok

 
>[...]
> >> 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. 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. Although with some
guesswork it could. Maybe this will be added, when the problem arises.
So far no one needed that.


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


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

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.


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

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.

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


> >>>> 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 :-(

I too, when I hear the reasoning of such programmers, but this universe
is not that simple.

 
> 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 you create a new fpdoc file, the fpdoc editor requires a package.
When searching a fpdoc file of a unit the IDE searches in the above
path too. I know no one that uses this. You are the first wanting to
document units without a package.


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

Yes. In most cases the search path has only one directory. In fact I
don't know a case with more than one fpdoc directory.


> 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 :-(

Is this a theoretical case or do you have any real life example where
this is a problem?

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

An option to override and use some different fpdoc files would be nice.
But this is for expert users. I think the help must be done for
newbies, experts come here second.

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

It is not always 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.

Only the lpk files are loaded.


Mattias