Remove Asciidoc versions of the documentation and building apparatus;
authorPhilip Hazel <ph10@hermes.cam.ac.uk>
Wed, 1 Feb 2006 11:01:01 +0000 (11:01 +0000)
committerPhilip Hazel <ph10@hermes.cam.ac.uk>
Wed, 1 Feb 2006 11:01:01 +0000 (11:01 +0000)
replace with xfpt versions.

19 files changed:
doc/doc-docbook/AdMarkup.txt [deleted file]
doc/doc-docbook/HowItWorks.txt
doc/doc-docbook/Makefile
doc/doc-docbook/Markup.txt [new file with mode: 0644]
doc/doc-docbook/MyAsciidoc.conf [deleted file]
doc/doc-docbook/MyStyle-fo.xsl
doc/doc-docbook/MyStyle-spec-fo.xsl
doc/doc-docbook/MyStyle.xsl
doc/doc-docbook/MyTitleStyle.xsl [new file with mode: 0644]
doc/doc-docbook/MyTitlepage.templates.xml
doc/doc-docbook/PageLabelPDF [new file with mode: 0755]
doc/doc-docbook/Pre-xml
doc/doc-docbook/TidyHTML-filter
doc/doc-docbook/TidyHTML-spec
doc/doc-docbook/Tidytxt
doc/doc-docbook/filter.ascd [deleted file]
doc/doc-docbook/filter.xfpt [new file with mode: 0644]
doc/doc-docbook/spec.xfpt [moved from doc/doc-docbook/spec.ascd with 51% similarity]
doc/doc-docbook/x2man

diff --git a/doc/doc-docbook/AdMarkup.txt b/doc/doc-docbook/AdMarkup.txt
deleted file mode 100644 (file)
index 4267f55..0000000
+++ /dev/null
@@ -1,438 +0,0 @@
-$Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.2 2005/11/10 12:30:13 ph10 Exp $
-
-Asciidoc markup used in the Exim documentation
-----------------------------------------------
-
-This file contains a summary of the AsciiDoc markup that is used in the source
-files of the Exim documentation. The source files are in plain text that can be
-edited by any text editor. They are converted by the AsciiDoc application into
-DocBook XML for subsequent processing into the various output formats.
-
-This markup requires AsciiDoc release 6.0.3 or later.
-
-The advantage of using AsciiDoc format as a "back end" is that is uses
-relatively simple markup in the majority of the text, making it easier to read
-and edit. The disadvantage is that it is tricky to deal with complicated
-formatting - though that is probably true of any markup language - and there
-are a few gotchas.
-
-The Exim documentation uses the default AsciiDoc markup with some additions. I
-have created a special AsciiDoc configuration file for use with the Exim
-documentation. You must use this configuration if you want to get sensible
-results,
-
-
-SPECIAL CHARACTERS
-
-When typing paragraphs of text, the following character sequences are
-recognized as markup if they occur surrounding a "word phrase" within a
-paragraph. In the list below, ... represents the text that is enclosed.
-
-  '...'    single quotes        italic:
-                                  used for email addresses, domains, local
-                                  parts, header names, user names
-
-  *...*    asterisks            bold
-                                  used for things like "*Note:*"
-
-  `...`    backticks            monospaced text
-                                  used for literal quoting
-
-  $...$    dollar               Exim variable
-                                  maps to XML <varname> with leading $
-
-  %...%    percent              Exim option, command line option
-                                  maps to XML <option>
-
-  ^...^    circumflex           Exim driver name, Unix command, filter command
-                                 maps to XML <command>
-
-  ^^...^^  double circumflex    C function: maps to XML <function>
-
-  ^%...%^  circumflex percent   parameter: maps to XML <parameter>
-                                  Not currently used
-
-  _..._    underscore           file name: maps to XML <filename>
-
-  ``...''  backticks & quotes   put word in quotation marks
-
-For example,
-
-  This is an 'italic phrase'. This is a _filename_ and a $variable$.
-  This ``word'' is in quote marks.
-
-These quoting characters are recognized only if they are not flanked by
-alphanumeric characters. Thus, for instance, an apostrophe within a word can be
-represented as a single quote without any problem. Quoting can be nested, but
-not overlapped. However, the resulting XML from nested quotes is not always
-valid, so nesting is best avoided. (For example, `xxx'yyy'xxx` generates an
-<emphasis> item within a <literal> item, and the DocBook DTD doesn't allow
-that.) However, one combination that does work is <literal> within an
-<emphasis>, so that is what you have to use if you want a boldface monospaced
-font. That is, use *`bold mono`* and not `*bold mono*`. Sigh.
-
-There are also some character sequences that are translated into non-Ascii
-characters:
-
-  --     en-dash    (&#x2013;)
-  ---    em-dash    (&#x8212;)
-  ~      hard space (&#x00a0;)
-  !!     dagger     (&#x2020;}
-
-The two-character sequence ## is turned into nothing. It is useful for
-disambiguating markup. For example, something like
-
-  ``quoted ending in 'emphasized'''
-
-is ambiguous, and as AsciiDoc looks for the longest markup first, it doesn't do
-what you want. You have to code this as
-
-  ``quoted ending in 'emphasized'##''
-
-The dashes are recognized only when surrounded by white space. The special Exim
-AsciiDoc configuration also translates most apostrophes to a typographic
-apostrophe (&#x2019;). There are some cases where this doesn't work, for
-example, an apostrophe after a word in another font (because the quote
-character gets in the way). For this purpose, there is a named "attribute" that
-can be used. Named attributes are substituted inside curly braces.
-
-For example, in the filter document there is a reference to an imaginary user
-called lg303. User names are italicized, so this is always typed as 'lg303' but
-if an apostrophe-s is needed after it, you have to type
-
-  'lg303'{ap}s
-
-Another named attribute is {tl}, which turns into a tilde character, because a
-literal tilde becomes a hard space.
-
-A third named attribute is {hh}, which turns into two hyphens, because a
-literal "--" is converted into an en dash.
-
-A fourth named attributs is {pc}, which turns into a percent sign.
-
-
-ESCAPING SPECIAL CHARACTERS
-
-Use backslash if you need to escape a special character.
-
-***** GOTCHA *****
-Backslash is not special when it precedes any other character. Thus, you need
-to know which characters are special, which is a pain.
-
-
-COMMENTS
-
-You can include comments that will not be copied to the XML document by
-creating a comment block that is delimited by at least three slashes. For
-example:
-
-  ///
-  This is an AsciiDoc comment block.
-  ///
-
-You can also include one-line comments by starting the line with //.
-
-
-URL REFERENCES
-
-To refer to a URL, just put it in the text, followed by some text in square
-brackets to define the displayed text. If that is empty, the URL itself is
-displayed. For example, here's a reference to http://www.exim.org/[exim home
-page]. In HTML output, all you see is the display text; in printed output you
-see something like "exim home page [http://www.exim.org/]". The URL is printed
-in whatever is the current font, so it can be made bold by putting it in
-asterisks (for example).
-
-
-FORMAL PARAGRAPHS
-
-A formal paragraph has a title. This is normally typeset in bold at the start
-of the paragraph, and is useful as an alternative to a vertical labelled list
-(see below). To create such a paragraph, you just put its title first, like
-this:
-
-  [title="the title"]
-  Now give the text of the paragraph as usual.
-
-
-CHAPTERS AND SECTIONS
-
-AsciiDoc recognizes chapter and sections by looking for underlined lines, with
-the underlining character used to determine the type of section.
-
-  This is a chapter title
-  -----------------------
-
-  This is a section title
-  ~~~~~~~~~~~~~~~~~~~~~~~
-
-Chapter titles are used for running feet in the PDF form of the manual.
-Sometimes they are too long, causing them to be split in an ugly way. The
-solution to this is to define a short title for the chapter, like this:
-
-  [titleabbrev="short title"]
-  This is a rather long chapter title
-  -----------------------------------
-
-
-DISPLAYS
-
-Displayed blocks in a monospaced font can just be indented:
-
-  # Exim filter
-  deliver baggins@rivendell.middle-earth.example
-
-However, it seems that if the first line in such a block starts with an
-asterisk or if any lines in the block end in a backslash (as is quite often the
-case in Exim configuration examples), you have to use a "listing block" or a
-"literal block" instead of a "literal paragraph". Otherwise an initial asterisk
-makes AsciiDoc think this is a list item, and a terminating backslash causes
-lines to be concatenated. Also, a blank line in the block generates two output
-items, so that case should also be avoided.
-
-Another time when you have to use an explicit block is when a display forms
-part of a list item. This is because you have to indent such displays more than
-usual, because the processors don't appear to do this automatically.
-
-Listing blocks are delimited by lines of at least three hyphens; literal blocks
-are delimited by lines of at least four dots. For example:
-
-....
-/usr/sbin/sendmail -bf myfilter \
-   -f islington@never.where <test-message
-....
-
-Such blocks are indented by an amount that is specified in the style sheet, but
-this amount is always the same, regardless of whether the block is inside a
-list item (which is itself indented) or not. So if the block is within a list
-item, it must be explicitly indented as well.
-
-Blocks that are between lines of ampersands (at least 3 in each line) are
-displayed (by default) in the normal font, but with the lines unchanged. Quotes
-can be used in the block to specify different fonts. For example:
-
-&&&&
-`\n`   is replaced by a newline
-`\r`   is replaced by a carriage return
-`\t`   is replaced by a tab
-&&&&
-
-When this kind of output is required within a list of any kind (see below), you
-must precede it with a line consisting of just a plus sign, because by default
-any kind of block terminates the list item.
-
-
-CROSS-REFERENCES
-
-To set a cross-reference point, enclose the name in double square brackets:
-
-  [[SECTexample]]
-
-To refer to a cross-reference point, enclose the name in double angle brackets:
-
-  <<SECTexample>>
-
-
-INDEX ENTRIES
-
-To create an index entry, include a line like one of these:
-
-  cindex:[primary text,secondary text]
-  oindex:[primary text,secondary text]
-
-at the appropriate point in the text. The first is for the "concept index" and
-the second is for the "options index". Not all forms of output distinguish
-between these - sometimes there is just one index.
-
-The index for the Exim reference manual has a number of "see also" entries.
-Rather than invent some fancy AsciiDoc way of doing this, I have just coded
-them in XML, using the AsciiDoc escape hatch that is described below under
-FUDGES.
-
-
-LISTS
-
-For a bulleted list, start each item in the list with a hyphen or an asterisk
-followed by a space:
-
-  - First item.
-  - Second item.
-
-For a numbered list, start each item with a dot followed by a space:
-
-  . First item.
-  . Second item.
-
-
-VERTICAL LABELLED LISTS
-
-These are used for Exim command line options and similar things. They map into
-XML <variablelist> items. Start the list with the item name, followed by two
-colons, on a line by itself. This is followed by the text for the list item.
-
-
-LISTS CONTAINING MORE THAN ONE PARAGRAPH
-
-If there is more than one paragraph in a list item, the second and subsequent
-ones must be preceded by a line containing just a single "+" character, as
-otherwise the list is terminated. Literal paragraphs can be included without
-any special markup. For example:
-
-  first item::
-  This is the pararaph that describes the item.
-
-    We can even have an indented display
-    within the item
-  +
-  but any more paragraphs must be preceded by a plus character
-  (otherwise they aren't included in the list, and won't be
-  properly indented).
-
-The "+" notation can also be used to include other kinds of block within a list
-item. It's needed for all block types except nested lists and literal
-paragraphs.
-
-An alternative approach to lists that contain multiple paragraphs or blocks
-within each item is to put a line containing just two hyphens immediately
-before and immediately after the list. For example:
-
-  --
-  . First item
-
-  Second paragraph of first item
-
-  . Second item
-
-  And so on
-  --
-
-This is particularly helpful for nested lists (see below).
-
-
-NESTED LISTS
-
-You can nest lists of different types. However, if you want to revert to an
-outer list item at the end of a nested list, you must use the "--" feature
-described above for the inner list, so that its end can be explicitly marked.
-For example:
-
-  . Outer list
-  +
-  Second paragraph in outer list
-  +
-  --
-  - Inner list item
-  - Inner list second item
-  --
-  +
-  Another paragraph in the outer list first item
-
-  . Next item in the outer list
-
-
-TABLES
-
-A fixed-width table is started by a line of hyphens that determines the width
-of the table, interspersed with the following column stop characters:
-
-  ` backtick   align left
-  ' quote      align right
-  . dot        align centre
-
-The data is then aligned with the stop characters. For example:
-
-  `---`---
-  1   2
-  3   4
-  --------
-
-Alternatively, if tildes are used instead of hyphens, the data fields are
-comma-separated. Columns can also be specified numerically instead of by
-pattern. This is usually used with CSV data. For example:
-
-  `10`20`30~
-  one, two, three
-  ~~~~~
-
-This format is useful when the data is full of markup so that its final length
-bears little relationship to the input (for example, when there are cross
-references).
-
-By default, tables will be rendered with a frame at the top and bottom, and no
-separators between rows and columns. You can use AsciiDoc "attributes" to
-change this. Attributes are set by a sequence of name=value items in square
-brackets, before the thing to which they apply. For example:
-
-  [frame="none"]
-  `-----`-----
-  11    22
-  33    44
-  ------------
-
-The values for "frame" are "topbot", "sides", "all", or "none". There is also a
-"grid" attribute, whose possible values are "none", "cols", "rows", or "all".
-For example:
-
-  [frame="sides", grid="cols"]
-
-The commas between the attribute settings are important; if they are omitted,
-AsciiDoc ignores the attribute settings.
-
-
-EXIM CONFIGURATION OPTION HEADINGS
-
-Each Exim configuration option is formatted with its name, usage, type, and
-default value on a single line, spread over the line so as to fill it
-completely. The only way I know of aligning text using DocBook is to use a
-table. A special table format has been created to handle this special case. For
-example:
-
-  `..'=
-  %keep_malformed%, Use: 'main', Type: 'boolean', Default: 'false'
-  ===
-
-The first line defines four colums using stop characters, followed by an equals
-character that defines the table's "ruler" character. There is no need to
-define column widths, because the style forces the columns to fill the page
-width. The data is comma-separated.
-
-
-CHANGE BARS
-
-I haven't yet found a way of doing changebars in the printed versions. However,
-it is possible to put a green background behind changed text in the HTML
-version, so the appropriate markup should be used. Before a changed paragraph,
-insert
-
-  [revisionflag="changed"]
-
-This should precede any index settings at the start of the paragraph. If you
-want to do this for a display, you must use the "...." or "&&&" blocks
-described above, because that's the only types that I have set up to support
-it.
-
-
-FUDGES
-
-The current release of "fop", a program for producing PostScript from
-"formatting objects" (fo) data, which is an intermediate output that can be
-generated from DocBook XML, is not very good at page layout. For example, it
-can place a section heading as the last line on a page. I have set up a style
-that provides a means of forcing a page break in order to get round this. (But
-in practice, it happens so often that I have given up trying to use it.)
-
-At the AsciiDoc level, the markup uses a "backend block", which provides a way
-of specifying DocBook output directly. Backend blocks are surrounded by lines
-of plusses, and this particular fudge looks like this:
-
-  ++++++++++++
-  <?hard-pagebreak?>
-  ++++++++++++
-
-Backend blocks are used to insert XML comments into the output, to mark the
-start and end of Exim's command line options. These are used by the x2man
-script that creates the man page.
-
-
-Philip Hazel
-Last updated: 10 June 2005
index 8491909..2287092 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.2 2005/11/10 12:30:13 ph10 Exp $
+$Cambridge: exim/doc/doc-docbook/HowItWorks.txt,v 1.3 2006/02/01 11:01:01 ph10 Exp $
 
 CREATING THE EXIM DOCUMENTATION
 
@@ -22,7 +22,7 @@ bought the Adobe distiller software.)
 A demand for a version in "info" format led me to write a Perl script that
 converted the SGCAL input into a Texinfo file. Because of the somewhat
 restrictive requirements of Texinfo, this script has always needed a lot of
-maintenance, and has never been 100% satisfactory.
+maintenance, and was never totally satisfactory.
 
 The HTML version of the documentation was originally produced from the Texinfo
 version, but later I wrote another Perl script that produced it directly from
@@ -54,8 +54,16 @@ particular form of XML suited to documents that were effectively "books".
 Maintaining an XML document by hand editing is a tedious, verbose, and
 error-prone process. A number of specialized XML text editors were available,
 but all the free ones were at a very primitive stage. I therefore decided to
-keep the master source in AsciiDoc format (described below), from which a
-secondary XML master could be automatically generated.
+keep the master source in AsciiDoc format, from which a secondary XML master
+could be automatically generated.
+
+The first "new" versions of the documents, for the 4.60 release, were generated
+this way. However, there were a number of problems with using AsciiDoc for a
+document as large and as complex as the Exim manual. As a result, I wrote a new
+application called xfpt ("XML From Plain Text") which creates XML from a
+relatively simple and consistent markup language. This application has been
+released for general use, and the master sources for the Exim documentation are
+now in xfpt format.
 
 All the output formats are generated from the XML file. If, in the future, a
 better way of maintaining the XML source becomes available, this can be adopted
@@ -64,14 +72,14 @@ Equally, if better ways of processing the XML become available, they can be
 adopted without affecting the source maintenance.
 
 A number of issues arose while setting this all up, which are best summed up by
-the statement that a lot of the technology is (in 2005) still very immature. It
+the statement that a lot of the technology is (in 2006) still very immature. It
 is probable that trying to do this conversion any earlier would not have been
 anywhere near as successful. The main problems that still bother me are
 described in the penultimate section of this document.
 
-The following sections describe the processes by which the AsciiDoc files are
+The following sections describe the processes by which the xfpt files are
 transformed into the final output documents. In practice, the details are coded
-into a makefile that specifies the chain of commands for each output format.
+into a Makefile that specifies the chain of commands for each output format.
 
 
 REQUIRED SOFTWARE
@@ -81,10 +89,9 @@ run Gentoo Linux, and a lot of things have been installed as dependencies that
 I am not fully aware of. This is what I know about (version numbers are current
 at the time of writing):
 
-. AsciiDoc 6.0.3
+. xfpt 0.00
 
-  This converts the master source file into a DocBook XML file, using a
-  customized AsciiDoc configuration file.
+  This converts the master source file into a DocBook XML file.
 
 . xmlto 0.0.18
 
@@ -94,26 +101,27 @@ at the time of writing):
   things that I have not figured out, to apply the DocBook XSLT stylesheets.
 
 . libxml 1.8.17
-  libxml2 2.6.17
-  libxslt 1.1.12
+  libxml2 2.6.22
+  libxslt 1.1.15
 
   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.66.1
+. xsl-stylesheets-1.68.1
 
   These are the standard DocBook XSL stylesheets.
 
 . fop 0.20.5
 
   FOP is a processor for "formatted objects". It is written in Java. The fop
-  command is a shell script that drives it.
+  command is a shell script that drives it. It is used to generate PostScript
+  and PDF output.
 
 . w3m 0.5.1
 
   This is a text-oriented web brower. It is used to produce the Ascii form of
-  the Exim documentation 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.
 
 . docbook2texi (part of docbook2X 0.8.5)
 
@@ -130,27 +138,8 @@ at the time of writing):
 
   This is used to make a set of "info" files from a Texinfo file.
 
-In addition, there are some locally written Perl scripts. These are described
-below.
-
-
-ASCIIDOC
-
-AsciiDoc (http://www.methods.co.nz/asciidoc/) is a Python script that converts
-an input document in a more-or-less human-readable format into DocBook XML.
-For a document as complex as the Exim specification, the markup is quite
-complex - probably no simpler than the original SGCAL markup - but it is
-definitely easier to work with than XML itself.
-
-AsciiDoc is highly configurable. It comes with a default configuration, but I
-have extended this with an additional configuration file that must be used when
-processing the Exim documents. There is a separate document called AdMarkup.txt
-that describes the markup that is used in these documents. This includes the
-default AsciiDoc markup and the local additions.
-
-The author of AsciiDoc uses the extension .txt for input documents. I find
-this confusing, especially as some of the output files have .txt extensions.
-Therefore, I have used the extension .ascd for the sources.
+In addition, there are a number of locally written Perl scripts. These are
+described below.
 
 
 THE MAKEFILE
@@ -163,13 +152,13 @@ testing purposes. The other five targets are production targets. For example:
   make spec.pdf
 
 This runs the necessary tools in order to create the file spec.pdf from the
-original source spec.ascd. A number of intermediate files are created during
+original source spec.xfpt. A number of intermediate files are created during
 this process, including the master DocBook source, called spec.xml. Of course,
 the usual features of "make" ensure that if this already exists and is
 up-to-date, it is not needlessly rebuilt.
 
 The "test" series of targets were created so that small tests could easily be
-run fairly quickly, because processing even the shortish filter document takes
+run fairly quickly, because processing even the shortish XML document takes
 a bit of time, and processing the main specification takes ages.
 
 Another target is "exim.8". This runs a locally written Perl script called
@@ -180,11 +169,12 @@ enable the script to find the start and end of the options list.
 There is also a "clean" target that deletes all the generated files.
 
 
-CREATING DOCBOOK XML FROM ASCIIDOC
+CREATING DOCBOOK XML FROM XFPT INPUT
 
-There is a single local AsciiDoc configuration file called MyAsciidoc.conf.
-Using this, one run of the asciidoc command creates a .xml file from a .ascd
-file. When this succeeds, there is no output.
+The small amount of local configuration for xfpt is included at the start of
+the two .xfpt files; there are no separate local xfpt configuration files.
+Running the xfpt command creates a .xml file from a .xfpt file. When this
+succeeds, there is no output.
 
 
 DOCBOOK PROCESSING
@@ -213,32 +203,28 @@ THE PRE-XML SCRIPT
 The Pre-xml script copies a .xml file, making certain changes according to the
 options it is given. The currently available options are as follows:
 
--abstract
-
-  This option causes the <abstract> element to be removed from the XML. The
-  source abuses the <abstract> element by using it to contain the author's
-  address so that it appears on the title page verso in the printed renditions.
-  This just gets in the way for the non-PostScript/PDF renditions.
-
 -ascii
 
   This option is used for Ascii output formats. It makes the following
   character replacements:
 
-    &8230;    =>  ...       (sic, no #x)
     &#x2019;  =>  '         apostrophe
-    &#x201C;  =>  "         opening double quote
-    &#x201D;  =>  "         closing double quote
-    &#x2013;  =>  -         en dash
-    &#x2020;  =>  *         dagger
-    &#x2021;  =>  **        double dagger
-    &#x00a0;  =>  a space   hard space
-    &#x00a9;  =>  (c)       copyright
-
-  In addition, this option causes quotes to be put round <literal> text items,
-  and <quote> and </quote> to be replaced by Ascii quote marks. You would think
-  the stylesheet would cope with the latter, but it seems to generate non-Ascii
-  characters that w3m then turns into question marks.
+    &copy;    =>  (c)       copyright
+    &dagger;  =>  *         dagger
+    &Dagger;  =>  **        double dagger
+    &nbsp;    =>  a space   hard space
+    &ndash;   =>  -         en dash
+
+  The apostrophe is specified numerically because that is what xfpt generates
+  from an Ascii single quote character. Non-Ascii characters that are not in
+  this list should not be used without thinking about how they might be
+  converted for the Ascii formats.
+
+  In addition to the character replacements, this option causes quotes to be
+  put round <literal> text items, and <quote> and </quote> to be replaced by
+  Ascii quote marks. You would think the stylesheet would cope with the latter,
+  but it seems to generate non-Ascii characters that w3m then turns into
+  question marks.
 
 -bookinfo
 
@@ -259,28 +245,36 @@ options it is given. The currently available options are as follows:
 
 -noindex
 
-  Remove the XML to generate a Concept Index and an Options index.
+  Remove the XML to generate a Concept Index and an Options index. The source
+  document has two types of index entry, for a concept and an options index.
+  However, no index is required for the .txt and .texinfo outputs.
 
 -oneindex
 
   Remove the XML to generate a Concept and an Options Index, and add XML to
-  generate a single index.
+  generate a single index. The only output processor that supports multiple
+  indexes is the processor that produces "formatted objects" for PostScript and
+  PDF output. The HTML processor ignores the XML settings for multiple indexes
+  and just makes one unified index. Specifying two indexes gets you two copies
+  of the same index, so this has to be changed.
 
-The source document has two types of index entry, for a concept and an options
-index. However, no index is required for the .txt and .texinfo outputs.
-Furthermore, the only output processor that supports multiple indexes is the
-processor that produces "formatted objects" for PostScript and PDF output. The
-HTML processor ignores the XML settings for multiple indexes and just makes one
-unified index. Specifying two indexes gets you two copies of the same index, so
-this has to be changed.
+-optbreak
+
+  Look for items of the form <option>...</option> and <varname>...</varname> in
+  ordinary paragraphs, and insert &#x200B; after each underscore in the
+  enclosed text. The same is done for any word containing four or more upper
+  case letters (compile-time options in the Exim specification). The character
+  &#x200B; is a zero-width space. This means that the line may be split after
+  one of these underscores, but no hyphen is inserted.
 
 
 CREATING POSTSCRIPT AND PDF
 
-These two output formats are created in three stages. First, the XML is
-pre-processed. For the filter document, the <bookinfo> element is removed so
-that no title page is generated, but for the main specification, no changes are
-currently made.
+These two output formats are created in three stages, with an additional fourth
+stage for PDF. First, the XML is pre-processed by the Pre-xml script. For the
+filter document, the <bookinfo> element is removed so that no title page is
+generated. For the main specification, the only change is to insert line
+breakpoints via -optbreak.
 
 Second, the xmlto command is used to produce a "formatted objects" (.fo) file.
 This process uses the following stylesheets:
@@ -300,10 +294,14 @@ modified. The template is processed with xsltproc to produce the stylesheet.
 All this apparatus is appallingly heavyweight. The processing is also very slow
 in the case of the specification document. However, there should be no errors.
 
-In the third and final part of the processing, the .fo file that is produced by
-the xmlto command is processed by the fop command to generate either PostScript
-or PDF. This is also very slow, and you get a whole slew of errors, of which
-these are a sample:
+The reference book that saved my life while I was trying to get all this to
+work is "DocBook XSL, The Complete Guide", third edition (2005), by Bob
+Stayton, published by Sagehill Enterprises.
+
+In the third part of the processing, the .fo file that is produced by the xmlto
+command is processed by the fop command to generate either PostScript or PDF.
+This is also very slow, and you get a whole slew of errors, of which these are
+a sample:
 
   [ERROR] property - "background-position-horizontal" is not implemented yet.
 
@@ -330,14 +328,39 @@ The last one is particularly meaningless gobbledegook. Some of the errors and
 warnings are repeated many times. Nevertheless, it does eventually produce
 usable output, though I have a number of issues with it (see a later section of
 this document). Maybe one day there will be a new release of fop that does
-better. Maybe there will be some other means of producing PostScript and PDF
-from DocBook XML. Maybe porcine aeronautics will really happen.
+better (there are now signs - February 2006 - that this may be happening).
+Maybe there will be some other means of producing PostScript and PDF from
+DocBook XML. Maybe porcine aeronautics will really happen.
+
+The PDF file that is produced by this process has one problem: the pages, as
+shown by acroread in its thumbnail display, are numbered sequentially from one
+to the end. Those numbers do not correspond with the page numbers of the body
+of the document, which makes finding a page from the index awkward. There is a
+facility in the PDF format to give pages appropriate "labels", but I cannot
+find a way of persuading fop to generate these. Fortunately, it is possibly to
+fix up the PDF to add page labels. I wrote a script called PageLabelPDF which
+does this. They are shown correctly by acroread, but not by GhostScript (gv).
+
+
+THE PAGELABELPDF SCRIPT
+
+This script reads the standard input and writes the standard output. It
+searches for the PDF object that sets data in its "Catalog", and adds
+appropriate information about page labels. The number of front-matter pages
+(those before chapter 1) is hard-wired into this script as 12 because I could
+not find a way of determining it automatically. As the current table of
+contents finishes near the top of the 11th page, there is plenty of room for
+expansion, so it is unlikely to be a problem.
+
+Having added data to the PDF file, the script then finds the xref table at the
+end of the file, and adjusts its entries to allow for the added text. This
+simple processing seems to be enough to generate a new, valid, PDF file.
 
 
 CREATING HTML
 
 Only two stages are needed to produce HTML, but the main specification is
-subsequently postprocessed. The Pre-xml script is called with the -abstract and
+subsequently postprocessed. The Pre-xml script is called with the -optbreak and
 -oneindex options to preprocess the XML. Then the xmlto command creates the
 HTML output directly. For the specification document, a directory of files is
 created, whereas the filter document is output as a single HTML page. The
@@ -347,9 +370,13 @@ following stylesheets are used:
   (2) MyStyle-html.xsl
   (3) MyStyle.xsl
 
-The first stylesheet references the chunking or non-chunking standard
+The first stylesheet references the chunking or non-chunking standard DocBook
 stylesheet, as appropriate.
 
+You may see a number of these errors when creating HTML: "Revisionflag on
+unexpected element: literallayout (Assuming block)". They seem to be harmless;
+the output appears to be what is intended.
+
 The original HTML that I produced from the SGCAL input had hyperlinks back from
 chapter and section titles to the table of contents. These links are not
 generated by xmlto. One of the testers pointed out that the lack of these
@@ -387,10 +414,11 @@ so the logic is somewhat different.
 
 CREATING TEXT FILES
 
-This happens in four stages. The Pre-xml script is called with the -abstract,
--ascii and -noindex options to remove the <abstract> element, convert the input
-to Ascii characters, and to disable the production of an index. Then the xmlto
-command converts the XML to a single HTML document, using these stylesheets:
+This happens in four stages. The Pre-xml script is called with the -ascii,
+-optbreak, and -noindex options to convert the input to Ascii characters,
+insert line break points, and disable the production of an index. Then the
+xmlto command converts the XML to a single HTML document, using these
+stylesheets:
 
   (1) MyStyle-txt-html.xsl
   (2) MyStyle-html.xsl
@@ -404,21 +432,25 @@ document title; the character is not in the original input.
 
 The w3m command is used with the -dump option to turn the HTML file into Ascii
 text, but this contains multiple sequences of blank lines that make it look
-awkward, so, finally, a local Perl script called Tidytxt is used to convert
-sequences of blank lines into a single blank line.
+awkward. Furthermore, chapter and section titles do not stand out very well. A
+local Perl script called Tidytxt is used to post-process the output. First, it
+converts sequences of blank lines into a single blank lines. Then it searches
+for chapter and section headings. Each chapter heading is uppercased, and
+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.
 
 
 CREATING INFO FILES
 
-This process starts with the same Pre-xml call as for text files. The
-<abstract> element is deleted, non-ascii characters in the source are
-transliterated, and the <index> elements are removed. The docbook2texi script
-is then called to convert the XML file into a Texinfo file. However, this is
-not quite enough. The converted file ends up with "conceptindex" and
-"optionindex" items, which are not recognized by the makeinfo command. An
-in-line call to Perl in the Makefile changes these to "cindex" and "findex"
-respectively in the final .texinfo file. Finally, a call of makeinfo creates a
-set of .info files.
+This process starts with the same Pre-xml call as for text files. Non-ascii
+characters in the source are transliterated, and the <index> elements are
+removed. The docbook2texi script is then called to convert the XML file into a
+Texinfo file. However, this is not quite enough. The converted file ends up
+with "conceptindex" and "optionindex" items, which are not recognized by the
+makeinfo command. An in-line call to Perl in the Makefile changes these to
+"cindex" and "findex" respectively in the final .texinfo file. Finally, a call
+of makeinfo creates a set of .info files.
 
 There is one apparently unconfigurable feature of docbook2texi: it does not
 seem possible to give it a file name for its output. It chooses a name based on
@@ -431,14 +463,14 @@ inline Perl call, which makes a .texinfo file.
 CREATING THE MAN PAGE
 
 I wrote a Perl script called x2man to create the exim.8 man page from the
-DocBook XML source. I deliberately did NOT start from the AsciiDoc source,
+DocBook XML source. I deliberately did NOT start from the xfpt source,
 because it is the DocBook source that is the "standard". This comment line in
 the DocBook source marks the start of the command line options:
 
   <!-- === Start of command line options === -->
 
 A similar line marks the end. If at some time in the future another way other
-than AsciiDoc is used to maintain the DocBook source, it needs to be capable of
+than xfpt is used to maintain the DocBook source, it needs to be capable of
 maintaining these comments.
 
 
@@ -448,18 +480,16 @@ There are a number of unresolved problems with producing the Exim documentation
 in the manner described above. I will describe them here in the hope that in
 future some way round them can be found.
 
-(1)  Errors in the toolchain
-
-     When a whole chain of tools is processing a file, an error somewhere in
-     the middle is often very hard to debug. For instance, an error in the
-     AsciiDoc might not show up until an XML processor throws a wobbly because
+(1)  When a whole chain of tools is processing a file, an error somewhere
+     in the middle is often very hard to debug. For instance, an error in the
+     xfpt file might not show up until an XML processor throws a wobbly because
      the generated XML is bad. You have to be able to read XML and figure out
      what generated what. One of the reasons for creating the "test" series of
      targets was to help in checking out these kinds of problem.
 
 (2)  There is a mechanism in XML for marking parts of the document as
-     "revised", and I have arranged for AsciiDoc markup to use it. However, at
-     the moment, the only output format that pays attention to this is the HTML
+     "revised", and I have arranged for xfpt markup to use it. However, at the
+     moment, the only output format that pays attention to this is the HTML
      output, which sets a green background. There are therefore no revision
      marks (change bars) in the PostScript, PDF, or text output formats as
      there used to be. (There never were for Texinfo.)
@@ -502,13 +532,23 @@ future some way round them can be found.
 (9)  The fop processor does not support "fi" ligatures, not even if you put the
      appropriate Unicode character into the source by hand.
 
-(10) There are no diagrams in the new documentation. This is something I could
-     work on. The previously-used Aspic command for creating line art from a
+(10) There are no diagrams in the new documentation. This is something I hope
+     to work on. The previously used Aspic command for creating line art from a
      textual description can output Encapsulated PostScript or Scalar Vector
      Graphics, which are two standard diagram representations. Aspic could be
      formally released and used to generate output that could be included in at
      least some of the output formats.
 
+(11) The use of a "zero-width space" works well as a way of specifying that
+     Exim option names can be split, without hyphens, over line breaks.
+     However, when an option is not split, if the line is very "loose", the
+     zero-width space is expanded, along with other spaces. This is a totally
+     crazy thing to, but unfortunately it is suggested by the Unicode
+     definition of the zero-width space, which says "its presence between two
+     characters does not prevent increased letter spacing in justification".
+     It seems that the implementors of fop have understood "letter spacing"
+     also to include "word spacing". Sigh.
+
 The consequence of (7), (8), and (9) is that the PostScript/PDF output looks as
 if it comes from some of the very early attempts at text formatting of around
 20 years ago. We can only hope that 20 years' progress is not going to get
@@ -517,10 +557,9 @@ lost, and that things will improve in this area.
 
 LIST OF FILES
 
-AdMarkup.txt                   Describes the AsciiDoc markup that is used
+Markup.txt                     Describes the xfpt markup that is used
 HowItWorks.txt                 This document
 Makefile                       The makefile
-MyAsciidoc.conf                Localized AsciiDoc configuration
 MyStyle-chunk-html.xsl         Stylesheet for chunked HTML output
 MyStyle-filter-fo.xsl          Stylesheet for filter fo output
 MyStyle-fo.xsl                 Stylesheet for any fo output
@@ -532,17 +571,15 @@ MyStyle.xsl                    Stylesheet for all output
 MyTitleStyle.xsl               Stylesheet for spec title page
 MyTitlepage.templates.xml      Template for creating MyTitleStyle.xsl
 Myhtml.css                     Experimental css stylesheet for HTML output
+PageLabelPDF                   Script to postprocess PDF
 Pre-xml                        Script to preprocess XML
 TidyHTML-filter                Script to tidy up the filter HTML output
 TidyHTML-spec                  Script to tidy up the spec HTML output
 Tidytxt                        Script to compact multiple blank lines
-filter.ascd                    AsciiDoc source of the filter document
-spec.ascd                      AsciiDoc source of the specification document
+filter.xfpt                    xfpt source of the filter document
+spec.xfpt                      xfpt source of the specification document
 x2man                          Script to make the Exim man page from the XML
 
-The file Myhtml.css was an experiment that was not followed through. It is
-mentioned in a comment in MyStyle-html.xsl, but is not at present in use.
-
 
 Philip Hazel
-Last updated: 10 June 2005
+Last updated: 31 January 2006
index 38e6ebf..0495b58 100644 (file)
@@ -1,6 +1,6 @@
-# $Cambridge: exim/doc/doc-docbook/Makefile,v 1.6 2005/12/20 15:45:02 ph10 Exp $
+# $Cambridge: exim/doc/doc-docbook/Makefile,v 1.7 2006/02/01 11:01:01 ph10 Exp $
 
-# Make file for Exim documentation from Asciidoc source.
+# Make file for Exim documentation from xfpt source.
 
 notarget:;    @echo "** You must specify a target, in the form x.y, where x is 'filter', 'spec',"
              @echo "** or 'test', and y is 'xml', 'fo', 'ps', 'pdf', 'html', 'txt', or 'info'."
@@ -10,7 +10,7 @@ notarget:;    @echo "** You must specify a target, in the form x.y, where x is '
 
 ############################## MAN PAGE ################################
 
-exim.8: spec.xml
+exim.8:       spec.xml x2man
              ./x2man
 
 ########################################################################
@@ -18,8 +18,8 @@ exim.8: spec.xml
 
 ############################### FILTER #################################
 
-filter.xml:   filter.ascd MyAsciidoc.conf
-             asciidoc -d book -b docbook -f MyAsciidoc.conf filter.ascd
+filter.xml:   filter.xfpt
+             xfpt filter.xfpt
 
 filter-fo.xml: filter.xml Pre-xml
              ./Pre-xml -bookinfo <filter.xml >filter-fo.xml
@@ -28,7 +28,10 @@ filter-html.xml: filter.xml Pre-xml
              ./Pre-xml -html <filter.xml >filter-html.xml
 
 filter-txt.xml: filter.xml Pre-xml
-             ./Pre-xml -ascii -html <filter.xml >filter-txt.xml
+             ./Pre-xml -ascii -html -quoteliteral <filter.xml >filter-txt.xml
+
+filter-info.xml: filter.xml Pre-xml
+             ./Pre-xml -ascii -html <filter.xml >filter-info.xml
 
 filter.fo:    filter-fo.xml MyStyle-filter-fo.xsl MyStyle-fo.xsl MyStyle.xsl
              /bin/rm -rf filter.fo filter-fo.fo
@@ -48,23 +51,25 @@ filter.pdf:   filter.fo
              fop filter.fo -pdf filter-tmp.pdf
              mv filter-tmp.pdf filter.pdf
 
-filter.html:  filter-html.xml TidyHTML-filter MyStyle-nochunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+filter.html:  filter-html.xml TidyHTML-filter MyStyle-nochunk-html.xsl \
+                MyStyle-html.xsl MyStyle.xsl
              /bin/rm -rf filter.html filter-html.html
              xmlto -x MyStyle-nochunk-html.xsl html-nochunks filter-html.xml
              /bin/mv -f filter-html.html filter.html
              ./TidyHTML-filter
 
-filter.txt:   filter-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+filter.txt:   filter-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl \
+                MyStyle.xsl
              /bin/rm -rf filter-txt.html
              xmlto -x MyStyle-txt-html.xsl html-nochunks filter-txt.xml
-             w3m -dump filter-txt.html >filter.txt
+             w3m -dump filter-txt.html | ./Tidytxt >filter.txt
 
 # I have not found a way of making docbook2texi write its output anywhere
 # other than the file name that it makes up. The --to-stdout option does not
 # work.
 
-filter.info:  filter-txt.xml
-             docbook2texi filter-txt.xml
+filter.info:  filter-info.xml
+             docbook2texi filter-info.xml
              perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
                <exim_filtering.texi | Tidytxt >filter.texinfo
              /bin/rm -rf exim_filtering.texi
@@ -75,19 +80,25 @@ filter.info:  filter-txt.xml
 
 ################################ SPEC ##################################
 
-spec.xml:     spec.ascd MyAsciidoc.conf
-             asciidoc -d book -b docbook -f MyAsciidoc.conf spec.ascd
+spec.xml:     spec.xfpt
+             xfpt spec.xfpt
 
 spec-fo.xml:  spec.xml Pre-xml
-             ./Pre-xml <spec.xml >spec-fo.xml
+             ./Pre-xml -optbreak <spec.xml >spec-fo.xml
 
 spec-html.xml: spec.xml Pre-xml
-             ./Pre-xml -abstract -html -oneindex <spec.xml >spec-html.xml
+             ./Pre-xml -html -oneindex \
+               <spec.xml >spec-html.xml
 
 spec-txt.xml: spec.xml Pre-xml
-             ./Pre-xml -abstract -ascii -html -noindex <spec.xml >spec-txt.xml
+             ./Pre-xml -ascii -html -noindex -quoteliteral \
+               <spec.xml >spec-txt.xml
+
+spec-info.xml: spec.xml Pre-xml
+             ./Pre-xml -ascii -html -noindex <spec.xml >spec-info.xml
 
-spec.fo:      spec-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl MyTitleStyle.xsl
+spec.fo:      spec-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl \
+              MyTitleStyle.xsl
              /bin/rm -rf spec.fo spec-fo.fo
              xmlto -x MyStyle-spec-fo.xsl fo spec-fo.xml
              /bin/mv -f spec-fo.fo spec.fo
@@ -99,28 +110,31 @@ spec.ps:      spec.fo
              mv spec-tmp.ps spec.ps
 
 # Do not use ps2pdf from the PS version; better PDF is generated directly. It
-# contains cross links etc.
+# contains cross links etc. We post-process it to add page label information
+# so that the page identifiers shown by acroread are the correct page numbers.
 
-spec.pdf:     spec.fo
+spec.pdf:     spec.fo PageLabelPDF
              FOP_OPTS=-Xmx512m fop spec.fo -pdf spec-tmp.pdf
-             mv spec-tmp.pdf spec.pdf
+             ./PageLabelPDF <spec-tmp.pdf >spec.pdf
 
-spec.html:    spec-html.xml TidyHTML-spec MyStyle-chunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+spec.html:    spec-html.xml TidyHTML-spec MyStyle-chunk-html.xsl \
+                MyStyle-html.xsl MyStyle.xsl
              /bin/rm -rf spec.html
              xmlto -x MyStyle-chunk-html.xsl -o spec.html html spec-html.xml
              ./TidyHTML-spec
 
-spec.txt:     spec-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+spec.txt:     spec-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl \
+                MyStyle.xsl
              /bin/rm -rf spec-txt.html
              xmlto -x MyStyle-txt-html.xsl html-nochunks spec-txt.xml
-             w3m -dump spec-txt.html | Tidytxt >spec.txt
+             w3m -dump spec-txt.html | ./Tidytxt >spec.txt
 
 # I have not found a way of making docbook2texi write its output anywhere
 # other than the file name that it makes up. The --to-stdout option does not
 # work.
 
-spec.info:    spec-txt.xml
-             docbook2texi spec-txt.xml
+spec.info:    spec-info.xml
+             docbook2texi spec-info.xml
              perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
                <the_exim_mta.texi >spec.texinfo
              /bin/rm -rf the_exim_mta.texi
@@ -133,19 +147,24 @@ spec.info:    spec-txt.xml
 
 # These targets (similar to the above)  are for running little tests.
 
-test.xml:     test.ascd MyAsciidoc.conf
-             asciidoc -d book -b docbook -f MyAsciidoc.conf test.ascd
+test.xml:     test.xfpt
+             xfpt test.xfpt
 
 test-fo.xml:  test.xml Pre-xml
              ./Pre-xml <test.xml >test-fo.xml
 
 test-html.xml: test.xml Pre-xml
-             ./Pre-xml -abstract -html -oneindex <test.xml >test-html.xml
+             ./Pre-xml -html -oneindex <test.xml >test-html.xml
 
 test-txt.xml: test.xml Pre-xml
-             ./Pre-xml -abstract -ascii -html -noindex <test.xml >test-txt.xml
+             ./Pre-xml -ascii -html -noindex -quoteinfo \
+               <test.xml >test-txt.xml
+
+test-info.xml: test.xml Pre-xml
+             ./Pre-xml -ascii -html -noindex <test.xml >test-info.xml
 
-test.fo:      test-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl MyTitleStyle.xsl
+test.fo:      test-fo.xml MyStyle-spec-fo.xsl MyStyle-fo.xsl MyStyle.xsl \
+                MyTitleStyle.xsl
              /bin/rm -rf test.fo test-fo.fo
              xmlto -x MyStyle-spec-fo.xsl fo test-fo.xml
              /bin/mv -f test-fo.fo test.fo
@@ -163,12 +182,14 @@ test.pdf:     test.fo
              fop test.fo -pdf test-tmp.pdf
              mv test-tmp.pdf test.pdf
 
-test.html:    test-html.xml MyStyle-nochunk-html.xsl MyStyle-html.xsl MyStyle.xsl
+test.html:    test-html.xml MyStyle-nochunk-html.xsl MyStyle-html.xsl \
+                MyStyle.xsl
              /bin/rm -rf test.html test-html.html
              xmlto -x MyStyle-nochunk-html.xsl html-nochunks test-html.xml
              /bin/mv -f test-html.html test.html
 
-test.txt:     test-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle.xsl
+test.txt:     test-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl \
+                MyStyle.xsl
              /bin/rm -rf test-txt.html
              xmlto -x MyStyle-txt-html.xsl html-nochunks test-txt.xml
              w3m -dump test-txt.html | Tidytxt >test.txt
@@ -177,8 +198,8 @@ test.txt:     test-txt.xml Tidytxt MyStyle-txt-html.xsl MyStyle-html.xsl MyStyle
 # other than the file name that it makes up. The --to-stdout option does not
 # work.
 
-test.info:    test-txt.xml
-             docbook2texi test-txt.xml
+test.info:    test-info.xml
+             docbook2texi test-info.xml
              perl -ne 's/conceptindex/cindex/;s/optionindex/findex/;print;' \
                <short_title.texi >test.texinfo
              /bin/rm -rf short_title.texi
diff --git a/doc/doc-docbook/Markup.txt b/doc/doc-docbook/Markup.txt
new file mode 100644 (file)
index 0000000..9220eb4
--- /dev/null
@@ -0,0 +1,354 @@
+$Cambridge: exim/doc/doc-docbook/Markup.txt,v 1.1 2006/02/01 11:01:01 ph10 Exp $
+
+XFPT MARKUP USED IN THE EXIM DOCUMENTATION
+------------------------------------------
+
+This file contains a summary of the xfpt markup that is used in the source
+files of the Exim documentation. The source files are in plain text that can be
+edited by any text editor. They are converted by the xfpt application into
+DocBook XML for subsequent processing into the various output formats.
+
+The advantage of using xfpt format as a "back end" is that is uses relatively
+simple markup in the majority of the text, making it easier to read and edit.
+The disadvantage is that it is tricky to deal with complicated formatting,
+though that is probably true of any markup language, and is certainly true of
+XML itself.
+
+The Exim documentation uses standard xfpt DocBook markup with a few additions.
+The definitions of the additions that are used in spec.xfpt and filter.xfpt,
+respectively, appear at the start of each of those files. In this file we
+describe all the markup briefly, both the standard and additional items. See
+the xfpt specification for more details.
+
+Markup in xfpt is indicated in one of two ways: lines that start with a dot are
+interpreted specially ("directive lines"), and ampersand characters within the
+text always introduce a markup item. Recognized sequences that start with an
+ampersand are called "flags". Some of these have "partners" that do not
+necessarily start with an ampersand, but these must always appear after a flag
+that starts with an ampersand. There are no other forms of markup.
+
+There are two text characters that are not printed as their Ascii graphics.
+These are the grave accent and the single quote. They are automatically
+converted into opening and closing typographic quote characters in non-literal
+text. Other input characters that are not part of some markup always stand for
+themselves.
+
+
+CONTINUATION LINES
+
+Any line of input can be continued onto the next line by ending the first line
+with the sequence &&&. The line break and any leading spaces at the start of
+the following line are ignored. This processing happens as the lines are read
+in, before any other processing.
+
+
+SPECIAL CHARACTERS IN TEXT
+
+The following flag sequences are translated to non-Ascii characters:
+
+  &--     en-dash (generates &ndash;)
+  &~      hard space (generates &nbsp;)
+
+The following two flags are for use on Exim option definitions. They are
+designed for use within italic text; however, they terminate and restart the
+italic so that the daggers themselves are roman. These flags do not work
+outside italic text.
+
+  &!!     dagger         (generates </emphasis>&dagger;<emphasis>)
+  &!?     double dagger  (generates </emphasis>&Dagger;<emphasis>)
+
+Any Unicode character can be accessed by giving its name or code point in the
+normal XML fashion. For example, &dagger; gives a dagger and &copy; gives a
+copyright symbol.
+
+
+AMPERSANDS AS DATA
+
+If you really do want an ampersand character in the text, you must type two
+ampersands. This is a flag that expands to &amp; in the output. Of course, you
+could also just type &amp; yourself; the flag is just for convenience.
+
+
+PAIRED FLAGS
+
+There are several sequences that use pairs of markup flags, surrounding some
+enclosed text, which is represented as ... in the following list:
+
+  &'...'&    italic: maps to <emphasis>...</emphasis>
+             used for email addresses, domains, local
+             parts, header names, user names
+
+  &*...*&    bold: maps to <emphasis role="bold">...</emphasis>
+             used for things like &*Note:*&
+
+  &`...`&    monospaced text: maps to <literal>...</literal>
+             used for literal quoting in mixed-font text
+
+  &$...$&    Exim variable: maps to <varname>$...</varname>
+             note that the leading dollar is automatically inserted
+
+  &%...%&    Exim option, command line option: maps to <option>...</option>
+
+  &(...)&    Exim driver name, Unix command name, filter command name:
+             maps to <command>...</command>
+
+  &[...]&    C function: maps to <function>...</function>
+
+  &_..._&    file name: maps to <filename>...</filename>
+
+  &"..."&    put word in quotation marks: maps to <quote>...</quote>
+
+For example,
+
+  This is an &'italic phrase'&. This is a &_filename_& and a &$variable$&.
+  This &"word"& is in quote marks.
+
+It is important to use &"..."& rather than literal quotes so that different
+renditions can be used for different forms of output.
+
+These markup items can be nested, but not overlapped. However, the resulting
+XML from nested constructions is not always valid, so nesting is best avoided
+if possible. For example, &`xxx&'yyy'&xxx`& generates an <emphasis> item within
+a <literal> item, and the DocBook DTD does not allow that. However, a
+combination that does work is <literal> within an <emphasis>, so that is what
+you have to use if you want an italic or boldface monospaced font. For example,
+you have to use &*&`bold mono`&*& and not &`&*bold mono*&`&.
+
+
+LITERAL XML
+
+You can include blocks of literal XML between these two directive lines:
+
+  .literal xml
+  ...
+  .literal off
+
+There are some examples at the start of the Exim specification. You can also
+include individual XML elements by enclosing them in &<...>& but at the time of
+writing there are no examples of this usage in the Exim documentation.
+
+
+COMMENTS
+
+You can include comments that will not be copied to the XML document by
+starting a line with a dot followed by a space. You can include comments that
+are copied to the XML by either of the literal XML methods just described.
+
+
+URL REFERENCES
+
+To refer to a URL, use &url, followed by parentheses that can enclose one or
+two arguments, comma separated. The second, if present, is used as the
+displayed text. If there is only one argument, it is used both as the displayed
+text and as the URL. For example, here is a reference to
+&url(http://www.exim.org/,the exim home page). In HTML output, all you see is
+the display text; in printed output you see something like "the exim home page
+[http://www.exim.org/]". The URL is printed in a bold font.
+
+
+CHAPTERS AND SECTIONS
+
+The directives .chapter and .section mark the beginnings of chapters and
+sections. They are followed by a title in quotes, and optionally by up to two
+more arguments. Either single or double quotes can be used, and if you need a
+quote of the type being used as a delimiter within the string, it must be
+doubled. (Quotes are not in fact needed if the title contains no white space,
+but this is rare.)
+
+The second argument, if present and not an empty string, is an id for
+cross-references. For example:
+
+  .chapter "Environment for running local transports" "CHAPenvironment"
+
+To refer to a cross-reference point, enclose the name in &<<...>>&. For
+example:
+
+  See section &<<SECTexample>>&.
+
+Chapter titles are used for running feet in the PostScript and PDF forms of the
+manual. Sometimes they are too long, causing them to be split in an ugly way.
+The solution to this is to define a short title for the running feet as the
+third argument for .chapter or .section, like this:
+
+  .chapter "Environment for running local transports" "CHAPenvironment" &&&
+           "Environment for local transports"
+
+Note the use of &&& in this example to continue the logical input line. If you
+need to specify a third argument without a second argument, the second argument
+must be given as an empty string in quotes.
+
+
+DISPLAYS
+
+There are two forms of text display. Displayed blocks of literal text are
+started by .code and terminated by .endd:
+
+  .code
+  # Exim filter
+  deliver baggins@rivendell.middle-earth.example
+  .endd
+
+No flags are recognized in such blocks, which are displayed in a monospaced
+font.
+
+Blocks of text between .display and .endd are displayed in the current font,
+with the lines processed for flags as in normal paragraphs, but keeping the
+line layout. Flags can be used in the block to specify different fonts or
+special characters. For example:
+
+  .display
+  &`\n`&   is replaced by a newline
+  &`\r`&   is replaced by a carriage return
+  &`\t`&   is replaced by a tab
+  .endd
+
+
+BLOCK QUOTES
+
+Text between .blockquote and .endblockquote is forced to start a new paragraph
+and is wrapped in a <blockquote> element.
+
+
+INDEX ENTRIES
+
+To create an index entry, include a line like one of these:
+
+  .cindex "primary text" "secondary text"
+  .oindex "primary text" "secondary text"
+
+The first is for the "concept index" and the second is for the "options index".
+Not all forms of output distinguish between these - sometimes there is just one
+index.
+
+The index for the Exim reference manual has a number of "see also" entries.
+These are coded in raw XML at the start of the source file.
+
+
+LISTS
+
+Bulleted (itemized) lists are started by .ilist, and ordered (numbered) lists
+are started by .olist, which can be followed by "arabic", "loweralpha",
+"lowerroman", "upperalpha", or "upperroman" to indicate the type of numeration
+that is wanted. Each new item is started by .next, and the whole list is
+terminated by .endlist. Lists can be nested. For example:
+
+  .ilist
+  The first item in the itemized list.
+  .olist lowerroman
+  The first item in the nested, numbered list
+  .next
+  The next item in the nested, numbered list.
+  .endlist
+  Continuing with the first item in the itemized list.
+  .next
+  The next item in the itemized list.
+  .endlist
+
+Variable lists are used for Exim command line options and similar things. They
+map into XML <variablelist> items. Start the list with .vlist and end it with
+.endlist. Each item starts with a .vitem line, followed by its description. The
+argument to .vitem must be quoted if it contains spaces. For example:
+
+  .vlist
+  .vitem &*--*&
+  This is a pseudo-option whose only purpose is to terminate the options and
+  therefore to cause subsequent command line items to be treated as arguments
+  rather than options, even if they begin with hyphens.
+
+  .vitem &*--help*&
+  This option causes Exim to output a few sentences stating what it is.
+  The same output is generated if the Exim binary is called with no options and
+  no arguments.
+  ...
+  .endlist
+
+
+TABLES
+
+The .itable macro directive in xfpt can be used to specify an informal table.
+See the specification for details. The Exim specification uses this directly in
+one place, but most of its tables contain only two columns, for which a
+cut-down macro called .table2 has been defined. Its arguments are the widths of
+the columns, defaulting to 190pt and 300pt, which are suitable for the many
+tables that appear at the start of the global options definition chapter. Each
+row in a table is defined by a .row macro, and the table ends with .endtable.
+For example:
+
+  .table2 100pt
+  .row &_OptionLists.txt_&   "list of all options in alphabetical order"
+  .row &_dbm.discuss.txt_&   "discussion about DBM libraries"
+  ...
+  .endtable
+
+This example overrides the width of the first column. The first arguments of
+the .row macro do not need quotes, because they contain no white space, but
+quotes could have been used.
+
+
+EXIM CONFIGURATION OPTION HEADINGS
+
+Each Exim configuration option is formatted with its name, usage, type, and
+default value on a single output line, spread over the line so as to fill it
+completely. The only way I know of aligning text using DocBook is to use a
+table. The .option macro defines such a table and inserts its four arguments
+into the cells. For example:
+
+  .option acl_not_smtp_mime main string&!! unset
+  This option causes...
+
+The macro contains the font definitions and the heading words "Use", "Type",
+and "Default", so you do not have to supply them. Notice the use of the &!!
+flag to put a dagger after the word "string".
+
+
+CHANGE BARS
+
+I have not yet found a way of producing change bars in the PostScript and PDF
+versions of the documents. However, it is possible to put a green background
+behind changed text in the HTML version, so the appropriate markup should be
+used in the source. There is a facility in xfpt for setting the "revisionflag"
+attribute on appropriate XML elements. There is also a macro called .new which
+packages this up for use in three different ways. One or more large text items
+can be placed between .new and .wen ("wen" is "new" backwards). For example:
+
+  This paragraph is not flagged as new.
+  .new
+  This is a new paragraph that contains a display:
+  .display
+  whatever
+  .endd
+  This is the next paragraph.
+  .wen
+  Here is the next, unmarked, paragraph.
+
+When called without an argument, .new terminates the current paragraph, and
+.wen always does so. Therefore, even though there are no blank lines before
+.new or .wen above, the marked text will be in a paragraph of its own. You
+can, of course, put in blank lines if you wish, and it is probably clearer to
+do so.
+
+If want to mark just a few words inside a paragraph as new, you can call the
+.new macro with an argument. The macro can be called either as a directive or
+as an inline macro call, which takes the form of an ampersand followed by the
+name, with the argument in parentheses. For example:
+
+  This is a paragraph that has
+  .new "a few marked words"
+  within it. Here are &new(some more) marked words.
+
+The effect of this is to generate a <phrase> XML element with the revisionflag
+attribute set. The .wen macro is not used in this case.
+
+If you want to mark a whole table as new, .new and .wen can be used to surround
+it as described above. However, current DocBook processors do not seem to
+recognize the "revisionflag" attribute on individual rows and table entries.
+You can, nevertheless, mark the contents of individual table entries as changed
+by using an inline macro call. For example:
+
+  .row "&new(some text)" "...."
+
+Each such entry must be separately marked. If there are more than one or two,
+it may be easier just to mark the entire table.
+
+Philip Hazel
+Last updated: 25 January 2006
diff --git a/doc/doc-docbook/MyAsciidoc.conf b/doc/doc-docbook/MyAsciidoc.conf
deleted file mode 100644 (file)
index 316e167..0000000
+++ /dev/null
@@ -1,212 +0,0 @@
-# $Cambridge: exim/doc/doc-docbook/MyAsciidoc.conf,v 1.2 2005/11/10 12:30:13 ph10 Exp $
-
-# Asciidoc configuration customization for creating the DocBook XML sources
-# of the Exim specification and the filter document.
-
-[miscellaneous]
-newline=\n
-
-[quotes]
-_=filename
-$=varname
-%=option
-^=command
-^^=function
-^%|%^=parameter
-``|''=quoted
-
-[tags]
-strong=<emphasis role="bold">|</emphasis>
-
-filename=<filename>|</filename>
-varname=<varname>$|</varname>
-option=<option>|</option>
-command=<command>|</command>
-function=<function>|</function>
-parameter=<parameter>|</parameter>
-quoted=<quote>|</quote>
-
-
-[replacements]
-# Nothing - this is for disambiguating markup
-"##"=
-
-# -- En dash
-(^|[^-])--($|[^-])=\1&#x2013;\2
-
-# --- Em dash
-(^|\s+)---($|\s+)=\1&#x8212;\2
-
-# -- Hard space
-~=&#x00a0;
-
-# ' automatic apostrophe
-([A-Za-z0-9])'([A-Za-z\s])=\1&#x2019;\2
-
-# daggers
-!!=&#x2020;
-!\?=&#x2021;
-
-# The default markup recognizes subscripts and superscripts using tilde and
-# circumflex. We don't want this. These settings manage to turn off the
-# effect, while still allowing tilde to be recognized as a hard space.
-\^(.+?)\^=^\1^
-~(.+?)~=~\1~
-
-
-[attributes]
-# Manual apostrophe: needed for an apostrophe after something quoted, because
-# I can't get the automatic one to work in that situation
-ap=&#x2019;
-
-# Manual tilde: tilde is defined as a hard space, and it doesn't seem possible
-# to quote is using a backslash.
-tl=&#x007e;
-
-# Two hyphens, to stop them being treated as an en dash
-hh=&#x002d;&#x002d;
-
-# Percent: causes confusion with the quote otherwise
-pc=&#x0025;
-
-# Colon: there's a case where this causes trouble
-co=&#x003A;
-
-# The sequence "[]" for use in index terms
-bk=&#x005B;&#x005D;
-
-
-# We need to add extra stuff to the <bookinfo> element
-
-[header]
-<?xml {xmldecl}?>
-<!DOCTYPE book {dtddecl}>
-
-<book lang="en">
-{doctitle#}<bookinfo>
-    <title>{doctitle}</title>
-    <titleabbrev>{doctitleabbrev}</titleabbrev>
-    <date>{date}</date>
-    {authored#}<author>
-        <firstname>{firstname}</firstname>
-        <othername>{middlename}</othername>
-        <surname>{lastname}</surname>
-    {authored#}</author>
-    <authorinitials>{authorinitials}</authorinitials>
-    {revisionhistory%}<revhistory><revision><revnumber>{revision}</revnumber><date>{date}</date>{authorinitials?<authorinitials>{authorinitials}</authorinitials>}{revremark?<revremark>{revremark}</revremark>}</revision></revhistory>
-    <corpname>{companyname}</corpname>
-    <othercredit><contrib>{othercredit},</contrib></othercredit>
-    {copyright#}<copyright><year>{cpyear}</year><holder>{copyright}</holder></copyright>
-    <abstract><para>{abstract}</para></abstract>
-{doctitle#}</bookinfo>
-
-
-# Define a new kind of block that maps to <literallayout> so as not to
-# insist on a monospaced font. Delimiter is &&&.
-
-[blockdef-literallayout]
-delimiter=^&{3,}(\[(?P<args>.*)\])?=*$
-template=literallayoutblock
-presubs=specialcharacters,quotes,replacements,macros,callouts
-
-# The template for my non-monospaced literal layout block
-
-[literallayoutblock]
-<literallayout{revisionflag? revisionflag="{revisionflag}"}>|</literallayout>
-
-# Replace the template for normal literal blocks so as to support the
-# revisionflag feature.
-
-[literalblock]
-<example><title>{title}</title>
-<literallayout{id? id="{id}"} {revisionflag? revisionflag="{revisionflag}"} class="monospaced">
-|
-</literallayout>
-{title#}</example>
-
-# Paragraph substitution - use <para> rather than <simplepara>
-
-[paragraph]
-{title#}<formalpara{id? id="{id}"{revisionflag? revisionflag="{revisionflag}"}}><title>{title}</title><para>
-{title%}<para{id? id="{id}"}{revisionflag? revisionflag="{revisionflag}"}>
-|
-{title%}</para>
-{title#}</para></formalpara>
-{empty}
-
-
-# Define a special table for left-centre-right lines, filling the whole page
-# width, with a border but no separators, for Exim configuration options. It
-# would be nice if this could call the default [table] template, forcing the
-# appropriate attributes, but I have not found a way of doing this.
-
-[tabledef-conf]
-fillchar==
-format=csv
-template=conf-table
-colspec=<colspec align="{colalign}"/>
-bodyrow=<row>|</row>
-bodydata=<entry>|</entry>
-
-[conf-table]
-<{title?table}{title!informaltable}{id? id="{id}"} pgwide="1" frame="all" colsep="0" rowsep="0">
-<title>{title}</title>
-<tgroup cols="{cols}">
-<colspec align="left" colwidth="8*"/>
-<colspec align="center" colwidth = "5*"/>
-<colspec align="center" colwidth = "5*"/>
-<colspec align="right" colwidth = "6*"/>
-{headrows#}<thead>
-{headrows}
-{headrows#}</thead>
-{footrows#}<tfoot>
-{footrows}
-{footrows#}</tfoot>
-<tbody>
-{bodyrows}
-</tbody>
-</tgroup>
-</{title?table}{title!informaltable}>
-
-# The default indexterm macro generates primary index entries for the
-# secondary and tertiary terms as well, which does not make sense
-# in the context of the way I write indexes. As well as a replacement
-# that does the simple, straightforward thing, we actually want to have
-# two different macros: one for concepts and one for options.
-
-[cindex-inlinemacro]
-# Inline index term for concepts.
-<indexterm role="concept">
-  <primary>{1}</primary>
-  <secondary>{2}</secondary>
-  <tertiary>{3}</tertiary>
-</indexterm>
-
-[oindex-inlinemacro]
-# Inline index term for options.
-<indexterm role="option">
-  <primary>{1}</primary>
-  <secondary>{2}</secondary>
-  <tertiary>{3}</tertiary>
-</indexterm>
-
-# Allow for the "role" attribute for an index.
-
-[sect-index]
-<index{id? id="{id}"}{role? role="{role}"}>
-<title>{title}</title>
-|
-</index>
-
-
-# Allow for the "titleabbrev" attribute for chapters.
-
-[sect1]
-<chapter{id? id="{id}"}>
-<title>{title}</title>
-<titleabbrev>{titleabbrev}</titleabbrev>
-|
-</chapter>
-
-
-#### End ####
index 3eb6c45..a23da64 100644 (file)
@@ -1,4 +1,4 @@
-<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-fo.xsl,v 1.2 2005/11/10 12:30:13 ph10 Exp $ -->
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-fo.xsl,v 1.3 2006/02/01 11:01:01 ph10 Exp $ -->
 
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                 xmlns:fo="http://www.w3.org/1999/XSL/Format"
@@ -21,6 +21,10 @@ specification. It is imported by MyStyle-filter-fo.xsl and MyStyle-spec-fo.xsl.
 <xsl:param name="double.sided" select="1"></xsl:param>
 -->
 
+<!-- Let's have whatever fop extensions there are -->
+
+<xsl:param name="fop.extensions" select="1"></xsl:param>
+
 <!-- Allow for typed index entries. The "role" setting works with DocBook
 version 4.2 or earlier. Later versions (which we are not currently using)
 need "type". -->
@@ -28,7 +32,6 @@ need "type". -->
 <xsl:param name="index.on.type" select="1"></xsl:param>
 <xsl:param name="index.on.role" select="1"></xsl:param>
 
-
 <!-- The default uses short chapter titles in the TOC! I want them only for
 use in footer lines. So we have to modify this template. I changed
 "titleabbrev.markup" to "title.markup". While I'm here, I also made chapter
@@ -135,7 +138,6 @@ Adjust the sizes of the fonts for titles; the defaults are too gross.
 http://www.sagehill.net/docbookxsl/PrintHeaders.html
 -->
 
-
 <xsl:attribute-set name="footer.content.properties">
   <!-- <xsl:attribute name="font-family">serif</xsl:attribute> -->
   <!-- <xsl:attribute name="font-size">9pt</xsl:attribute> -->
@@ -143,40 +145,16 @@ http://www.sagehill.net/docbookxsl/PrintHeaders.html
 </xsl:attribute-set>
 
 
-<!-- Things that can be inserted into the footer are:
-
-<fo:page-number/>
-Inserts the current page number.
-
-<xsl:apply-templates select="." mode="title.markup"/>
-Inserts the title of the current chapter, appendix, or other component.
-
-<xsl:apply-templates select="." mode="titleabbrev.markup"/>
-Inserts the titleabbrev of the current chapter, appendix, or other component,
-if it is available. Otherwise it inserts the regular title.
-
-<xsl:apply-templates select="." mode="object.title.markup"/>
-Inserts the chapter title with chapter number label. Likewise for appendices.
+<!-- The default cell widths make the centre one too large -->
 
-<fo:retrieve-marker ... />      Used to retrieve the current section name.
+<xsl:param name="footer.column.widths">4 1 4</xsl:param>
 
-<xsl:apply-templates select="//corpauthor[1]"/>
-Inserts the value of the first corpauthor element found anywhere in the
-document.
 
-<xsl:call-template name="datetime.format">
-  <xsl:with-param ...
-Inserts a date timestamp.
-
-<xsl:call-template name="draft.text"/>
-Inserts the Draft message if draft.mode is currently on.
-
-<fo:external-graphic ... />
-Inserts a graphical image.
-See the section Graphic in header or footer for details.
+<!-- Put the abbreviated chapter titles in running feet, and add the chapter
+number afterwards in parentheses. I changed title.markup to titleabbrev.markup,
+and added some lines.
 -->
 
-
 <xsl:template name="footer.content">
   <xsl:param name="pageclass" select="''"/>
   <xsl:param name="sequence" select="''"/>
@@ -206,6 +184,15 @@ See the section Graphic in header or footer for details.
         <fo:page-number/>
       </xsl:when>
 
+      <!-- This clause added by PH -->
+      <xsl:when test="$double.sided = 0 and $position='right' and $pageclass='body'">
+        <xsl:apply-templates select="." mode="titleabbrev.markup"/>
+          <xsl:text> (</xsl:text>
+          <xsl:apply-templates select="." mode="label.markup"/>
+          <xsl:text>)</xsl:text>
+      </xsl:when>
+
+      <!-- Changed title.markup to titleabbrev.markup for TOC -->
       <xsl:when test="$double.sided = 0 and $position='right'">
         <xsl:apply-templates select="." mode="titleabbrev.markup"/>
       </xsl:when>
@@ -231,4 +218,47 @@ See the section Graphic in header or footer for details.
   </fo:block>
 </xsl:template>
 
+
+<!-- Arrange for ordered list numbers to be in parentheses instead of just
+followed by a dot, which I don't like. Unfortunately, this styling is
+output-specific, so we have to do it separately for FO and HTML output. -->
+
+<xsl:template match="orderedlist/listitem" mode="item-number">
+  <xsl:variable name="numeration">
+    <xsl:call-template name="list.numeration">
+      <xsl:with-param name="node" select="parent::orderedlist"/>
+    </xsl:call-template>
+  </xsl:variable>
+
+  <xsl:variable name="type">
+    <xsl:choose>
+      <xsl:when test="$numeration='arabic'">(1)</xsl:when>
+      <xsl:when test="$numeration='loweralpha'">(a)</xsl:when>
+      <xsl:when test="$numeration='lowerroman'">(i)</xsl:when>
+      <xsl:when test="$numeration='upperalpha'">(A)</xsl:when>
+      <xsl:when test="$numeration='upperroman'">(I)</xsl:when>
+      <!-- What!? This should never happen -->
+      <xsl:otherwise>
+        <xsl:message>
+          <xsl:text>Unexpected numeration: </xsl:text>
+          <xsl:value-of select="$numeration"/>
+        </xsl:message>
+        <xsl:value-of select="1."/>
+      </xsl:otherwise>
+    </xsl:choose>
+  </xsl:variable>
+
+  <xsl:variable name="item-number">
+    <xsl:call-template name="orderedlist-item-number"/>
+  </xsl:variable>
+
+  <xsl:if test="parent::orderedlist/@inheritnum='inherit'
+                and ancestor::listitem[parent::orderedlist]">
+    <xsl:apply-templates select="ancestor::listitem[parent::orderedlist][1]"
+                         mode="item-number"/>
+  </xsl:if>
+
+  <xsl:number value="$item-number" format="{$type}"/>
+</xsl:template>
+
 </xsl:stylesheet>
index c5fa9ad..afca6c5 100644 (file)
@@ -1,4 +1,4 @@
-<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-spec-fo.xsl,v 1.2 2005/08/05 10:57:41 ph10 Exp $ -->
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle-spec-fo.xsl,v 1.3 2006/02/01 11:01:01 ph10 Exp $ -->
 
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
 
@@ -12,6 +12,19 @@ printing the Exim specification document. -->
 <xsl:import href="MyStyle.xsl"/>
 <xsl:import href="MyStyle-fo.xsl"/>
 
-<!-- Nothing special for the full spec document yet -->
+<!-- Special for the spec document -->
+
+<!-- Arrange for the table of contents to be an even number of pages. The name
+"lot" includes all pages that contain a "list of titles", which in our case is
+only the TOC. -->
+
+<xsl:template name="force.page.count">
+  <xsl:param name="element" select="local-name(.)"/>
+  <xsl:param name="master-reference" select="''"/>
+  <xsl:choose>
+    <xsl:when test="$master-reference = 'lot'">end-on-even</xsl:when>
+    <xsl:otherwise>no-force</xsl:otherwise>
+  </xsl:choose>
+</xsl:template>
 
 </xsl:stylesheet>
index 78f1cdf..0d6bb57 100644 (file)
@@ -1,4 +1,4 @@
-<!-- $Cambridge: exim/doc/doc-docbook/MyStyle.xsl,v 1.2 2005/11/10 12:30:13 ph10 Exp $ -->
+<!-- $Cambridge: exim/doc/doc-docbook/MyStyle.xsl,v 1.3 2006/02/01 11:01:01 ph10 Exp $ -->
 
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
 
@@ -51,18 +51,11 @@ book      toc,title
 <xsl:param name="hyphenate">false</xsl:param>
 
 
-<!--
-Generate only numbers, no titles, in cross references.
--->
+<!-- Generate only numbers, no titles, in cross references. -->
 
 <xsl:param name="xref.with.number.and.title">0</xsl:param>
 
 
-<!-- Hopefully this might do something useful? It doesn't seem to. -->
-
-<xsl:param name="fop.extensions" select="1"></xsl:param>
-
-
 <!-- Output variable names in italic rather than the default monospace. -->
 
 <xsl:template match="varname">
@@ -77,6 +70,13 @@ Generate only numbers, no titles, in cross references.
 </xsl:template>
 
 
+<!-- Output function names in italic rather than the default boldface. -->
+
+<xsl:template match="function">
+  <xsl:call-template name="inline.italicseq"/>
+</xsl:template>
+
+
 <!-- Output options in bold rather than the default monospace. -->
 
 <xsl:template match="option">
@@ -93,6 +93,12 @@ fiddling with a parameter.
 <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
   <l:l10n language="en">
 
+    <!-- Turn the text "Revision History" into nothing, because we only have
+    the info for the latest revision in the file. -->
+
+    <l:gentext key="revhistory" text=""/>
+    <l:gentext key="RevHistory" text=""/>
+
     <!-- The default (as modified above) gives us "Chapter xxx" or "Section
     xxx", with a capital letter at the start. So we have to make an more
     complicated explicit change to give just the number. -->
diff --git a/doc/doc-docbook/MyTitleStyle.xsl b/doc/doc-docbook/MyTitleStyle.xsl
new file mode 100644 (file)
index 0000000..80bc59a
--- /dev/null
@@ -0,0 +1,223 @@
+<?xml version="1.0"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+
+<!-- This stylesheet was created by template/titlepage.xsl; do not edit it by hand. -->
+
+<xsl:template name="book.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="bookinfo/title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="bookinfo/subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/author"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/affiliation"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/affiliation"/>
+</xsl:template>
+
+<xsl:template name="book.titlepage.verso">
+  <xsl:choose>
+    <xsl:when test="bookinfo/title">
+      <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/author"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/affiliation"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/affiliation"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/address"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/address"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/pubdate"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/abstract"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/abstract"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/copyright"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/revhistory"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="bookinfo/legalnotice"/>
+  <xsl:apply-templates mode="book.titlepage.verso.auto.mode" select="info/legalnotice"/>
+</xsl:template>
+
+<xsl:template name="book.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="book.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="book.titlepage.before.verso"><fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" break-after="page"/>
+</xsl:template>
+
+<xsl:template name="book.titlepage">
+  <fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="book.titlepage.before.recto"/>
+      <xsl:call-template name="book.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:if test="normalize-space($recto.content) != ''">
+      <fo:block><xsl:copy-of select="$recto.content"/></fo:block>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="book.titlepage.before.verso"/>
+      <xsl:call-template name="book.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:if test="normalize-space($verso.content) != ''">
+      <fo:block><xsl:copy-of select="$verso.content"/></fo:block>
+    </xsl:if>
+    <xsl:call-template name="book.titlepage.separator"/>
+  </fo:block>
+</xsl:template>
+
+<xsl:template match="*" mode="book.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="book.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="center" font-size="24.8832pt" space-before="5em" font-weight="bold" font-family="{$title.fontset}">
+<xsl:call-template name="division.title">
+<xsl:with-param name="node" select="ancestor-or-self::book[1]"/>
+</xsl:call-template>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" text-align="center" font-size="20.736pt" space-before="15.552pt" font-family="{$title.fontset}">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" font-size="17.28pt" keep-with-next="always" space-before="2in">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" space-before="2in">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="author" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" font-size="17.28pt" space-before="10.8pt" keep-with-next="always">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="affiliation" mode="book.titlepage.recto.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.recto.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="title" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" font-size="14.4pt" font-weight="bold" font-family="{$title.fontset}">
+<xsl:call-template name="book.verso.title">
+</xsl:call-template>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style">
+<xsl:call-template name="verso.authorgroup">
+</xsl:call-template>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="author" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="affiliation" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="address" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="abstract" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="copyright" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" space-before="1em">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="book.titlepage.verso.auto.mode">
+<fo:block xmlns:fo="http://www.w3.org/1999/XSL/Format" xsl:use-attribute-sets="book.titlepage.verso.style" font-size="8pt">
+<xsl:apply-templates select="." mode="book.titlepage.verso.mode"/>
+</fo:block>
+</xsl:template>
+
+</xsl:stylesheet>
index 27c4c8a..d2da77d 100644 (file)
 <!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
 ]>
 
-<!-- $Cambridge: exim/doc/doc-docbook/MyTitlepage.templates.xml,v 1.1 2005/06/16 10:32:31 ph10 Exp $ -->
+<!-- $Cambridge: exim/doc/doc-docbook/MyTitlepage.templates.xml,v 1.2 2006/02/01 11:01:01 ph10 Exp $ -->
 
 <!-- This document is copied from the DocBook XSL stylesheets, and modified to
 do what I want it to do for the Exim reference manual. Process this document
 with:
 
 xsltproc -output MyTitleStyle.xsl \
-  /usr/share/sgml/docbook/xsl-stylesheets-1.66.1/template/titlepage.xsl \
+  /usr/share/sgml/docbook/xsl-stylesheets-1.68.1/template/titlepage.xsl \
   MyTitlepage.templates.xml
 
 in order to generate a style sheet called MyTitleStyle.xsl. That is then
@@ -52,7 +52,7 @@ need to set up! -->
              param:node="ancestor-or-self::book[1]"
              text-align="center"
              font-size="&hsize5;"
-             space-before="&hsize5space;"
+             space-before="5em"
              font-weight="bold"
              font-family="{$title.fontset}"/>
       <subtitle
@@ -67,6 +67,7 @@ need to set up! -->
       <author font-size="&hsize3;"
               space-before="&hsize2space;"
               keep-with-next="always"/>
+      <affiliation space-before="1em"/>
     </t:titlepage-content>
 
   <t:titlepage-content t:side="verso">
@@ -77,11 +78,13 @@ need to set up! -->
              font-family="{$title.fontset}"/>
       <corpauthor/>
       <authorgroup t:named-template="verso.authorgroup"/>
-      <author/>
-      <othercredit/>
+      <author space-before="1em"/>
+      <affiliation space-before="1em"/>
+      <address/>
       <pubdate space-before="1em"/>
       <abstract/>
-      <copyright/>
+      <copyright space-before="1em"/>
+      <revhistory space-before="1em"/>
       <legalnotice font-size="8pt"/>
   </t:titlepage-content>
 
diff --git a/doc/doc-docbook/PageLabelPDF b/doc/doc-docbook/PageLabelPDF
new file mode 100755 (executable)
index 0000000..aa144e2
--- /dev/null
@@ -0,0 +1,61 @@
+#! /usr/bin/perl -w
+
+# $Cambridge: exim/doc/doc-docbook/PageLabelPDF,v 1.1 2006/02/01 11:01:01 ph10 Exp $
+
+# Program to add page label information to the PDF output file. I have not
+# found a way of automatically discovering the number of frontmatter pages
+# in the document. It is therefore screwed in as 12 in the next statement.
+
+$add = "/PageLabels << /Nums [ 0 << /S /r >>\n" .
+       "                      12 << /S /D >>\n" .
+       "                     ]\n" .
+       "            >>\n";
+
+$extra = length $add;
+
+$before = 0;
+while (<>)
+  {
+  print;
+  $before += length($_);
+  last if $_ =~ "^<< /Type /Catalog";
+  }
+
+print $add;
+
+while (<>)
+  {
+  print;
+  last if $_ =~ /^xref$/;
+  }
+
+while (<>)
+  {
+  if (/^(\d{10}) (.*)/)
+    {
+    my($was) = $1;
+    my($rest) = $2;
+    printf "%010d $rest\n", $was + (($was > $before)? $extra : 0);
+    }
+  elsif (/^startxref/)
+    {
+    print;
+    $_ = <>;
+    if (/^(\d+)/)
+      {
+      print $1 + $extra, "\n";
+      }
+    else
+      {
+      print;
+      }
+    }
+  else
+    {
+    print;
+    }
+  }
+
+# End
+
+
index 4e28ada..4e606dd 100755 (executable)
@@ -1,6 +1,6 @@
 #! /usr/bin/perl
 
-# $Cambridge: exim/doc/doc-docbook/Pre-xml,v 1.2 2005/11/10 12:30:13 ph10 Exp $
+# $Cambridge: exim/doc/doc-docbook/Pre-xml,v 1.3 2006/02/01 11:01:01 ph10 Exp $
 
 # Script to pre-process XML input before processing it for various purposes.
 # Options specify which transformations are to be done. Monospaced literal
@@ -8,20 +8,17 @@
 
 # Changes:
 
-# -abstract: Remove the <abstract> element
-
-# -ascii:    Replace &8230;   (sic, no x) with ...
-#            Replace &#x2019; by '
-#            Replace &#x201C; by "
-#            Replace &#x201D; by "
-#            Replace &#x2013; by -
-#            Replace &#x2020; by *
-#            Replace &#x2021; by **
-#            Replace &#x00a0; by a space
-#            Replace &#169;   by (c)
-#            Put quotes round <literal> text
+# -ascii:    Replace &#x2019; by '
+#            Replace &copy;   by (c)
+#            Replace &dagger; by *
+#            Replace &Dagger; by **
+#            Replace &nbsp;   by a space
+#            Replace &ndash;  by -
 #            Put quotes round <quote> text
 #
+# -quoteliteral:
+#            Put quotes round <literal> text
+#
 # -bookinfo: Remove the <bookinfo> element from the file
 #
 # -fi:       Replace "fi" by &#xFB01; except when it is in an XML element, or
 #
 # -html:     Certain things are done only for HTML output:
 #
-#            If <literallayout> is followed by optional space and then a
+#            If <literallayout> is followed by optional space and then a
 #            newline, the space and newline are removed, because otherwise you
 #            get a blank line in the HTML output.
 #
 # -noindex   Remove the XML to generate a Concept and an Options index.
 # -oneindex  Ditto, but add XML to generate a single index.
+#
+# -optbreak  Insert an optional line break (zero-width space, &#x200B;) after
+#            every underscore in text within <option> and <variable> elements,
+#            except when preceded by <entry> (i.e. not in tables). The same is
+#            also done within a word of four or more upper-case letters (for
+#            compile-time options).
 
 
 
-# The function that processes non-literal monospaced text
+# The function that processes non-literal, non-monospaced text
 
 sub process()
 {
@@ -46,17 +49,23 @@ my($s) = $_[0];
 
 $s =~ s/fi(?![^<>]*>)/&#xFB01;/g if $ligatures;
 
+if ($optbreak)
+  {
+  $s =~ s%(?<!<entry>)(<option>|<varname>)([^<]+)%
+    my($x,$y) = ($1,$2); $y =~ s/_/_&#x200B;/g; "$x"."$y"%gex;
+
+  $s =~ s?\b([A-Z_]{4,})\b?
+    my($x) = $1; $x =~ s/_/_&#x200B;/g; "$x"?gex;
+  }
+
 if ($ascii)
   {
-  $s =~ s/&#8230;/.../g;
   $s =~ s/&#x2019;/'/g;
-  $s =~ s/&#x201C;/"/g;
-  $s =~ s/&#x201D;/"/g;
-  $s =~ s/&#x2013;/-/g;
-  $s =~ s/&#x2020;/*/g;
-  $s =~ s/&#x2021;/**/g;
-  $s =~ s/&#x00a0;/ /g;
-  $s =~ s/&#169;/(c)/g;
+  $s =~ s/&copy;/(c)/g;
+  $s =~ s/&dagger;/*/g;
+  $s =~ s/&Dagger;/**/g;
+  $s =~ s/&nsbp;/ /g;
+  $s =~ s/&ndash;/-/g;
   $s =~ s/<quote>/"/g;
   $s =~ s/<\/quote>/"/g;
   }
@@ -67,7 +76,6 @@ $s;
 
 # The main program
 
-$abstract  = 0;
 $ascii     = 0;
 $bookinfo  = 0;
 $html      = 0;
@@ -77,25 +85,24 @@ $ligatures = 0;
 $madeindex = 0;
 $noindex   = 0;
 $oneindex  = 0;
+$optbreak  = 0;
+$quoteliteral = 0;
 
 foreach $arg (@ARGV)
   {
   if    ($arg eq "-fi")       { $ligatures = 1; }
-  elsif ($arg eq "-abstract") { $abstract = 1; }
   elsif ($arg eq "-ascii")    { $ascii = 1; }
   elsif ($arg eq "-bookinfo") { $bookinfo = 1; }
   elsif ($arg eq "-html")     { $html = 1; }
   elsif ($arg eq "-noindex")  { $noindex = 1; }
   elsif ($arg eq "-oneindex") { $oneindex = 1; }
+  elsif ($arg eq "-optbreak") { $optbreak = 1; }
+  elsif ($arg eq "-quoteliteral") { $quoteliteral = 1; }
   else  { die "** Pre-xml: Unknown option \"$arg\"\n"; }
   }
 
 while (<STDIN>)
   {
-  # Remove <abstract> if required
-
-  next if ($abstract && /^\s*<abstract>/);
-
   # Remove <bookinfo> if required
 
   if ($bookinfo && /^<bookinfo/)
@@ -152,7 +159,7 @@ while (<STDIN>)
       if (/^(.*?)<\/literal>(?!<\/quote>)(.*)$/)
         {
         print $1;
-        print "\"" if $ascii && !$inliterallayout;
+        print "\"" if $quoteliteral && !$inliterallayout;
         print "</literal>";
         $inliteral = 0;
         $_ = "$2\n";
@@ -172,7 +179,7 @@ while (<STDIN>)
         {
         print &process($1);
         print "<literal>";
-        print "\"" if $ascii && !$inliterallayout;
+        print "\"" if $quoteliteral && !$inliterallayout;
         $inliteral = 1;
         $_ = "$2\n";
         }
index 5056c17..70bb865 100755 (executable)
@@ -1,6 +1,6 @@
 #! /usr/bin/perl
 
-# $Cambridge: exim/doc/doc-docbook/TidyHTML-filter,v 1.2 2005/11/10 12:30:13 ph10 Exp $
+# $Cambridge: exim/doc/doc-docbook/TidyHTML-filter,v 1.3 2006/02/01 11:01:01 ph10 Exp $
 
 # Script to tidy up the filter HTML file that is generated by xmlto. The
 # following changes are made:
@@ -21,13 +21,21 @@ open(IN, "filter.html") || die "Failed to open filter.html for reading: $!\n";
 @text = <IN>;
 close(IN);
 
-# Insert a newline after every > because the whole toc is generated as one
-# humungous line that is hard to check. Then split the lines so that each one
-# is a separate element in the vector.
+# Insert a newline after every > in the toc, because the whole toc is generated
+# as one humungous line that is hard to check. Indeed, the start of the first
+# chapter is also on the line, so we have to split if off first. Having
+# inserted newlines, we split the toc into separate items in the vector.
 
-foreach $line (@text) { $line =~ s/>\s*/>\n/g; }
 for ($i = 0; $i < scalar(@text); $i++)
-  { splice @text, $i, 1, (split /(?<=\n)/, $text[$i]); }
+  {
+  if ($text[$i] =~ ?<title>Exim's interfaces to mail filtering</title>?)
+    {
+    splice @text, $i, 1, (split /(?=<div class="chapter")/, $text[$i]);
+    $text[$i] =~ s/>\s*/>\n/g;
+    splice @text, $i, 1, (split /(?<=\n)/, $text[$i]);
+    last;
+    }
+  }
 
 # We want to create reverse links from each chapter and section title back to
 # the relevant place in the TOC. Scan the TOC for the relevant entries. Add
@@ -60,26 +68,25 @@ for (; $i < scalar(@text); $i++)
 
 for (; $i < scalar(@text); $i++)
   {
-  if ($text[$i] eq "<div class=\"literallayout\">\n" && $text[$i+1] eq "<p>\n")
+  while ($text[$i] =~
+      /^(.*)<a( xmlns="[^"]+")? id="([^"]+)"><\/a>(.*?)<\/h(.*)/)
     {
-    $text[++$i] = "";
-    $thisdiv = 1;
+    my($ref) = $backref{"#$2"};
+    $text[$i] = "$1<a$2 href=\"#$ref\" id=\"$3\">$4</a></h$5";
     }
-  elsif ($thisdiv && $text[$i] eq "</p>\n" && $text[$i+1] eq "</div>\n")
-    {
-    $text[$i] = "";
-    $thisdiv = 0;
-    }
-  elsif ($text[$i] =~ /^<h[23] /)
+
+  if ($text[$i] =~ /^(.*)<div class="literallayout"><p>(?:<br \/>)?(.*)/)
     {
-    $i++;
-    if ($text[$i] =~ /^<a( xmlns="[^"]+")? id="([^"]+)">$/)
+    my($j);
+    $text[$i] = "$1<div class=\"literallayout\">$2";
+
+    for ($j = $i + 1; $j < scalar(@text); $j++)
       {
-      my($ref) = $backref{"#$2"};
-      $text[$i++] = "<a$1 href=\"#$ref\" id=\"$2\">\n";
-      my($temp) = $text[$i];
-      $text[$i] = $text[$i+1];
-      $text[++$i] = $temp;
+      if ($text[$j] =~ /^<\/p><\/div>/)
+        {
+        $text[$j] =~ s/<\/p>//;
+        last;
+        }
       }
     }
   }
index 05a9d82..c1bc994 100755 (executable)
@@ -1,6 +1,6 @@
 #! /usr/bin/perl
 
-# $Cambridge: exim/doc/doc-docbook/TidyHTML-spec,v 1.2 2005/11/10 12:30:13 ph10 Exp $
+# $Cambridge: exim/doc/doc-docbook/TidyHTML-spec,v 1.3 2006/02/01 11:01:01 ph10 Exp $
 
 # Script to tidy up the spec HTML files that are generated by xmlto. The
 # following changes are made:
@@ -101,7 +101,7 @@ foreach $file (@chlist)
       $text[$i]= "$pre<a$opt href=\"index.html#$ref\" id=\"$id\">$title</a></h$post";
       }
 
-    elsif ($text[$i] eq "<div class=\"literallayout\">\n" && $text[$i+1] eq "<p>\n")
+    elsif ($text[$i] =~ /^<div [^>]*?class="literallayout">$/ && $text[$i+1] eq "<p>\n")
       {
       $text[++$i] = "";
       $thisdiv = 1;
index 02bf9db..5e19c37 100755 (executable)
@@ -1,21 +1,66 @@
 #! /usr/bin/perl
 
-# $Cambridge: exim/doc/doc-docbook/Tidytxt,v 1.1 2005/06/16 10:32:31 ph10 Exp $
+# $Cambridge: exim/doc/doc-docbook/Tidytxt,v 1.2 2006/02/01 11:01:01 ph10 Exp $
 
-# Script to tidy up the output of w3m when it makes a text file. We convert
-# sequences of blank lines into a single blank line.
+# Script to tidy up the output of w3m when it makes a text file. First we
+# convert sequences of blank lines into a single blank line, to get everything
+# uniform. Then we go through and insert blank lines before chapter and
+# sections, also converting chapter titles to uppercase.
 
-$blanks = 0;
-while (<>)
+@lines = <>;
+
+$lastwasblank = 0;
+foreach $line (@lines)
   {
-  if (/^\s*$/)
+  if ($line =~ /^\s*$/)
     {
-    $blanks++;
+    $line = "" if $lastwasblank;
+    $lastwasblank = 1;
     next;
     }
-  print "\n" if $blanks > 0;
-  $blanks = 0;
-  print;
+  $lastwasblank = 0;
+  }
+
+# Find start of TOC, uppercasing its title
+
+for ($i = 0; $i < scalar @lines; $i++)
+  {
+  $lines[$i] = "TABLE OF CONTENTS\n" if $lines[$i] =~ /^Table of Contents/;
+  last if $lines[$i] =~ /^1. /;
+  }
+
+# Find start of first chapter
+
+for ($i++; $i < scalar @lines; $i++)
+  { last if $lines[$i] =~ /^1. /; }
+
+# Process the body. We can detect the starts of chapters and sections by
+# looking for preceding and following blank lines, and then matching against
+# the numbers.
+
+$chapter = 0;
+for (; $i < scalar @lines; $i++)
+  {
+  next if $lines[$i-1] !~ /^$/ || $lines[$i+1] !~ /^$/;
+
+  # Start of chapter
+
+  if ($lines[$i] =~ /^(\d+)\. / && $1 == $chapter + 1)
+    {
+    $chapter++;
+    $section = 0;
+    $lines[$i] = "\n\n" . ("=" x 79) . "\n" . uc($lines[$i]);
+    }
+
+  # Start of next section
+
+  elsif ($lines[$i] =~ /^(\d+)\.(\d+) / && $1 == $chapter && $2 == $section + 1)
+    {
+    $section++;
+    $lines[$i] = "\n$lines[$i]" . "-" x (length($lines[$i]) - 1) . "\n";
+    }
   }
 
+print @lines;
+
 # End
diff --git a/doc/doc-docbook/filter.ascd b/doc/doc-docbook/filter.ascd
deleted file mode 100644 (file)
index e8763f5..0000000
+++ /dev/null
@@ -1,1758 +0,0 @@
-///
-$Cambridge: exim/doc/doc-docbook/filter.ascd,v 1.2 2005/11/10 12:30:13 ph10 Exp $
-
-This file contains the Asciidoc source for the document that describes Exim's
-filtering facilities from a user's point of view. See the file AdMarkup.txt for
-an explanation of the markup that is used. It is more or less standard
-Asciidoc, but with a few changes and additions.
-///
-
-
-///
-This preliminary stuff creates a <bookinfo> entry in the XML. This is removed
-when creating the PostScript/PDF output, because we do not want a full-blown
-title page created for those versions. The stylesheet fudges up a title line to
-replace the text "Table of contents". However, for the other forms of output,
-the <bookinfo> element is retained and used.
-///
-
-Exim's interfaces to mail filtering
-===================================
-:author:          Philip Hazel
-:copyright:       University of Cambridge
-:cpyear:          2005
-:date:            06 October 2005
-:doctitleabbrev:  Exim filtering
-:revision:        4.60
-
-
-//////////////////////////////////////////////////////////////////////////////
-***WARNING*** Do not put anything, not even a titleabbrev setting, before
-the first chapter (luckily it does not need one) because if you do, AsciiDoc
-creates an empty <preface> element, which we do not want.
-//////////////////////////////////////////////////////////////////////////////
-
-
-Forwarding and filtering in Exim
---------------------------------
-
-This document describes the user interfaces to Exim's in-built mail filtering
-facilities, and is copyright (C) University of Cambridge 2005. It corresponds
-to Exim version 4.60.
-
-
-
-Introduction
-~~~~~~~~~~~~
-Most Unix mail transfer agents (programs that deliver mail) permit individual
-users to specify automatic forwarding of their mail, usually by placing a list
-of forwarding addresses in a file called '.forward' in their home directories.
-Exim extends this facility by allowing the forwarding instructions to be a set
-of rules rather than just a list of addresses, in effect providing ``'.forward'
-with conditions''. Operating the set of rules is called 'filtering', and the
-file that contains them is called a 'filter file'.
-
-Exim supports two different kinds of filter file. An 'Exim filter' contains
-instructions in a format that is unique to Exim. A 'Sieve filter' contains
-instructions in the Sieve format that is defined by RFC 3028. As this is a
-standard format, Sieve filter files may already be familiar to some users.
-Sieve files should also be portable between different environments. However,
-the Exim filtering facility contains more features (such as variable
-expansion), and better integration with the host environment (such as the use
-of external processes and pipes).
-
-The choice of which kind of filter to use can be left to the end-user, provided
-that the system administrator has configured Exim appropriately for both kinds
-of filter. However, if interoperability is important, Sieve is the only
-choice.
-
-The ability to use filtering or traditional forwarding has to be enabled by the
-system administrator, and some of the individual facilities can be separately
-enabled or disabled. A local document should be provided to describe exactly
-what has been enabled. In the absence of this, consult your system
-administrator.
-
-This document describes how to use a filter file and the format of its
-contents. It is intended for use by end-users. Both Sieve filters and Exim
-filters are covered. However, for Sieve filters, only issues that relate to the
-Exim implementation are discussed, since Sieve itself is described elsewhere.
-
-The contents of traditional '.forward' files are not described here. They
-normally contain just a list of addresses, file names, or pipe commands,
-separated by commas or newlines, but other types of item are also available.
-The full details can be found in the chapter on the ^redirect^ router in the
-Exim specification, which also describes how the system administrator can set
-up and control the use of filtering.
-
-
-
-Filter operation
-~~~~~~~~~~~~~~~~
-It is important to realize that, in Exim, no deliveries are actually made while
-a filter or traditional '.forward' file is being processed. Running a filter
-or processing a traditional '.forward' file sets up future delivery
-operations, but does not carry them out.
-
-The result of filter or '.forward' file processing is a list of destinations
-to which a message should be delivered. The deliveries themselves take place
-later, along with all other deliveries for the message. This means that it is
-not possible to test for successful deliveries while filtering. It also means
-that any duplicate addresses that are generated are dropped, because Exim never
-delivers the same message to the same address more than once.
-
-
-
-
-[[SECTtesting]]
-Testing a new filter file
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Filter files, especially the more complicated ones, should always be tested, as
-it is easy to make mistakes. Exim provides a facility for preliminary testing
-of a filter file before installing it. This tests the syntax of the file and
-its basic operation, and can also be used with traditional '.forward' files.
-
-Because a filter can do tests on the content of messages, a test message is
-required. Suppose you have a new filter file called 'myfilter' and a test
-message called 'test-message'. Assuming that Exim is installed with the
-conventional path name '/usr/sbin/sendmail' (some operating systems use
-'/usr/lib/sendmail'), the following command can be used:
-
-  /usr/sbin/sendmail -bf myfilter <test-message
-
-The %-bf% option tells Exim that the following item on the command line is the
-name of a filter file that is to be tested. There is also a %-bF% option,
-which is similar, but which is used for testing system filter files, as opposed
-to user filter files, and which is therefore of use only to the system
-administrator.
-
-The test message is supplied on the standard input. If there are no
-message-dependent tests in the filter, an empty file ('/dev/null') can be
-used. A supplied message must start with header lines or the ``From'' message
-separator line which is found in many multi-message folder files. Note that
-blank lines at the start terminate the header lines. A warning is given if no
-header lines are read.
-
-The result of running this command, provided no errors are detected in the
-filter file, is a list of the actions that Exim would try to take if presented
-with the message for real.
-For example, for an Exim filter, the output
-
-  Deliver message to: gulliver@lilliput.fict.example
-  Save message to: /home/lemuel/mail/archive
-
-means that one copy of the message would be sent to
-'gulliver@lilliput.fict.example', and another would be added to the file
-_/home/lemuel/mail/archive_, if all went well.
-
-The actions themselves are not attempted while testing a filter file in this
-way; there is no check, for example, that any forwarding addresses are valid.
-For an Exim filter,
-if you want to know why a particular action is being taken, add the %-v%
-option to the command. This causes Exim to output the results of any
-conditional tests and to indent its output according to the depth of nesting of
-^if^ commands. Further additional output from a filter test can be generated
-by the ^testprint^ command, which is described below.
-
-When Exim is outputting a list of the actions it would take, if any text
-strings are included in the output, non-printing characters therein are
-converted to escape sequences. In particular, if any text string contains a
-newline character, this is shown as ``\n'' in the testing output.
-
-When testing a filter in this way, Exim makes up an ``envelope'' for the message.
-The recipient is by default the user running the command, and so is the sender,
-but the command can be run with the %-f% option to supply a different sender.
-For example,
-
-....
-/usr/sbin/sendmail -bf myfilter \
-   -f islington@never.where <test-message
-....
-
-Alternatively, if the %-f% option is not used, but the first line of the
-supplied message is a ``From'' separator from a message folder file (not the same
-thing as a 'From:' header line), the sender is taken from there. If %-f% is
-present, the contents of any ``From'' line are ignored.
-
-The ``return path'' is the same as the envelope sender, unless the message
-contains a 'Return-path:' header, in which case it is taken from there. You
-need not worry about any of this unless you want to test out features of a
-filter file that rely on the sender address or the return path.
-
-It is possible to change the envelope recipient by specifying further options.
-The %-bfd% option changes the domain of the recipient address, while the
-%-bfl% option changes the ``local part'', that is, the part before the @ sign.
-An adviser could make use of these to test someone else's filter file.
-
-The %-bfp% and %-bfs% options specify the prefix or suffix for the local part.
-These are relevant only when support for multiple personal mailboxes is
-implemented; see the description in section <<SECTmbox>> below.
-
-
-Installing a filter file
-~~~~~~~~~~~~~~~~~~~~~~~~
-A filter file is normally installed under the name '.forward' in your home
-directory -- it is distinguished from a conventional '.forward' file by its
-first line (described below). However, the file name is configurable, and some
-system administrators may choose to use some different name or location for
-filter files.
-
-
-Testing an installed filter file
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Testing a filter file before installation cannot find every potential problem;
-for example, it does not actually run commands to which messages are piped.
-Some ``live'' tests should therefore also be done once a filter is installed.
-
-If at all possible, test your filter file by sending messages from some other
-account. If you send a message to yourself from the filtered account, and
-delivery fails, the error message will be sent back to the same account, which
-may cause another delivery failure. It won't cause an infinite sequence of such
-messages, because delivery failure messages do not themselves generate further
-messages. However, it does mean that the failure won't be returned to you, and
-also that the postmaster will have to investigate the stuck message.
-
-If you have to test an Exim filter from the same account, a sensible precaution
-is to include the line
-
-  if error_message then finish endif
-
-as the first filter command, at least while testing. This causes filtering to
-be abandoned for a delivery failure message, and since no destinations are
-generated, the message goes on to be delivered to the original address. Unless
-there is a good reason for not doing so, it is recommended that the above test
-be left in all Exim filter files.
-(This does not apply to Sieve files.)
-
-
-
-Details of filtering commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The filtering commands for Sieve and Exim filters are completely different in
-syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
-chapter we describe how it is integrated into Exim. The subsequent chapter
-covers Exim filtering commands in detail.
-
-
-
-[[CHAPsievefilter]]
-Sieve filter files
-------------------
-The code for Sieve filtering in Exim was contributed by Michael Haardt, and
-most of the content of this chapter is taken from the notes he provided. Since
-Sieve is an extensible language, it is important to understand ``Sieve'' in
-this context as ``the specific implementation of Sieve for Exim''.
-
-This chapter does not contain a description of Sieve, since that can be found
-in RFC 3028, which should be read in conjunction with these notes.
-
-The Exim Sieve implementation offers the core as defined by RFC 3028,
-comparison tests, the *copy*, *envelope*, *fileinto*, and *vacation*
-extensions, but not the *reject* extension. Exim does not support message
-delivery notifications (MDNs), so adding it just to the Sieve filter (as
-required for *reject*) makes little sense.
-
-In order for Sieve to work properly in Exim, the system administrator needs to
-make some adjustments to the Exim configuration. These are described in the
-chapter on the ^redirect^ router in the full Exim specification.
-
-
-Recognition of Sieve filters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A filter file is interpreted as a Sieve filter if its first line is
-
-  # Sieve filter
-
-This is what distinguishes it from a conventional '.forward' file or an Exim
-filter file.
-
-
-
-Saving to specified folders
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If the system administrator has set things up as suggested in the Exim
-specification, and you use *keep* or *fileinto* to save a mail into a
-folder, absolute files are stored where specified, relative files are stored
-relative to $home$, and *inbox* goes to the standard mailbox location.
-
-
-
-Strings containing header names
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-RFC 3028 does not specify what happens if a string denoting a header field does
-not contain a valid header name, for example, it contains a colon. This
-implementation generates an error instead of ignoring the header field in order
-to ease script debugging, which fits in with the common picture of Sieve.
-
-
-
-Exists test with empty list of headers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The *exists* test succeeds only if all the specified headers exist. RFC 3028
-does not explicitly specify what happens on an empty list of headers. This
-implementation evaluates that condition as true, interpreting the RFC in a
-strict sense.
-
-
-
-Header test with invalid MIME encoding in header
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Some MUAs process invalid base64 encoded data, generating junk.
-Others ignore junk after seeing an equal sign in base64 encoded data.
-RFC 2047 does not specify how to react in this case, other than stating
-that a client must not forbid to process a message for that reason.
-RFC 2045 specifies that invalid data should be ignored (apparently
-looking at end of line characters). It also specifies that invalid data
-may lead to rejecting messages containing them (and there it appears to
-talk about true encoding violations), which is a clear contradiction to
-ignoring them.
-
-RFC 3028 does not specify how to process incorrect MIME words.
-This implementation treats them literally, as it does if the word is
-correct but its character set cannot be converted to UTF-8.
-
-
-
-Address test for multiple addresses per header
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A header may contain multiple addresses. RFC 3028 does not explicitly
-specify how to deal with them, but since the address test checks if
-anything matches anything else, matching one address suffices to
-satisfy the condition. That makes it impossible to test if a header
-contains a certain set of addresses and no more, but it is more logical
-than letting the test fail if the header contains an additional address
-besides the one the test checks for.
-
-
-
-Semantics of keep
-~~~~~~~~~~~~~~~~~
-The *keep* command is equivalent to
-
-  fileinto "inbox";
-
-It saves the message and resets the implicit keep flag. It does not set the
-implicit keep flag; there is no command to set it once it has been reset.
-
-
-
-Semantics of fileinto
-~~~~~~~~~~~~~~~~~~~~~
-RFC 3028 does not specify whether %fileinto% should try to create a mail folder
-if it does not exist. This implementation allows the sysadmin to configure that
-aspect using the ^appendfile^ transport options %create_directory%,
-%create_file%, and %file_must_exist%. See the ^appendfile^ transport in
-the Exim specification for details.
-
-
-
-Semantics of redirect
-~~~~~~~~~~~~~~~~~~~~~
-Sieve scripts are supposed to be interoperable between servers, so this
-implementation does not allow mail to be redirected to unqualified addresses,
-because the domain would depend on the system being used. On systems with
-virtual mail domains, the default domain is probably not what the user expects
-it to be.
-
-
-
-String arguments
-~~~~~~~~~~~~~~~~
-There has been confusion if the string arguments to *require* are to be matched
-case-sensitively or not. This implementation matches them with the match type
-^:is^ (default, see section 2.7.1 of the RFC) and the comparator
-^i;ascii-casemap^ (default, see section 2.7.3 of the RFC). The RFC defines the
-command defaults clearly, so any different implementations violate RFC 3028.
-The same is valid for comparator names, also specified as strings.
-
-
-
-Number units
-~~~~~~~~~~~~
-There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
-The mistake is obvious, because RFC 3028 specifies G to denote 2^30
-(which is gibi, not tebi), and that is what this implementation uses as
-the scaling factor for the suffix G.
-
-
-
-RFC compliance
-~~~~~~~~~~~~~~
-Exim requires the first line of a Sieve filter to be
-
-  # Sieve filter
-
-Of course the RFC does not specify that line. Do not expect examples to work
-without adding it, though.
-
-RFC 3028 requires the use of CRLF to terminate a line.
-The rationale was that CRLF is universally used in network protocols
-to mark the end of the line. This implementation does not embed Sieve
-in a network protocol, but uses Sieve scripts as part of the Exim MTA.
-Since all parts of Exim use LF as the newline character, this implementation
-does, too, by default, though the system administrator may choose (at Exim
-compile time) to use CRLF instead.
-
-Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so
-this implementation repeats this violation to stay consistent with Exim.
-This is in preparation for UTF-8 data.
-
-Sieve scripts cannot contain NUL characters in strings, but mail
-headers could contain MIME encoded NUL characters, which could never
-be matched by Sieve scripts using exact comparisons.  For that reason,
-this implementation extends the Sieve quoted string syntax with \0
-to describe a NUL character, violating \0 being the same as 0 in
-RFC 3028.  Even without using \0, the following tests are all true in
-this implementation. Implementations that use C-style strings will only
-evaluate the first test as true.
-
-  Subject: =?iso-8859-1?q?abc=00def
-
-  header :contains "Subject" ["abc"]
-  header :contains "Subject" ["def"]
-  header :matches "Subject" ["abc?def"]
-
-Note that by considering Sieve to be an MUA, RFC 2047 can be interpreted
-in a way that NUL characters truncating strings is allowed for Sieve
-implementations, although not recommended. It is further allowed to use
-encoded NUL characters in headers, but that's not recommended either.
-The above example shows why.
-
-RFC 3028 states that if an implementation fails to convert a character
-set to UTF-8, two strings cannot be equal if one contains octets greater
-than 127. Assuming that all unknown character sets are one-byte character
-sets with the lower 128 octets being US-ASCII is not sound, so this
-implementation violates RFC 3028 and treats such MIME words literally.
-That way at least something could be matched.
-
-The folder specified by *fileinto* must not contain the character
-sequence ``##`..`##'' to avoid security problems. RFC 3028 does not specify the
-syntax of folders apart from *keep* being equivalent to
-
-  fileinto "INBOX";
-
-This implementation uses _inbox_ instead.
-
-Sieve script errors currently cause messages to be silently filed into
-_inbox_.  RFC 3028 requires that the user is notified of that condition.
-This may be implemented in the future by adding a header line to mails that
-are filed into _inbox_ due to an error in the filter.
-
-
-
-[[CHAPeximfilter]]
-Exim filter files
------------------
-This chapter contains a full description of the contents of Exim filter files.
-
-
-Format of Exim filter files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Apart from leading white space, the first text in an Exim filter file must be
-
-  # Exim filter
-
-This is what distinguishes it from a conventional '.forward' file or a Sieve
-filter file. If the file does not have this initial line (or the equivalent for
-a Sieve filter), it is treated as a conventional '.forward' file, both when
-delivering mail and when using the %-bf% testing mechanism. The white space in
-the line is optional, and any capitalization may be used. Further text on the
-same line is treated as a comment. For example, you could have
-
-  #   Exim filter   <<== do not edit or remove this line!
-
-The remainder of the file is a sequence of filtering commands, which consist of
-keywords and data values. For example, in the command
-
-  deliver gulliver@lilliput.fict.example
-
-the keyword is `deliver` and the data value is
-`gulliver@lilliput.fict.example`. White space or line breaks separate the
-components of a command, except in the case of conditions for the ^if^ command,
-where round brackets (parentheses) also act as separators. Complete commands
-are separated from each other by white space or line breaks; there are no
-special terminators. Thus, several commands may appear on one line, or one
-command may be spread over a number of lines.
-
-If the character # follows a separator anywhere in a command, everything from
-# up to the next newline is ignored. This provides a way of including comments
-in a filter file.
-
-
-Data values in filter commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two ways in which a data value can be input:
-
-- If the text contains no white space then it can be typed verbatim. However, if
-it is part of a condition, it must also be free of round brackets
-(parentheses), as these are used for grouping in conditions.
-
-- Otherwise, it must be enclosed in double quotation marks. In this case, the
-character \ (backslash) is treated as an ``escape character'' within the string,
-causing the following character or characters to be treated specially:
-+
-&&&&
-`\n`   is replaced by a newline
-`\r`   is replaced by a carriage return
-`\t`   is replaced by a tab
-&&&&
-
-Backslash followed by up to three octal digits is replaced by the character
-specified by those digits, and \x followed by up to two hexadecimal digits is
-treated similarly. Backslash followed by any other character is replaced
-by the second character, so that in particular, \\" becomes " and \\ becomes
-\. A data item enclosed in double quotes can be continued onto the next line
-by ending the first line with a backslash. Any leading white space at the start
-of the continuation line is ignored.
-
-In addition to the escape character processing that occurs when strings are
-enclosed in quotes, most data values are also subject to 'string expansion'
-(as described in the next section), in which case the characters `\$` and `\`
-are also significant. This means that if a single backslash is actually
-required in such a string, and the string is also quoted, \\\\ has to be
-entered.
-
-The maximum permitted length of a data string, before expansion, is 1024
-characters.
-
-
-[[SECTfilterstringexpansion]]
-String expansion
-~~~~~~~~~~~~~~~~
-Most data values are expanded before use. Expansion consists of replacing
-substrings beginning with `\$` with other text. The full expansion facilities
-available in Exim are extensive. If you want to know everything that Exim can
-do with strings, you should consult the chapter on string expansion in the Exim
-documentation.
-
-In filter files, by far the most common use of string expansion is the
-substitution of the contents of a variable. For example, the substring
-
-  $reply_address
-
-is replaced by the address to which replies to the message should be sent. If
-such a variable name is followed by a letter or digit or underscore, it must be
-enclosed in curly brackets (braces), for example,
-
-  ${reply_address}
-
-If a `\$` character is actually required in an expanded string, it must be
-escaped with a backslash, and because backslash is also an escape character in
-quoted input strings, it must be doubled in that case. The following two
-examples illustrate two different ways of testing for a `\$` character in a
-message:
-
-  if $message_body contains \$ then ...
-  if $message_body contains "\\$" then ...
-
-You can prevent part of a string from being expanded by enclosing it between
-two occurrences of `\N`. For example,
-
-  if $message_body contains \N$$$$\N then ...
-
-tests for a run of four dollar characters.
-
-
-Some useful general variables
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A complete list of the available variables is given in the Exim documentation.
-This shortened list contains the ones that are most likely to be useful in
-personal filter files:
-
-$body_linecount$: The number of lines in the body of the message.
-
-$body_zerocount$: The number of binary zero characters in the body of the
-message.
-
-
-$home$: In conventional configurations, this variable normally contains the
-user's home directory. The system administrator can, however, change this.
-
-$local_part$: The part of the email address that precedes the @ sign --
-normally the user's login name. If support for multiple personal mailboxes is
-enabled (see section <<SECTmbox>> below) and a prefix or suffix for the local
-part was recognized, it is removed from the string in this variable.
-
-$local_part_prefix$: If support for multiple personal mailboxes is enabled
-(see section <<SECTmbox>> below), and a local part prefix was recognized,
-this variable contains the prefix. Otherwise it contains an empty string.
-
-$local_part_suffix$: If support for multiple personal mailboxes is enabled
-(see section <<SECTmbox>> below), and a local part suffix was recognized,
-this variable contains the suffix. Otherwise it contains an empty string.
-
-$message_body$: The initial portion of the body of the message. By default,
-up to 500 characters are read into this variable, but the system administrator
-can configure this to some other value. Newlines in the body are converted into
-single spaces.
-
-$message_body_end$: The final portion of the body of the message, formatted
-and limited in the same way as $message_body$.
-
-$message_body_size$: The size of the body of the message, in bytes.
-
-$message_headers$: The header lines of the message, concatenated into a
-single string, with newline characters between them.
-
-$message_id$: The message's local identification string, which is unique for
-each message handled by a single host.
-
-$message_size$: The size of the entire message, in bytes.
-
-$original_local_part$: When an address that arrived with the message is
-being processed, this contains the same value as the variable $local_part$.
-However, if an address generated by an alias, forward, or filter file is being
-processed, this variable contains the local part of the original address.
-
-$reply_address$: The contents of the 'Reply-to:' header, if the message
-has one; otherwise the contents of the 'From:' header. It is the address to
-which normal replies to the message should be sent.
-
-$return_path$: The return path -- that is, the sender field that will be
-transmitted as part of the message's envelope if the message is sent to another
-host. This is the address to which delivery errors are sent. In many cases,
-this variable has the same value as $sender_address$, but if, for example,
-an incoming message to a mailing list has been expanded, $return_path$ may
-have been changed to contain the address of the list maintainer.
-
-$sender_address$: The sender address that was received in the envelope of
-the message. This is not necessarily the same as the contents of the 'From:'
-or 'Sender:' header lines. For delivery error messages (``bounce messages'')
-there is no sender address, and this variable is empty.
-
-$tod_full$: A full version of the time and date, for example: Wed, 18 Oct
-1995 09:51:40 +0100. The timezone is always given as a numerical offset from
-GMT.
-
-$tod_log$: The time and date in the format used for writing Exim's log files,
-without the timezone, for example: 1995-10-12 15:32:29.
-
-$tod_zone$: The local timezone offset, for example: +0100.
-
-
-
-[[SECTheadervariables]]
-Header variables
-~~~~~~~~~~~~~~~~
-There is a special set of expansion variables containing the header lines of
-the message being processed. These variables have names beginning with
-$header_$ followed by the name of the header line, terminated by a colon.
-For example,
-
-  $header_from:
-  $header_subject:
-
-The whole item, including the terminating colon, is replaced by the contents of
-the message header line. If there is more than one header line with the same
-name, their contents are concatenated. For header lines whose data consists of
-a list of addresses (for example, 'From:' and 'To:'), a comma and newline is
-inserted between each set of data. For all other header lines, just a newline
-is used.
-
-Leading and trailing white space is removed from header line data, and if there
-are any MIME ``words'' that are encoded as defined by RFC 2047 (because they
-contain non-ASCII characters), they are decoded and translated, if possible, to
-a local character set. Translation is attempted only on operating systems that
-have the ^^iconv()^^ function. This makes the header line look the same as it
-would when displayed by an MUA. The default character set is ISO-8859-1, but
-this can be changed by means of the ^headers^ command (see below).
-
-If you want to see the actual characters that make up a header line, you can
-specify $rheader_$ instead of $header_$. This inserts the ``raw''
-header line, unmodified.
-
-There is also an intermediate form, requested by $bheader_$, which removes
-leading and trailing space and decodes MIME ``words'', but does not do any
-character translation. If an attempt to decode what looks superficially like a
-MIME ``word'' fails, the raw string is returned. If decoding produces a binary
-zero character, it is replaced by a question mark.
-
-The capitalization of the name following $header_$ is not significant.
-Because any printing character except colon may appear in the name of a
-message's header (this is a requirement of RFC 2822, the document that
-describes the format of a mail message) curly brackets must 'not' be used in
-this case, as they will be taken as part of the header name. Two shortcuts are
-allowed in naming header variables:
-
-- The initiating $header_$, $rheader_$, or $bheader_$ can be
-abbreviated to $h_$, $rh_$, or $bh_$, respectively.
-
-- The terminating colon can be omitted if the next character is white space. The
-white space character is retained in the expanded string. However, this is not
-recommended, because it makes it easy to forget the colon when it really is
-needed.
-
-If the message does not contain a header of the given name, an empty string is
-substituted. Thus it is important to spell the names of headers correctly. Do
-not use $header_Reply_to$ when you really mean $header_Reply-to$.
-
-
-User variables
-~~~~~~~~~~~~~~
-There are ten user variables with names $n0$ -- $n9$ that can be
-incremented by the ^add^ command (see section <<SECTadd>>). These can be used
-for ``scoring'' messages in various ways. If Exim is configured to run a
-``system filter'' on every message, the values left in these variables are
-copied into the variables $sn0$ -- $sn9$ at the end of the system filter, thus
-making them available to users' filter files. How these values are used is
-entirely up to the individual installation.
-
-
-Current directory
-~~~~~~~~~~~~~~~~~
-The contents of your filter file should not make any assumptions about the
-current directory. It is best to use absolute paths for file names; you
-can normally make use of the $home$ variable to refer to your home directory.
-The ^save^ command automatically inserts $home$ at the start of non-absolute
-paths.
-
-
-
-
-[[SECTsigdel]]
-Significant deliveries
-~~~~~~~~~~~~~~~~~~~~~~
-When in the course of delivery a message is processed by a filter file, what
-happens next, that is, after the filter file has been processed, depends on
-whether or not the filter sets up any 'significant deliveries'. If at least
-one significant delivery is set up, the filter is considered to have handled
-the entire delivery arrangements for the current address, and no further
-processing of the address takes place. If, however, no significant deliveries
-are set up, Exim continues processing the current address as if there were no
-filter file, and typically sets up a delivery of a copy of the message into a
-local mailbox. In particular, this happens in the special case of a filter file
-containing only comments.
-
-The delivery commands ^deliver^, ^save^, and ^pipe^ are by default
-significant. However, if such a command is preceded by the word ^unseen^, its
-delivery is not considered to be significant. In contrast, other commands such
-as ^mail^ and ^vacation^ do not set up significant deliveries unless
-preceded by the word ^seen^.
-
-The following example commands set up significant deliveries:
-
-  deliver jack@beanstalk.example
-  pipe $home/bin/mymailscript
-  seen mail subject "message discarded"
-  seen finish
-
-The following example commands do not set up significant deliveries:
-
-  unseen deliver jack@beanstalk.example
-  unseen pipe $home/bin/mymailscript
-  mail subject "message discarded"
-  finish
-
-
-
-
-Filter commands
-~~~~~~~~~~~~~~~
-The filter commands that are described in subsequent sections are listed
-below, with the section in which they are described in brackets:
-
-[frame="none"]
-`-------------`-----------------------------------------------
-^add^         ~~increment a user variable (section <<SECTadd>>)
-^deliver^     ~~deliver to an email address (section <<SECTdeliver>>)
-^fail^        ~~force delivery failure (sysadmin use) (section <<SECTfail>>)
-^finish^      ~~end processing (section <<SECTfinish>>)
-^freeze^      ~~freeze message (sysadmin use) (section <<SECTfreeze>>)
-^headers^     ~~set the header character set (section <<SECTheaders>>)
-^if^          ~~test condition(s) (section <<SECTif>>)
-^logfile^     ~~define log file (section <<SECTlog>>)
-^logwrite^    ~~write to log file (section <<SECTlog>>)
-^mail^        ~~send a reply message (section <<SECTmail>>)
-^pipe^        ~~pipe to a command (section <<SECTpipe>>)
-^save^        ~~save to a file (section <<SECTsave>>)
-^testprint^   ~~print while testing (section <<SECTtestprint>>)
-^vacation^    ~~tailored form of ^mail^ (section <<SECTmail>>)
---------------------------------------------------------------
-
-The ^headers^ command has additional parameters that can be used only in a
-system filter. The ^fail^ and ^freeze^ commands are available only when
-Exim's filtering facilities are being used as a system filter, and are
-therefore usable only by the system administrator and not by ordinary users.
-They are mentioned only briefly in this document; for more information, see the
-main Exim specification.
-
-
-
-[[SECTadd]]
-The add command
-~~~~~~~~~~~~~~~
-&&&
-`     add `<'number'>` to `<'user variable'>
-`e.g. add 2 to n3`
-&&&
-
-There are 10 user variables of this type, with names $n0$ -- $n9$. Their
-values can be obtained by the normal expansion syntax (for example $n3$) in
-other commands. At the start of filtering, these variables all contain zero.
-Both arguments of the ^add^ command are expanded before use, making it
-possible to add variables to each other. Subtraction can be obtained by adding
-negative numbers.
-
-
-
-[[SECTdeliver]]
-The deliver command
-~~~~~~~~~~~~~~~~~~~
-
-&&&
-`     deliver` <'mail address'>
-`e.g. deliver "Dr Livingstone <David@somewhere.africa.example>"`
-&&&
-
-This command provides a forwarding operation. The delivery that it sets up is
-significant unless the command is preceded by ^unseen^ (see section
-<<SECTsigdel>>). The message is sent on to the given address, exactly as
-happens if the address had appeared in a traditional '.forward' file. If you
-want to deliver the message to a number of different addresses, you can use
-more than one ^deliver^ command (each one may have only one address). However,
-duplicate addresses are discarded.
-
-To deliver a copy of the message to your normal mailbox, your login name can be
-given as the address. Once an address has been processed by the filtering
-mechanism, an identical generated address will not be so processed again, so
-doing this does not cause a loop.
-
-However, if you have a mail alias, you should 'not' refer to it here. For
-example, if the mail address 'L.Gulliver' is aliased to 'lg303' then all
-references in Gulliver's '.forward' file should be to 'lg303'. A reference
-to the alias will not work for messages that are addressed to that alias,
-since, like '.forward' file processing, aliasing is performed only once on an
-address, in order to avoid looping.
-
-Following the new address, an optional second address, preceded by
-^errors_to^ may appear. This changes the address to which delivery errors on
-the forwarded message will be sent. Instead of going to the message's original
-sender, they go to this new address. For ordinary users, the only value that is
-permitted for this address is the user whose filter file is being processed.
-For example, the user 'lg303' whose mailbox is in the domain
-'lilliput.example' could have a filter file that contains
-
-  deliver jon@elsewhere.example errors_to lg303@lilliput.example
-
-Clearly, using this feature makes sense only in situations where not all
-messages are being forwarded. In particular, bounce messages must not be
-forwarded in this way, as this is likely to create a mail loop if something
-goes wrong.
-
-
-
-[[SECTsave]]
-The save command
-~~~~~~~~~~~~~~~~
-&&&
-`     save `<'file name'>
-`e.g. save $home/mail/bookfolder`
-&&&
-
-This command specifies that a copy of the message is to be appended to the
-given file (that is, the file is to be used as a mail folder). The delivery
-that ^save^ sets up is significant unless the command is preceded by
-^unseen^ (see section <<SECTsigdel>>).
-
-More than one ^save^ command may be obeyed; each one causes a copy of the
-message to be written to its argument file, provided they are different
-(duplicate ^save^ commands are ignored).
-
-If the file name does not start with a / character, the contents of the
-$home$ variable are prepended, unless it is empty. In conventional
-configurations, this variable is normally set in a user filter to the user's
-home directory, but the system administrator may set it to some other path. In
-some configurations, $home$ may be unset, in which case a non-absolute path
-name may be generated. Such configurations convert this to an absolute path
-when the delivery takes place. In a system filter, $home$ is never set.
-
-The user must of course have permission to write to the file, and the writing
-of the file takes place in a process that is running as the user, under the
-user's primary group. Any secondary groups to which the user may belong are not
-normally taken into account, though the system administrator can configure Exim
-to set them up. In addition, the ability to use this command at all is
-controlled by the system administrator -- it may be forbidden on some systems.
-
-An optional mode value may be given after the file name. The value for the mode
-is interpreted as an octal number, even if it does not begin with a zero. For
-example:
-
-  save /some/folder 640
-
-This makes it possible for users to override the system-wide mode setting for
-file deliveries, which is normally 600. If an existing file does not have the
-correct mode, it is changed.
-
-An alternative form of delivery may be enabled on your system, in which each
-message is delivered into a new file in a given directory. If this is the case,
-this functionality can be requested by giving the directory name terminated by
-a slash after the ^save^ command, for example
-
-  save separated/messages/
-
-There are several different formats for such deliveries; check with your system
-administrator or local documentation to find out which (if any) are available
-on your system. If this functionality is not enabled, the use of a path name
-ending in a slash causes an error.
-
-
-
-[[SECTpipe]]
-The pipe command
-~~~~~~~~~~~~~~~~
-&&&
-`     pipe `<'command'>
-`e.g. pipe "$home/bin/countmail $sender_address"`
-&&&
-
-This command specifies that the message is to be delivered to the specified
-command using a pipe. The delivery that it sets up is significant unless the
-command is preceded by ^unseen^ (see section <<SECTsigdel>>). Remember,
-however, that no deliveries are done while the filter is being processed. All
-deliveries happen later on. Therefore, the result of running the pipe is not
-available to the filter.
-
-When the deliveries are done, a separate process is run, and a copy of the
-message is passed on its standard input. The process runs as the user, under
-the user's primary group. Any secondary groups to which the user may belong are
-not normally taken into account, though the system administrator can configure
-Exim to set them up. More than one ^pipe^ command may appear; each one causes
-a copy of the message to be written to its argument pipe, provided they are
-different (duplicate ^pipe^ commands are ignored).
-
-When the time comes to transport the message,
-the command supplied to ^pipe^ is split up by Exim into a command name and a
-number of arguments. These are delimited by white space except for arguments
-enclosed in double quotes, in which case backslash is interpreted as an escape,
-or in single quotes, in which case no escaping is recognized. Note that as the
-whole command is normally supplied in double quotes, a second level of quoting
-is required for internal double quotes. For example:
-
-  pipe "$home/myscript \"size is $message_size\""
-
-String expansion is performed on the separate components after the line has
-been split up, and the command is then run directly by Exim; it is not run
-under a shell. Therefore, substitution cannot change the number of arguments,
-nor can quotes, backslashes or other shell metacharacters in variables cause
-confusion.
-
-Documentation for some programs that are normally run via this kind of pipe
-often suggest that the command should start with
-
-  IFS=" "
-
-This is a shell command, and should 'not' be present in Exim filter files,
-since it does not normally run the command under a shell.
-
-However, there is an option that the administrator can set to cause a shell to
-be used. In this case, the entire command is expanded as a single string and
-passed to the shell for interpretation. It is recommended that this be avoided
-if at all possible, since it can lead to problems when inserted variables
-contain shell metacharacters.
-
-The default PATH set up for the command is determined by the system
-administrator, usually containing at least _/usr/bin_ so that common commands
-are available without having to specify an absolute file name. However, it is
-possible for the system administrator to restrict the pipe facility so that the
-command name must not contain any / characters, and must be found in one of the
-directories in the configured PATH. It is also possible for the system
-administrator to lock out the use of the ^pipe^ command altogether.
-
-When the command is run, a number of environment variables are set up. The
-complete list for pipe deliveries may be found in the Exim reference manual.
-Those that may be useful for pipe deliveries from user filter files are:
-
-&&&
-`DOMAIN            `   the domain of the address
-`HOME              `   your home directory
-`LOCAL_PART        `   see below
-`LOCAL_PART_PREFIX `   see below
-`LOCAL_PART_SUFFIX `   see below
-`LOGNAME           `   your login name
-`MESSAGE_ID        `   the unique id of the message
-`PATH              `   the command search path
-`RECIPIENT         `   the complete recipient address
-`SENDER            `   the sender of the message
-`SHELL             `   `/bin/sh`
-`USER              `   see below
-&&&
-
-LOCAL_PART, LOGNAME, and USER are all set to the same value,
-namely, your login id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may
-be set if Exim is configured to recognize prefixes or suffixes in the local
-parts of addresses. For example, a message addressed to
-'pat-suf2@domain.example' may cause the filter for user 'pat' to be run. If
-this sets up a pipe delivery, LOCAL_PART_SUFFIX is `-suf2` when the
-pipe command runs. The system administrator has to configure Exim specially for
-this feature to be available.
-
-If you run a command that is a shell script, be very careful in your use of
-data from the incoming message in the commands in your script. RFC 2822 is very
-generous in the characters that are permitted to appear in mail addresses, and
-in particular, an address may begin with a vertical bar or a slash. For this
-reason you should always use quotes round any arguments that involve data from
-the message, like this:
-
-  /some/command '$SENDER'
-
-so that inserted shell meta-characters do not cause unwanted effects.
-
-Remember that, as was explained earlier, the pipe command is not run at the
-time the filter file is interpreted. The filter just defines what deliveries
-are required for one particular addressee of a message. The deliveries
-themselves happen later, once Exim has decided everything that needs to be done
-for the message.
-
-A consequence of this is that you cannot inspect the return code from the pipe
-command from within the filter. Nevertheless, the code returned by the command
-is important, because Exim uses it to decide whether the delivery has succeeded
-or failed.
-
-The command should return a zero completion code if all has gone well. Most
-non-zero codes are treated by Exim as indicating a failure of the pipe. This is
-treated as a delivery failure, causing the message to be returned to its
-sender. However, there are some completion codes that are treated as temporary
-errors. The message remains on Exim's spool disk, and the delivery is tried
-again later, though it will ultimately time out if the delivery failures go on
-too long. The completion codes to which this applies can be specified by the
-system administrator; the default values are 73 and 75.
-
-The pipe command should not normally write anything to its standard output or
-standard error file descriptors. If it does, whatever is written is normally
-returned to the sender of the message as a delivery error, though this action
-can be varied by the system administrator.
-
-
-
-[[SECTmail]]
-Mail commands
-~~~~~~~~~~~~~
-There are two commands that cause the creation of a new mail message, neither
-of which count as a significant delivery unless the command is preceded by the
-word ^seen^ (see section <<SECTsigdel>>). This is a powerful facility, but it
-should be used with care, because of the danger of creating infinite sequences
-of messages. The system administrator can forbid the use of these commands
-altogether.
-
-To help prevent runaway message sequences, these commands have no effect when
-the incoming message is a bounce (delivery error) message, and messages sent by
-this means are treated as if they were reporting delivery errors. Thus, they
-should never themselves cause a bounce message to be returned. The basic
-mail-sending command is
-
-&&&
-`mail [to `<'address-list'>`]`
-`     [cc `<'address-list'>`]`
-`     [bcc `<'address-list'>`]`
-`     [from `<'address'>`]`
-`     [reply_to `<'address'>`]`
-`     [subject `<'text'>`]`
-`     [extra_headers `<'text'>`]`
-`     [text `<'text'>`]`
-`     [[expand] file `<'filename'>`]`
-`     [return message]`
-`     [log `<'log file name'>`]`
-`     [once `<'note file name'>`]`
-`     [once_repeat `<'time interval'>`]`
-
-`e.g. mail text "Your message about $h_subject: has been received"`
-&&&
-
-Each <'address-list'> can contain a number of addresses, separated by commas,
-in the format of a 'To:' or 'Cc:' header line. In fact, the text you supply
-here is copied exactly into the appropriate header line. It may contain
-additional information as well as email addresses. For example:
-
-....
-mail to "Julius Caesar <jc@rome.example>, \
-         <ma@rome.example> (Mark A.)"
-....
-
-Similarly, the texts supplied for ^from^ and ^reply_to^ are copied into
-their respective header lines.
-
-As a convenience for use in one common case, there is also a command called
-^vacation^. It behaves in the same way as ^mail^, except that the defaults for
-the %subject%, %file%, %log%, %once%, and %once_repeat% options are
-
-  subject "On vacation"
-  expand file .vacation.msg
-  log  .vacation.log
-  once .vacation
-  once_repeat 7d
-
-respectively. These are the same file names and repeat period used by the
-traditional Unix ^vacation^ command. The defaults can be overridden by
-explicit settings, but if a file name is given its contents are expanded only
-if explicitly requested.
-
-*Warning*: The ^vacation^ command should always be used conditionally,
-subject to at least the ^personal^ condition (see section <<SECTpersonal>>
-below) so as not to send automatic replies to non-personal messages from
-mailing lists or elsewhere. Sending an automatic response to a mailing list or
-a mailing list manager is an Internet Sin.
-
-For both commands, the key/value argument pairs can appear in any order. At
-least one of ^text^ or ^file^ must appear (except with ^vacation^, where
-there is a default for ^file^); if both are present, the text string appears
-first in the message. If ^expand^ precedes ^file^, each line of the file is
-subject to string expansion before it is included in the message.
-
-Several lines of text can be supplied to ^text^ by including the escape
-sequence ``\n'' in the string wherever a newline is required. If the command is
-output during filter file testing, newlines in the text are shown as ``\n''.
-
-Note that the keyword for creating a 'Reply-To:' header is ^reply_to^,
-because Exim keywords may contain underscores, but not hyphens. If the ^from^
-keyword is present and the given address does not match the user who owns the
-forward file, Exim normally adds a 'Sender:' header to the message,
-though it can be configured not to do this.
-
-The %extra_headers% keyword allows you to add custom header lines to the
-message. The text supplied must be one or more syntactically valid RFC 2822
-header lines. You can use ``\n'' within quoted text to specify newlines between
-headers, and also to define continued header lines. For example:
-
-  extra_headers "h1: first\nh2: second\n continued\nh3: third"
-
-No newline should appear at the end of the final header line.
-
-If no ^to^ argument appears, the message is sent to the address in the
-$reply_address$ variable (see section <<SECTfilterstringexpansion>> above).
-An 'In-Reply-To:' header is automatically included in the created message,
-giving a reference to the message identification of the incoming message.
-
-If ^return message^ is specified, the incoming message that caused the filter
-file to be run is added to the end of the message, subject to a maximum size
-limitation.
-
-If a log file is specified, a line is added to it for each message sent.
-
-If a ^once^ file is specified, it is used to hold a database for remembering
-who has received a message, and no more than one message is ever sent to any
-particular address, unless ^once_repeat^ is set. This specifies a time
-interval after which another copy of the message is sent. The interval is
-specified as a sequence of numbers, each followed by the initial letter of one
-of ``seconds'', ``minutes'', ``hours'', ``days'', or ``weeks''. For example,
-
-  once_repeat 5d4h
-
-causes a new message to be sent if 5 days and 4 hours have elapsed since the
-last one was sent. There must be no white space in a time interval.
-
-Commonly, the file name specified for ^once^ is used as the base name for
-direct-access (DBM) file operations. There are a number of different DBM
-libraries in existence. Some operating systems provide one as a default, but
-even in this case a different one may have been used when building Exim. With
-some DBM libraries, specifying ^once^ results in two files being created,
-with the suffixes _.dir_ and _.pag_ being added to the given name. With
-some others a single file with the suffix _.db_ is used, or the name is used
-unchanged.
-
-Using a DBM file for implementing the ^once^ feature means that the file
-grows as large as necessary. This is not usually a problem, but some system
-administrators want to put a limit on it. The facility can be configured not to
-use a DBM file, but instead, to use a regular file with a maximum size. The
-data in such a file is searched sequentially, and if the file fills up, the
-oldest entry is deleted to make way for a new one. This means that some
-correspondents may receive a second copy of the message after an unpredictable
-interval. Consult your local information to see if your system is configured
-this way.
-
-More than one ^mail^ or ^vacation^ command may be obeyed in a single filter
-run; they are all honoured, even when they are to the same recipient.
-
-
-
-[[SECTlog]]
-Logging commands
-~~~~~~~~~~~~~~~~
-A log can be kept of actions taken by a filter file. This facility is normally
-available in conventional configurations, but there are some situations where
-it might not be. Also, the system administrator may choose to disable it. Check
-your local information if in doubt.
-
-Logging takes place while the filter file is being interpreted. It does not
-queue up for later like the delivery commands. The reason for this is so that a
-log file need be opened only once for several write operations. There are two
-commands, neither of which constitutes a significant delivery. The first
-defines a file to which logging output is subsequently written:
-
-&&&
-`     logfile `<'file name'>
-`e.g. logfile $home/filter.log`
-&&&
-
-The file name must be fully qualified. You can use $home$, as in this
-example, to refer to your home directory. The file name may optionally be
-followed by a mode for the file, which is used if the file has to be created.
-For example,
-
-  logfile $home/filter.log 0644
-
-The number is interpreted as octal, even if it does not begin with a zero.
-The default for the mode is 600. It is suggested that the ^logfile^ command
-normally appear as the first command in a filter file. Once ^logfile^ has
-been obeyed, the ^logwrite^ command can be used to write to the log file:
-
-&&&
-`     logwrite "`<'some text string'>`"`
-`e.g. logwrite "$tod_log $message_id processed"`
-&&&
-
-It is possible to have more than one ^logfile^ command, to specify writing to
-different log files in different circumstances. Writing takes place at the end
-of the file, and a newline character is added to the end of each string if
-there isn't one already there. Newlines can be put in the middle of the string
-by using the ``\n'' escape sequence. Lines from simultaneous deliveries may get
-interleaved in the file, as there is no interlocking, so you should plan your
-logging with this in mind. However, data should not get lost.
-
-
-
-[[SECTfinish]]
-The finish command
-~~~~~~~~~~~~~~~~~~
-The command ^finish^, which has no arguments, causes Exim to stop
-interpreting the filter file. This is not a significant action unless preceded
-by ^seen^. A filter file containing only ^seen finish^ is a black hole.
-
-
-[[SECTtestprint]]
-The testprint command
-~~~~~~~~~~~~~~~~~~~~~
-It is sometimes helpful to be able to print out the values of variables when
-testing filter files. The command
-
-&&&
-`     testprint `<'text'>
-`e.g. testprint "home=$home reply_address=$reply_address"`
-&&&
-
-does nothing when mail is being delivered. However, when the filtering code is
-being tested by means of the %-bf% option (see section <<SECTtesting>> above),
-the value of the string is written to the standard output.
-
-
-[[SECTfail]]
-The fail command
-~~~~~~~~~~~~~~~~
-When Exim's filtering facilities are being used as a system filter, the
-^fail^ command is available, to force delivery failure. Because this command
-is normally usable only by the system administrator, and not enabled for use by
-ordinary users, it is described in more detail in the main Exim specification
-rather than in this document.
-
-
-[[SECTfreeze]]
-The freeze command
-~~~~~~~~~~~~~~~~~~
-When Exim's filtering facilities are being used as a system filter, the
-^freeze^ command is available, to freeze a message on the queue. Because this
-command is normally usable only by the system administrator, and not enabled
-for use by ordinary users, it is described in more detail in the main Exim
-specification rather than in this document.
-
-
-
-[[SECTheaders]]
-The headers command
-~~~~~~~~~~~~~~~~~~~
-The ^headers^ command can be used to change the target character set that is
-used when translating the contents of encoded header lines for insertion by the
-$header_$ mechanism (see section <<SECTheadervariables>> above). The default
-can be set in the Exim configuration; if not specified, ISO-8859-1 is used. The
-only currently supported format for the ^headers^ command in user filters is as
-in this example:
-
-  headers charset "UTF-8"
-
-That is, ^headers^ is followed by the word ^charset^ and then the name of a
-character set. This particular example would be useful if you wanted to compare
-the contents of a header to a UTF-8 string.
-
-In system filter files, the ^headers^ command can be used to add or remove
-header lines from the message. These features are described in the main Exim
-specification.
-
-
-
-[[SECTif]]
-Obeying commands conditionally
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Most of the power of filtering comes from the ability to test conditions and
-obey different commands depending on the outcome. The ^if^ command is used to
-specify conditional execution, and its general form is
-
-&&&
-`if    `<'condition'>
-`then  `<'commands'>
-`elif  `<'condition'>
-`then  `<'commands'>
-`else  `<'commands'>
-`endif`
-&&&
-
-There may be any number of ^elif^ and ^then^ sections (including none) and
-the ^else^ section is also optional. Any number of commands, including nested
-^if^ commands, may appear in any of the <'commands'> sections.
-
-Conditions can be combined by using the words ^and^ and ^or^, and round
-brackets (parentheses) can be used to specify how several conditions are to
-combine. Without brackets, ^and^ is more binding than ^or^.
-For example,
-
-  if
-    $h_subject: contains "Make money" or
-    $h_precedence: is "junk" or
-    ($h_sender: matches ^\\d{8}@ and not personal) or
-    $message_body contains "this is not spam"
-  then
-    seen finish
-  endif
-
-A condition can be preceded by ^not^ to negate it, and there are also some
-negative forms of condition that are more English-like.
-
-
-
-String testing conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~
-There are a number of conditions that operate on text strings, using the words
-``begins'', ``ends'', ``is'', ``contains'' and ``matches''. If you want to apply the same
-test to more than one header line, you can easily concatenate them into a
-single string for testing, as in this example:
-
-  if "$h_to:, $h_cc:" contains me@domain.example then ...
-
-If a string-testing condition name is written in lower case, the testing
-of letters is done without regard to case; if it is written in upper case
-(for example, ``CONTAINS''), the case of letters is taken into account.
-
-&&&
-`     `<'text1'>` begins `<'text2'>
-`     `<'text1'>` does not begin `<'text2'>
-`e.g. $header_from: begins "Friend@"`
-&&&
-
-A ``begins'' test checks for the presence of the second string at the start of
-the first, both strings having been expanded.
-
-&&&
-`     `<'text1'>` ends `<'text2'>
-`     `<'text1'>` does not end `<'text2'>
-`e.g. $header_from: ends "public.com.example"`
-&&&
-
-An ``ends'' test checks for the presence of the second string at the end of
-the first, both strings having been expanded.
-
-&&&
-`     `<'text1'>` is `<'text2'>
-`     `<'text1'>` is not `<'text2'>
-`e.g. $local_part_suffix is "-foo"`
-&&&
-
-An ``is'' test does an exact match between the strings, having first expanded
-both strings.
-
-&&&
-`     `<'text1'>` contains `<'text2'>
-`     `<'text1'>` does not contain `<'text2'>
-`e.g. $header_subject: contains "evolution"`
-&&&
-
-A ``contains'' test does a partial string match, having expanded both strings.
-
-&&&
-`     `<'text1'>` matches `<'text2'>
-`     `<'text1'>` does not match `<'text2'>
-`e.g. $sender_address matches "(bill|john)@"`
-&&&
-
-For a ``matches'' test, after expansion of both strings, the second one is
-interpreted as a regular expression. Exim uses the PCRE regular expression
-library, which provides regular expressions that are compatible with Perl.
-
-The match succeeds if the regular expression matches any part of the first
-string. If you want a regular expression to match only at the start or end of
-the subject string, you must encode that requirement explicitly, using the `^`
-or `$` metacharacters. The above example, which is not so constrained, matches
-all these addresses:
-
-  bill@test.example
-  john@some.example
-  spoonbill@example.com
-  littlejohn@example.com
-
-To match only the first two, you could use this:
-
-  if $sender_address matches "^(bill|john)@" then ...
-
-Care must be taken if you need a backslash in a regular expression, because
-backslashes are interpreted as escape characters both by the string expansion
-code and by Exim's normal processing of strings in quotes. For example, if you
-want to test the sender address for a domain ending in '.com' the regular
-expression is
-
-  \.com$
-
-The backslash and dollar sign in that expression have to be escaped when used
-in a filter command, as otherwise they would be interpreted by the expansion
-code. Thus, what you actually write is
-
-  if $sender_address matches \\.com\$
-
-An alternative way of handling this is to make use of the `\N` expansion
-flag for suppressing expansion:
-
-  if $sender_address matches \N\.com$\N
-
-Everything between the two occurrences of `\N` is copied without change by
-the string expander (and in fact you do not need the final one, because it is
-at the end of the string). If the regular expression is given in quotes
-(mandatory only if it contains white space) you have to write either
-
-  if $sender_address matches "\\\\.com\\$"
-
-or
-
-  if $sender_address matches "\\N\\.com$\\N"
-
-
-If the regular expression contains bracketed sub-expressions, numeric
-variable substitutions such as $1$ can be used in the subsequent actions
-after a successful match. If the match fails, the values of the numeric
-variables remain unchanged. Previous values are not restored after ^endif^.
-In other words, only one set of values is ever available. If the condition
-contains several sub-conditions connected by ^and^ or ^or^, it is the
-strings extracted from the last successful match that are available in
-subsequent actions. Numeric variables from any one sub-condition are also
-available for use in subsequent sub-conditions, because string expansion of a
-condition occurs just before it is tested.
-
-
-Numeric testing conditions
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-The following conditions are available for performing numerical tests:
-
-&&&
-`     `<'number1'>` is above `<'number2'>
-`     `<'number1'>` is not above `<'number2'>
-`     `<'number1'>` is below `<'number2'>
-`     `<'number1'>` is not below `<'number2'>
-`e.g. $message_size is not above 10k`
-&&&
-
-The <'number'> arguments must expand to strings of digits, optionally followed
-by one of the letters K or M (upper case or lower case) which cause
-multiplication by 1024 and 1024x1024 respectively.
-
-
-Testing for significant deliveries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can use the ^delivered^ condition to test whether or not any previously
-obeyed filter commands have set up a significant delivery. For example:
-
-  if not delivered then save mail/anomalous endif
-
-``Delivered'' is perhaps a poor choice of name for this condition, because the
-message has not actually been delivered; rather, a delivery has been set up for
-later processing.
-
-
-Testing for error messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-The condition ^error_message^ is true if the incoming message is a bounce
-(mail delivery error) message. Putting the command
-
-  if error_message then finish endif
-
-at the head of your filter file is a useful insurance against things going
-wrong in such a way that you cannot receive delivery error reports. *Note*:
-^error_message^ is a condition, not an expansion variable, and therefore is
-not preceded by `$`.
-
-
-Testing a list of addresses
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is a facility for looping through a list of addresses and applying a
-condition to each of them. It takes the form
-
-&&&
-`foranyaddress `<'string'>` (`<'condition'>`)`
-&&&
-
-where <'string'> is interpreted as a list of RFC 2822 addresses, as in a
-typical header line, and <'condition'> is any valid filter condition or
-combination of conditions. The ``group'' syntax that is defined for certain
-header lines that contain addresses is supported.
-
-The parentheses surrounding the condition are mandatory, to delimit it from
-possible further sub-conditions of the enclosing ^if^ command. Within the
-condition, the expansion variable $thisaddress$ is set to the non-comment
-portion of each of the addresses in the string in turn. For example, if the
-string is
-
-  B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister)
-
-then $thisaddress$ would take on the values `bart@sfld.example` and
-`lisa@sfld.example` in turn.
-
-If there are no valid addresses in the list, the whole condition is false. If
-the internal condition is true for any one address, the overall condition is
-true and the loop ends. If the internal condition is false for all addresses in
-the list, the overall condition is false. This example tests for the presence
-of an eight-digit local part in any address in a 'To:' header:
-
-  if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ...
-
-When the overall condition is true, the value of $thisaddress$ in the
-commands that follow ^then^ is the last value it took on inside the loop. At
-the end of the ^if^ command, the value of $thisaddress$ is reset to what it
-was before. It is best to avoid the use of multiple occurrences of
-^foranyaddress^, nested or otherwise, in a single ^if^ command, if the
-value of $thisaddress$ is to be used afterwards, because it isn't always
-clear what the value will be. Nested ^if^ commands should be used instead.
-
-Header lines can be joined together if a check is to be applied to more than
-one of them. For example:
-
-  if foranyaddress $h_to:,$h_cc: ....
-
-scans through the addresses in both the 'To:' and the 'Cc:' headers.
-
-
-[[SECTpersonal]]
-Testing for personal mail
-~~~~~~~~~~~~~~~~~~~~~~~~~
-A common requirement is to distinguish between incoming personal mail and mail
-from a mailing list, or from a robot or other automatic process (for example, a
-bounce message). In particular, this test is normally required for ``vacation
-messages''.
-
-The ^personal^ condition checks that the message is not a bounce message and
-that the current user's email address appears in the 'To:' header. It also
-checks that the sender is not the current user or one of a number of common
-daemons, and that there are no header lines starting 'List-' in the message.
-Finally, it checks the content of the 'Precedence:' header line, if there is
-one.
-
-You should always use the ^personal^ condition when generating automatic
-responses. This example shows the use of ^personal^ in a filter file that is
-sending out vacation messages:
-
-  if personal then
-    mail to $reply_address
-    subject "I am on holiday"
-    file $home/vacation/message
-    once $home/vacation/once
-    once_repeat 10d
-  endif
-
-It is tempting, when writing commands like the above, to quote the original
-subject in the reply. For example:
-
-  subject "Re: $h_subject:"
-
-There is a danger in doing this, however. It may allow a third party to
-subscribe you to an opt-in mailing list, provided that the list accepts bounce
-messages as subscription confirmations. (Messages sent from filters are always
-sent as bounce messages.) Well-managed lists require a non-bounce message to
-confirm a subscription, so the danger is relatively small.
-
-If prefixes or suffixes are in use for local parts -- something which depends
-on the configuration of Exim (see section <<SECTmbox>> below) -- the tests for
-the current user are done with the full address (including the prefix and
-suffix, if any) as well as with the prefix and suffix removed. If the system is
-configured to rewrite local parts of mail addresses, for example, to rewrite
-`dag46` as `Dirk.Gently`, the rewritten form of the address is also used in
-the tests.
-
-
-
-Alias addresses for the personal condition
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-It is quite common for people who have mail accounts on a number of different
-systems to forward all their mail to one system, and in this case a check for
-personal mail should test all their various mail addresses. To allow for this,
-the ^personal^ condition keyword can be followed by
-
-&&&
-`alias `<'address'>
-&&&
-
-any number of times, for example
-
-  if personal alias smith@else.where.example
-              alias jones@other.place.example
-  then ...
-
-The alias addresses are treated as alternatives to the current user's email
-address when testing the contents of header lines.
-
-
-Details of the personal condition
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The basic ^personal^ test is roughly equivalent to the following:
-
-  not error_message and
-  $message_headers does not contain "\nList-Id:" and
-  $message_headers does not contain "\nList-Help:" and
-  $message_headers does not contain "\nList-Subscribe:" and
-  $message_headers does not contain "\nList-Unsubscribe:" and
-  $message_headers does not contain "\nList-Post:" and
-  $message_headers does not contain "\nList-Owner:" and
-  $message_headers does not contain "\nList-Archive:" and
-    (
-    "${if def h_auto-submitted:{present}{absent}}" is "absent" or
-    $header_auto-submitted: is "no"
-    ) and
-  $header_precedence: does not contain "bulk" and
-  $header_precedence: does not contain "list" and
-  $header_precedence: does not contain "junk" and
-  foranyaddress $header_to:
-    ( $thisaddress contains "$local_part$domain" ) and
-  not foranyaddress $header_from:
-    (
-    $thisaddress contains "$local_partdomain" or
-    $thisaddress contains "server" or
-    $thisaddress contains "daemon" or
-    $thisaddress contains "root" or
-    $thisaddress contains "listserv" or
-    $thisaddress contains "majordomo" or
-    $thisaddress contains "-request" or
-    $thisaddress matches  "^owner-[^]+"
-    )
-
-The variable $local_part$ contains the local part of the mail address of
-the user whose filter file is being run -- it is normally your login id. The
-$domain$ variable contains the mail domain. As explained above, if aliases
-or rewriting are defined, or if prefixes or suffixes are in use, the tests for
-the current user are also done with alternative addresses.
-
-
-
-
-Testing delivery status
-~~~~~~~~~~~~~~~~~~~~~~~
-There are two conditions that are intended mainly for use in system filter
-files, but which are available in users' filter files as well. The condition
-^first_delivery^ is true if this is the first process that is attempting to
-deliver the message, and false otherwise. This indicator is not reset until the
-first delivery process successfully terminates; if there is a crash or a power
-failure (for example), the next delivery attempt is also a ``first delivery''.
-
-In a user filter file ^first_delivery^ will be false if there was previously an
-error in the filter, or if a delivery for the user failed owing to, for
-example, a quota error, or if forwarding to a remote address was deferred for
-some reason.
-
-The condition ^manually_thawed^ is true if the message was ``frozen'' for some
-reason, and was subsequently released by the system administrator. It is
-unlikely to be of use in users' filter files.
-
-
-[[SECTmbox]]
-Multiple personal mailboxes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The system administrator can configure Exim so that users can set up variants
-on their email addresses and handle them separately. Consult your system
-administrator or local documentation to see if this facility is enabled on your
-system, and if so, what the details are.
-
-The facility involves the use of a prefix or a suffix on an email address. For
-example, all mail addressed to 'lg303-'<'something'> would be the property of
-user 'lg303', who could determine how it was to be handled, depending on the
-value of <'something'>.
-
-There are two possible ways in which this can be set up. The first possibility
-is the use of multiple '.forward' files. In this case, mail to 'lg303-foo',
-for example, is handled by looking for a file called _.forward-foo_ in
-'lg303'{ap}s home directory. If such a file does not exist, delivery fails and the
-message is returned to its sender.
-
-The alternative approach is to pass all messages through a single _.forward_
-file, which must be a filter file so that it can distinguish between the
-different cases by referencing the variables $local_part_prefix$ or
-$local_part_suffix$, as in the final example in section <<SECTex>> below.
-
-It is possible to configure Exim to support both schemes at once. In this case,
-a specific _.forward-foo_ file is first sought; if it is not found, the basic
-_.forward_ file is used.
-
-The ^personal^ test (see section <<SECTpersonal>>) includes prefixes and
-suffixes in its checking.
-
-
-
-Ignoring delivery errors
-~~~~~~~~~~~~~~~~~~~~~~~~
-As was explained above, filtering just sets up addresses for delivery -- no
-deliveries are actually done while a filter file is active. If any of the
-generated addresses subsequently suffers a delivery failure, an error message
-is generated in the normal way. However, if a filter command that sets up a
-delivery is preceded by the word ^noerror^, errors for that delivery,
-'and any deliveries consequent on it' (that is, from alias, forwarding, or
-filter files it invokes) are ignored.
-
-
-
-[[SECTex]]
-Examples of Exim filter commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Simple forwarding:
-
-  # Exim filter
-  deliver baggins@rivendell.middle-earth.example
-
-Vacation handling using traditional means, assuming that the _.vacation.msg_
-and other files have been set up in your home directory:
-
-  # Exim filter
-  unseen pipe "/usr/ucb/vacation \"$local_part\""
-
-Vacation handling inside Exim, having first created a file called
-_.vacation.msg_ in your home directory:
-
-  # Exim filter
-  if personal then vacation endif
-
-File some messages by subject:
-
-  # Exim filter
-  if $header_subject: contains "empire" or
-     $header_subject: contains "foundation"
-  then
-     save $home/mail/f+e
-  endif
-
-Save all non-urgent messages by weekday:
-
-  # Exim filter
-  if $header_subject: does not contain "urgent" and
-     $tod_full matches "^(...),"
-  then
-    save $home/mail/$1
-  endif
-
-Throw away all mail from one site, except from postmaster:
-
-  # Exim filter
-  if $reply_address contains "@spam.site.example" and
-     $reply_address does not contain "postmaster@"
-  then
-     seen finish
-  endif
-
-Handle multiple personal mailboxes:
-
-  # Exim filter
-  if $local_part_suffix is "-foo"
-  then
-    save $home/mail/foo
-  elif $local_part_suffix is "-bar"
-  then
-    save $home/mail/bar
-  endif
-
-
diff --git a/doc/doc-docbook/filter.xfpt b/doc/doc-docbook/filter.xfpt
new file mode 100644 (file)
index 0000000..d0eda01
--- /dev/null
@@ -0,0 +1,1688 @@
+. $Cambridge: exim/doc/doc-docbook/filter.xfpt,v 1.1 2006/02/01 11:01:01 ph10 Exp $
+
+. /////////////////////////////////////////////////////////////////////////////
+. This is the primary source of the document that describes Exim's filtering
+. facilities. It is an xfpt document that is converted into DocBook XML for
+. subsequent conversion into printing and online formats. The markup used
+. herein is "standard" xfpt markup, with some extras. The markup is summarized
+. in a file called Markup.txt.
+. /////////////////////////////////////////////////////////////////////////////
+
+.include stdflags
+.include stdmacs
+.docbook
+.book
+
+. ===========================================================================
+. Additional xfpt markup used by this document, over and above the default
+. provided in the xfpt library.
+
+. Override the &$ flag to automatically insert a $ with the variable name
+
+.flag &$  $&   "<varname>$"  "</varname>"
+
+. A macro for the common 2-column tables
+
+.macro table2 100pt 300pt
+.itable none 0 0 2 $1 left $2 left
+.endmacro
+. ===========================================================================
+
+
+. This preliminary stuff creates a <bookinfo> entry in the XML. This is removed
+. when creating the PostScript/PDF output, because we do not want a full-blown
+. title page created for those versions. The stylesheet fudges up a title line
+. to replace the text "Table of contents". However, for the other forms of
+. output, the <bookinfo> element is retained and used.
+
+.literal xml
+<bookinfo>
+<title>Exim's interfaces to mail filtering</title>
+<titleabbrev>Exim filtering</titleabbrev>
+<date>30 January 2006</date>
+<author><firstname>Philip</firstname><surname>Hazel</surname></author>
+<authorinitials>PH</authorinitials>
+<revhistory><revision>
+  <revnumber>4.60-1</revnumber>
+  <date>30 January 2006</date>
+  <authorinitials>PH</authorinitials>
+</revision></revhistory>
+<copyright><year>2006</year><holder>University of Cambridge</holder></copyright>
+</bookinfo>
+.literal off
+
+
+.chapter "Forwarding and filtering in Exim"
+This document describes the user interfaces to Exim's in-built mail filtering
+facilities, and is copyright &copy; University of Cambridge 2006. It
+corresponds to Exim version 4.60.
+
+
+
+.section "Introduction"
+Most Unix mail transfer agents (programs that deliver mail) permit individual
+users to specify automatic forwarding of their mail, usually by placing a list
+of forwarding addresses in a file called &_.forward_& in their home
+directories. Exim extends this facility by allowing the forwarding instructions
+to be a set of rules rather than just a list of addresses, in effect providing
+&"&_.forward_& with conditions"&. Operating the set of rules is called
+&'filtering'&, and the file that contains them is called a &'filter file'&.
+
+Exim supports two different kinds of filter file. An &'Exim filter'& contains
+instructions in a format that is unique to Exim. A &'Sieve filter'& contains
+instructions in the Sieve format that is defined by RFC 3028. As this is a
+standard format, Sieve filter files may already be familiar to some users.
+Sieve files should also be portable between different environments. However,
+the Exim filtering facility contains more features (such as variable
+expansion), and better integration with the host environment (such as the use
+of external processes and pipes).
+
+The choice of which kind of filter to use can be left to the end-user, provided
+that the system administrator has configured Exim appropriately for both kinds
+of filter. However, if interoperability is important, Sieve is the only
+choice.
+
+The ability to use filtering or traditional forwarding has to be enabled by the
+system administrator, and some of the individual facilities can be separately
+enabled or disabled. A local document should be provided to describe exactly
+what has been enabled. In the absence of this, consult your system
+administrator.
+
+This document describes how to use a filter file and the format of its
+contents. It is intended for use by end-users. Both Sieve filters and Exim
+filters are covered. However, for Sieve filters, only issues that relate to the
+Exim implementation are discussed, since Sieve itself is described elsewhere.
+
+The contents of traditional &_.forward_& files are not described here. They
+normally contain just a list of addresses, file names, or pipe commands,
+separated by commas or newlines, but other types of item are also available.
+The full details can be found in the chapter on the &(redirect)& router in the
+Exim specification, which also describes how the system administrator can set
+up and control the use of filtering.
+
+
+
+.section "Filter operation"
+It is important to realize that, in Exim, no deliveries are actually made while
+a filter or traditional &_.forward_& file is being processed. Running a filter
+or processing a traditional &_.forward_& file sets up future delivery
+operations, but does not carry them out.
+
+The result of filter or &_.forward_& file processing is a list of destinations
+to which a message should be delivered. The deliveries themselves take place
+later, along with all other deliveries for the message. This means that it is
+not possible to test for successful deliveries while filtering. It also means
+that any duplicate addresses that are generated are dropped, because Exim never
+delivers the same message to the same address more than once.
+
+
+
+
+.section "Testing a new filter file" "SECTtesting"
+Filter files, especially the more complicated ones, should always be tested, as
+it is easy to make mistakes. Exim provides a facility for preliminary testing
+of a filter file before installing it. This tests the syntax of the file and
+its basic operation, and can also be used with traditional &_.forward_& files.
+
+Because a filter can do tests on the content of messages, a test message is
+required. Suppose you have a new filter file called &_myfilter_& and a test
+message in a file called &_test-message_&. Assuming that Exim is installed with
+the conventional path name &_/usr/sbin/sendmail_& (some operating systems use
+&_/usr/lib/sendmail_&), the following command can be used:
+.code
+/usr/sbin/sendmail -bf myfilter <test-message
+.endd
+The &%-bf%& option tells Exim that the following item on the command line is
+the name of a filter file that is to be tested. There is also a &%-bF%& option,
+which is similar, but which is used for testing system filter files, as opposed
+to user filter files, and which is therefore of use only to the system
+administrator.
+
+The test message is supplied on the standard input. If there are no
+message-dependent tests in the filter, an empty file (&_/dev/null_&) can be
+used. A supplied message must start with header lines or the &"From&~"& message
+separator line that is found in many multi-message folder files. Note that
+blank lines at the start terminate the header lines. A warning is given if no
+header lines are read.
+
+The result of running this command, provided no errors are detected in the
+filter file, is a list of the actions that Exim would try to take if presented
+with the message for real. For example, for an Exim filter, the output
+.code
+Deliver message to: gulliver@lilliput.fict.example
+Save message to: /home/lemuel/mail/archive
+.endd
+means that one copy of the message would be sent to
+&'gulliver@lilliput.fict.example'&, and another would be added to the file
+&_/home/lemuel/mail/archive_&, if all went well.
+
+The actions themselves are not attempted while testing a filter file in this
+way; there is no check, for example, that any forwarding addresses are valid.
+For an Exim filter, if you want to know why a particular action is being taken,
+add the &%-v%& option to the command. This causes Exim to output the results of
+any conditional tests and to indent its output according to the depth of
+nesting of &(if)& commands. Further additional output from a filter test can be
+generated by the &(testprint)& command, which is described below.
+
+When Exim is outputting a list of the actions it would take, if any text
+strings are included in the output, non-printing characters therein are
+converted to escape sequences. In particular, if any text string contains a
+newline character, this is shown as &"\n"& in the testing output.
+
+When testing a filter in this way, Exim makes up an &"envelope"& for the
+message. The recipient is by default the user running the command, and so is
+the sender, but the command can be run with the &%-f%& option to supply a
+different sender. For example,
+.code
+/usr/sbin/sendmail -bf myfilter \
+   -f islington@never.where <test-message
+.endd
+Alternatively, if the &%-f%& option is not used, but the first line of the
+supplied message is a &"From&~"& separator from a message folder file (not the
+same thing as a &'From:'& header line), the sender is taken from there. If
+&%-f%& is present, the contents of any &"From&~"& line are ignored.
+
+The &"return path"& is the same as the envelope sender, unless the message
+contains a &'Return-path:'& header, in which case it is taken from there. You
+need not worry about any of this unless you want to test out features of a
+filter file that rely on the sender address or the return path.
+
+It is possible to change the envelope recipient by specifying further options.
+The &%-bfd%& option changes the domain of the recipient address, while the
+&%-bfl%& option changes the &"local part"&, that is, the part before the @
+sign. An adviser could make use of these to test someone else's filter file.
+
+The &%-bfp%& and &%-bfs%& options specify the prefix or suffix for the local
+part. These are relevant only when support for multiple personal mailboxes is
+implemented; see the description in section &<<SECTmbox>>& below.
+
+
+.section "Installing a filter file"
+A filter file is normally installed under the name &_.forward_& in your home
+directory &-- it is distinguished from a conventional &_.forward_& file by its
+first line (described below). However, the file name is configurable, and some
+system administrators may choose to use some different name or location for
+filter files.
+
+
+.section "Testing an installed filter file"
+Testing a filter file before installation cannot find every potential problem;
+for example, it does not actually run commands to which messages are piped.
+Some &"live"& tests should therefore also be done once a filter is installed.
+
+If at all possible, test your filter file by sending messages from some other
+account. If you send a message to yourself from the filtered account, and
+delivery fails, the error message will be sent back to the same account, which
+may cause another delivery failure. It won't cause an infinite sequence of such
+messages, because delivery failure messages do not themselves generate further
+messages. However, it does mean that the failure won't be returned to you, and
+also that the postmaster will have to investigate the stuck message.
+
+If you have to test an Exim filter from the same account, a sensible precaution
+is to include the line
+.code
+if error_message then finish endif
+.endd
+as the first filter command, at least while testing. This causes filtering to
+be abandoned for a delivery failure message, and since no destinations are
+generated, the message goes on to be delivered to the original address. Unless
+there is a good reason for not doing so, it is recommended that the above test
+be left in all Exim filter files. (This does not apply to Sieve files.)
+
+
+
+.section "Details of filtering commands"
+The filtering commands for Sieve and Exim filters are completely different in
+syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
+chapter we describe how it is integrated into Exim. The subsequent chapter
+covers Exim filtering commands in detail.
+
+
+
+.chapter "Sieve filter files" "CHAPsievefilter"
+The code for Sieve filtering in Exim was contributed by Michael Haardt, and
+most of the content of this chapter is taken from the notes he provided. Since
+Sieve is an extensible language, it is important to understand &"Sieve"& in
+this context as &"the specific implementation of Sieve for Exim"&.
+
+This chapter does not contain a description of Sieve, since that can be found
+in RFC 3028, which should be read in conjunction with these notes.
+
+The Exim Sieve implementation offers the core as defined by RFC 3028,
+comparison tests, the &*copy*&, &*envelope*&, &*fileinto*&, and &*vacation*&
+extensions, but not the &*reject*& extension. Exim does not support message
+delivery notifications (MDNs), so adding it just to the Sieve filter (as
+required for &*reject*&) makes little sense.
+
+In order for Sieve to work properly in Exim, the system administrator needs to
+make some adjustments to the Exim configuration. These are described in the
+chapter on the &(redirect)& router in the full Exim specification.
+
+
+.section "Recognition of Sieve filters"
+A filter file is interpreted as a Sieve filter if its first line is
+.code
+# Sieve filter
+.endd
+This is what distinguishes it from a conventional &_.forward_& file or an Exim
+filter file.
+
+
+
+.section "Saving to specified folders"
+If the system administrator has set things up as suggested in the Exim
+specification, and you use &(keep)& or &(fileinto)& to save a mail into a
+folder, absolute files are stored where specified, relative files are stored
+relative to &$home$&, and &_inbox_& goes to the standard mailbox location.
+
+
+
+.section "Strings containing header names"
+RFC 3028 does not specify what happens if a string denoting a header field does
+not contain a valid header name, for example, it contains a colon. This
+implementation generates an error instead of ignoring the header field in order
+to ease script debugging, which fits in with the common picture of Sieve.
+
+
+
+.section "Exists test with empty list of headers"
+The &*exists*& test succeeds only if all the specified headers exist. RFC 3028
+does not explicitly specify what happens on an empty list of headers. This
+implementation evaluates that condition as true, interpreting the RFC in a
+strict sense.
+
+
+
+.section "Header test with invalid MIME encoding in header"
+Some MUAs process invalid base64 encoded data, generating junk. Others ignore
+junk after seeing an equal sign in base64 encoded data. RFC 2047 does not
+specify how to react in this case, other than stating that a client must not
+forbid to process a message for that reason. RFC 2045 specifies that invalid
+data should be ignored (apparently looking at end of line characters). It also
+specifies that invalid data may lead to rejecting messages containing them (and
+there it appears to talk about true encoding violations), which is a clear
+contradiction to ignoring them.
+
+RFC 3028 does not specify how to process incorrect MIME words. This
+implementation treats them literally, as it does if the word is correct but its
+character set cannot be converted to UTF-8.
+
+
+
+.section "Address test for multiple addresses per header"
+A header may contain multiple addresses. RFC 3028 does not explicitly specify
+how to deal with them, but since the address test checks if anything matches
+anything else, matching one address suffices to satisfy the condition. That
+makes it impossible to test if a header contains a certain set of addresses and
+no more, but it is more logical than letting the test fail if the header
+contains an additional address besides the one the test checks for.
+
+
+
+.section "Semantics of keep"
+The &(keep)& command is equivalent to
+.code
+fileinto "inbox";
+.endd
+It saves the message and resets the implicit keep flag. It does not set the
+implicit keep flag; there is no command to set it once it has been reset.
+
+
+
+.section "Semantics of fileinto"
+RFC 3028 does not specify whether &(fileinto)& should try to create a mail
+folder if it does not exist. This implementation allows the sysadmin to
+configure that aspect using the &(appendfile)& transport options
+&%create_directory%&, &%create_file%&, and &%file_must_exist%&. See the
+&(appendfile)& transport in the Exim specification for details.
+
+
+
+.section "Semantics of redirect"
+Sieve scripts are supposed to be interoperable between servers, so this
+implementation does not allow mail to be redirected to unqualified addresses,
+because the domain would depend on the system being used. On systems with
+virtual mail domains, the default domain is probably not what the user expects
+it to be.
+
+
+
+.section "String arguments"
+There has been confusion if the string arguments to &(require)& are to be
+matched case-sensitively or not. This implementation matches them with the
+match type &(:is)& (default, see section 2.7.1 of the RFC) and the comparator
+&(i;ascii-casemap)& (default, see section 2.7.3 of the RFC). The RFC defines
+the command defaults clearly, so any different implementations violate RFC
+3028. The same is valid for comparator names, also specified as strings.
+
+
+
+.section "Number units"
+There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
+The mistake is obvious, because RFC 3028 specifies G to denote 2^30
+(which is gibi, not tebi), and that is what this implementation uses as
+the scaling factor for the suffix G.
+
+
+
+.section "RFC compliance"
+Exim requires the first line of a Sieve filter to be
+.code
+# Sieve filter
+.endd
+Of course the RFC does not specify that line. Do not expect examples to work
+without adding it, though.
+
+RFC 3028 requires the use of CRLF to terminate a line. The rationale was that
+CRLF is universally used in network protocols to mark the end of the line. This
+implementation does not embed Sieve in a network protocol, but uses Sieve
+scripts as part of the Exim MTA. Since all parts of Exim use LF as the newline
+character, this implementation does, too, by default, though the system
+administrator may choose (at Exim compile time) to use CRLF instead.
+
+Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so this
+implementation repeats this violation to stay consistent with Exim. This is in
+preparation for UTF-8 data.
+
+Sieve scripts cannot contain NUL characters in strings, but mail headers could
+contain MIME encoded NUL characters, which could never be matched by Sieve
+scripts using exact comparisons. For that reason, this implementation extends
+the Sieve quoted string syntax with \0 to describe a NUL character, violating
+\0 being the same as 0 in RFC 3028. Even without using \0, the following tests
+are all true in this implementation. Implementations that use C-style strings
+will only evaluate the first test as true.
+.code
+Subject: =?iso-8859-1?q?abc=00def
+
+header :contains "Subject" ["abc"]
+header :contains "Subject" ["def"]
+header :matches "Subject" ["abc?def"]
+.endd
+Note that by considering Sieve to be an MUA, RFC 2047 can be interpreted in a
+way that NUL characters truncating strings is allowed for Sieve
+implementations, although not recommended. It is further allowed to use encoded
+NUL characters in headers, but that's not recommended either. The above example
+shows why.
+
+RFC 3028 states that if an implementation fails to convert a character set to
+UTF-8, two strings cannot be equal if one contains octets greater than 127.
+Assuming that all unknown character sets are one-byte character sets with the
+lower 128 octets being US-ASCII is not sound, so this implementation violates
+RFC 3028 and treats such MIME words literally. That way at least something
+could be matched.
+
+The folder specified by &(fileinto)& must not contain the character sequence
+&".."& to avoid security problems. RFC 3028 does not specify the syntax of
+folders apart from &(keep)& being equivalent to
+.code
+fileinto "INBOX";
+.endd
+This implementation uses &_inbox_& instead.
+
+Sieve script errors currently cause messages to be silently filed into
+&_inbox_&.  RFC 3028 requires that the user is notified of that condition.
+This may be implemented in the future by adding a header line to mails that
+are filed into &_inbox_& due to an error in the filter.
+
+
+
+.chapter "Exim filter files" "CHAPeximfilter"
+This chapter contains a full description of the contents of Exim filter files.
+
+
+.section "Format of Exim filter files"
+Apart from leading white space, the first text in an Exim filter file must be
+.code
+# Exim filter
+.endd
+This is what distinguishes it from a conventional &_.forward_& file or a Sieve
+filter file. If the file does not have this initial line (or the equivalent for
+a Sieve filter), it is treated as a conventional &_.forward_& file, both when
+delivering mail and when using the &%-bf%& testing mechanism. The white space
+in the line is optional, and any capitalization may be used. Further text on
+the same line is treated as a comment. For example, you could have
+.code
+#   Exim filter   <<== do not edit or remove this line!
+.endd
+The remainder of the file is a sequence of filtering commands, which consist of
+keywords and data values. For example, in the command
+.code
+deliver gulliver@lilliput.fict.example
+.endd
+the keyword is &`deliver`& and the data value is
+&`gulliver@lilliput.fict.example`&. White space or line breaks separate the
+components of a command, except in the case of conditions for the &(if)&
+command, where round brackets (parentheses) also act as separators. Complete
+commands are separated from each other by white space or line breaks; there are
+no special terminators. Thus, several commands may appear on one line, or one
+command may be spread over a number of lines.
+
+If the character # follows a separator anywhere in a command, everything from
+# up to the next newline is ignored. This provides a way of including comments
+in a filter file.
+
+
+.section "Data values in filter commands"
+There are two ways in which a data value can be input:
+
+.ilist
+If the text contains no white space, it can be typed verbatim. However, if it
+is part of a condition, it must also be free of round brackets (parentheses),
+as these are used for grouping in conditions.
+.next
+Otherwise, text must be enclosed in double quotation marks. In this case, the
+character \ (backslash) is treated as an &"escape character"& within the
+string, causing the following character or characters to be treated specially:
+.display
+&`\n`&   is replaced by a newline
+&`\r`&   is replaced by a carriage return
+&`\t`&   is replaced by a tab
+.endd
+.endlist
+
+Backslash followed by up to three octal digits is replaced by the character
+specified by those digits, and &`\x`& followed by up to two hexadecimal digits
+is treated similarly. Backslash followed by any other character is replaced by
+the second character, so that in particular, &`\"`& becomes &`"`& and &`\\`&
+becomes &`\`&. A data item enclosed in double quotes can be continued onto the
+next line by ending the first line with a backslash. Any leading white space at
+the start of the continuation line is ignored.
+
+In addition to the escape character processing that occurs when strings are
+enclosed in quotes, most data values are also subject to &'string expansion'&
+(as described in the next section), in which case the characters &`$`& and
+&`\`& are also significant. This means that if a single backslash is actually
+required in such a string, and the string is also quoted, &`\\\\`& has to be
+entered.
+
+The maximum permitted length of a data string, before expansion, is 1024
+characters.
+
+
+.section "String expansion" "SECTfilterstringexpansion"
+Most data values are expanded before use. Expansion consists of replacing
+substrings beginning with &`$`& with other text. The full expansion facilities
+available in Exim are extensive. If you want to know everything that Exim can
+do with strings, you should consult the chapter on string expansion in the Exim
+documentation.
+
+In filter files, by far the most common use of string expansion is the
+substitution of the contents of a variable. For example, the substring
+.code
+$reply_address
+.endd
+is replaced by the address to which replies to the message should be sent. If
+such a variable name is followed by a letter or digit or underscore, it must be
+enclosed in curly brackets (braces), for example,
+.code
+${reply_address}
+.endd
+If a &`$`& character is actually required in an expanded string, it must be
+escaped with a backslash, and because backslash is also an escape character in
+quoted input strings, it must be doubled in that case. The following two
+examples illustrate two different ways of testing for a &`$`& character in a
+message:
+.code
+if $message_body contains \$ then ...
+if $message_body contains "\\$" then ...
+.endd
+You can prevent part of a string from being expanded by enclosing it between
+two occurrences of &`\N`&. For example,
+.code
+if $message_body contains \N$$$$\N then ...
+.endd
+tests for a run of four dollar characters.
+
+
+.section "Some useful general variables"
+A complete list of the available variables is given in the Exim documentation.
+This shortened list contains the ones that are most likely to be useful in
+personal filter files:
+
+&$body_linecount$&: The number of lines in the body of the message.
+
+&$body_zerocount$&: The number of binary zero characters in the body of the
+message.
+
+&$home$&: In conventional configurations, this variable normally contains the
+user's home directory. The system administrator can, however, change this.
+
+&$local_part$&: The part of the email address that precedes the @ sign &--
+normally the user's login name. If support for multiple personal mailboxes is
+enabled (see section &<<SECTmbox>>& below) and a prefix or suffix for the local
+part was recognized, it is removed from the string in this variable.
+
+&$local_part_prefix$&: If support for multiple personal mailboxes is enabled
+(see section &<<SECTmbox>>& below), and a local part prefix was recognized,
+this variable contains the prefix. Otherwise it contains an empty string.
+
+&$local_part_suffix$&: If support for multiple personal mailboxes is enabled
+(see section &<<SECTmbox>>& below), and a local part suffix was recognized,
+this variable contains the suffix. Otherwise it contains an empty string.
+
+&$message_body$&: The initial portion of the body of the message. By default,
+up to 500 characters are read into this variable, but the system administrator
+can configure this to some other value. Newlines in the body are converted into
+single spaces.
+
+&$message_body_end$&: The final portion of the body of the message, formatted
+and limited in the same way as &$message_body$&.
+
+&$message_body_size$&: The size of the body of the message, in bytes.
+
+&$message_exim_id$&: The message's local identification string, which is unique
+for each message handled by a single host.
+
+&$message_headers$&: The header lines of the message, concatenated into a
+single string, with newline characters between them.
+
+&$message_size$&: The size of the entire message, in bytes.
+
+&$original_local_part$&: When an address that arrived with the message is
+being processed, this contains the same value as the variable &$local_part$&.
+However, if an address generated by an alias, forward, or filter file is being
+processed, this variable contains the local part of the original address.
+
+&$reply_address$&: The contents of the &'Reply-to:'& header, if the message
+has one; otherwise the contents of the &'From:'& header. It is the address to
+which normal replies to the message should be sent.
+
+&$return_path$&: The return path &-- that is, the sender field that will be
+transmitted as part of the message's envelope if the message is sent to another
+host. This is the address to which delivery errors are sent. In many cases,
+this variable has the same value as &$sender_address$&, but if, for example,
+an incoming message to a mailing list has been expanded, &$return_path$& may
+have been changed to contain the address of the list maintainer.
+
+&$sender_address$&: The sender address that was received in the envelope of
+the message. This is not necessarily the same as the contents of the &'From:'&
+or &'Sender:'& header lines. For delivery error messages (&"bounce messages"&)
+there is no sender address, and this variable is empty.
+
+&$tod_full$&: A full version of the time and date, for example: Wed, 18 Oct
+1995 09:51:40 +0100. The timezone is always given as a numerical offset from
+GMT.
+
+&$tod_log$&: The time and date in the format used for writing Exim's log files,
+without the timezone, for example: 1995-10-12 15:32:29.
+
+&$tod_zone$&: The local timezone offset, for example: +0100.
+
+
+
+.section "Header variables" "SECTheadervariables"
+There is a special set of expansion variables containing the header lines of
+the message being processed. These variables have names beginning with
+&$header_$& followed by the name of the header line, terminated by a colon.
+For example,
+.code
+$header_from:
+$header_subject:
+.endd
+The whole item, including the terminating colon, is replaced by the contents of
+the message header line. If there is more than one header line with the same
+name, their contents are concatenated. For header lines whose data consists of
+a list of addresses (for example, &'From:'& and &'To:'&), a comma and newline
+is inserted between each set of data. For all other header lines, just a
+newline is used.
+
+Leading and trailing white space is removed from header line data, and if there
+are any MIME &"words"& that are encoded as defined by RFC 2047 (because they
+contain non-ASCII characters), they are decoded and translated, if possible, to
+a local character set. Translation is attempted only on operating systems that
+have the &[iconv()]& function. This makes the header line look the same as it
+would when displayed by an MUA. The default character set is ISO-8859-1, but
+this can be changed by means of the &(headers)& command (see below).
+
+If you want to see the actual characters that make up a header line, you can
+specify &$rheader_$& instead of &$header_$&. This inserts the &"raw"&
+header line, unmodified.
+
+There is also an intermediate form, requested by &$bheader_$&, which removes
+leading and trailing space and decodes MIME &"words"&, but does not do any
+character translation. If an attempt to decode what looks superficially like a
+MIME &"word"& fails, the raw string is returned. If decoding produces a binary
+zero character, it is replaced by a question mark.
+
+The capitalization of the name following &$header_$& is not significant.
+Because any printing character except colon may appear in the name of a
+message's header (this is a requirement of RFC 2822, the document that
+describes the format of a mail message) curly brackets must &'not'& be used in
+this case, as they will be taken as part of the header name. Two shortcuts are
+allowed in naming header variables:
+
+.ilist
+The initiating &$header_$&, &$rheader_$&, or &$bheader_$& can be
+abbreviated to &$h_$&, &$rh_$&, or &$bh_$&, respectively.
+.next
+The terminating colon can be omitted if the next character is white space. The
+white space character is retained in the expanded string. However, this is not
+recommended, because it makes it easy to forget the colon when it really is
+needed.
+.endlist
+
+If the message does not contain a header of the given name, an empty string is
+substituted. Thus it is important to spell the names of headers correctly. Do
+not use &$header_Reply_to$& when you really mean &$header_Reply-to$&.
+
+
+.section "User variables"
+There are ten user variables with names &$n0$& &-- &$n9$& that can be
+incremented by the &(add)& command (see section &<<SECTadd>>&). These can be
+used for &"scoring"& messages in various ways. If Exim is configured to run a
+&"system filter"& on every message, the values left in these variables are
+copied into the variables &$sn0$& &-- &$sn9$& at the end of the system filter,
+thus making them available to users' filter files. How these values are used is
+entirely up to the individual installation.
+
+
+.section "Current directory"
+The contents of your filter file should not make any assumptions about the
+current directory. It is best to use absolute paths for file names; you can
+normally make use of the &$home$& variable to refer to your home directory. The
+&(save)& command automatically inserts &$home$& at the start of non-absolute
+paths.
+
+
+
+
+.section "Significant deliveries" "SECTsigdel"
+When in the course of delivery a message is processed by a filter file, what
+happens next, that is, after the filter file has been processed, depends on
+whether or not the filter sets up any &'significant deliveries'&. If at least
+one significant delivery is set up, the filter is considered to have handled
+the entire delivery arrangements for the current address, and no further
+processing of the address takes place. If, however, no significant deliveries
+are set up, Exim continues processing the current address as if there were no
+filter file, and typically sets up a delivery of a copy of the message into a
+local mailbox. In particular, this happens in the special case of a filter file
+containing only comments.
+
+The delivery commands &(deliver)&, &(save)&, and &(pipe)& are by default
+significant. However, if such a command is preceded by the word &"unseen"&, its
+delivery is not considered to be significant. In contrast, other commands such
+as &(mail)& and &(vacation)& do not set up significant deliveries unless
+preceded by the word &"seen"&. The following example commands set up
+significant deliveries:
+.code
+deliver jack@beanstalk.example
+pipe $home/bin/mymailscript
+seen mail subject "message discarded"
+seen finish
+.endd
+The following example commands do not set up significant deliveries:
+.code
+unseen deliver jack@beanstalk.example
+unseen pipe $home/bin/mymailscript
+mail subject "message discarded"
+finish
+.endd
+
+
+
+.section "Filter commands"
+The filter commands that are described in subsequent sections are listed
+below, with the section in which they are described in brackets:
+
+.table2
+.row &(add)&        "&~&~increment a user variable (section &<<SECTadd>>&)"
+.row &(deliver)&    "&~&~deliver to an email address (section &<<SECTdeliver>>&)"
+.row &(fail)&       "&~&~force delivery failure (sysadmin use) (section &<<SECTfail>>&)"
+.row &(finish)&     "&~&~end processing (section &<<SECTfinish>>&)"
+.row &(freeze)&     "&~&~freeze message (sysadmin use) (section &<<SECTfreeze>>&)"
+.row &(headers)&    "&~&~set the header character set (section &<<SECTheaders>>&)"
+.row &(if)&         "&~&~test condition(s) (section &<<SECTif>>&)"
+.row &(logfile)&    "&~&~define log file (section &<<SECTlog>>&)"
+.row &(logwrite)&   "&~&~write to log file (section &<<SECTlog>>&)"
+.row &(mail)&       "&~&~send a reply message (section &<<SECTmail>>&)"
+.row &(pipe)&       "&~&~pipe to a command (section &<<SECTpipe>>&)"
+.row &(save)&       "&~&~save to a file (section &<<SECTsave>>&)"
+.row &(testprint)&  "&~&~print while testing (section &<<SECTtestprint>>&)"
+.row &(vacation)&   "&~&~tailored form of &(mail)& (section &<<SECTmail>>&)"
+.endtable
+
+The &(headers)& command has additional parameters that can be used only in a
+system filter. The &(fail)& and &(freeze)& commands are available only when
+Exim's filtering facilities are being used as a system filter, and are
+therefore usable only by the system administrator and not by ordinary users.
+They are mentioned only briefly in this document; for more information, see the
+main Exim specification.
+
+
+
+.section "The add command" "SECTadd"
+.display
+&`     add `&<&'number'&>&` to `&<&'user variable'&>
+&`e.g. add 2 to n3`&
+.endd
+
+There are 10 user variables of this type, with names &$n0$& &-- &$n9$&. Their
+values can be obtained by the normal expansion syntax (for example &$n3$&) in
+other commands. At the start of filtering, these variables all contain zero.
+Both arguments of the &(add)& command are expanded before use, making it
+possible to add variables to each other. Subtraction can be obtained by adding
+negative numbers.
+
+
+
+.section "The deliver command" "SECTdeliver"
+.display
+&`     deliver`& <&'mail address'&>
+&`e.g. deliver "Dr Livingstone <David@somewhere.africa.example>"`&
+.endd
+
+This command provides a forwarding operation. The delivery that it sets up is
+significant unless the command is preceded by &"unseen"& (see section
+&<<SECTsigdel>>&). The message is sent on to the given address, exactly as
+happens if the address had appeared in a traditional &_.forward_& file. If you
+want to deliver the message to a number of different addresses, you can use
+more than one &(deliver)& command (each one may have only one address).
+However, duplicate addresses are discarded.
+
+To deliver a copy of the message to your normal mailbox, your login name can be
+given as the address. Once an address has been processed by the filtering
+mechanism, an identical generated address will not be so processed again, so
+doing this does not cause a loop.
+
+However, if you have a mail alias, you should &'not'& refer to it here. For
+example, if the mail address &'L.Gulliver'& is aliased to &'lg303'& then all
+references in Gulliver's &_.forward_& file should be to &'lg303'&. A reference
+to the alias will not work for messages that are addressed to that alias,
+since, like &_.forward_& file processing, aliasing is performed only once on an
+address, in order to avoid looping.
+
+Following the new address, an optional second address, preceded by
+&"errors_to"& may appear. This changes the address to which delivery errors on
+the forwarded message will be sent. Instead of going to the message's original
+sender, they go to this new address. For ordinary users, the only value that is
+permitted for this address is the user whose filter file is being processed.
+For example, the user &'lg303'& whose mailbox is in the domain
+&'lilliput.example'& could have a filter file that contains
+.code
+deliver jon@elsewhere.example errors_to lg303@lilliput.example
+.endd
+Clearly, using this feature makes sense only in situations where not all
+messages are being forwarded. In particular, bounce messages must not be
+forwarded in this way, as this is likely to create a mail loop if something
+goes wrong.
+
+
+
+.section "The save command" "SECTsave"
+.display
+&`     save `&<&'file name'&>
+&`e.g. save $home/mail/bookfolder`&
+.endd
+
+This command specifies that a copy of the message is to be appended to the
+given file (that is, the file is to be used as a mail folder). The delivery
+that &(save)& sets up is significant unless the command is preceded by
+&"unseen"& (see section &<<SECTsigdel>>&).
+
+More than one &(save)& command may be obeyed; each one causes a copy of the
+message to be written to its argument file, provided they are different
+(duplicate &(save)& commands are ignored).
+
+If the file name does not start with a / character, the contents of the
+&$home$& variable are prepended, unless it is empty. In conventional
+configurations, this variable is normally set in a user filter to the user's
+home directory, but the system administrator may set it to some other path. In
+some configurations, &$home$& may be unset, in which case a non-absolute path
+name may be generated. Such configurations convert this to an absolute path
+when the delivery takes place. In a system filter, &$home$& is never set.
+
+The user must of course have permission to write to the file, and the writing
+of the file takes place in a process that is running as the user, under the
+user's primary group. Any secondary groups to which the user may belong are not
+normally taken into account, though the system administrator can configure Exim
+to set them up. In addition, the ability to use this command at all is
+controlled by the system administrator &-- it may be forbidden on some systems.
+
+An optional mode value may be given after the file name. The value for the mode
+is interpreted as an octal number, even if it does not begin with a zero. For
+example:
+.code
+save /some/folder 640
+.endd
+This makes it possible for users to override the system-wide mode setting for
+file deliveries, which is normally 600. If an existing file does not have the
+correct mode, it is changed.
+
+An alternative form of delivery may be enabled on your system, in which each
+message is delivered into a new file in a given directory. If this is the case,
+this functionality can be requested by giving the directory name terminated by
+a slash after the &(save)& command, for example
+.code
+save separated/messages/
+.endd
+There are several different formats for such deliveries; check with your system
+administrator or local documentation to find out which (if any) are available
+on your system. If this functionality is not enabled, the use of a path name
+ending in a slash causes an error.
+
+
+
+.section "The pipe command" "SECTpipe"
+.display
+&`     pipe `&<&'command'&>
+&`e.g. pipe "$home/bin/countmail $sender_address"`&
+.endd
+
+This command specifies that the message is to be delivered to the specified
+command using a pipe. The delivery that it sets up is significant unless the
+command is preceded by &"unseen"& (see section &<<SECTsigdel>>&). Remember,
+however, that no deliveries are done while the filter is being processed. All
+deliveries happen later on. Therefore, the result of running the pipe is not
+available to the filter.
+
+When the deliveries are done, a separate process is run, and a copy of the
+message is passed on its standard input. The process runs as the user, under
+the user's primary group. Any secondary groups to which the user may belong are
+not normally taken into account, though the system administrator can configure
+Exim to set them up. More than one &(pipe)& command may appear; each one causes
+a copy of the message to be written to its argument pipe, provided they are
+different (duplicate &(pipe)& commands are ignored).
+
+When the time comes to transport the message, the command supplied to &(pipe)&
+is split up by Exim into a command name and a number of arguments. These are
+delimited by white space except for arguments enclosed in double quotes, in
+which case backslash is interpreted as an escape, or in single quotes, in which
+case no escaping is recognized. Note that as the whole command is normally
+supplied in double quotes, a second level of quoting is required for internal
+double quotes. For example:
+.code
+pipe "$home/myscript \"size is $message_size\""
+.endd
+String expansion is performed on the separate components after the line has
+been split up, and the command is then run directly by Exim; it is not run
+under a shell. Therefore, substitution cannot change the number of arguments,
+nor can quotes, backslashes or other shell metacharacters in variables cause
+confusion.
+
+Documentation for some programs that are normally run via this kind of pipe
+often suggest that the command should start with
+.code
+IFS=" "
+.endd
+This is a shell command, and should &'not'& be present in Exim filter files,
+since it does not normally run the command under a shell.
+
+However, there is an option that the administrator can set to cause a shell to
+be used. In this case, the entire command is expanded as a single string and
+passed to the shell for interpretation. It is recommended that this be avoided
+if at all possible, since it can lead to problems when inserted variables
+contain shell metacharacters.
+
+The default PATH set up for the command is determined by the system
+administrator, usually containing at least &_/bin_& and &_/usr/bin_& so that
+common commands are available without having to specify an absolute file name.
+However, it is possible for the system administrator to restrict the pipe
+facility so that the command name must not contain any / characters, and must
+be found in one of the directories in the configured PATH. It is also possible
+for the system administrator to lock out the use of the &(pipe)& command
+altogether.
+
+When the command is run, a number of environment variables are set up. The
+complete list for pipe deliveries may be found in the Exim reference manual.
+Those that may be useful for pipe deliveries from user filter files are:
+
+.display
+&`DOMAIN            `&   the domain of the address
+&`HOME              `&   your home directory
+&`LOCAL_PART        `&   see below
+&`LOCAL_PART_PREFIX `&   see below
+&`LOCAL_PART_SUFFIX `&   see below
+&`LOGNAME           `&   your login name
+&`MESSAGE_ID        `&   the unique id of the message
+&`PATH              `&   the command search path
+&`RECIPIENT         `&   the complete recipient address
+&`SENDER            `&   the sender of the message
+&`SHELL             `&   &`/bin/sh`&
+&`USER              `&   see below
+.endd
+
+LOCAL_PART, LOGNAME, and USER are all set to the same value, namely, your login
+id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may be set if Exim is configured to
+recognize prefixes or suffixes in the local parts of addresses. For example, a
+message addressed to &'pat-suf2@domain.example'& may cause the filter for user
+&'pat'& to be run. If this sets up a pipe delivery, LOCAL_PART_SUFFIX is
+&`-suf2`& when the pipe command runs. The system administrator has to configure
+Exim specially for this feature to be available.
+
+If you run a command that is a shell script, be very careful in your use of
+data from the incoming message in the commands in your script. RFC 2822 is very
+generous in the characters that are permitted to appear in mail addresses, and
+in particular, an address may begin with a vertical bar or a slash. For this
+reason you should always use quotes round any arguments that involve data from
+the message, like this:
+.code
+/some/command '$SENDER'
+.endd
+so that inserted shell meta-characters do not cause unwanted effects.
+
+Remember that, as was explained earlier, the pipe command is not run at the
+time the filter file is interpreted. The filter just defines what deliveries
+are required for one particular addressee of a message. The deliveries
+themselves happen later, once Exim has decided everything that needs to be done
+for the message.
+
+A consequence of this is that you cannot inspect the return code from the pipe
+command from within the filter. Nevertheless, the code returned by the command
+is important, because Exim uses it to decide whether the delivery has succeeded
+or failed.
+
+The command should return a zero completion code if all has gone well. Most
+non-zero codes are treated by Exim as indicating a failure of the pipe. This is
+treated as a delivery failure, causing the message to be returned to its
+sender. However, there are some completion codes that are treated as temporary
+errors. The message remains on Exim's spool disk, and the delivery is tried
+again later, though it will ultimately time out if the delivery failures go on
+too long. The completion codes to which this applies can be specified by the
+system administrator; the default values are 73 and 75.
+
+The pipe command should not normally write anything to its standard output or
+standard error file descriptors. If it does, whatever is written is normally
+returned to the sender of the message as a delivery error, though this action
+can be varied by the system administrator.
+
+
+
+.section "Mail commands" "SECTmail"
+There are two commands that cause the creation of a new mail message, neither
+of which count as a significant delivery unless the command is preceded by the
+word &"seen"& (see section &<<SECTsigdel>>&). This is a powerful facility, but
+it should be used with care, because of the danger of creating infinite
+sequences of messages. The system administrator can forbid the use of these
+commands altogether.
+
+To help prevent runaway message sequences, these commands have no effect when
+the incoming message is a bounce (delivery error) message, and messages sent by
+this means are treated as if they were reporting delivery errors. Thus, they
+should never themselves cause a bounce message to be returned. The basic
+mail-sending command is
+.display
+&`mail [to `&<&'address-list'&>&`]`&
+&`     [cc `&<&'address-list'&>&`]`&
+&`     [bcc `&<&'address-list'&>&`]`&
+&`     [from `&<&'address'&>&`]`&
+&`     [reply_to `&<&'address'&>&`]`&
+&`     [subject `&<&'text'&>&`]`&
+&`     [extra_headers `&<&'text'&>&`]`&
+&`     [text `&<&'text'&>&`]`&
+&`     [[expand] file `&<&'filename'&>&`]`&
+&`     [return message]`&
+&`     [log `&<&'log file name'&>&`]`&
+&`     [once `&<&'note file name'&>&`]`&
+&`     [once_repeat `&<&'time interval'&>&`]`&
+
+&`e.g. mail text "Your message about $h_subject: has been received"`&
+.endd
+Each <&'address-list'&> can contain a number of addresses, separated by commas,
+in the format of a &'To:'& or &'Cc:'& header line. In fact, the text you supply
+here is copied exactly into the appropriate header line. It may contain
+additional information as well as email addresses. For example:
+.code
+mail to "Julius Caesar <jc@rome.example>, \
+         <ma@rome.example> (Mark A.)"
+.endd
+Similarly, the texts supplied for &%from%& and &%reply_to%& are copied into
+their respective header lines.
+
+As a convenience for use in one common case, there is also a command called
+&(vacation)&. It behaves in the same way as &(mail)&, except that the defaults
+for the &%subject%&, &%file%&, &%log%&, &%once%&, and &%once_repeat%& options
+are
+.code
+subject "On vacation"
+expand file .vacation.msg
+log  .vacation.log
+once .vacation
+once_repeat 7d
+.endd
+respectively. These are the same file names and repeat period used by the
+traditional Unix &(vacation)& command. The defaults can be overridden by
+explicit settings, but if a file name is given its contents are expanded only
+if explicitly requested.
+
+&*Warning*&: The &(vacation)& command should always be used conditionally,
+subject to at least the &(personal)& condition (see section &<<SECTpersonal>>&
+below) so as not to send automatic replies to non-personal messages from
+mailing lists or elsewhere. Sending an automatic response to a mailing list or
+a mailing list manager is an Internet Sin.
+
+For both commands, the key/value argument pairs can appear in any order. At
+least one of &%text%& or &%file%& must appear (except with &(vacation)&, where
+there is a default for &%file%&); if both are present, the text string appears
+first in the message. If &%expand%& precedes &%file%&, each line of the file is
+subject to string expansion before it is included in the message.
+
+Several lines of text can be supplied to &%text%& by including the escape
+sequence &"\n"& in the string wherever a newline is required. If the command is
+output during filter file testing, newlines in the text are shown as &"\n"&.
+
+Note that the keyword for creating a &'Reply-To:'& header is &%reply_to%&,
+because Exim keywords may contain underscores, but not hyphens. If the &%from%&
+keyword is present and the given address does not match the user who owns the
+forward file, Exim normally adds a &'Sender:'& header to the message, though it
+can be configured not to do this.
+
+The &%extra_headers%& keyword allows you to add custom header lines to the
+message. The text supplied must be one or more syntactically valid RFC 2822
+header lines. You can use &"\n"& within quoted text to specify newlines between
+headers, and also to define continued header lines. For example:
+.code
+extra_headers "h1: first\nh2: second\n continued\nh3: third"
+.endd
+No newline should appear at the end of the final header line.
+
+If no &%to%& argument appears, the message is sent to the address in the
+&$reply_address$& variable (see section &<<SECTfilterstringexpansion>>& above).
+An &'In-Reply-To:'& header is automatically included in the created message,
+giving a reference to the message identification of the incoming message.
+
+If &%return message%& is specified, the incoming message that caused the filter
+file to be run is added to the end of the message, subject to a maximum size
+limitation.
+
+If a log file is specified, a line is added to it for each message sent.
+
+If a &%once%& file is specified, it is used to hold a database for remembering
+who has received a message, and no more than one message is ever sent to any
+particular address, unless &%once_repeat%& is set. This specifies a time
+interval after which another copy of the message is sent. The interval is
+specified as a sequence of numbers, each followed by the initial letter of one
+of &"seconds"&, &"minutes"&, &"hours"&, &"days"&, or &"weeks"&. For example,
+.code
+once_repeat 5d4h
+.endd
+causes a new message to be sent if at least 5 days and 4 hours have elapsed
+since the last one was sent. There must be no white space in a time interval.
+
+Commonly, the file name specified for &%once%& is used as the base name for
+direct-access (DBM) file operations. There are a number of different DBM
+libraries in existence. Some operating systems provide one as a default, but
+even in this case a different one may have been used when building Exim. With
+some DBM libraries, specifying &%once%& results in two files being created,
+with the suffixes &_.dir_& and &_.pag_& being added to the given name. With
+some others a single file with the suffix &_.db_& is used, or the name is used
+unchanged.
+
+Using a DBM file for implementing the &%once%& feature means that the file
+grows as large as necessary. This is not usually a problem, but some system
+administrators want to put a limit on it. The facility can be configured not to
+use a DBM file, but instead, to use a regular file with a maximum size. The
+data in such a file is searched sequentially, and if the file fills up, the
+oldest entry is deleted to make way for a new one. This means that some
+correspondents may receive a second copy of the message after an unpredictable
+interval. Consult your local information to see if your system is configured
+this way.
+
+More than one &(mail)& or &(vacation)& command may be obeyed in a single filter
+run; they are all honoured, even when they are to the same recipient.
+
+
+
+.section "Logging commands" "SECTlog"
+A log can be kept of actions taken by a filter file. This facility is normally
+available in conventional configurations, but there are some situations where
+it might not be. Also, the system administrator may choose to disable it. Check
+your local information if in doubt.
+
+Logging takes place while the filter file is being interpreted. It does not
+queue up for later like the delivery commands. The reason for this is so that a
+log file need be opened only once for several write operations. There are two
+commands, neither of which constitutes a significant delivery. The first
+defines a file to which logging output is subsequently written:
+.display
+&`     logfile `&<&'file name'&>
+&`e.g. logfile $home/filter.log`&
+.endd
+The file name must be fully qualified. You can use &$home$&, as in this
+example, to refer to your home directory. The file name may optionally be
+followed by a mode for the file, which is used if the file has to be created.
+For example,
+.code
+logfile $home/filter.log 0644
+.endd
+The number is interpreted as octal, even if it does not begin with a zero.
+The default for the mode is 600. It is suggested that the &(logfile)& command
+normally appear as the first command in a filter file. Once a log file has
+been obeyed, the &(logwrite)& command can be used to write to it:
+.display
+&`     logwrite "`&<&'some text string'&>&`"`&
+&`e.g. logwrite "$tod_log $message_id processed"`&
+.endd
+It is possible to have more than one &(logfile)& command, to specify writing to
+different log files in different circumstances. Writing takes place at the end
+of the file, and a newline character is added to the end of each string if
+there isn't one already there. Newlines can be put in the middle of the string
+by using the &"\n"& escape sequence. Lines from simultaneous deliveries may get
+interleaved in the file, as there is no interlocking, so you should plan your
+logging with this in mind. However, data should not get lost.
+
+
+
+.section "The finish command" "SECTfinish"
+The command &(finish)&, which has no arguments, causes Exim to stop
+interpreting the filter file. This is not a significant action unless preceded
+by &"seen"&. A filter file containing only &"seen finish"& is a black hole.
+
+
+.section "The testprint command" "SECTtestprint"
+It is sometimes helpful to be able to print out the values of variables when
+testing filter files. The command
+.display
+&`     testprint `&<&'text'&>
+&`e.g. testprint "home=$home reply_address=$reply_address"`&
+.endd
+does nothing when mail is being delivered. However, when the filtering code is
+being tested by means of the &%-bf%& option (see section &<<SECTtesting>>&
+above), the value of the string is written to the standard output.
+
+
+.section "The fail command" "SECTfail"
+When Exim's filtering facilities are being used as a system filter, the
+&(fail)& command is available, to force delivery failure. Because this command
+is normally usable only by the system administrator, and not enabled for use by
+ordinary users, it is described in more detail in the main Exim specification
+rather than in this document.
+
+
+.section "The freeze command" "SECTfreeze"
+When Exim's filtering facilities are being used as a system filter, the
+&(freeze)& command is available, to freeze a message on the queue. Because this
+command is normally usable only by the system administrator, and not enabled
+for use by ordinary users, it is described in more detail in the main Exim
+specification rather than in this document.
+
+
+
+.section "The headers command" "SECTheaders"
+The &(headers)& command can be used to change the target character set that is
+used when translating the contents of encoded header lines for insertion by the
+&$header_$& mechanism (see section &<<SECTheadervariables>>& above). The
+default can be set in the Exim configuration; if not specified, ISO-8859-1 is
+used. The only currently supported format for the &(headers)& command in user
+filters is as in this example:
+.code
+headers charset "UTF-8"
+.endd
+That is, &(headers)& is followed by the word &"charset"& and then the name of a
+character set. This particular example would be useful if you wanted to compare
+the contents of a header to a UTF-8 string.
+
+In system filter files, the &(headers)& command can be used to add or remove
+header lines from the message. These features are described in the main Exim
+specification.
+
+
+
+.section "Obeying commands conditionally" "SECTif"
+Most of the power of filtering comes from the ability to test conditions and
+obey different commands depending on the outcome. The &(if)& command is used to
+specify conditional execution, and its general form is
+.display
+&`if    `&<&'condition'&>
+&`then  `&<&'commands'&>
+&`elif  `&<&'condition'&>
+&`then  `&<&'commands'&>
+&`else  `&<&'commands'&>
+&`endif`&
+.endd
+There may be any number of &(elif)& and &(then)& sections (including none) and
+the &(else)& section is also optional. Any number of commands, including nested
+&(if)& commands, may appear in any of the <&'commands'&> sections.
+
+Conditions can be combined by using the words &(and)& and &(or)&, and round
+brackets (parentheses) can be used to specify how several conditions are to
+combine. Without brackets, &(and)& is more binding than &(or)&. For example:
+.code
+if
+$h_subject: contains "Make money" or
+$h_precedence: is "junk" or
+($h_sender: matches ^\\d{8}@ and not personal) or
+$message_body contains "this is not spam"
+then
+seen finish
+endif
+.endd
+A condition can be preceded by &(not)& to negate it, and there are also some
+negative forms of condition that are more English-like.
+
+
+
+.section "String testing conditions"
+There are a number of conditions that operate on text strings, using the words
+&"begins"&, &"ends"&, &"is"&, &"contains"& and &"matches"&. If you want to
+apply the same test to more than one header line, you can easily concatenate
+them into a single string for testing, as in this example:
+.code
+if "$h_to:, $h_cc:" contains me@domain.example then ...
+.endd
+If a string-testing condition name is written in lower case, the testing
+of letters is done without regard to case; if it is written in upper case
+(for example, &"CONTAINS"&), the case of letters is taken into account.
+
+.display
+&`     `&<&'text1'&>&` begins `&<&'text2'&>
+&`     `&<&'text1'&>&` does not begin `&<&'text2'&>
+&`e.g. $header_from: begins "Friend@"`&
+.endd
+
+A &"begins"& test checks for the presence of the second string at the start of
+the first, both strings having been expanded.
+
+.display
+&`     `&<&'text1'&>&` ends `&<&'text2'&>
+&`     `&<&'text1'&>&` does not end `&<&'text2'&>
+&`e.g. $header_from: ends "public.com.example"`&
+.endd
+
+An &"ends"& test checks for the presence of the second string at the end of
+the first, both strings having been expanded.
+
+.display
+&`     `&<&'text1'&>&` is `&<&'text2'&>
+&`     `&<&'text1'&>&` is not `&<&'text2'&>
+&`e.g. $local_part_suffix is "-foo"`&
+.endd
+
+An &"is"& test does an exact match between the strings, having first expanded
+both strings.
+
+.display
+&`     `&<&'text1'&>&` contains `&<&'text2'&>
+&`     `&<&'text1'&>&` does not contain `&<&'text2'&>
+&`e.g. $header_subject: contains "evolution"`&
+.endd
+
+A &"contains"& test does a partial string match, having expanded both strings.
+
+.display
+&`     `&<&'text1'&>&` matches `&<&'text2'&>
+&`     `&<&'text1'&>&` does not match `&<&'text2'&>
+&`e.g. $sender_address matches "(bill|john)@"`&
+.endd
+
+For a &"matches"& test, after expansion of both strings, the second one is
+interpreted as a regular expression. Exim uses the PCRE regular expression
+library, which provides regular expressions that are compatible with Perl.
+
+The match succeeds if the regular expression matches any part of the first
+string. If you want a regular expression to match only at the start or end of
+the subject string, you must encode that requirement explicitly, using the
+&`^`& or &`$`& metacharacters. The above example, which is not so constrained,
+matches all these addresses:
+.code
+bill@test.example
+john@some.example
+spoonbill@example.com
+littlejohn@example.com
+.endd
+To match only the first two, you could use this:
+.code
+if $sender_address matches "^(bill|john)@" then ...
+.endd
+Care must be taken if you need a backslash in a regular expression, because
+backslashes are interpreted as escape characters both by the string expansion
+code and by Exim's normal processing of strings in quotes. For example, if you
+want to test the sender address for a domain ending in &'.com'& the regular
+expression is
+.code
+\.com$
+.endd
+The backslash and dollar sign in that expression have to be escaped when used
+in a filter command, as otherwise they would be interpreted by the expansion
+code. Thus, what you actually write is
+.code
+if $sender_address matches \\.com\$
+.endd
+An alternative way of handling this is to make use of the &`\N`& expansion
+flag for suppressing expansion:
+.code
+if $sender_address matches \N\.com$\N
+.endd
+Everything between the two occurrences of &`\N`& is copied without change by
+the string expander (and in fact you do not need the final one, because it is
+at the end of the string). If the regular expression is given in quotes
+(mandatory only if it contains white space) you have to write either
+.code
+if $sender_address matches "\\\\.com\\$"
+.endd
+or
+.code
+if $sender_address matches "\\N\\.com$\\N"
+.endd
+
+If the regular expression contains bracketed sub-expressions, numeric
+variable substitutions such as &$1$& can be used in the subsequent actions
+after a successful match. If the match fails, the values of the numeric
+variables remain unchanged. Previous values are not restored after &(endif)&.
+In other words, only one set of values is ever available. If the condition
+contains several sub-conditions connected by &(and)& or &(or)&, it is the
+strings extracted from the last successful match that are available in
+subsequent actions. Numeric variables from any one sub-condition are also
+available for use in subsequent sub-conditions, because string expansion of a
+condition occurs just before it is tested.
+
+
+.section "Numeric testing conditions"
+The following conditions are available for performing numerical tests:
+
+.display
+&`     `&<&'number1'&>&` is above `&<&'number2'&>
+&`     `&<&'number1'&>&` is not above `&<&'number2'&>
+&`     `&<&'number1'&>&` is below `&<&'number2'&>
+&`     `&<&'number1'&>&` is not below `&<&'number2'&>
+&`e.g. $message_size is not above 10k`&
+.endd
+
+The <&'number'&> arguments must expand to strings of digits, optionally
+followed by one of the letters K or M (upper case or lower case) which cause
+multiplication by 1024 and 1024x1024 respectively.
+
+
+.section "Testing for significant deliveries"
+You can use the &(delivered)& condition to test whether or not any previously
+obeyed filter commands have set up a significant delivery. For example:
+.code
+if not delivered then save mail/anomalous endif
+.endd
+&"Delivered"& is perhaps a poor choice of name for this condition, because the
+message has not actually been delivered; rather, a delivery has been set up for
+later processing.
+
+
+.section "Testing for error messages"
+The condition &(error_message)& is true if the incoming message is a bounce
+(mail delivery error) message. Putting the command
+.code
+if error_message then finish endif
+.endd
+at the head of your filter file is a useful insurance against things going
+wrong in such a way that you cannot receive delivery error reports. &*Note*&:
+&(error_message)& is a condition, not an expansion variable, and therefore is
+not preceded by &`$`&.
+
+
+.section "Testing a list of addresses"
+There is a facility for looping through a list of addresses and applying a
+condition to each of them. It takes the form
+.display
+&`foranyaddress `&<&'string'&>&` (`&<&'condition'&>&`)`&
+.endd
+where <&'string'&> is interpreted as a list of RFC 2822 addresses, as in a
+typical header line, and <&'condition'&> is any valid filter condition or
+combination of conditions. The &"group"& syntax that is defined for certain
+header lines that contain addresses is supported.
+
+The parentheses surrounding the condition are mandatory, to delimit it from
+possible further sub-conditions of the enclosing &(if)& command. Within the
+condition, the expansion variable &$thisaddress$& is set to the non-comment
+portion of each of the addresses in the string in turn. For example, if the
+string is
+.code
+B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister)
+.endd
+then &$thisaddress$& would take on the values &`bart@sfld.example`& and
+&`lisa@sfld.example`& in turn.
+
+If there are no valid addresses in the list, the whole condition is false. If
+the internal condition is true for any one address, the overall condition is
+true and the loop ends. If the internal condition is false for all addresses in
+the list, the overall condition is false. This example tests for the presence
+of an eight-digit local part in any address in a &'To:'& header:
+.code
+if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ...
+.endd
+When the overall condition is true, the value of &$thisaddress$& in the
+commands that follow &(then)& is the last value it took on inside the loop. At
+the end of the &(if)& command, the value of &$thisaddress$& is reset to what it
+was before. It is best to avoid the use of multiple occurrences of
+&(foranyaddress)&, nested or otherwise, in a single &(if)& command, if the
+value of &$thisaddress$& is to be used afterwards, because it isn't always
+clear what the value will be. Nested &(if)& commands should be used instead.
+
+Header lines can be joined together if a check is to be applied to more than
+one of them. For example:
+.code
+if foranyaddress $h_to:,$h_cc: ....
+.endd
+This scans through the addresses in both the &'To:'& and the &'Cc:'& headers.
+
+
+.section "Testing for personal mail" "SECTpersonal"
+A common requirement is to distinguish between incoming personal mail and mail
+from a mailing list, or from a robot or other automatic process (for example, a
+bounce message). In particular, this test is normally required for &"vacation
+messages"&.
+
+The &(personal)& condition checks that the message is not a bounce message and
+that the current user's email address appears in the &'To:'& header. It also
+checks that the sender is not the current user or one of a number of common
+daemons, and that there are no header lines starting &'List-'& in the message.
+Finally, it checks the content of the &'Precedence:'& header line, if there is
+one.
+
+You should always use the &(personal)& condition when generating automatic
+responses. This example shows the use of &(personal)& in a filter file that is
+sending out vacation messages:
+.code
+if personal then
+mail to $reply_address
+subject "I am on holiday"
+file $home/vacation/message
+once $home/vacation/once
+once_repeat 10d
+endif
+.endd
+It is tempting, when writing commands like the above, to quote the original
+subject in the reply. For example:
+.code
+subject "Re: $h_subject:"
+.endd
+There is a danger in doing this, however. It may allow a third party to
+subscribe you to an opt-in mailing list, provided that the list accepts bounce
+messages as subscription confirmations. (Messages sent from filters are always
+sent as bounce messages.) Well-managed lists require a non-bounce message to
+confirm a subscription, so the danger is relatively small.
+
+If prefixes or suffixes are in use for local parts &-- something which depends
+on the configuration of Exim (see section &<<SECTmbox>>& below) &-- the tests
+for the current user are done with the full address (including the prefix and
+suffix, if any) as well as with the prefix and suffix removed. If the system is
+configured to rewrite local parts of mail addresses, for example, to rewrite
+&`dag46`& as &`Dirk.Gently`&, the rewritten form of the address is also used in
+the tests.
+
+
+
+.section "Alias addresses for the personal condition"
+It is quite common for people who have mail accounts on a number of different
+systems to forward all their mail to one system, and in this case a check for
+personal mail should test all their various mail addresses. To allow for this,
+the &(personal)& condition keyword can be followed by
+.display
+&`alias `&<&'address'&>
+.endd
+any number of times, for example:
+.code
+if personal alias smith@else.where.example
+            alias jones@other.place.example
+then ...
+.endd
+The alias addresses are treated as alternatives to the current user's email
+address when testing the contents of header lines.
+
+
+.section "Details of the personal condition"
+The basic &(personal)& test is roughly equivalent to the following:
+.code
+not error_message and
+$message_headers does not contain "\nList-Id:" and
+$message_headers does not contain "\nList-Help:" and
+$message_headers does not contain "\nList-Subscribe:" and
+$message_headers does not contain "\nList-Unsubscribe:" and
+$message_headers does not contain "\nList-Post:" and
+$message_headers does not contain "\nList-Owner:" and
+$message_headers does not contain "\nList-Archive:" and
+(
+"${if def h_auto-submitted:{present}{absent}}" is "absent" or
+$header_auto-submitted: is "no"
+) and
+$header_precedence: does not contain "bulk" and
+$header_precedence: does not contain "list" and
+$header_precedence: does not contain "junk" and
+foranyaddress $header_to:
+( $thisaddress contains "$local_part$domain" ) and
+not foranyaddress $header_from:
+(
+$thisaddress contains "$local_partdomain" or
+$thisaddress contains "server" or
+$thisaddress contains "daemon" or
+$thisaddress contains "root" or
+$thisaddress contains "listserv" or
+$thisaddress contains "majordomo" or
+$thisaddress contains "-request" or
+$thisaddress matches  "^owner-[^]+"
+)
+.endd
+The variable &$local_part$& contains the local part of the mail address of
+the user whose filter file is being run &-- it is normally your login id. The
+&$domain$& variable contains the mail domain. As explained above, if aliases
+or rewriting are defined, or if prefixes or suffixes are in use, the tests for
+the current user are also done with alternative addresses.
+
+
+
+
+.section "Testing delivery status"
+There are two conditions that are intended mainly for use in system filter
+files, but which are available in users' filter files as well. The condition
+&(first_delivery)& is true if this is the first process that is attempting to
+deliver the message, and false otherwise. This indicator is not reset until the
+first delivery process successfully terminates; if there is a crash or a power
+failure (for example), the next delivery attempt is also a &"first delivery"&.
+
+In a user filter file &(first_delivery)& will be false if there was previously
+an error in the filter, or if a delivery for the user failed owing to, for
+example, a quota error, or if forwarding to a remote address was deferred for
+some reason.
+
+The condition &(manually_thawed)& is true if the message was &"frozen"& for
+some reason, and was subsequently released by the system administrator. It is
+unlikely to be of use in users' filter files.
+
+
+.section "Multiple personal mailboxes" "SECTmbox"
+The system administrator can configure Exim so that users can set up variants
+on their email addresses and handle them separately. Consult your system
+administrator or local documentation to see if this facility is enabled on your
+system, and if so, what the details are.
+
+The facility involves the use of a prefix or a suffix on an email address. For
+example, all mail addressed to &'lg303-'&<&'something'&> would be the property
+of user &'lg303'&, who could determine how it was to be handled, depending on
+the value of <&'something'&>.
+
+There are two possible ways in which this can be set up. The first possibility
+is the use of multiple &_.forward_& files. In this case, mail to &'lg303-foo'&,
+for example, is handled by looking for a file called &_.forward-foo_& in
+&'lg303'&'s home directory. If such a file does not exist, delivery fails
+and the message is returned to its sender.
+
+The alternative approach is to pass all messages through a single &_.forward_&
+file, which must be a filter file so that it can distinguish between the
+different cases by referencing the variables &$local_part_prefix$& or
+&$local_part_suffix$&, as in the final example in section &<<SECTex>>& below.
+
+It is possible to configure Exim to support both schemes at once. In this case,
+a specific &_.forward-foo_& file is first sought; if it is not found, the basic
+&_.forward_& file is used.
+
+The &(personal)& test (see section &<<SECTpersonal>>&) includes prefixes and
+suffixes in its checking.
+
+
+
+.section "Ignoring delivery errors"
+As was explained above, filtering just sets up addresses for delivery &-- no
+deliveries are actually done while a filter file is active. If any of the
+generated addresses subsequently suffers a delivery failure, an error message
+is generated in the normal way. However, if a filter command that sets up a
+delivery is preceded by the word &"noerror"&, errors for that delivery,
+and any deliveries consequent on it (that is, from alias, forwarding, or
+filter files it invokes) are ignored.
+
+
+
+.section "Examples of Exim filter commands" "SECTex"
+Simple forwarding:
+
+.code
+# Exim filter
+deliver baggins@rivendell.middle-earth.example
+.endd
+
+Vacation handling using traditional means, assuming that the &_.vacation.msg_&
+and other files have been set up in your home directory:
+
+.code
+# Exim filter
+unseen pipe "/usr/ucb/vacation \"$local_part\""
+.endd
+
+Vacation handling inside Exim, having first created a file called
+&_.vacation.msg_& in your home directory:
+
+.code
+# Exim filter
+if personal then vacation endif
+.endd
+
+File some messages by subject:
+
+.code
+# Exim filter
+if $header_subject: contains "empire" or
+$header_subject: contains "foundation"
+then
+save $home/mail/f+e
+endif
+.endd
+
+Save all non-urgent messages by weekday:
+
+.code
+# Exim filter
+if $header_subject: does not contain "urgent" and
+$tod_full matches "^(...),"
+then
+save $home/mail/$1
+endif
+.endd
+
+Throw away all mail from one site, except from postmaster:
+
+.code
+# Exim filter
+if $reply_address contains "@spam.site.example" and
+$reply_address does not contain "postmaster@"
+then
+seen finish
+endif
+.endd
+
+Handle multiple personal mailboxes:
+
+.code
+# Exim filter
+if $local_part_suffix is "-foo"
+then
+save $home/mail/foo
+elif $local_part_suffix is "-bar"
+then
+save $home/mail/bar
+endif
+.endd
+
similarity index 51%
rename from doc/doc-docbook/spec.ascd
rename to doc/doc-docbook/spec.xfpt
index 0fb9137..67d8c83 100644 (file)
-////////////////////////////////////////////////////////////////////////////
-$Cambridge: exim/doc/doc-docbook/spec.ascd,v 1.4 2005/12/05 14:38:18 ph10 Exp $
-
-This is the primary source of the Exim Manual. It is an AsciiDoc document
-that is converted into DocBook XML for subsequent conversion into printing
-and online formats. The markup used herein is traditional AsciiDoc markup,
-with some extras. The markup is summarized in a file called AdMarkup.txt. A
-private AsciiDoc configuration file specifies how the extra markup is to be
-translated into DocBook XML. You MUST use this private AsciiDoc markup if you
-want to get sensible results from processing this document.
-////////////////////////////////////////////////////////////////////////////
-
-
-
-////////////////////////////////////////////////////////////////////////////
-I am abusing the <abstract> DocBook element as the only trivial way of getting
-this information onto the title verso page in the printed renditions. A better
-title page would be a useful improvement. The <abstract> element is removed by
-preprocessing for the HTML renditions, and the whole <docbookinfo> element is
-removed for ascii output formats.
-////////////////////////////////////////////////////////////////////////////
-
-Specification of the Exim Mail Transfer Agent
-=============================================
-:abstract:        University of Cambridge Computing Service, New Museums Site, Pembroke Street, Cambridge CB2 3QH, England
-:author:          Philip Hazel
-:copyright:       University of Cambridge
-:cpyear:          2005
-:date:            01 November 2005
-:doctitleabbrev:  The Exim MTA
-:revision:        4.60
-
-
-//////////////////////////////////////////////////////////////////////////////
-***WARNING*** Do not put anything, not even a titleabbrev, setting before
-the first chapter (luckily it does not need one) because if you do, AsciiDoc
-creates an empty <preface> element, which we do not want.
-//////////////////////////////////////////////////////////////////////////////
-
-Introduction
-------------
-
-////////////////////////////////////////////////////////////////////////////
-These are definitions of AsciiDoc "attributes" that are in effect "variables"
-whose values can be substituted. The first makes index entries shorter. The
-second avoids problems with literal asterisks getting tangled up with bold
-emphasis quotes. The others are here for convenience of editing.
-
-***WARNING*** The positioning of these definitions, after the first Chapter
-title, seems to be important. If they are placed earlier, they give rise to
-incorrect XML.
-////////////////////////////////////////////////////////////////////////////
-
-:ACL:             access control lists (ACLs)
-:star:            *
-:previousversion: 4.50
-:version:         4.60
-
-
-////////////////////////////////////////////////////////////////////////////
-This chunk of literal XML implements index entries of the form "x, see y" and
-"x, see also y". It didn't seem worth inventing AsciiDoc markup for this,
-because is it not something that is likely to change often.
-////////////////////////////////////////////////////////////////////////////
-
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.1 2006/02/01 11:01:02 ph10 Exp $
+.
+. /////////////////////////////////////////////////////////////////////////////
+. This is the primary source of the Exim Manual. It is an xfpt document that is
+. converted into DocBook XML for subsequent conversion into printing and online
+. formats. The markup used herein is "standard" xfpt markup, with some extras.
+. The markup is summarized in a file called Markup.txt.
+. /////////////////////////////////////////////////////////////////////////////
+
+.include stdflags
+.include stdmacs
+.docbook
+.book
+
+. /////////////////////////////////////////////////////////////////////////////
+. These definitions set some parameters and save some typing. Remember that
+. the <bookinfo> element must also be updated for each new edition.
+. /////////////////////////////////////////////////////////////////////////////
+
+.set ACL "access control lists (ACLs)"
+.set previousversion "4.50"
+.set version "4.60"
+
+
+. /////////////////////////////////////////////////////////////////////////////
+. Additional xfpt markup used by this document, over and above the default
+. provided in the xfpt library.
+. /////////////////////////////////////////////////////////////////////////////
+
+. --- Override the &$ flag to automatically insert a $ with the variable name
+
+.flag &$  $&   "<varname>$"  "</varname>"
+
+. --- Short flags for daggers in option headings. They will always be inside
+. --- an italic string, but we want the daggers to be roman.
+
+.flag &!!      "</emphasis>&dagger;<emphasis>"
+.flag &!?      "</emphasis>&Dagger;<emphasis>"
+
+. --- A macro for an Exim option definition heading, generating a one-line
+. --- table with four columns.
+
+.macro option
+.oindex "$1"
+.itable all 0 0 4 8* left 5* center 5* center 6* right
+.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
+.endtable
+.endmacro
+
+. --- A macro for the common 2-column tables. The width of the first column
+. --- is suitable for the many tables at the start of the main options chapter;
+. --- the small number of other 2-column tables override it.
+
+.macro table2 190pt 300pt
+.itable none 0 0 2 $1 left $2 left
+.endmacro
+
+. --- Macros for the concept and option index entries
+
+.macro cindex
+&<indexterm role="concept">&
+&<primary>&$1&</primary>&
+.arg 2
+&<secondary>&$2&</secondary>&
+.endarg
+&</indexterm>&
+.endmacro
+
+.macro oindex
+&<indexterm role="option">&
+&<primary>&$1&</primary>&
+.arg 2
+&<secondary>&$2&</secondary>&
+.endarg
+&</indexterm>&
+.endmacro
+
+.macro index
+.echo "** Don't use .index; use .cindex or .oindex"
+.endmacro
+. ////////////////////////////////////////////////////////////////////////////
+
+
+. ////////////////////////////////////////////////////////////////////////////
+. The <bookinfo> element is removed from the XML before processing for Ascii
+. output formats.
+. ////////////////////////////////////////////////////////////////////////////
+
+.literal xml
+<bookinfo>
+<title>Specification of the Exim Mail Transfer Agent</title>
+<titleabbrev>The Exim MTA</titleabbrev>
+<date>05 January 2006</date>
+<author><firstname>Philip</firstname><surname>Hazel</surname></author>
+<authorinitials>PH</authorinitials>
+<affiliation><orgname>University of Cambridge Computing Service</orgname></affiliation>
+<address>New Museums Site, Pembroke Street, Cambridge CB2 3QH, England</address>
+<revhistory><revision>
+  <revnumber>4.60-1</revnumber>
+  <date>30 January 2006</date>
+  <authorinitials>PH</authorinitials>
+</revision></revhistory>
+<copyright><year>2006</year><holder>University of Cambridge</holder></copyright>
+</bookinfo>
+.literal off
+
+
+. /////////////////////////////////////////////////////////////////////////////
+. This chunk of literal XML implements index entries of the form "x, see y" and
+. "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
+. at the top level, so we have to put the .chapter directive first.
+. /////////////////////////////////////////////////////////////////////////////
+
+.chapter "Introduction"
+.literal xml
+
 <indexterm role="concept">
   <primary>$1, $2, etc.</primary>
   <see><emphasis>numerical variables</emphasis></see>
@@ -184,12 +234,15 @@ because is it not something that is likely to change often.
   <primary>zero, binary</primary>
   <see><emphasis>binary zero</emphasis></see>
 </indexterm>
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.literal off
 
 
-////////////////////////////////////////////////////////////////////////////
-OK, now we start with the real data for this first chapter.
-////////////////////////////////////////////////////////////////////////////
+. /////////////////////////////////////////////////////////////////////////////
+. This is the real start of the first chapter. See the comment above as to why
+. we can't have the .chapter line here.
+. chapter "Introduction"
+. /////////////////////////////////////////////////////////////////////////////
 
 Exim is a mail transfer agent (MTA) for hosts that are running Unix or
 Unix-like operating systems. It was designed on the assumption that it would be
@@ -209,8 +262,8 @@ that can be installed on systems running Windows. However, this document does
 not contain any information about running Exim in the Cygwin environment.
 
 The terms and conditions for the use and distribution of Exim are contained in
-the file _NOTICE_. Exim is distributed under the terms of the GNU General
-Public Licence, a copy of which may be found in the file _LICENCE_.
+the file &_NOTICE_&. Exim is distributed under the terms of the GNU General
+Public Licence, a copy of which may be found in the file &_LICENCE_&.
 
 The use, supply or promotion of Exim for the purpose of sending bulk,
 unsolicited electronic mail is incompatible with the basic aims of the program,
@@ -227,19 +280,18 @@ new, and has developed far beyond the initial concept.
 Many people, both in Cambridge and around the world, have contributed to the
 development and the testing of Exim, and to porting it to various operating
 systems. I am grateful to them all. The distribution now contains a file called
-_ACKNOWLEDGMENTS_, in which I have started recording the names of
+&_ACKNOWLEDGMENTS_&, in which I have started recording the names of
 contributors.
 
 
-
-Exim documentation
-~~~~~~~~~~~~~~~~~~
-[revisionflag="changed"]
-cindex:[documentation]
-This edition of the Exim specification applies to version {version} of Exim.
-Substantive changes from the {previousversion} edition are marked in some
+.section "Exim documentation"
+.new
+.cindex "documentation"
+This edition of the Exim specification applies to version &version; of Exim.
+Substantive changes from the &previousversion; edition are marked in some
 renditions of the document; this paragraph is so marked if the rendition is
 capable of showing a change indicator.
+.wen
 
 This document is very much a reference manual; it is not a tutorial. The reader
 is expected to have some familiarity with the SMTP mail transfer protocol and
@@ -250,499 +302,455 @@ Furthermore, the manual aims to cover every aspect of Exim in detail, including
 a number of rarely-used, special-purpose features that are unlikely to be of
 very wide interest.
 
-cindex:[books about Exim]
-An ``easier'' discussion of Exim which provides more in-depth explanatory,
-introductory, and tutorial material can be found in a book entitled
-'The Exim SMTP Mail Server', published by UIT Cambridge
-(*http://www.uit.co.uk/exim-book/[]*).
+.cindex "books about Exim"
+An &"easier"& discussion of Exim which provides more in-depth explanatory,
+introductory, and tutorial material can be found in a book entitled &'The Exim
+SMTP Mail Server'&, published by UIT Cambridge
+(&url(http://www.uit.co.uk/exim-book/)).
 
 This book also contains a chapter that gives a general introduction to SMTP and
 Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
 with the latest release of Exim. (Note that the earlier book about Exim,
 published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.)
 
-[revisionflag="changed"]
-cindex:[Debian,information sources]
+.new
+.cindex "Debian" "information sources"
 If you are using a Debian distribution of Exim, you will find information about
 Debian-specific features in the file
-&&&&
-_/usr/share/doc/exim4-base/README.Debian_
-&&&&
-The command ^man update-exim.conf^ is another source of Debian-specific
+.display
+&_/usr/share/doc/exim4-base/README.Debian_&
+.endd
+The command &(man update-exim.conf)& is another source of Debian-specific
 information.
+.wen
 
-cindex:[_doc/NewStuff_]
-cindex:[_doc/ChangeLog_]
-cindex:[change log]
+.cindex "&_doc/NewStuff_&"
+.cindex "&_doc/ChangeLog_&"
+.cindex "change log"
 As the program develops, there may be features in newer versions that have not
 yet made it into this document, which is updated only when the most significant
 digit of the fractional part of the version number changes. Specifications of
 new features that are not yet in this manual are placed in the file
-_doc/NewStuff_ in the Exim distribution.
+&_doc/NewStuff_& in the Exim distribution.
 
-Some features may be classified as ``experimental''. These may change
+Some features may be classified as &"experimental"&. These may change
 incompatibly while they are developing, or even be withdrawn. For this reason,
 they are not documented in this manual. Information about experimental features
-can be found in the file _doc/experimental.txt_.
+can be found in the file &_doc/experimental.txt_&.
 
 All changes to the program (whether new features, bug fixes, or other kinds of
-change) are noted briefly in the file called _doc/ChangeLog_.
+change) are noted briefly in the file called &_doc/ChangeLog_&.
 
-cindex:[_doc/spec.txt_]
-This specification itself is available as an ASCII file in _doc/spec.txt_ so
-that it can easily be searched with a text editor. Other files in the _doc_
+.cindex "&_doc/spec.txt_&"
+This specification itself is available as an ASCII file in &_doc/spec.txt_& so
+that it can easily be searched with a text editor. Other files in the &_doc_&
 directory are:
 
-[frame="none"]
-`--------------------`------------------------------------------
-_OptionLists.txt_    list of all options in alphabetical order
-_dbm.discuss.txt_    discussion about DBM libraries
-_exim.8_             a man page of Exim's command line options
-_experimental.txt_   documentation of experimental features
-_filter.txt_         specification of the filter language
-_pcrepattern.txt_    specification of PCRE regular expressions
-_pcretest.txt_       specification of the PCRE testing program
-_Exim3.upgrade_      upgrade notes from release 2 to release 3
-_Exim4.upgrade_      upgrade notes from release 3 to release 4
-----------------------------------------------------------------
+.table2 100pt
+.row &_OptionLists.txt_&     "list of all options in alphabetical order"
+.row &_dbm.discuss.txt_&     "discussion about DBM libraries"
+.row &_exim.8_&              "a man page of Exim's command line options"
+.row &_experimental.txt_&    "documentation of experimental features"
+.row &_filter.txt_&          "specification of the filter language"
+.row &_pcrepattern.txt_&     "specification of PCRE regular expressions"
+.row &_pcretest.txt_&        "specification of the PCRE testing program"
+.row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
+.row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
+.endtable
 
 The main specification and the specification of the filtering language are also
 available in other formats (HTML, PostScript, PDF, and Texinfo). Section
-<<SECTavail>> below tells you how to get hold of these.
+&<<SECTavail>>& below tells you how to get hold of these.
 
 
 
-FTP and web sites
-~~~~~~~~~~~~~~~~~
-cindex:[web site]
-cindex:[FTP site]
+.section "FTP and web sites"
+.cindex "web site"
+.cindex "FTP site"
 The primary site for Exim source distributions is currently the University of
-Cambridge's FTP site, whose contents are described in 'Where to find the Exim
-distribution' below. In addition, there is a web site and an FTP site at
-%exim.org%. These are now also hosted at the University of Cambridge. The
-%exim.org% site was previously hosted for a number of years by Energis Squared,
-formerly Planet Online Ltd, whose support I gratefully acknowledge.
-
+Cambridge's FTP site, whose contents are described in &'Where to find the Exim
+distribution'& below. In addition, there is a web site and an FTP site at
+&%exim.org%&. These are now also hosted at the University of Cambridge. The
+&%exim.org%& site was previously hosted for a number of years by Energis
+Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge.
+
+.cindex "wiki"
+.cindex "FAQ"
 As well as Exim distribution tar files, the Exim web site contains a number of
-differently formatted versions of the documentation, including the
-cindex:[FAQ] FAQ in both text and HTML formats. The HTML version comes with
-a keyword-in-context index. A recent addition to the online information is the
-cindex:[wiki]
-Exim wiki (*http://www.exim.org/eximwiki/[]*).
-We hope that this will make it easier for Exim users to contribute examples,
-tips, and know-how for the benefit of others.
+differently formatted versions of the documentation, including the FAQ in both
+text and HTML formats. The HTML version comes with a keyword-in-context index.
+A recent addition to the online information is the Exim wiki
+(&url(http://www.exim.org/eximwiki/)). We hope that this will make it easier
+for Exim users to contribute examples, tips, and know-how for the benefit of
+others.
 
 
 
-Mailing lists
-~~~~~~~~~~~~~
-cindex:[mailing lists,for Exim users]
+.section "Mailing lists"
+.cindex "mailing lists" "for Exim users"
 The following are the three main Exim mailing lists:
 
-[frame="none"]
-`-------------------------------`----------------------------------------
-'exim-users@exim.org'           general discussion list
-'exim-dev@exim.org'             discussion of bugs, enhancements, etc.
-'exim-announce@exim.org'        moderated, low volume announcements list
--------------------------------------------------------------------------
+.table2 140pt
+.row &'exim-users@exim.org'&      "general discussion list"
+.row &'exim-dev@exim.org'&        "discussion of bugs, enhancements, etc."
+.row &'exim-announce@exim.org'&   "moderated, low volume announcements list"
+.endtable
 
 You can subscribe to these lists, change your existing subscriptions, and view
-or search the archives via the mailing lists link on the Exim home page. The
-'exim-users' mailing list is also forwarded to
-*http://www.egroups.com/list/exim-users[]*, an archiving system with searching
-capabilities.
-
-[revisionflag="changed"]
-cindex:[Debian,mailing list for]
-If you are using a Debian distribution of Exim, you may wish to subscribe to
-the Debian-specific mailing list, which is
-'pkg-exim4-users@lists.alioth.debian.org'.
-
-
-Exim training
-~~~~~~~~~~~~~
-cindex:[training courses]
+or search the archives via the mailing lists link on the Exim home page.
+.cindex "Debian" "mailing list for"
+&new("If you are using a Debian distribution of Exim, you may wish to subscribe
+to the Debian-specific mailing list
+&'pkg-exim4-users@lists.alioth.debian.org'&.")
+.wen
+
+.section "Exim training"
+.cindex "training courses"
 From time to time (approximately annually at the time of writing), training
-courses are run by the author of Exim in Cambridge, UK. Details can be found on
-the web site *http://www-tus.csx.cam.ac.uk/courses/exim/[]*.
+courses are run by the author of Exim in Cambridge, UK. Details of any
+forthcoming courses can be found on the web site
+&url(http://www-tus.csx.cam.ac.uk/courses/exim/).
 
 
-Bug reports
-~~~~~~~~~~~
-cindex:[bug reports]
-cindex:[reporting bugs]
-Reports of obvious bugs should be emailed to 'bugs@exim.org'. However, if
-you are unsure whether some behaviour is a bug or not, the best thing to do is
-to post a message to the 'exim-dev' mailing list and have it discussed.
+.section "Bug reports"
+.cindex "bug reports"
+.cindex "reporting bugs"
+Reports of obvious bugs should be emailed to &'bugs@exim.org'&. However, if you
+are unsure whether some behaviour is a bug or not, the best thing to do is to
+post a message to the &'exim-dev'& mailing list and have it discussed.
 
 
 
-[[SECTavail]]
-Where to find the Exim distribution
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[FTP site]
-cindex:[distribution,ftp site]
+.section "Where to find the Exim distribution" "SECTavail"
+.cindex "FTP site"
+.cindex "distribution" "ftp site"
 The master ftp site for the Exim distribution is
-
-&&&
-*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim[]*
-&&&
-
+.display
+&*ftp://ftp.csx.cam.ac.uk/pub/software/email/exim*&
+.endd
 This is mirrored by
-
-&&&
-*ftp://ftp.exim.org/pub/exim[]*
-&&&
-
-The file references that follow are relative to the _exim_ directories at these
-sites. There are now quite a number of independent mirror sites around the
-world. Those that I know about are listed in the file called _Mirrors_.
-
-Within the _exim_ directory there are subdirectories called _exim3_ (for
-previous Exim 3 distributions), _exim4_ (for the latest Exim 4
-distributions), and _Testing_ for testing versions. In the _exim4_
+.display
+&*ftp://ftp.exim.org/pub/exim*&
+.endd
+The file references that follow are relative to the &_exim_& directories at
+these sites. There are now quite a number of independent mirror sites around
+the world. Those that I know about are listed in the file called &_Mirrors_&.
+
+Within the &_exim_& directory there are subdirectories called &_exim3_& (for
+previous Exim 3 distributions), &_exim4_& (for the latest Exim 4
+distributions), and &_Testing_& for testing versions. In the &_exim4_&
 subdirectory, the current release can always be found in files called
-
-&&&
-_exim-n.nn.tar.gz_
-_exim-n.nn.tar.bz2_
-&&&
-
-where 'n.nn' is the highest such version number in the directory. The two
+.display
+&_exim-n.nn.tar.gz_&
+&_exim-n.nn.tar.bz2_&
+.endd
+where &'n.nn'& is the highest such version number in the directory. The two
 files contain identical data; the only difference is the type of compression.
-The _.bz2_ file is usually a lot smaller than the _.gz_ file.
+The &_.bz2_& file is usually a lot smaller than the &_.gz_& file.
 
-cindex:[distribution,signing details]
-cindex:[distribution,public key]
-cindex:[public key for signed distribution]
+.cindex "distribution" "signing details"
+.cindex "distribution" "public key"
+.cindex "public key for signed distribution"
 The distributions are currently signed with Philip Hazel's GPG key. The
 corresponding public key is available from a number of keyservers, and there is
-also a copy in the file _Public-Key_. The signatures for the tar bundles are
+also a copy in the file &_Public-Key_&. The signatures for the tar bundles are
 in:
-
-&&&
-_exim-n.nn.tar.gz.sig_
-_exim-n.nn.tar.bz2.sig_
-&&&
-
+.display
+&_exim-n.nn.tar.gz.sig_&
+&_exim-n.nn.tar.bz2.sig_&
+.endd
 For each released version, the log of changes is made separately available in a
-separate file in the directory _ChangeLogs_ so that it is possible to
+separate file in the directory &_ChangeLogs_& so that it is possible to
 find out what has changed without having to download the entire distribution.
 
-cindex:[documentation,available formats]
+.cindex "documentation" "available formats"
 The main distribution contains ASCII versions of this specification and other
 documentation; other formats of the documents are available in separate files
-inside the _exim4_ directory of the FTP site:
-
-&&&
-_exim-html-n.nn.tar.gz_
-_exim-pdf-n.nn.tar.gz_
-_exim-postscript-n.nn.tar.gz_
-_exim-texinfo-n.nn.tar.gz_
-&&&
-
-These tar files contain only the _doc_ directory, not the complete
-distribution, and are also available in _.bz2_ as well as _.gz_ forms.
-cindex:[FAQ]
+inside the &_exim4_& directory of the FTP site:
+.display
+&_exim-html-n.nn.tar.gz_&
+&_exim-pdf-n.nn.tar.gz_&
+&_exim-postscript-n.nn.tar.gz_&
+&_exim-texinfo-n.nn.tar.gz_&
+.endd
+These tar files contain only the &_doc_& directory, not the complete
+distribution, and are also available in &_.bz2_& as well as &_.gz_& forms.
+.cindex "FAQ"
 The FAQ is available for downloading in two different formats in these files:
-
-&&&
-_exim4/FAQ.txt.gz_
-_exim4/FAQ.html.tar.gz_
-&&&
-
+.display
+&_exim4/FAQ.txt.gz_&
+&_exim4/FAQ.html.tar.gz_&
+.endd
 The first of these is a single ASCII file that can be searched with a text
 editor. The second is a directory of HTML files, normally accessed by starting
-at _index.html_. The HTML version of the FAQ (which is also included in the
+at &_index.html_&. The HTML version of the FAQ (which is also included in the
 HTML documentation tarbundle) includes a keyword-in-context index, which is
 often the most convenient way of finding your way around.
 
 
-Wish list
-~~~~~~~~~
-cindex:[wish list]
+.section "Wish list"
+.cindex "wish list"
 A wish list is maintained, containing ideas for new features that have been
 submitted. From time to time the file is exported to the ftp site into the file
-_exim4/WishList_. Items are removed from the list if they get implemented.
+&_exim4/WishList_&. Items are removed from the list if they get implemented.
 
 
 
-Contributed material
-~~~~~~~~~~~~~~~~~~~~
-cindex:[contributed material]
-At the ftp site, there is a directory called _Contrib_ that contains
+.section "Contributed material"
+.cindex "contributed material"
+At the ftp site, there is a directory called &_Contrib_& that contains
 miscellaneous files contributed to the Exim community by Exim users. There is
 also a collection of contributed configuration examples in
-_exim4/config.samples.tar.gz_. These samples are referenced from the FAQ.
-
-
-
-Limitations
-~~~~~~~~~~~
-- cindex:[limitations of Exim]
-Exim is designed for use as an Internet MTA, and therefore handles addresses
-in RFC 2822 domain format only.
-cindex:[bang paths,not handled by Exim]
-It cannot handle UUCP ``bang paths'', though simple two-component bang paths can
-be converted by a straightforward rewriting configuration. This restriction
-does not prevent Exim from being interfaced to UUCP as a transport mechanism,
-provided that domain addresses are used.
-
-- cindex:[domainless addresses]
-cindex:[address,without domain]
+&_exim4/config.samples.tar.gz_&. These samples are referenced from the FAQ.
+
+
+
+.section "Limitations"
+.ilist
+.cindex "limitations of Exim"
+.cindex "bang paths" "not handled by Exim"
+Exim is designed for use as an Internet MTA, and therefore handles addresses in
+RFC 2822 domain format only. It cannot handle UUCP &"bang paths"&, though
+simple two-component bang paths can be converted by a straightforward rewriting
+configuration. This restriction does not prevent Exim from being interfaced to
+UUCP as a transport mechanism, provided that domain addresses are used.
+.next
+.cindex "domainless addresses"
+.cindex "address" "without domain"
 Exim insists that every address it handles has a domain attached. For incoming
 local messages, domainless addresses are automatically qualified with a
 configured domain value. Configuration options specify from which remote
 systems unqualified addresses are acceptable. These are then qualified on
 arrival.
-
-- cindex:[transport,external]
-cindex:[external transports]
-The only external transport currently implemented is an SMTP transport over a
-TCP/IP network (using sockets, including support for IPv6). However, a pipe
+.next
+.cindex "transport" "external"
+.cindex "external transports"
+The only external transport mechanisms that are currently implemented are SMTP
+and LMTP over a TCP/IP network (including support for IPv6). However, a pipe
 transport is available, and there are facilities for writing messages to files
-and pipes, optionally in 'batched SMTP' format; these facilities can be used
-to send messages to some other transport mechanism such as UUCP, provided it
-can handle domain-style addresses. Batched SMTP input is also catered for.
-
-Exim is not designed for storing mail for dial-in hosts. When the volumes of
-such mail are large, it is better to get the messages ``delivered'' into files
+and pipes, optionally in &'batched SMTP'& format; these facilities can be used
+to send messages to other transport mechanisms such as UUCP, provided they can
+handle domain-style addresses. Batched SMTP input is also catered for.
+.next
+Exim is not designed for storing mail for dial-in hosts. When the volumes of
+such mail are large, it is better to get the messages &"delivered"& into files
 (that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
 other means.
-
-Although Exim does have basic facilities for scanning incoming messages, these
+.next
+Although Exim does have basic facilities for scanning incoming messages, these
 are not comprehensive enough to do full virus or spam scanning. Such operations
 are best carried out using additional specialized software packages. If you
 compile Exim with the content-scanning extension, straightforward interfaces to
 a number of common scanners are provided.
+.endlist
 
 
-
-
-
-Run time configuration
-~~~~~~~~~~~~~~~~~~~~~~
+.section "Run time configuration"
 Exim's run time configuration is held in a single text file that is divided
 into a number of sections. The entries in this file consist of keywords and
 values, in the style of Smail 3 configuration files. A default configuration
 file which is suitable for simple online installations is provided in the
-distribution, and is described in chapter <<CHAPdefconfil>> below.
+distribution, and is described in chapter &<<CHAPdefconfil>>& below.
 
 
-
-Calling interface
-~~~~~~~~~~~~~~~~~
-cindex:[Sendmail compatibility,command line interface]
+.section "Calling interface"
+.cindex "Sendmail compatibility" "command line interface"
 Like many MTAs, Exim has adopted the Sendmail command line interface so that it
-can be a straight replacement for _/usr/lib/sendmail_ or
-_/usr/sbin/sendmail_ when sending mail, but you do not need to know anything
+can be a straight replacement for &_/usr/lib/sendmail_& or
+&_/usr/sbin/sendmail_& when sending mail, but you do not need to know anything
 about Sendmail in order to run Exim. For actions other than sending messages,
 Sendmail-compatible options also exist, but those that produce output (for
-example, %-bp%, which lists the messages on the queue) do so in Exim's own
+example, &%-bp%&, which lists the messages on the queue) do so in Exim's own
 format. There are also some additional options that are compatible with Smail
-3, and some further options that are new to Exim. Chapter <<CHAPcommandline>>
+3, and some further options that are new to Exim. Chapter &<<CHAPcommandline>>&
 documents all Exim's command line options. This information is automatically
 made into the man page that forms part of the Exim distribution.
 
 Control of messages on the queue can be done via certain privileged command
-line options. There is also an optional monitor program called 'eximon', which
-displays current information in an X window, and which contains a menu
+line options. There is also an optional monitor program called &'eximon'&,
+which displays current information in an X window, and which contains a menu
 interface to Exim's command line administration options.
 
 
 
-Terminology
-~~~~~~~~~~~
-cindex:[terminology definitions]
-cindex:[body of message,definition of]
-The 'body' of a message is the actual data that the sender wants to transmit.
-It is the last part of a message, and is separated from the 'header' (see
+.section "Terminology"
+.cindex "terminology definitions"
+.cindex "body of message" "definition of"
+The &'body'& of a message is the actual data that the sender wants to transmit.
+It is the last part of a message, and is separated from the &'header'& (see
 below) by a blank line.
 
-cindex:[bounce message,definition of]
+.cindex "bounce message" "definition of"
 When a message cannot be delivered, it is normally returned to the sender in a
-delivery failure message or a ``non-delivery report'' (NDR). The term 'bounce'
-is commonly used for this action, and the error reports are often called
-'bounce messages'. This is a convenient shorthand for ``delivery failure error
-report''. Such messages have an empty sender address in the message's
-'envelope' (see below) to ensure that they cannot themselves give rise to
-further bounce messages.
-
-The term 'default' appears frequently in this manual. It is used to qualify a
+delivery failure message or a &"non-delivery report"& (NDR). The term
+&'bounce'& is commonly used for this action, and the error reports are often
+called &'bounce messages'&. This is a convenient shorthand for &"delivery
+failure error report"&. Such messages have an empty sender address in the
+message's &'envelope'& (see below) to ensure that they cannot themselves give
+rise to further bounce messages.
+
+The term &'default'& appears frequently in this manual. It is used to qualify a
 value which is used in the absence of any setting in the configuration. It may
 also qualify an action which is taken unless a configuration setting specifies
 otherwise.
 
-The term 'defer' is used when the delivery of a message to a specific
+The term &'defer'& is used when the delivery of a message to a specific
 destination cannot immediately take place for some reason (a remote host may be
-down, or a user's local mailbox may be full). Such deliveries are 'deferred'
+down, or a user's local mailbox may be full). Such deliveries are &'deferred'&
 until a later time.
 
-The word 'domain' is sometimes used to mean all but the first component of a
-host's name. It is 'not' used in that sense here, where it normally
-refers to the part of an email address following the @ sign.
+The word &'domain'& is sometimes used to mean all but the first component of a
+host's name. It is &'not'& used in that sense here, where it normally refers to
+the part of an email address following the @ sign.
 
-cindex:[envelope, definition of]
-cindex:[sender,definition of]
-A message in transit has an associated 'envelope', as well as a header and a
+.cindex "envelope" "definition of"
+.cindex "sender" "definition of"
+A message in transit has an associated &'envelope'&, as well as a header and a
 body. The envelope contains a sender address (to which bounce messages should
 be delivered), and any number of recipient addresses. References to the
 sender or the recipients of a message usually mean the addresses in the
 envelope. An MTA uses these addresses for delivery, and for returning bounce
 messages, not the addresses that appear in the header lines.
 
-cindex:[message header, definition of]
-cindex:[header section,definition of]
-The 'header' of a message is the first part of a message's text, consisting
-of a number of lines, each of which has a name such as 'From:', 'To:',
-'Subject:', etc. Long header lines can be split over several text lines by
+.cindex "message header" "definition of"
+.cindex "header section" "definition of"
+The &'header'& of a message is the first part of a message's text, consisting
+of a number of lines, each of which has a name such as &'From:'&, &'To:'&,
+&'Subject:'&, etc. Long header lines can be split over several text lines by
 indenting the continuations. The header is separated from the body by a blank
 line.
 
-cindex:[local part,definition of]
-cindex:[domain,definition of]
-The term 'local part', which is taken from RFC 2822, is used to refer to that
+.cindex "local part" "definition of"
+.cindex "domain" "definition of"
+The term &'local part'&, which is taken from RFC 2822, is used to refer to that
 part of an email address that precedes the @ sign. The part that follows the
-@ sign is called the 'domain' or 'mail domain'.
+@ sign is called the &'domain'& or &'mail domain'&.
 
-cindex:[local delivery,definition of]
-cindex:[remote delivery, definition of]
-The terms 'local delivery' and 'remote delivery' are used to distinguish
+.cindex "local delivery" "definition of"
+.cindex "remote delivery" "definition of"
+The terms &'local delivery'& and &'remote delivery'& are used to distinguish
 delivery to a file or a pipe on the local host from delivery by SMTP over
 TCP/IP to another host. As far as Exim is concerned, all hosts other than the
-host it is running on are 'remote'.
+host it is running on are &'remote'&.
 
-cindex:[return path,definition of]
-'Return path' is another name that is used for the sender address in a
+.cindex "return path" "definition of"
+&'Return path'& is another name that is used for the sender address in a
 message's envelope.
 
-cindex:[queue,definition of]
-The term 'queue' is used to refer to the set of messages awaiting delivery,
+.cindex "queue" "definition of"
+The term &'queue'& is used to refer to the set of messages awaiting delivery,
 because this term is in widespread use in the context of MTAs. However, in
 Exim's case the reality is more like a pool than a queue, because there is
 normally no ordering of waiting messages.
 
-cindex:[queue runner,definition of]
-The term 'queue runner' is used to describe a process that scans the queue
+.cindex "queue runner" "definition of"
+The term &'queue runner'& is used to describe a process that scans the queue
 and attempts to deliver those messages whose retry times have come. This term
-is used by other MTAs, and also relates to the command %runq%, but in Exim
+is used by other MTAs, and also relates to the command &%runq%&, but in Exim
 the waiting messages are normally processed in an unpredictable order.
 
-cindex:[spool directory,definition of]
-The term 'spool directory' is used for a directory in which Exim keeps the
-messages on its queue -- that is, those that it is in the process of
+.cindex "spool directory" "definition of"
+The term &'spool directory'& is used for a directory in which Exim keeps the
+messages on its queue &-- that is, those that it is in the process of
 delivering. This should not be confused with the directory in which local
-mailboxes are stored, which is called a ``spool directory'' by some people. In
-the Exim documentation, ``spool'' is always used in the first sense.
+mailboxes are stored, which is called a &"spool directory"& by some people. In
+the Exim documentation, &"spool"& is always used in the first sense.
 
 
 
 
 
 
-////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
 
-Incorporated code
------------------
-cindex:[incorporated code]
-cindex:[regular expressions,library]
-cindex:[PCRE]
+.chapter "Incorporated code"
+.cindex "incorporated code"
+.cindex "regular expressions" "library"
+.cindex "PCRE"
 A number of pieces of external code are included in the Exim distribution.
 
-- Regular expressions are supported in the main Exim program and in the Exim
-monitor using the freely-distributable PCRE library, copyright (c) University
-of Cambridge. The source is distributed in the directory _src/pcre_. However,
-this is a cut-down version of PCRE. If you want to use the PCRE library in
-other programs, you should obtain and install the full version from
-*ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre[]*.
-
-- cindex:[cdb,acknowledgement]
+.ilist
+Regular expressions are supported in the main Exim program and in the Exim
+monitor using the freely-distributable PCRE library, copyright &copy;
+University of Cambridge. The source is distributed in the directory
+&_src/pcre_&. However, this is a cut-down version of PCRE. If you want to use
+the PCRE library in other programs, you should obtain and install the full
+version from &*ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre*&.
+.next
+.cindex "cdb" "acknowledgement"
 Support for the cdb (Constant DataBase) lookup method is provided by code
 contributed by Nigel Metheringham of (at the time he contributed it) Planet
-Online Ltd. which contains the following statements:
-+
-++++++++++++++++++++++
-<blockquote>
-++++++++++++++++++++++
-+
-Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
-+
+Online Ltd. The implementation is completely contained within the code of Exim.
+It does not link against an external cdb library. The code contains the
+following statements:
+
+.blockquote
+Copyright &copy; 1998 Nigel Metheringham, Planet Online Ltd
+
 This program is free software; you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
 Foundation; either version 2 of the License, or (at your option) any later
 version.
-+
+
 This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information,
 the spec and sample code for cdb can be obtained from
-*http://www.pobox.com/{tl}djb/cdb.html[]*. This implementation borrows some code
-from Dan Bernstein's implementation (which has no license restrictions applied
-to it).
-+
-++++++++++++++++++++++
-</blockquote>
-++++++++++++++++++++++
-+
-The implementation is completely contained within the code of Exim.
-It does not link against an external cdb library.
-
-- cindex:[SPA authentication]
-cindex:[Samba project]
-cindex:[Microsoft Secure Password Authentication]
-Client support for Microsoft's 'Secure Password Authentication' is provided
+&url(http://www.pobox.com/~djb/cdb.html). This implementation borrows some
+code from Dan Bernstein's implementation (which has no license restrictions
+applied to it).
+.endblockquote
+.next
+.cindex "SPA authentication"
+.cindex "Samba project"
+.cindex "Microsoft Secure Password Authentication"
+Client support for Microsoft's &'Secure Password Authentication'& is provided
 by code contributed by Marc Prud'hommeaux. Server support was contributed by
 Tom Kistner. This includes code taken from the Samba project, which is released
 under the Gnu GPL.
-
-- cindex:[Cyrus]
-cindex:['pwcheck' daemon]
-cindex:['pwauthd' daemon]
-Support for calling the Cyrus 'pwcheck' and 'saslauthd' daemons is provided
+.next
+.cindex "Cyrus"
+.cindex "&'pwcheck'& daemon"
+.cindex "&'pwauthd'& daemon"
+Support for calling the Cyrus &'pwcheck'& and &'saslauthd'& daemons is provided
 by code taken from the Cyrus-SASL library and adapted by Alexander S.
 Sabourenkov. The permission notice appears below, in accordance with the
 conditions expressed therein.
-+
-++++++++++++++++++++++
-<blockquote>
-++++++++++++++++++++++
-+
-Copyright (c) 2001 Carnegie Mellon University.  All rights reserved.
-+
+
+.blockquote
+Copyright &copy; 2001 Carnegie Mellon University.  All rights reserved.
+
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
-+
-. Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
 
-. Redistributions in binary form must reproduce the above copyright
+.olist
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+.next
+Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in
 the documentation and/or other materials provided with the
 distribution.
-
-. The name ``Carnegie Mellon University'' must not be used to
+.next
+The name &"Carnegie Mellon University"& must not be used to
 endorse or promote products derived from this software without
 prior written permission. For permission or any other legal
 details, please contact
-+
-&&&
+.display
               Office of Technology Transfer
               Carnegie Mellon University
               5000 Forbes Avenue
               Pittsburgh, PA  15213-3890
               (412) 268-4387, fax: (412) 268-7395
               tech-transfer@andrew.cmu.edu
-&&&
-///
-The need to indent that block explicitly is a pain.
-///
-
-. Redistributions of any form whatsoever must retain the following
+.endd
+.next
+Redistributions of any form whatsoever must retain the following
 acknowledgment:
-+
-``This product includes software developed by Computing Services
-at Carnegie Mellon University (*http://www.cmu.edu/computing/[]*).''
-+
+
+&"This product includes software developed by Computing Services
+at Carnegie Mellon University (&url(http://www.cmu.edu/computing/)."&
+
 CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
 THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
 AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
@@ -750,33 +758,24 @@ FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
 AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
 OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.endlist
+.endblockquote
 
-///
-Note, no "+" line there, because we want to terminate the inner list item
-before ending the block quote.
-///
-+
-++++++++++++++++++++++
-</blockquote>
-++++++++++++++++++++++
-
-- cindex:[Exim monitor,acknowledgement]
-cindex:[X-windows]
-cindex:[Athena]
+.next
+.cindex "Exim monitor" "acknowledgement"
+.cindex "X-windows"
+.cindex "Athena"
 The Exim Monitor program, which is an X-Window application, includes
 modified versions of the Athena StripChart and TextPop widgets.
 This code is copyright by DEC and MIT, and their permission notice appears
 below, in accordance with the conditions expressed therein.
-+
-++++++++++++++++++++++
-<blockquote>
-++++++++++++++++++++++
-+
+
+.blockquote
 Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
 and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
-+
+
 All Rights Reserved
-+
+
 Permission to use, copy, modify, and distribute this software and its
 documentation for any purpose and without fee is hereby granted,
 provided that the above copyright notice appear in all copies and that
@@ -784,7 +783,7 @@ both that copyright notice and this permission notice appear in
 supporting documentation, and that the names of Digital or MIT not be
 used in advertising or publicity pertaining to distribution of the
 software without specific, written prior permission.
-+
+
 DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
 ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
 DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
@@ -792,30 +791,27 @@ ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
 WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
 ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
 SOFTWARE.
-+
-++++++++++++++++++++++
-</blockquote>
-++++++++++++++++++++++
+.endblockquote
 
-- Many people have contributed code fragments, some large, some small, that were
+.next
+Many people have contributed code fragments, some large, some small, that were
 not covered by any specific licence requirements. It is assumed that the
 contributors are happy to see their code incoporated into Exim under the GPL.
+.endlist
 
 
 
 
 
-////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
 
-[titleabbrev="Receiving and delivering mail"]
-How Exim receives and delivers mail
------------------------------------
+.chapter "How Exim receives and delivers mail" "" &&&
+         "Receiving and delivering mail"
 
 
-Overall philosophy
-~~~~~~~~~~~~~~~~~~
-cindex:[design philosophy]
+.section "Overall philosophy"
+.cindex "design philosophy"
 Exim is designed to work efficiently on systems that are permanently connected
 to the Internet and are handling a general mix of mail. In such circumstances,
 most messages can be delivered immediately. Consequently, Exim does not
@@ -824,92 +820,91 @@ it does try to send several messages in a single SMTP connection after a host
 has been down, and it also maintains per-host retry information.
 
 
-
-Policy control
-~~~~~~~~~~~~~~
-cindex:[policy control,overview]
+.section "Policy control"
+.cindex "policy control" "overview"
 Policy controls are now an important feature of MTAs that are connected to the
 Internet. Perhaps their most important job is to stop MTAs being abused as
-``open relays'' by misguided individuals who send out vast amounts of unsolicited
-junk, and want to disguise its source. Exim provides flexible facilities for
-specifying policy controls on incoming mail:
+&"open relays"& by misguided individuals who send out vast amounts of
+unsolicited junk, and want to disguise its source. Exim provides flexible
+facilities for specifying policy controls on incoming mail:
 
-- cindex:[{ACL},introduction]
+.ilist
+.cindex "&ACL;" "introduction"
 Exim 4 (unlike previous versions of Exim) implements policy controls on
-incoming mail by means of 'Access Control Lists' (ACLs). Each list is a
+incoming mail by means of &'Access Control Lists'& (ACLs). Each list is a
 series of statements that may either grant or deny access. ACLs can be used at
 several places in the SMTP dialogue while receiving a message from a remote
-host. However, the most common places are after each RCPT command, and at
-the very end of the message. The sysadmin can specify conditions for accepting
-or rejecting individual recipients or the entire message, respectively, at
-these two points (see chapter <<CHAPACL>>). Denial of access results in an SMTP
+host. However, the most common places are after each RCPT command, and at the
+very end of the message. The sysadmin can specify conditions for accepting or
+rejecting individual recipients or the entire message, respectively, at these
+two points (see chapter &<<CHAPACL>>&). Denial of access results in an SMTP
 error code.
-
-An ACL is also available for locally generated, non-SMTP messages. In this
+.next
+An ACL is also available for locally generated, non-SMTP messages. In this
 case, the only available actions are to accept or deny the entire message.
-
-When Exim is compiled with the content-scanning extension, facilities are
+.next
+When Exim is compiled with the content-scanning extension, facilities are
 provided in the ACL mechanism for passing the message to external virus and/or
 spam scanning software. The result of such a scan is passed back to the ACL,
 which can then use it to decide what to do with the message.
-
-When a message has been received, either from a remote host or from the local
+.next
+When a message has been received, either from a remote host or from the local
 host, but before the final acknowledgement has been sent, a locally supplied C
-function called 'local_scan()' can be run to inspect the message and decide
-whether to accept it or not (see chapter <<CHAPlocalscan>>). If the message is
-accepted, the list of recipients can be modified by the function.
-
-- Using the 'local_scan()' mechanism is another way of calling external
-scanner software. The %SA-Exim% add-on package works this way. It does not
-require Exim to be compiled with the content-scanning extension.
-
-After a message has been accepted, a further checking mechanism is available in
-the form of the 'system filter' (see chapter <<CHAPsystemfilter>>). This runs
-at the start of every delivery process.
-
-
-
-User filters
-~~~~~~~~~~~~
-cindex:[filter,introduction]
-cindex:[Sieve filter]
+function called &[local_scan()]& can be run to inspect the message and decide
+whether to accept it or not (see chapter &<<CHAPlocalscan>>&). If the message
+is accepted, the list of recipients can be modified by the function.
+.next
+Using the &[local_scan()]& mechanism is another way of calling external scanner
+software. The &%SA-Exim%& add-on package works this way. It does not require
+Exim to be compiled with the content-scanning extension.
+.next
+After a message has been accepted, a further checking mechanism is available in
+the form of the &'system filter'& (see chapter &<<CHAPsystemfilter>>&). This
+runs at the start of every delivery process.
+.endlist
+
+
+
+.section "User filters"
+.cindex "filter" "introduction"
+.cindex "Sieve filter"
 In a conventional Exim configuration, users are able to run private filters by
-setting up appropriate _.forward_ files in their home directories. See
-chapter <<CHAPredirect>> (about the ^redirect^ router) for the configuration
-needed to support this, and the separate document entitled 'Exim's interfaces
-to mail filtering' for user details. Two different kinds of filtering are
-available:
-
-- Sieve filters are written in the standard filtering language that is defined
+setting up appropriate &_.forward_& files in their home directories. See
+chapter &<<CHAPredirect>>& (about the &(redirect)& router) for the
+configuration needed to support this, and the separate document entitled
+&'Exim's interfaces to mail filtering'& for user details. Two different kinds
+of filtering are available:
+
+.ilist
+Sieve filters are written in the standard filtering language that is defined
 by RFC 3028.
-
-Exim filters are written in a syntax that is unique to Exim, but which is more
+.next
+Exim filters are written in a syntax that is unique to Exim, but which is more
 powerful than Sieve, which it pre-dates.
+.endlist
 
 User filters are run as part of the routing process, described below.
 
 
 
-[[SECTmessiden]]
-Message identification
-~~~~~~~~~~~~~~~~~~~~~~
-cindex:[message ids, details of format]
-cindex:[format,of message id]
-cindex:[id of message]
-cindex:[base62]
-cindex:[base36]
-cindex:[Darwin]
-cindex:[Cygwin]
-Every message handled by Exim is given a 'message id' which is sixteen
+.section "Message identification" "SECTmessiden"
+.cindex "message ids" "details of format"
+.cindex "format" "of message id"
+.cindex "id of message"
+.cindex "base62"
+.cindex "base36"
+.cindex "Darwin"
+.cindex "Cygwin"
+Every message handled by Exim is given a &'message id'& which is sixteen
 characters long. It is divided into three parts, separated by hyphens, for
-example `16VDhn-0001bo-D3`. Each part is a sequence of letters and digits,
+example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits,
 normally encoding numbers in base 62. However, in the Darwin operating
 system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
 (avoiding the use of lower case letters) is used instead, because the message
 id is used to construct file names, and the names of files in those systems are
 not always case-sensitive.
 
-cindex:[pid (process id),re-use of]
+.cindex "pid (process id)" "re-use of"
 The detail of the contents of the message id have changed as Exim has evolved.
 Earlier versions relied on the operating system not re-using a process id (pid)
 within one second. On modern operating systems, this assumption can no longer
@@ -917,25 +912,28 @@ be made, so the algorithm had to be changed. To retain backward compatibility,
 the format of the message id was retained, which is why the following rules are
 somewhat eccentric:
 
-- The first six characters of the message id are the time at which the message
+.ilist
+The first six characters of the message id are the time at which the message
 started to be received, to a granularity of one second. That is, this field
 contains the number of seconds since the start of the epoch (the normal Unix
 way of representing the date and time of day).
-
-After the first hyphen, the next six characters are the id of the process that
+.next
+After the first hyphen, the next six characters are the id of the process that
 received the message.
-
-There are two different possibilities for the final two characters:
-
-. cindex:[%localhost_number%]
-If %localhost_number% is not set, this value is the fractional part of the
+.next
+There are two different possibilities for the final two characters:
+.olist
+.cindex "&%localhost_number%&"
+If &%localhost_number%& is not set, this value is the fractional part of the
 time of reception, normally in units of 1/2000 of a second, but for systems
 that must use base 36 instead of base 62 (because of case-insensitive file
 systems), the units are 1/1000 of a second.
-
-. If %localhost_number% is set, it is multiplied by 200 (100) and added to
+.next
+If &%localhost_number%& is set, it is multiplied by 200 (100) and added to
 the fractional part of the time, which in this case is in units of 1/200
 (1/100) of a second.
+.endlist
+.endlist
 
 After a message has been received, Exim waits for the clock to tick at the
 appropriate resolution before proceeding, so that if another message is
@@ -944,50 +942,51 @@ pid, it is guaranteed that the time will be different. In most cases, the clock
 will already have ticked while the message was being received.
 
 
-Receiving mail
-~~~~~~~~~~~~~~
-cindex:[receiving mail]
-cindex:[message,reception]
+.section "Receiving mail"
+.cindex "receiving mail"
+.cindex "message" "reception"
 The only way Exim can receive mail from another host is using SMTP over
 TCP/IP, in which case the sender and recipient addresses are transferred using
 SMTP commands. However, from a locally running process (such as a user's MUA),
 there are several possibilities:
 
-- If the process runs Exim with the %-bm% option, the message is read
+.ilist
+If the process runs Exim with the &%-bm%& option, the message is read
 non-interactively (usually via a pipe), with the recipients taken from the
-command line, or from the body of the message if %-t% is also used.
-
-- If the process runs Exim with the %-bS% option, the message is also read
+command line, or from the body of the message if &%-t%& is also used.
+.next
+If the process runs Exim with the &%-bS%& option, the message is also read
 non-interactively, but in this case the recipients are listed at the start of
 the message in a series of SMTP RCPT commands, terminated by a DATA
-command. This is so-called ``batch SMTP'' format,
+command. This is so-called &"batch SMTP"& format,
 but it isn't really SMTP. The SMTP commands are just another way of passing
 envelope addresses in a non-interactive submission.
-
-- If the process runs Exim with the %-bs% option, the message is read
+.next
+If the process runs Exim with the &%-bs%& option, the message is read
 interactively, using the SMTP protocol. A two-way pipe is normally used for
 passing data between the local process and the Exim process.
-This is ``real'' SMTP and is handled in the same way as SMTP over TCP/IP. For
+This is &"real"& SMTP and is handled in the same way as SMTP over TCP/IP. For
 example, the ACLs for SMTP commands are used for this form of submission.
-
-A local process may also make a TCP/IP call to the host's loopback address
+.next
+A local process may also make a TCP/IP call to the host's loopback address
 (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
 does not treat the loopback address specially. It treats all such connections
 in the same way as connections from other hosts.
+.endlist
 
 
-cindex:[message sender, constructed by Exim]
-cindex:[sender,constructed by Exim]
+.cindex "message sender" "constructed by Exim"
+.cindex "sender" "constructed by Exim"
 In the three cases that do not involve TCP/IP, the sender address is
 constructed from the login name of the user that called Exim and a default
-qualification domain (which can be set by the %qualify_domain% configuration
+qualification domain (which can be set by the &%qualify_domain%& configuration
 option). For local or batch SMTP, a sender address that is passed using the
 SMTP MAIL command is ignored. However, the system administrator may allow
-certain users (``trusted users'') to specify a different sender address
+certain users (&"trusted users"&) to specify a different sender address
 unconditionally, or all users to specify certain forms of different sender
-address. The %-f% option or the SMTP MAIL command is used to specify these
-different addresses. See section <<SECTtrustedadmin>> for details of trusted
-users, and the %untrusted_set_sender% option for a way of allowing untrusted
+address. The &%-f%& option or the SMTP MAIL command is used to specify these
+different addresses. See section &<<SECTtrustedadmin>>& for details of trusted
+users, and the &%untrusted_set_sender%& option for a way of allowing untrusted
 users to change sender addresses.
 
 Messages received by either of the non-interactive mechanisms are subject to
@@ -995,8 +994,8 @@ checking by the non-SMTP ACL, if one is defined. Messages received using SMTP
 (either over TCP/IP, or interacting with a local process) can be checked by a
 number of ACLs that operate at different times during the SMTP session. Either
 individual recipients, or the entire message, can be rejected if local policy
-requirements are not met. The 'local_scan()' function (see chapter
-<<CHAPlocalscan>>) is run for all incoming messages.
+requirements are not met. The &[local_scan()]& function (see chapter
+&<<CHAPlocalscan>>&) is run for all incoming messages.
 
 Exim can be configured not to start a delivery process when a message is
 received; this can be unconditional, or depend on the number of incoming SMTP
@@ -1009,21 +1008,20 @@ message is received.
 
 
 
-Handling an incoming message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[spool directory,files that hold a message]
-cindex:[file,how a message is held]
+.section "Handling an incoming message"
+.cindex "spool directory" "files that hold a message"
+.cindex "file" "how a message is held"
 When Exim accepts a message, it writes two files in its spool directory. The
 first contains the envelope information, the current status of the message, and
 the header lines, and the second contains the body of the message. The names of
-the two spool files consist of the message id, followed by `-H` for the
-file containing the envelope and header, and `-D` for the data file.
+the two spool files consist of the message id, followed by &`-H`& for the
+file containing the envelope and header, and &`-D`& for the data file.
 
-cindex:[spool directory,_input_ sub-directory]
+.cindex "spool directory" "&_input_& sub-directory"
 By default all these message files are held in a single directory called
-_input_ inside the general Exim spool directory. Some operating systems do
+&_input_& inside the general Exim spool directory. Some operating systems do
 not perform very well if the number of files in a directory gets very large; to
-improve performance in such cases, the %split_spool_directory% option can be
+improve performance in such cases, the &%split_spool_directory%& option can be
 used. This causes Exim to split up the input files into 62 sub-directories
 whose names are single letters or digits.
 
@@ -1031,11 +1029,11 @@ The envelope information consists of the address of the message's sender and
 the addresses of the recipients. This information is entirely separate from
 any addresses contained in the header lines. The status of the message includes
 a list of recipients who have already received the message. The format of the
-first spool file is described in chapter <<CHAPspool>>.
+first spool file is described in chapter &<<CHAPspool>>&.
 
-cindex:[rewriting,addresses]
+.cindex "rewriting" "addresses"
 Address rewriting that is specified in the rewrite section of the configuration
-(see chapter <<CHAPrewrite>>) is done once and for all on incoming addresses,
+(see chapter &<<CHAPrewrite>>&) is done once and for all on incoming addresses,
 both in the header lines and the envelope, at the time the message is accepted.
 If during the course of delivery additional addresses are generated (for
 example, via aliasing), these new addresses are rewritten as soon as they are
@@ -1043,53 +1041,55 @@ generated. At the time a message is actually delivered (transported) further
 rewriting can take place; because this is a transport option, it can be
 different for different forms of delivery. It is also possible to specify the
 addition or removal of certain header lines at the time the message is
-delivered (see chapters <<CHAProutergeneric>> and <<CHAPtransportgeneric>>).
+delivered (see chapters &<<CHAProutergeneric>>& and
+&<<CHAPtransportgeneric>>&).
 
 
 
-Life of a message
-~~~~~~~~~~~~~~~~~
-cindex:[message,life of]
-cindex:[message,frozen]
+.section "Life of a message"
+.cindex "message" "life of"
+.cindex "message" "frozen"
 A message remains in the spool directory until it is completely delivered to
 its recipients or to an error address, or until it is deleted by an
 administrator or by the user who originally created it. In cases when delivery
-cannot proceed -- for example, when a message can neither be delivered to its
-recipients nor returned to its sender, the message is marked ``frozen'' on the
+cannot proceed &-- for example, when a message can neither be delivered to its
+recipients nor returned to its sender, the message is marked &"frozen"& on the
 spool, and no more deliveries are attempted.
 
-cindex:[frozen messages,thawing]
-cindex:[message,thawing frozen]
-An administrator can ``thaw'' such messages when the problem has been corrected,
-and can also freeze individual messages by hand if necessary. In addition, an
-administrator can force a delivery error, causing a bounce message to be sent.
-
-[revisionflag="changed"]
-cindex:[%timeout_frozen_after%]
-cindex:[%ignore_bounce_errors_after%]
-There are options called %ignore_bounce_errors_after% and
-%timeout_frozen_after%, which discard frozen messages after a certain time.
+.cindex "frozen messages" "thawing"
+.cindex "message" "thawing frozen"
+An administrator can &"thaw"& such messages when the problem has been
+corrected, and can also freeze individual messages by hand if necessary. In
+addition, an administrator can force a delivery error, causing a bounce message
+to be sent.
+
+.new
+.cindex "&%timeout_frozen_after%&"
+.cindex "&%ignore_bounce_errors_after%&"
+There are options called &%ignore_bounce_errors_after%& and
+&%timeout_frozen_after%&, which discard frozen messages after a certain time.
 The first applies only to frozen bounces, the second to any frozen messages.
+.wen
 
-cindex:[message,log file for]
-cindex:[log,file for each message]
+.cindex "message" "log file for"
+.cindex "log" "file for each message"
 While Exim is working on a message, it writes information about each delivery
 attempt to its main log file. This includes successful, unsuccessful, and
-delayed deliveries for each recipient (see chapter <<CHAPlog>>). The log lines
-are also written to a separate 'message log' file for each message. These
-logs are solely for the benefit of the administrator, and are normally deleted
-along with the spool files when processing of a message is complete.
+delayed deliveries for each recipient (see chapter &<<CHAPlog>>&). The log
+lines are also written to a separate &'message log'& file for each message.
+These logs are solely for the benefit of the administrator, and are normally
+deleted along with the spool files when processing of a message is complete.
 The use of individual message logs can be disabled by setting
-%no_message_logs%; this might give an improvement in performance on very
-busy systems.
+&%no_message_logs%&; this might give an improvement in performance on very busy
+systems.
 
-cindex:[journal file]
-cindex:[file,journal]
+.cindex "journal file"
+.cindex "file" "journal"
 All the information Exim itself needs to set up a delivery is kept in the first
 spool file, along with the header lines. When a successful delivery occurs, the
 address is immediately written at the end of a journal file, whose name is the
-message id followed by `-J`. At the end of a delivery run, if there are some
-addresses left to be tried again later, the first spool file (the `-H` file)
+message id followed by &`-J`&. At the end of a delivery run, if there are some
+addresses left to be tried again later, the first spool file (the &`-H`& file)
 is updated to indicate which these are, and the journal file is then deleted.
 Updating the spool file is done by writing a new file and renaming it, to
 minimize the possibility of data loss.
@@ -1102,42 +1102,40 @@ deliveries caused by crashes.
 
 
 
-[[SECTprocaddress]]
-Processing an address for delivery
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[drivers,definition of]
-cindex:[router,definition of]
-cindex:[transport,definition of]
-The main delivery processing elements of Exim are called 'routers' and
-'transports', and collectively these are known as 'drivers'. Code for a
+.section "Processing an address for delivery" "SECTprocaddress"
+.cindex "drivers" "definition of"
+.cindex "router" "definition of"
+.cindex "transport" "definition of"
+The main delivery processing elements of Exim are called &'routers'& and
+&'transports'&, and collectively these are known as &'drivers'&. Code for a
 number of them is provided in the source distribution, and compile-time options
 specify which ones are included in the binary. Run time options specify which
 ones are actually used for delivering messages.
 
-cindex:[drivers,instance definition]
-Each driver that is specified in the run time configuration is an 'instance'
+.cindex "drivers" "instance definition"
+Each driver that is specified in the run time configuration is an &'instance'&
 of that particular driver type. Multiple instances are allowed; for example,
-you can set up several different ^smtp^ transports, each with different
+you can set up several different &(smtp)& transports, each with different
 option values that might specify different ports or different timeouts. Each
 instance has its own identifying name. In what follows we will normally use the
 instance name when discussing one particular instance (that is, one specific
 configuration of the driver), and the generic driver name when discussing
 the driver's features in general.
 
-A 'router' is a driver that operates on an address, either determining how
+A &'router'& is a driver that operates on an address, either determining how
 its delivery should happen, by assigning it to a specific transport, or
 converting the address into one or more new addresses (for example, via an
 alias file). A router may also explicitly choose to fail an address, causing it
 to be bounced.
 
-A 'transport' is a driver that transmits a copy of the message from Exim's
-spool to some destination. There are two kinds of transport: for a 'local'
+A &'transport'& is a driver that transmits a copy of the message from Exim's
+spool to some destination. There are two kinds of transport: for a &'local'&
 transport, the destination is a file or a pipe on the local host, whereas for a
-'remote' transport the destination is some other host. A message is passed
+&'remote'& transport the destination is some other host. A message is passed
 to a specific transport as a result of successful routing. If a message has
 several recipients, it may be passed to a number of different transports.
 
-cindex:[preconditions,definition of]
+.cindex "preconditions" "definition of"
 An address is processed by passing it to each configured router instance in
 turn, subject to certain preconditions, until a router accepts the address or
 specifies that it should be bounced. We will describe this process in more
@@ -1153,14 +1151,14 @@ The first router that is specified in a configuration is often one that handles
 addresses in domains that are not recognized specially by the local host. These
 are typically addresses for arbitrary domains on the Internet. A precondition
 is set up which looks for the special domains known to the host (for example,
-its own domain name), and the router is run for addresses that do 'not'
+its own domain name), and the router is run for addresses that do &'not'&
 match. Typically, this is a router that looks up domains in the DNS in order to
 find the hosts to which this address routes. If it succeeds, the address is
 assigned to a suitable SMTP transport; if it does not succeed, the router is
 configured to fail the address.
 
 The second router is reached only when the domain is recognized as one that
-``belongs'' to the local host. This router does redirection -- also known as
+&"belongs"& to the local host. This router does redirection &-- also known as
 aliasing and forwarding. When it generates one or more new addresses from the
 original, each of them is routed independently from the start. Otherwise, the
 router may cause an address to fail, or it may simply decline to handle the
@@ -1175,231 +1173,229 @@ the address is bounced.
 
 
 
-Processing an address for verification
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[router,for verification]
-cindex:[verifying address, overview]
+.section "Processing an address for verification"
+.cindex "router" "for verification"
+.cindex "verifying address" "overview"
 As well as being used to decide how to deliver to an address, Exim's routers
-are also used for 'address verification'. Verification can be requested as
+are also used for &'address verification'&. Verification can be requested as
 one of the checks to be performed in an ACL for incoming messages, on both
-sender and recipient addresses, and it can be tested using the %-bv% and
-%-bvs% command line options.
+sender and recipient addresses, and it can be tested using the &%-bv%& and
+&%-bvs%& command line options.
 
-When an address is being verified, the routers are run in ``verify mode''. This
+When an address is being verified, the routers are run in &"verify mode"&. This
 does not affect the way the routers work, but it is a state that can be
 detected. By this means, a router can be skipped or made to behave differently
 when verifying. A common example is a configuration in which the first router
 sends all messages to a message-scanning program, unless they have been
 previously scanned. Thus, the first router accepts all addresses without any
-checking, making it useless for verifying. Normally, the %no_verify% option
+checking, making it useless for verifying. Normally, the &%no_verify%& option
 would be set for such a router, causing it to be skipped in verify mode.
 
 
 
 
-[[SECTrunindrou]]
-Running an individual router
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[router,running details]
-cindex:[preconditions,checking]
-cindex:[router,result of running]
+.section "Running an individual router" "SECTrunindrou"
+.cindex "router" "running details"
+.cindex "preconditions" "checking"
+.cindex "router" "result of running"
 As explained in the example above, a number of preconditions are checked before
 running a router. If any are not met, the router is skipped, and the address is
-passed to the next router. When all the preconditions on a router 'are' met,
+passed to the next router. When all the preconditions on a router &'are'& met,
 the router is run. What happens next depends on the outcome, which is one of
 the following:
 
-- 'accept': The router accepts the address, and either assigns it to a
-transport, or generates one or more ``child'' addresses. Processing the original
-address ceases,
-cindex:[%unseen% option]
-unless the %unseen% option is set on the router. This option
+.ilist
+&'accept'&: The router accepts the address, and either assigns it to a
+transport, or generates one or more &"child"& addresses. Processing the
+original address ceases,
+.cindex "&%unseen%& option"
+unless the &%unseen%& option is set on the router. This option
 can be used to set up multiple deliveries with different routing (for example,
-for keeping archive copies of messages). When %unseen% is set, the address is
-passed to the next router. Normally, however, an 'accept' return marks the
+for keeping archive copies of messages). When &%unseen%& is set, the address is
+passed to the next router. Normally, however, an &'accept'& return marks the
 end of routing.
-+
+
 Any child addresses generated by the router are processed independently,
 starting with the first router by default. It is possible to change this by
-setting the %redirect_router% option to specify which router to start at for
-child addresses. Unlike %pass_router% (see below) the router specified by
-%redirect_router% may be anywhere in the router configuration.
-
-- 'pass': The router recognizes the address, but cannot handle it itself. It
+setting the &%redirect_router%& option to specify which router to start at for
+child addresses. Unlike &%pass_router%& (see below) the router specified by
+&%redirect_router%& may be anywhere in the router configuration.
+.next
+&'pass'&: The router recognizes the address, but cannot handle it itself. It
 requests that the address be passed to another router. By default the address
 is passed to the next router, but this can be changed by setting the
-%pass_router% option. However, (unlike %redirect_router%) the named router
+&%pass_router%& option. However, (unlike &%redirect_router%&) the named router
 must be below the current router (to avoid loops).
-
-- 'decline': The router declines to accept the address because it does not
+.next
+&'decline'&: The router declines to accept the address because it does not
 recognize it at all. By default, the address is passed to the next router, but
-this can be prevented by setting the %no_more% option. When %no_more% is set,
-all the remaining routers are skipped. In effect, %no_more% converts 'decline'
-into 'fail'.
-
-- 'fail': The router determines that the address should fail, and queues it for
+this can be prevented by setting the &%no_more%& option. When &%no_more%& is
+set, all the remaining routers are skipped. In effect, &%no_more%& converts
+&'decline'& into &'fail'&.
+.next
+&'fail'&: The router determines that the address should fail, and queues it for
 the generation of a bounce message. There is no further processing of the
-original address unless %unseen% is set on the router.
-
-- 'defer': The router cannot handle the address at the present time. (A
+original address unless &%unseen%& is set on the router.
+.next
+&'defer'&: The router cannot handle the address at the present time. (A
 database may be offline, or a DNS lookup may have timed out.) No further
 processing of the address happens in this delivery attempt. It is tried again
 next time the message is considered for delivery.
-
-- 'error': There is some error in the router (for example, a syntax error in
+.next
+&'error'&: There is some error in the router (for example, a syntax error in
 its configuration). The action is as for defer.
+.endlist
 
 If an address reaches the end of the routers without having been accepted by
 any of them, it is bounced as unrouteable. The default error message in this
-situation is ``unrouteable address'', but you can set your own message by
-making use of the %cannot_route_message% option. This can be set for any
-router; the value from the last router that ``saw'' the address is used.
+situation is &"unrouteable address"&, but you can set your own message by
+making use of the &%cannot_route_message%& option. This can be set for any
+router; the value from the last router that &"saw"& the address is used.
 
 Sometimes while routing you want to fail a delivery when some conditions are
 met but others are not, instead of passing the address on for further routing.
 You can do this by having a second router that explicitly fails the delivery
-when the relevant conditions are met. The ^redirect^ router has a ``fail''
+when the relevant conditions are met. The &(redirect)& router has a &"fail"&
 facility for this purpose.
 
 
-Duplicate addresses
-~~~~~~~~~~~~~~~~~~~
-
-[revisionflag="changed"]
-cindex:[case of local parts]
-cindex:[address duplicate, discarding]
+.section "Duplicate addresses"
+.new
+.cindex "case of local parts"
+.cindex "address duplicate" "discarding"
 Once routing is complete, Exim scans the addresses that are assigned to local
 and remote transports, and discards any duplicates that it finds. During this
 check, local parts are treated as case-sensitive.
+.wen
 
 
-
-[[SECTrouprecon]]
-Router preconditions
-~~~~~~~~~~~~~~~~~~~~
-cindex:[router preconditions, order of processing]
-cindex:[preconditions,order of processing]
+.section "Router preconditions" "SECTrouprecon"
+.cindex "router preconditions" "order of processing"
+.cindex "preconditions" "order of processing"
 The preconditions that are tested for each router are listed below, in the
 order in which they are tested. The individual configuration options are
-described in more detail in chapter <<CHAProutergeneric>>.
+described in more detail in chapter &<<CHAProutergeneric>>&.
 
-- The %local_part_prefix% and %local_part_suffix% options can specify that
+.ilist
+The &%local_part_prefix%& and &%local_part_suffix%& options can specify that
 the local parts handled by the router may or must have certain prefixes and/or
 suffixes. If a mandatory affix (prefix or suffix) is not present, the router is
 skipped. These conditions are tested first. When an affix is present, it is
 removed from the local part before further processing, including the evaluation
 of any other conditions.
-
-Routers can be designated for use only when not verifying an address, that is,
+.next
+Routers can be designated for use only when not verifying an address, that is,
 only when routing it for delivery (or testing its delivery routing). If the
-%verify% option is set false, the router is skipped when Exim is verifying an
+&%verify%& option is set false, the router is skipped when Exim is verifying an
 address.
-Setting the %verify% option actually sets two options, %verify_sender% and
-%verify_recipient%, which independently control the use of the router for
+Setting the &%verify%& option actually sets two options, &%verify_sender%& and
+&%verify_recipient%&, which independently control the use of the router for
 sender and recipient verification. You can set these options directly if
 you want a router to be used for only one type of verification.
-
-- If the %address_test% option is set false, the router is skipped when Exim is
-run with the %-bt% option to test an address routing. This can be helpful when
-the first router sends all new messages to a scanner of some sort; it makes it
-possible to use %-bt% to test subsequent delivery routing without having to
-simulate the effect of the scanner.
-
-Routers can be designated for use only when verifying an address, as
-opposed to routing it for delivery. The %verify_only% option controls this.
-
-Individual routers can be explicitly skipped when running the routers to
-check an address given in the SMTP EXPN command (see the %expn% option).
-
-- If the %domains% option is set, the domain of the address must be in the set
+.next
+If the &%address_test%& option is set false, the router is skipped when Exim is
+run with the &%-bt%& option to test an address routing. This can be helpful
+when the first router sends all new messages to a scanner of some sort; it
+makes it possible to use &%-bt%& to test subsequent delivery routing without
+having to simulate the effect of the scanner.
+.next
+Routers can be designated for use only when verifying an address, as
+opposed to routing it for delivery. The &%verify_only%& option controls this.
+.next
+Individual routers can be explicitly skipped when running the routers to
+check an address given in the SMTP EXPN command (see the &%expn%& option).
+.next
+If the &%domains%& option is set, the domain of the address must be in the set
 of domains that it defines.
-
-- cindex:[$local_part_prefix$]
-cindex:[$local_part$]
-cindex:[$local_part_suffix$]
-If the %local_parts% option is set, the local part of the address must be in
-the set of local parts that it defines. If %local_part_prefix% or
-%local_part_suffix% is in use, the prefix or suffix is removed from the local
+.next
+.cindex "&$local_part_prefix$&"
+.cindex "&$local_part$&"
+.cindex "&$local_part_suffix$&"
+If the &%local_parts%& option is set, the local part of the address must be in
+the set of local parts that it defines. If &%local_part_prefix%& or
+&%local_part_suffix%& is in use, the prefix or suffix is removed from the local
 part before this check. If you want to do precondition tests on local parts
-that include affixes, you can do so by using a %condition% option (see below)
-that uses the variables $local_part$, $local_part_prefix$, and
-$local_part_suffix$ as necessary.
-
-- cindex:[$local_user_uid$]
-cindex:[$local_user_gid$]
-cindex:[$home$]
-If the %check_local_user% option is set, the local part must be the name of
+that include affixes, you can do so by using a &%condition%& option (see below)
+that uses the variables &$local_part$&, &$local_part_prefix$&, and
+&$local_part_suffix$& as necessary.
+.next
+.cindex "&$local_user_uid$&"
+.cindex "&$local_user_gid$&"
+.cindex "&$home$&"
+If the &%check_local_user%& option is set, the local part must be the name of
 an account on the local host. If this check succeeds, the uid and gid of the
-local user are placed in $local_user_uid$ and $local_user_gid$ and the user's
-home directory is placed in $home$; these values can be used in the remaining
-preconditions.
-
-- If the %router_home_directory% option is set, it is expanded at this point,
-because it overrides the value of $home$. If this expansion were left till
-later, the value of $home$ as set by %check_local_user% would be used in
-subsequent tests. Having two different values of $home$ in the same router
+local user are placed in &$local_user_uid$& and &$local_user_gid$& and the
+user's home directory is placed in &$home$&; these values can be used in the
+remaining preconditions.
+.next
+If the &%router_home_directory%& option is set, it is expanded at this point,
+because it overrides the value of &$home$&. If this expansion were left till
+later, the value of &$home$& as set by &%check_local_user%& would be used in
+subsequent tests. Having two different values of &$home$& in the same router
 could lead to confusion.
-
-- If the %senders% option is set, the envelope sender address must be in the set
-of addresses that it defines.
-
-- If the %require_files% option is set, the existence or non-existence of
+.next
+If the &%senders%& option is set, the envelope sender address must be in the
+set of addresses that it defines.
+.next
+If the &%require_files%& option is set, the existence or non-existence of
 specified files is tested.
+.next
+.cindex "customizing" "precondition"
+If the &%condition%& option is set, it is evaluated and tested. This option
+uses an expanded string to allow you to set up your own custom preconditions.
+Expanded strings are described in chapter &<<CHAPexpand>>&.
+.endlist
 
-- cindex:[customizing,precondition]
-If the %condition% option is set, it is evaluated and tested. This option uses
-an expanded string to allow you to set up your own custom preconditions.
-Expanded strings are described in chapter <<CHAPexpand>>.
 
-
-Note that %require_files% comes near the end of the list, so you cannot use it
-to check for the existence of a file in which to lookup up a domain, local
+Note that &%require_files%& comes near the end of the list, so you cannot use
+it to check for the existence of a file in which to lookup up a domain, local
 part, or sender. However, as these options are all expanded, you can use the
-%exists% expansion condition to make such tests within each condition. The
-%require_files% option is intended for checking files that the router may be
+&%exists%& expansion condition to make such tests within each condition. The
+&%require_files%& option is intended for checking files that the router may be
 going to use internally, or which are needed by a specific transport (for
-example, _.procmailrc_).
+example, &_.procmailrc_&).
 
 
 
-Delivery in detail
-~~~~~~~~~~~~~~~~~~
-cindex:[delivery,in detail]
+.section "Delivery in detail"
+.cindex "delivery" "in detail"
 When a message is to be delivered, the sequence of events is as follows:
 
-- If a system-wide filter file is specified, the message is passed to it. The
+.ilist
+If a system-wide filter file is specified, the message is passed to it. The
 filter may add recipients to the message, replace the recipients, discard the
 message, cause a new message to be generated, or cause the message delivery to
 fail. The format of the system filter file is the same as for Exim user filter
-files, described in the separate document entitled
-'Exim's interfaces to mail filtering'.
-cindex:[Sieve filter,not available for system filter]
-(*Note*: Sieve cannot be used for system filter files.)
-+
-Some additional features are available in system filters -- see chapter
-<<CHAPsystemfilter>> for details. Note that a message is passed to the system
+files, described in the separate document entitled &'Exim's interfaces to mail
+filtering'&.
+.cindex "Sieve filter" "not available for system filter"
+(&*Note*&: Sieve cannot be used for system filter files.)
+
+Some additional features are available in system filters &-- see chapter
+&<<CHAPsystemfilter>>& for details. Note that a message is passed to the system
 filter only once per delivery attempt, however many recipients it has. However,
 if there are several delivery attempts because one or more addresses could not
 be immediately delivered, the system filter is run each time. The filter
-condition %first_delivery% can be used to detect the first run of the system
+condition &%first_delivery%& can be used to detect the first run of the system
 filter.
-
-- Each recipient address is offered to each configured router in turn, subject
-to its preconditions, until one is able to handle it. If no router can handle
-the address, that is, if they all decline, the address is failed. Because
-routers can be targeted at particular domains, several locally handled domains
-can be processed entirely independently of each other.
-
-- cindex:[routing,loops in]
-cindex:[loop,while routing]
-A router that accepts an address may assign it to a local or a remote transport. However, the transport is not run at this time. Instead, the address is
-placed on a list for the particular transport, which will be run later.
+.next
+Each recipient address is offered to each configured router in turn, subject to
+its preconditions, until one is able to handle it. If no router can handle the
+address, that is, if they all decline, the address is failed. Because routers
+can be targeted at particular domains, several locally handled domains can be
+processed entirely independently of each other.
+.next
+.cindex "routing" "loops in"
+.cindex "loop" "while routing"
+A router that accepts an address may assign it to a local or a remote
+transport. However, the transport is not run at this time. Instead, the address
+is placed on a list for the particular transport, which will be run later.
 Alternatively, the router may generate one or more new addresses (typically
 from alias, forward, or filter files). New addresses are fed back into this
 process from the top, but in order to avoid loops, a router ignores any address
 which has an identically-named ancestor that was processed by itself.
-
-When all the routing has been done, addresses that have been successfully
+.next
+When all the routing has been done, addresses that have been successfully
 handled are passed to their assigned transports. When local transports are
 doing real local deliveries, they handle only one address at a time, but if a
 local transport is being used as a pseudo-remote transport (for example, to
@@ -1407,17 +1403,17 @@ collect batched SMTP messages for transmission by some other means) multiple
 addresses can be handled. Remote transports can always handle more than one
 address at a time, but can be configured not to do so, or to restrict multiple
 addresses to the same domain.
-
-Each local delivery to a file or a pipe runs in a separate process under a
+.next
+Each local delivery to a file or a pipe runs in a separate process under a
 non-privileged uid, and these deliveries are run one at a time. Remote
 deliveries also run in separate processes, normally under a uid that is private
-to Exim (``the Exim user''), but in this case, several remote deliveries can be
+to Exim (&"the Exim user"&), but in this case, several remote deliveries can be
 run in parallel. The maximum number of simultaneous remote deliveries for any
-one message is set by the %remote_max_parallel% option.
+one message is set by the &%remote_max_parallel%& option.
 The order in which deliveries are done is not defined, except that all local
 deliveries happen before any remote deliveries.
-
-- cindex:[queue runner]
+.next
+.cindex "queue runner"
 When it encounters a local delivery during a queue run, Exim checks its retry
 database to see if there has been a previous temporary delivery failure for the
 address before running the local transport. If there was a previous failure,
@@ -1427,40 +1423,40 @@ queue run. Local deliveries are always attempted when delivery immediately
 follows message reception, even if retry times are set for them. This makes for
 better behaviour if one particular message is causing problems (for example,
 causing quota overflow, or provoking an error in a filter file).
-
-- cindex:[delivery,retry in remote transports]
+.next
+.cindex "delivery" "retry in remote transports"
 Remote transports do their own retry handling, since an address may be
 deliverable to one of a number of hosts, each of which may have a different
 retry time. If there have been previous temporary failures and no host has
 reached its retry time, no delivery is attempted, whether in a queue run or
-not. See chapter <<CHAPretry>> for details of retry strategies.
-
-If there were any permanent errors, a bounce message is returned to an
+not. See chapter &<<CHAPretry>>& for details of retry strategies.
+.next
+If there were any permanent errors, a bounce message is returned to an
 appropriate address (the sender in the common case), with details of the error
 for each failing address. Exim can be configured to send copies of bounce
 messages to other addresses.
-
-- cindex:[delivery,deferral]
+.next
+.cindex "delivery" "deferral"
 If one or more addresses suffered a temporary failure, the message is left on
 the queue, to be tried again later. Delivery of these addresses is said to be
-'deferred'.
-
-When all the recipient addresses have either been delivered or bounced,
+&'deferred'&.
+.next
+When all the recipient addresses have either been delivered or bounced,
 handling of the message is complete. The spool files and message log are
 deleted, though the message log can optionally be preserved if required.
+.endlist
 
 
 
 
-Retry mechanism
-~~~~~~~~~~~~~~~
-cindex:[delivery,retry mechanism]
-cindex:[retry,description of mechanism]
-cindex:[queue runner]
+.section "Retry mechanism"
+.cindex "delivery" "retry mechanism"
+.cindex "retry" "description of mechanism"
+.cindex "queue runner"
 Exim's mechanism for retrying messages that fail to get delivered at the first
 attempt is the queue runner process. You must either run an Exim daemon that
-uses the %-q% option with a time interval to start queue runners at regular
-intervals, or use some other means (such as 'cron') to start them. If you do
+uses the &%-q%& option with a time interval to start queue runners at regular
+intervals, or use some other means (such as &'cron'&) to start them. If you do
 not arrange for queue runners to be run, messages that fail temporarily at the
 first attempt will remain on your queue for ever. A queue runner process works
 its way through the queue, one message at a time, trying each delivery that has
@@ -1468,17 +1464,16 @@ passed its retry time.
 You can run several queue runners at once.
 
 Exim uses a set of configured rules to determine when next to retry the failing
-address (see chapter <<CHAPretry>>). These rules also specify when Exim should
-give up trying to deliver to the address, at which point it generates a bounce
-message. If no retry rules are set for a particular host, address, and error
-combination, no retries are attempted, and temporary errors are treated as
-permanent.
+address (see chapter &<<CHAPretry>>&). These rules also specify when Exim
+should give up trying to deliver to the address, at which point it generates a
+bounce message. If no retry rules are set for a particular host, address, and
+error combination, no retries are attempted, and temporary errors are treated
+as permanent.
 
 
 
-Temporary delivery failure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[delivery,temporary failure]
+.section "Temporary delivery failure"
+.cindex "delivery" "temporary failure"
 There are many reasons why a message may not be immediately deliverable to a
 particular address. Failure to connect to a remote machine (because it, or the
 connection to it, is down) is one of the most common. Temporary failures may be
@@ -1493,7 +1488,7 @@ waiting for it by the time it recovers, and sending them in a single SMTP
 connection is clearly beneficial. Whenever a delivery to a remote host is
 deferred,
 
-cindex:[hints database]
+.cindex "hints database"
 Exim makes a note in its hints database, and whenever a successful
 SMTP delivery has happened, it looks to see if any other messages are waiting
 for the same host. If any are found, they are sent over the same SMTP
@@ -1503,10 +1498,9 @@ one connection.
 
 
 
-Permanent delivery failure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[delivery,permanent failure]
-cindex:[bounce message,when generated]
+.section "Permanent delivery failure"
+.cindex "delivery" "permanent failure"
+.cindex "bounce message" "when generated"
 When a message cannot be delivered to some or all of its intended recipients, a
 bounce message is generated. Temporary delivery failures turn into permanent
 errors when their timeout expires. All the addresses that fail in a given
@@ -1514,120 +1508,110 @@ delivery attempt are listed in a single message. If the original message has
 many recipients, it is possible for some addresses to fail in one delivery
 attempt and others to fail subsequently, giving rise to more than one bounce
 message. The wording of bounce messages can be customized by the administrator.
-See chapter <<CHAPemsgcust>> for details.
+See chapter &<<CHAPemsgcust>>& for details.
 
-cindex:['X-Failed-Recipients:' header line]
-Bounce messages contain an 'X-Failed-Recipients:' header line that lists the
+.cindex "&'X-Failed-Recipients:'& header line"
+Bounce messages contain an &'X-Failed-Recipients:'& header line that lists the
 failed addresses, for the benefit of programs that try to analyse such messages
 automatically.
 
-cindex:[bounce message,recipient of]
+.cindex "bounce message" "recipient of"
 A bounce message is normally sent to the sender of the original message, as
 obtained from the message's envelope. For incoming SMTP messages, this is the
-address given in the MAIL command. However, when an address is
-expanded via a forward or alias file, an alternative address can be specified
-for delivery failures of the generated addresses. For a mailing list expansion
-(see section <<SECTmailinglists>>) it is common to direct bounce messages to the
-manager of the list.
-
+address given in the MAIL command. However, when an address is expanded via a
+forward or alias file, an alternative address can be specified for delivery
+failures of the generated addresses. For a mailing list expansion (see section
+&<<SECTmailinglists>>&) it is common to direct bounce messages to the manager
+of the list.
 
 
 
-Failures to deliver bounce messages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[bounce message,failure to deliver]
+.section "Failures to deliver bounce messages"
+.cindex "bounce message" "failure to deliver"
 If a bounce message (either locally generated or received from a remote host)
 itself suffers a permanent delivery failure, the message is left on the queue,
 but it is frozen, awaiting the attention of an administrator. There are options
 that can be used to make Exim discard such failed messages, or to keep them
-for only a short time (see %timeout_frozen_after% and
-%ignore_bounce_errors_after%).
+for only a short time (see &%timeout_frozen_after%& and
+&%ignore_bounce_errors_after%&).
 
 
 
 
 
-////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
+////////////////////////////////////////////////////////////////////////////
 
-Building and installing Exim
-----------------------------
+.chapter "Building and installing Exim"
+.cindex "building Exim"
 
-cindex:[building Exim]
-
-Unpacking
-~~~~~~~~~
+.section "Unpacking"
 Exim is distributed as a gzipped or bzipped tar file which, when upacked,
 creates a directory with the name of the current release (for example,
-_exim-{version}_) into which the following files are placed:
-
-[frame="none"]
-`--------------------`--------------------------------------------------------
-_ACKNOWLEDGMENTS_    contains some acknowledgments
-_CHANGES_            contains a reference to where changes are documented
-_LICENCE_            the GNU General Public Licence
-_Makefile_           top-level make file
-_NOTICE_             conditions for the use of Exim
-_README_             list of files, directories and simple build instructions
-------------------------------------------------------------------------------
-
-Other files whose names begin with _README_ may also be present. The
+&_exim-&version;_&) into which the following files are placed:
+
+.table2 140pt
+.row &_ACKNOWLEDGMENTS_& "contains some acknowledgments"
+.row &_CHANGES_&         "contains a reference to where changes are documented"
+.row &_LICENCE_&         "the GNU General Public Licence"
+.row &_Makefile_&        "top-level make file"
+.row &_NOTICE_&          "conditions for the use of Exim"
+.row &_README_&          "list of files, directories and simple build &&&
+                          instructions"
+.endtable
+
+Other files whose names begin with &_README_& may also be present. The
 following subdirectories are created:
 
-[frame="none"]
-`--------------------`------------------------------------------------
-_Local_              an empty directory for local configuration files
-_OS_                 OS-specific files
-_doc_                documentation files
-_exim_monitor_       source files for the Exim monitor
-_scripts_            scripts used in the build process
-_src_                remaining source files
-_util_               independent utilities
-----------------------------------------------------------------------
-
-The main utility programs are contained in the _src_ directory, and are built
-with the Exim binary. The _util_ directory contains a few optional scripts
+.table2 140pt
+.row &_Local_&           "an empty directory for local configuration files"
+.row &_OS_&              "OS-specific files"
+.row &_doc_&             "documentation files"
+.row &_exim_monitor_&    "source files for the Exim monitor"
+.row &_scripts_&         "scripts used in the build process"
+.row &_src_&             "remaining source files"
+.row &_util_&            "independent utilities"
+.endtable
+
+The main utility programs are contained in the &_src_& directory, and are built
+with the Exim binary. The &_util_& directory contains a few optional scripts
 that may be useful to some sites.
 
 
-Multiple machine architectures and operating systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[building Exim,multiple OS/architectures]
+.section "Multiple machine architectures and operating systems"
+.cindex "building Exim" "multiple OS/architectures"
 The building process for Exim is arranged to make it easy to build binaries for
 a number of different architectures and operating systems from the same set of
-source files. Compilation does not take place in the _src_ directory. Instead,
-a 'build directory' is created for each architecture and operating system.
-
-cindex:[symbolic link,to build directory]
+source files. Compilation does not take place in the &_src_& directory.
+Instead, a &'build directory'& is created for each architecture and operating
+system.
+.cindex "symbolic link" "to build directory"
 Symbolic links to the sources are installed in this directory, which is where
-the actual building takes place.
+the actual building takes place. In most cases, Exim can discover the machine
+architecture and operating system for itself, but the defaults can be
+overridden if necessary.
 
-In most cases, Exim can discover the machine architecture and operating system
-for itself, but the defaults can be overridden if necessary.
 
-
-[[SECTdb]]
-DBM libraries
-~~~~~~~~~~~~~
-cindex:[DBM libraries, discussion of]
-cindex:[hints database,DBM files used for]
+.section "DBM libraries" "SECTdb"
+.cindex "DBM libraries" "discussion of"
+.cindex "hints database" "DBM files used for"
 Even if you do not use any DBM files in your configuration, Exim still needs a
 DBM library in order to operate, because it uses indexed files for its hints
 databases. Unfortunately, there are a number of DBM libraries in existence, and
 different operating systems often have different ones installed.
 
-cindex:[Solaris,DBM library for]
-cindex:[IRIX, DBM library for]
-cindex:[BSD, DBM library for]
-cindex:[Linux, DBM library for]
+.cindex "Solaris" "DBM library for"
+.cindex "IRIX" "DBM library for"
+.cindex "BSD" "DBM library for"
+.cindex "Linux" "DBM library for"
 If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
 Linux distribution, the DBM configuration should happen automatically, and you
 may be able to ignore this section. Otherwise, you may have to learn more than
 you would like about DBM libraries from what follows.
 
-cindex:['ndbm' DBM library]
+.cindex "&'ndbm'& DBM library"
 Licensed versions of Unix normally contain a library of DBM functions operating
-via the 'ndbm' interface, and this is what Exim expects by default. Free
+via the &'ndbm'& interface, and this is what Exim expects by default. Free
 versions of Unix seem to vary in what they contain as standard. In particular,
 some early versions of Linux have no default DBM library, and different
 distributors have chosen to bundle different libraries with their packaged
@@ -1635,55 +1619,50 @@ versions. However, the more recent releases seem to have standardised on the
 Berkeley DB library.
 
 Different DBM libraries have different conventions for naming the files they
-use. When a program opens a file called _dbmfile_, there are four
+use. When a program opens a file called &_dbmfile_&, there are several
 possibilities:
 
-. A traditional 'ndbm' implementation, such as that supplied as part of
-Solaris, operates on two files called _dbmfile.dir_ and _dbmfile.pag_.
-
-. cindex:['gdbm' DBM library]
-The GNU library, 'gdbm', operates on a single file. If used via its 'ndbm'
+.olist
+A traditional &'ndbm'& implementation, such as that supplied as part of
+Solaris, operates on two files called &_dbmfile.dir_& and &_dbmfile.pag_&.
+.next
+.cindex "&'gdbm'& DBM library"
+The GNU library, &'gdbm'&, operates on a single file. If used via its &'ndbm'&
 compatibility interface it makes two different hard links to it with names
-_dbmfile.dir_ and _dbmfile.pag_, but if used via its native interface, the
+&_dbmfile.dir_& and &_dbmfile.pag_&, but if used via its native interface, the
 file name is used unmodified.
-
-. cindex:[Berkeley DB library]
-The Berkeley DB package, if called via its 'ndbm' compatibility interface,
-operates on a single file called _dbmfile.db_, but otherwise looks to the
-programmer exactly the same as the traditional 'ndbm' implementation.
-
-If the Berkeley package is used in its native mode, it operates on a single
-file called _dbmfile_; the programmer's interface is somewhat different to
-the traditional 'ndbm' interface.
-
-To complicate things further, there are several very different versions of the
+.next
+.cindex "Berkeley DB library"
+The Berkeley DB package, if called via its &'ndbm'& compatibility interface,
+operates on a single file called &_dbmfile.db_&, but otherwise looks to the
+programmer exactly the same as the traditional &'ndbm'& implementation.
+.next
+If the Berkeley package is used in its native mode, it operates on a single
+file called &_dbmfile_&; the programmer's interface is somewhat different to
+the traditional &'ndbm'& interface.
+.next
+To complicate things further, there are several very different versions of the
 Berkeley DB package. Version 1.85 was stable for a very long time, releases
-2.'x' and 3.'x' were current for a while, but the latest versions are now
-numbered 4.'x'. Maintenance of some of the earlier releases has ceased. All
+2.&'x'& and 3.&'x'& were current for a while, but the latest versions are now
+numbered 4.&'x'&. Maintenance of some of the earlier releases has ceased. All
 versions of Berkeley DB can be obtained from
-+
-&&&
-*http://www.sleepycat.com/[]*
-&&&
-
-. cindex:['tdb' DBM library]
-Yet another DBM library, called 'tdb', has become available from
-+
-&&&
-*http://download.sourceforge.net/tdb[]*
-&&&
-+
-It has its own interface, and also operates on a single file.
-
-cindex:[USE_DB]
-cindex:[DBM libraries, configuration for building]
+&url(http://www.sleepycat.com/).
+.next
+.cindex "&'tdb'& DBM library"
+Yet another DBM library, called &'tdb'&, is available from
+&url(http://download.sourceforge.net/tdb). It has its own interface, and also
+operates on a single file.
+.endlist
+
+.cindex "USE_DB"
+.cindex "DBM libraries" "configuration for building"
 Exim and its utilities can be compiled to use any of these interfaces. In order
 to use any version of the Berkeley DB package in native mode, you must set
 USE_DB in an appropriate configuration file (typically
-_Local/Makefile_). For example:
-
-  USE_DB=yes
-
+&_Local/Makefile_&). For example:
+.code
+USE_DB=yes
+.endd
 Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An
 error is diagnosed if you set more than one of these.
 
@@ -1692,43 +1671,41 @@ thereby assuming an interface of type (1). However, some operating system
 configuration files (for example, those for the BSD operating systems and
 Linux) assume type (4) by setting USE_DB as their default, and the
 configuration files for Cygwin set USE_GDBM. Anything you set in
-_Local/Makefile_, however, overrides these system defaults.
+&_Local/Makefile_&, however, overrides these system defaults.
 
 As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be
 necessary to set DBMLIB, to cause inclusion of the appropriate library, as
 in one of these lines:
-
-  DBMLIB = -ldb
-  DBMLIB = -ltdb
-
+.code
+DBMLIB = -ldb
+DBMLIB = -ltdb
+.endd
 Settings like that will work if the DBM library is installed in the standard
 place. Sometimes it is not, and the library's header file may also not be in
 the default path. You may need to set INCLUDE to specify where the header
 file is, and to specify the path to the library more fully in DBMLIB, as in
 this example:
-
-  INCLUDE=-I/usr/local/include/db-4.1
-  DBMLIB=/usr/local/lib/db-4.1/libdb.a
-
-
+.code
+INCLUDE=-I/usr/local/include/db-4.1
+DBMLIB=/usr/local/lib/db-4.1/libdb.a
+.endd
 There is further detailed discussion about the various DBM libraries in the
-file _doc/dbm.discuss.txt_ in the Exim distribution.
+file &_doc/dbm.discuss.txt_& in the Exim distribution.
 
 
 
-Pre-building configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[building Exim,pre-building configuration]
-cindex:[configuration for building Exim]
-cindex:[_Local/Makefile_]
-cindex:[_src/EDITME_]
+.section "Pre-building configuration"
+.cindex "building Exim" "pre-building configuration"
+.cindex "configuration for building Exim"
+.cindex "&_Local/Makefile_&"
+.cindex "&_src/EDITME_&"
 Before building Exim, a local configuration file that specifies options
 independent of any operating system has to be created with the name
-_Local/Makefile_. A template for this file is supplied as the file
-_src/EDITME_, and it contains full descriptions of all the option settings
+&_Local/Makefile_&. A template for this file is supplied as the file
+&_src/EDITME_&, and it contains full descriptions of all the option settings
 therein. These descriptions are therefore not repeated here. If you are
 building Exim for the first time, the simplest thing to do is to copy
-_src/EDITME_ to _Local/Makefile_, then read it and edit it appropriately.
+&_src/EDITME_& to &_Local/Makefile_&, then read it and edit it appropriately.
 
 There are three settings that you must supply, because Exim will not build
 without them. They are the location of the run time configuration file
@@ -1741,74 +1718,71 @@ There are a few other parameters that can be specified either at build time or
 at run time, to enable the same binary to be used on a number of different
 machines. However, if the locations of Exim's spool directory and log file
 directory (if not within the spool directory) are fixed, it is recommended that
-you specify them in _Local/Makefile_ instead of at run time, so that errors
+you specify them in &_Local/Makefile_& instead of at run time, so that errors
 detected early in Exim's execution (such as a malformed configuration file) can
 be logged.
 
-cindex:[content scanning,specifying at build time]
+.cindex "content scanning" "specifying at build time"
 Exim's interfaces for calling virus and spam scanning software directly from
 access control lists are not compiled by default. If you want to include these
 facilities, you need to set
-
-  WITH_CONTENT_SCAN=yes
-
-in your _Local/Makefile_. For details of the facilities themselves, see
-chapter <<CHAPexiscan>>.
+.code
+WITH_CONTENT_SCAN=yes
+.endd
+in your &_Local/Makefile_&. For details of the facilities themselves, see
+chapter &<<CHAPexiscan>>&.
 
 
-cindex:[_Local/eximon.conf_]
-cindex:[_exim_monitor/EDITME_]
+.cindex "&_Local/eximon.conf_&"
+.cindex "_exim_monitor/EDITME_"
 If you are going to build the Exim monitor, a similar configuration process is
-required. The file _exim_monitor/EDITME_ must be edited appropriately for
-your installation and saved under the name _Local/eximon.conf_. If you are
-happy with the default settings described in _exim_monitor/EDITME_,
-_Local/eximon.conf_ can be empty, but it must exist.
+required. The file &_exim_monitor/EDITME_& must be edited appropriately for
+your installation and saved under the name &_Local/eximon.conf_&. If you are
+happy with the default settings described in &_exim_monitor/EDITME_&,
+&_Local/eximon.conf_& can be empty, but it must exist.
 
 This is all the configuration that is needed in straightforward cases for known
 operating systems. However, the building process is set up so that it is easy
 to override options that are set by default or by operating-system-specific
 configuration files, for example to change the name of the C compiler, which
-defaults to %gcc%. See section <<SECToverride>> below for details of how to do
-this.
+defaults to &%gcc%&. See section &<<SECToverride>>& below for details of how to
+do this.
 
 
 
-Support for iconv()
-~~~~~~~~~~~~~~~~~~~
-cindex:['iconv()' support]
-cindex:[RFC 2047]
+.section "Support for iconv()"
+.cindex "&[iconv()]& support"
+.cindex "RFC 2047"
 The contents of header lines in messages may be encoded according to the rules
 described RFC 2047. This makes it possible to transmit characters that are not
 in the ASCII character set, and to label them as being in a particular
-character set. When Exim is inspecting header lines by means of the %\$h_%
+character set. When Exim is inspecting header lines by means of the &%$h_%&
 mechanism, it decodes them, and translates them into a specified character set
 (default ISO-8859-1). The translation is possible only if the operating system
-supports the 'iconv()' function.
-
-However, some of the operating systems that supply 'iconv()' do not support
-very many conversions. The GNU %libiconv% library (available from
-*http://www.gnu.org/software/libiconv/[]*) can be installed on such systems to
-remedy this deficiency, as well as on systems that do not supply 'iconv()' at
-all. After installing %libiconv%, you should add
-
-  HAVE_ICONV=yes
-
-to your _Local/Makefile_ and rebuild Exim.
-
-
-
-[[SECTinctlsssl]]
-Including TLS/SSL encryption support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[TLS,including support for TLS]
-cindex:[encryption,including support for]
-cindex:[SUPPORT_TLS]
-cindex:[OpenSSL,building Exim with]
-cindex:[GnuTLS,building Exim with]
+supports the &[iconv()]& function.
+
+However, some of the operating systems that supply &[iconv()]& do not support
+very many conversions. The GNU &%libiconv%& library (available from
+&url(http://www.gnu.org/software/libiconv/)) can be installed on such
+systems to remedy this deficiency, as well as on systems that do not supply
+&[iconv()]& at all. After installing &%libiconv%&, you should add
+.code
+HAVE_ICONV=yes
+.endd
+to your &_Local/Makefile_& and rebuild Exim.
+
+
+
+.section "Including TLS/SSL encryption support" "SECTinctlsssl"
+.cindex "TLS" "including support for TLS"
+.cindex "encryption" "including support for"
+.cindex "SUPPORT_TLS"
+.cindex "OpenSSL" "building Exim with"
+.cindex "GnuTLS" "building Exim with"
 Exim can be built to support encrypted SMTP connections, using the STARTTLS
 command as per RFC 2487. It can also support legacy clients that expect to
 start a TLS session immediately on connection to a non-standard port (see the
-%tls_on_connect_ports% runtime option and the %-tls-on-connect% command
+&%tls_on_connect_ports%& runtime option and the &%-tls-on-connect%& command
 line option).
 
 If you want to build Exim with TLS support, you must first install either the
@@ -1816,74 +1790,72 @@ OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
 implementing SSL.
 
 If OpenSSL is installed, you should set
-
-  SUPPORT_TLS=yes
-  TLS_LIBS=-lssl -lcrypto
-
-in _Local/Makefile_. You may also need to specify the locations of the
+.code
+SUPPORT_TLS=yes
+TLS_LIBS=-lssl -lcrypto
+.endd
+in &_Local/Makefile_&. You may also need to specify the locations of the
 OpenSSL library and include files. For example:
-
-  SUPPORT_TLS=yes
-  TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
-  TLS_INCLUDE=-I/usr/local/openssl/include/
-
-cindex:[USE_GNUTLS]
+.code
+SUPPORT_TLS=yes
+TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
+TLS_INCLUDE=-I/usr/local/openssl/include/
+.endd
+.cindex "USE_GNUTLS"
 If GnuTLS is installed, you should set
-
-  SUPPORT_TLS=yes
-  USE_GNUTLS=yes
-  TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
-
-in _Local/Makefile_, and again you may need to specify the locations of the
+.code
+SUPPORT_TLS=yes
+USE_GNUTLS=yes
+TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
+.endd
+in &_Local/Makefile_&, and again you may need to specify the locations of the
 library and include files. For example:
-
-  SUPPORT_TLS=yes
-  USE_GNUTLS=yes
-  TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
-  TLS_INCLUDE=-I/usr/gnu/include
-
+.code
+SUPPORT_TLS=yes
+USE_GNUTLS=yes
+TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
+TLS_INCLUDE=-I/usr/gnu/include
+.endd
 You do not need to set TLS_INCLUDE if the relevant directory is already
-specified in INCLUDE. Details of how to configure Exim to make use of TLS
-are given in chapter <<CHAPTLS>>.
+specified in INCLUDE. Details of how to configure Exim to make use of TLS are
+given in chapter &<<CHAPTLS>>&.
 
 
 
 
-Use of tcpwrappers
-~~~~~~~~~~~~~~~~~~
-cindex:[tcpwrappers, building Exim to support]
-cindex:[USE_TCP_WRAPPERS]
-Exim can be linked with the 'tcpwrappers' library in order to check incoming
-SMTP calls using the 'tcpwrappers' control files. This may be a convenient
+.section "Use of tcpwrappers"
+.cindex "tcpwrappers" "building Exim to support"
+.cindex "USE_TCP_WRAPPERS"
+Exim can be linked with the &'tcpwrappers'& library in order to check incoming
+SMTP calls using the &'tcpwrappers'& control files. This may be a convenient
 alternative to Exim's own checking facilities for installations that are
-already making use of 'tcpwrappers' for other purposes. To do this, you should
-set USE_TCP_WRAPPERS in _Local/Makefile_, arrange for the file
-_tcpd.h_ to be available at compile time, and also ensure that the library
-_libwrap.a_ is available at link time, typically by including %-lwrap% in
-EXTRALIBS_EXIM. For example, if 'tcpwrappers' is installed in
-_/usr/local_, you might have
-
-  USE_TCP_WRAPPERS=yes
-  CFLAGS=-O -I/usr/local/include
-  EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
-
-in _Local/Makefile_. The name to use in the 'tcpwrappers' control files is
-``exim''. For example, the line
-
-  exim : LOCAL  192.168.1.  .friendly.domain.example
-
-in your _/etc/hosts.allow_ file allows connections from the local host, from
-the subnet 192.168.1.0/24, and from all hosts in 'friendly.domain.example'.
-All other connections are denied. Consult the 'tcpwrappers' documentation for
+already making use of &'tcpwrappers'& for other purposes. To do this, you
+should set USE_TCP_WRAPPERS in &_Local/Makefile_&, arrange for the file
+&_tcpd.h_& to be available at compile time, and also ensure that the library
+&_libwrap.a_& is available at link time, typically by including &%-lwrap%& in
+EXTRALIBS_EXIM. For example, if &'tcpwrappers'& is installed in &_/usr/local_&,
+you might have
+.code
+USE_TCP_WRAPPERS=yes
+CFLAGS=-O -I/usr/local/include
+EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
+.endd
+in &_Local/Makefile_&. The name to use in the &'tcpwrappers'& control files is
+&"exim"&. For example, the line
+.code
+exim : LOCAL  192.168.1.  .friendly.domain.example
+.endd
+in your &_/etc/hosts.allow_& file allows connections from the local host, from
+the subnet 192.168.1.0/24, and from all hosts in &'friendly.domain.example'&.
+All other connections are denied. Consult the &'tcpwrappers'& documentation for
 further details.
 
 
 
-Including support for IPv6
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[IPv6,including support for]
+.section "Including support for IPv6"
+.cindex "IPv6" "including support for"
 Exim contains code for use on systems that have IPv6 support. Setting
-`HAVE_IPV6=YES` in _Local/Makefile_ causes the IPv6 code to be included;
+&`HAVE_IPV6=YES`& in &_Local/Makefile_& causes the IPv6 code to be included;
 it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems
 where the IPv6 support is not fully integrated into the normal include and
 library files.
@@ -1892,241 +1864,230 @@ Two different types of DNS record for handling IPv6 addresses have been
 defined. AAAA records (analagous to A records for IPv4) are in use, and are
 currently seen as the mainstream. Another record type called A6 was proposed
 as better than AAAA because it had more flexibility. However, it was felt to be
-over-complex, and its status was reduced to ``experimental''. It is not known
+over-complex, and its status was reduced to &"experimental"&. It is not known
 if anyone is actually using A6 records. Exim has support for A6 records, but
-this is included only if you set `SUPPORT_A6=YES` in _Local/Makefile_. The
+this is included only if you set &`SUPPORT_A6=YES`& in &_Local/Makefile_&. The
 support has not been tested for some time.
 
 
 
-The building process
-~~~~~~~~~~~~~~~~~~~~
-cindex:[build directory]
-Once _Local/Makefile_ (and _Local/eximon.conf_, if required) have been
-created, run 'make' at the top level. It determines the architecture and
+.section "The building process"
+.cindex "build directory"
+Once &_Local/Makefile_& (and &_Local/eximon.conf_&, if required) have been
+created, run &'make'& at the top level. It determines the architecture and
 operating system types, and creates a build directory if one does not exist.
 For example, on a Sun system running Solaris 8, the directory
-_build-SunOS5-5.8-sparc_ is created.
-cindex:[symbolic link,to source files]
+&_build-SunOS5-5.8-sparc_& is created.
+.cindex "symbolic link" "to source files"
 Symbolic links to relevant source files are installed in the build directory.
 
-*Warning*: The %-j% (parallel) flag must not be used with 'make'; the
+&*Warning*&: The &%-j%& (parallel) flag must not be used with &'make'&; the
 building process fails if it is set.
 
-If this is the first time 'make' has been run, it calls a script that builds
+If this is the first time &'make'& has been run, it calls a script that builds
 a make file inside the build directory, using the configuration files from the
-_Local_ directory. The new make file is then passed to another instance of
-'make'. This does the real work, building a number of utility scripts, and
+&_Local_& directory. The new make file is then passed to another instance of
+&'make'&. This does the real work, building a number of utility scripts, and
 then compiling and linking the binaries for the Exim monitor (if configured), a
-number of utility programs, and finally Exim itself. The command 'make
-makefile' can be used to force a rebuild of the make file in the build
+number of utility programs, and finally Exim itself. The command &`make
+makefile`& can be used to force a rebuild of the make file in the build
 directory, should this ever be necessary.
 
 If you have problems building Exim, check for any comments there may be in the
-_README_ file concerning your operating system, and also take a look at the
+&_README_& file concerning your operating system, and also take a look at the
 FAQ, where some common problems are covered.
 
 
 
-Output from ``make''
-~~~~~~~~~~~~~~~~~~~~
-
-[revisionflag="changed"]
-The output produced by the 'make' process for compile lines is often very
+.section 'Output from &"make"&'
+.new
+The output produced by the &'make'& process for compile lines is often very
 unreadable, because these lines can be very long. For this reason, the normal
 output is suppressed by default, and instead output similar to that which
 appears when compiling the 2.6 Linux kernel is generated: just a short line for
 each module that is being compiled or linked. However, it is still possible to
-get the full output, by calling 'make' like this:
-
-  FULLECHO='' make -e
-
-The value of FULLECHO defaults to ``@'', the flag character that suppresses
-command reflection in 'make'. When you ask for the full output, it is
+get the full output, by calling &'make'& like this:
+.code
+FULLECHO='' make -e
+.endd
+The value of FULLECHO defaults to &"@"&, the flag character that suppresses
+command reflection in &'make'&. When you ask for the full output, it is
 given in addition to the the short output.
+.wen
 
 
 
-
-[[SECToverride]]
-Overriding build-time options for Exim
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-cindex:[build-time options, overriding]
+.section "Overriding build-time options for Exim" "SECToverride"
+.cindex "build-time options" "overriding"
 The main make file that is created at the beginning of the building process
 consists of the concatenation of a number of files which set configuration
-values, followed by a fixed set of 'make' instructions. If a value is set
+values, followed by a fixed set of &'make'& instructions. If a value is set
 more than once, the last setting overrides any previous ones. This provides a
 convenient way of overriding defaults. The files that are concatenated are, in
 order:
-
-&&&
-_OS/Makefile-Default_
-_OS/Makefile-_<'ostype'>
-_Local/Makefile_
-_Local/Makefile-_<'ostype'>
-_Local/Makefile-_<'archtype'>
-_Local/Makefile-_<'ostype'>-<'archtype'>
-_OS/Makefile-Base_
-&&&
-
-cindex:[_Local/Makefile_]
-cindex:[building Exim,operating system type]
-cindex:[building Exim,architecture type]
-where <'ostype'> is the operating system type and <'archtype'> is the
-architecture type. _Local/Makefile_ is required to exist, and the building
-process fails if it is absent. The other three _Local_ files are optional,
+.display
+&_OS/Makefile-Default_&
+&_OS/Makefile-_&<&'ostype'&>
+&_Local/Makefile_&
+&_Local/Makefile-_&<&'ostype'&>
+&_Local/Makefile-_&<&'archtype'&>
+&_Local/Makefile-_&<&'ostype'&>-<&'archtype'&>
+&_OS/Makefile-Base_&
+.endd
+.cindex "&_Local/Makefile_&"
+.cindex "building Exim" "operating system type"
+.cindex "building Exim" "architecture type"
+where <&'ostype'&> is the operating system type and <&'archtype'&> is the
+architecture type. &_Local/Makefile_& is required to exist, and the building
+process fails if it is absent. The other three &_Local_& files are optional,
 and are often not needed.
 
-The values used for <'ostype'> and <'archtype'> are obtained from scripts
-called _scripts/os-type_ and _scripts/arch-type_ respectively. If either of
+The values used for <&'ostype'&> and <&'archtype'&> are obtained from scripts
+called &_scripts/os-type_& and &_scripts/arch-type_& respectively. If either of
 the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their
 values are used, thereby providing a means of forcing particular settings.
-Otherwise, the scripts try to get values from the %uname% command. If this
+Otherwise, the scripts try to get values from the &%uname%& command. If this
 fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number
-of 'ad hoc' transformations are then applied, to produce the standard names
+of &'ad hoc'& transformations are then applied, to produce the standard names
 that Exim expects. You can run these scripts directly from the shell in order
 to find out what values are being used on your system.
 
 
-_OS/Makefile-Default_ contains comments about the variables that are set
+&_OS/Makefile-Default_& contains comments about the variables that are set
 therein. Some (but not all) are mentioned below. If there is something that
 needs changing, review the contents of this file and the contents of the make
-file for your operating system (_OS/Makefile-<ostype>_) to see what the
+file for your operating system (&_OS/Makefile-<ostype>_&) to see what the
 default values are.
 
 
-cindex:[building Exim,overriding default settings]
-If you need to change any of the values that are set in _OS/Makefile-Default_
-or in _OS/Makefile-<ostype>_, or to add any new definitions, you do not
+.cindex "building Exim" "overriding default settings"
+If you need to change any of the values that are set in &_OS/Makefile-Default_&
+or in &_OS/Makefile-<ostype>_&, or to add any new definitions, you do not
 need to change the original files. Instead, you should make the changes by
-putting the new values in an appropriate _Local_ file. For example,
-cindex:[Tru64-Unix build-time settings]
+putting the new values in an appropriate &_Local_& file. For example,
+.cindex "Tru64-Unix build-time settings"
 when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX,
 formerly DEC-OSF1) operating system, it is necessary to specify that the C
-compiler is called 'cc' rather than 'gcc'. Also, the compiler must be
-called with the option %-std1%, to make it recognize some of the features of
+compiler is called &'cc'& rather than &'gcc'&. Also, the compiler must be
+called with the option &%-std1%&, to make it recognize some of the features of
 Standard C that Exim uses. (Most other compilers recognize Standard C by
-default.) To do this, you should create a file called _Local/Makefile-OSF1_
+default.) To do this, you should create a file called &_Local/Makefile-OSF1_&
 containing the lines
-
-  CC=cc
-  CFLAGS=-std1
-
+.code
+CC=cc
+CFLAGS=-std1
+.endd
 If you are compiling for just one operating system, it may be easier to put
-these lines directly into _Local/Makefile_.
+these lines directly into &_Local/Makefile_&.
 
 Keeping all your local configuration settings separate from the distributed
 files makes it easy to transfer them to new versions of Exim simply by copying
-the contents of the _Local_ directory.
+the contents of the &_Local_& directory.
 
 
-cindex:[NIS lookup type,including support for]
-cindex:[NIS+ lookup type,including support for]
-cindex:[LDAP,including support for]
-cindex:[lookup,inclusion in binary]
+.cindex "NIS lookup type" "including support for"
+.cindex "NIS+ lookup type" "including support for"
+.cindex "LDAP" "including support for"
+.cindex "lookup" "inclusion in binary"
 Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
 lookup, but not all systems have these components installed, so the default is
 not to include the relevant code in the binary. All the different kinds of file
 and database lookup that Exim supports are implemented as separate code modules
 which are included only if the relevant compile-time options are set. In the
-case of LDAP, NIS, and NIS+, the settings for _Local/Makefile_ are:
-
-  LOOKUP_LDAP=yes
-  LOOKUP_NIS=yes
-  LOOKUP_NISPLUS=yes
-
+case of LDAP, NIS, and NIS+, the settings for &_Local/Makefile_& are:
+.code
+LOOKUP_LDAP=yes
+LOOKUP_NIS=yes
+LOOKUP_NISPLUS=yes
+.endd
 and similar settings apply to the other lookup types. They are all listed in
-_src/EDITME_. In many cases the relevant include files and interface
+&_src/EDITME_&. In many cases the relevant include files and interface
 libraries need to be installed before compiling Exim.
-cindex:[cdb,including support for]
+.cindex "cdb" "including support for"
 However, there are some optional lookup types (such as cdb) for which
 the code is entirely contained within Exim, and no external include
 files or libraries are required. When a lookup type is not included in the
 binary, attempts to configure Exim to use it cause run time configuration
 errors.
 
-cindex:[Perl,including support for]
+.cindex "Perl" "including support for"
 Exim can be linked with an embedded Perl interpreter, allowing Perl
 subroutines to be called during string expansion. To enable this facility,
+.code
+EXIM_PERL=perl.o
+.endd
+must be defined in &_Local/Makefile_&. Details of this facility are given in
+chapter &<<CHAPperl>>&.
 
-  EXIM_PERL=perl.o
-
-must be defined in _Local/Makefile_. Details of this facility are given in
-chapter <<CHAPperl>>.
-
-cindex:[X11 libraries, location of]
+.cindex "X11 libraries" "location of"
 The location of the X11 libraries is something that varies a lot between
 operating systems, and there may be different versions of X11 to cope
 with. Exim itself makes no use of X11, but if you are compiling the Exim
 monitor, the X11 libraries must be available.
-The following three variables are set in _OS/Makefile-Default_:
-
-  X11=/usr/X11R6
-  XINCLUDE=-I$(X11)/include
-  XLFLAGS=-L$(X11)/lib
-
+The following three variables are set in &_OS/Makefile-Default_&:
+.code
+X11=/usr/X11R6
+XINCLUDE=-I$(X11)/include
+XLFLAGS=-L$(X11)/lib
+.endd
 These are overridden in some of the operating-system configuration files. For
-example, in _OS/Makefile-SunOS5_ there is
-
-  X11=/usr/openwin
-  XINCLUDE=-I$(X11)/include
-  XLFLAGS=-L$(X11)/lib -R$(X11)/lib
-
+example, in &_OS/Makefile-SunOS5_& there is
+.code
+X11=/usr/openwin
+XINCLUDE=-I$(X11)/include
+XLFLAGS=-L$(X11)/lib -R$(X11)/lib
+.endd
 If you need to override the default setting for your operating system, place a
 definition of all three of these variables into your
-_Local/Makefile-<ostype>_ file.
+&_Local/Makefile-<ostype>_& file.
 
-cindex:[EXTRALIBS]
+.cindex "EXTRALIBS"
 If you need to add any extra libraries to the link steps, these can be put in a
 variable called EXTRALIBS, which appears in all the link commands, but by
 default is not defined. In contrast, EXTRALIBS_EXIM is used only on the
&