From 086cf5784ac889e7fe7af9e8d6e7769a178bb718 Mon Sep 17 00:00:00 2001 From: Sven Neumann Date: Sun, 24 Nov 2002 22:54:46 +0000 Subject: [PATCH] README updated 2002-11-24 Sven Neumann * README * README.gtkdoc: updated --- devel-docs/ChangeLog | 2 + devel-docs/README | 18 +++--- devel-docs/README.gtkdoc | 134 ++++++++++++++++++--------------------- 3 files changed, 72 insertions(+), 82 deletions(-) diff --git a/devel-docs/ChangeLog b/devel-docs/ChangeLog index caddd6a230..953641adc4 100644 --- a/devel-docs/ChangeLog +++ b/devel-docs/ChangeLog @@ -1,5 +1,7 @@ 2002-11-24 Sven Neumann + * README + * README.gtkdoc * libgimpwidgets/libgimpwidgets-sections.txt * libgimpwidgets/tmpl/gimpwidgets.sgml: updated. diff --git a/devel-docs/README b/devel-docs/README index 2eb61538c2..ffa99674c3 100644 --- a/devel-docs/README +++ b/devel-docs/README @@ -1,21 +1,19 @@ 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. +This directory holds information that you will find useful if you +develop a GIMP plug-in or want to work on the GIMP core. libgimp libgimpbase libgimpcolor libgimpmath - libgimpwidgets - complete libgimp documentation generated - from the source; see README.gtkdoc - - gih.txt - description of the GIH format used to - store a series of pixmap brushes - gpb.txt - description of the GPB format used to - store pixmap brushes + libgimpmodule + libgimpwidgets - complete libgimp documentation generated from + the source; see README.gtkdoc + gih.txt - description of the GIH format used to store a + series of pixmap brushes + gpb.txt - description of the GPB format for pixmap brushes parasites.txt - descriptions of known parasites undo.txt - description of the undo system xcf.txt - description of Gimp's XCF format diff --git a/devel-docs/README.gtkdoc b/devel-docs/README.gtkdoc index a2b95c5b47..6c8d5407c9 100644 --- a/devel-docs/README.gtkdoc +++ b/devel-docs/README.gtkdoc @@ -1,108 +1,98 @@ 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 +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). + +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 - the main scripts are in Perl. +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. +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. +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). +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. +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 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. +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. -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: +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 sgml - Creates the SGML files from the templates found - in the tmpl dir and from the comment blocks found - in the source. +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 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. +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/. +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/.