
GTK+ DocBook Documentation Generator
====================================

This package automatically generates DocBook documentation for GTK+ and Gnome,
and converts the DocBook documentation into HTML (and man pages in future).



Requirements
============

Perl v5 - the main scripts are in Perl.

DocBook DTD v3.0 - This is the DocBook SGML DTD.
    http://www.ora.com/davenport

Jade v1.1 - This is a DSSSL processor for converting SGML to various formats.
    http://www.jclark.com/jade

Modular DocBook Stylesheets (I've got 1.33, but v1.15+ should be OK)
    This is the DSSSL code to convert DocBook to HTML (and a few other
    formats). It's used together with jade.
    I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour
    the program code listings/declarations, and to support global
    cross-reference indices in the generated HTML.
    http://nwalsh.com/docbook/dsssl

docbook-to-man - if you want to create man pages from the DocBook.
    I've customized the 'translation spec' slightly, to capitalise section
    headings and add the 'GTK Library' title at the top of the pages and the
    revision date at the bottom.
    There is a link to this on http://www.ora.com/davenport
    NOTE: This does not work yet.


Installation
============

There is no standard place where the DocBook Modular Stylesheets are installed.

gtk-doc's configure script searches these 2 directories automatically:
  /usr/lib/sgml/stylesheets/nwalsh-modular       (used by RedHat)
  /usr/lib/dsssl/stylesheets/docbook             (used by Debian)

If you have the stylesheets installed somewhere else, you need to configure
gtk-doc using the option:
   --with-dsssl-dir=<PATH_TO_TOPLEVEL_STYLESHEETS_DIR>


Overview
========

There are main 6 programs in gtk-doc. Most of them take a --module=XXX flag
specifying the name of the module (we'll use MODULE below):


gtkdoc-scan:	Scans header files looking for declarations of functions,
		macros, enums, structs, and union. It outputs two files -
		MODULE-decl.txt which contains the declarations, and
		MODULE-decl-list.txt which contains a list of their names.


gtkdoc-scanobj:	Creates a small C program which is compiled and run to query
		your library about which GtkObjects it contains and the
		signals that they emit. If your module has no GtkObjects then
		you don't need to use this.

		You need to create a MODULE.types file which contains:

		a) #include lines necessary to compile a program against
		   your library.
		b) The GtkObject types in your library, represented by lines
		   listing the name of a get_type() function.

		An example file that does part of gtk would look like:

		============
		#include <gtk/gtk.h>
		gtk_object_get_type
		gtk_widget_get_type
		gtk_button_get_type
		============

		Set the CFLAGS and LDFLAGS environment variables to the
		values necessary to compile a program against your
		library, then run 'gtkdoc-scanobj --module=MODULE'.

		It outputs MODULE.hierarchy which contains your widgets and
		their ancestors, and MODULE.signals which contains prototypes
		of the signals that they emit.


gtkdoc-mktmpl:	Uses MODULE-sections.txt to generate a set of template files
		in tmpl/. MODULE-sections.txt is used to determine the order
		and organization of the functions in the generated templates.
		It is initially created by copying MODULE-decl-list.txt which
		was generated by gtkdoc-scan, and then edited manually to
		reorganise it.

		The template files are then filled in with descriptions of
		the functions/macros etc. and their arguments.
		(For Gnome, functions are described in the source code in
		specially formatted comment blocks, but the templates are still
		used for the section descriptions and for long examples.)


gtkdoc-mkdb:	Generates the DocBook SGML in sgml/, using MODULE-sections.txt
		and the template files (and for Gnome it also uses the comment
		blocks in the source code).


gtkdoc-mkhtml:	Turns the DocBook SGML into HTML, using the main SGML file
		(typically called MODULE-docs.sgml) which you must create.
		gtkdoc-mkdb creates the files sgml/MODULE-doc.top & 
		sgml/MODULE-doc.bottom which contains all the entities which
		were generated, so they should be included somewhere.
		When new files have been added to MODULE-sections.txt, or when
		titles of sections change, you must update the main SGML file.

		Warnings output by gtkdoc-mkhtml about references to
		non-existent entities can generally be ignored.

		Warnings about not being able to find .sgml files usually
		means that you haven't updated the main SGML file.


gtkdoc-fixxref:	Fixes up the cross-references to documentation in other
		modules. This is run immediately after installing the HTML
		files.

		We have customised the DSSSL code so that each module outputs
		an index.sgml file containing relative URLs to all of the
		functions/macro etc. descriptions, like this:

	     <ANCHOR id ="GBOOLEAN" href="glib/glib-basic-types.html#GBOOLEAN">
	     <ANCHOR id ="GPOINTER" href="glib/glib-basic-types.html#GPOINTER">

		We have also changed the DSSSL so that if a link target can't
		be found within the module it outputs
		<GTKDOCLINK href="target-element-id">...</GTKDOCLINK>.
		
		gtkdoc-fixref reads all the available index.sgml files and
		converts all of the GTKDOCLINK tags to proper links.



Resyncing the Documentation with New Versions of the Source
===========================================================

Run gtkdoc-scan (and gtkdoc-scanobj if necessary) to rescan the sources.

Run gtkdoc-mktmpl to merge the changes into the templates.
This will output warnings about any declarations which have been added/removed.

Update the MODULE-sections.txt to include the new functions etc. in the
appropriate sections, and delete ones which are no longer available.

Run gtkdoc-mktmpl again, until there are no warnings output.


Using automake & make
=====================

Rather than run the above scripts by hand, passing the appropriate arguments,
its better to use automake & make and create special targets for gtk-doc.

We've been using the targets:

  make scan	 - to run gtkdoc-scan (& gtkdoc-scanobj if appropriate)

  make templates - does the same as make scan but also runs gtkdoc-mktmpl
		   to regerenate the templates

  make sgml      - runs gtkdoc-mkdb to generate the DocBook SGML.

  make html      - runs gtkdoc-mkhtml to convert the DocBook to HTML.

We also added local clean and install commands.


Examples
========

The examples directory shows how libgnome and libgnomeui could be set up to
use gtk-doc. (These are what I have been using to test gtk-doc.)


Damon Chaplin (damon@karuna.freeserve.co.uk), 18 Jan 1999.

