X-Git-Url: http://repo.macrolet.net/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2FDOCDOC;fp=doc%2FDOCDOC;h=034f1710869034142947f47ca375f6992affe951;hb=0898da1d2bf772db65a98bfc424ef52aa150fb38;hp=1bb9f5edb3df723e84161b2a0f07d68efeeaa968;hpb=cfd322bd3d1775da08b1a42ffa7816bcd20092a8;p=sbcl.git

diff --git a/doc/DOCDOC b/doc/DOCDOC
index 1bb9f5e..034f171 100644
--- a/doc/DOCDOC
+++ b/doc/DOCDOC
@@ -1,16 +1,70 @@
-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