Commit 473e9257 authored by Sven Neumann's avatar Sven Neumann Committed by Sven Neumann

Switched to DocBook XML for the developers documentation:

2003-02-06  Sven Neumann  <sven@gimp.org>

	Switched to DocBook XML for the developers documentation:

	* configure.in: check for gtk-doc >= 1.0.

	* tools/pdbgen/lib.pl: replace <, > and & in comments with their
	XML entities.

	* libgimp/gimpdrawable_pdb.c
	* libgimp/gimpgimprc_pdb.c
	* libgimp/gimppainttools_pdb.c
	* libgimp/gimpselection_pdb.c: regenerated.

	* libgimpbase/gimpsignal.c: did the same manually here.

2003-02-06  Sven Neumann  <sven@gimp.org>

	* Makefile.am
	* README.gtkdoc
	* libgimp*/Makefile.am
	* libgimp*/libgimp-docs.sgml: changed to create DocBook XML
	instead of SGML.

	* libgimp*/version.xml.in: added new file used to include the GIMP
	version in the generated XML.
parent a4a27eca
2003-02-06 Sven Neumann <sven@gimp.org>
Switched to DocBook XML for the developers documentation:
* configure.in: check for gtk-doc >= 1.0.
* tools/pdbgen/lib.pl: replace <, > and & in comments with their
XML entities.
* libgimp/gimpdrawable_pdb.c
* libgimp/gimpgimprc_pdb.c
* libgimp/gimppainttools_pdb.c
* libgimp/gimpselection_pdb.c: regenerated.
* libgimpbase/gimpsignal.c: did the same manually here.
2003-02-06 Sven Neumann <sven@gimp.org>
* app/gui/image-menu.c (image_menu_entries): removed /Filters/Text
......
......@@ -17,7 +17,7 @@ AC_INIT(app/core/gimp.c)
GLIB_REQUIRED_VERSION=2.0.0
GTK_REQUIRED_VERSION=$GLIB_REQUIRED_VERSION
PANGOFT2_REQUIRED_VERSION=1.0.0
GTKDOC_REQUIRED_VERSION=0.9
GTKDOC_REQUIRED_VERSION=1.0
GTKHTML2_REQUIRED_VERSION=1.99.5
GIMPPRINT_REQUIRED_VERSION=4.2.0
......@@ -1029,9 +1029,6 @@ if $GTKDOC ; then
fi
fi
AC_CHECK_PROG(DB2HTML, db2html, true, false)
AM_CONDITIONAL(HAVE_DOCBOOK, $DB2HTML)
dnl Make people enable the gtk-doc stuff explicitely.
AC_ARG_ENABLE(gtk-doc, [ --enable-gtk-doc use gtk-doc to build documentation [default=no]], enable_gtk_doc="$enableval", enable_gtk_doc=auto)
......@@ -1205,11 +1202,17 @@ plug-ins/tools/Makefile
modules/Makefile
devel-docs/Makefile
devel-docs/libgimp/Makefile
devel-docs/libgimp/version.xml
devel-docs/libgimpbase/Makefile
devel-docs/libgimpbase/version.xml
devel-docs/libgimpcolor/Makefile
devel-docs/libgimpcolor/version.xml
devel-docs/libgimpmath/Makefile
devel-docs/libgimpmath/version.xml
devel-docs/libgimpmodule/Makefile
devel-docs/libgimpmodule/version.xml
devel-docs/libgimpwidgets/Makefile
devel-docs/libgimpwidgets/version.xml
docs/Makefile
docs/gimp-1.3.1
docs/gimprc-1.3.5
......
2003-02-06 Sven Neumann <sven@gimp.org>
* Makefile.am
* README.gtkdoc
* libgimp*/Makefile.am
* libgimp*/libgimp-docs.sgml: changed to create DocBook XML
instead of SGML.
* libgimp*/version.xml.in: added new file used to include the GIMP
version in the generated XML.
* libgimpwidgets/tmpl/gimpdialog.sgml
* libgimpwidgets/tmpl/gimpunitmenu.sgml
* libgimpwidgets/tmpl/gimpwidgets.sgml: fixed broken syntax.
2003-02-06 Sven Neumann <sven@gimp.org>
* libgimpbase/tmpl/gimputils.sgml
......
## Process this file with automake to produce Makefile.in
SUBDIRS = \
libgimpbase \
libgimpcolor \
libgimpmath \
libgimpbase \
libgimpmodule \
libgimpwidgets \
libgimp
......
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.
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.
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 SGML template files.
Requirements
------------
GIMP release tarballs contain a complete set of precompiled HTML files as well
as SGML 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:
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.
DocBook DTD v3.0 - This is the DocBook SGML DTD.
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
libxslt & libxml2 (version >= 2.3.6) - This is used to convert the
XML templates to HTML.
http://xmlsoft.org/
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 other formats).
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/
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.
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 touch the Makefile or any other files
in the toplevel directory.
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 SGML files in the tmpl
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 SGML 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 SGML and HTML files for you. Since the dependencies are not
perfect, you sometimes need to call 'make clean; make' to force regeneration.
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.
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 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/.
......@@ -9,5 +9,6 @@ libgimp-decl-list.txt
libgimp-unused.txt
libgimp-undocumented.txt
html
sgml
xml
version.xml
*.stamp
......@@ -16,7 +16,7 @@ SCANGOBJ_OPTIONS =
SCAN_OPTIONS =
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS =
MKDB_OPTIONS = --sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS = --extra-dir=../libgimpbase/html --extra-dir=../libgimpcolor/html --extra-dir=../libgimpmath/html --extra-dir=../libgimpwidgets/html
......@@ -73,7 +73,7 @@ EXTRA_DIST = \
$(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt
DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
DOC_STAMPS=scan-build.stamp tmpl-build.stamp xml-build.stamp html-build.stamp \
$(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
SCANOBJ_FILES = \
......@@ -113,15 +113,15 @@ tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections
tmpl.stamp: tmpl-build.stamp
@true
#### sgml ####
#### xml ####
sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
@echo '*** Building SGML ***'
xml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
@echo '*** Building XML ***'
cd $(srcdir) && \
gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
touch sgml-build.stamp
touch xml-build.stamp
sgml.stamp: sgml-build.stamp
sgml.stamp: xml-build.stamp
@true
#### html ####
......@@ -145,7 +145,7 @@ clean-local:
rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
cd $(srcdir) && rm -rf xml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
install-data-local:
$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
......@@ -182,10 +182,10 @@ endif
dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
mkdir $(distdir)/sgml
mkdir $(distdir)/xml
mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/xml/*.xml $(distdir)/xml
-cp $(srcdir)/html/* $(distdir)/html
.PHONY : dist-hook-local
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity Gimp SYSTEM "sgml/gimp.sgml">
<!entity GimpBrushes SYSTEM "sgml/gimpbrushes.sgml">
<!entity GimpChannel SYSTEM "sgml/gimpchannel.sgml">
<!entity GimpColor SYSTEM "sgml/gimpcolor.sgml">
<!entity GimpConvert SYSTEM "sgml/gimpconvert.sgml">
<!entity GimpDisplay SYSTEM "sgml/gimpdisplay.sgml">
<!entity GimpDrawable SYSTEM "sgml/gimpdrawable.sgml">
<!entity GimpEdit SYSTEM "sgml/gimpedit.sgml">
<!entity GimpFileops SYSTEM "sgml/gimpfileops.sgml">
<!entity GimpFloatingsel SYSTEM "sgml/gimpfloatingsel.sgml">
<!entity GimpGimprc SYSTEM "sgml/gimpgimprc.sgml">
<!entity GimpGradients SYSTEM "sgml/gimpgradients.sgml">
<!entity GimpGuides SYSTEM "sgml/gimpguides.sgml">
<!entity GimpHelp SYSTEM "sgml/gimphelp.sgml">
<!entity GimpImage SYSTEM "sgml/gimpimage.sgml">
<!entity GimpLayer SYSTEM "sgml/gimplayer.sgml">
<!entity GimpMessage SYSTEM "sgml/gimpmessage.sgml">
<!entity GimpMisc SYSTEM "sgml/gimpmisc.sgml">
<!entity GimpPalette SYSTEM "sgml/gimppalette.sgml">
<!entity GimpPatterns SYSTEM "sgml/gimppatterns.sgml">
<!entity GimpPixelrgn SYSTEM "sgml/gimppixelrgn.sgml">
<!entity GimpPlugin SYSTEM "sgml/gimpplugin.sgml">
<!entity GimpProceduraldb SYSTEM "sgml/gimpproceduraldb.sgml">
<!entity GimpSelection SYSTEM "sgml/gimpselection.sgml">
<!entity GimpTexttool SYSTEM "sgml/gimptexttool.sgml">
<!entity GimpTile SYSTEM "sgml/gimptile.sgml">
<!entity GimpTools SYSTEM "sgml/gimptools.sgml">
<!entity GimpUndo SYSTEM "sgml/gimpundo.sgml">
<!entity GimpEnums SYSTEM "sgml/gimpenums.sgml">
<!entity GimpExport SYSTEM "sgml/gimpexport.sgml">
<!entity GimpMenu SYSTEM "sgml/gimpmenu.sgml">
<!entity GimpUI SYSTEM "sgml/gimpui.sgml">
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY Gimp SYSTEM "xml/gimp.xml">
<!ENTITY GimpBrushes SYSTEM "xml/gimpbrushes.xml">
<!ENTITY GimpChannel SYSTEM "xml/gimpchannel.xml">
<!ENTITY GimpColor SYSTEM "xml/gimpcolor.xml">
<!ENTITY GimpConvert SYSTEM "xml/gimpconvert.xml">
<!ENTITY GimpDisplay SYSTEM "xml/gimpdisplay.xml">
<!ENTITY GimpDrawable SYSTEM "xml/gimpdrawable.xml">
<!ENTITY GimpEdit SYSTEM "xml/gimpedit.xml">
<!ENTITY GimpFileops SYSTEM "xml/gimpfileops.xml">
<!ENTITY GimpFloatingsel SYSTEM "xml/gimpfloatingsel.xml">
<!ENTITY GimpGimprc SYSTEM "xml/gimpgimprc.xml">
<!ENTITY GimpGradients SYSTEM "xml/gimpgradients.xml">
<!ENTITY GimpGuides SYSTEM "xml/gimpguides.xml">
<!ENTITY GimpHelp SYSTEM "xml/gimphelp.xml">
<!ENTITY GimpImage SYSTEM "xml/gimpimage.xml">
<!ENTITY GimpLayer SYSTEM "xml/gimplayer.xml">
<!ENTITY GimpMessage SYSTEM "xml/gimpmessage.xml">
<!ENTITY GimpMisc SYSTEM "xml/gimpmisc.xml">
<!ENTITY GimpPalette SYSTEM "xml/gimppalette.xml">
<!ENTITY GimpPatterns SYSTEM "xml/gimppatterns.xml">
<!ENTITY GimpPixelrgn SYSTEM "xml/gimppixelrgn.xml">
<!ENTITY GimpPlugin SYSTEM "xml/gimpplugin.xml">
<!ENTITY GimpProceduraldb SYSTEM "xml/gimpproceduraldb.xml">
<!ENTITY GimpSelection SYSTEM "xml/gimpselection.xml">
<!ENTITY GimpTexttool SYSTEM "xml/gimptexttool.xml">
<!ENTITY GimpTile SYSTEM "xml/gimptile.xml">
<!ENTITY GimpTools SYSTEM "xml/gimptools.xml">
<!ENTITY GimpUndo SYSTEM "xml/gimpundo.xml">
<!ENTITY GimpEnums SYSTEM "xml/gimpenums.xml">
<!ENTITY GimpExport SYSTEM "xml/gimpexport.xml">
<!ENTITY GimpMenu SYSTEM "xml/gimpmenu.xml">
<!ENTITY GimpUI SYSTEM "xml/gimpui.xml">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>GIMP Library Reference Manual</title>
<releaseinfo>for GIMP &version;</releaseinfo>
</bookinfo>
<chapter id="gimpdefinitions">
......
......@@ -9,5 +9,6 @@ libgimpbase-decl-list.txt
libgimpbase-unused.txt
libgimpbase-undocumented.txt
html
sgml
xml
version.xml
*.stamp
......@@ -16,7 +16,7 @@ SCANGOBJ_OPTIONS =
SCAN_OPTIONS =
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS =
MKDB_OPTIONS = --sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS =
......@@ -67,7 +67,7 @@ EXTRA_DIST = \
$(DOC_MODULE).types \
$(DOC_MODULE)-sections.txt
DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
DOC_STAMPS=scan-build.stamp tmpl-build.stamp xml-build.stamp html-build.stamp \
$(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp
SCANOBJ_FILES = \
......@@ -107,15 +107,15 @@ tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections
tmpl.stamp: tmpl-build.stamp
@true
#### sgml ####
#### xml ####
sgml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
@echo '*** Building SGML ***'
xml-build.stamp: tmpl.stamp $(CFILE_GLOB) $(srcdir)/tmpl/*.sgml
@echo '*** Building XML ***'
cd $(srcdir) && \
gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) $(MKDB_OPTIONS)
touch sgml-build.stamp
touch xml-build.stamp
sgml.stamp: sgml-build.stamp
sgml.stamp: xml-build.stamp
@true
#### html ####
......@@ -139,7 +139,7 @@ clean-local:
rm -f *~ *.bak $(SCANOBJ_FILES) *-unused.txt $(DOC_STAMPS)
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
cd $(srcdir) && rm -rf xml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
install-data-local:
$(mkinstalldirs) $(DESTDIR)$(TARGET_DIR)
......@@ -176,10 +176,10 @@ endif
dist-hook: dist-check-gtkdoc dist-hook-local
mkdir $(distdir)/tmpl
mkdir $(distdir)/sgml
mkdir $(distdir)/xml
mkdir $(distdir)/html
-cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl
-cp $(srcdir)/sgml/*.sgml $(distdir)/sgml
-cp $(srcdir)/xml/*.xml $(distdir)/xml
-cp $(srcdir)/html/* $(distdir)/html
.PHONY : dist-hook-local
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity GimpBaseTypes SYSTEM "sgml/gimpbasetypes.sgml">
<!entity GimpLimits SYSTEM "sgml/gimplimits.sgml">
<!entity GimpDatafiles SYSTEM "sgml/gimpdatafiles.sgml">
<!entity GimpEnv SYSTEM "sgml/gimpenv.sgml">
<!entity GimpParasite SYSTEM "sgml/gimpparasite.sgml">
<!entity GimpParasiteIO SYSTEM "sgml/gimpparasiteio.sgml">
<!entity GimpSignal SYSTEM "sgml/gimpsignal.sgml">
<!entity GimpUnit SYSTEM "sgml/gimpunit.sgml">
<!entity GimpUtils SYSTEM "sgml/gimputils.sgml">
<!entity GimpVersion SYSTEM "sgml/gimpversion.sgml">
<!entity GimpProtocol SYSTEM "sgml/gimpprotocol.sgml">
<!entity GimpWire SYSTEM "sgml/gimpwire.sgml">
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY GimpBaseTypes SYSTEM "xml/gimpbasetypes.xml">
<!ENTITY GimpLimits SYSTEM "xml/gimplimits.xml">
<!ENTITY GimpDatafiles SYSTEM "xml/gimpdatafiles.xml">
<!ENTITY GimpEnv SYSTEM "xml/gimpenv.xml">
<!ENTITY GimpParasite SYSTEM "xml/gimpparasite.xml">
<!ENTITY GimpParasiteIO SYSTEM "xml/gimpparasiteio.xml">
<!ENTITY GimpSignal SYSTEM "xml/gimpsignal.xml">
<!ENTITY GimpUnit SYSTEM "xml/gimpunit.xml">
<!ENTITY GimpUtils SYSTEM "xml/gimputils.xml">
<!ENTITY GimpVersion SYSTEM "xml/gimpversion.xml">
<!ENTITY GimpProtocol SYSTEM "xml/gimpprotocol.xml">
<!ENTITY GimpWire SYSTEM "xml/gimpwire.xml">
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index">
<bookinfo>
<title>GIMP Base Library Reference Manual</title>
<releaseinfo>for GIMP &version;</releaseinfo>
</bookinfo>
<chapter id="libgimpbase">
......
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