[Lazarus] Help on FCL?

Hans-Peter Diettrich DrDiettrich1 at aol.com
Sat Jan 21 21:40:37 CET 2012


Mattias Gaertner schrieb:

>> 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 don't remember how to check the FPC version - can you give me a source 
snippet?


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

Why should a user care about the Lazarus package name? When Controls.pp 
is in LCLBase, should it show up only in LCLBase.chm, instead of lcl.chm 
(as is)?


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

Ausnahmen bestätigen die Regel ;-)


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

I dare to doubt that, but I'm not an CHM expert.


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

One more reason to use an single documentation package name throughout 
all LCL supplied packages.


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

Right, and that's why they have to find the xml files first. These files 
can reside in any directory, as specified in the fpdoc path of the 
related package or project.


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

Some foresight had prevented the current mess :-(

DoDi





More information about the Lazarus mailing list