[Lazarus] Help on FCL?

[Mattias Gaertner]

On Thu, 19 Jan 2012 23:15:14 +0100
Hans-Peter Diettrich <DrDiettrich1 at aol.com> wrote:

> 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

It should not conflict it should extend. There is no code in the
fcl.lpk that needs fpdoc help.
I removed the test xml. The fpdoc entry for RegisterUnit was not
helpful.

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

yes

> Then the unit must be added to the package, so that the 
> document file can be created in the package doc directory.

The fcl files must not be added to the fcl.lpk, because they can be
moved/renamed by the FPC team between versions.

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

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

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


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

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

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

I think that is not the right word for a forgotten entry.

Should I update the xml files or need something be updated first?

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

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

The old laz_dom should not be used for new projects. The documentation
can be short.
The laz2_dom docs can refer to the FCL one.

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

laz2_dom is part of lazutils.
laz2_dom/read/write are of good use for developers. They are fast
UTF-8 xml units. I use them in some of my projects.
The fcl.lpk package does not need fpdoc help.

 
> > That is not optimal, but better than data corruption.
> 
> Well, currently I see help corruption all over the place :-(

As far as I remember: you always did. ;)

Mattias