Imported from /Users/nigel/Work/x/xfpt-0.03.tar.bz2.

author: Philip Hazel <ph10@hermes.cam.ac.uk> 2007-07-04 08:30:36 +0000
committer: Nigel Metheringham <nigel@exim.org> 2010-06-09 12:42:07 +0000
commit: 383466003e800a06ed6d3de9ede2185d03cca488 (patch)
tree: 3f34f0b82c8eafb38967c4bc73cf380e5e9afabf
parent: 4f307ce2d96bae1c86f9d3d9e6de73caae10f1b9 (diff)
download: exim4-383466003e800a06ed6d3de9ede2185d03cca488.tar.gz
14 files changed, 881 insertions, 193 deletions
diff --git a/doc/xfpt.html b/doc/xfpt.html
index ad3069017..b86fb4e4a 100644
--- a/doc/xfpt.html
+++ b/doc/xfpt.html
@@ -54,7 +54,7 @@ The xfpt plain text to XML processor</title>
 <div>
 <div>
 <h1 class="title">
-<a id="id2433571">
+<a id="id2488007">
 </a>
 The xfpt plain text to XML processor</h1>
 </div>
@@ -83,9 +83,9 @@ Revision History</b>
 </tr>
 <tr>
 <td align="left">
-Revision 0.02</td>
+Revision 0.03</td>
 <td align="left">
-10 April 2007</td>
+03 July 2007</td>
 <td align="left">
 PH</td>
 </tr>
@@ -103,7 +103,7 @@ Table of Contents</b>
 <dl>
 <dt>
 <span xmlns="" class="chapter">
-<a id="toc0001" href="#id2527524">
+<a id="toc0001" href="#id2527655">
 1. Introduction</a>
 </span>
 </dt>
@@ -111,7 +111,7 @@ Table of Contents</b>
 <dl>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0002" href="#id2489713">
+<a id="toc0002" href="#id2489811">
 1.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
 <em>
 xfpt</em>
@@ -121,7 +121,7 @@ command line</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0003" href="#id2491619">
+<a id="toc0003" href="#id2491791">
 1.2. A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
 <em>
 xfpt</em>
@@ -137,7 +137,7 @@ example</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0005" href="#id2490024">
+<a id="toc0005" href="#id2490210">
 1.4. Format of directive lines</a>
 </span>
 </dt>
@@ -151,7 +151,7 @@ example</a>
 </dd>
 <dt>
 <span xmlns="" class="chapter">
-<a id="toc0007" href="#id2490270">
+<a id="toc0007" href="#id2490456">
 2. Flag sequences</a>
 </span>
 </dt>
@@ -159,7 +159,7 @@ example</a>
 <dl>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0008" href="#id2490323">
+<a id="toc0008" href="#id2490509">
 2.1. Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis">
 <em>
 xfpt</em>
@@ -169,25 +169,25 @@ variables</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0009" href="#id2536958">
+<a id="toc0009" href="#id2537121">
 2.2. Flag sequences for calling macros</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0010" href="#id2536978">
+<a id="toc0010" href="#id2537142">
 2.3. Other flag sequences</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0011" href="#id2537122">
+<a id="toc0011" href="#id2537295">
 2.4. Unrecognized flag sequences</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0012" href="#id2537135">
+<a id="toc0012" href="#id2537308">
 2.5. Standard flag sequences</a>
 </span>
 </dt>
@@ -195,7 +195,7 @@ variables</a>
 </dd>
 <dt>
 <span xmlns="" class="chapter">
-<a id="toc0013" href="#id2537375">
+<a id="toc0013" href="#id2537548">
 3. Built-in directive processing</a>
 </span>
 </dt>
@@ -203,7 +203,7 @@ variables</a>
 <dl>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0014" href="#id2537397">
+<a id="toc0014" href="#id2537570">
 3.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .arg</strong>
@@ -213,7 +213,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0015" href="#id2537451">
+<a id="toc0015" href="#id2537638">
 3.2. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .eacharg</strong>
@@ -223,7 +223,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0016" href="#id2537607">
+<a id="toc0016" href="#id2537808">
 3.3. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .echo</strong>
@@ -233,7 +233,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0017" href="#id2537627">
+<a id="toc0017" href="#id2537828">
 3.4. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .endarg</strong>
@@ -243,7 +243,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0018" href="#id2537650">
+<a id="toc0018" href="#id2537851">
 3.5. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .endeach</strong>
@@ -253,7 +253,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0019" href="#id2537672">
+<a id="toc0019" href="#id2537873">
 3.6. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .endinliteral</strong>
@@ -263,7 +263,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0020" href="#id2537695">
+<a id="toc0020" href="#id2537896">
 3.7. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .flag</strong>
@@ -273,7 +273,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0021" href="#id2537730">
+<a id="toc0021" href="#id2537931">
 3.8. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .include</strong>
@@ -283,7 +283,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0022" href="#id2537755">
+<a id="toc0022" href="#id2537956">
 3.9. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .inliteral</strong>
@@ -293,7 +293,7 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0023" href="#id2537801">
+<a id="toc0023" href="#id2538001">
 3.10. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
 .literal</strong>
@@ -313,49 +313,59 @@ directive</a>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0025" href="#id2538016">
+<a id="toc0025" href="#id2538217">
 3.12. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
-.nonl</strong>
+.nest</strong>
 </span>
 directive</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0026" href="#id2538043">
+<a id="toc0026" href="#id2538290">
 3.13. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
-.pop</strong>
+.nonl</strong>
 </span>
 directive</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0027" href="#id2538104">
+<a id="toc0027" href="#id2538316">
 3.14. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
-.push</strong>
+.pop</strong>
 </span>
 directive</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0028" href="#SECTrevision">
+<a id="toc0028" href="#id2538377">
 3.15. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
-.revision</strong>
+.push</strong>
 </span>
 directive</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0029" href="#id2538330">
+<a id="toc0029" href="#SECTrevision">
 3.16. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
 <strong>
+.revision</strong>
+</span>
+directive</a>
+</span>
+</dt>
+<dt>
+<span xmlns="" class="section">
+<a id="toc0030" href="#id2538603">
+3.17. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
+<strong>
 .set</strong>
 </span>
 directive</a>
@@ -365,7 +375,7 @@ directive</a>
 </dd>
 <dt>
 <span xmlns="" class="chapter">
-<a id="toc0030" href="#CHAPstdmac">
+<a id="toc0031" href="#CHAPstdmac">
 4. The standard macros for DocBook</a>
 </span>
 </dt>
@@ -373,81 +383,105 @@ directive</a>
 <dl>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0031" href="#id2538433">
+<a id="toc0032" href="#id2538706">
 4.1. Overall setup</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0032" href="#id2538490">
+<a id="toc0033" href="#id2538763">
 4.2. Chapters, sections, and subsections</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0033" href="#id2538597">
-4.3. URL references</a>
+<a id="toc0034" href="#id2538870">
+4.3. Prefaces, appendixes, and colophons</a>
+</span>
+</dt>
+<dt>
+<span xmlns="" class="section">
+<a id="toc0035" href="#id2538917">
+4.4. URL references</a>
+</span>
+</dt>
+<dt>
+<span xmlns="" class="section">
+<a id="toc0036" href="#id2538987">
+4.5. Itemized lists</a>
+</span>
+</dt>
+<dt>
+<span xmlns="" class="section">
+<a id="toc0037" href="#id2539061">
+4.6. Ordered lists</a>
+</span>
+</dt>
+<dt>
+<span xmlns="" class="section">
+<a id="toc0038" href="#id2539153">
+4.7. Variable lists</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0034" href="#id2538666">
-4.4. Itemized lists</a>
+<a id="toc0039" href="#id2539208">
+4.8. Nested lists</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0035" href="#id2538740">
-4.5. Ordered lists</a>
+<a id="toc0040" href="#id2539230">
+4.9. Displayed text</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0036" href="#id2538833">
-4.6. Variable lists</a>
+<a id="toc0041" href="#id2539342">
+4.10. Block quotes</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0037" href="#id2538887">
-4.7. Nested lists</a>
+<a id="toc0042" href="#SECTrevmacs">
+4.11. Revision markings</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0038" href="#id2538909">
-4.8. Displayed text</a>
+<a id="toc0043" href="#id2539589">
+4.12. Informal tables</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0039" href="#id2539021">
-4.9. Block quotes</a>
+<a id="toc0044" href="#id2539865">
+4.13. Formal tables</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0040" href="#SECTrevmacs">
-4.10. Revision markings</a>
+<a id="toc0045" href="#id2539922">
+4.14. Figures and images</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0041" href="#id2539248">
-4.11. Informal tables</a>
+<a id="toc0046" href="#id2540084">
+4.15. Footnotes</a>
 </span>
 </dt>
 <dt>
 <span xmlns="" class="section">
-<a id="toc0042" href="#id2539524">
-4.12. Indexes</a>
+<a id="toc0047" href="#id2540145">
+4.16. Indexes</a>
 </span>
 </dt>
 </dl>
 </dd>
 </dl>
 </div>
