mirror of https://github.com/GNOME/gimp.git
README updated
2002-11-24 Sven Neumann <sven@gimp.org> * README * README.gtkdoc: updated
This commit is contained in:
Sven Neumann
Sven Neumann
parent
da888cfb4d
commit
086cf5784a
|
|
@ -1,5 +1,7 @@
|
|||
2002-11-24 Sven Neumann <sven@gimp.org>
|
||||
|
||||
* README
|
||||
* README.gtkdoc
|
||||
* libgimpwidgets/libgimpwidgets-sections.txt
|
||||
* libgimpwidgets/tmpl/gimpwidgets.sgml: updated.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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/.
|
||||
|
|
|
|||
Loading…
Reference in New Issue