In our previous episode, Hans-Peter Diettrich said:

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:

As far as the CSS location problems go, make sure that the cssfile is passed to fpdoc using -css-file=/location/to/cssfile.css

fpdoc will then copy the cssfile into your output path automatically for the html/chm targets.

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">&nbsp;&nbsp;alNone<span class="sym">,</span></span></tt></p></td>
<td><p>&nbsp;&nbsp;</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

Where do you see 'empty' paragraphs ?

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.

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.

Why is this invalid? It looks valid to me.

In HTML, maybe. But not in fpdoc.

The DTD specifies that below a <descr> there must be only text, or a set of <p> <dl>, <ul> Never a mix of both text and <p>.

If people think that fpdoc accepts html: No, it does not.

Michael.

I think Hans-Peter ment the paragraph with the whitespace. In html you appareantly need to put something in the <p> tags for them to be used visually. 2 spaces are maybe overkill, but still.

who uses DTDs anyway anymore? xmlschema (xsd) or relaxng schema can give you even more validation with regard to contents/constraints, not just placement.

I haven't yet looked at fpdoc, but is there a templating possibility? (or is it a xslt transform on the xml?)

From what I read in this thread, it seems that css use is underused (deduced from the fact that tables and <p> are used). Your own layouting/styling could be not only the css itself, but the way your resulting html is structured. xslt could be a natural fit in this respect. In most browsers you can open the/a xml then with a stylesheet. Another way to generate with fpdoc could be using some html-snippets/html-templates if they are too overrideable.

kind regards,
Dimitri Smits

Well, I don't use a DTD; Never saw the need, but then, I know what I'm doing. However, initially there was one made by Sebastian Guenther (the original author of fpdoc), I just don't know where it is.

But I challenge you to produce an xsd that describes fpdoc correctly :-)

I haven't yet looked at fpdoc, but is there a templating possibility? (or is it a xslt transform on the xml?)

There is no xslt used.

Well, you're free to provide a XML backend. The more backends, the better.

I think that XSLT and so on are overkill, but if people think a XML backend with xslt can be better, why not...

Michael.

In our previous episode, Dimitri Smits said:

r18924 | marco | 2011-08-31 21:33:20 +0200 (Wed, 31 Aug 2011) | 2 lines Changed paths:
M /trunk/utils/fpdoc/dglobals.pp
M /trunk/utils/fpdoc/fpdoc.pp
M /trunk/utils/fpdoc/fpdocproj.pas
M /trunk/utils/fpdoc/fpdocxmlopts.pas

* --dont-trim avoids trimming while loading XMLs. Mantis #16683

In our previous episode, Michael Van Canneyt said:

The html output is not used only for the website. There is CHM, and afaik Lazarus now has "help" popups too. Increasing the subset of webtechnologies means that all other uses must implement/emulate these.

The FPC doc directories do not contain any css file. This seems to cause the random rendering of the HTML docs, using the last cached fpdoc.css or default css. Consequently a proper fpdoc.css file *must* be supplied with the docs, at least for Windows platforms.

Unfortunately the Lazarus supplied fpdoc.css doesn't help, it does *not* remove the excess whitespace in the tables.

Where is the official fpdoc.css, that should be used for all fpdoc generated HTML pages?

DoDi

After updating I cannot rebuild FPC (on Windows), due to errors in fgl.pp: Generics without specialization cannot be used as a type for a variable

I hope that this one will be fixed soon.

DoDi

> <td><p>&nbsp;&nbsp;</p></td> Where do you see 'empty' paragraphs ?

See above. Even if the &nbsp may be inteded to form a gap between the columns, I don't unterstand why these (and the other columns) are embedded in an paragraph.

Argh, such constructs are really hard to find :-(

Can <printshort> tags import such unparagraphed text?

Yes, please.

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

You are right, I used version 2.5.1.

Now I tried again, using version 2.7.1, and the unmodified sample-project.xml crashes with exception: Unable to open file "dglobals.xml" :-(

It's not really nice when fpdoc crashes with unhandled exceptions, instead of skipping missing or invalid files.

Can somebody supply a working test project?

Sorry, the fpdoc internal structure is so obscure, I have no idea where to start with modifications :-(

DoDi

In my book, empty means <p></p>.

As for why: I don't know.

Not really, the error message tells you where to look.

Can <printshort> tags import such unparagraphed text?

Yes.

The sample project is meant as a sample for studying, not for actual work.

It's not really nice when fpdoc crashes with unhandled exceptions, instead of skipping missing or invalid files.

Skipping missing or invalid files is the worst you can do. a) the output will be invalid anyway
b) you have no warning that something is wrong.
Consequently, fpdoc stops on error.

I assume you would not want the compiler to happily ignore errors in your code and then go on to produce an invalid program ?
It's exactly the same principle for fpdoc.

Michael.

> Argh, such constructs are really hard to find :-( Not really, the error message tells you where to look.

Have a look at the lcl grids "How to..." topic, and try to find out where a passage
#text var #text
might violate any fpdoc assumption.

Even if I could reduce the error messages from 14 down to 3 messages (shown above), I'm absolutely clueless with the rest :-(

It would help a lot, when also the *next* tag were shown, which requires that the preceding text must be wrapped into an paragraph.

What's a sample worth when it doesn't compile or work properly? Would you you have committed such a broken project, when supplied by some user?

> It's not really nice when fpdoc crashes with unhandled exceptions, > instead of skipping missing or invalid files. Skipping missing or invalid files is the worst you can do.

Only bad compilers stop after finding the first error.

a) the output will be invalid anyway

The output will be valid, even if incomplete.

b) you have no warning that something is wrong.

What prevents the exception handler from showing the error message?

Consequently, fpdoc stops on error.

