Docs: add warning note on ${listnamed:} operator

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

diff --git a/doc/doc-docbook/HowItWorks.txt b/doc/doc-docbook/HowItWorks.txt
index fe99ff6b328a7b87c75d8d09e508b5921930757a..9fd197cac9070863e51916426781f9425a8238be 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."
 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.
 
   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.
 
 
   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
 . fop 0.93
 
   FOP is a processor for "formatted objects". It is written in Java. The fop


@@ -149,7 +150,7 @@ at the time of writing):
 
 . w3m 0.5.2
 
 
 . w3m 0.5.2
 

-  This is a text-oriented web brower. It is used to produce the ASCII form of
+  This is a text-oriented web browser. It is used to produce the ASCII form of

   the Exim documentation (spec.txt) from a specially-created HTML format. It
   seems to do a better job than lynx.
 
   the Exim documentation (spec.txt) from a specially-created HTML format. It
   seems to do a better job than lynx.
 


@@ -234,6 +235,39 @@ comments in these style files to explain what changes I have made. Some of the
 changes are quite significant.
 
 
 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
 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
 
 
 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