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/