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

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 for functions, macros, widget signals, and widget properties
can be written in 2 ways:

  a) Embedded inside the source code in specially-formatted comments.

 or

  b) Added to the 'template' files which gtk-doc outputs after scanning all
     the header files and parsing the declarations.


Documentation for other constructs such as enums, structs and callbacks must
be added to the template files as in (b) above.



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

Perl v5 - the main scripts are in Perl.
    http://www.perl.com/

DocBook SGML DTD v3.0 or DocBook XML DTD v4.1.2 - the DocBook DTDs.
    http://www.oasis-open.org/docbook/

Jade v1.1 or OpenJade 1.3.1 for SGML.
    http://www.jclark.com/jade
    http://sourceforge.net/projects/openjade

libxslt & libxml2 2.3.6 for XML.
    http://xmlsoft.org/

DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK)
    This is the DSSSL code to convert DocBook SGML 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://docbook.sourceforge.net/projects/dsssl/

DocBook XSL Stylesheets
    http://docbook.sourceforge.net/projects/xsl/

Most distributions now have packages for all of these, so I would strongly
advise that you grab those.

You will also need to make sure that the DocBook XML DTD and XSL
stylesheets are installed in the system's XML catalog.  The packages
for Red Hat Linux have done this for a while, and the Debian packages
will do so too soon.  For Debian systems, you might want to try the
following script to set up the catalog:
  http://www.daa.com.au/~james/files/build-xml-catalog-for-debian.sh

For other systems, you can try the following steps provided by Mark
McLoughlin:
  1) download http://www.oasis-open.org/docbook/xml/4.1.2/docbkx412.zip
  2) install it in /usr/share/sgml/docbook/xml-dtd-4.1.2
  3) Download docbook-xsl from docbook.sf.net and install it in
     /usr/share/sgml
  4) download and run http://xmlsoft.org/buildDocBookCatalog


See the documentation in the docs directory for more information, especially
the setting-up.txt file which describes how to set up your application or
library to use gtk-doc.


Damon Chaplin (damon@gnome.org), 13 Nov 2002.

