Adding upstream version 2.10.34.upstream/2.10.34upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 128 insertions, 0 deletions

diff --git a/devel-docs/README.gtkdoc b/devel-docs/README.gtkdoc
new file mode 100644
index 0000000..b571a7b
--- /dev/null
+++ b/devel-docs/README.gtkdoc
@@ -0,0 +1,128 @@
+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 (see
+http://www.gtk.org/gtk-doc/). We use a combination of comment blocks
+embedded into the source and additional information added manually
+into SGML template files.
+
+
+Requirements
+------------
+
+GIMP release tarballs contain a complete set of precompiled HTML files
+as well as DocBook XML files to create other formats. You 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.
+
+libxslt & libxml2 (version >= 2.3.6)
+    This is used to convert the XML templates to HTML.
+    http://xmlsoft.org/
+
+DocBook XML DTD v4.1.2
+    http://www.docbook.org/
+
+gtk-doc (version >= 1.0)
+    This package automatically generates DocBook documentation from
+    source and is able to convert it into HTML (and other formats).
+    ftp://ftp.gtk.org/pub/gtk-doc/
+
+
+You need to have all this properly setup. This includes the
+availability of an XML catalog (/etc/xml/catalog) that tells the
+XSLT processor where to look for locally installed DTDs. If that
+file is missing, the XSLT processor will try to access the DTDs
+online which will either fail or take forever. For this reason,
+the docs are not built by default. If you think you have a working
+setup, pass '--enable-gtk-doc' to configure.
+
+
+How it works
+------------
+
+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 touch the
+Makefile or any other files in the toplevel directory.
+
+In most cases you will work on the documentation by adding or editing
+comment blocks in the C source and by editing the template XML files
+in the tmpl directory.
+
+After you've done any changes to the documentation, running 'make'
+should rebuild the documentation. This will however only work if
+configure was called with the option '--enable-gtk-doc' and gtk-doc
+was successfully found. If everything was set up correctly, running
+'make' should do the trick and generate the XML and HTML files for
+you. Since the dependencies are not perfect, you sometimes need to
+call 'make clean; make' to force regeneration.
+
+
+How to write proper gtk-doc comments
+------------------------------------
+
+Here are some hints on writing proper gtk-doc comments. They are based
+on the gtk-doc documentation which comes with the gtk-doc source tree:
+
+These are the comment blocks used in GIMP source files to document
+functions (and macros, signals and properties, if you want).
+
+/**
+ * function_name:
+ * @par1:  description of parameter 1. These can extend over more than
+ *         one line.
+ * @par2:  description of parameter 2
+ *
+ * The function description goes here. You can use @par1 to refer to
+ * parameters so that they are highlighted in the output. You can also
+ * use %constant for constants, function_name2() for functions and
+ * #GtkWidget for links to other declarations (which may be documented
+ * elsewhere).
+ * 
+ * Return value: an integer.
+ **/
+
+The block starts with '/**'.
+Each line starts with ' * '.
+
+The second line is the function name, followed by a ':'. In order to
+document signals in inline comments, use a name of the form
+class::signal, e.g. GtkWidget::notify-child. For properties, use a
+name of the form class:property, e.g. GtkAlignment:top-padding. Note
+that gtk-doc expects the signal and property names to be spelled with
+hyphens, not underlines.
+
+Following the function name are the parameters, e.g. '@par1:' above.
+
+A blank line MUST be used to separate parameter descriptions from the
+main description (otherwise it is assumed to be a continuation of the
+parameter description.)
+
+After the main description is a 'Return value:' line to describe the
+returned value of the function (if it is not void).
+
+
+More information
+----------------
+
+Using the system as described above, you can write documentation
+without any knowledge of DocBook XML, 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/.