[fpc-devel] FPDoc and Lazarus

[Hans-Peter Diettrich]

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