-<div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2527524">1. Introduction</a></h2></div></div></div><p><span class="emphasis"><em>xfpt</em></span> is a program that reads a marked-up ASCII source file, and converts it into
+<div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2527655">1. Introduction</a></h2></div></div></div><p><span class="emphasis"><em>xfpt</em></span> is a program that reads a marked-up ASCII source file, and converts it into
 XML. It was written with DocBook XML in mind, but can also be used for other
 forms of XML. Unlike <span class="emphasis"><em>AsciiDoc</em></span> (<span class="bold"><strong><a href="http://www.methods.co.nz/asciidoc/" target="_top">http://www.methods.co.nz/asciidoc/</a></strong></span>),
 <span class="emphasis"><em>xfpt</em></span> does not try to produce XML from a document that is also usable as a
@@ -481,7 +515,7 @@ closing quotes, as follows:
  <code class="literal"> '    </code>  becomes  ’<br />
 </div><p>
 Within normal input text, ampersand, grave accent, and apostrophe are the only
-characters that cause <span class="emphasis"><em>xfpt</em></span> to change the input text, and this applies only to
+characters that cause <span class="emphasis"><em>xfpt</em></span> to change the input text, but this applies only to
 non-literal text. In literal text, there are no markup characters, and only a
 dot at the start of a line is recognized as special. Within the body of a
 macro, there is one more special character: the dollar character is used to
@@ -491,29 +525,25 @@ Notwithstanding the previous paragraph, <span class="emphasis"><em>xfpt</em></sp
 and in all cases when a literal ampersand or angle bracket is required in the
 output, the appropriate XML entity reference (<code class="literal">&amp;amp;</code>, <code class="literal">&amp;lt;</code>, or
 <code class="literal">&amp;gt;</code>, respectively) is generated.
-</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2489713">1.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> command line</a></h3></div></div></div><p>The format of the <span class="emphasis"><em>xfpt</em></span> command line is:
+</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2489811">1.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> command line</a></h3></div></div></div><p>The format of the <span class="emphasis"><em>xfpt</em></span> command line is:
 </p><div class="literallayout">
  <code class="literal">xfpt [</code><span class="emphasis"><em>options</em></span><code class="literal">] [</code><span class="emphasis"><em>input source</em></span><code class="literal">]</code><br />
 </div><p>
-If no input is specified, the standard input is read. There are three options:
-</p><div class="literallayout">
- <code class="literal">-help</code><br />
-</div><p>
+If no input is specified, the standard input is read. There are four options:
+</p><div class="variablelist"><dl><dt><span class="term"><span><strong class="option">-help</strong></span></span></dt><dd><p>
 This option causes <span class="emphasis"><em>xfpt</em></span> to output its “<span class="quote">usage</span>” message, and exit.  
-</p><div class="literallayout">
- <code class="literal">-o </code><span class="emphasis"><em>&lt;output destination&gt;</em></span><br />
-</div><p>
+</p></dd><dt><span class="term"><span><strong class="option">-o</strong></span> <span class="emphasis"><em>&lt;output destination&gt;</em></span></span></dt><dd><p>
 This option overrides the default destination. If the standard input is being
 read, the default destination is the standard output. Otherwise, the default
 destination is the name of the input file with the extension <em class="filename">.xml</em>,
 replacing its existing extension if there is one. A single hyphen character can
 be given as an output destination to refer to the standard output.
-</p><div class="literallayout">
-  <code class="literal">-S </code><span class="emphasis"><em>&lt;directory path&gt;</em></span><br />
-</div><p>
+</p></dd><dt><span class="term"><span><strong class="option">-S</strong></span> <span class="emphasis"><em>&lt;directory path&gt;</em></span></span></dt><dd><p>
 This option overrides the path to <span class="emphasis"><em>xfpt</em></span>’s library directory that is built into
 the program. This makes it possible to use or test alternate libraries.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2491619">1.2 A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> example</a></h3></div></div></div><p>Here is a very short example of a complete <span class="emphasis"><em>xfpt</em></span> input file that uses some of the
+</p></dd><div xmlns="" class="changed"><dt xmlns="http://www.w3.org/1999/xhtml"><span class="term"><span><strong class="option">-v</strong></span></span></dt><dd xmlns="http://www.w3.org/1999/xhtml"><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+This option causes <span class="emphasis"><em>xfpt</em></span> to output its version number and exit.
+</p></div></dd></div></dl></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2491791">1.2 A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> example</a></h3></div></div></div><p>Here is a very short example of a complete <span class="emphasis"><em>xfpt</em></span> input file that uses some of the
 standard macros and flags:
 </p><pre class="literallayout">
  .include stdflags
@@ -534,14 +564,15 @@ standard macros and flags:
  .endlist
 
  There are also standard macros for ordered lists, literal
- layout blocks, code blocks, URL references, index entries
- and tables.
+ layout blocks, code blocks, URL references, index entries,
+ tables, footnotes, figures, etc.
 </pre></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTliteralprocessing">1.3 Literal and non-literal processing</a></h3></div></div></div><p><span class="emphasis"><em>xfpt</em></span> processes non-directive input lines in one of four ways (known as
 “<span class="quote">modes</span>”):
 </p><div class="itemizedlist"><ul type="disc"><li><p>
