[Lazarus] Help on FCL?

Mattias Gaertner nc-gaertnma at netcologne.de
Sat Jan 21 19:18:58 CET 2012


On Fri, 20 Jan 2012 14:01:49 +0100
Hans-Peter Diettrich <DrDiettrich1 at aol.com> wrote:

> Mattias Gaertner schrieb:
>[...]
> > 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.

I will take a look. It needs dGlobals.
Please add an error directive when compiling with less than 2.7.1.

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

It seems I don't get it. 
I think it is confusing if the docs shows the wrong package. The unit
fileutil is in LazUtils, so the docs should show LazUtils, not LCL.

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

Hacks don't need to be fragile. I know some pretty stable hacks.

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

The scripts says something about a combined chm for rtl+fcl+lcl.
So apparently it is possible to combine multiple fpdoc packages into
one chm.

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

Ehm, the LCL is only one part of Lazarus. There are more packages
with fpdoc files in the Lazarus sources. The help will eventually
contain all of them. 
 

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

FPDoc Editor and hints do not use the chm files. They work directly on
the xml files.

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

It was named FCL, because the FCL needed a package to register its
components in the IDE.
Renaming would break many projects and packages.


Mattias




More information about the Lazarus mailing list