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/ _______________________________________________ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel