X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/e492cc8d4574fe3a0919df64346d6e91a92a7496..85e453f622a540ecc8c86b3817e8b85d8218c474:/doc/doc-docbook/HowItWorks.txt diff --git a/doc/doc-docbook/HowItWorks.txt b/doc/doc-docbook/HowItWorks.txt index a3049952a..9fd197cac 100644 --- 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- 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: + +to pull in the file automatically maintained by the Ports system. That file +will contain: + + +and that catalog file contains: + + +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