***
*** 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:
***

<filename>	Filenames and paths: <filename>main.aap</filename>

<command>	Shell commands: <command>aap install</command>

<userinput>	What the user has to type something at a prompt:
		<userinput>yes</userinput>

<link>		Aap command names: <link linkend="cmd-conf">:conf</link>

<programlisting>
		Example recipes.
		Note that the </programlisting> must be in the first
		column to avoid a blank line at the end.

<literallayout>
		Listing of shell commands and their output.
		Note that a line break causes an empty line, thus use it
		like this:
			<literallayout>   this is the first line
			this is the second line
			this is the last line </literallayout>


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:
