[fpc-devel] fpdoc content syntax suggestion

[Graeme Geldenhuys]

Op 2010-07-09 09:38, Michael Van Canneyt het geskryf:
> 
> Do you want to drop the XML entirely, or just replace the content
> of the <short> and <descr> nodes with asciidoc ?

Sorry, I see I wasn't clear in my original post. The XML file can stay,
it's just the syntax used for the documentation content in the <short> and
<descr> that should change. It's the help content syntax I have a issue
with, not the usage of the XML file itself.


> a) The asciidoc parsing (or whatever you call it) engine *must* be in the FCL

Not a problem.


>     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.

You should know me by now. Test suites are a given. I didn't know you can
program in any other way than TDD (Test Driven Development). ;-)


> b) It must exist alongside the current format (obviously), and the two must

This shouldn't be hard at all. As you suggested, a parameter telling fpdoc
what syntax is used in the description is a good solution.


> c) all current 'extra' constructs must somehow be supported.
>     (printshort, img, link etc.)

whatever "light" markup syntax we use, if that syntax doesn't support
something like <printshort>, then we simply make our own syntax symbol for
it. All the syntax I mentioned support img and link symbols already.


> d) Documentation of the format in fpdoc.tex (in LaTeX)

Again, not a problem.


> And of course I do not intend converting the current documentation to
> asciidoc :-)

I wasn't suggesting that, but I do intend to write a converter from the old
format to new format. You can decide if you want to switch or not.
Obviously, I'll do lots of testing on this with the existing fpGUI and
tiOPF documentation, as I'd much prefer a light markup syntax for those
projects.


Regards,
  - Graeme -

-- 
fpGUI Toolkit - a cross-platform GUI toolkit using Free Pascal
http://opensoft.homeip.net/fpgui/