Re: Documentation

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

Federico Mena Quintero wrote:

> 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 think the man pages would work best with the autogenerated docu-comments.  Man pages
are good for the dry, encyclopedic listings of API's, and wouldn't really need broader,
sweeping conceptualizations like a tutorial would need.  So I say generate the man pages
strictly from docu-comments content.  Whether DocBook even needs to be in the man page
creation process remains to be seen.

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

That would be Mark, wouldn't it?The more I think about it, the more I think we should
keep the auto-generated docu-comments separate from the hand-written Usage docs
(tutorials, concepts, etc.).  It shouldn't be too hard to link 'em all together all
smooth-like...create HTML links from the Usage descriptions to the docu-commented API's.
So you're reading along in the Canvas tutorial, and you find a reference to some related
function, say gnome_set_fusion_state() in another module.  >Click< and you jump over to
the gnome_set_fusion_state API, with parameter-by-parameter descriptions and other
technical jive.  (On a printed doc, it could maybe indicate the page that the API is
on.)  Sounds reasonable.

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

Yep, downloaded the official docs last night from O'Reilly, and also read through Mark's
tutorial (not a bad little piece, BTW).  I believe my emacs already has an SGML mode --
is there more than one?  If so, how do they compare?  Does the psgml package include any
good docs on itself?

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

I agree.  The Usage part of the GNOME devel-docs should be hand-written.  We should try
to integrate the docu-comments into it as best as we can, but those should only be a raw
reference.  We don't want to clutter up the source files with pages & pages of dippy-doo
philosophy.  The docu-comments should be a line or two for each parameter, and a
paragraph or two for the description.  Concise, accurate, and very unfrilly.

I agree with Mark in that we shouldn't tie ourselves down to a file == chapter model.
Maybe for the reference section, but not for the main Usage docs.  The less arbitrary
limitations we put on ourselves, the better the documentation will be.

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

Yes, it all makes sense, but don't let that deter you from a good cup o' brew (especially
after bedtime :c).

John