[Lazarus] Help on FCL?

[Mattias Gaertner]

Hans-Peter Diettrich <DrDiettrich1 at aol.com> hat am 19. Januar 2012 um 16:55
geschrieben:

>[...]
> >> FPDoc Editor doesn't show anything as well, even if I added the
RTL/FCL
> >> help directories to its search path.
> >
> > I enabled fpdoc for the FCL package.
>
> FPDoc Editor still seems not to recognize the FCL units correctly. When
> I want to add documentation on e.g. fcl-xml/src/dom.pp, it complains
> that this unit is not owned by any package or project. What should I do
> to add this and other FCL units to the FCL package, so that I can extend
> the FCL documentation?


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



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


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



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



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


What hack?



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



> 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. The chm help format
has the ability to combine multiple fpdoc files into one. 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. I leave this
decision to the chm packagers.



>
> 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.
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.
That is not optimal, but better than data corruption.



>
> WRT LCL documentation see above: should the LazUtils units be made part
> of the LCL documentation package, and will that really work?



Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20120119/0356061e/attachment-0003.html>