Re: GNOME Documentation Framework

[Scott Wimer <scottw dev cgibuilder com>]

Hi Fredreico,

I've written a tool that may be useful once somebody has built the
various templates.  Basically, it makes it easy to glue templates and
the data for them (even if it comes from various different sources)
together into an output file.  The tool is called Document Welder.  You
can grab it from http://www.cgibuilder.com/welder/  if you want to take
a look at it.

I've also started looking at DocBook, and if I get to the point where I
think i can handle it reasonably well, I will probably create a DocBook
plugin library for Welder (since it's got a slick plugin interface).

let me know if you're interested in having me work on this.

Regards,
scottwimer   aka 'happybob'


On Thu, 15 Oct 1998, Federico Mena Quintero wrote:

> Hello,
> 
> I wrote the following text about how the GNOME documentation framework
> should be set up.  Please roam through it and feel free to ask any
> questions that you may have.  We will be doing a lot of work regarding
> documentation in the following months :-)
> 
> This is available from cvs as gnome-libs/devel-docs/gnome-doc-framework.txt.
> 
>   Federico
> 
> 
> ----------------------------------------------------------------------
> 
> 
> 		    GNOME Documentation Framework
> 
> 			     October 1998
> 
> 	       Federico Mena <federico@nuclecu.unam.mx>
> 
> 
> * Abstract
> 
> This document presents a framework for organizing and writing
> documentation for the GNOME project.  GNOME needs a good documentation
> system that makes it easy for people to integrate their own
> documentation into the global framework.
> 
> 
> * Documentation back-end
> 
> DocBook (http://www.ora.com/davenport) is the documentation back-end
> we have chosen for GNOME.  It is an industry standard, it provides
> markup defined by logical content, and it allows for hyperlinks and
> convenient navigation.
> 
> 
> * Organization
> 
> This section explains the organization of the documentation files in
> the file system.
> 
> Each package that provides development libraries needs to have a
> directory with documentation for users and developers.  For the sake
> of this discussion, we will use the gnome-libs package as an example,
> and only consider development documentation for it.
> 
> The source code to Gnome-libs is organized as follows:
> 
> 	gnome-libs
> 		libgnome
> 		libgnomeui
> 		libgnorba
> 		libvfs
> 		gtk-xmhtml
> 		zvt
> 
> Hopefully, developers have chosen a good organization of the code
> inside those directories.  If we take this assumption to be true, then
> it makes sense to organize documentation in the same way:
> 
> 	gnome-libs
> 		devel-docs
> 			libgnome
> 			libgnomeui
> 			libgnorba
> 			libvfs
> 			gtk-xhmtl
> 			zvt
> 
> Inside each of those directories there would be one sgml file for each
> module in the libraries:
> 
> 	gnome-libs
> 		devel-docs
> 			libgnome
> 				gnome-config.sgml
> 				gnome-dentry.sgml
> 				gnome-metadata.sgml
> 				...
> 			libgnomeui
> 				gnome-app-helper.sgml
> 				gnome-canvas.sgml
> 				gnome-mdi.sgml
> 				...
> 			...
> 
> Modules are usually (hopefully!) small enough that they can be
> conveniently described in a single sgml file.  Each of these would be
> a separate chapter.
> 
> Some chapters may want to include images or pictures, or other bizarre
> entities.  I am not sure where to put them -- the easiest way is to
> just put them at the same level as the sgml files themselves, but it
> could potentially get messy if there are a lot of images.  Another
> option is to have a "pictures" subdirectory.  I imagine this is
> specific to each book or part, and can be resolved on the fly.
> 
> Going upwards one level, the libgnome/libgnomeui/libgnorba/etc. groups
> would form a part in a book for gnome-libs.  As other GNOME modules
> with libraries are added, they would become separate books.
> Eventually they would all be tied together by a very big toplevel
> book-set.  This maps well to DocBook:
> 
> 	GNOME Book Set:
> 		gnome-libs book
> 			libgnome part
> 				gnome-config chapter
> 				gnome-dentry chapter
> 				...
> 			libgnomeui part
> 				gnome-app-helper chapter
> 				gnome-canvas chapter
> 				...
> 			...
> 
> 		gnome-core book
> 			user-docs part
> 				panel chapter
> 				help-browser chapter
> 				control-center chapter
> 			devel-docs part
> 				libapplet chapter
> 				libcapplet chapter
> 				
> 		gnome-print book
> 			font management chapter
> 			graphics primitives chapter
> 			...
> 
> 		ORBit book
> 			???
> 		
> 		...
> 
> You get the idea.  I need a DocBook wizard to see if this makes the
> most sense in the DocBook philosophy of life.
> 
> 
> * Meta-documentation
> 
> DocBook is a complex beast, and the online documentation for it is not
> very clear.  We need to provide template files that documentation
> writers can simply cut&paste and modify for their specific docs.  We
> also need a short document that explains how to write documentation
> for GNOME.  I propose something similar to the following:
> 
> 	gnome-libs
> 		devel-docs
> 			meta-docs
> 				writing-gnome-documentation.sgml
> 
> 				chapter-template.sgml
> 				function-description-template.sgml
> 				struct-definition-template.sgml
> 				enum-definition-template.sgml
> 				...
> 
> The "writing GNOME documentation" document would explain the GNOME
> documentation framework, and how people can integrate their own docs
> into it.  The other files are little templates of DocBook markup that
> users can cut&paste, so that they do not have to go and consult a
> DocBook manual every time they want to describe something.
> 
> 
> * Web availability
> 
> Ideally, all the documentation tree should be available for browsing
> in HTML on the GNOME web page.  This makes it easy for people to
> quickly look up something while they are writing programs.  Java has
> this (and it is awesome), KDE has this, and it works very well.
> 
> Since all the sgml files live on cvs, we could set up a cron job that
> every day at midnight converts the whole documentation tree into HTML
> and assembles it nicely for the GNOME web page.
> 
> When users install a GNOME component in their system, this could
> happen as well (either by conversion at installation time, but this
> means users would need to have the DocBook toolset installed; or by
> shipping pre-HTMLized files).  Users could have /usr/doc/GNOME/... be
> populated automatically when they install a GNOME component.
> 
> 
> * Documentation browser
> 
> To be defined later.
> 
> 
> * Nice hacks
> 
> An minor mode for Emacs that lets you press a hot key when the cursor
> is over a GNOME function, it would launch the GNOME documentation
> browser and take you to the description of that function.
> 
> A minor mode for Emacs, built on top of psgml-mode, that lets you
> insert and fill the templates described above automatically.
> 
> 
> -- 
>          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/