X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;f=doc%2FDOCDOC;h=465f1f371be6f4405a68c87c160da45474377566;hb=4f45338a22a0206247251a73b7468b5c98c5aa28;hp=803aa1af08f351d495b3e1108ed8a69b1b5bcf59;hpb=d1b34780e8c44ecf1034aa30d4f2c0e2c492ca7a;p=sbcl.git

diff --git a/doc/DOCDOC b/doc/DOCDOC
index 803aa1a..465f1f3 100644
--- a/doc/DOCDOC
+++ b/doc/DOCDOC
@@ -1,13 +1,78 @@
-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 configuration 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 RedHat as of sbcl-0.8.6.1 -- you might
-    need to add such a configuration yourself.)
+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/