Re: [AD] Documentation system 2009

[Thomas Fjellstrom <tfjellstrom@xxxxxxxxxx>]

On January 11, 2009, Thomas Fjellstrom wrote:
> 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...

And what format exactly do we write in? markdown? It doesn't seem particularly 
useful for code docs.. Just making a link to an api item seems a little more 
difficult than it needs to be. (naturaldocs at least had <foo> to link to other 
items).

> --
> Thomas Fjellstrom
> tfjellstrom@xxxxxxxxxx
>
> ---------------------------------------------------------------------------
>--- Check out the new SourceForge.net Marketplace.
> It is the best place to buy or sell services for
> just about anything Open Source.
> http://p.sf.net/sfu/Xq1LFB


-- 
Thomas Fjellstrom
tfjellstrom@xxxxxxxxxx