Metadocumentation: documentation for generating SBCL's Documentation

Overview
========

SBCL's documentation is written in XML DocBook which is a semantically
marked document not meant for humans to read directly. Rather, a
DocBook file is meant to be transformed into presentation formats such
as HTML, PDF, and plain text. To perform such translation, you'll need
tools beyond what is included in the SBCL distribution:

1) To verify the correctness of the XML documentation, you'll need the
DocBook DTD files and an XML verification tool.

2) To transform the main XML DocBook file (user-manual.xml), you need
an XSL Transformer and the Docbook XSL Stylesheets. The stylesheets
provide output in HTML, XHTML, and FO (formatted objects) formats.

3) If you want to create PDF or Postscript output, you'll need an FO
processor.

Catalog Files
=============

Catalog files are used to map URLs used in the SBCL Docbook and
stylesheet files into local file names. By using a catalog, processing
is faster and a network connection is not necessary. Catalog files are
specific to an operating system since they embed file locations. The
SBCL Makefile attempts to determine the correct catalog for your
system. If SBCL does not supply a catalog for your system, processing
the DocBook files will require a network connection.

Default Processing
==================

A shell script (make-doc.sh) is provided which creates the default
HTML documentation. This shell scripts invokes the GNU make tool to
create the HTML target. The Makefile assumes the existance of a
standard set of tools: the xsltproc XSL transformer and, ideally, the
DocBook XML DTDs and XSL stylesheets.

Tools for Debian
----------------
  You will the below binary packages, and their dependencies, installed.
    xsltproc (XSLT engine)
    docbook-xml (XML DTDs)
    docbook-xsl (stylesheets)
    libxml2-utils (provides the xmllint verifier) [optional]
    libfop-java (provides a FO processor for generating PDF output) [optiona]

  The easiest way to do this is with the command:
    apt-get install xsltproc docbook-xsl docbook-xml libxml2-utils libfop-java

Tools for SuSE
--------------
  You will the below binary packages, and their dependencies, installed.
    libxslt (xsltproc)
    docbook_4 (XML DTDs)
    docbook-xsl-stylesheets (stylesheets)
    libxml2 (xmllint) [optional]  

Tools for Fink
--------------
   libxslt (xsltproc)
   docbook-dtd (XML DTDs)
   docbook-xsl (stylesheets)
   libxml2-bin (xmllint) [optional]
       
  The easiest way to do this is with the command:
    fink install libxslt docbook-dtd docbook-xsl libxml2-bin

Tools Web Home
--------------
xsltproc     http://xmlsoft.org/XSLT/
DocBook DTD  http://www.docbook.org/xml/
DocBook XSL  http://sourceforge.net/projects/docbook
xmllint      http://xmlsoft.org/
FOP          http://xml.apache.org/fop/