Currently I'm working on the LCL documentation, on Win7, using
Lazarus\docs\html\build_lcl_docs.lpr on Win7. Here I ran into some problems:
There's something wrong with table row spacing, in all fpdoc generated
HTML files. All fpdoc generated tables (lists of types, classes...) have
excess whitspace between the rows (about 2 lines each), which makes the
tables hard to read (using Firefox). A look at the source code reveals e.g.:
<h2>Declaration</h2>
<p>Source position: controls.pp line 148</p>
<table cellpadding="0" cellspacing="0">
<tr>
<td><p><tt><span class="code"><span class="kw">type </span>TAlign<span
class="sym"> = </span><span class="sym">(</span></span></tt></p></td>
</tr>
<tr>
<td valign="top"><p><tt><span class="code"> alNone<span
class="sym">,</span></span></tt></p></td>
<td><p> </p></td>
<td><p class="cmt">Control has fixed size and position</p></td>
</tr>
...
Why the many (empty) paragraphs inside the rows?
Following an hint, I also found
<link rel="stylesheet" href="../fpdoc.css" type="text/css">
but no such css in the referenced location. Lazarus supplies an
docs/html/fpdoc.css, but this one resides in the wrong directory, and
also doesn't reduce the whitespace. Graeme pointed me to
http://opensoft.homeip.net:8080/tiopf/core/fpdoc.css
and this css in the right place seems to remove all the excess
whitespace from the tables. Actually I'm not sure what really helps to
remove the whitespace, it seems to reappear every now and then :-(
About the location of the css file:
In a directory structure .../docs/html/<package>/<module>/doc.html a
single css file in docs/html/fpdoc.css would be sufficient, to make all
pages look the same. Is it really required to have css files in every
package directory?
Next problem are the error messages, when running build_lcl_docs.exe, in
detail:
[#lcl.Grids.HowToUseGrids] Invalid table content
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element:
"#text")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "link")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "b")
[#lcl.Grids.HowToUseGrids] Invalid description (illegal XML element: "var")
...
These messages are quite vague, since this topic contains several
tables, and I also could not find out the reason for above messages. The
output looks as expected, and there exists no "#text" in the topic
source. Are topics treated differently from other element descriptions,
making <link>, <b> or <var> invalid?
I suspect that it is not possible to give xml source line numbers with
the messages?
Can somebody suggest an XML validator, that would give more precise
information about the location of invalid tags?
I also came across <br/>, which seems to be allowed in the fpdoc
sources, but is missing from the documentation. It is converted into
<br> in the HTML output, what looks correct to me.
As a last note, on the --descr option: wouldn't it be sufficient to
specify a directory here, in which fpdoc can find all the xml files for
a package? Such an option would e.g. allow to create the docs for
multiple languages from the same command line (or script, Makefile...),
by only varying the xml directory.
One more: --project seems not to work, fpdoc complains about invalid
option and missing package specification?
As already mentioned, an option would be nice that makes fpdoc create an
project file from the command line, instead of or in addition to
creating the docs.
DoDi
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
