diff options
Diffstat (limited to '')
| -rw-r--r-- | devel-docs/README | 61 | ||||
| -rw-r--r-- | devel-docs/README.gtkdoc | 128 |
2 files changed, 189 insertions, 0 deletions
diff --git a/devel-docs/README b/devel-docs/README new file mode 100644 index 0000000..5fc7cdb --- /dev/null +++ b/devel-docs/README @@ -0,0 +1,61 @@ +Developers documentation +------------------------ + +This directory holds information that you will find useful if you +develop a GIMP plug-in or want to work on the GIMP core. + +See https://wiki.gimp.org/index.php/Main_Page for more information. + + app - setup for documentation of the GIMP core; + not built by default since it is huge and + only relevant for core developers + + libgimp + libgimpbase + libgimpcolor + libgimpconfig + libgimpmath + libgimpmodule + libgimpthumb + libgimpwidgets - complete libgimp documentation generated from + the source; see README.gtkdoc + + tools - the source code for tools used to generate + documentation + + + + gitlab-milestones.txt - describes how the GIMP project uses + milestones in the GNOME gitlab issue tracker + commit-rules.txt - describes rules and things to think + about when creating GIMP commits + contexts.txt - describes how GimpContexts are used in GIMP + debug-plug-ins.txt - how to debug GIMP plug-ins + exif-handling.txt - how GIMP should handle EXIF data + includes.txt - the policy for inclusion of header files + parasites.txt - descriptions of known parasites + release-howto.txt - a check-list for doing a GIMP release + submitting-patches.txt - how to submit a patch for GIMP + tagging.txt - how resource tagging in Gimp works + ui-framework.txt - describes how the GIMP UI framework functions and + how it is implemented + undo.txt - description of the undo system + + + structure.xml - a DocBook article that gives an overview on + the directory structure of the GIMP source tree, + also check out gimp-module-dependencies.svg + + + gbr.txt - description of the GBR format used to store + pixmap brushes + ggr.txt - description of the GGR format used to store + GIMP gradients + gih.txt - description of the GIH format used to store a + series of pixmap brushes + gpb.txt - OBSOLETE: description of the GPB format for + pixmap brushes + pat.txt - description of the PAT format for patterns + vbr.txt - description of VBR format used for + "generated" brushes + xcf.txt - description of Gimp's XCF format 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/. |