Re: gtk-doc documentation

[Damon Chaplin <damon karuna uklinux net>]

On Mon, 2005-02-07 at 16:13, Stefan Kost wrote:
> Hi all,
> 
> the original xml docs are written by Chris Lyttle and Dan Mueth. The basically
> have streted the docbook help file and written some introductions.
> The documents is under GFDL 1.1.
> I don't know what others think about this licence. Which licence would be more
> appropriate?
> Should I mail to the oringinal aithor to ask for permission to change the
> licence. If so where do we archive their answers (this list)?

Actually most of the existing text was written by me. I'll attach an
email I sent to Dan Mueth years ago. The requirements section came from
the README (also by me). The only part I didn't do was the part about
the stylesheets, which looks out-of-date anyway.

So you could start it again from scratch and we'd be the only 2 authors,
which might help if the license needs changing in future.

Damon

>From - Tue Nov  7 11:20:07 2000
X-Mozilla-Status: 0001
X-Mozilla-Status2: 00000000
Message-ID: <3A06E76F C8B2AAB1 helixcode com>
Date: Mon, 06 Nov 2000 17:16:31 +0000
From: Damon Chaplin <damon helixcode com>
X-Mailer: Mozilla 4.72 [en] (X11; U; Linux 2.2.14-5.0 i586)
X-Accept-Language: en
MIME-Version: 1.0
To: Dan Mueth <d-mueth uchicago edu>
Subject: Re: Gtk-doc doc
References: <Pine LNX 4 21 0011021411430 778-100000 enlightenment uchicago edu>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Dan Mueth wrote:
> 
> Hi Damon,
> 
> I thought I'd send you a gentle reminder about the gtk-doc doc.  Have you
> had any time to work on it?  We have two other people interested in it
> now.  I'm hoping you can work on the hard part (overall picture of how it
> works and the harder parts of setting it up with autoconf) and then they
> can work on the other stuff like DocBook, writing the actual comments,
> etc.

I did a new release of gtk-doc, since I hadn't done a release in ages.

I also spent a few hours thinking about how to make the entire process simpler.
I have a few ideas but I haven't quite figured it out yet.


There is quite a bit of documentation on it already, in the README and in 
doc/ - setting-up.txt, style-guide.txt, authors.txt, sections.txt.

I'll attempt a new overview:


gtk-doc is used to document C code. It is typically used to document the public
API of libraries, such as the GTK+ and Gnome libraries. But it can also be
used to document application code.

Documentation on functions can be placed inside the source files in
specially-formatted comment blocks, or it can be added to the template files
which gtk-doc uses (though note that gtk-doc will only document functions that
are declared in header files; it won't produce output for static functions).
Currently gtk-doc does not support placing documentation of other types of
declarations, such as enums, macros, and structs, inside the source code.

gtk-doc consists of a number of perl scripts, each performing a different step
in the process.


There are 5 main steps in the process:


1) Gathering information about the code.

   gtkdoc-scan scans the header files of the code looking for declarations of
   functions, macros, enums, structs, and unions. It creates a list of the
   declarations, placing them into sections according to which header file they
   are in. The author can rearrange the sections, and the order of the declarations
   within them, to produce the final desired order.

   gtkdoc-scanobj can also be used to dynamically query a library about
   any GtkObject subclasses it exports. It saves information about each object's
   position in the class hierarchy and about any GTK Args and Signals it provides.


2) Generating the "template" files.

   gtkdoc-mktmpl creates a number of files in the tmpl/ subdirectory, using the
   information gathered in the first step. (Note that this can be run repeatedly.
   It will try to ensure that no documentation is ever lost.)


3) Writing the documentation.

   The author fills in the template files with the documentation for each function,
   macro, union etc.


4) Generating the SGML and HTML.

   gtkdoc-mkdb turns the template files into SGML files in the sgml/ subdirectory.
   (If the source code contains documentation on functions, using the special
   comment blocks, it gets merged in here.)

   gtkdoc-mkhtml turns the SGML files into HTML files in the html/ subdirectory.


5) Fixing up cross-references between documents.

   After installing the HTML files, gtkdoc-fixxref can be run to fix up any
   cross-references between separate documents. For example, the GTK+ documentation
   contains many cross-references to types documented in the GLib manual.


Was that the sort of thing you wanted? Not enough detail/too much?

Damon