*** *** README for A-A-P's doc/ directory *** This file consists of two parts: a description of how to install the XML docbook tools, which you will need to process the documentation, and a section describing how A-A-P's documentation uses the docbook tags. This is what you can do: aap html - generates all html docs, requires the XML docbook tools aap txt - generates txt doc, requires links or lynx as well aap pdf - generates pdf doc, requires htmldoc as well *** *** Installing the XML docbook tools *** @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 everything installed, you should be able to run "xsltproc" and have it return its usage information. You may need to change XMLdir and XSLdir in the main.aap recipe to reflect where you have installed the files. If you do so, chunk.xsl and onechunk.xsl will be generated again, since they contain hard-coded paths and will be re-generated when you use the recipe. *** *** Installing other tools *** To produce the HTML, PDF and text files from the docbook sources you need to install various tools. Here are a few hints. htmldoc See http://www.easysw.com/htmldoc links Only old versions support the "-dump" argument, thus if you don't already have links you probably don't want to bother with it. lynx See http://lynx.isc.org *** *** Tagging conventions used in the Aap docbook documentation: *** Filenames and paths: main.aap Shell commands: aap install What the user has to type something at a prompt: yes Aap command names: :conf Example recipes. Note that the must be in the first column to avoid a blank line at the end. Listing of shell commands and their output. Note that a line break causes an empty line, thus use it like this: this is the first line this is the second line this is the last line Other conventions: - Program listings are indented 4 spaces and line-numbered (if needed) with just numbers (no dots). - Aap commands as examples in running text get double quotes: ":do compile $source" - Variable names get $, no markup vim: set tw=72: