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.

Note that GTK-Doc wasn't originally intended to be a general-purpose
documentation tool, so it can be a bit awkward to setup and use.
For a more polished general-purpose documentation tool you may want to look
at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code
to document the signals and properties of GTK+ widgets and GObject classes
which other tools may not have.

GTK-Doc allows your documentation to 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.

(Note that currently the documentation describing each section can only be
added to the template files, though in future that will also be allowed within
the source code.)

From these source code comments and template files GTK-Doc generates a Docbook
XML (or SGML) document, which is then transformed into HTML.
The generated HTML documentation can be browsed in an ordinary web browser or
by using the special Devhelp API browser
(see http://developer.imendio.com/wiki/Devhelp).


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

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


For XML output (recommended):

The DocBook XML DTD.
    http://www.oasis-open.org/docbook/

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

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



For SGML output (not actively maintained any more):

The DocBook SGML DTD.
    http://www.oasis-open.org/docbook/

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

The DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK).
    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/


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
for Sarge do also. For older 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.