[AD] Documentation system 2009

[Peter Wang <novalazy@xxxxxxxxxx>]

The new web site system gave me an idea for another documentation system
based on Pandoc (plus a bit of Natural Docs).


Each section of the manual lives in a directory, contain the files:

    a.*
    type.*	    (e.g. type.ALLEGRO_DISPLAY)
    enum.*
    func.*	    (e.g. func.al_create_display)
    z.*

The files are concatenated together and passed to Pandoc as input, in
that order.  The a and z files are passed verbatim.  {type,enum,func}.*
files contain the bodies of API entries.

We don't get fine control over the order that API entries appear in the
generated manual, but I think alphabetical order is fine.  But see below
for an alternative.

Triple maintenance of function prototypes (and type declarations) in
headers, source and documentation would be irritating.  Hence we *don't*
write prototypes in {type,enum,func} files.  Instead, they are
automatically extracted from source files and inserted into the input.

Prototypes could be extracted in many ways (if you have a C parser), but
one very simple way is use the Natural Docs markers that we've already
got.  If we see a "Function: foo" line then it's very easy to extract
the function prototype for `foo` that follows it.  It depends on our
formatting conventions, of course.


ALTERATIVE TO SEPARATE FILES

The separate {type,enum,func} files are easy for dumb scripts to work
with but might be annoying to edit.  I don't want to invent an new
markup layer on top of Pandoc, but I think special section names could
be acceptable, e.g.

    ## Function: al_start_thread

    When a thread is created, it is initially in a suspended state.
    Calling `al_start_thread` will start its actual execution.

The Function: tag wouldn't appear in the output, but tells us the start
of API entry so we know where to insert prototypes, and where we need to
generate man pages.


OPTIONAL FEATURE

I do like to be able to read inline descriptions of functions, as long
as they aren't too long and clutter up the entire screen.  Since we're
using Natural Docs markers anyway, I have a script that can reinsert
text from func.* (etc.) files back into source code.  Currently it just
inserts the first paragraph into place, but it could be changed.

Of course, then you could generate Natural Docs too if you like.  Pandoc
and Natural Docs use different markup so you would lose some formatting,
but it should still be readable.


What do you think?

Peter