Re: Documentation

[John R Sheets <dusk smsi-roman com>]

Thanks, Miguel.  I noticed Federico's article, gnome-doc-framework.txt in there
too.  Federico's vision matches pretty closely with what I was thinking, regarding
a GNOME Book-Set, package Books (e.g. gnome-libs, ORBit, etc.), and a Chapter for
each .c file (more or less).  Should the functions be divided up into Sections
inside the Chapter?

Granted, I just started studying DocBook.  I'd be happy to start hacking on the
templates, though, for starters.  I imagine they'll be pretty neanderthal until I
get better footing in DocBook.  Eh, shouldn't take too long, if I make the effort.

Miguel de Icaza wrote:

> ------------------ api-commenting-style.txt --------------------
>
> I suggest we use the following to documenting API entry points in the
> GNOME libraries.  I have written a simple Perl script that can extract
> these comments into a file.  I will need to make my Perl script
> generate DocBook output.

Looks good.  (I'd be interested in seeing that Perl script, BTW.)

What's the plan, then?  Should I start submitting document patches for each file
in e.g. gnome-libs?  Is the Master Plan that the Perl script would automatically
generate the (entire?) documentation structure in Federico's proposal?  Or would
Federico's doc framework be a separately-maintained, hand-written manual.  Or both
in parallel/combination?  We should probably standardize on our approach so
developers will know whether to put their docs in comment blocks, or directly into
DocBook format.

John