doc/DOCDOC

   1 Metadocumentation: documentation for generating SBCL's Documentation
   2
   3 Overview
   4 ========
   5
   6 SBCL's documentation is written in XML DocBook which is a semantically
   7 marked document not meant for humans to read directly. Rather, a
   8 DocBook file is meant to be transformed into presentation formats such
   9 as HTML, PDF, and plain text. To perform such translation, you'll need
  10 tools beyond what is included in the SBCL distribution:
  11
  12 1) To verify the correctness of the XML documentation, you'll need the
  13 DocBook DTD files and an XML verification tool.
  14
  15 2) To transform the main XML DocBook file (user-manual.xml), you need
  16 an XSL Transformer and the Docbook XSL Stylesheets. The stylesheets
  17 provide output in HTML, XHTML, and FO (formatted objects) formats.
  18
  19 3) If you want to create PDF or Postscript output, you'll need an FO
  20 processor.
  21
  22 Catalog Files
  23 =============
  24
  25 Catalog files are used to map URLs used in the SBCL Docbook and
  26 stylesheet files into local file names. By using a catalog, processing
  27 is faster and a network connection is not necessary. Catalog files are
  28 specific to an operating system since they embed file locations. The
  29 SBCL Makefile attempts to determine the correct catalog for your
  30 system. If SBCL does not supply a catalog for your system, processing
  31 the DocBook files will require a network connection.
  32
  33 Default Processing
  34 ==================
  35
  36 A shell script (make-doc.sh) is provided which creates the default
  37 HTML documentation. This shell scripts invokes the GNU make tool to
  38 create the HTML target. The Makefile assumes the existance of a
  39 standard set of tools: the xsltproc XSL transformer and, ideally, the
  40 DocBook XML DTDs and XSL stylesheets.
  41
  42 Tools for Debian
  43 ----------------
  44   You will the below binary packages, and their dependencies, installed.
  45     xsltproc (XSLT engine)
  46     docbook-xml (XML DTDs)
  47     docbook-xsl (stylesheets)
  48     libxml2-utils (provides the xmllint verifier) [optional]
  49     libfop-java (provides a FO processor for generating PDF output) [optiona]
  50
  51   The easiest way to do this is with the command:
  52     apt-get install xsltproc docbook-xsl docbook-xml libxml2-utils libfop-java
  53
  54 Tools for SuSE
  55 --------------
  56   You will the below binary packages, and their dependencies, installed.
  57     libxslt (xsltproc)
  58     docbook_4 (XML DTDs)
  59     docbook-xsl-stylesheets (stylesheets)
  60     libxml2 (xmllint) [optional]
  61
  62 Tools for Fink
  63 --------------
  64    libxslt (xsltproc)
  65    docbook-dtd (XML DTDs)
  66    docbook-xsl (stylesheets)
  67    libxml2-bin (xmllint) [optional]
  68
  69   The easiest way to do this is with the command:
  70     fink install libxslt docbook-dtd docbook-xsl libxml2-bin
  71
  72 Tools Web Home
  73 --------------
  74 xsltproc     http://xmlsoft.org/XSLT/
  75 DocBook DTD  http://www.docbook.org/xml/
  76 DocBook XSL  http://sourceforge.net/projects/docbook
  77 xmllint      http://xmlsoft.org/
  78 FOP          http://xml.apache.org/fop/