On Fri, 9 Jul 2010, Graeme Geldenhuys wrote:
Hi, Currently fpdoc supports a hybrid HTML syntax for documentation content. I use fpdoc a lot, and over time and noticed a few problems:
[snip]
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.
I think this is largely a matter of opinion, but I will not go into that. One thing which is not clear from your explanation: Do you want to drop the XML entirely, or just replace the content of the <short> and <descr> nodes with asciidoc ?
fpdoc is great, I simply want to make it even better.
I am absolutely not against introducing this, I even welcome any attempt to make fpdoc better. But there are some "rules" to adhere to. a) The asciidoc parsing (or whatever you call it) engine *must* be in the FCL as a separate package (I need to be able to maintain it in case you don't). Preferably with testsuite, although I don't insist on that. b) It must exist alongside the current format (obviously), and the two must be mixable on a per-file basis. (that is, one format per file, but 2 files may have a different format) c) all current 'extra' constructs must somehow be supported. (printshort, img, link etc.) d) Documentation of the format in fpdoc.tex (in LaTeX) I think most of these rules speak for themselves :) I suggest --ascii-descr=filename as a commandline option, so the fpdoc engine can link together the plain xml and asciidoc engines. And of course I do not intend converting the current documentation to asciidoc :-) Michael. _______________________________________________ fpc-devel maillist - fpc-devel@lists.freepascal.org http://lists.freepascal.org/mailman/listinfo/fpc-devel