diff --git a/ChangeLog b/ChangeLog index a59801459b..f963eb1488 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2000-06-13 Sven Neumann + + 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 These files should have been commited in my 2000-05-08 commit diff --git a/Makefile.am b/Makefile.am index b11152dc17..cda099285c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 \ diff --git a/configure.in b/configure.in index 24609546b3..5aaf37e9f1 100644 --- a/configure.in +++ b/configure.in @@ -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 diff --git a/devel-docs/ChangeLog b/devel-docs/ChangeLog index 6e1b36b855..3c3c731a29 100644 --- a/devel-docs/ChangeLog +++ b/devel-docs/ChangeLog @@ -1,3 +1,8 @@ +2000-06-09 Sven Neumann + + moved various files from the docs directory + over here + 2000-06-09 Sven Neumann * libgimp/libgimp-decl.txt diff --git a/devel-docs/Makefile.am b/devel-docs/Makefile.am index 5aac00dfda..19d76ffa98 100644 --- a/devel-docs/Makefile.am +++ b/devel-docs/Makefile.am @@ -1,3 +1,21 @@ 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 diff --git a/devel-docs/README b/devel-docs/README index cbad6c52b1..15eaed68a4 100644 --- a/devel-docs/README +++ b/devel-docs/README @@ -1,109 +1,19 @@ 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 diff --git a/devel-docs/README.gtkdoc b/devel-docs/README.gtkdoc new file mode 100644 index 0000000000..a2b95c5b47 --- /dev/null +++ b/devel-docs/README.gtkdoc @@ -0,0 +1,108 @@ +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/. + diff --git a/docs/gih.txt b/devel-docs/gih.txt similarity index 100% rename from docs/gih.txt rename to devel-docs/gih.txt diff --git a/docs/gpb.txt b/devel-docs/gpb.txt similarity index 100% rename from docs/gpb.txt rename to devel-docs/gpb.txt diff --git a/docs/parasites.txt b/devel-docs/parasites.txt similarity index 100% rename from docs/parasites.txt rename to devel-docs/parasites.txt diff --git a/devel-docs/pdb/.cvsignore b/devel-docs/pdb/.cvsignore new file mode 100644 index 0000000000..ec537fa762 --- /dev/null +++ b/devel-docs/pdb/.cvsignore @@ -0,0 +1,5 @@ +Makefile +Makefile.in +pdb.info* +pdb_dump +pdb_dump.texi diff --git a/docs/Makefile.am b/devel-docs/pdb/Makefile.am similarity index 54% rename from docs/Makefile.am rename to devel-docs/pdb/Makefile.am index f07869201b..8e76a3ffd1 100644 --- a/docs/Makefile.am +++ b/devel-docs/pdb/Makefile.am @@ -1,15 +1,3 @@ -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 diff --git a/docs/pdb.texi b/devel-docs/pdb/pdb.texi similarity index 100% rename from docs/pdb.texi rename to devel-docs/pdb/pdb.texi diff --git a/docs/pdb_self_doc.el b/devel-docs/pdb/pdb_self_doc.el similarity index 100% rename from docs/pdb_self_doc.el rename to devel-docs/pdb/pdb_self_doc.el diff --git a/docs/undo.txt b/devel-docs/undo.txt similarity index 100% rename from docs/undo.txt rename to devel-docs/undo.txt diff --git a/docs/xcf.doc b/devel-docs/xcf.txt similarity index 100% rename from docs/xcf.doc rename to devel-docs/xcf.txt diff --git a/docs/.cvsignore b/docs/.cvsignore index 2fbaf8cf80..43c10f32d0 100644 --- a/docs/.cvsignore +++ b/docs/.cvsignore @@ -1,8 +1,2 @@ -Makefile -Makefile.in -pdb.info* -pdb_dump -pdb_dump.texi -*.log -*.aux -*.dvi +Wilber.xcf +quick_reference diff --git a/docs/OO.txt b/docs/OO.txt deleted file mode 100644 index 9c91af651d..0000000000 --- a/docs/OO.txt +++ /dev/null @@ -1,48 +0,0 @@ - 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. - - diff --git a/docs/white-paper/.cvsignore b/docs/papers/script-fu/.cvsignore similarity index 100% rename from docs/white-paper/.cvsignore rename to docs/papers/script-fu/.cvsignore diff --git a/docs/architecture.eps b/docs/papers/script-fu/architecture.eps similarity index 100% rename from docs/architecture.eps rename to docs/papers/script-fu/architecture.eps diff --git a/docs/logo.eps b/docs/papers/script-fu/logo.eps similarity index 100% rename from docs/logo.eps rename to docs/papers/script-fu/logo.eps diff --git a/docs/net-fu.eps b/docs/papers/script-fu/net-fu.eps similarity index 100% rename from docs/net-fu.eps rename to docs/papers/script-fu/net-fu.eps diff --git a/docs/script-fu.tex b/docs/papers/script-fu/script-fu.tex similarity index 100% rename from docs/script-fu.tex rename to docs/papers/script-fu/script-fu.tex diff --git a/docs/timeline.eps b/docs/papers/script-fu/timeline.eps similarity index 100% rename from docs/timeline.eps rename to docs/papers/script-fu/timeline.eps diff --git a/docs/papers/white-paper/.cvsignore b/docs/papers/white-paper/.cvsignore new file mode 100644 index 0000000000..92460503bd --- /dev/null +++ b/docs/papers/white-paper/.cvsignore @@ -0,0 +1,3 @@ +*.dvi +*.log +*.aux diff --git a/docs/white-paper/gimp-white-paper.tex b/docs/papers/white-paper/gimp-white-paper.tex similarity index 100% rename from docs/white-paper/gimp-white-paper.tex rename to docs/papers/white-paper/gimp-white-paper.tex