Sign in Join

Live chat for Free Pascal, Lazarus, Delphi and every Pascal programmer.

Mailing lists / fpc-pascal / 2012-02

Adding Notes in FPDoc

4 messages · 3 people · –

Reply by email Subscribe to this list Your subscription

Read-only archive. Use j and k to move between messages.

Michael Van Canneyt

Hi,

Seeing the discussions about annotating the documentation created by FPDoc, I added support for notes. (revision 20304)

In short:

At the level of the <module>, <topic> and <element> tags, you can now include a <notes> tag.

Within the <notes> tag, you can include one or more <note> tags.

They are typeset as an unordered list, which means that it can basically contain the same things as a <li> element. (so no tables, code blocks and what not).

By default, the <notes> tag is ignored.

Only if you give fpdoc the --emit-notes option, then the notes will be included in the output. (at least in HTML and all linear output).

The fpdoc XML project file also supports the emit-notes option.

I have documented all this it in the official fpdoc reference guide. (rev. 890)

As a side note:
The official FPC documentation will not contain notes in the output. I consider them for private use only, so it is useless to submit notes. But I can understand other people want such a feature, therefor I added it to fpdoc.

Michael.

Reinier Olislagers
Michael Van Canneyt wrote 28 lines
On Sat, 11 Feb 2012, Howard Page-Clark wrote: > The prospect of a website dedicated to discussion of documentation > seems to me to be a helpful move forward. It's not really about discussion (fed up with that, if you can believe it ;) ), but about showing and collaborative editing of the docs. The idea was/is the following: * All nodes of an FPDoc description file can be put in a database; One record per element/module/whatnot, fields for short/descr/seealso and whatnot elements. I have the structure floating around here somewhere. * FPDoc needs (or already has, don't remember?) a mode to generate a single HTML page, based on node name. * The website can use the fpdoc engine to fetch and display the HTML 'on-demand'. * For people with enough rights, the content can be edited. * When creating the full docs, the XML is read from the database and written to an FPDoc file. In fact, not so different from a WIKI, but more structured. And now: Since we now have notes, these can be displayed, and edited by all.

I'd say go for it, Michael.

If discussion can't be done in those notes, they can be done in some pages of the regular wiki with hyperlinks to the help HTML pages... Actually.... that is possible right now, I suppose ;)

Regards,
Reinier

Graeme Geldenhuys
to Michael Van Canneyt: Seeing the discussions about annotating the documentation created by FPDoc, I added…
Michael Van Canneyt wrote
Seeing the discussions about annotating the documentation created by FPDoc, I added support for notes. (revision 20304)

Thank you Michael, this should definitely come in handy for some people.

I also investigated this functionality further with INF and DocView. The INF specification has support for a "hide" function. These HIDE tags takes into account an environment variable in the OS, which tells the INF viewer if that content should be displayed or not. INF takes it one step further and even allows you to specify various "access levels" separated by a + sign (eg: set IPF_KEYS=LEVEL1+LEVEL2) to have even more fine-grained control over which notes are displayed or not.

So based on this, fpdoc notes could be displayed or hidden using a single INF file - simply by toggling the value of the IPF_KEYS environment variable.

I'll pull the latest fpdoc code and experiment with this functionality a bit more.

Regards,   - Graeme - _______________________________________________ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net
Graeme Geldenhuys
Michael Schnell wrote
just "Notes" that can be hidden. But I would vote for letting the user decide at any point in time to switch the verbosity level in the help viewer itself rather than use a static environment variable.

That's already on my DocView todo list. :-)

Regards,   - Graeme - _______________________________________________ fpGUI - a cross-platform Free Pascal GUI toolkit http://fpgui.sourceforge.net