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 document, which is then transformed into HTML and/or PDF.
  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 use DoxBook XML instead of DocBook SGML - support for the later will be
  29 dropped.
  30
  31 Requirements
  32 ============
  33
  34 Perl v5 - the main scripts are in Perl.
  35     http://www.perl.com/
  36
  37 Python 2.7, 3.x - the secondary scripts are written in Python
  38     http:///www.python.org
  39
  40 For XML output (recommended):
  41
  42 The DocBook XML DTD.
  43     http://www.oasis-open.org/docbook/
  44
  45 The DocBook XSL Stylesheets.
  46     http://docbook.sourceforge.net/projects/xsl/
  47
  48 libxslt & libxml2 >= 2.3.6.
  49     http://xmlsoft.org/
  50
  51
  52 Most distributions now have packages for all of these, so I would strongly
  53 advise that you grab those.
  54
  55 See the documentation in the help/manual directory for more information. You can
  56 read it e.g. with yelp file://$PWD/help/manual/C/gtk-doc-manual.xml