Re: Contributing to documentation, How to get started?

["Jonathon Jongsma" <jonathon jongsma gmail com>]

On 4/17/06, Tamer Mowafy <kalimakhus yahoo com> wrote:
> What the one should do to contribute to the
> documentation of Gtkmm and Glibmm libraries. I haven't
> contributed to any open-source project before so I
> don't have a good background about the right way to do
> this. I hope someone can point me to some online
> document that would help me get started.

Welcome Tamer,
Documentation contributions are always welcomed.  I'll try to keep my
comments fairly basic since I don't know your level of familiarity
with the gtkmm code base.

gtkmm has two separate pieces of documenatation: The tutorial and the
API reference.  The best way to contribute to either of these is to
checkout a cvs version of gtkmm (see
http://developer.gnome.org/tools/cvs.html for details on this).  Then
edit the files that you want to change (see below for a bit of
information on the directory structure, etc), and when you've got a
chunk of similar work which should be committed, edit the ChangeLog
file and describe what changes you made.  Then create a patch file
(e.g. cvs diff -u > my-patchfile-name.patch), file a bug in gnome's
bug tracking system (bugzilla.gnome.org) explaining your change, and
attach your patch to that bug.  Generally gtkmm / glibmm bugs get
handled fairly quickly and somebody will review your patch and either
apply it to cvs or request changes.  If you're unsure about whether to
make a change or not, or you think something requires discussion, feel
free to bring it up on this list before starting work or filing a bug.

The tutorial is probably the most straight-forward one to contribute
to, as it's essentially a book written in docbook xml format.  The
tutorial is located at /docs/tutorial/, and the main book is in the
file gtkmm-tut.xml.  Images are located in the images/ subdirectory,
and the book also includes some example code from /examples/book/*
into the text. A good reference on the docbook format can be found at
docbook.org.

The API reference is generated from comments in the source code using
doxygen, but most of the documentation is generated from the GTK+
documentation (which is why you might find some references to GTK+
functions in the documentation for gtkmm).  First a little background:
much of the gtkmm code is automatically generated from the GTK+
headers using a macro preprocessor.  The code that will get
preprocessed is located in e.g. /gtk/src (or /gdk/src, etc) with file
extensions of .ccg or .hg.  After processing, source files will be
created in /gtk/gtkmm with file extensions of .cc or .h.  Do not edit
these generated source files, since they will be overwritten the next
time the preprocessor is run.  instead, edit the .ccg or .hg files. 
(Note, however that there are some files in /gtk/gtkmm that are not
generated since they implement classes that are unique to gtkmm and
are not wrapping GTK+ types -- these files can be edited).  Most of
the documentation is not inside of the .hg files however.  As a
general rule, only the doxygen documentation for classes and class
constructors are put into the .hg files.  Most of the function
documentation is generated from the GTK+ documentation found in the
file /gtk/src/gtk_docs.xml (which is generated periodically from the
GTK+ sources, although I'm not sure exactly how that's done). 
Obviously, a lot of the GTK+ documentation makes direct reference to
GTK+ types, so much of it will need to be altered to refer to gtkmm
types instead.  This is where /gtk/src/gtk_docs_override.xml comes in.
 Any documentation located in gtk_docs_override.xml will override the
automatically generated GTK+ documentation found in gtk_docs.xml.

All of this applies to glibmm as well (except glibmm doesn't have a
tutorial, although it would be sort of nice to have one).

Hope that helps.  Feel free to ask questions if you need any more information.

Jonner