Re: Documentation

[Federico Mena Quintero <federico nuclecu unam mx>]

>  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?

At some point I would like to be able to generate man pages from the
DocBook documentation -- these would be man pages only for the API functions.

I need a DocBook wizard to tell me what is the best way to accomplish
this.  As far as I can tell from the documentation on DocBook, your
chapters can be made up of either sections or reference entries.
I think it is reference entries that you turn into man pages, so I
don't know how to solve this problem; ideally I would like a chapter
to be organized as

	chapter - The GnomeCanvas widget
		section - Introduction
		section - Coordinates
		section - Using canvas items
		...
		<something> - Reference section with man-like entries
		for all the GnomeCanvas API functions.

But it seems that DocBook will not let you mix refentries and sections
in the same chapter.

I guess I wouldn't mind having this:

	chapter - The GnomeCanvas widget
		section - Introduction
		section - Coordinates
		...

	chapter - Reference for the GnomeCanvas API
		refentry - foo
		refentry - bar
		...

What is the DocBook-kosher thing to do in a case like this?

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

My limited advice on learning DocBook is to get psgml-mode for Emacs
and the user documentation for DocBook.  The user docs are rather
brutal the first time you read them, but by trying out psgml-mode
you can more or less get the hang of which elements are allowed in
which places in the document.

I wish there were a friendlier introduction to DocBook :-/  Hopefully
the Gnome meta-docs will make this less painful for people.  I'll try
my hand at writing some "how-to-write-Gnome-docs" document this weekend.

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

The tutorial or explanation-like part of the documentation should be
written by hand, I think.  There is no point in trying to shove that
in the .c files.  However, I would really like the function API
reference parts to be automatically generated.

Does this all make sense, or do I need to make myself some coffee?

  Federico