[fpc-devel] fpdoc description file syntax

[Graeme Geldenhuys]

Hi,

I've been looking and working with the fpdoc descriptions files again
for the fpGUI project. I find that to write documentation you need to
know HTML (or at least a subset of HTML). This makes it harder for
somebody not knowing HTML to write documentation.  Yes the amount of
tags are not much.

I've been looking at the Wiki sites and their syntax. They had to
solve the same problem. Allowing general non-HTML programmers to write
articles.  Why couldn't we do the same for fpdoc.

For example. Here is a markup language as used by IkiWiki
[http://ikiwiki.info]. The goal of MarkDown syntax is to be just as
readable in the markup as the final output.

For example:  The article....
   http://daringfireball.net/projects/markdown/

... and is markup for that article...
  http://daringfireball.net/projects/markdown/index.text


I think that's pretty neat! A simple markup that is very easy to read
even if it's not the final rendered product.  I believe this should
also help the fpdoc backends (HTML, Text, Latex, RTF ...).  Having a
neutral markup language that can be converted to any supported backend
and is even very close to the plain Text output format (which would
hardly need any work).


The major issue I have with the current fpdoc description markup is
what is involved in written complex documentation. Including
paragraphs with unordered list and maybe a table. As it stands now,
that is a fairly complex task to combine all the above items in the
simplified HTML markup used by fpdoc.  Even I get the syntax wrong
most of the times. Having to remember the closing </p> tags or the
</li> tags with embedded <p> tags if the item contains paragraphs
etc...

Anyway, this is just some of my thoughts on how we could improve and
simplify fpdoc's description syntax.... Any other thoughts on the
subject?


Regards,
  - Graeme -


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