Do not refer to TRUSTED_CONFIG_PREFIX_FILE.
[users/heiko/exim.git] / doc / doc-docbook / HowItWorks.txt
1 $Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.9 2008/02/04 17:28:44 fanf2 Exp $
2
3 CREATING THE EXIM DOCUMENTATION
4
5 "You are lost in a maze of twisty little scripts."
6
7
8 This document describes how the various versions of the Exim documentation, in
9 different output formats, are created from DocBook XML, and also how the
10 DocBook XML is itself created.
11
12
13 BACKGROUND: THE OLD WAY
14
15 From the start of Exim, in 1995, the specification was written in a local text
16 formatting system known as SGCAL. This is capable of producing PostScript and
17 plain text output from the same source file. Later, when the "ps2pdf" command
18 became available with GhostScript, that was used to create a PDF version from
19 the PostScript. (A few earlier versions were created by a helpful user who had
20 bought the Adobe distiller software.)
21
22 A demand for a version in "info" format led me to write a Perl script that
23 converted the SGCAL input into a Texinfo file. Because of the somewhat
24 restrictive requirements of Texinfo, this script always needed a lot of
25 maintenance, and was never totally satisfactory.
26
27 The HTML version of the documentation was originally produced from the Texinfo
28 version, but later I wrote another Perl script that produced it directly from
29 the SGCAL input, which made it possible to produce better HTML.
30
31 There were a small number of diagrams in the documentation. For the PostScript
32 and PDF versions, these were created using Aspic, a local text-driven drawing
33 program that interfaces directly to SGCAL. For the text and texinfo versions,
34 alternative ascii-art diagrams were used. For the HTML version, screen shots of
35 the PostScript output were turned into gifs.
36
37
38 A MORE STANDARD APPROACH
39
40 Although in principle SGCAL and Aspic could be generally released, they would
41 be unlikely to receive much (if any) maintenance, especially after I retire.
42 Furthermore, the old production method was only semi-automatic; I still did a
43 certain amount of hand tweaking of spec.txt, for example. As the maintenance of
44 Exim itself was being opened up to a larger group of people, it seemed sensible
45 to move to a more standard way of producing the documentation, preferable fully
46 automated. However, we wanted to use only non-commercial software to do this.
47
48 At the time I was thinking about converting (early 2005), the "obvious"
49 standard format in which to keep the documentation was DocBook XML. The use of
50 XML in general, in many different applications, was increasing rapidly, and it
51 seemed likely to remain a standard for some time to come. DocBook offered a
52 particular form of XML suited to documents that were effectively "books".
53
54 Maintaining an XML document by hand editing is a tedious, verbose, and
55 error-prone process. A number of specialized XML text editors were available,
56 but all the free ones were at a very primitive stage. I therefore decided to
57 keep the master source in AsciiDoc format, from which a secondary XML master
58 could be automatically generated.
59
60 The first "new" versions of the documents, for the 4.60 release, were generated
61 this way. However, there were a number of problems with using AsciiDoc for a
62 document as large and as complex as the Exim manual. As a result, I wrote a new
63 application called xfpt ("XML From Plain Text") which creates XML from a
64 relatively simple and consistent markup language. This application has been
65 released for general use, and the master sources for the Exim documentation are
66 now in xfpt format.
67
68 All the output formats are generated from the XML file. If, in the future, a
69 better way of maintaining the XML source becomes available, this can be adopted
70 without changing any of the processing that produces the output documents.
71 Equally, if better ways of processing the XML become available, they can be
72 adopted without affecting the source maintenance.
73
74 A number of issues arose while setting this all up, which are best summed up by
75 the statement that a lot of the technology was (in 2006) still very immature.
76 Trying to do this conversion any earlier would probably not have been anywhere
77 near as successful. The main issues that bother me in the XML-generated
78 documentation are described in the penultimate section of this document.
79
80 Initially, the major problems were in producing PostScript and PDF outputs. The
81 available free software for doing this was and still is (we are now in 2007)
82 cumbersome and slow, and does not support certain output features that I would
83 like. My response to this was, over a period of two years, to write an XML
84 processor called SDoP (Simple DocBook Processor). This program reads DocBook
85 XML and writes PostScript, without using any of the heavyweight apparatus that
86 is required for xmlto and fop (the previously used software).
87
88 An experimental first version of SDoP was used for the Exim 4.67
89 documentation. Subsequently SDoP was released for general use. SDoP's output
90 includes features that are missing when xmlto/fop is used, and it also runs
91 about 60 times faster. The main manual can be formatted in 2.5 seconds instead
92 of 2.5 minutes, which makes checking and fixing mistakes much easier.
93
94 The Makefile that is used to build the various forms of output will, for the
95 moment, support both ways of producing PostScript and PDF output, though the
96 default is now to use SDoP.
97
98 The following sections describe the processes by which the xfpt files are
99 transformed into the final output documents. In practice, the details are coded
100 into a Makefile that specifies the chain of commands for each output format.
101
102
103 REQUIRED SOFTWARE
104
105 Installing software to process XML puts lots and lots of stuff on your box. I
106 run Gentoo Linux, and a lot of things have been installed as dependencies that
107 I am not fully aware of. This is what I know about (version numbers are current
108 at the time of writing):
109
110 . xfpt 0.03
111
112   This converts the master source file into a DocBook XML file.
113
114 . sdop 0.03
115
116   This is my new DocBook-to-PostScript processor.
117
118 . ps2pdf
119
120   This is a wrapper script that is part of the GhostScript distribution. It
121   converts a PostScript file into a PDF file. It is used to process the output
122   from SDoP. It is not required when xmlto/fop is being used to generate PDF
123   output.
124
125 . xmlto 0.0.18
126
127   This is a shell script that drives various XML processors. It is used to
128   produce "formatted objects" when PostScript and PDF output is being generated
129   using fop (the old way) rather than SDoP. It is always used to produce HTML
130   output. It uses xsltproc, libxml, libxslt, libexslt, and possibly other
131   things that I have not figured out, to apply the DocBook XSLT stylesheets.
132
133 . libxml 1.8.17
134   libxml2 2.6.28
135   libxslt 1.1.20
136
137   These are all installed on my box; I do not know which of libxml or libxml2
138   the various scripts are actually using.
139
140 . xsl-stylesheets-<version>
141
142   These are the standard DocBook XSL stylesheets.
143
144   The documents use http://docbook.sourceforge.net/release/xsl/current/ which
145   should be mapped to an appropriate local path via the system catalogs.
146
147 . fop 0.93
148
149   FOP is a processor for "formatted objects". It is written in Java. The fop
150   command is a shell script that drives it. It required only if you do not
151   want to use SDoP and ps2pdf to generate PostScript and PDF output.
152
153 . w3m 0.5.2
154
155   This is a text-oriented web brower. It is used to produce the ASCII form of
156   the Exim documentation (spec.txt) from a specially-created HTML format. It
157   seems to do a better job than lynx.
158
159 . docbook2texi (part of docbook2X 0.8.5)
160
161   This is a wrapper script for a two-stage conversion process from DocBook to a
162   Texinfo file. It uses db2x_xsltproc and db2x_texixml. Unfortunately, there
163   are two versions of this command; the old one is based on an earlier fork of
164   docbook2X and does not work.
165
166 . db2x_xsltproc and db2x_texixml (part of docbook2X 0.8.5)
167
168   More wrapping scripts (see previous item).
169
170 . makeinfo 4.8
171
172   This is used to make an "info" file from a Texinfo file.
173
174 In addition, there are a number of locally written Perl scripts. These are
175 described below.
176
177
178 THE MAKEFILE
179
180 The makefile supports a number of targets of the form x.y, where x is one of
181 "filter", "spec", or "test", and y is one of "xml", "fo", "ps", "pdf", "html",
182 "txt", or "info". The intermediate targets "x.xml" and "x.fo" are provided for
183 testing purposes. The other five targets are production targets. For example:
184
185   make spec.pdf
186
187 This runs the necessary tools in order to create the file spec.pdf from the
188 original source spec.xfpt. A number of intermediate files are created during
189 this process, including the master DocBook source, called spec.xml. Of course,
190 the usual features of "make" ensure that if this already exists and is
191 up-to-date, it is not needlessly rebuilt.
192
193 Because there are now two ways of creating the PostScript and PDF outputs,
194 there are two targets for each one. For example fop-spec.ps makes PostScript
195 using fop, and sdop-spec.ps makes it using SDoP. The generic targets spec.ps
196 and spec.pdf now point to the SDoP versions.
197
198 The "test" series of targets were created so that small tests could easily be
199 run fairly quickly, because processing even the shortish XML document takes
200 a bit of time, and processing the main specification takes ages -- except when
201 using SDoP for PostScript and PDF.
202
203 Another target is "exim.8". This runs a locally written Perl script called
204 x2man, which extracts the list of command line options from the spec.xml file,
205 and creates a man page. There are some XML comments in the spec.xml file to
206 enable the script to find the start and end of the options list.
207
208 There is also a "clean" target that deletes all the generated files.
209
210
211 CREATING DOCBOOK XML FROM XFPT INPUT
212
213 The small amount of local configuration for xfpt is included at the start of
214 the two .xfpt files; there are no separate local xfpt configuration files.
215 Running the xfpt command creates a .xml file from a .xfpt file. When this
216 succeeds, there is no output.
217
218
219 DOCBOOK PROCESSING
220
221 Processing a .xml file into the five different output formats is not entirely
222 straightforward. For a start, the same XML is not suitable for all the
223 different output styles. When the final output is in a text format (.txt,
224 .texinfo) for instance, all non-ASCII characters in the input must be converted
225 to ASCII transliterations because the current processing tools do not do this
226 correctly automatically.
227
228 In order to cope with these issues in a flexible way, a Perl script called
229 Pre-xml was written. This is used to preprocess the .xml files before they are
230 handed to the main processors. Adding one more tool onto the front of the
231 processing chain does at least seem to be in the spirit of XML processing.
232
233 The XML processors other than SDoP make use of style files, which can be
234 overridden by local versions. There is one that applies to all styles, called
235 MyStyle.xsl, and others for the different output formats. I have included
236 comments in these style files to explain what changes I have made. Some of the
237 changes are quite significant.
238
239
240 XSL INCLUDES
241
242 References to XSL paths should use the public URLs, such as:
243   http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl
244 If this fails to work for you, then there is a problem with your system
245 catalogs.  As a work-around, you can adjust the OS-Fixups script and then:
246 $ make os-fixup
247
248 As an example of how this should normally work, on a FreeBSD system the
249 resolution goes to /usr/local/share/xml/catalog which contains a directive:
250   <nextCatalog catalog="/usr/local/share/xml/catalog.ports" />
251 to pull in the file automatically maintained by the Ports system.  That file
252 will contain:
253   <delegateSystem
254    systemIdStartString="http://docbook.sourceforge.net/release/xsl/"
255    catalog="file:///usr/local/share/xsl/docbook/catalog" />
256   <delegateURI
257    uriStartString="http://docbook.sourceforge.net/release/xsl/"
258    catalog="file:///usr/local/share/xsl/docbook/catalog" />
259 and that catalog file contains:
260   <rewriteSystem
261    systemIdStartString="http://docbook.sourceforge.net/release/xsl/current"
262    rewritePrefix="file:///usr/local/share/xsl/docbook" />
263   <rewriteURI
264    uriStartString="http://docbook.sourceforge.net/release/xsl/current"
265     rewritePrefix="file:///usr/local/share/xsl/docbook" />
266 and the full path is thus eventually arrived at.
267
268 See also the tools:
269   xmlcatalog(1) from libxml2
270   xmlcatmgr(1) for a lightweight tool written for the NetBSD Packages system.
271
272
273 THE PRE-XML SCRIPT
274
275 The Pre-xml script copies a .xml file, making certain changes according to the
276 options it is given. The currently available options are as follows:
277
278 -ascii
279
280   This option is used for ASCII output formats. It makes the following
281   character replacements:
282
283     &#x2019;  =>  '         apostrophe
284     &copy;    =>  (c)       copyright
285     &dagger;  =>  *         dagger
286     &Dagger;  =>  **        double dagger
287     &nbsp;    =>  a space   hard space
288     &ndash;   =>  -         en dash
289
290   The apostrophe is specified numerically because that is what xfpt generates
291   from an ASCII single quote character. Non-ASCII characters that are not in
292   this list should not be used without thinking about how they might be
293   converted for the ASCII formats.
294
295   In addition to the character replacements, this option causes quotes to be
296   put round <literal> text items, and <quote> and </quote> to be replaced by
297   ASCII quote marks. You would think the stylesheet would cope with the latter,
298   but it seems to generate non-ASCII characters that w3m then turns into
299   question marks.
300
301 -bookinfo
302
303   This option causes the <bookinfo> element to be removed from the XML. It is
304   used for the PostScript/PDF forms of the filter document, in order to avoid
305   the generation of a full title page.
306
307 -fi
308
309   Replace any occurrence of "fi" by the ligature &#xFB01; except when it is
310   inside an XML element, or inside a <literal> part of the text.
311
312   The use of ligatures would be nice for the PostScript and PDF formats. Sadly,
313   it turns out that fop cannot at present handle the FB01 character correctly.
314   Happily this problem is now avoided when SDoP is used to generate PostScript
315   (and thence PDF) because SDoP automatically uses an "fi" ligature for
316   non-fixed-width fonts.
317
318   The only xmlto format that handles FB01 is the HTML format, but when I used
319   this in the test version, people complained that it made searching for words
320   difficult. So this option is in practice not used at all.
321
322 -noindex
323
324   Remove the XML to generate a Concept Index and an Options index. The source
325   document has three types of index entry, for variables, options, and concept
326   indexes. However, no index is required for the .txt and .texinfo outputs.
327
328 -oneindex
329
330   Remove the XML to generate separate variables, options, and concept indexes,
331   and add XML to generate a single index. The only output processors that
332   support multiple indexes are SDoP and the processor that produces "formatted
333   objects" for PostScript and PDF output for fop. The HTML processor ignores
334   the XML settings for multiple indexes and just makes one unified index.
335   Specifying three indexes gets you three copies of the same index, so this has
336   to be changed.
337
338 -optbreak
339
340   Look for items of the form <option>...</option> and <varname>...</varname> in
341   ordinary paragraphs, and insert &#x200B; after each underscore in the
342   enclosed text. The same is done for any word containing four or more upper
343   case letters (compile-time options in the Exim specification). The character
344   &#x200B; is a zero-width space. This means that the line may be split after
345   one of these underscores, but no hyphen is inserted.
346
347
348 CREATING POSTSCRIPT AND PDF
349
350 These two output formats are created either by using my new SDoP program to
351 produce PostScript which can then be run through ps2pdf to make a PDF, or by
352 using xmlto and fop in the old way.
353
354
355 USING SDOP TO CREATE POSTSCRIPT AND PDF
356
357 PostScript output is created in two stages. First, the XML is pre-processed by
358 the Pre-xml script. For the filter document, the <bookinfo> element is removed
359 so that no title page is generated. For the main specification, the only change
360 is to insert line breakpoints via -optbreak.
361
362 The SDoP program is then used to create PostScript output directly from the XML
363 input. Then the ps2pdf command is used to generated a PDF from the PostScript.
364 There are no external stylesheets that are used by SDoP. Any variations to the
365 default format are specified inline using "processing instructions".
366
367
368 USING XMLTO AND FOP TO CREATE POSTSCRIPT AND PDF
369
370 This is the original way of creating PostScript and PDF output. The processing
371 happens in three stages, with an additional fourth stage for PDF. First, the
372 XML is pre-processed by the Pre-xml script. For the filter document, the
373 <bookinfo> element is removed so that no title page is generated. For the main
374 specification, the only change is to insert line breakpoints via -optbreak.
375
376 Second, the xmlto command is used to produce a "formatted objects" (.fo) file.
377 This process uses the following stylesheets:
378
379   (1) Either MyStyle-filter-fo.xsl or MyStyle-spec-fo.xsl
380   (2) MyStyle-fo.xsl
381   (3) MyStyle.xsl
382   (4) MyTitleStyle.xsl
383
384 The last of these is not used for the filter document, which does not have a
385 title page. The first three stylesheets were created manually, either by typing
386 directly, or by coping from the standard style sheet and editing.
387
388 The final stylesheet has to be created from a template document, which is
389 called MyTitlepage.templates.xml. This was copied from the standard styles and
390 modified. The template is processed with xsltproc to produce the stylesheet.
391 All this apparatus is appallingly heavyweight. The processing is also very slow
392 in the case of the specification document. However, there should be no errors.
393
394 The reference book that saved my life while I was trying to get all this to
395 work is "DocBook XSL, The Complete Guide", third edition (2005), by Bob
396 Stayton, published by Sagehill Enterprises.
397
398 In the third part of the processing, the .fo file that is produced by the xmlto
399 command is processed by the fop command to generate either PostScript or PDF.
400 This is also very slow, and you get a whole slew of errors, of which these are
401 a sample:
402
403   [ERROR] property - "background-position-horizontal" is not implemented yet.
404
405   [ERROR] property - "background-position-vertical" is not implemented yet.
406
407   [INFO] JAI support was not installed (read: not present at build time).
408     Trying to use Jimi instead
409     Error creating background image: Error creating FopImage object (Error
410     creating FopImage object
411     (http://docbook.sourceforge.net/release/images/draft.png) :
412     org.apache.fop.image.JimiImage
413
414   [WARNING] table-layout=auto is not supported, using fixed!
415
416   [ERROR] Unknown enumerated value for property 'span': inherit
417
418   [ERROR] Error in span property value 'inherit':
419     org.apache.fop.fo.expr.PropertyException: No conversion defined
420
421   [ERROR] Areas pending, text probably lost in lineinclude parts matched in the
422     response by response_pattern by means of numeric variables such as
423
424 The last one is particularly meaningless gobbledegook. Some of the errors and
425 warnings are repeated many times. Nevertheless, it does eventually produce
426 usable output, though I have a number of issues with it (see a later section of
427 this document). Maybe one day there will be a new release of fop that does
428 better. In the meantime, I have written my own program for making PostScript
429 output -- see the previous section -- because the problems with xmlto/fop were
430 sufficiently annoying.
431
432 The PDF file that is produced by this process has one problem: the pages, as
433 shown by acroread in its thumbnail display, are numbered sequentially from one
434 to the end. Those numbers do not correspond with the page numbers of the body
435 of the document, which makes finding a page from the index awkward. There is a
436 facility in the PDF format to give pages appropriate "labels", but I cannot
437 find a way of persuading fop to generate these. Fortunately, it is possibly to
438 fix up the PDF to add page labels. I wrote a script called PageLabelPDF which
439 does this. They are shown correctly by acroread and xpdf, but not by
440 GhostScript (gv).
441
442
443 THE PAGELABELPDF SCRIPT
444
445 This script reads the standard input and writes the standard output. It is used
446 to "tidy up" the PDF output that is produced by fop. It is not needed when
447 PDF output is generated from SDoP's output using ps2pdf.
448
449 The PageLabelPDF script searches for the PDF object that sets data in its
450 "Catalog", and adds appropriate information about page labels. The number of
451 front-matter pages (those before chapter 1) is hard-wired into this script as
452 12 because I could not find a way of determining it automatically. As the
453 current table of contents finishes near the top of the 11th page, there is
454 plenty of room for expansion, so it is unlikely to be a problem.
455
456 Having added data to the PDF file, the script then finds the xref table at the
457 end of the file, and adjusts its entries to allow for the added text. This
458 simple processing seems to be enough to generate a new, valid, PDF file.
459
460
461 CREATING HTML
462
463 Only two stages are needed to produce HTML, but the main specification is
464 subsequently postprocessed. The Pre-xml script is called with the -optbreak and
465 -oneindex options to preprocess the XML. Then the xmlto command creates the
466 HTML output directly. For the specification document, a directory of files is
467 created, whereas the filter document is output as a single HTML page. The
468 following stylesheets are used:
469
470   (1) Either MyStyle-chunk-html.xsl or MyStyle-nochunk-html.xsl
471   (2) MyStyle-html.xsl
472   (3) MyStyle.xsl
473
474 The first stylesheet references the chunking or non-chunking standard DocBook
475 stylesheet, as appropriate.
476
477 You may see a number of these errors when creating HTML: "Revisionflag on
478 unexpected element: literallayout (Assuming block)". They seem to be harmless;
479 the output appears to be what is intended.
480
481 The original HTML that I produced from the SGCAL input had hyperlinks back from
482 chapter and section titles to the table of contents. These links are not
483 generated by xmlto. One of the testers pointed out that the lack of these
484 links, or simple self-referencing links for titles, makes it harder to copy a
485 link name into, for example, a mailing list response.
486
487 I could not find where to fiddle with the stylesheets to make such a change, if
488 indeed the stylesheets are capable of it. Instead, I wrote a Perl script called
489 TidyHTML-spec to do the job for the specification document. It updates the
490 index.html file (which contains the the table of contents) setting up anchors,
491 and then updates all the chapter files to insert appropriate links.
492
493 The index.html file as built by xmlto contains the whole table of contents in a
494 single line, which makes is hard to debug by hand. Since I was postprocessing
495 it anyway, I arranged to insert newlines after every '>' character.
496
497 The TidyHTML-spec script also processes every HTML file, to tidy up some of the
498 untidy features therein. It turns <div class="literallayout"><p> into <div
499 class="literallayout"> and a matching </p></div> into </div> to get rid of
500 unwanted vertical white space in literallayout blocks. Before each occurrence
501 of </td> it inserts &nbsp; so that the table's cell is a little bit wider than
502 the text itself.
503
504 The TidyHTML-spec script also takes the opportunity to postprocess the
505 spec_html/ix01.html file, which contains the document index. Again, the index
506 is generated as one single line, so it splits it up. Then it creates a list of
507 letters at the top of the index and hyperlinks them both ways from the
508 different letter portions of the index.
509
510 People wanted similar postprocessing for the filter.html file, so that is now
511 done using a similar script called TidyHTML-filter. It was easier to use a
512 separate script because filter.html is a single file rather than a directory,
513 so the logic is somewhat different.
514
515
516 CREATING TEXT FILES
517
518 This happens in four stages. The Pre-xml script is called with the -ascii,
519 -optbreak, and -noindex options to convert the input to ASCII characters,
520 insert line break points, and disable the production of an index. Then the
521 xmlto command converts the XML to a single HTML document, using these
522 stylesheets:
523
524   (1) MyStyle-txt-html.xsl
525   (2) MyStyle-html.xsl
526   (3) MyStyle.xsl
527
528 The MyStyle-txt-html.xsl stylesheet is the same as MyStyle-nochunk-html.xsl,
529 except that it contains an addition item to ensure that a generated "copyright"
530 symbol is output as "(c)" rather than the Unicode character. This is necessary
531 because the stylesheet itself generates a copyright symbol as part of the
532 document title; the character is not in the original input.
533
534 The w3m command is used with the -dump option to turn the HTML file into ASCII
535 text, but this contains multiple sequences of blank lines that make it look
536 awkward. Furthermore, chapter and section titles do not stand out very well. A
537 local Perl script called Tidytxt is used to post-process the output. First, it
538 converts sequences of blank lines into a single blank lines. Then it searches
539 for chapter and section headings. Each chapter heading is uppercased, and
540 preceded by an extra two blank lines and a line of equals characters. An extra
541 newline is inserted before each section heading, and they are underlined with
542 hyphens.
543
544 The output of xmlto also contains non-ASCII Unicode characters that w3m passes
545 through. Fortunately, they are few, and Tidytxt cleans them up as well. Some
546 headings use "box drawing" characters in the range U+2500 to U+253F which are
547 translated into -+| as appropriate, and U+00A0 (hard space) and U+25CF (bullet)
548 are translated into plain spaces and asterisks. (It might be possible to do all
549 this in the same way as I dealt with copyright - see above - but adding a few
550 lines of Perl to an existing script was a lot easier.)
551
552
553 CREATING INFO FILES
554
555 This process starts with the same Pre-xml call as for text files. Non-ascii
556 characters in the source are transliterated, and the <index> elements are
557 removed. The docbook2texi script is then called to convert the XML file into a
558 Texinfo file. However, this is not quite enough. The converted file ends up
559 with "conceptindex" and "optionindex" items, which are not recognized by the
560 makeinfo command. These have to be changed to "cindex" and "findex"
561 respectively in the final .texinfo file. Furthermore, the main menu lacks a
562 pointer to the index, and indeed the index node itself is missing. These
563 problems are fixed by running the file through a script called TidyInfo.
564 Finally, a call of makeinfo creates a .info file.
565
566 There is one apparently unconfigurable feature of docbook2texi: it does not
567 seem possible to give it a file name for its output. It chooses a name based on
568 the title of the document. Thus, the main specification ends up in a file
569 called the_exim_mta.texi and the filter document in exim_filtering.texi. These
570 files are removed after their contents have been copied and modified by the
571 TidyInfo script, which writes to a .texinfo file.
572
573
574 CREATING THE MAN PAGE
575
576 I wrote a Perl script called x2man to create the exim.8 man page from the
577 DocBook XML source. I deliberately did NOT start from the xfpt source,
578 because it is the DocBook source that is the "standard". This comment line in
579 the DocBook source marks the start of the command line options:
580
581   <!-- === Start of command line options === -->
582
583 A similar line marks the end. If at some time in the future another way other
584 than xfpt is used to maintain the DocBook source, it needs to be capable of
585 maintaining these comments.
586
587
588 UNRESOLVED PROBLEMS
589
590 There are a number of unresolved problems with producing the Exim documentation
591 in the manner described above. I will describe them here in the hope that in
592 future some way round them can be found. Some of the problems are solved by
593 using SDoP instead of xmlto/fop to produce PostScript and PDF output.
594
595 (1)  When a whole chain of tools is processing a file, an error somewhere
596      in the middle is often very hard to debug. For instance, an error in the
597      xfpt file might not show up until an XML processor throws a wobbly because
598      the generated XML is bad. You have to be able to read XML and figure out
599      what generated what. One of the reasons for creating the "test" series of
600      targets was to help in checking out these kinds of problem.
601
602 (2)  There is a mechanism in XML for marking parts of the document as
603      "revised", and I have arranged for xfpt markup to use it. However, the
604      only xmlto output format that pays attention to this is the HTML output,
605      which sets a green background. If xmlto/fop is used to generate PostScript
606      and PDF, there are no revision marks (change bars). This problem
607      is not present when SDoP is used. However, the text and Texinfo output
608      format lack revision indications.
609
610 (3)  The index entries in the HTML format take you to the top of the section
611      that is referenced, instead of to the point in the section where the index
612      marker was set.
613
614 (4)  The HTML output supports only a single index, so the variable, options,
615      and concept index entries have to be merged.
616
617 (5)  The index for the PostScript/PDF output created by xmlto/fop does not
618      merge identical page numbers, which makes some entries look ugly. This is
619      not a problem when SDoP is used.
620
621 (6)  The HTML index and the PostScript/PDF indexes, when made with xmlto/fop,
622      make no use of textual markup; the text is all roman, without any italic
623      or boldface. For PostScript/PDF, this is not a problem when SDoP is used.
624
625 (7)  I turned off hyphenation in the PostScript/PDF output produced by
626      xmlto/fop, because it was being done so badly. Needless to say, I made
627      SDoP do a better job. These comments apply to xmlto/fop:
628
629      (a) It seems to force hyphenation if it is at all possible, without
630          regard to the "tightness" or "looseness" of the line. Decent
631          formatting software should attempt hyphenation only if the line is
632          over some "looseness" threshold; otherwise you get far too many
633          hyphenations, often for several lines in succession.
634
635      (b) It uses an algorithmic form of hyphenation that doesn't always produce
636          acceptable word breaks. (I prefer to use a hyphenation dictionary,
637          which is what SDoP does.)
638
639 (8)  The PostScript/PDF output produced by xmlto/fop is badly paginated:
640
641      (a) There seems to be no attempt to avoid "widow" and "orphan" lines on
642          pages. A "widow" is the last line of a paragraph at the top of a page,
643          and an "orphan" is the first line of a paragraph at the bottom of a
644          page.
645
646      (b) There seems to be no attempt to prevent section headings being placed
647          last on a page, with no following text on the page.
648
649      Neither of these problems occurs when SDoP is used to produce the
650      PostScript/PDF output.
651
652 (9)  The fop processor does not support "fi" ligatures, not even if you put the
653      appropriate Unicode character into the source by hand. Again, this is not
654      a problem if SDoP is used.
655
656 (10) There are no diagrams in the new documentation. This is something I hope
657      to work on. The previously used Aspic command for creating line art from a
658      textual description can output Encapsulated PostScript or Scalar Vector
659      Graphics, which are two standard diagram representations. Aspic could be
660      formally released and used to generate output that could be included in at
661      least some of the output formats.
662
663 (11) The use of a "zero-width space" works well as a way of specifying that
664      Exim option names can be split, without hyphens, over line breaks.
665
666      However, when xmlto/fop is being used and an option is not split, if the
667      line is very "loose", the zero-width space is expanded, along with other
668      spaces. This is a totally crazy thing to, but unfortunately it is
669      suggested by the Unicode definition of the zero-width space, which says
670      "its presence between two characters does not prevent increased letter
671      spacing in justification". It seems that the implementors of fop have
672      understood "letter spacing" also to include "word spacing". Sigh.
673
674      This problem does not arise when SDoP is used.
675
676 The consequence of (7), (8), and (9) is that the PostScript/PDF output as
677 produced by xmlto/fop looks as if it comes from some of the very early attempts
678 at text formatting of around 20 years ago. We can only hope that 20 years'
679 progress is not going to get lost, and that things will improve in this area.
680 My small contribution to this has been to write SDoP, which, though simple and
681 "non-standard", does get some of these formatting issues right.
682
683
684 LIST OF FILES
685
686 Markup.txt                     Describes the xfpt markup that is used
687 HowItWorks.txt                 This document
688 Makefile                       The makefile
689 MyStyle-chunk-html.xsl         Stylesheet for chunked HTML output
690 MyStyle-filter-fo.xsl          Stylesheet for filter fo output
691 MyStyle-fo.xsl                 Stylesheet for any fo output
692 MyStyle-html.xsl               Stylesheet for any HTML output
693 MyStyle-nochunk-html.xsl       Stylesheet for non-chunked HTML output
694 MyStyle-spec-fo.xsl            Stylesheet for spec fo output
695 MyStyle-txt-html.xsl           Stylesheet for HTML=>text output
696 MyStyle.xsl                    Stylesheet for all output
697 MyTitleStyle.xsl               Stylesheet for spec title page
698 MyTitlepage.templates.xml      Template for creating MyTitleStyle.xsl
699 Myhtml.css                     Experimental css stylesheet for HTML output
700 PageLabelPDF                   Script to postprocess xmlto/fop PDF output
701 Pre-xml                        Script to preprocess XML
702 TidyHTML-filter                Script to tidy up the filter HTML output
703 TidyHTML-spec                  Script to tidy up the spec HTML output
704 TidyInfo                       Script to sort index problems in Texinfo output
705 Tidytxt                        Script to compact multiple blank lines
706 filter.xfpt                    xfpt source of the filter document
707 spec.xfpt                      xfpt source of the specification document
708 x2man                          Script to make the Exim man page from the XML
709
710
711 (Originally, and for the most part: Philip Hazel)
712 The Exim Maintainers
713 Last updated: 5 July 2010