-In the default mode, text is processed paragraph by paragraph. The end of a
-paragraph is indicated by the end of the input, a blank line, or by an
-occurrence of the <span class="bold"><strong>.literal</strong></span> directive. Other directives (for example,
+In the default mode, text is processed paragraph by paragraph. 
+<sup>[<a id="id2490979" href="#ftn.id2490979">1</a>]</sup>
+The end of a paragraph is indicated by the end of the input, a blank line, or
+by an occurrence of the <span class="bold"><strong>.literal</strong></span> directive. Other directives (for example,
 <span class="bold"><strong>.include</strong></span>) do not of themselves terminate a paragraph. Most of the standard
 macros (such as <span class="bold"><strong>.chapter</strong></span> and <span class="bold"><strong>.section</strong></span>) force a paragraph end by
 starting their contents with a <span class="bold"><strong>.literal</strong></span> directive.
@@ -552,10 +583,11 @@ typically that of the last line of the paragraph.
 </p></li><li><p>
 In the “<span class="quote">literal layout</span>” mode, text is processed line by line, but is
 otherwise handled as in the default mode. The only real difference this makes
-to the markup from the user’s point of view is that paired flags must be on the
-same line. In this mode, error messages are more likely to contain the exact
-line number where the fault lies. Literal layout mode is used by the standard
-<span class="bold"><strong>.display</strong></span> macro to generate <code class="literal">&lt;literallayout&gt;</code> elements.
+to the markup from the user’s point of view is that both parts of a set of
+paired flags must be on the same line. In this mode, error messages are more
+likely to contain the exact line number where the fault lies. Literal layout
+mode is used by the standard <span class="bold"><strong>.display</strong></span> macro to generate <code class="literal">&lt;literallayout&gt;</code>
+elements.
 </p></li><li><p>
 In the “<span class="quote">literal text</span>” mode, text is also processed line by line, but no flags
 are recognized. The only modification <span class="emphasis"><em>xfpt</em></span> makes to the text is to turn
@@ -593,7 +625,7 @@ to use literal layout mode if you require such output. Another solution, which
 is used in the source for this document (where many examples show directive
 lines), is to indent every displayed line by one space, and thereby avoid the
 problem altogether.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2490024">1.4 Format of directive lines</a></h3></div></div></div><p>If an input line starts with a dot followed by a space, it is ignored by <span class="emphasis"><em>xfpt</em></span>.
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2490210">1.4 Format of directive lines</a></h3></div></div></div><p>If an input line starts with a dot followed by a space, it is ignored by <span class="emphasis"><em>xfpt</em></span>.
 This provides a facility for including comments in the input. Otherwise, the
 dot must be followed by a directive or macro name, and possibly one or more
 arguments. Arguments that are strings are delimited by white space unless they
@@ -642,7 +674,11 @@ A macro that can be called inline can always be called as a directive, but the
 opposite is not always true. Macros are usually designed to be called either
 one way or the other. However, the <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.index</strong></span> macros in the
 standard library are examples of macros that are designed be called either way.
-</p></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2490270">2. Flag sequences</a></h2></div></div></div><p>Only one flag sequence is built-into the code itself. If an input line ends
+</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id2490979" href="#id2490979">1</a>] </sup>
+<span xmlns="" class="changed"><span xmlns="http://www.w3.org/1999/xhtml">There is, however, a special case when a paragraph contains one or more 
+footnotes. In that situation, each part of the outer paragraph is processed 
+independently.</span></span>
+</p></div></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2490456">2. Flag sequences</a></h2></div></div></div><p>Only one flag sequence is built-into the code itself. If an input line ends
 with three ampersands (ignoring trailing white space), the ampersands are
 removed, and the next input line, with any leading white space removed, is
 joined to the original line. This happens before any other processing, and may
@@ -655,7 +691,7 @@ involve any number of lines. Thus:
 produces exactly the same output as:
 </p><pre class="literallayout">
  The quick brown fox.
-</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2490323">2.1 Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> variables</a></h3></div></div></div><p>If an ampersand is followed by a # character, a number, and a semicolon, it is
+</pre><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2490509">2.1 Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"><em>xfpt</em></span> variables</a></h3></div></div></div><p>If an ampersand is followed by a # character, a number, and a semicolon, it is
 understood as a numerical reference to an XML entity, and is passed through
 unmodified. The number can be decimal, or hexadecimal preceded by <code class="literal">x</code>. For
 example:
@@ -679,11 +715,11 @@ of the previous types. In this case, the input text is passed to the output
 without modification. For example:
 </p><pre class="literallayout">
  This is an Ohm sign: &amp;Ohm;.
-</pre></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2536958">2.2 Flag sequences for calling macros</a></h3></div></div></div><p>If an ampersand is followed by a sequence of alphanumeric characters starting
+</pre></li></ul></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537121">2.2 Flag sequences for calling macros</a></h3></div></div></div><p>If an ampersand is followed by a sequence of alphanumeric characters starting
 with a letter, terminated by an opening parenthesis, the characters between the
 ampersand and the parenthesis are interpreted as the name of a macro. See
 section <a href="#SECTcallingmacro" title="1.5&#xA0;Calling macros">1.5</a> for more details.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2536978">2.3 Other flag sequences</a></h3></div></div></div><p>Any other flag sequences that are needed must be defined by means of the
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537142">2.3 Other flag sequences</a></h3></div></div></div><p>Any other flag sequences that are needed must be defined by means of the
 <span class="bold"><strong>.flag</strong></span> directive. These are of two types, standalone and paired. Both cases
 define replacement text. This is always literal; it is not itself scanned for
 flag occurrences.
@@ -701,24 +737,28 @@ A standalone flag consists of an ampersand followed by any number of
 non-alphanumeric characters. When it is encountered, it is replaced by its
 replacement text. For example, in the standard flag definitions, <code class="literal">&amp;&amp;</code>
 is defined as a standalone flag with with the replacement text <code class="literal">&amp;amp;</code>.
-</p><p>
+</p><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
 A paired flag is defined as two sequences. The first takes the same form as a
 standalone flag. The second also consists of non-alphanumeric characters, but
 need not start with an ampersand. It is often defined as the reverse of the
-first sequence. When the first sequence of a paired flag is encountered, its
-partner is expected to be found within the same paragraph (or line, in literal
-layout mode). Furthermore, multiple occurrences of paired flags must be
-correctly nested. For example, in the standard definitions, <code class="literal">&amp;'</code> and
+first sequence. For example, in the standard definitions, <code class="literal">&amp;'</code> and
 <code class="literal">'&amp;</code> are defined as a flag pair for enclosing text in an <code class="literal">&lt;emphasis&gt;</code>
-element. Each member of the pair is replaced by its replacement text.
-</p><p>
-Note that, though <span class="emphasis"><em>xfpt</em></span> diagnoses an error for badly nested flag pairs, it does
-not prevent you from generating invalid XML. For example, DocBook does not
-allow <code class="literal">&lt;emphasis&gt;</code> within <code class="literal">&lt;literal&gt;</code>, though it does allow <code class="literal">&lt;literal&gt;</code>
-within <code class="literal">&lt;emphasis&gt;</code>.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537122">2.4 Unrecognized flag sequences</a></h3></div></div></div><p>If an ampersand is not followed by a character sequence in one of the forms
+element.
+</p></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+When the first sequence of a paired flag is encountered, its partner is
+expected to be found within the same text unit. In the default mode, the units
+are a paragraphs, or part-paragraphs if footnotes intervene. In literal layout
+mode, the text is processed line by line. Each member of the pair is replaced
+by its replacement text. 
+</p></div><p>
+Multiple occurrences of paired flags must be correctly nested. Note that,
+though <span class="emphasis"><em>xfpt</em></span> diagnoses an error for badly nested flag pairs, it does not prevent
+you from generating invalid XML. For example, DocBook does not allow
+<code class="literal">&lt;emphasis&gt;</code> within <code class="literal">&lt;literal&gt;</code>, though it does allow <code class="literal">&lt;literal&gt;</code> within
+<code class="literal">&lt;emphasis&gt;</code>.
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537295">2.4 Unrecognized flag sequences</a></h3></div></div></div><p>If an ampersand is not followed by a character sequence in one of the forms
 described in the preceding sections, an error occurs.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537135">2.5 Standard flag sequences</a></h3></div></div></div><p>These are the standalone flag sequences that are defined in the <em class="filename">stdflags</em>
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537308">2.5 Standard flag sequences</a></h3></div></div></div><p>These are the standalone flag sequences that are defined in the <em class="filename">stdflags</em>
 file in the <span class="emphasis"><em>xfpt</em></span> library:
 </p><div class="literallayout">
  <code class="literal">&amp;&amp;        </code> becomes <code class="literal"> &amp;amp;</code> (ampersand)<br />
@@ -744,10 +784,10 @@ For example, if you want to include a literal XML element in your output, you
 can do it like this: <code class="literal">&amp;&lt;element&gt;&amp;</code>. If you want to include a longer
 sequence of literal XML, changing to the literal XML mode may be more
 convenient.
-</p></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2537375">3. Built-in directive processing</a></h2></div></div></div><p>The directives that are built into the code of <span class="emphasis"><em>xfpt</em></span> are now described in
-alphabetical order. You can see more examples of their use in the definitions
+</p></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2537548">3. Built-in directive processing</a></h2></div></div></div><p>The directives that are built into the code of <span class="emphasis"><em>xfpt</em></span> are now described in
+alphabetical order. You can see more examples of their use in the descriptions
 of the standard macros in chapter <a href="#CHAPstdmac" title="4.&#xA0;The standard macros for DocBook">4</a>.
-</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537397">3.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.arg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed
+</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537570">3.1 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.arg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed
 by a single number, optionally preceded by a minus sign. If the number is
 positive (no minus sign), subsequent lines, up to a <span class="bold"><strong>.endarg</strong></span> directive, are
 skipped unless the macro has been called with at least that number of
@@ -767,13 +807,19 @@ for the given argument. For example:
  and the second one is not empty. 
  .endarg 
  .endmacro
-</pre><p>
+</pre><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+Note that if a macro is defined with default values for its arguments, these
+are not counted by the <span class="bold"><strong>.arg</strong></span> directive, which looks only at the actual
+arguments in a particular macro call.
+</p></div><p>
 The <span class="bold"><strong>.arg</strong></span> directive may be nested.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537451">3.2 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.eacharg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It may optionally be
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537638">3.2 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.eacharg</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It may optionally be
 followed by a single number; if omitted the value is taken to be 1. Subsequent
 lines, up to a <span class="bold"><strong>.endeach</strong></span> directive, are processed multiple times, once for
 each remaining argument. Unlike <span class="bold"><strong>.arg</strong></span>, an argument that is an empty string 
-is not treated specially.
+is not treated specially. <span xmlns="" class="changed"><span xmlns="http://www.w3.org/1999/xhtml">However, like <span class="bold"><strong>.arg</strong></span>, only the actual
+arguments of a macro call are considered. Default argument values do not 
+count.</span></span>
 </p><p>
 The number given with <span class="bold"><strong>.eacharg</strong></span> defines which argument to start with. If the
 macro is called with fewer arguments, the lines up to <span class="bold"><strong>.endeach</strong></span> are skipped,
@@ -804,14 +850,14 @@ fifth argument:
 </pre><p>
 The <span class="bold"><strong>.eacharg</strong></span> directive may in principle be nested, though this does not 
 seem useful in practice.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537607">3.3 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.echo</strong></span> directive</a></h3></div></div></div><p>This directive takes a single string argument. It writes it to the standard
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537808">3.3 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.echo</strong></span> directive</a></h3></div></div></div><p>This directive takes a single string argument. It writes it to the standard
 error stream. Within a macro, argument substitution takes place, but no other
 processing is done on the string. This directive can be useful for debugging
 macros or writing comments to the user.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537627">3.4 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endarg</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.arg</strong></span> above.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537650">3.5 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endeach</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.eacharg</strong></span> above.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537672">3.6 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endinliteral</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.inliteral</strong></span> below.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537695">3.7 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.flag</strong></span> directive</a></h3></div></div></div><p>This directive is used to define flag sequences. The directive must be followed
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537828">3.4 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endarg</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.arg</strong></span> above.
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537851">3.5 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endeach</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.eacharg</strong></span> above.
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537873">3.6 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.endinliteral</strong></span> directive</a></h3></div></div></div><p>See the description of <span class="bold"><strong>.inliteral</strong></span> below.
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537896">3.7 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.flag</strong></span> directive</a></h3></div></div></div><p>This directive is used to define flag sequences. The directive must be followed
 either by a standalone flag sequence and one string in quotes, or by a flag
 pair and two strings in quotes. White space separates these items. For example:
 </p><pre class="literallayout">
@@ -821,16 +867,16 @@ pair and two strings in quotes. White space separates these items. For example:
 There are more examples in the definitions of the standard flags. If you
 redefine an existing flag, the new definition overrides the old. There is no
 way to revert to the previous definition.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537730">3.8 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.include</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument that is the path to
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537931">3.8 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.include</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument that is the path to
 a file. The contents of the file are read and incorporated into the input at
 this point. If the string does not contain any slashes, the path to the <span class="emphasis"><em>xfpt</em></span>
 library is prepended. Otherwise, the path is used unaltered.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537755">3.9 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.inliteral</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed 
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537956">3.9 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.inliteral</strong></span> directive</a></h3></div></div></div><p>This directive may appear only within the body of a macro. It must be followed 
 by one of the words “<span class="quote">layout</span>”, “<span class="quote">text</span>”, “<span class="quote">off</span>”, or “<span class="quote">xml</span>”. If the current 
 literal mode does not correspond to the word, subsequent lines, up to a 
 <span class="bold"><strong>.endinliteral</strong></span> directive, are skipped. The <span class="bold"><strong>.inliteral</strong></span> directive may be
 nested.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2537801">3.10 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.literal</strong></span> directive</a></h3></div></div></div><p>This must be followed by one of the words “<span class="quote">layout</span>”, “<span class="quote">text</span>”, “<span class="quote">off</span>”, or
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538001">3.10 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.literal</strong></span> directive</a></h3></div></div></div><p>This must be followed by one of the words “<span class="quote">layout</span>”, “<span class="quote">text</span>”, “<span class="quote">off</span>”, or
 “<span class="quote">xml</span>”. It forces an end to a previous paragraph, if there is one, and then
 switches between processing modes. The default mode is the “<span class="quote">off</span>” mode, in
 which text is processed paragraph by paragraph, and flags are recognized.
@@ -888,11 +934,26 @@ call it, because <span class="emphasis"><em>xfpt</em></span> looks for built-in
 It is possible to define a macro within a macro, though clearly care must be 
 taken with argument references to ensure that substitutions happen at the right
 level.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538016">3.12 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nonl</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument. It is processed 
+</p></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538217">3.12 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nest</strong></span> directive</a></h3></div></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">This directive must be followed by one of the words “<span class="quote">begin</span>” or “<span class="quote">end</span>”. It is
+used to delimit a nested sequence of independent text items that occurs inside
+another, such as the contents of a footnote inside a paragraph. This directive
+is usually used inside a macro. For example, a <span class="bold"><strong>footnote</strong></span> macro could be
+defined like this:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ .macro footnote
+ &amp;&lt;footnote&gt;&amp;
+ .nest begin
+ .endmacro
+</pre></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+At the start of a nested sequence, the current mode and paragraph state are
+remembered and <span class="emphasis"><em>xfpt</em></span> then reverts to the default mode and “<span class="quote">not in a paragraph</span>”.
+At the end of a nested sequence, if a paragraph has been started, it is
+terminated, and then <span class="emphasis"><em>xfpt</em></span> reverts to the previous state.
+</p></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538290">3.13 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nonl</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a single string argument. It is processed 
 as normal text, but without a newline at the end. This facility is useful in 
 macros when constructing a single data line from several text fragments. See 
 for example the <span class="bold"><strong>.new</strong></span> macro in the standard macros.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538043">3.13 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.pop</strong></span> directive</a></h3></div></div></div><p><span class="emphasis"><em>xfpt</em></span> keeps a stack of text strings that are manipulated by the <span class="bold"><strong>.push</strong></span> and
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538316">3.14 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.pop</strong></span> directive</a></h3></div></div></div><p><span class="emphasis"><em>xfpt</em></span> keeps a stack of text strings that are manipulated by the <span class="bold"><strong>.push</strong></span> and
 <span class="bold"><strong>.pop</strong></span> directives. When the end of the input is reached, any strings that
 remain on the stack are popped off, processed for flags, and written to the
 output.
@@ -905,7 +966,7 @@ to and including the one that matches.
 </p><p>
 If <span class="bold"><strong>.pop</strong></span> is given without a following letter, it pops one string off the
 stack and writes it out. If there is nothing on the stack, an error occurs.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538104">3.14 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.push</strong></span> directive</a></h3></div></div></div><p>This directive pushes a string onto the stack. If the rest of the command line
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538377">3.15 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.push</strong></span> directive</a></h3></div></div></div><p>This directive pushes a string onto the stack. If the rest of the command line
 starts with an upper case letter followed by white space, that letter is
 associated with the string that is pushed, which consists of the rest of the
 line. For example, the <span class="bold"><strong>.chapter</strong></span> macro contains this line:
@@ -918,7 +979,7 @@ Earlier in the macro there is the line:
 </pre><p>
 This arrangement ensures that any previous chapter is terminated before
 starting a new one, and also when the end of the input is reached.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevision">3.15 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.revision</strong></span> directive</a></h3></div></div></div><p>This directive is provided to make it easy to set the <code class="literal">revisionflag</code>
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevision">3.16 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.revision</strong></span> directive</a></h3></div></div></div><p>This directive is provided to make it easy to set the <code class="literal">revisionflag</code>
 attribute on XML elements in a given portion of the document. The DocBook
 specification states that the <code class="literal">revisionflag</code> attribute is common to all
 elements.
@@ -947,8 +1008,8 @@ though it does still seem to process it correctly.
 </p><p>
 For handling the most common case (setting and unsetting “<span class="quote">changed</span>”), the
 standard macros <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.wen</strong></span> are provided (see section
-<a href="#SECTrevmacs" title="4.10&#xA0;Revision markings">4.10</a>).
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538330">3.16 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.set</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a name and a text string. It defines a user
+<a href="#SECTrevmacs" title="4.11&#xA0;Revision markings">4.11</a>).
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538603">3.17 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.set</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by a name and a text string. It defines a user
 variable and gives it a name. A reference to the name in the style of an XML
 entity causes the string to be substituted, without further processing. For
 example:
