Add the documentation.

9 files changed, 491 insertions, 0 deletions

diff --git a/doc/asciidoc/docbook-xsl/asciidoc-docbook-xsl.txt b/doc/asciidoc/docbook-xsl/asciidoc-docbook-xsl.txt
new file mode 100644
index 0000000..fd71e63
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/asciidoc-docbook-xsl.txt
@@ -0,0 +1,65 @@
+AsciiDoc DocBook XSL Stylesheets Notes
+======================================
+
+Output file customisation is achieved by tweaking the DocBook XSL
+stylesheets.  I've tried to keep customization to a minimum and
+confine it to the separate XSL driver files in the distribution
+`./docbook-xsl/` directory (see the User Guide for details).
+
+To polish some rough edges I've written some patches for the DocBook
+XSL stylesheets -- you don't need them but they're documented below
+and included in the distribution `./docbook-xsl/` directory.
+
+
+Manually upgrading Debian to the latest DocBook XSL stylesheets
+---------------------------------------------------------------
+The DocBook XSL Stylesheets distribution is just a directory full of
+text files and you can switch between releases by changing the
+directory name in the system XML catalog.
+
+To upgrade to the latest docbook-xsl stylesheets without having to
+wait for the Debian `docbook-xsl` package:
+
+- Download the latest docbook-xsl tarball from
+  http://sourceforge.net/projects/docbook/. Bleeding edge snapshots
+  can be found at http://docbook.sourceforge.net/snapshots/
+
+- Unzip the tarball to `/usr/share/xml/docbook/stylesheet/`:
+
+  $ cd /usr/share/xml/docbook/stylesheet
+  $ sudo tar -xzf /tmp/docbook-xsl-1.72.0.tar.gz
+
+- Edit `/etc/xml/docbook-xsl.xml` catalog and replace occurences of
+  the current stylesheets directory with the new one (in our example
+  it would be `/usr/share/xml/docbook/stylesheet/docbook-xsl-1.72.0`.
+
+  $ cd /etc/xml/
+  $ sudo cp -p docbook-xsl.xml docbook-xsl.xml.ORIG
+  $ sudo vi docbook-xsl.xml
+
+
+Customizing Generated Text
+--------------------------
+An example
+http://www.sagehill.net/docbookxsl/CustomGentext.html#CustomGenText[DocBook
+XSL Stylesheets customization file] for formatting chapter titles
+without chapter numbering.
+
+.custom-chapter.xml
+---------------------------------------------------------------------
+<!-- Customize chapter title -->
+<l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
+  <l:l10n language="en">
+    <l:context name="title">
+      <l:template name="chapter" text="%t"/>
+    </l:context>
+  </l:l10n>
+</l:i18n>
+---------------------------------------------------------------------
+
+Executed with this 'xsltproc' parameter:
+
+  --param local.l10n.xml document\(\'custom-chapter.xml\'\)
+
+NOTE: This example is hypothetical -- use the 'xsltproc'
+`--stringparam chapter.autolabel 0` option to do the same job.
diff --git a/doc/asciidoc/docbook-xsl/chunked.xsl b/doc/asciidoc/docbook-xsl/chunked.xsl
new file mode 100644
index 0000000..aafcca0
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/chunked.xsl
@@ -0,0 +1,17 @@
+<!--
+  Generates chunked XHTML documents from DocBook XML source using DocBook XSL
+  stylesheets.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"/>
+<xsl:import href="common.xsl"/>
+<xsl:param name="navig.graphics.path">images/icons/</xsl:param>
+<xsl:param name="admon.graphics.path">images/icons/</xsl:param>
+<xsl:param name="callout.graphics.path" select="'images/icons/callouts/'"/>
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/common.xsl b/doc/asciidoc/docbook-xsl/common.xsl
new file mode 100644
index 0000000..2e5cbc2
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/common.xsl
@@ -0,0 +1,106 @@
+<!--
+  Inlcuded in xhtml.xsl, xhtml.chunked.xsl, htmlhelp.xsl.
+  Contains common XSL stylesheets parameters.
+  Output documents styled by docbook.css.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:param name="html.stylesheet" select="'docbook-xsl.css'"/>
+
+<xsl:param name="htmlhelp.chm" select="'htmlhelp.chm'"/>
+<xsl:param name="htmlhelp.hhc.section.depth" select="5"/>
+
+<xsl:param name="section.autolabel">
+  <xsl:choose>
+    <xsl:when test="/processing-instruction('asciidoc-numbered')">1</xsl:when>
+    <xsl:otherwise>0</xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+
+<xsl:param name="suppress.navigation" select="0"/>
+<xsl:param name="navig.graphics.extension" select="'.png'"/>
+<xsl:param name="navig.graphics" select="0"/>
+<xsl:param name="navig.graphics.path">images/icons/</xsl:param>
+<xsl:param name="navig.showtitles">0</xsl:param>
+
+<xsl:param name="shade.verbatim" select="0"/>
+<xsl:attribute-set name="shade.verbatim.style">
+  <xsl:attribute name="border">0</xsl:attribute>
+  <xsl:attribute name="background-color">#E0E0E0</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:param name="admon.graphics" select="1"/>
+<xsl:param name="admon.graphics.path">images/icons/</xsl:param>
+<xsl:param name="admon.graphics.extension" select="'.png'"/>
+<xsl:param name="admon.style">
+  <xsl:text>margin-left: 0; margin-right: 10%;</xsl:text>
+</xsl:param>
+<xsl:param name="admon.textlabel" select="1"/>
+
+<xsl:param name="callout.defaultcolumn" select="'60'"/>
+<xsl:param name="callout.graphics.extension" select="'.png'"/>
+<xsl:param name="callout.graphics" select="'1'"/>
+<xsl:param name="callout.graphics.number.limit" select="'10'"/>
+<xsl:param name="callout.graphics.path" select="'images/icons/callouts/'"/>
+<xsl:param name="callout.list.table" select="'1'"/>
+
+<!-- This does not seem to work. -->
+<xsl:param name="section.autolabel.max.depth" select="2"/>
+
+<xsl:param name="chunk.first.sections" select="1"/>
+<xsl:param name="chunk.section.depth" select="1"/>
+<xsl:param name="chunk.quietly" select="0"/>
+<xsl:param name="chunk.toc" select="''"/>
+<xsl:param name="chunk.tocs.and.lots" select="0"/>
+
+<xsl:param name="html.cellpadding" select="'4px'"/>
+<xsl:param name="html.cellspacing" select="''"/>
+
+<xsl:param name="table.borders.with.css" select="1"/>
+<xsl:param name="table.cell.border.color" select="'#527bbd'"/>
+
+<xsl:param name="table.cell.border.style" select="'solid'"/>
+<xsl:param name="table.cell.border.thickness" select="'1px'"/>
+<xsl:param name="table.footnote.number.format" select="'a'"/>
+<xsl:param name="table.footnote.number.symbols" select="''"/>
+<xsl:param name="table.frame.border.color" select="'#527bbd'"/>
+<xsl:param name="table.frame.border.style" select="'solid'"/>
+<xsl:param name="table.frame.border.thickness" select="'3px'"/>
+<xsl:param name="tablecolumns.extension" select="'1'"/>
+
+<xsl:param name="highlight.source" select="1"/>
+
+<xsl:param name="section.label.includes.component.label" select="1"/>
+
+<!--
+  Table of contents inserted by <?asciidoc-toc?> processing instruction.
+-->
+<xsl:param name="generate.toc">
+  <xsl:choose>
+    <xsl:when test="/processing-instruction('asciidoc-toc')">
+article toc,title
+book    toc,title,figure,table,example,equation
+      <!-- The only way I could find that suppressed book chapter TOCs -->
+      <xsl:if test="$generate.section.toc.level != 0">
+chapter   toc,title
+part      toc,title
+preface   toc,title
+qandadiv  toc
+qandaset  toc
+reference toc,title
+sect1     toc
+sect2     toc
+sect3     toc
+sect4     toc
+sect5     toc
+section   toc
+set       toc,title
+      </xsl:if>
+    </xsl:when>
+    <xsl:otherwise>
+article nop
+book    nop
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/epub.xsl b/doc/asciidoc/docbook-xsl/epub.xsl
new file mode 100644
index 0000000..b15748d
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/epub.xsl
@@ -0,0 +1,35 @@
+<!--
+  Generates EPUB XHTML documents from DocBook XML source using DocBook XSL
+  stylesheets.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/epub/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+
+<!--
+DocBook XSL 1.75.2: Nav headers are invalid XHTML (table width element).
+Suppressed by default in Docbook XSL 1.76.1 epub.xsl.
+-->
+<xsl:param name="suppress.navigation" select="1"/>
+
+<!--
+DocBook XLS 1.75.2 doesn't handle TOCs
+-->
+<xsl:param name="generate.toc">
+  <xsl:choose>
+    <xsl:when test="/article">
+/article  nop
+    </xsl:when>
+    <xsl:when test="/book">
+/book  nop
+    </xsl:when>
+  </xsl:choose>
+</xsl:param>
+
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/fo.xsl b/doc/asciidoc/docbook-xsl/fo.xsl
new file mode 100644
index 0000000..5537e8e
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/fo.xsl
@@ -0,0 +1,152 @@
+<!--
+  Generates single FO document from DocBook XML source using DocBook XSL
+  stylesheets.
+
+  See xsl-stylesheets/fo/param.xsl for all parameters.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet version="1.0"
+                xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                xmlns:fo="http://www.w3.org/1999/XSL/Format">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+
+<xsl:param name="fop1.extensions" select="1" />
+<xsl:param name="variablelist.as.blocks" select="1" />
+
+<xsl:param name="paper.type" select="'A4'"/>
+<!--
+<xsl:param name="paper.type" select="'USletter'"/>
+-->
+<xsl:param name="hyphenate">false</xsl:param>
+<!-- justify, left or right -->
+<xsl:param name="alignment">left</xsl:param>
+
+<xsl:param name="body.font.family" select="'serif'"/>
+<xsl:param name="body.font.master">12</xsl:param>
+<xsl:param name="body.font.size">
+ <xsl:value-of select="$body.font.master"/><xsl:text>pt</xsl:text>
+</xsl:param>
+
+<xsl:param name="body.margin.bottom" select="'0.5in'"/>
+<xsl:param name="body.margin.top" select="'0.5in'"/>
+<xsl:param name="bridgehead.in.toc" select="0"/>
+
+<!-- overide setting in common.xsl -->
+<xsl:param name="table.frame.border.thickness" select="'2px'"/>
+
+<!-- Default fetches image from Internet (long timeouts) -->
+<xsl:param name="draft.watermark.image" select="''"/>
+
+<!-- Line break -->
+<xsl:template match="processing-instruction('asciidoc-br')">
+  <fo:block/>
+</xsl:template>
+
+<!-- Horizontal ruler -->
+<xsl:template match="processing-instruction('asciidoc-hr')">
+  <fo:block space-after="1em">
+    <fo:leader leader-pattern="rule" rule-thickness="0.5pt"  rule-style="solid" leader-length.minimum="100%"/>
+  </fo:block>
+</xsl:template>
+
+<!-- Hard page break -->
+<xsl:template match="processing-instruction('asciidoc-pagebreak')">
+   <fo:block break-after='page'/>
+</xsl:template>
+
+<!-- Sets title to body text indent -->
+<xsl:param name="body.start.indent">
+  <xsl:choose>
+    <xsl:when test="$fop.extensions != 0">0pt</xsl:when>
+    <xsl:when test="$passivetex.extensions != 0">0pt</xsl:when>
+    <xsl:otherwise>1pc</xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+<xsl:param name="title.margin.left">
+  <xsl:choose>
+    <xsl:when test="$fop.extensions != 0">-1pc</xsl:when>
+    <xsl:when test="$passivetex.extensions != 0">0pt</xsl:when>
+    <xsl:otherwise>0pt</xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+<xsl:param name="page.margin.bottom" select="'0.25in'"/>
+<xsl:param name="page.margin.inner">
+  <xsl:choose>
+    <xsl:when test="$double.sided != 0">0.75in</xsl:when>
+    <xsl:otherwise>0.75in</xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+<xsl:param name="page.margin.outer">
+  <xsl:choose>
+    <xsl:when test="$double.sided != 0">0.5in</xsl:when>
+    <xsl:otherwise>0.5in</xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+
+<xsl:param name="page.margin.top" select="'0.5in'"/>
+<xsl:param name="page.orientation" select="'portrait'"/>
+<xsl:param name="page.width">
+  <xsl:choose>
+    <xsl:when test="$page.orientation = 'portrait'">
+      <xsl:value-of select="$page.width.portrait"/>
+    </xsl:when>
+    <xsl:otherwise>
+      <xsl:value-of select="$page.height.portrait"/>
+    </xsl:otherwise>
+  </xsl:choose>
+</xsl:param>
+
+<xsl:attribute-set name="monospace.properties">
+  <xsl:attribute name="font-size">10pt</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="admonition.title.properties">
+  <xsl:attribute name="font-size">14pt</xsl:attribute>
+  <xsl:attribute name="font-weight">bold</xsl:attribute>
+  <xsl:attribute name="hyphenate">false</xsl:attribute>
+  <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:attribute-set name="sidebar.properties" use-attribute-sets="formal.object.properties">
+  <xsl:attribute name="border-style">solid</xsl:attribute>
+  <xsl:attribute name="border-width">1pt</xsl:attribute>
+  <xsl:attribute name="border-color">silver</xsl:attribute>
+  <xsl:attribute name="background-color">#ffffee</xsl:attribute>
+  <xsl:attribute name="padding-left">12pt</xsl:attribute>
+  <xsl:attribute name="padding-right">12pt</xsl:attribute>
+  <xsl:attribute name="padding-top">6pt</xsl:attribute>
+  <xsl:attribute name="padding-bottom">6pt</xsl:attribute>
+  <xsl:attribute name="margin-left">0pt</xsl:attribute>
+  <xsl:attribute name="margin-right">12pt</xsl:attribute>
+  <xsl:attribute name="margin-top">6pt</xsl:attribute>
+  <xsl:attribute name="margin-bottom">6pt</xsl:attribute>
+</xsl:attribute-set>
+
+<xsl:param name="callout.graphics" select="'1'"/>
+
+<!-- Only shade programlisting and screen verbatim elements -->
+<xsl:param name="shade.verbatim" select="1"/>
+<xsl:attribute-set name="shade.verbatim.style">
+  <xsl:attribute name="background-color">
+    <xsl:choose>
+      <xsl:when test="self::programlisting|self::screen">#E0E0E0</xsl:when>
+      <xsl:otherwise>inherit</xsl:otherwise>
+    </xsl:choose>
+  </xsl:attribute>
+</xsl:attribute-set>
+
+<!--
+  Force XSL Stylesheets 1.72 default table breaks to be the same as the current
+  version (1.74) default which (for tables) is keep-together="auto".
+-->
+<xsl:attribute-set name="table.properties">
+  <xsl:attribute name="keep-together.within-column">auto</xsl:attribute>
+</xsl:attribute-set>
+
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/htmlhelp.xsl b/doc/asciidoc/docbook-xsl/htmlhelp.xsl
new file mode 100644
index 0000000..f064c0c
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/htmlhelp.xsl
@@ -0,0 +1,16 @@
+<!--
+  Generates chunked HTML Help HTML documents from DocBook XML source using
+  DocBook XSL stylesheets.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/htmlhelp/htmlhelp.xsl"/>
+<xsl:import href="common.xsl"/>
+<xsl:param name="htmlhelp.hhp" select="'asciidoc.hhp'"/>
+<xsl:param name="suppress.navigation" select="1"/>
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/manpage.xsl b/doc/asciidoc/docbook-xsl/manpage.xsl
new file mode 100644
index 0000000..b5201a5
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/manpage.xsl
@@ -0,0 +1,31 @@
+<!--
+  Generates single roff manpage document from DocBook XML source using DocBook
+  XSL stylesheets.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+
+<!-- Only render the link text -->
+<xsl:template match="ulink">
+  <xsl:variable name="content">
+    <xsl:apply-templates/>
+  </xsl:variable>
+  <xsl:value-of select="$content"/>
+</xsl:template>
+
+<!-- Don't automatically generate the REFERENCES section -->
+<xsl:template name="endnotes.list">
+</xsl:template>
+<!-- Next entry for backward compatibility with old docbook-xsl versions -->
+<xsl:template name="format.links.list">
+</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/doc/asciidoc/docbook-xsl/text.xsl b/doc/asciidoc/docbook-xsl/text.xsl
new file mode 100644
index 0000000..566884c
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/text.xsl
@@ -0,0 +1,55 @@
+<?xml version="1.0"?>
+<!--
+  Used by AsciiDoc a2x(1) for w3m(1) based text generation.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+  <xsl:import
+    href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/>
+
+  <!-- parameters for optimal text output -->
+  <xsl:param name="callout.graphics" select="0"/>
+  <xsl:param name="callout.unicode" select="0"/>
+  <xsl:param name="section.autolabel" select="1"/>
+  <xsl:param name="section.label.includes.component.label" select="1"/>
+  <xsl:param name="generate.toc">
+  appendix  title
+  article/appendix  nop
+  article   toc,title
+  book      toc,title,figure,table,example,equation
+  chapter   title
+  part      toc,title
+  preface   toc,title
+  qandadiv  toc
+  qandaset  toc
+  reference toc,title
+  section   toc
+  set       toc,title
+  </xsl:param>
+
+  <xsl:template match="book/bookinfo/title | article/articleinfo/title" mode="titlepage.mode">
+      <hr />
+        <xsl:apply-imports/>
+      <hr />
+  </xsl:template>
+
+  <xsl:template match="book/*/title | article/*/title" mode="titlepage.mode">
+      <br /><hr />
+        <xsl:apply-imports/>
+      <hr />
+  </xsl:template>
+
+  <xsl:template match="book/chapter/*/title | article/section/*/title" mode="titlepage.mode">
+      <br />
+        <xsl:apply-imports/>
+      <hr width="100" align="left" />
+  </xsl:template>
+
+
+</xsl:stylesheet>
diff --git a/doc/asciidoc/docbook-xsl/xhtml.xsl b/doc/asciidoc/docbook-xsl/xhtml.xsl
new file mode 100644
index 0000000..cdfe27f
--- /dev/null
+++ b/doc/asciidoc/docbook-xsl/xhtml.xsl
@@ -0,0 +1,14 @@
+<!--
+  Generates single XHTML document from DocBook XML source using DocBook XSL
+  stylesheets.
+
+  NOTE: The URL reference to the current DocBook XSL stylesheets is
+  rewritten to point to the copy on the local disk drive by the XML catalog
+  rewrite directives so it doesn't need to go out to the Internet for the
+  stylesheets. This means you don't need to edit the <xsl:import> elements on
+  a machine by machine basis.
+-->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"/>
+<xsl:import href="common.xsl"/>
+</xsl:stylesheet>