[fpc-devel] fpdoc content syntax suggestion

[Michael Van Canneyt]

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.