mirror of https://github.com/GNOME/gimp.git
109 lines
4.1 KiB
Plaintext
109 lines
4.1 KiB
Plaintext
|
Developers documentation using gtk-doc
|
||
|
|
--------------------------------------
|
||
|
|
|
||
|
|
The goal is to provide useful source documentation. Right
|
||
|
|
now this is limited to libgimp since that is the part that
|
||
|
|
is used 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.
|
||
|
|
|
||
|
|
|
||
|
|
If the source was changed (real changes as described above),
|
||
|
|
you will need to perform the following two steps before you can
|
||
|
|
rebuild the sgml and html files:
|
||
|
|
|
||
|
|
make scan - Scans the header files and builds and runs a
|
||
|
|
binary that asks the GtkObjects to describe
|
||
|
|
themselves. That way the hierarchy of widgets,
|
||
|
|
arguments and signals are determined. If you
|
||
|
|
have added new objects, you will have to update
|
||
|
|
the MODULE.types files accordingly before you
|
||
|
|
perform this step.
|
||
|
|
|
||
|
|
make templates - Merges the changes into the templates. This will
|
||
|
|
output warnings about any declarations which have
|
||
|
|
been added/removed. Update the MODULE-sections.txt
|
||
|
|
to include the new functions etc. in the
|
||
|
|
appropriate sections, and delete ones which are
|
||
|
|
no longer available. Run "make templates" again
|
||
|
|
until there are no warnings output.
|
||
|
|
|
||
|
|
|
||
|
|
More information
|
||
|
|
----------------
|
||
|
|
Using the system as described above, you can write documentation without
|
||
|
|
any knowledge of SGML and DocBook, but when editing the templates you
|
||
|
|
will sometimes want to do a little extra structuring or markup. The best
|
||
|
|
source for information about DocBook seems to be "DocBook: The Definitive
|
||
|
|
Guide" which is available online at http://www.docbook.org/tdg/html/.
|
||
|
|
|