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 (deprecated now).
  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 Please don't use template files in new projects. Support for for those will
  29 be removed at some point in the future (together with gtkdoc-mktmpl). Please
  30 also use DoxBook XML instead of DocBook SGML.
  31
  32 Requirements
  33 ============
  34
  35 Perl v5 - the main scripts are in Perl.
  36     http://www.perl.com/
  37
  38
  39 For XML output (recommended):
  40
  41 The DocBook XML DTD.
  42     http://www.oasis-open.org/docbook/
  43
  44 The DocBook XSL Stylesheets.
  45     http://docbook.sourceforge.net/projects/xsl/
  46
  47 libxslt & libxml2 >= 2.3.6.
  48     http://xmlsoft.org/
  49
  50
  51 For SGML output (not actively maintained any more):
  52
  53 The DocBook SGML DTD.
  54     http://www.oasis-open.org/docbook/
  55
  56 Jade v1.1 or OpenJade 1.3.1.
  57     http://www.jclark.com/jade
  58     http://sourceforge.net/projects/openjade
  59
  60 The DocBook DSSSL Stylesheets (I've got 1.40, but v1.19+ may be OK).
  61     I've customized the DSSSL code slightly, in gtk-doc.dsl, to colour
  62     the program code listings/declarations, and to support global
  63     cross-reference indices in the generated HTML.
  64     http://docbook.sourceforge.net/projects/dsssl/
  65
  66
  67 Most distributions now have packages for all of these, so I would strongly
  68 advise that you grab those.
  69
  70 See the documentation in the help/manual directory for more information. You can
  71 read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml