Commit c9c94b2a authored by Sven Neumann's avatar Sven Neumann Committed by Sven Neumann

Moved various files from the docs directory to devel-docs and

2000-06-13  Sven Neumann  <sven@gimp.org>

        Moved various files from the docs directory to
        devel-docs and devel-docs/pdb. Excluded papers
        from being distributed but left them in CVS.
parent 49424610
2000-06-13 Sven Neumann <sven@gimp.org>
Moved various files from the docs directory to
devel-docs and devel-docs/pdb. Excluded papers
from being distributed but left them in CVS.
2000-06-13 Jay Cox <jaycox@gimp.org>
These files should have been commited in my 2000-05-08 commit
......
......@@ -90,6 +90,13 @@ EXTRA_DIST = \
cursors/zoom_out_mask.xbm \
cursors/zoom_small.xbm \
cursors/zoom_small_mask.xbm \
docs/Wilber.xcf.gz \
docs/Wilber.xcf.gz.README \
docs/cheat_sheet.txt \
docs/gimp.txt \
docs/keybindings.txt \
docs/gimp_quick_reference.ps \
docs/gimp_quick_reference.tar.gz \
pixmaps/anchor.xpm \
pixmaps/chain.xpm \
pixmaps/channel.xbm \
......
......@@ -792,9 +792,9 @@ plug-ins/sgi/Makefile
plug-ins/sinus/Makefile
plug-ins/struc/Makefile
modules/Makefile
docs/Makefile
devel-docs/Makefile
devel-docs/libgimp/Makefile
devel-docs/pdb/Makefile
data/Makefile
data/brushes/Makefile
data/gradients/Makefile
......
2000-06-09 Sven Neumann <sven@gimp.org>
moved various files from the docs directory
over here
2000-06-09 Sven Neumann <sven@gimp.org>
* libgimp/libgimp-decl.txt
......
SUBDIRS = libgimp
EXTRA_DIST = \
README \
README.gtkdoc \
pdb/pdb_self_doc.el \
pdb/pdb_dump \
pdb/pdb_dump.texi \
pdb/texinfo.tex \
gih.txt \
gpb.txt \
parasites.txt \
undo.txt \
xcf.txt
files:
@files=`ls $(DISTFILES) 2> /dev/null`; for p in $$files macros/*; do \
echo $$p; \
done
# devel-docs/Makefile.am ends here
Developers documentation
------------------------
The goal is to provide useful source documentation. Right
now this is limited to libgimp since that is the part that
is 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).
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.
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 man pages in future).
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 dir. The following steps
should rebuild the documentation after a change:
make sgml - Creates the SGML files from the templates found
in the tmpl dir 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 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.
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/.
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 - complete libgimp documentation generated
from the source; see README.gtkdoc
pdb - some lisp magic that allows to generate
complete PDB information in texinfo format
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
parasites.txt - descriptions of known parasites
undo.txt - description of the undo system
xcf.txt - description of Gimp's XCF format
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. It is planned to extract useful
inforamtion about the PDB wrappers out of the PDB
(probably using pdbgen).
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.
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 man pages in future).
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 dir. The following steps
should rebuild the documentation after a change:
make sgml - Creates the SGML files from the templates found
in the tmpl dir 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 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.
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/.
Makefile
Makefile.in
pdb.info*
pdb_dump
pdb_dump.texi
EXTRA_DIST = \
gimp.txt pdb_self_doc.el \
pdb_dump xcf.doc \
cheat_sheet.txt keybindings.txt \
texinfo.tex script-fu.tex \
architecture.eps logo.eps \
net-fu.eps timeline.eps \
pdb_dump.texi gimp_quick_reference.ps \
gimp_quick_reference.tar.gz undo.txt
BUILT_SOURCES = pdb_dump.texi
info_TEXINFOS = pdb.texi
pdb_TEXINFOS = pdb_dump.texi
......@@ -18,18 +6,14 @@ pdb_dump.texi: $(srcdir)/pdb_self_doc.el $(srcdir)/pdb_dump
@EMACS@ --batch -l pdb_self_doc.el -f make-docs-noargs
## use `cp' followed by `rm' since `mv' may not be able to move across mount pts
$(srcdir)/pdb_dump: $(top_srcdir)/app/*.c
$(srcdir)/pdb_dump: $(top_srcdir)/app/*_cmds.c
$(top_builddir)/app/gimp --no-interface --batch '(gimp-procedural-db-dump "pdb_dump.tmp")' '(gimp-quit 0)'
cp pdb_dump.tmp $(srcdir)/pdb_dump
-rm -f pdb_dump.tmp
script-fu.ps: script-fu.dvi
dvips -f script-fu.dvi > script-fu.ps
script-fu.dvi:
latex script-fu.tex
files:
@files=`ls $(DISTFILES) 2> /dev/null`; for p in $$files macros/*; do \
echo $$p; \
done
# devel-docs/Makefile.am ends here
Makefile
Makefile.in
pdb.info*
pdb_dump
pdb_dump.texi
*.log
*.aux
*.dvi
Wilber.xcf
quick_reference
On making Gimp OO
This document outlines the ideas of the conversion to using the GTK
object system in gimp core.
The basic problem with gimp's internals is that it is _old_. Some of
the stuff dates from the 0.54 era, before layers, before GTK. This has
caused the current source to be what some people call a "mess". You
don't want to hear what the other people call it.
Some of the main problems are that there are far, far too many headers
included everywhere. That is, encapsulation doesn't work. This causes
nasty dependencies, and doesn't exactly do good for compile times,
either. In addition, there are too much integer ids on objects. These
should only be used for pdb, and even there there'd probably be better
ways of passing them. The gtk object system will better facilitate
data hiding and encapsulation.
Then there are the tools. The tools have a primitive object hierarchy,
but it is a mess when compared to gtk's system. Restructuring the
tools will make the world a better place, and new tools easier to
implement.
GTK's object system has many other features that will make gimp
programming easier, the chief one being signals. When gimp's images
and displays have signals that you can connect callbacks to, different
components of the program will be better able to keep up with the
state of things.
Also, having all types in the gimp core use a standard object system
will make it easier to export these types as CORBA objects when the
time comes for that.
Some guidelines:
Everything should be as modular and independent as possible. Core
image manipulation classes should have no hard-coded relations with an
"UI". There should be no global variables in the classes.
All gimp classes should derive from GimpObject. This is just in case
we need some common debugging functionality or something.
For a future locking system, and just for code clarity, things should
be made const correct. That is, if a function doesn't modify an
object, it should take a pointer to a const object.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment