[fpc-devel] FPDoc and Lazarus

[Michael Van Canneyt]

On Sat, 3 Sep 2011, Hans-Peter Diettrich wrote:

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

Where do you see 'empty' paragraphs ?

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

No. It means your text structure is invalid. Typical errors are

<descr>
some text
<p>
</p>
</descr>

this needs to be

<descr>
<p>some text</p>
<p>
</p>
</descr>

>
> I suspect that it is not possible to give xml source line numbers with the 
> messages?

No, because the above errors are only produced after the XML was read, when the XML is transformed to HTML.

>
> Can somebody suggest an XML validator, that would give more precise 
> information about the location of invalid tags?

That won't help you, since there is no fpdoc DTD (any more). 
There used to be one. I will see if I can find it.

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

Feel free to submit a patch.

>
> One more: --project seems not to work, fpdoc complains about invalid option 
> and missing package specification?

Probably your fpdoc is too old. You should use the one from SVN.

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

Again: Feel free to submit a patch.

Michael.