Re: Documentation

[Scott Wimer <scottw dev cgibuilder com>]

Fredrico,

I think that making the API function documentation get built automatically
will be ready to roll sometime this weekend. :)  As to formatting it so
DocBook can spit out man pages from it, I'm not to sure.  I'll probably 
need to start studying DocBook frantically this weekend as well.  I am
fairly confident in making a Welder plugin lib that could do it (so we
compile the documentation for the .c files to some intermediat form that
we build DocBook and or man pages from).

I've got to run to class, more as I get more of the code in the first
paragraph finished.

Regards,
scottwimer

On Fri, 16 Oct 1998, Federico Mena Quintero wrote:

> >  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
> 
> 
> -- 
>          To unsubscribe: mail gnome-list-request@gnome.org with 
>                        "unsubscribe" as the Subject.
> 
> 

--
Scott Wimer
play  --->    scottw@cgibuilder.com         http://www.cgibuilder.com/
work  --->    scottw@corp.earthlink.net     http://www.earthlink.net/