The only consequence I can see in this behaviour is lazyness of the author, or inability to handle exceptions in a reasonable way :-(

I assume you would not want the compiler to happily ignore errors in your code and then go on to produce an invalid program ? It's exactly the same principle for fpdoc.

I assume you don't want an compiler stop with an exception, on the first encountered error.

DoDi

Michael Van Canneyt wrote

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.

On my installation of a recent Windows Lazarus snapshot, there is an fpdoc.dtd file at

C:\lazarus\fpc\2.5.1\source\packages\fcl-base\examples

Howard

For starters, you can't have a <ul> in a table cell.

Then,

<li>
<var>DrawCell</var>. The DrawCell method is virtual and may be overriden in descendent grids to do custom drawing. The information passed to

<var>DrawCell</var> helps to identify which particular cell is being painted, the physical area occupied on the screen and its visible status. S

<link id="TCustomGrid.DrawCell">DrawCell</link> reference for details. For each cell the following occurs: <ul>
<li>

is wrong. This should be

<li>
<p>
<var>DrawCell</var>. The DrawCell method is virtual and may be overriden in descendent grids to do custom drawing. The information passed to

<var>DrawCell</var> helps to identify which particular cell is being painted, the physical area occupied on the screen and its visible status. S

<link id="TCustomGrid.DrawCell">DrawCell</link> reference for details. For each cell the following occurs: </p>
<ul>
<li>

Thirdly

<li>
As the drawing process is running, the visual state of each cell is adjusted according to grid options and position within grid. The visual state <table>

Should be

<li>
<p>
As the drawing process is running, the visual state of each cell is adjusted according to grid options and position within grid. The visual state </p>
<table>

As a rule, never put mix #Text (text blocks) at the same level as structural elements like <p> <ul> <dl> <ol> or <table>.

I suggest you start submitting patches for all the issues that bother you.

The programs seem to work well enough for me and other people. As evidence, I refer to the many pages of existing documentation.

If the programs are not up to your standards: feel free to submit patches to improve them.

Michael.

That's allowed:
<tr>
<td>TitleStyle</td>
<td>
<p>Changes the 3D look of fixed cells. There are 3 settings:</p>
<ul>
<li><var>tsLazarus</var> The default look</li>
[...]

The problem here was the plain text between <td> and <ul>, which must be wrapped into an paragraph <p>...</p> (see above). The same for the DrawCell part.

Bingo! Here I was misleaded by the indentation of <table> :-(

As a rule, never put mix #Text (text blocks) at the same level as structural elements like <p> <ul> <dl> <ol> or <table>.

Right.

> It would help a lot, when also the *next* tag were shown, which > requires that the preceding text must be wrapped into an paragraph. I suggest you start submitting patches for all the issues that bother you.

For now I only have feature requests or bug reports, no solutions.

The programs seem to work well enough for me and other people. As evidence, I refer to the many pages of existing documentation.

Following your logic, a compiler is good enough when it accepts only valid code, and stops with exceptions on errors?

There seem to exist other people with different experience and expectations as well :-(

DoDi

Hello,

I think that one thing passed here unnoticed Michael, Hans-Peter is correct in pointing out that the fpdoc.css is missing and this prevents building the FCL docs and nothing is written about this in the README.

I think it should be added to the subversion, but which fpdoc.css should I add? The one which Lazarus uses? Or do you have a more special version for fpc?

I did just this:

cd fpcdocs
make rtl.chk
make fcl.chk

and I got:

FPDoc - Free Pascal Documentation Tool
Version 2.4.4 [2011/05/01]
(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther,

new alias #rtl.System.IInterface (IUnknown)
new alias #rtl.System.IInterface (IUnknown)
new alias #rtl.System.IInterface (IUnknown)
new alias #rtl.System.IInterface (IUnknown)
new alias #rtl.System.IInterface (IUnknown)
exception at 000C1293:
../packages/fcl-base/src/iostream.pp.
cp fpdoc.cst fcl/fpdoc.css
cp: fcl/fpdoc.css: No such file or directory
make: *** [fcl.chk] Error 1

I would also like to add to the README the syntax to pass a path to the CSS, but this command had no effect for me:

make fcl.chk OPT=-css-file=/Users/felipe/Programas/lazarus/docs/html/fpdoc.css

The only way that I could make it work was by creating a directory fcl and putting fpdoc.css from Lazarus inside it.

Now it works for me with these commands:

make rtl.chk
make fcl.chk
make html FPCSRCDIR=../fpctrunk/

Except for the fact that I have no latex installed, so the html generation fails.

One more question:

What is the output of make rtl.chk? I could find nothing...

I just added fpvectorial to Makefile.fpc ... I would be very happy if a gentle soul could rebuild the makefile =) I always have trouble with that...

thanks,

It is normal that this fails, since the fpdoc run gave an error and did not produce the fcl dir. What is strange is that the Makefile should not even run the command in that file.

I would also like to add to the README the syntax to pass a path to the CSS, but this command had no effect for me: make fcl.chk OPT=-css-file=/Users/felipe/Programas/lazarus/docs/html/fpdoc.css

Define CSSFILE
make fcl.chk CSSFILE=/Users/felipe/Programas/lazarus/docs/html/fpdoc.css

The rtl dir.

Michael.

On 05/09/2011, Felipe Monteiro de Carvalho >

I think that one thing passed here unnoticed Michael, Hans-Peter is correct in pointing out that the fpdoc.css is missing and this

Wasn't there a built-in template inside fpdoc, that on generating the HTML output, it generated the fpdoc.css. I vaguely remember something like this - or maybe it was simply a feature request.

should I add? The one which Lazarus uses? Or do you have a more special version for fpc?

The one Lazaru uses is broken, so don't use that one. It causes double-spacing in the HTML output. Use the one I posted a URL link to, or use the one use by the freepascal.org website.

http://www.freepascal.org/docs-html/rtl/index.html

You are confused, or didn't read the README.DOCS file very well. The first two commands don't require LaTeX, because they use fpdoc XML files and the FPC source code as the documentation source. You would probably have to pass in the FPCSRCDIR parameter too though.

The last command 'make html', generates the "full" documentation. That means RTL, FCL, Language Reference, User Guide, Programmer Guide etc... The last three are *.tex file, hence they need LaTeX or the LaTex-to-HTML tool to work.

What is the output of make rtl.chk? I could find nothing...

There should have been a 'rtl' directory created in the current directory, with the HTML class documentation for the RTL.

Felipe Monteiro de Carvalho wrote

I just added fpvectorial to Makefile.fpc ... I would be very happy if a gentle soul could rebuild the makefile =) I always have trouble with that...

I have put it under a define FPVECTORIAL.

Only completely documented units are added to the distributed docs, so if you want it added to the official distro, you'll have to complete the documentation first.

Michael.

It is already complete AFAIK. What are you missing?

Felipe Monteiro de Carvalho wrote

I just added fpvectorial to Makefile.fpc ... I would be very happy if a gentle soul could rebuild the makefile =) I always have trouble with that...

The procedure is:
1) perform "make all" in the top level FPC directory
2) use the newly generated "utils/fpcm/fpcmake" (utils\fpcm\fpcmake.exe) to perform a "fpcmake -Tall" in the directory where you want to regenerate the Makefile
3) there is no step 3

