
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.

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.
    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.

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.
