Merge branch 'master' of ssh://git.exim.org/home/git/exim

[exim.git] / doc / doc-docbook / HowItWorks.txt

diff --git a/doc/doc-docbook/HowItWorks.txt b/doc/doc-docbook/HowItWorks.txt
index fe99ff6b328a7b87c75d8d09e508b5921930757a..c5e328a09408245f464bd531e29a211ac22969f4 100644 (file)
--- a/doc/doc-docbook/HowItWorks.txt
+++ b/doc/doc-docbook/HowItWorks.txt
@@ -1,5 +1,3 @@
-$Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.9 2008/02/04 17:28:44 fanf2 Exp $
-
 CREATING THE EXIM DOCUMENTATION
 
 "You are lost in a maze of twisty little scripts."
@@ -137,10 +135,13 @@ at the time of writing):
   These are all installed on my box; I do not know which of libxml or libxml2
   the various scripts are actually using.
 
-. xsl-stylesheets-1.70.1
+. xsl-stylesheets-<version>
 
   These are the standard DocBook XSL stylesheets.
 
+  The documents use http://docbook.sourceforge.net/release/xsl/current/ which
+  should be mapped to an appropriate local path via the system catalogs.
+
 . fop 0.93
 
   FOP is a processor for "formatted objects". It is written in Java. The fop
@@ -234,6 +235,39 @@ comments in these style files to explain what changes I have made. Some of the
 changes are quite significant.
 
 
+XSL INCLUDES
+
+References to XSL paths should use the public URLs, such as:
+  http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl
+If this fails to work for you, then there is a problem with your system
+catalogs.  As a work-around, you can adjust the OS-Fixups script and then:
+$ make os-fixup
+
+As an example of how this should normally work, on a FreeBSD system the
+resolution goes to /usr/local/share/xml/catalog which contains a directive:
+  <nextCatalog catalog="/usr/local/share/xml/catalog.ports" />
+to pull in the file automatically maintained by the Ports system.  That file
+will contain:
+  <delegateSystem
+   systemIdStartString="http://docbook.sourceforge.net/release/xsl/"
+   catalog="file:///usr/local/share/xsl/docbook/catalog" />
+  <delegateURI
+   uriStartString="http://docbook.sourceforge.net/release/xsl/"
+   catalog="file:///usr/local/share/xsl/docbook/catalog" />
+and that catalog file contains:
+  <rewriteSystem
+   systemIdStartString="http://docbook.sourceforge.net/release/xsl/current"
+   rewritePrefix="file:///usr/local/share/xsl/docbook" />
+  <rewriteURI
+   uriStartString="http://docbook.sourceforge.net/release/xsl/current"
+    rewritePrefix="file:///usr/local/share/xsl/docbook" />
+and the full path is thus eventually arrived at.
+
+See also the tools:
+  xmlcatalog(1) from libxml2
+  xmlcatmgr(1) for a lightweight tool written for the NetBSD Packages system.
+
+
 THE PRE-XML SCRIPT
 
 The Pre-xml script copies a .xml file, making certain changes according to the
@@ -672,5 +706,6 @@ spec.xfpt                      xfpt source of the specification document
 x2man                          Script to make the Exim man page from the XML
 
 
-Philip Hazel
-Last updated: 31 August 2007
+(Originally, and for the most part: Philip Hazel)
+The Exim Maintainers
+Last updated: 5 July 2010