README

   1
   2 GTK+ DocBook Documentation Generator
   3 ====================================
   4
   5 GTK-Doc is used to document C code. It is typically used to document the public
   6 API of libraries, such as the GTK+ and GNOME libraries, but it can also be
   7 used to document application code.
   8
   9 Note that GTK-Doc wasn't originally intended to be a general-purpose
  10 documentation tool, so it can be a bit awkward to setup and use.
  11 For a more polished general-purpose documentation tool you may want to look
  12 at Doxygen (http://www.doxygen.org/). However GTK-Doc has some special code
  13 to document the signals and properties of GTK+ widgets and GObject classes
  14 which other tools may not have.
  15
  16 GTK-Doc allows your documentation to be written in 2 ways:
  17   a) Embedded inside the source code in specially-formatted comments.
  18  or
  19   b) Added to the 'template' files which gtk-doc outputs after scanning all
  20      the header files and parsing the declarations.
  21
  22 From these source code comments and template files GTK-Doc generates a Docbook
  23 XML (or SGML) document, which is then transformed into HTML.
  24 The generated HTML documentation can be browsed in an ordinary web browser or
  25 by using the special Devhelp API browser
  26 (see http://developer.imendio.com/wiki/Devhelp).
  27
  28
  29 Requirements
  30 ============
  31
  32 Perl v5 - the main scripts are in Perl.
  33     http://www.perl.com/
  34
  35
  36 For XML output (recommended):
  37
  38 The DocBook XML DTD.
  39     http://www.oasis-open.org/docbook/
  40
  41 The DocBook XSL Stylesheets.
  42     http://docbook.sourceforge.net/projects/xsl/
  43
  44 libxslt & libxml2 2.3.6.
  45     http://xmlsoft.org/
  46
  47
  48 For SGML output (not actively maintained any more):
  49
  50 The DocBook SGML DTD.
  51     http://www.oasis-open.org/docbook/
  52
  53 Jade v1.1 or OpenJade 1.3.1.
  54     http://www.jclark.com/jade
  55     http://sourceforge.net/projects/openjade
  56
  57 The DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK).
  58     I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour
  59     the program code listings/declarations, and to support global
  60     cross-reference indices in the generated HTML.
  61     http://docbook.sourceforge.net/projects/dsssl/
  62
  63
  64 Most distributions now have packages for all of these, so I would strongly
  65 advise that you grab those.
  66
  67 See the documentation in the help/manual directory for more information. You can
  68 read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml