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.
_______________________________________________
fpc-devel maillist - [email protected]
http://lists.freepascal.org/mailman/listinfo/fpc-devel
