-$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."
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
. 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.
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
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
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
git://git.exim.org / users / jgh / exim.git / blobdiff