@@ -970,7 +1031,7 @@ is going to use these features should start with:
 All the standard macros except <span class="bold"><strong>new</strong></span>, <span class="bold"><strong>index</strong></span>, and <span class="bold"><strong>url</strong></span> are intended to
 be called as directive lines. Their names are therefore shown with a leading
 dot in the discussion below.
-</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538433">4.1 Overall setup</a></h3></div></div></div><p>There are two macros that should be used only once, at the start of the
+</p><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538706">4.1 Overall setup</a></h3></div></div></div><p>There are two macros that should be used only once, at the start of the
 document. The <span class="bold"><strong>.docbook</strong></span> macro has no arguments. It inserts into the output
 file the standard header material for a DocBook XML file, which is:
 </p><pre class="literallayout">
@@ -980,7 +1041,7 @@ file the standard header material for a DocBook XML file, which is:
 </pre><p>
 The <span class="bold"><strong>.book</strong></span> macro has no arguments. It generates <code class="literal">&lt;book&gt;</code> and pushes
 <code class="literal">&lt;/book&gt;</code> onto the stack so that it will be output at the end.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538490">4.2 Chapters, sections, and subsections</a></h3></div></div></div><p>Chapters, sections, and subsections are supported by three macros that all
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538763">4.2 Chapters, sections, and subsections</a></h3></div></div></div><p>Chapters, sections, and subsections are supported by three macros that all
 operate in the same way. They are <span class="bold"><strong>.chapter</strong></span>, <span class="bold"><strong>.section</strong></span>, and
 <span class="bold"><strong>.subsection</strong></span>. They take either one, two, or three arguments. The first
 argument is the title. If a second argument is present, and is not an empty
@@ -1012,7 +1073,10 @@ controlled by the stylesheet when the XML is processed.
 These three macros use the stack to ensure that each chapter, section, and
 subsection is terminated at the correct point. For example, starting a new
 section automatically terminates an open subsection and a previous section.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538597">4.3 URL references</a></h3></div></div></div><p>The <span class="bold"><strong>url</strong></span> macro generates URL references, and is intended to be called inline
+</p></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538870">4.3 Prefaces, appendixes, and colophons</a></h3></div></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">The macros <span class="bold"><strong>.preface</strong></span>, <span class="bold"><strong>.appendix</strong></span>, and <span class="bold"><strong>.colophon</strong></span> operate in the same 
+way as <span class="bold"><strong>.chapter</strong></span>, except that the first and the last have the default title
+strings “<span class="quote">Preface</span>” and “<span class="quote">Colophon</span>”.
+</p></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538917">4.4 URL references</a></h3></div></div></div><p>The <span class="bold"><strong>url</strong></span> macro generates URL references, and is intended to be called inline
 within the text that is being processed. It generates a <code class="literal">&lt;ulink&gt;</code> element,
 and has either one or two arguments. The first argument is the URL, and the
 second is the text that describes it. For example:
@@ -1027,7 +1091,7 @@ If the second argument is absent, the contents of the first argument are used
 instead. If <span class="bold"><strong>url</strong></span> is called as a directive, there will be a newline in the 
 output after <code class="literal">&lt;/ulink&gt;</code>, which in most cases (such as the example above), you 
 do not want.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538666">4.4 Itemized lists</a></h3></div></div></div><p>The <span class="bold"><strong>.ilist</strong></span> macro marks the start of an itemized list, the items of which
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538987">4.5 Itemized lists</a></h3></div></div></div><p>The <span class="bold"><strong>.ilist</strong></span> macro marks the start of an itemized list, the items of which
 are normally rendered with bullets or similar markings. The macro can
 optionally be called with one argument, for which there is no default. If the
 argument is present, it is used to add a <code class="literal">mark=</code> attribute to the
@@ -1046,7 +1110,7 @@ For example:
  .endlist
 </pre><p>
 There may be more than one paragraph in an item. 
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538740">4.5 Ordered lists</a></h3></div></div></div><p>The <span class="bold"><strong>.olist</strong></span> macro marks the start of an ordered list, the items of which are
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539061">4.6 Ordered lists</a></h3></div></div></div><p>The <span class="bold"><strong>.olist</strong></span> macro marks the start of an ordered list, the items of which are
 numbered. If no argument is given, arabic numerals are used. One of the
 following words can be given as the macro’s argument to specify the numeration:
 </p><div class="literallayout">
@@ -1067,7 +1131,7 @@ For example:
  .endlist
 </pre><p>
 There may be more than one paragraph in an item.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538833">4.6 Variable lists</a></h3></div></div></div><p>A variable list is one in which each entry is composed of a set of one or more
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539153">4.7 Variable lists</a></h3></div></div></div><p>A variable list is one in which each entry is composed of a set of one or more
 terms and an associated description. Typically, the terms are printed in a
 style that makes them stand out, and the description is indented underneath.
 The start of a variable list is indicated by the <span class="bold"><strong>.vlist</strong></span> macro, which has
@@ -1085,12 +1149,12 @@ This is followed by the body of the entry. The list is terminated by the
  .endlist
 </pre><p>
 As for the other lists, there may be more than one paragraph in an item.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538887">4.7 Nested lists</a></h3></div></div></div><p>Lists may be nested as required. Some DocBook processors automatically choose
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539208">4.8 Nested lists</a></h3></div></div></div><p>Lists may be nested as required. Some DocBook processors automatically choose
 different bullets for nested itemized lists, but others do not. The
 <span class="bold"><strong>.endlist</strong></span> macro has no useful arguments. Any text that follows it is
 treated as a comment. This can provide an annotation facility that may make the
 input easier to understand when lists are nested.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2538909">4.8 Displayed text</a></h3></div></div></div><p>In displayed text each non-directive input line generates one output line. The
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539230">4.9 Displayed text</a></h3></div></div></div><p>In displayed text each non-directive input line generates one output line. The
 <code class="literal">&lt;literallayout&gt;</code> DocBook element is used to achieve this. Two kinds of
 displayed text are supported by the standard macros. They differ in their
 handling of the text itself.
@@ -1121,10 +1185,10 @@ monospaced font. For example:
 </pre><p>
 As the examples illustrate, both kinds of display are terminated by the
 <span class="bold"><strong>.endd</strong></span> macro.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539021">4.9 Block quotes</a></h3></div></div></div><p>The macro pair <span class="bold"><strong>.blockquote</strong></span> and <span class="bold"><strong>.endblockquote</strong></span> are used to wrap the
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539342">4.10 Block quotes</a></h3></div></div></div><p>The macro pair <span class="bold"><strong>.blockquote</strong></span> and <span class="bold"><strong>.endblockquote</strong></span> are used to wrap the
 lines between them in a <code class="literal">&lt;blockquote&gt;</code> element.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevmacs">4.10 Revision markings</a></h3></div></div></div><p>Two macros are provided to simplify setting and unsetting the “<span class="quote">changed</span>”
-revision marking (see section <a href="#SECTrevision" title="3.15&#xA0;The .revision directive">3.15</a>). When the revised text is
+</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevmacs">4.11 Revision markings</a></h3></div></div></div><p>Two macros are provided to simplify setting and unsetting the “<span class="quote">changed</span>”
+revision marking (see section <a href="#SECTrevision" title="3.16&#xA0;The .revision directive">3.16</a>). When the revised text is
 substantial (for example, a complete paragraph, table, display, or section), it
 can be placed between <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.wen</strong></span>, as in this example:
 </p><pre class="literallayout">
@@ -1170,7 +1234,11 @@ This usage works with both <span class="bold"><strong>.display</strong></span> a
 section you can also call <span class="bold"><strong>.new</strong></span> with an argument, either as a directive or 
 inline. This does not work for <span class="bold"><strong>.code</strong></span> because its lines are processed in
 literal text mode.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539248">4.11 Informal tables</a></h3></div></div></div><p>The <span class="bold"><strong>.itable</strong></span> macro starts an informal (untitled) table with some basic
+</p><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+If you want to add revision indications to part of a table, you must use an
+inline call of <span class="bold"><strong>new</strong></span> within an argument of the <span class="bold"><strong>.row</strong></span> macro (see below).
+This is the only usage that works in this case.
+</p></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539589">4.12 Informal tables</a></h3></div></div></div><p>The <span class="bold"><strong>.itable</strong></span> macro starts an informal (untitled) table with some basic
 parameterization. If you are working on a large document that has many tables
 with the same parameters, the best approach is to define your own table macros,
 possibly calling the standard one with specific arguments.
