91326d83ec62e075bac4b551d5b763cc7e169fb3
[exim.git] / doc / doc-docbook / HowItWorks.txt
1 $Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.7 2007/08/29 13:37:28 ph10 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 problems that bother me in the XML-generated
78 documentation are described in the penultimate section of this document.
79
80 The major problems were originally 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 will be used for the Exim 4.67
89 documentation. A full release of SDoP requires further work. 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 seconds instead of
92 2 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.01
111
112   This converts the master source file into a DocBook XML file.
113
114 . sdop 0.00
115
116   This is my new, still-very-alpha, 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.22
135   libxslt 1.1.15
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-1.70.1
141
142   These are the standard DocBook XSL stylesheets.
143
144 . fop 0.20.5
145
146   FOP is a processor for "formatted objects". It is written in Java. The fop
147   command is a shell script that drives it. It required only if you do not
148   want to use SDoP and ps2pdf to generate PostScript and PDF output.
149
150 . w3m 0.5.1
151
152   This is a text-oriented web brower. It is used to produce the ASCII form of
153   the Exim documentation (spec.txt) from a specially-created HTML format. It
154   seems to do a better job than lynx.
155
156 . docbook2texi (part of docbook2X 0.8.5)
157
158   This is a wrapper script for a two-stage conversion process from DocBook to a
159   Texinfo file. It uses db2x_xsltproc and db2x_texixml. Unfortunately, there
160   are two versions of this command; the old one is based on an earlier fork of
161   docbook2X and does not work.
162
163 . db2x_xsltproc and db2x_texixml (part of docbook2X 0.8.5)
164
165   More wrapping scripts (see previous item).
166
167 . makeinfo 4.8
168
169   This is used to make a set of "info" files from a Texinfo file.
170
171 In addition, there are a number of locally written Perl scripts. These are
172 described below.
173
174
175 THE MAKEFILE
176
177 The makefile supports a number of targets of the form x.y, where x is one of
178 "filter", "spec", or "test", and y is one of "xml", "fo", "ps", "pdf", "html",
179 "txt", or "info". The intermediate targets "x.xml" and "x.fo" are provided for
180 testing purposes. The other five targets are production targets. For example:
181
182   make spec.pdf
183
184 This runs the necessary tools in order to create the file spec.pdf from the
185 original source spec.xfpt. A number of intermediate files are created during
186 this process, including the master DocBook source, called spec.xml. Of course,
187 the usual features of "make" ensure that if this already exists and is
188 up-to-date, it is not needlessly rebuilt.
189
190 Because there are now two ways of creating the PostScript and PDF outputs,
191 there are two targets for each one. For example fop-spec.ps makes PostScript
192 using fop, and sdop-spec.ps makes it using SDoP. The generic targets spec.ps
193 and spec.pdf now point to the SDoP versions.
194
195 The "test" series of targets were created so that small tests could easily be
196 run fairly quickly, because processing even the shortish XML document takes
197 a bit of time, and processing the main specification takes ages -- except when
198 using SDoP for PostScript and PDF.
199
200 Another target is "exim.8". This runs a locally written Perl script called
201 x2man, which extracts the list of command line options from the spec.xml file,
202 and creates a man page. There are some XML comments in the spec.xml file to
203 enable the script to find the start and end of the options list.
204
205 There is also a "clean" target that deletes all the generated files.
206
207
208 CREATING DOCBOOK XML FROM XFPT INPUT
209
210 The small amount of local configuration for xfpt is included at the start of
211 the two .xfpt files; there are no separate local xfpt configuration files.
212 Running the xfpt command creates a .xml file from a .xfpt file. When this
213 succeeds, there is no output.
214
215
216 DOCBOOK PROCESSING
217
218 Processing a .xml file into the five different output formats is not entirely
219 straightforward. For a start, the same XML is not suitable for all the
220 different output styles. When the final output is in a text format (.txt,
221 .texinfo) for instance, all non-ASCII characters in the input must be converted
222 to ASCII transliterations because the current processing tools do not do this
223 correctly automatically.
224
225 In order to cope with these issues in a flexible way, a Perl script called
226 Pre-xml was written. This is used to preprocess the .xml files before they are
227 handed to the main processors. Adding one more tool onto the front of the
228 processing chain does at least seem to be in the spirit of XML processing.
229
230 The XML processors other than SDoP make use of style files, which can be
231 overridden by local versions. There is one that applies to all styles, called
232 MyStyle.xsl, and others for the different output formats. I have included
233 comments in these style files to explain what changes I have made. Some of the
234 changes are quite significant.
235
236
237 THE PRE-XML SCRIPT
238
239 The Pre-xml script copies a .xml file, making certain changes according to the
240 options it is given. The currently available options are as follows:
241
242 -ascii
243
244   This option is used for ASCII output formats. It makes the following
245   character replacements:
246
247     ’  =>  '         apostrophe
248     ©    =>  (c)       copyright
249     †  =>  *         dagger
250     ‡  =>  **        double dagger
251          =>  a space   hard space
252     –   =>  -         en dash
253
254   The apostrophe is specified numerically because that is what xfpt generates
255   from an ASCII single quote character. Non-ASCII characters that are not in
256   this list should not be used without thinking about how they might be
257   converted for the ASCII formats.
258
259   In addition to the character replacements, this option causes quotes to be
260   put round <literal> text items, and <quote> and </quote> to be replaced by
261   ASCII quote marks. You would think the stylesheet would cope with the latter,
262   but it seems to generate non-ASCII characters that w3m then turns into
263   question marks.
264
265 -bookinfo
266
267   This option causes the <bookinfo> element to be removed from the XML. It is
268   used for the PostScript/PDF forms of the filter document, in order to avoid
269   the generation of a full title page.
270
271 -fi
272
273   Replace any occurrence of "fi" by the ligature &#xFB01; except when it is
274   inside an XML element, or inside a <literal> part of the text.
275
276   The use of ligatures would be nice for the PostScript and PDF formats. Sadly,
277   it turns out that fop cannot at present handle the FB01 character correctly.
278   Happily this problem is now avoided when SDoP is used to generate PostScript
279   (and thence PDF) because SDoP automatically uses an "fi" ligature for
280   non-fixed-width fonts.
281
282   The only xmlto format that handles FB01 is the HTML format, but when I used
283   this in the test version, people complained that it made searching for words
284   difficult. So this option is in practice not used at all.
285
286 -noindex
287
288   Remove the XML to generate a Concept Index and an Options index. The source
289   document has two types of index entry, for a concept and an options index.
290   However, no index is required for the .txt and .texinfo outputs.
291
292 -oneindex
293
294   Remove the XML to generate a Concept and an Options Index, and add XML to
295   generate a single index. The only output processors that support multiple
296   indexes are SDoP and the processor that produces "formatted objects" for
297   PostScript and PDF output for fop. The HTML processor ignores the XML
298   settings for multiple indexes and just makes one unified index. Specifying
299   two indexes gets you two copies of the same index, so this has to be changed.
300
301 -optbreak
302
303   Look for items of the form <option>...</option> and <varname>...</varname> in
304   ordinary paragraphs, and insert &#x200B; after each underscore in the
305   enclosed text. The same is done for any word containing four or more upper
306   case letters (compile-time options in the Exim specification). The character
307   &#x200B; is a zero-width space. This means that the line may be split after
308   one of these underscores, but no hyphen is inserted.
309
310
311 CREATING POSTSCRIPT AND PDF
312
313 These two output formats are created either by using my new SDoP program to
314 produce PostScript which can then be run through ps2pdf to make a PDF, or by
315 using xmlto and fop in the old way.
316
317
318 USING SDOP TO CREATE POSTSCRIPT AND PDF
319
320 PostScript output is created in two stages. First, the XML is pre-processed by
321 the Pre-xml script. For the filter document, the <bookinfo> element is removed
322 so that no title page is generated. For the main specification, the only change
323 is to insert line breakpoints via -optbreak.
324
325 The SDoP program is then used to create PostScript output directly from the XML
326 input. Then the ps2pdf command is used to generated a PDF from the PostScript.
327 There are no external stylesheets that are used by SDoP. Any variations to the
328 default format are specified inline using "processing instructions".
329
330
331 USING XMLTO AND FOP TO CREATE POSTSCRIPT AND PDF
332
333 This is the original way of creating PostScript and PDF output. The processing
334 happens in three stages, with an additional fourth stage for PDF. First, the
335 XML is pre-processed by the Pre-xml script. For the filter document, the
336 <bookinfo> element is removed so that no title page is generated. For the main
337 specification, the only change is to insert line breakpoints via -optbreak.
338
339 Second, the xmlto command is used to produce a "formatted objects" (.fo) file.
340 This process uses the following stylesheets:
341
342   (1) Either MyStyle-filter-fo.xsl or MyStyle-spec-fo.xsl
343   (2) MyStyle-fo.xsl
344   (3) MyStyle.xsl
345   (4) MyTitleStyle.xsl
346
347 The last of these is not used for the filter document, which does not have a
348 title page. The first three stylesheets were created manually, either by typing
349 directly, or by coping from the standard style sheet and editing.
350
351 The final stylesheet has to be created from a template document, which is
352 called MyTitlepage.templates.xml. This was copied from the standard styles and
353 modified. The template is processed with xsltproc to produce the stylesheet.
354 All this apparatus is appallingly heavyweight. The processing is also very slow
355 in the case of the specification document. However, there should be no errors.
356
357 The reference book that saved my life while I was trying to get all this to
358 work is "DocBook XSL, The Complete Guide", third edition (2005), by Bob
359 Stayton, published by Sagehill Enterprises.
360
361 In the third part of the processing, the .fo file that is produced by the xmlto
362 command is processed by the fop command to generate either PostScript or PDF.
363 This is also very slow, and you get a whole slew of errors, of which these are
364 a sample:
365
366   [ERROR] property - "background-position-horizontal" is not implemented yet.
367
368   [ERROR] property - "background-position-vertical" is not implemented yet.
369
370   [INFO] JAI support was not installed (read: not present at build time).
371     Trying to use Jimi instead
372     Error creating background image: Error creating FopImage object (Error
373     creating FopImage object
374     (http://docbook.sourceforge.net/release/images/draft.png) :
375     org.apache.fop.image.JimiImage
376
377   [WARNING] table-layout=auto is not supported, using fixed!
378
379   [ERROR] Unknown enumerated value for property 'span': inherit
380
381   [ERROR] Error in span property value 'inherit':
382     org.apache.fop.fo.expr.PropertyException: No conversion defined
383
384   [ERROR] Areas pending, text probably lost in lineinclude parts matched in the
385     response by response_pattern by means of numeric variables such as
386
387 The last one is particularly meaningless gobbledegook. Some of the errors and
388 warnings are repeated many times. Nevertheless, it does eventually produce
389 usable output, though I have a number of issues with it (see a later section of
390 this document). Maybe one day there will be a new release of fop that does
391 better. In the meantime, I have written my own program for making PostScript
392 output -- see the previous section -- because the problems with xmlto/fop were
393 sufficiently annoying.
394
395 The PDF file that is produced by this process has one problem: the pages, as
396 shown by acroread in its thumbnail display, are numbered sequentially from one
397 to the end. Those numbers do not correspond with the page numbers of the body
398 of the document, which makes finding a page from the index awkward. There is a
399 facility in the PDF format to give pages appropriate "labels", but I cannot
400 find a way of persuading fop to generate these. Fortunately, it is possibly to
401 fix up the PDF to add page labels. I wrote a script called PageLabelPDF which
402 does this. They are shown correctly by acroread and xpdf, but not by
403 GhostScript (gv).
404
405
406 THE PAGELABELPDF SCRIPT
407
408 This script reads the standard input and writes the standard output. It is used
409 to "tidy up" the PDF output that is produced by fop. It is not needed when
410 PDF output is generated from SDoP's output using ps2pdf.
411
412 The PageLabelPDF script searches for the PDF object that sets data in its
413 "Catalog", and adds appropriate information about page labels. The number of
414 front-matter pages (those before chapter 1) is hard-wired into this script as
415 12 because I could not find a way of determining it automatically. As the
416 current table of contents finishes near the top of the 11th page, there is
417 plenty of room for expansion, so it is unlikely to be a problem.
418
419 Having added data to the PDF file, the script then finds the xref table at the
420 end of the file, and adjusts its entries to allow for the added text. This
421 simple processing seems to be enough to generate a new, valid, PDF file.
422
423
424 CREATING HTML
425
426 Only two stages are needed to produce HTML, but the main specification is
427 subsequently postprocessed. The Pre-xml script is called with the -optbreak and
428 -oneindex options to preprocess the XML. Then the xmlto command creates the
429 HTML output directly. For the specification document, a directory of files is
430 created, whereas the filter document is output as a single HTML page. The
431 following stylesheets are used:
432
433   (1) Either MyStyle-chunk-html.xsl or MyStyle-nochunk-html.xsl
434   (2) MyStyle-html.xsl
435   (3) MyStyle.xsl
436
437 The first stylesheet references the chunking or non-chunking standard DocBook
438 stylesheet, as appropriate.
439
440 You may see a number of these errors when creating HTML: "Revisionflag on
441 unexpected element: literallayout (Assuming block)". They seem to be harmless;
442 the output appears to be what is intended.
443
444 The original HTML that I produced from the SGCAL input had hyperlinks back from
445 chapter and section titles to the table of contents. These links are not
446 generated by xmlto. One of the testers pointed out that the lack of these
447 links, or simple self-referencing links for titles, makes it harder to copy a
448 link name into, for example, a mailing list response.
449
450 I could not find where to fiddle with the stylesheets to make such a change, if
451 indeed the stylesheets are capable of it. Instead, I wrote a Perl script called
452 TidyHTML-spec to do the job for the specification document. It updates the
453 index.html file (which contains the the table of contents) setting up anchors,
454 and then updates all the chapter files to insert appropriate links.
455
456 The index.html file as built by xmlto contains the whole table of contents in a
457 single line, which makes is hard to debug by hand. Since I was postprocessing
458 it anyway, I arranged to insert newlines after every '>' character.
459
460 The TidyHTML-spec script also processes every HTML file, to tidy up some of the
461 untidy features therein. It turns <div class="literallayout"><p> into <div
462 class="literallayout"> and a matching </p></div> into </div> to get rid of
463 unwanted vertical white space in literallayout blocks. Before each occurrence
464 of </td> it inserts &nbsp; so that the table's cell is a little bit wider than
465 the text itself.
466
467 The TidyHTML-spec script also takes the opportunity to postprocess the
468 spec_html/ix01.html file, which contains the document index. Again, the index
469 is generated as one single line, so it splits it up. Then it creates a list of
470 letters at the top of the index and hyperlinks them both ways from the
471 different letter portions of the index.
472
473 People wanted similar postprocessing for the filter.html file, so that is now
474 done using a similar script called TidyHTML-filter. It was easier to use a
475 separate script because filter.html is a single file rather than a directory,
476 so the logic is somewhat different.
477
478
479 CREATING TEXT FILES
480
481 This happens in four stages. The Pre-xml script is called with the -ascii,
482 -optbreak, and -noindex options to convert the input to ASCII characters,
483 insert line break points, and disable the production of an index. Then the
484 xmlto command converts the XML to a single HTML document, using these
485 stylesheets:
486
487   (1) MyStyle-txt-html.xsl
488   (2) MyStyle-html.xsl
489   (3) MyStyle.xsl
490
491 The MyStyle-txt-html.xsl stylesheet is the same as MyStyle-nochunk-html.xsl,
492 except that it contains an addition item to ensure that a generated "copyright"
493 symbol is output as "(c)" rather than the Unicode character. This is necessary
494 because the stylesheet itself generates a copyright symbol as part of the
495 document title; the character is not in the original input.
496
497 The w3m command is used with the -dump option to turn the HTML file into ASCII
498 text, but this contains multiple sequences of blank lines that make it look
499 awkward. Furthermore, chapter and section titles do not stand out very well. A
500 local Perl script called Tidytxt is used to post-process the output. First, it
501 converts sequences of blank lines into a single blank lines. Then it searches
502 for chapter and section headings. Each chapter heading is uppercased, and
503 preceded by an extra two blank lines and a line of equals characters. An extra
504 newline is inserted before each section heading, and they are underlined with
505 hyphens.
506
507 August 2007: A further feature has been added to Tidytxt. The current version
508 of xmlto makes HTML that contains non-ASCII Unicode characters. Fortunately,
509 they are few. The heading uses "box drawing" characters in the range U+2500 to
510 U+253F, and within the main text, U+00A0 (hard space) occasionally appears. The
511 Tidytxt script now turns all the former into hyphens and the latter into normal
512 spaces. Bullets, which are set as U+25CF, are turned into asterisks. (It might
513 be possible to do all this in the same way as I dealt with copyright - see
514 above - but adding three lines of Perl to an existing script was a lot easier.)
515
516
517 CREATING INFO FILES
518
519 This process starts with the same Pre-xml call as for text files. Non-ascii
520 characters in the source are transliterated, and the <index> elements are
521 removed. The docbook2texi script is then called to convert the XML file into a
522 Texinfo file. However, this is not quite enough. The converted file ends up
523 with "conceptindex" and "optionindex" items, which are not recognized by the
524 makeinfo command. These have to be changed to "cindex" and "findex"
525 respectively in the final .texinfo file. Furthermore, the main menu lacks a
526 pointer to the index, and indeed the index node itself is missing. These
527 problems are fixed by running the file through a script called TidyInfo.
528 Finally, a call of makeinfo creates a set of .info files.
529
530 There is one apparently unconfigurable feature of docbook2texi: it does not
531 seem possible to give it a file name for its output. It chooses a name based on
532 the title of the document. Thus, the main specification ends up in a file
533 called the_exim_mta.texi and the filter document in exim_filtering.texi. These
534 files are removed after their contents have been copied and modified by the
535 TidyInfo script, which writes to a .texinfo file.
536
537
538 CREATING THE MAN PAGE
539
540 I wrote a Perl script called x2man to create the exim.8 man page from the
541 DocBook XML source. I deliberately did NOT start from the xfpt source,
542 because it is the DocBook source that is the "standard". This comment line in
543 the DocBook source marks the start of the command line options:
544
545   <!-- === Start of command line options === -->
546
547 A similar line marks the end. If at some time in the future another way other
548 than xfpt is used to maintain the DocBook source, it needs to be capable of
549 maintaining these comments.
550
551
552 UNRESOLVED PROBLEMS
553
554 There are a number of unresolved problems with producing the Exim documentation
555 in the manner described above. I will describe them here in the hope that in
556 future some way round them can be found. Some of the problems are solved by
557 using SDoP instead of xmlto/fop to produce PostScript and PDF output.
558
559 (1)  When a whole chain of tools is processing a file, an error somewhere
560      in the middle is often very hard to debug. For instance, an error in the
561      xfpt file might not show up until an XML processor throws a wobbly because
562      the generated XML is bad. You have to be able to read XML and figure out
563      what generated what. One of the reasons for creating the "test" series of
564      targets was to help in checking out these kinds of problem.
565
566 (2)  There is a mechanism in XML for marking parts of the document as
567      "revised", and I have arranged for xfpt markup to use it. However, the
568      only xmlto output format that pays attention to this is the HTML output,
569      which sets a green background. If xmlto/fop is used to generate PostScript
570      and PDF, there are no revision marks (change bars). This problem
571      is not present when SDoP is used. However, the text and Texinfo output
572      format lack revision indications.
573
574 (3)  The index entries in the HTML format take you to the top of the section
575      that is referenced, instead of to the point in the section where the index
576      marker was set.
577
578 (4)  The HTML output supports only a single index, so the concept and options
579      index entries have to be merged.
580
581 (5)  The index for the PostScript/PDF output created by xmlto/fop does not
582      merge identical page numbers, which makes some entries look ugly. This is
583      not a problem when SDoP is used.
584
585 (6)  None of the indexes (PostScript/PDF and HTML) make use of textual
586      markup; the text is all roman, without any italic or boldface. For
587      PostScript/PDF, this is not a problem when SDoP is used.
588
589 (7)  I turned off hyphenation in the PostScript/PDF output produced by
590      xmlto/fop, because it was being done so badly. Needless to say, I made
591      SDoP do a better job. These comments apply to xmlto/fop:
592
593      (a) It seems to force hyphenation if it is at all possible, without
594          regard to the "tightness" or "looseness" of the line. Decent
595          formatting software should attempt hyphenation only if the line is
596          over some "looseness" threshold; otherwise you get far too many
597          hyphenations, often for several lines in succession.
598
599      (b) It uses an algorithmic form of hyphenation that doesn't always produce
600          acceptable word breaks. (I prefer to use a hyphenation dictionary.)
601
602 (8)  The PostScript/PDF output produced by xmlto/fop is badly paginated:
603
604      (a) There seems to be no attempt to avoid "widow" and "orphan" lines on
605          pages. A "widow" is the last line of a paragraph at the top of a page,
606          and an "orphan" is the first line of a paragraph at the bottom of a
607          page.
608
609      (b) There seems to be no attempt to prevent section headings being placed
610          last on a page, with no following text on the page.
611
612      Neither of these problems occurs when SDoP is used to produce the
613      PostScript/PDF output.
614
615 (9)  The fop processor does not support "fi" ligatures, not even if you put the
616      appropriate Unicode character into the source by hand. Again, this is not
617      a problem if SDoP is used.
618
619 (10) There are no diagrams in the new documentation. This is something I hope
620      to work on. The previously used Aspic command for creating line art from a
621      textual description can output Encapsulated PostScript or Scalar Vector
622      Graphics, which are two standard diagram representations. Aspic could be
623      formally released and used to generate output that could be included in at
624      least some of the output formats.
625
626 (11) The use of a "zero-width space" works well as a way of specifying that
627      Exim option names can be split, without hyphens, over line breaks.
628
629      However, when xmlto/fop is being used and an option is not split, if the
630      line is very "loose", the zero-width space is expanded, along with other
631      spaces. This is a totally crazy thing to, but unfortunately it is
632      suggested by the Unicode definition of the zero-width space, which says
633      "its presence between two characters does not prevent increased letter
634      spacing in justification". It seems that the implementors of fop have
635      understood "letter spacing" also to include "word spacing". Sigh.
636
637      This problem does not arise when SDoP is used.
638
639 The consequence of (7), (8), and (9) is that the PostScript/PDF output as
640 produced by xmlto/fop looks as if it comes from some of the very early attempts
641 at text formatting of around 20 years ago. We can only hope that 20 years'
642 progress is not going to get lost, and that things will improve in this area.
643 My small contribution to this has been to write SDoP, which, though simple and
644 "non-standard", does get some of these formatting issues right.
645
646
647 LIST OF FILES
648
649 Markup.txt                     Describes the xfpt markup that is used
650 HowItWorks.txt                 This document
651 Makefile                       The makefile
652 MyStyle-chunk-html.xsl         Stylesheet for chunked HTML output
653 MyStyle-filter-fo.xsl          Stylesheet for filter fo output
654 MyStyle-fo.xsl                 Stylesheet for any fo output
655 MyStyle-html.xsl               Stylesheet for any HTML output
656 MyStyle-nochunk-html.xsl       Stylesheet for non-chunked HTML output
657 MyStyle-spec-fo.xsl            Stylesheet for spec fo output
658 MyStyle-txt-html.xsl           Stylesheet for HTML=>text output
659 MyStyle.xsl                    Stylesheet for all output
660 MyTitleStyle.xsl               Stylesheet for spec title page
661 MyTitlepage.templates.xml      Template for creating MyTitleStyle.xsl
662 Myhtml.css                     Experimental css stylesheet for HTML output
663 PageLabelPDF                   Script to postprocess xmlto/fop PDF output
664 Pre-xml                        Script to preprocess XML
665 TidyHTML-filter                Script to tidy up the filter HTML output
666 TidyHTML-spec                  Script to tidy up the spec HTML output
667 TidyInfo                       Script to sort index problems in Texinfo output
668 Tidytxt                        Script to compact multiple blank lines
669 filter.xfpt                    xfpt source of the filter document
670 spec.xfpt                      xfpt source of the specification document
671 x2man                          Script to make the Exim man page from the XML
672
673
674 Philip Hazel
675 Last updated: 23 August 2007