[Lazarus] Help on FCL?

[Hans-Peter Diettrich]

Mattias Gaertner schrieb:

> The fcl.lpk is only a representative package, e.g. registering FCL 
> components and containing the IDE registration code. It is not meant to 
> handle the whole FCL.

Then it should be possible to rename the package, so that it does not 
conflict with the FPC FCL. E.g. LazFCL

> Technically the fcl.lpk only contains the units in the 
> packager/registration folder. 
> 
> Maybe the fpdoc editor can be extended to ask the user where to put the 
> xml file.

A package name is required as well, so that a package name has to be 
requested. Then the unit must be added to the package, so that the 
document file can be created in the package doc directory.


>  > >> Can somebody explain how the RTL and FCL docs are found at all, 
> when RTL
>  > >> the RTL is not (and FCL a different) Lazarus package?
>  > >
>  > > Every designtime package can register help for source directories.
>  >
>  > The RTL at least is not a registered Lazarus designtime package, and the
>  > FCL package obviously doesn't cover the full FCL :-(
> 
>  
> 
> Yes.

But you can't tell why it is as it is, and how documentation is supposed 
to work?


>  > >> As already mentioned, we should rethink the packaging for Help. 
> IMO the
>  > >> LCL docs should include LazUtils
>  > >
>  > > Means?
>  >
>  > 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 :-(


>  > I wonder how FPDoc Editor finds the documentation on e.g. unit
>  > barchart.pp, which is part of the LCLBase package, but barchart.xml
>  > mentions this module as part of the lcl package?
> 
>  
> 
> 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.


>  > Should the LazUtils units documentation use the same hack?
> 
>  
> 
> What hack?

A documentation package name *different* from the Lazarus package name.


>  > >> , and the RTL and FCL docs must be made
>  > >> available, somehow. My previous attempt to add RTL and FCL 
> directories
>  > >> to the Lazarus/docs/xml was dropped, because it cannot be synced with
>  > >> reasonable efforts with the FPC docs. But now we have accessible FCL
>  > >> documentation any more, what certainly is intolerable.
>  > >
>  > > What is the problem?
>  >
>  > Lazarus seems to create its own package structure, different from the
>  > FPC structure. This becomes obvious with the LazUtils package,
>  > containing modified copies(?) of the corresponding FCL units.
> 
>  
> 
> For example?

Please find your question answered in my preceding message.


>  > The documentation again introduces a different package structure, 
> with the
>  > units of the LCLBase package merged into the lcl package.
> 
>  
> 
> The code is logically divided into separate package. Therefore I think 
> the fpdoc xml files should be in separate directories too.

This may be a reasonable decision for third party or other optional 
packages, but not for the RTL, FCL and LCL.

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

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

> I leave this decision to the chm packagers.

What makes you think that it's easier to modify fpdoc, instead of 
adopting Lazarus help to the established fpdoc conventions and 
implementation?

IMO you should understand how fpdoc works, before you try to convince 
the developers to modify the current model.


>  > When I'm working with FPDoc code (FPC/utils/fpdoc), the units refer to
>  > the FCL XML modules (e.g. FPC/packages/fcl-xml/src/dom.pp), while
>  > LazUtils contains an different set of units, e.g. lazutils/laz_dom.pas,
>  > which redefine the FCL classes and identifiers. This means duplicate
>  > documentation efforts, for the FCL and LazUtils units. That's a
>  > maintenance nightmare :-(
> 
>  
> 
> The laz_dom unit is pretty old and the dom unit has gained many updates 
> and changes. So it makes sense to have different docs.
> 
> The laz2_dom is the UTF-8 port of the dom unit with a few additions.

So we have to document a total of 3 DOM packages???

> Because the IDE uses it for its config files it is important that these 
> units do not change like the FCL units. Therefore they are in the 
> Lazarus sources.

Then these legacy units are of no use for developers, and the entire 
LazFCL package can stay undocumented?

> That is not optimal, but better than data corruption.

Well, currently I see help corruption all over the place :-(

DoDi