mirror of
https://gitlab.gnome.org/GNOME/gimp
synced 2024-10-20 08:37:21 +00:00
99 lines
4.1 KiB
Plaintext
99 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.
|
|
|
|
|
|
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 - Most of the scripts used are written 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 other formats).
|
|
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
|
|
directory. The following steps should rebuild the documentation after a
|
|
change:
|
|
|
|
make sgml - Creates the SGML files from the templates found in the tmpl
|
|
directory 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
|
|
objects to describe themselves using the GObject
|
|
introspection facilities. 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/.
|