@@ -1210,14 +1278,76 @@ which has no arguments. For example:
 </pre><p>
 This specifies a framed table, with both column and row separator lines. There
 are two columns: the first is one inch wide and left aligned, and the second is
-two inches wide and centred. There are two rows. The output looks like this:
+two inches wide and centred. There are two rows. The resulting table looks like
+this:
 </p><div class="informaltable"><table border="1"><colgroup><col align="left" /><col align="center" /></colgroup><tbody><tr><td align="left">cell 11</td><td align="center">cell 12</td></tr><tr><td align="left">cell 21</td><td align="center">cell 22</td></tr></tbody></table></div><p>
 The <span class="bold"><strong>.row</strong></span> macro does not set the <code class="literal">revisionflag</code> attribute in the 
 <code class="literal">&lt;entry&gt;</code> elements that it generates because this appears to be ignored by 
 all current XML processors. However, you can use an inline call of the <span class="bold"><strong>new</strong></span> 
 macro within an entry to generate a <code class="literal">&lt;phrase&gt;</code> element with <code class="literal">revisionflag</code> 
 set.
-</p></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539524">4.12 Indexes</a></h3></div></div></div><p>The <span class="bold"><strong>.index</strong></span> macro generates <code class="literal">&lt;indexterm&gt;</code> elements (index entries) in the
+</p></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539865">4.13 Formal tables</a></h3></div></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">The <span class="bold"><strong>.table</strong></span> macro starts a formal table, that is, a table that has a title, 
+and which can be cross referenced. The first argument of this macro is the 
+table’s title; the second is an identifier for cross-referencing. If you are 
+not going to reference the table, an empty string must be supplied. From the 
+third argument onwards, the arguments are identical to the <span class="bold"><strong>.itable</strong></span> macro.
+For example:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ .table "A title for the table" "" all 1 1 2 1in left 2in center
+ .row "cell 11" "cell 12"
+ .row "cell 21" "cell 22"
+ .endtable
+</pre></div></div></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2539922">4.14 Figures and images</a></h3></div></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">A figure is enclosed between <span class="bold"><strong>.figure</strong></span> and <span class="bold"><strong>.endfigure</strong></span> macros. The first 
+argument of <span class="bold"><strong>.figure</strong></span> provides a title for the figure. The second is 
+optional; if present, it is a tag for references to the figure.
+</p></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+A figure normally contains an image. The <span class="bold"><strong>.image</strong></span> macro can be used in simple 
+cases. It generates a <code class="literal">&lt;mediaobject&gt;</code> element containing an
+<code class="literal">&lt;imageobject&gt;</code>. The first argument is the name of the file containing the 
+image. The remaining arguments are optional; if any one is not needed, an empty 
+string must be supplied as a placeholder.
+</p></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="itemizedlist"><ul type="disc"><li><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+The second argument specifies a scaling factor for the image, as a percentage. 
+Thus, a value of 50 reduces the image to half size.
+</p></div></li><li><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+The third argument specifies an alignment for the image. It must be one of 
+<code class="literal">left</code>, <code class="literal">right</code> or <code class="literal">center</code> (or even <code class="literal">centre</code> if the DocBook processor 
+you are using can handle it).
+</p></div></li><li><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+The fourth and fifth arguments specify the depth and width, respectively. How 
+these values are handled depends on the processing software.
+</p></div></li></ul></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+Here is an example of the input for a figure, with all the image options 
+defaulted:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ .figure "My figure's title" "FIGfirst"
+ .image figure01.eps
+ .endfigure
+</pre></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+Here is another example, where the figure is reduced to 80% and centred:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ .figure "A reduced figure"
+ .image figure02.eps 80 center
+ .endfigure  
+</pre></div></div></div><div xmlns="" class="changed"><div xmlns="http://www.w3.org/1999/xhtml" class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2540084">4.15 Footnotes</a></h3></div></div></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">Footnotes can be specified between <span class="bold"><strong>.footnote</strong></span> and <span class="bold"><strong>.endnote</strong></span> macros. 
+Within a footnote there can be any kind of text item, including displays and 
+tables. When a footnote occurs in the middle of a paragraph, paired flags 
+must not straddle the footnote. This example is wrong:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ The &amp;'quick
+ .footnote
+ That's really fast.
+ .endf
+ brown'&amp; fox.
+</pre></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+The correct markup for this example is:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ The &amp;'quick'&amp;
+ .footnote
+ That's really fast.
+ .endf
+ &amp;'brown'&amp; fox.
+</pre></div></div></div><div class="section" lang="en" xml:lang="en"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="id2540145">4.16 Indexes</a></h3></div></div></div><p>The <span class="bold"><strong>.index</strong></span> macro generates <code class="literal">&lt;indexterm&gt;</code> elements (index entries) in the
 output. It takes one or two arguments. The first is the text for the primary
 index term, and the second, if present, specifies a secondary index term. This
 macro can be called either from a directive line, or inline. However, it is
@@ -1226,10 +1356,20 @@ example:
 </p><pre class="literallayout">
  .index goose "wild chase"
  The chasing of wild geese...
-</pre><p>
+</pre><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
 You can generate “<span class="quote">see</span>” and “<span class="quote">see also</span>” index entries by using <span class="bold"><strong>.index-see</strong></span> 
-and <span class="bold"><strong>.index-seealso</strong></span> instead of <span class="bold"><strong>.index</strong></span>.
-</p><p>
+and <span class="bold"><strong>.index-seealso</strong></span> instead of <span class="bold"><strong>.index</strong></span>. The first argument of these 
+macros is the text for the “<span class="quote">see</span>”. For example:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ .index-see "chase" "wild goose"
+</pre></div><div xmlns="" class="changed"><p xmlns="http://www.w3.org/1999/xhtml">
+This generates:
+</p></div><div xmlns="" class="changed"><pre xmlns="http://www.w3.org/1999/xhtml" class="literallayout">
+ &lt;indexterm&gt;
+ &lt;primary&gt;wild goose&lt;/primary&gt;
+ &lt;see&gt;chase&lt;/see&gt;
+ &lt;/indexterm&gt;
+</pre></div><p>
 If you want to generate an index entry for a range of pages, you can use the 
 <span class="bold"><strong>.index-from</strong></span> and <span class="bold"><strong>.index-to</strong></span> macros. The first argument of each of them is 
 an ID that ties them together. The second and third arguments of 
diff --git a/doc/xfpt.pdf b/doc/xfpt.pdf
index 8e2dc330c..c585068d8 100644
--- a/doc/xfpt.pdf
+++ b/doc/xfpt.pdf
diff --git a/doc/xfpt.xfpt b/doc/xfpt.xfpt
index b2e5d3cb0..71d54bceb 100644
--- a/doc/xfpt.xfpt
+++ b/doc/xfpt.xfpt
@@ -13,13 +13,13 @@
 <bookinfo>
 <title>The xfpt plain text to XML processor</title>
 <titleabbrev>xfpt</titleabbrev>
-<date>10 April 2007</date>
+<date>03 July 2007</date>
 <author>
   <firstname>Philip</firstname>
   <surname>Hazel</surname>
 </author>
 <authorinitials>PH</authorinitials>
-<revhistory><revision><revnumber>0.02</revnumber><date>10 April 2007</date><authorinitials>PH</authorinitials></revision></revhistory>
+<revhistory><revision><revnumber>0.03</revnumber><date>03 July 2007</date><authorinitials>PH</authorinitials></revision></revhistory>
 <copyright><year>2007</year><holder>University of Cambridge</holder></copyright>
 </bookinfo>
 .literal off
@@ -78,7 +78,7 @@ closing quotes, as follows:
 .endd
 
 Within normal input text, ampersand, grave accent, and apostrophe are the only
-characters that cause &X; to change the input text, and this applies only to
+characters that cause &X; to change the input text, but this applies only to
 non-literal text. In literal text, there are no markup characters, and only a
 dot at the start of a line is recognized as special. Within the body of a
 macro, there is one more special character: the dollar character is used to
@@ -95,26 +95,29 @@ The format of the &X; command line is:
 .display
  &`xfpt [`&&'options'&&`] [`&&'input source'&&`]`&
 .endd
-If no input is specified, the standard input is read. There are three options:
-.display
- &`-help`&
-.endd
+If no input is specified, the standard input is read. There are four options:
+
+.vlist
+.vitem &%-help%&
 This option causes &X; to output its &"usage"& message, and exit.  
   
-.display
- &`-o `&&'<output destination>'&
-.endd
+.vitem "&%-o%&&~&'<output destination>'&"
 This option overrides the default destination. If the standard input is being
 read, the default destination is the standard output. Otherwise, the default
 destination is the name of the input file with the extension &_.xml_&,
 replacing its existing extension if there is one. A single hyphen character can
 be given as an output destination to refer to the standard output.
-.display
-  &`-S `&&'<directory path>'&
-.endd
+
+.vitem "&%-S%&&~&'<directory path>'&"
 This option overrides the path to &X;'s library directory that is built into
 the program. This makes it possible to use or test alternate libraries.
 
+.new
+.vitem &%-v%&
+This option causes &X; to output its version number and exit.
+.wen  
+.endlist
+
 
 .section "A short &X; example"
 Here is a very short example of a complete &X; input file that uses some of the
@@ -138,8 +141,8 @@ standard macros and flags:
  .endlist
 
  There are also standard macros for ordered lists, literal
- layout blocks, code blocks, URL references, index entries
- and tables.
+ layout blocks, code blocks, URL references, index entries,
+ tables, footnotes, figures, etc.
 .endd
 
 
@@ -149,9 +152,14 @@ standard macros and flags:
 &"modes"&):
 
 .ilist
