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 (deprecated now).

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

Please don't use template files in new projects. Support for for those will
be removed at some point in the future (together with gtkdoc-mktmpl). Please
also use DoxBook XML instead of DocBook SGML. 

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 help/manual directory for more information. You can
read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml