Re: [AD] Documentation system 2009

[Peter Wang <novalazy@xxxxxxxxxx>]

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

Yeah, there are tradeoffs.

> 
> And what format exactly do we write in? markdown? It doesn't seem particularly 
> useful for code docs..

Markdown, or rather markdown with Pandoc's extensions.
It seems to be basically the same as Natural Docs as far as I can see,
except that code blocks are easier to write in markdown.

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

You *should* be able to just write [foo], but currently it only works in
the HTML output, and if foo is defined in the same file.  I think I know
how to make it work across files, which I'll try to implement soon.

man: We just have to replace [foo] by foo(3) if we know foo is the name
of an API entry.  (Or just assume anything beginning with al_* or
ALLEGRO_* has a man page.)

Info, LaTeX: for these we'll generate the entire manual at a time so no
worries about separate files.  Unfortunately there's no general syntax
to refer to a section yet.  Changes to Pandoc are probably required.

Peter