-In the default mode, text is processed paragraph by paragraph. The end of a
-paragraph is indicated by the end of the input, a blank line, or by an
-occurrence of the &*.literal*& directive. Other directives (for example,
+In the default mode, text is processed paragraph by paragraph. 
+.footnote
+&new("There is, however, a special case when a paragraph contains one or more 
+footnotes. In that situation, each part of the outer paragraph is processed 
+independently.")
+.endnote
+The end of a paragraph is indicated by the end of the input, a blank line, or
+by an occurrence of the &*.literal*& directive. Other directives (for example,
 &*.include*&) do not of themselves terminate a paragraph. Most of the standard
 macros (such as &*.chapter*& and &*.section*&) force a paragraph end by
 starting their contents with a &*.literal*& directive.
@@ -160,13 +168,15 @@ Because &X; reads a whole paragraph before processing it, error messages
 contain the phrase &"detected near line &'nnn'&"&, where the line number is
 typically that of the last line of the paragraph.
 
+
 .next
 In the &"literal layout"& mode, text is processed line by line, but is
 otherwise handled as in the default mode. The only real difference this makes
-to the markup from the user's point of view is that paired flags must be on the
-same line. In this mode, error messages are more likely to contain the exact
-line number where the fault lies. Literal layout mode is used by the standard
-&*.display*& macro to generate &`<literallayout>`& elements.
+to the markup from the user's point of view is that both parts of a set of
+paired flags must be on the same line. In this mode, error messages are more
+likely to contain the exact line number where the fault lies. Literal layout
+mode is used by the standard &*.display*& macro to generate &`<literallayout>`&
+elements.
 
 .next
 In the &"literal text"& mode, text is also processed line by line, but no flags
@@ -347,20 +357,26 @@ non-alphanumeric characters. When it is encountered, it is replaced by its
 replacement text. For example, in the standard flag definitions, &`&&&&`&
 is defined as a standalone flag with with the replacement text &`&&amp;`&.
 
+.new
 A paired flag is defined as two sequences. The first takes the same form as a
 standalone flag. The second also consists of non-alphanumeric characters, but
 need not start with an ampersand. It is often defined as the reverse of the
-first sequence. When the first sequence of a paired flag is encountered, its
-partner is expected to be found within the same paragraph (or line, in literal
-layout mode). Furthermore, multiple occurrences of paired flags must be
-correctly nested. For example, in the standard definitions, &`&&&#x27;`& and
+first sequence. For example, in the standard definitions, &`&&&#x27;`& and
 &`&#x27;&&`& are defined as a flag pair for enclosing text in an &`<emphasis>`&
-element. Each member of the pair is replaced by its replacement text.
+element.
 
-Note that, though &X; diagnoses an error for badly nested flag pairs, it does
-not prevent you from generating invalid XML. For example, DocBook does not
-allow &`<emphasis>`& within &`<literal>`&, though it does allow &`<literal>`&
-within &`<emphasis>`&.
+When the first sequence of a paired flag is encountered, its partner is
+expected to be found within the same text unit. In the default mode, the units
+are a paragraphs, or part-paragraphs if footnotes intervene. In literal layout
+mode, the text is processed line by line. Each member of the pair is replaced
+by its replacement text. 
+.wen
+
+Multiple occurrences of paired flags must be correctly nested. Note that,
+though &X; diagnoses an error for badly nested flag pairs, it does not prevent
+you from generating invalid XML. For example, DocBook does not allow
+&`<emphasis>`& within &`<literal>`&, though it does allow &`<literal>`& within
+&`<emphasis>`&.
 
 .section "Unrecognized flag sequences"
 If an ampersand is not followed by a character sequence in one of the forms
@@ -401,7 +417,7 @@ convenient.
 . ----------------------------------------------------------------------------
 .chapter "Built-in directive processing"
 The directives that are built into the code of &X; are now described in
-alphabetical order. You can see more examples of their use in the definitions
+alphabetical order. You can see more examples of their use in the descriptions
 of the standard macros in chapter &<<CHAPstdmac>>&.
 
 
@@ -427,6 +443,12 @@ for the given argument. For example:
  .endarg 
  .endmacro
 .endd
+.new
+Note that if a macro is defined with default values for its arguments, these
+are not counted by the &*.arg*& directive, which looks only at the actual
+arguments in a particular macro call.
+.wen
+
 The &*.arg*& directive may be nested.
 
 
@@ -435,7 +457,9 @@ This directive may appear only within the body of a macro. It may optionally be
 followed by a single number; if omitted the value is taken to be 1. Subsequent
 lines, up to a &*.endeach*& directive, are processed multiple times, once for
 each remaining argument. Unlike &*.arg*&, an argument that is an empty string 
-is not treated specially.
+is not treated specially. &new("However, like &*.arg*&, only the actual
+arguments of a macro call are considered. Default argument values do not 
+count.")
 
 The number given with &*.eacharg*& defines which argument to start with. If the
 macro is called with fewer arguments, the lines up to &*.endeach*& are skipped,
@@ -482,6 +506,7 @@ See the description of &*.arg*& above.
 .section "The &*.endeach*& directive"
 See the description of &*.eacharg*& above.
 
+
 .section "The &*.endinliteral*& directive"
 See the description of &*.inliteral*& below.
 
@@ -505,6 +530,7 @@ a file. The contents of the file are read and incorporated into the input at
 this point. If the string does not contain any slashes, the path to the &X;
 library is prepended. Otherwise, the path is used unaltered.
 
+
 .section "The &*.inliteral*& directive"
 This directive may appear only within the body of a macro. It must be followed 
 by one of the words &"layout"&, &"text"&, &"off"&, or &"xml"&. If the current 
@@ -578,6 +604,26 @@ taken with argument references to ensure that substitutions happen at the right
 level.
 
 
+.new
+.section "The &*.nest*& directive"
+This directive must be followed by one of the words &"begin"& or &"end"&. It is
+used to delimit a nested sequence of independent text items that occurs inside
+another, such as the contents of a footnote inside a paragraph. This directive
+is usually used inside a macro. For example, a &*footnote*& macro could be
+defined like this:
+.code
+ .macro footnote
+ &<footnote>&
+ .nest begin
+ .endmacro
+.endd
+At the start of a nested sequence, the current mode and paragraph state are
+remembered and &X; then reverts to the default mode and &"not in a paragraph"&.
+At the end of a nested sequence, if a paragraph has been started, it is
+terminated, and then &X; reverts to the previous state.
+.wen
+
+
 .section "The &*.nonl*& directive"
 This directive must be followed by a single string argument. It is processed 
 as normal text, but without a newline at the end. This facility is useful in 
@@ -585,7 +631,6 @@ macros when constructing a single data line from several text fragments. See
 for example the &*.new*& macro in the standard macros.
 
 
-
 .section "The &*.pop*& directive"
 &X; keeps a stack of text strings that are manipulated by the &*.push*& and
 &*.pop*& directives. When the end of the input is reached, any strings that
@@ -728,6 +773,13 @@ subsection is terminated at the correct point. For example, starting a new
 section automatically terminates an open subsection and a previous section.
 
 
+.new
+.section "Prefaces, appendixes, and colophons"
+The macros &*.preface*&, &*.appendix*&, and &*.colophon*& operate in the same 
+way as &*.chapter*&, except that the first and the last have the default title
+strings &"Preface"& and &"Colophon"&.
+.wen
+
 
 .section "URL references"
 The &*url*& macro generates URL references, and is intended to be called inline
@@ -914,6 +966,12 @@ section you can also call &*.new*& with an argument, either as a directive or
 inline. This does not work for &*.code*& because its lines are processed in
 literal text mode.
 
+.new
+If you want to add revision indications to part of a table, you must use an
+inline call of &*new*& within an argument of the &*.row*& macro (see below).
+This is the only usage that works in this case.
+.wen
+
 
 .section "Informal tables"
 The &*.itable*& macro starts an informal (untitled) table with some basic
@@ -958,7 +1016,8 @@ which has no arguments. For example:
 
 This specifies a framed table, with both column and row separator lines. There
 are two columns: the first is one inch wide and left aligned, and the second is
-two inches wide and centred. There are two rows. The output looks like this:
+two inches wide and centred. There are two rows. The resulting table looks like
+this:
 
 .itable all 1 1 2 1in left 2in center
 .row "cell 11" "cell 12"
@@ -972,6 +1031,85 @@ macro within an entry to generate a &`<phrase>`& element with &`revisionflag`&
 set.
 
 
+.new
+.section "Formal tables"
+The &*.table*& macro starts a formal table, that is, a table that has a title, 
+and which can be cross referenced. The first argument of this macro is the 
+table's title; the second is an identifier for cross-referencing. If you are 
+not going to reference the table, an empty string must be supplied. From the 
+third argument onwards, the arguments are identical to the &*.itable*& macro.
+For example:
+
+.code
+ .table "A title for the table" "" all 1 1 2 1in left 2in center
+ .row "cell 11" "cell 12"
+ .row "cell 21" "cell 22"
+ .endtable
+.endd
+
+
+.section "Figures and images"
+A figure is enclosed between &*.figure*& and &*.endfigure*& macros. The first 
+argument of &*.figure*& provides a title for the figure. The second is 
+optional; if present, it is a tag for references to the figure.
+
+A figure normally contains an image. The &*.image*& macro can be used in simple 
+cases. It generates a &`<mediaobject>`& element containing an
+&`<imageobject>`&. The first argument is the name of the file containing the 
+image. The remaining arguments are optional; if any one is not needed, an empty 
+string must be supplied as a placeholder.
+
+.ilist
+The second argument specifies a scaling factor for the image, as a percentage. 
+Thus, a value of 50 reduces the image to half size.
+.next
+The third argument specifies an alignment for the image. It must be one of 
+&`left`&, &`right`& or &`center`& (or even &`centre`& if the DocBook processor 
+you are using can handle it).
+.next
+The fourth and fifth arguments specify the depth and width, respectively. How 
+these values are handled depends on the processing software.
+.endlist
+
+Here is an example of the input for a figure, with all the image options 
+defaulted:
+.code
+ .figure "My figure's title" "FIGfirst"
+ .image figure01.eps
+ .endfigure
+.endd    
+
+Here is another example, where the figure is reduced to 80% and centred:
+.code
+ .figure "A reduced figure"
+ .image figure02.eps 80 center
+ .endfigure  
+.endd
+
+
+.section "Footnotes"
+Footnotes can be specified between &*.footnote*& and &*.endnote*& macros. 
+Within a footnote there can be any kind of text item, including displays and 
+tables. When a footnote occurs in the middle of a paragraph, paired flags 
+must not straddle the footnote. This example is wrong:
+.code
+ The &'quick
+ .footnote
+ That's really fast.
+ .endf
+ brown'& fox.
+.endd
+The correct markup for this example is:
+.code
+ The &'quick'&
+ .footnote
+ That's really fast.
+ .endf
+ &'brown'& fox.
+.endd
+.wen
+
+
 .section "Indexes"
 The &*.index*& macro generates &`<indexterm>`& elements (index entries) in the
 output. It takes one or two arguments. The first is the text for the primary
@@ -983,8 +1121,21 @@ example:
  .index goose "wild chase"
  The chasing of wild geese...
 .endd
+.new
 You can generate &"see"& and &"see also"& index entries by using &*.index-see*& 
-and &*.index-seealso*& instead of &*.index*&.
+and &*.index-seealso*& instead of &*.index*&. The first argument of these 
+macros is the text for the &"see"&. For example:
+.code
+ .index-see "chase" "wild goose"
+.endd
+This generates:
+.code
+ <indexterm>
+ <primary>wild goose</primary>
+ <see>chase</see>
+ </indexterm>
+.endd  
+.wen
 
 If you want to generate an index entry for a range of pages, you can use the 
 &*.index-from*& and &*.index-to*& macros. The first argument of each of them is 
@@ -1026,6 +1177,4 @@ indexes to be generated. The first is entitled &"Concept index"&, and contains
 only those index entries that were generated by the &*.cindex*& macro. The 
 second contains all index entries.
 
-
-
 . === End ===
diff --git a/share/stdmacs b/share/stdmacs
index 662dae6cc..6808f7d99 100644
--- a/share/stdmacs
+++ b/share/stdmacs
@@ -17,6 +17,19 @@
 .literal off
 .endmacro
 
+.macro preface "Preface"
+.literal layout
+.pop C
+.push C
+.push &</preface>&
+&<preface$=2+ id="$2"+&xfpt.rev;>&
+&<title>&$1&</title>&
+.arg 3
+&<titleabbrev>&$3&</titleabbrev>&
+.endarg
+.literal off
+.endmacro
+
 .macro chapter
 .literal layout
 .pop C
@@ -32,6 +45,34 @@
 .literal off
 .endmacro
 
+.macro appendix
+.literal layout
+.pop C
+.push C
+.push &</appendix>&
+&<appendix$=2+ id="$2"+&xfpt.rev;>&
+.arg 1
+&<title>&$1&</title>&
+.endarg
+.arg 3
+&<titleabbrev>&$3&</titleabbrev>&
+.endarg
+.literal off
+.endmacro
+
+.macro colophon "Colophon"
+.literal layout
+.pop C
+.push C
+.push &</colophon>&
+&<colophon$=2+ id="$2"+&xfpt.rev;>&
+&<title>&$1&</title>&
+.arg 3
+&<titleabbrev>&$3&</titleabbrev>&
+.endarg
+.literal off
+.endmacro
+
 .macro section
 .literal layout
 .pop S
@@ -150,8 +191,9 @@
 
 . =============== Tables ===============
 
-.macro itable "none" "0" "0" "2" "1*" "left" "1*" "left"
+.macro itable "none" "0" "0" "2"
 .literal layout
+.push &</informaltable>&
 &<informaltable frame="$1"&xfpt.rev;>&
 &<tgroup cols="$4" colsep="$2" rowsep="$3">&
 .eacharg 5
@@ -160,6 +202,20 @@
 &<tbody>&
 .endmacro
 
+.macro table "title" "ref" "none" "0" "0" "2"
+.literal layout
+.push &</table>&
+&<table$=2+ id="$2"+ $=3+frame="$3"+&xfpt.rev;>&
+.arg 1
+&<title>&$1&</title>&
+.endarg
+&<tgroup cols="$6" colsep="$4" rowsep="$5">&
+.eacharg 7
+&<colspec colwidth="$+1" align="$+2"/>&
+.endeach 2
+&<tbody>&
+.endmacro
+
 .macro row
 .literal layout
 &<row>&
@@ -173,7 +229,7 @@
 .literal layout
 &</tbody>&
 &</tgroup>&
-&</informaltable>&
+.pop
 .literal off
 .endmacro
 
@@ -285,4 +341,47 @@
 .endinliteral
 .endmacro
 
+. =============== Footnotes ===============
+
+.macro footnote
+&<footnote>&
+.push &</footnote>&
+.nest begin
+.endmacro
+
+.macro endnote
+.nest end
+.pop
+.endmacro
+
+. =============== Figures ===============
+
+.macro figure
+.literal layout
+&<figure$=2+ id="$2"+&xfpt.rev;>&
+.arg 1
+&<title>&$1&</title>&
+.endarg
+.literal off
+.endmacro
+
+.macro endfigure
+.literal layout
+&</figure>&
+.literal off
+.endmacro
+
+. =============== Images ===============
+
+. This is a complete image wrapped inside a <mediaobject>.
+.
+.macro image
+.literal layout
+&<mediaobject>&&<imageobject>&
+&<imagedata fileref="$1" $=2+ scale="$2"+$=3+ align="$3"+&&&
+  $=4+ depth="$4"+$=5+ width="$5"+>&
+&</imagedata>&&</imageobject>&&</mediaobject>&
+.literal off
+.endmacro
+
 . End
diff --git a/src/dot.c b/src/dot.c
index 3c87166e3..f30fab818 100644
--- a/src/dot.c
+++ b/src/dot.c
@@ -503,6 +503,40 @@ if (md->lines == NULL)
 
 
 /*************************************************
+*               Handle .nest                     *
+*************************************************/
+
+/* This processing happens when .nest is encountered when not in the middle of
+reading a normal paragraph. That is, it's either between paragraphs or in a
+literal section. Otherwise .nest is handled in read_paragraph().
+
+Argument: the rest of the line
+Returns:  nothing
+*/
+
+static void
+do_nest(uschar *p)
+{
+if (Ustrcmp(p, "begin") == 0)
+  {
+  if (nest_level >= MAXNEST) error(27); else
+    {
+    nest_literal_stack[nest_level++] = literal_state;
+    literal_state = LITERAL_OFF;
+    }
+  }
+else if (Ustrcmp(p, "end") == 0)
+  {
+  if (nest_level <= 0) error(28);
+    else literal_state = nest_literal_stack[--nest_level];
+  }
+else error(26, p);
+}
+
+
+
+
+/*************************************************
 *               Handle .nonl                     *
 *************************************************/
 
@@ -700,6 +734,7 @@ static dirstr dirs[] = {
   { US".inliteral",    10, do_inliteral,     TRUE,  TRUE },
   { US".literal",       8, do_literal,       TRUE, FALSE },
   { US".macro",         6, do_macro,        FALSE, FALSE },
+  { US".nest",          5, do_nest,          TRUE, FALSE },
   { US".nonl",          5, do_nonl,          TRUE, FALSE },
   { US".pop",           4, do_pop,           TRUE, FALSE },
   { US".push",          5, do_push,         FALSE, FALSE },
diff --git a/src/error.c b/src/error.c
index 3aa800742..b98715be0 100644
--- a/src/error.c
+++ b/src/error.c
@@ -73,10 +73,13 @@ static error_struct error_data[] = {
 { ec_serious,  "unknown macro \"%.*s\" in inline macro call" },
 { ec_serious,  "missing closing parenthesis in inline macro call:\n   %s" },
 /* 25-29 */
-{ ec_serious,  "ampersand found at end of line or string - ignored" }
+{ ec_serious,  "ampersand found at end of line or string - ignored" },
+{ ec_serious,  "\"begin\" or \"end\" expected, but \"%s\" found" },
+{ ec_serious,  "\".nest begin\" too deeply nested" },
+{ ec_serious,  "\".nest end\" incorrectly nested" }
 };
 
-#define error_maxerror 25
+#define error_maxerror 28
 
 
 
diff --git a/src/functions.h b/src/functions.h
index 53de12acc..696ba4604 100644
--- a/src/functions.h
+++ b/src/functions.h
@@ -2,7 +2,7 @@
 *     xfpt - Simple ASCII->Docbook processor     *
 *************************************************/
 
-/* Copyright (c) University of Cambridge, 2006 */
+/* Copyright (c) University of Cambridge, 2007 */
 /* Written by Philip Hazel. */
 
 /* This header defines all the global functions. */
@@ -19,7 +19,7 @@ extern uschar     *misc_readstring(uschar *, int *, uschar *, int);
 extern void        para_process(uschar *);
 
 extern uschar     *read_nextline(void);
-extern uschar     *read_paragraph(uschar *);
+extern uschar     *read_paragraph(uschar *, int *);
 extern void        read_process_macroline(uschar *, uschar *);
 
 extern int         tree_insertnode(tree_node **, tree_node *);
diff --git a/src/globals.c b/src/globals.c
index 697335d9b..7140ea876 100644
--- a/src/globals.c
+++ b/src/globals.c
@@ -11,7 +11,7 @@
 
 
 uschar    *xfpt_share                = US DATADIR;
-uschar    *xfpt_version              = US "0.02 05-Apr-2007";
+uschar    *xfpt_version              = US "0.03 02-July-2007";
 
 tree_node *entities                  = NULL;
 
@@ -22,6 +22,9 @@ istackstr *istack                    = NULL;
 
 int        literal_state             = LITERAL_OFF;
 
+int        nest_level                = 0;
+int        nest_literal_stack[MAXNEST+1];
+
 macroexe  *macrocurrent              = NULL;
 macrodef  *macrolist                 = NULL;
 
diff --git a/src/globals.h b/src/globals.h
index c8045105a..ce779b32b 100644
--- a/src/globals.h
+++ b/src/globals.h
@@ -24,6 +24,9 @@ extern istackstr  *istack;
 
 extern int         literal_state;
 
+extern int         nest_level;
+extern int         nest_literal_stack[];
+
 extern macroexe   *macrocurrent;
 extern macrodef   *macrolist;
 
diff --git a/src/read.c b/src/read.c
index 7a06eec4a..73b4fffc0 100644
--- a/src/read.c
+++ b/src/read.c
@@ -310,18 +310,27 @@ return inbuffer;
 
 /* This function is called after a line has been identified as the start of a
 paragraph. We need to read the rest so that flags can be matched across the
-entire paragraph. The whole is copied into the paragraph buffer. Directives
-that are encountered in the paragraph are processed, with the exception of
-.literal, which terminates it. We leave a .literal directive in the input
-buffer and set next_line to point to it, so that it is processed later.
+entire paragraph. (If there is nested material such as a footnote, this applies
+only to the separate parts, not across the nesting.) The text is copied into
+the paragraph buffer. Directives that are encountered in the paragraph are
+processed, with two exceptions.
 
-Arguments:  the first line
-Returns:    the paragraph
+(1) For .literal, we set next_line so it is processed next, and exit. This is
+the end of the paragraph.
+
+(2) For .nest, we set *nest_info, according to whether it is the start or
+end of a nested section, and exit.
+
+Arguments:
+  p           the first line
+  nest_info   returns NEST_NO, NEST_START, or NEST_END
+
+Returns:      the paragraph
 */
 
 
 uschar *
-read_paragraph(uschar *p)
+read_paragraph(uschar *p, int *nest_info)
 {
 uschar *q = parabuffer;
 int length = Ustrlen(p);
@@ -329,6 +338,8 @@ int length = Ustrlen(p);
 memcpy(q, p, length);
 q += length;
 
+*nest_info = NEST_NO;    /* Not hit .nest */
+
 for (;;)
   {
   uschar *s;
@@ -341,6 +352,19 @@ for (;;)
     break;
     }
 
+  if (Ustrncmp(p, ".nest ", 6) == 0)
+    {
+    p += 6;
+    while (isspace(*p)) p++;
+    s = p + Ustrlen(p);
+    while (s > p && isspace(s[-1])) s--;
+    *s = 0;
+    if (Ustrcmp(p, "begin") == 0) *nest_info = NEST_BEGIN;
+    else if (Ustrcmp(p, "end") == 0) *nest_info = NEST_END;
+    else error(26, p);
+    break;
+    }
+
   else if (*p == '.')
     {
     dot_process(p);
diff --git a/src/xfpt.c b/src/xfpt.c
index 7c5b59744..8bdd0e8fa 100644
--- a/src/xfpt.c
+++ b/src/xfpt.c
@@ -19,6 +19,8 @@ static uschar *xfpt_filename = NULL;
 static uschar *out_filename = NULL;
 
 
+
+
 /*************************************************
 *                  Usage                         *
 *************************************************/
@@ -112,10 +114,10 @@ return TRUE;
 *          Entry point and main program          *
 *************************************************/
 
-
 int
 main(int argc, char **argv)
 {
+BOOL para_unfinished[MAXNEST+1];
 uschar *p, *q;
 
 if (!xfpt_decode_arg(argc, argv)) return EXIT_FAILURE;
@@ -157,6 +159,9 @@ else
 
 /* Process the input */
 
+nest_level = 0;
+para_unfinished[0] = FALSE;
+
 while ((p = read_nextline()) != NULL)
   {
   if (*p == '.') dot_process(p); else switch (literal_state)
@@ -179,18 +184,39 @@ while ((p = read_nextline()) != NULL)
     while (isspace(*q)) q++;
     if (*q != 0)
       {
-      p = read_paragraph(p);
-      (void)fprintf(outfile, "<");
-      para_process(US"para&xfpt.rev;");
-      (void)fprintf(outfile, ">\n");
+      int nest_info;
+      p = read_paragraph(p, &nest_info);
+      if (!para_unfinished[nest_level])
+        {
+        (void)fprintf(outfile, "<");
+        para_process(US"para&xfpt.rev;");
+        (void)fprintf(outfile, ">\n");
+        }
+
       para_process(p);
-      (void)fprintf(outfile, "</para>\n");
+      if (nest_info == NEST_BEGIN)
+        {
+        if (nest_level >= MAXNEST) error(27); else
+          {
+          nest_literal_stack[nest_level] = literal_state;
+          para_unfinished[nest_level++] = TRUE;
+          }
+        }
+      else (void)fprintf(outfile, "</para>\n");
+
+      para_unfinished[nest_level] = FALSE;
+
+      if (nest_info == NEST_END)
+        {
+        if (nest_level <= 0) error(28);
+          else literal_state = nest_literal_stack[--nest_level];
+        }
       }
     break;
     }
   }
 
-/* Empty the pushed stack, close the output, and we are done */
+/* Empty the stack of pushed texts, close the output, and we are done. */
 
 while (pushed != 0)
   {
diff --git a/src/xfpt.h b/src/xfpt.h
index 4ae812267..bdd2c5a74 100644
--- a/src/xfpt.h
+++ b/src/xfpt.h
@@ -34,6 +34,12 @@ headers, but they might as well be together with those above. */
 #define INBUFFSIZE       1024
 #define PARABUFFSIZE    10000
 #define FLAGSTACKSIZE      40
+#define MAXNEST             3
+
+
+/* Nested block indicators for read_paragraph() */
+
+enum { NEST_NO, NEST_BEGIN, NEST_END };
 
 
 /* The literal states */
diff --git a/testing/infiles/01 b/testing/infiles/01
index 61d02eec8..e2e338484 100644
--- a/testing/infiles/01
+++ b/testing/infiles/01
@@ -310,4 +310,99 @@ END NOT FOUR
 .nesttest
 .endd
 
+Test footnotes. The quick brown fox
+.footnote
+Note?
+.endnote
+jumps
+.footnote
+.display
+Display in footnote.
+.endd
+.endnote
+over the lazy
+.footnote
+.itable all 1 1 3 1* left 2* center 3* right
+.row 1 2
+.row 3 4
+.endtable
+.endnote
+dog.
+
+Another paragraph
+.footnote
+First para in footnote.
+
+Second para in footnote.
+.endnote
+with some footnotes
+.
+.footnote
+This foot note will have text
+.code
+and a display
+.endd
+.endnote
+.
+in various forms.
+
+.display
+How about a footnote in a display?
+.footnote
+This is the note.
+.endnote
+Back in the display.
+.endd
+
+.include stdflags
+.include stdmacs
+
+.literal xml
+<?sdop toc_sections="no" ?>
+.literal off
+
+.macro image 
+.literal layout
+&<mediaobject>&&<imageobject>&
+&<imagedata fileref="$1" $=2+ scale="$2"+$=3+ align="$3"+&&&
+  $=4+ depth="$4"+$=5+ width="$5"+>&
+&</imagedata>&&</imageobject>&&</mediaobject>&
+.literal off
+.endmacro
+
+.macro figure
+.literal layout
+&<figure$=2+ id="$2"+&xfpt.rev;>&
+.arg 1
+&<title>&$1&</title>&
+.endarg
+.literal off
+.endmacro
+
+.macro endfigure
+.literal layout
+&</figure>&
+.literal off
+.endmacro
+
+Here is a reference to figure &<<FIGfirst>>&.
+
+.figure "This is the first figure" "FIGfirst"
+.image "eps1.eps"
+.endfigure
+
+Here is another reference to figure &<<FIGfirst>>&. We also have
+figure &<<FIGsecond>>& below.
+
+.figure "The second figure" "FIGsecond"
+.image eps1.eps 80 centre
+.endfigure
+
+.table "this is title" "TAB123" "" "" "" 2 1* left 1* left
+.row AAA BBB
+.row CCC DDD
+.endtable
+
+A ref to table &<<TAB123>>&.
+
 .makeindex
diff --git a/testing/outfiles/01 b/testing/outfiles/01
index 3af3114e6..2bffb0a72 100644
--- a/testing/outfiles/01
+++ b/testing/outfiles/01
@@ -343,6 +343,111 @@ NOT FOUR
 NOT THREE "" ""
 END NOT FOUR
 </literallayout>
+<para>
+Test footnotes. The quick brown fox
+<footnote>
+<para>
+Note?
+</para>
+</footnote>
+jumps
+<footnote>
+<literallayout>
+Display in footnote.
+</literallayout>
+</footnote>
+over the lazy
+<footnote>
+<informaltable frame="all">
+<tgroup cols="3" colsep="1" rowsep="1">
+<colspec colwidth="1*" align="left"/>
+<colspec colwidth="2*" align="center"/>
+<colspec colwidth="3*" align="right"/>
+<tbody>
+<row>
+<entry>1</entry>
+<entry>2</entry>
+</row>
+<row>
+<entry>3</entry>
+<entry>4</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+</footnote>
+dog.
+</para>
+<para>
+Another paragraph
+<footnote>
+<para>
+First para in footnote.
+</para>
+<para>
+Second para in footnote.
+</para>
+</footnote>
+with some footnotes
+<footnote>
+<para>
+This foot note will have text
+</para>
+<literallayout class="monospaced">
+and a display
+</literallayout>
+</footnote>
+in various forms.
+</para>
+<literallayout>
+How about a footnote in a display?
+<footnote>
+<para>
+This is the note.
+</para>
+</footnote>
+Back in the display.
+</literallayout>
+<?sdop toc_sections="no" ?>
+<para>
+Here is a reference to figure <xref linkend="FIGfirst"/>.
+</para>
+<figure id="FIGfirst">
+<title>This is the first figure</title>
+<mediaobject><imageobject>
+<imagedata fileref="eps1.eps" >
+</imagedata></imageobject></mediaobject>
+</figure>
+<para>
+Here is another reference to figure <xref linkend="FIGfirst"/>. We also have
+figure <xref linkend="FIGsecond"/> below.
+</para>
+<figure id="FIGsecond">
+<title>The second figure</title>
+<mediaobject><imageobject>
+<imagedata fileref="eps1.eps"  scale="80" align="centre">
+</imagedata></imageobject></mediaobject>
+</figure>
+<table id="TAB123" >
+<title>this is title</title>
+<tgroup cols="2" colsep="" rowsep="">
+<colspec colwidth="1*" align="left"/>
+<colspec colwidth="1*" align="left"/>
+<tbody>
+<row>
+<entry>AAA</entry>
+<entry>BBB</entry>
+</row>
+<row>
+<entry>CCC</entry>
+<entry>DDD</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+<para>
+A ref to table <xref linkend="TAB123"/>.
+</para>
 </chapter>
 
 <index>
author	Philip Hazel <ph10@hermes.cam.ac.uk>	2007-07-04 08:30:36 +0000
committer	Nigel Metheringham <nigel@exim.org>	2010-06-09 12:42:07 +0000
commit	383466003e800a06ed6d3de9ede2185d03cca488 (patch)
tree	3f34f0b82c8eafb38967c4bc73cf380e5e9afabf
parent	4f307ce2d96bae1c86f9d3d9e6de73caae10f1b9 (diff)
download	exim4-383466003e800a06ed6d3de9ede2185d03cca488.tar.gz