[Lazarus] Help on FCL?

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

> The IDE registers fpdoc help for some FPC directories (rtl,
> fcl-base/src;fcl-db/src;fcl-extra/src;fcl-process/src;fcl-web/src;paszlib/src)
> and simply opens the URL
> http://lazarus-ccr.sourceforge.net/docs/<fpdoc
> path>.

Would it help to add a dummy package (or project?) with all (relevant) 
FCL units?
Then an help author can add more units to that package, when adding docs 
on further FCL units?

> The chmhelppkg package extends/overrides some of these settings.
> Maybe the chm authors can give some clues about the chm parts.

Existing chm files seem to work off-the-shelf, I see no need for special 
updates there. The critical points are how F1 finds the (CHM/HTML) file 
for a unit, and how FPDoc Editor finds the XML file.


>> [...]
>>>  > Please explain how the LCL documentation is organized. The Lazarus
>>>  > 0.9.30 LCL was one synthetic package, covered by a corresponding lcl.chm
>>>  > file. But now (trunk) the package LCL contains the widgetsets, while the
>>>  > common code resides in packages LCLBase and LazUtils. I would like to
>>>  > have a single document (chm) for these 3 packages as well.
>>>
>>> Why?
>> Why what? In the last release a single CHM contains the LCL 
>> documentation. Breaking it up into multiple packages requires to provide 
>> different help files for every Lazarus version :-(
> 
> Well, the binaries do that anyway. But I see your point that you want to
> use thew newest docs for an older version too.

The problems started when I wanted to add documentation for FCL units, 
which are not recognized by the FPDoc Editor. Even if these docs will be 
added to FPC, Lazarus must be able to find the related docs. This is not 
related to Lazarus versions.

Lazarus adds further problems with the new package structure, which 
become obvious only when somebody tries to build the docs for Lazarus trunk.

> This is a general problem for any long living package. Maybe we can add
> now some features that make it possible that the current version
> can use the next version. Ideas?

As already suggested: add synthetic packages or projects, to which the 
contained units can be added freely. Then make the help system use these 
projects to find the applicable doc and XML file for these units.

Or make the help system use FPDoc project files, instead of Lazarus 
package files, which contain lists of all contained (documented) units 
(<inputs>) and related docs (<descriptions>). The <descriptions> deserve 
no special handling, as long as every $unit.pas is documented in 
$unit.xml, and the xml files reside in the same directory - as is.

The project files have been introduced in fpdoc 2.7, to simplify 
building the docs. Using them will also eliminate the need for 
build_lcl_docs or similar scripts, when only the equivalent fpdoc 
project is supplied. The FPDocManager (in examples) can create fpdoc 
projects from/for existing Lazarus packages or projects.


>> [...]
>>> The fpdoc editor has to find the xml file for a package, not the other 
>>> way round. So for the fpdoc editor it does not matter what module is in 
>>> the xml file. 
>>>
>>> But for fpdoc the module should be the Lazarus package name. The xml 
>>> files needs to be updated.
>> IMO we should virtualize the direct relationship between Lazarus and 
>> documentation packages. When every Lazarus package is assigned an FPDoc 
>> package name, too, the LCL documentation could e.g. span the packages 
>> LazUtils, LCLBase, LCL and (Lazarus) FCL, not hiding the FPC FCL any more.
> 
> I think it would be confusing if the fpdoc page says package 'LCL', but
> the unit is in the package 'LazUtils'.

Slowly you seem to get it ;-)

It *is* already confusing, when the fpdoc page says package 'LCL', but 
the unit is in the package 'LCLBase' :-(

A user will *not* be confused much, when all Lazarus supplied units are 
documented in 'LCL' (e.g. lcl.chm), regardless of Lazarus-added 
arbitrary subdivisions. He also will not be confused when FPDoc Editor 
simply can put a description into wherever it is expected by the help 
system.


>>>  > Should the LazUtils units documentation use the same hack?
>>>
>>> What hack?
>> A documentation package name *different* from the Lazarus package name.
> 
> Hack (computer science): "an inelegant but effective solution to a computing problem"

You forgot to add: a *fragile* solution, which may be broken by changes 
somewhere else in the code or compiler.

> I think that is not the right word for a forgotten entry.
> 
> Should I update the xml files or need something be updated first?

We have to find a working solution, before any attempt to make 
descriptions (in)accessible in the new docs :-]



>> [...]
>>> The chm help 
>>> format has the ability to combine multiple fpdoc files into one.
>> But only when these files are part of the same documentation package.
> 
> Is this a limitation of the fpdoc chm writer?

It's a limitation of fpdoc in general. It can generate documentation 
only for single *packages* (--package=xyz). This does not matter much 
when building HTML help, residing in a bunch of related HTML files, but 
it matters with every linear (monolithic) document, be CHM, PDF etc.

That's why I suggest a single (fpdoc) package 'LCL', instead of 
cluttering the docs and indices(!) into LCL, LCLBase, LazUtils etc. IMO 
a user will be confused when he *thinks* that he is using the LCL, but 
has to search for help on it in LCLBase.chm, where up to the last 
release *everything* LCL-related was documented in LCL.chm.


>>> It is 
>>> useful to combine all xml files of a package into one chm. But of course 
>>> it is also possible to combine multiple packages into a single chm file.
>> How that???
> 
> If you really want a single chm file then you can for example use a
> simple search and replace to change all package names and links and
> feed the new xml files into the chm creator.

Please check such a "solution" yourself, and find out how it breaks 
FPDoc Editor and Hints :-(

All I wanted to point out are *Lazarus generated* problems, not problems 
of fpdoc.


> The fcl.lpk package does not need fpdoc help.

That's why I wonder why it is *named* 'fcl', when this name already is 
in use for the FPC FCL. Rename it into LazFCL, and everything is fine again.

DoDi