Mattias Gaertner schrieb:
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>.
Would it help to add a dummy package (or project?) with all (relevant)
FCL units?
Then an help author can add more units to that package, when adding docs
on further FCL units?
The chmhelppkg package extends/overrides some of these settings.
Maybe the chm authors can give some clues about the chm parts.
Existing chm files seem to work off-the-shelf, I see no need for special
updates there. The critical points are how F1 finds the (CHM/HTML) file
for a unit, and how FPDoc Editor finds the XML file.
[...]
> 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.
The problems started when I wanted to add documentation for FCL units,
which are not recognized by the FPDoc Editor. Even if these docs will be
added to FPC, Lazarus must be able to find the related docs. This is not
related to Lazarus versions.
Lazarus adds further problems with the new package structure, which
become obvious only when somebody tries to build the docs for Lazarus trunk.
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.
[...]
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'.
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.
> 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.
I think that is not the right word for a forgotten entry.
Should I update the xml files or need something be updated first?
We have to find a working solution, before any attempt to make
descriptions (in)accessible in the new docs :-]
[...]
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'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.
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.
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 :-(
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.
DoDi
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
