gimp/devel-docs

Developers documentation 
------------------------

The goal is to provide useful source documentation. Right 
now this is limited to libgimp since that is the part that 
is by third-party coders (plug-in developers). Other parts
of the code may follow later, but not before libgimp is 
properly documented.


Principle
---------
The documentation is extracted out of the source using 
gtk-doc. We use a combination of comment blocks embedded 
into the source and additional information added manually 
into the SGML files. It is planned to extract useful 
inforamtion about the PDB wrappers out of the PDB 
(probably using pdbgen).


Requirements
------------
GIMP releases will contain a complete set of HTML files and
the SGML files to create other formats. You will only need
gtk-doc if you want to work on the documentation itself. 
In that case you will need the following utilities:

Perl v5 - the main scripts are in Perl.

DocBook DTD v3.0 - This is the DocBook SGML DTD.
    http://www.ora.com/davenport

Jade v1.1 - This is a DSSSL processor for converting SGML 
    to various formats. 
    http://www.jclark.com/jade

Modular DocBook Stylesheets (v1.19+ should be OK)
    This is the DSSSL code to convert DocBook to HTML (and 
    a few other formats). It's used together with jade.
    http://nwalsh.com/docbook/dsssl

gtk-doc - This package automatically generates DocBook 
    documentation for GTK+ and converts the DocBook 
    documentation into HTML (and man pages in future).
    http://www.gtk.org/rdp/download.html


HOWTO
-----
Carefully read the README that comes with gtk-doc. Then 
read it again! The following lines will only give you hints
about how our system works. You should have understood the
principles of gtk-doc before you touch it.

The system is already set up so unless there are substantial
changes to the source e.g. new files were added, functions 
were added, renamed or removed or parameters changed, there
is no need to repeat the scan step or rebuild the templates.

The Makefile will only work if gtk-doc was successfully
found when configure was ran. To rerun the scan step you also
need to have gimp installed (the version you are documenting)
and the correct version of gimptool should be found in your 
PATH. If everything was set up correctly running a simple 
make should do the trick and generate the SGML and HTML files 
for you.

In most cases you will work on the documentation by adding or
editing comment blocks in the C source and by editing the 
template SGML files in the tmpl dir. The following steps 
should rebuild the documentation after a change:

make sgml  - Creates the SGML files from the templates found
             in the tmpl dir and from the comment blocks found
             in the source.

make html  - Build HTML pages out of the SGML files.