Re: [AD] Documentation system 2009

[Thomas Fjellstrom <tfjellstrom@xxxxxxxxxx>]

On January 9, 2009, Peter Wang wrote:
> 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
>

So are we supposed to edit the docs in the new separate files now? I kind of 
like being able to edit one file for the docs and source...

-- 
Thomas Fjellstrom
tfjellstrom@xxxxxxxxxx