One more stab at an XML docbook tools tutorial

@if os.name == "FreeBSD":
    Installing the XML docbook tools from ports is by far the easiest thing
    to do. I have the following ports installed for XML docbook:
	docbook-xml-4.2_1   XML version of the DocBook DTD
	docbook-xsl-1.61.3_1 XSL DocBook stylesheets
	libxml2-2.5.10      Xml parser library for GNOME
	libxslt-1.0.32      The XSLT C library for GNOME
	sdocbook-xml-4.1.2.5_1 "Simplified" DocBook XML DTD
	xmlcatmgr-0.2_1     SGML/XML catalog manager
    You can portinstall(1) them in the order libxml2, libxslt, docbook-xml,
    docbook-xsl. The remaining two get pulled in automatically. Once this is 
    done, you should have an executable /usr/local/bin/xsltproc and
    directories /usr/local/share/xml and xsl.
@elsif os.name == "SuSE":
    (see also the "else:" branch below)
    You can make do with the following 4 rpms for xml and 
    xsl processing: libxml2-2.5.8-8, libxml2-devel-2.5.8-8,
    libxslt-1.0.31-7, libxslt-devel-1.0.31-7. They might be standard
    with some SuSE releases. They can certainly be fetched from
    SuSE's site. The docbook DTD and stylesheets are also available
    as rpm's, I found them on rpmfind.net as:
ftp://fr.rpmfind.net/linux/SuSE-Linux/i386/8.2/suse/src/docbook_4-4.2-214.src.rpm
ftp://fr.rpmfind.net/linux/SuSE-Linux/i386/8.2/suse/src/docbook-xsl-stylesheets-1.60.1-22.src.rpm
    also, it turns out that "Docbook: The Definitive Guide" is
    available as an rpm by itself, at
ftp://fr.rpmfind.net/linux/SuSE-Linux/i386/8.2/suse/noarch/docbook-tdg-2.0.6-75.noarch.rpm
    I imagine that after installing all that, you'll have a working xsltproc
    and the stylesheets installed somewhere - probably /usr/share, but you can
    use 'find / -name chunk.xsl' to find out where exactly.
@else:
    I'm utterly unfamiliar with how your system might package software.
    If you need all the details, see http://www.sagehill.net/docbookxsl/ .
    You will need four (4) things:
	libxml2 - the xml library
	libxslt - the stylesheet processor
	docbook-xml - docbook definition in xml
	docbook-xsl - stylesheets for docbook
    These may be obtained from (when the sites are not down due to
    patents interfering with the basic operation of the web):
	http://www.xmlsoft.org/index.html
	http://xmlsoft.org/XSLT/index.html
	http://www.docbook.org/xml/index.html
	http://eu.dl.sourceforge.net/docbook-xsl/
    Actually, this can be far more specific: get the files
ftp://ftp.gnome.org/pub/GNOME/sources/libxml2/2.5/libxml2-2.5.10.tar.gz
ftp://ftp.gnome.org/pub/GNOME/sources/libxslt/1.0/libxslt-1.0.32.tar.gz
http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip
http://belnet.dl.sourceforge.net/sourceforge/docbook/docbook-xsl-1.62.0.tar.gz
    You will need to install all four of these; the first two are configure
    -and- make - style applications, the latter are zipfiles you will need
    to unpack somewhere. I think it's best to try to copy the /usr/local/share
    setup of FreeBSD, though you may of course install it anywhere you like.

# Common part
Assuming you have got everything installed, the attached main.aap belongs in 
the doc/ directory. You may need to change XMLdir, XSLdir, and possibly even 
xsltproc if it is not in your path in the recipe. It also adds a workaround 
if you do not have "links" installed, which is a HTML-to-text converter tool.

The new recipe does not generate pdf. I know generating pdf is possible and 
straightforward, but I haven't talked to the right people yet as to how to do 
it. 

The new recipe generates differently-named HTML files than the previous one. I 
don't know if that can be remedied. The files might not match the previous 
division (one html file per chapter). That can be remedied with a suitable 
params.xsl file. Those remedies are beyond the scope of this paper, though.

-- 
pub  1024D/FEA2A3FE 2002-06-18 Adriaan de Groot <[email protected]>
     Key fingerprint = 934E 31AA 80A7 723F 54F9  50ED 76AC EE01 FEA2 A3FE

# A-A-P recipe for generating HTML files from the DocBook documentation.
#
# To use this you must install "jade" and various docbook files.
# This is different for every platform...

# List of the edited files.  There is no list of HTML files, since these are
# generated and their names can change.
DocSource =
	exec.sgml
	`glob("tutor*.sgml")`
	`glob("user*.sgml")`
	`glob("ref*.sgml")`
	license.sgml
	copyright.sgml
_top.DocDistFiles = $DocSource version.sgml aap.mod

links = `program_path('links')`
@if not links:
    :print "links" not found, adding workaround
    links = echo

XMLdir = /usr/local/share/xml
XSLdir = /usr/local/share/xsl

xsltproc = `program_path('xsltproc')`
@if not xsltproc:
    :print "xsltproc" not found, no output can be generated
    @raise UserError, 'No "xsltproc"'

# Only produce HTML when no target specified.
all: index.html

index.html {signfile = mysign} exec.html exec.txt : $_top.DocDistFiles
    # delete the old HTML files
    :del {force} *.html

    # generate the single big HTML file
    :sys SGML_CATALOG_FILES=$XMLdir/docbook/4.2/docbook.cat
	 xsltproc --catalogs $XSLdir/docbook/html/onechunk.xsl exec.sgml
    :move index.html exec.html

    # generate the separate HTML files
    :sys SGML_CATALOG_FILES=$XMLdir/docbook/4.2/docbook.cat
	 xsltproc --catalogs $XSLdir/docbook/html/chunk.xsl exec.sgml

    # Change a few things in the HTML code:
    # - Rename "book1.html" to "index.html".
    # - Rename the "Home" link at the bottom to "Contents".
    # - Turn the book title into a link to the index page.
    # - Add a link to the A-A-P home page in the left upper corner.
    @for fname in glob("*.html"):
	@if fname != "exec.html":
	   :cat $fname
		| :eval re.sub("book1.html", "index.html", stdin)
		| :eval re.sub(">Home</A", ">Contents</A", stdin)
		| :eval re.sub(">A-A-P Recipe Executive</TH", '><a href="index.html">A-A-P Recipe Executive</a></TH', stdin, 1)
		| :eval re.sub('COLSPAN="3"', 'nowrap><a href="http://www.a-a-p.org">A-A-P home page</a></TH><TH COLSPAN="2"', stdin, 1)
		>! $fname

    # convert the single HTML file to plain text
    :sys $links -dump exec.html >exec.txt


# Generate the version.sgml file, containing the date and version numbers
version.sgml {signfile = mysign} : $DocSource
    :print Generating $target
    :syseval ../aap --version |
	:eval re.sub('.* version ', '', stdin) |
	:eval re.sub(';.*\\s*', '', stdin) |
	:assign aapversion
    :print >! $target $lt!-- vim: set ft=dtd:
    :print >> $target THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
    :print >> $target --$gt
    :print >> $target $lt!ENTITY builddate "$DATESTR"$gt
    :print >> $target $lt!ENTITY aapversion "$aapversion"$gt

# vim: set sw=4 sts=4: