[fpc-devel] fpdoc content syntax suggestion
Michael Van Canneyt
michael at freepascal.org
Fri Jul 9 09:38:19 CEST 2010
On Fri, 9 Jul 2010, Graeme Geldenhuys wrote:
> Currently fpdoc supports a hybrid HTML syntax for documentation content. I
> use fpdoc a lot, and over time and noticed a few problems:
> 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
More information about the fpc-devel