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 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://nwalsh.com/docbook/dsssl


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



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.