-metadocumentation: hints for how to set things up so that the
-documentation gets processed correctly
-
-WHN's approach:
- * (starting from Debian 3.0r1, in a configuration where
- openjade-based toolchain for SGML DocBook was already present)
- * Use dselect to install everything plausible-looking which matches
- the search string 'xsl': docbook-xsl, xsltproc, libxslt1.
- * (Now things work. This is probably in part because Kevin Rosenberg
- already set up a suitable Debian catalog in the CVS files,
- so if you're on a system where there hasn't been done already -- i.e.
- system other than Debian or SuSE as of sbcl-0.8.6.1 -- you might
- need to add such a catalog file yourself. The catalog file is used
- to translate the URLs in the .xml and .xsl into local files. However,
- xsltproc should work fine and download the remote files if a catalog
- is no present on your system.)
+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 reading. 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 tools.
+
+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 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 connections.
+
+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
projects / sbcl.git / commitdiff