Add --version to all installed Perl and Shell scripts.

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

diff --git a/doc/doc-docbook/HowItWorks.txt b/doc/doc-docbook/HowItWorks.txt
index a3049952a112338522856e688af95d58939f855e..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.8 2007/08/31 09:13:40 ph10 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
@@ -149,7 +150,7 @@ at the time of writing):
 
 . 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.
 
@@ -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
@@ -505,14 +539,13 @@ preceded by an extra two blank lines and a line of equals characters. An extra
 newline is inserted before each section heading, and they are underlined with
 hyphens.
 
-August 2007: A further feature has been added to Tidytxt. The current version
-of xmlto makes HTML that contains non-ASCII Unicode characters. Fortunately,
-they are few. The heading uses "box drawing" characters in the range U+2500 to
-U+253F, and within the main text, U+00A0 (hard space) occasionally appears. The
-Tidytxt script now turns all the former into hyphens and the latter into normal
-spaces. Bullets, which are set as U+25CF, are turned into asterisks. (It might
-be possible to do all this in the same way as I dealt with copyright - see
-above - but adding three lines of Perl to an existing script was a lot easier.)
+The output of xmlto also contains non-ASCII Unicode characters that w3m passes
+through. Fortunately, they are few, and Tidytxt cleans them up as well. Some
+headings use "box drawing" characters in the range U+2500 to U+253F which are
+translated into -+| as appropriate, and U+00A0 (hard space) and U+25CF (bullet)
+are translated into plain spaces and asterisks. (It might be possible to do all
+this in the same way as I dealt with copyright - see above - but adding a few
+lines of Perl to an existing script was a lot easier.)
 
 
 CREATING INFO FILES
@@ -673,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