[fpc-devel] fpdoc content syntax suggestion

[Graeme Geldenhuys]

Hi,

Currently fpdoc supports a hybrid HTML syntax for documentation content. I
use fpdoc a lot, and over time and noticed a few problems:

* Document writers think it's full HTML, so they add other HTML tags inside
  the content, because they are used to using fpdoc to generate HTML
  output. HTML is definitely not the only output format used with fpdoc.
  We have PDF, PS, IPF, XML, TXT, MAN etc.. Those embedded HTML tags now
  causes problems in the non-HTML output generated.
* HTML or the hybrid-HTML used by fpdoc uses the same tag brackets as XML,
  so you can't easily insert a < or > or a & character inside your
  documentation content.
* The hybrid-HTML tags are very verbose
* Nested content inside lists are difficult to get right, sometimes
  impossible (I had this issue before, but can't remember the exact
  example. I'll have to give it some thought again).


Here is a simple example.

--------------------
< p >Paragraph one.< /p >
< p >< b >Note< /b >< br >
Paragraph two goes here.
< /p >
< p >Paragraph three goes here.< /p >
--------------------

Just look at the amount of tags for something so simple. We don't write
emails like that, or any other text for that matter, so why must we burden
the documentation writers to do so.

Why couldn't the above be something like this... a simplified "light" markup.
--------------------
Paragraph one.

[b]Note[/b]
Paragraph two goes here.

Paragraph three goes here.
--------------------

* Tags use the square brackets, so as not to interfere with XML tags.
* Hard line endings, are considered the beginning of a paragraph.


Or use something as simple and popular as Creole or WikiText.
--------------------
Paragraph one.

*Note*\\
Paragraph two goes here.

Paragraph three goes here.
--------------------

* A blank line denotes a end of paragraph.
* The \\ denotes a forced line break.
* The * before and after a word denotes bold text.


Everybody seems to know AsciiDoc, WikiText, Creole syntax. They are all
very simple, very near plain text, not very verbose and easy to parse. They
don't interfere with XML tags, and doesn't make the documentation writer
think he/she may use full HTML tags in the documentation content (the
syntax is clearly different).

I have already written a simple Object Pascal based Wiki that parses the
syntax of the square bracket example, and started a parser for the Creole
syntax.

Even so, I lately think using AsciiDoc style syntax is still the best
option for documentation. It is pretty much the same syntax as you would
use to write a README.txt document or a text email. The learning curve is
near a flat line - everybody can do it without even thinking about it. Just
looking at this email alone, it is pretty much how you would write a
AsciiDoc document. :)

So would the FPC team consider such a change in fpdoc? Obviously I will do
most of the work, as I am suggesting the change. If you guys don't agree,
I'll probably still do the work by forking fpdoc (which I don't really want
to do), to fulfill my own needs and some of the open source projects I work
with (fpGUI and tiOPF use fpdoc a lot). Mixing HTML tags inside XML or the
documentation content is just not the right way to go. fpdoc is great, I
simply want to make it even better.

References
==========
AsciiDoc:   http://www.methods.co.nz/asciidoc/
Creole:     http://www.wikicreole.org/wiki/Creole1.0
My OP wiki: http://opensoft.homeip.net/wiki/wiki.cgi?p=Main-Page


Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://opensoft.homeip.net/fpgui/