Jonas

I would have absolutely no problems with it. The error must be fixed first anyway.

I always look at the first error, fix it and recompile. I don't even look at the rest.

That doesn't mean I don't consider a compiler that would try to continue and give more info as a better compiler, but for my purposes the first one is enough.

There seem to exist other people with different experience and expectations as well :-(

No problem with that either. But they should not expect me to solve their issues for them, unless they can convince me that it's really an issue.

And so far, you have not convinced me.

Well, at least not of the fact that there are serious issues with fpdoc. The issues with the style file, I already fixed as you should well know.

Michael.

Content, of course.

It's simply an empty skeleton file. That's not enough. Every identifier must be documented.

<!-- variable Visibility: default -->
<element name="TPath.Len">
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TPath.Points">
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TPath.PointsEnd">
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

<!-- variable Visibility: default -->
<element name="TPath.CurPoint">
<short></short>
<descr>
</descr>
<seealso>
</seealso>
</element>

Michael.

Not unless they are completely documented.

Michael.

I just added fpvectorial to Makefile.fpc ... I would be very happy if a gentle soul could rebuild the makefile =) I always have trouble with that...

Also graph and systhreads should be added to the rtl docs, and sqldb to the fcl.

DoDi

It's simply an empty skeleton file. That's not enough. Every identifier must be documented.

Is rev822 good enough?

Formally, yes.

Michael.

In our previous episode, Hans-Peter Diettrich said:

Also graph and systhreads should be added to the rtl docs, and sqldb to the fcl.

systhreads?

In rev823 I modified the README to make more clear that the path to the sources is indispensable, hopefully avoiding confusion in the future.

It seams that all of the errors that I had were related to the missing sources path...

thanks,

Formally, yes.

So will you remove the define and add it to the fcl docs?

thanks,

Felipe Monteiro de Carvalho wrote

In rev823 I modified the README to make more clear that the path to the sources is indispensable, hopefully avoiding confusion in the future.

The explanation you provided was aleady there, complete with example, but further in the readme.

I adapted and simplified the text so it refers to the existing text.

Michael.

Felipe Monteiro de Carvalho wrote

On Mon, Sep 5, 2011 at 10:24 AM, wrote: > Formally, yes. So will you remove the define and add it to the fcl docs?

I will.

Michael.

Did you test your XML at all ? I had at least 3 errors in the XML structure.

I fixed the XML, and then added fpvectorial.

Michael.

Sorry: systhrds (see fpcdocs directory)

DoDi

In our previous episode, Hans-Peter Diettrich said:

Afaik systhrds no longer exist for years.