Fix non-EVENTS build

[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."
 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


@@ -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.
 
 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
 
 
 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
 
 
 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