Re: [AD] Documentation system 2009

[Peter Wang <novalazy@xxxxxxxxxx>]

On 2009-01-10, Peter Wang <novalazy@xxxxxxxxxx> wrote:
> 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.

I think this alternative is easier to work with than separate files.
The above description implies separate tags "Function:", "Type:",
"Enum:" as in Natural Docs, but since it only served to complicate the
scripts, I've unified them under "API:".

Patch attached.  The scripts are written in shell (they'd be trivial to
rewrite, even in C).  Natural Docs have been extracted but not reformatted.
The CMake build will generate HTML, man and info documents (if enabled).

I'll get some more opinions before committing.

Peter

Attachment: docsys.diff.gz
Description: application/gunzip