summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPhilip Hazel <ph10@hermes.cam.ac.uk>2007-03-22 12:05:50 +0000
committerNigel Metheringham <nigel@exim.org>2010-06-09 12:42:07 +0000
commit44bd711f68c13d22f580012249b458f2ce2168d4 (patch)
tree62bcb89f61a4ea4fb72afce41de208adc4b4cc7d
parent7dc539a3ed0e403a7f219f5c2b0f21e99752a8b5 (diff)
downloadexim4-44bd711f68c13d22f580012249b458f2ce2168d4.tar.gz
Imported from /Users/nigel/Work/x/xfpt-0.01.tar.bz2.
Diffstat
-rw-r--r--doc/xfpt.17
-rw-r--r--doc/xfpt.html163
-rw-r--r--doc/xfpt.pdfbin73519 -> 56783 bytes
-rw-r--r--doc/xfpt.xfpt41
-rw-r--r--share/stdmacs33
-rw-r--r--src/globals.c4
-rw-r--r--src/xfpt.c8
-rw-r--r--testing/infiles/0113
-rw-r--r--testing/outfiles/0116
9 files changed, 190 insertions, 95 deletions
diff --git a/doc/xfpt.1 b/doc/xfpt.1
index 8089911df..756c231fe 100644
--- a/doc/xfpt.1
+++ b/doc/xfpt.1
@@ -29,6 +29,9 @@ file is given, and the source file name with a \fI.xml\fP extension otherwise.
\fB-S\fP \fIdirectory\fP
This specifies an alternative "share" directory in which to find standard
configuration files.
+.TP
+\fB-v\fP
+Output the \fBxfpt\fP version and exit.
.
.SH AUTHOR
.rs
@@ -40,6 +43,6 @@ University Computing Service
Cambridge CB2 3QG, England.
.P
.in 0
-Last updated: 17 January 2006
+Last updated: 22 March 2007
.br
-Copyright (c) 2006 University of Cambridge.
+Copyright (c) 2007 University of Cambridge.
diff --git a/doc/xfpt.html b/doc/xfpt.html
index 49d6e1db7..f8d0825bd 100644
--- a/doc/xfpt.html
+++ b/doc/xfpt.html
@@ -46,7 +46,7 @@ div[class=changed] div.literallayout {
</style>
<title>
The xfpt plain text to XML processor</title>
-<meta name="generator" content="DocBook XSL Stylesheets V1.68.1" />
+<meta name="generator" content="DocBook XSL Stylesheets V1.70.1" />
</head>
<body>
<div class="book" lang="en" xml:lang="en">
@@ -54,7 +54,7 @@ The xfpt plain text to XML processor</title>
<div>
<div>
<h1 class="title">
-<a id="id2451640">
+<a id="id2434747">
</a>
The xfpt plain text to XML processor</h1>
</div>
@@ -70,7 +70,7 @@ Hazel</span>
</div>
<div>
<p class="copyright">
-Copyright © 2006 University of Cambridge</p>
+Copyright © 2007 University of Cambridge</p>
</div>
<div>
<div class="revhistory">
@@ -83,9 +83,9 @@ Revision History</b>
</tr>
<tr>
<td align="left">
-Revision 0.00</td>
+Revision 0.01</td>
<td align="left">
-16 January 2006</td>
+22 March 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="#id2490895">
+<a id="toc0001" href="#id2527527">
1. Introduction</a>
</span>
</dt>
@@ -111,7 +111,7 @@ Table of Contents</b>
<dl>
<dt>
<span xmlns="" class="section">
-<a id="toc0002" href="#id2453011">
+<a id="toc0002" href="#id2489706">
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="#id2454820">
+<a id="toc0003" href="#id2491606">
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="#id2453241">
+<a id="toc0005" href="#id2490011">
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="#id2453488">
+<a id="toc0007" href="#id2490257">
2. Flag sequences</a>
</span>
</dt>
@@ -159,7 +159,7 @@ example</a>
<dl>
<dt>
<span xmlns="" class="section">
-<a id="toc0008" href="#id2453540">
+<a id="toc0008" href="#id2490310">
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="#id2500320">
+<a id="toc0009" href="#id2536952">
2.2. Flag sequences for calling macros</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0010" href="#id2500341">
+<a id="toc0010" href="#id2536973">
2.3. Other flag sequences</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0011" href="#id2500485">
+<a id="toc0011" href="#id2537117">
2.4. Unrecognized flag sequences</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0012" href="#id2500498">
+<a id="toc0012" href="#id2537129">
2.5. Standard flag sequences</a>
</span>
</dt>
@@ -195,7 +195,7 @@ variables</a>
</dd>
<dt>
<span xmlns="" class="chapter">
-<a id="toc0013" href="#id2500738">
+<a id="toc0013" href="#id2537370">
3. Built-in directive processing</a>
</span>
</dt>
@@ -203,7 +203,7 @@ variables</a>
<dl>
<dt>
<span xmlns="" class="section">
-<a id="toc0014" href="#id2500760">
+<a id="toc0014" href="#id2537392">
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="#id2500804">
+<a id="toc0015" href="#id2537436">
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="#id2500942">
+<a id="toc0016" href="#id2537573">
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="#id2500962">
+<a id="toc0017" href="#id2537594">
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="#id2500984">
+<a id="toc0018" href="#id2537616">
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="#id2501007">
+<a id="toc0019" href="#id2537639">
3.6. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.flag</strong>
@@ -263,7 +263,7 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0020" href="#id2501042">
+<a id="toc0020" href="#id2537674">
3.7. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.include</strong>
@@ -273,7 +273,7 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0021" href="#id2501067">
+<a id="toc0021" href="#id2537699">
3.8. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.literal</strong>
@@ -293,7 +293,7 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0023" href="#id2501281">
+<a id="toc0023" href="#id2537915">
3.10. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.pop</strong>
@@ -303,7 +303,7 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0024" href="#id2501342">
+<a id="toc0024" href="#id2537976">
3.11. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.push</strong>
@@ -323,7 +323,7 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0026" href="#id2501568">
+<a id="toc0026" href="#id2538201">
3.13. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold">
<strong>
.set</strong>
@@ -343,55 +343,55 @@ directive</a>
<dl>
<dt>
<span xmlns="" class="section">
-<a id="toc0028" href="#id2501671">
+<a id="toc0028" href="#id2538305">
4.1. Overall setup</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0029" href="#id2501728">
+<a id="toc0029" href="#id2538362">
4.2. Chapters, sections, and subsections</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0030" href="#id2501835">
+<a id="toc0030" href="#id2538468">
4.3. URL references</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0031" href="#id2501904">
+<a id="toc0031" href="#id2538538">
4.4. Itemized lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0032" href="#id2501978">
+<a id="toc0032" href="#id2538612">
4.5. Ordered lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0033" href="#id2502071">
+<a id="toc0033" href="#id2538704">
4.6. Variable lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0034" href="#id2502125">
+<a id="toc0034" href="#id2538759">
4.7. Nested lists</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0035" href="#id2502147">
+<a id="toc0035" href="#id2538780">
4.8. Displayed text</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0036" href="#id2502259">
+<a id="toc0036" href="#id2538892">
4.9. Block quotes</a>
</span>
</dt>
@@ -403,13 +403,13 @@ directive</a>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0038" href="#id2502417">
+<a id="toc0038" href="#id2539050">
4.11. Informal tables</a>
</span>
</dt>
<dt>
<span xmlns="" class="section">
-<a id="toc0039" href="#id2502692">
+<a id="toc0039" href="#id2539326">
4.12. Indexes</a>
</span>
</dt>
@@ -417,7 +417,7 @@ directive</a>
</dd>
</dl>
</div>
-<div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2490895">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="id2527527">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
@@ -461,7 +461,7 @@ 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="id2453011">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="id2489706">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>
@@ -483,7 +483,7 @@ be given as an output destination to refer to the standard output.
</div><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="id2454820">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></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="id2491606">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
@@ -562,7 +562,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="id2453241">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="id2490011">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
@@ -611,7 +611,7 @@ 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="id2453488">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><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2490257">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
@@ -624,7 +624,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="id2453540">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="id2490310">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:
@@ -648,11 +648,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="id2500320">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="id2536952">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="id2500341">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="id2536973">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.
@@ -685,9 +685,9 @@ Note that, though <span class="emphasis"><em>xfpt</em></span> diagnoses an error
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="id2500485">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
+</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="id2537117">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="id2500498">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="id2537129">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 />
@@ -713,10 +713,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="id2500738">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
+</p></div></div><div class="chapter" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="id2537370">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
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="id2500760">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="id2537392">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
@@ -736,7 +736,7 @@ for the given argument. For example:
and the second one is not empty.
.endarg
.endmacro
-</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="id2500804">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
+</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="id2537436">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
@@ -766,13 +766,13 @@ fifth argument:
.eacharg 5
&amp;&lt;colspec colwidth="$+1" align="$+2"/&gt;&amp;
.endeach 2
-</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="id2500942">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
+</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="id2537573">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="id2500962">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="id2500984">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="id2501007">3.6 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="id2537594">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="id2537616">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="id2537639">3.6 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">
@@ -782,21 +782,22 @@ 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="id2501042">3.7 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="id2537674">3.7 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="id2501067">3.8 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="id2537699">3.8 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.
Section <a href="#SECTliteralprocessing" title="1.3&#xA0;Literal and non-literal processing">1.3</a> describes how input lines are processed in
the four modes.
</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="SECTmacro">3.9 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.macro</strong></span> directive</a></h3></div></div></div><p>This directive is used to define macros. It must be followed by a macro name,
-and then, optionally, by any number of arguments. These provide default values.
-The following lines, up to <span class="bold"><strong>.endmacro</strong></span>, form the body of the macro. They are
-not processed in any way when the macro is defined; they are processed only
-when the macro is called (see section <a href="#SECTcallingmacro" title="1.5&#xA0;Calling macros">1.5</a>).
+and then, optionally, by any number of arguments. The macro name can be any
+sequence of non-whitespace characters. The arguments in the definition provide
+default values. The following lines, up to <span class="bold"><strong>.endmacro</strong></span>, form the body of the
+macro. They are not processed in any way when the macro is defined; they are
+processed only when the macro is called (see section <a href="#SECTcallingmacro" title="1.5&#xA0;Calling macros">1.5</a>).
</p><p>
Within the body of a macro, argument substitutions can be specified by means of
a dollar character and an argument number, for example, <code class="literal">$3</code> for the third
@@ -843,7 +844,7 @@ 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="id2501281">3.10 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="id2537915">3.10 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.
@@ -856,7 +857,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="id2501342">3.11 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="id2537976">3.11 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:
@@ -899,7 +900,7 @@ though it does still seem to process it correctly.
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="id2501568">3.13 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
+</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="id2538201">3.13 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:
@@ -921,7 +922,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="id2501671">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="id2538305">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">
@@ -931,7 +932,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="id2501728">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="id2538362">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
@@ -963,7 +964,7 @@ 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="id2501835">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 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="id2538468">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
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:
@@ -978,7 +979,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="id2501904">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="id2538538">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
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
@@ -997,7 +998,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="id2501978">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="id2538612">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
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">
@@ -1018,7 +1019,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="id2502071">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="id2538704">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
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
@@ -1036,12 +1037,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="id2502125">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="id2538759">4.7 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="id2502147">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="id2538780">4.8 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.
@@ -1072,7 +1073,7 @@ 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="id2502259">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="id2538892">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
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.12&#xA0;The .revision directive">3.12</a>). When the revised text is
@@ -1104,7 +1105,7 @@ a directive or inline:
</pre><p>
The effect of this is to generate a <code class="literal">&lt;phrase&gt;</code> XML element with the
<code class="literal">revisionflag</code> attribute set. The <span class="bold"><strong>.wen</strong></span> macro is not used in this case.
-</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="id2502417">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><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="id2539050">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
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.
@@ -1151,7 +1152,7 @@ The <span class="bold"><strong>.row</strong></span> macro does not set the <code
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="id2502692">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 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="id2539326">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
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
@@ -1161,6 +1162,18 @@ example:
.index goose "wild chase"
The chasing of wild geese...
</pre><p>
+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>
+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
+<span class="bold"><strong>.index-from</strong></span> are the primary and secondary index items. For example:
+</p><pre class="literallayout">
+ .index-from "ID5" "indexes" "handling ranges"
+ ... &lt;lines of text&gt; ...
+ .index-to "ID5"
+</pre><p>
The <span class="bold"><strong>.makeindex</strong></span> macro should be called at the end of the document, at the
point where you want an index to be generated. It can have up to two
arguments. The first is the title for the index, for which the default is
diff --git a/doc/xfpt.pdf b/doc/xfpt.pdf
index 57a7c3d78..dce5c18a4 100644
--- a/doc/xfpt.pdf
+++ b/doc/xfpt.pdf
Binary files differ
diff --git a/doc/xfpt.xfpt b/doc/xfpt.xfpt
index d8f3c842f..552846cff 100644
--- a/doc/xfpt.xfpt
+++ b/doc/xfpt.xfpt
@@ -13,17 +13,31 @@
<bookinfo>
<title>The xfpt plain text to XML processor</title>
<titleabbrev>xfpt</titleabbrev>
-<date>16 January 2006</date>
+<date>22 March 2007</date>
<author>
<firstname>Philip</firstname>
<surname>Hazel</surname>
</author>
<authorinitials>PH</authorinitials>
-<revhistory><revision><revnumber>0.00</revnumber><date>16 January 2006</date><authorinitials>PH</authorinitials></revision></revhistory>
-<copyright><year>2006</year><holder>University of Cambridge</holder></copyright>
+<revhistory><revision><revnumber>0.01</revnumber><date>22 March 2007</date><authorinitials>PH</authorinitials></revision></revhistory>
+<copyright><year>2007</year><holder>University of Cambridge</holder></copyright>
</bookinfo>
.literal off
+. /////////////////////////////////////////////////////////////////////////////
+. These lines are processing instructions for the Simple DocBook Processor that
+. Philip Hazel has developed as a less cumbersome way of making PostScript and
+. PDFs than using xmlto and fop. They will be ignored by all other XML
+. processors.
+. /////////////////////////////////////////////////////////////////////////////
+
+.literal xml
+<?sdop
+ foot_right_recto="&chaptertitle;"
+ foot_right_verso="&chaptertitle;"
+?>
+.literal off
+
. ----------------------------------------------------------------------------
@@ -494,10 +508,11 @@ the four modes.
.section "The &*.macro*& directive" "SECTmacro"
This directive is used to define macros. It must be followed by a macro name,
-and then, optionally, by any number of arguments. These provide default values.
-The following lines, up to &*.endmacro*&, form the body of the macro. They are
-not processed in any way when the macro is defined; they are processed only
-when the macro is called (see section &<<SECTcallingmacro>>&).
+and then, optionally, by any number of arguments. The macro name can be any
+sequence of non-whitespace characters. The arguments in the definition provide
+default values. The following lines, up to &*.endmacro*&, form the body of the
+macro. They are not processed in any way when the macro is defined; they are
+processed only when the macro is called (see section &<<SECTcallingmacro>>&).
Within the body of a macro, argument substitutions can be specified by means of
a dollar character and an argument number, for example, &`$3`& for the third
@@ -928,6 +943,18 @@ example:
.index goose "wild chase"
The chasing of wild geese...
.endd
+You can generate &"see"& and &"see also"& index entries by using &*.index-see*&
+and &*.index-seealso*& instead of &*.index*&.
+
+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
+an ID that ties them together. The second and third arguments of
+&*.index-from*& are the primary and secondary index items. For example:
+.code
+ .index-from "ID5" "indexes" "handling ranges"
+ ... <lines of text> ...
+ .index-to "ID5"
+.endd
The &*.makeindex*& macro should be called at the end of the document, at the
point where you want an index to be generated. It can have up to two
diff --git a/share/stdmacs b/share/stdmacs
index 965f5911a..36e3c4ddd 100644
--- a/share/stdmacs
+++ b/share/stdmacs
@@ -188,6 +188,39 @@
&</indexterm>&
.endmacro
+.macro index-from
+&<indexterm id="$1" class="startofrange">&
+&<primary>&$2&</primary>&
+.arg 3
+&<secondary>&$3&</secondary>&
+.endarg
+&</indexterm>&
+.endmacro
+
+.macro index-to
+&<indexterm startref="$1" class="endofrange"/>&
+.endmacro
+
+.macro index-see
+&<indexterm>&
+&<primary>&$2&</primary>&
+.arg 3
+&<secondary>&$3&</secondary>&
+.endarg
+&<see>&$1&</see>&
+&</indexterm>&
+.endmacro
+
+.macro index-seealso
+&<indexterm>&
+&<primary>&$2&</primary>&
+.arg 3
+&<secondary>&$3&</secondary>&
+.endarg
+&<seealso>&$1&</seealso>&
+&</indexterm>&
+.endmacro
+
.macro makeindex "Index"
.literal layout
.pop C
diff --git a/src/globals.c b/src/globals.c
index 1e1a8ed3d..5082c105c 100644
--- a/src/globals.c
+++ b/src/globals.c
@@ -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. */
/* Allocate storage and initialize global variables */
@@ -11,7 +11,7 @@
uschar *xfpt_share = US DATADIR;
-uschar *xfpt_version = US "0.00";
+uschar *xfpt_version = US "0.01 22-Mar-2007";
tree_node *entities = NULL;
diff --git a/src/xfpt.c b/src/xfpt.c
index 7fbb18e25..7c5b59744 100644
--- a/src/xfpt.c
+++ b/src/xfpt.c
@@ -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 module contains the main program and initialization functions. */
@@ -30,6 +30,7 @@ usage(void)
"Usage: xfpt [-help]\n"
" [-o <output-file>]\n"
" [-S <share-directory>]\n"
+ " [-v]\n"
" [input-file]\n");
}
@@ -67,6 +68,11 @@ for (i = 1; i < argc; i++)
usage();
return FALSE;
}
+ else if (Ustrcmp(arg, "-v") == 0)
+ {
+ (void)fprintf(stdout, "xpft version %s\n", xfpt_version);
+ exit(0);
+ }
else
{
(void)fprintf(stderr, "xfpt: unknown option \"%s\"\n", arg);
diff --git a/testing/infiles/01 b/testing/infiles/01
index b24312336..9dbf963b4 100644
--- a/testing/infiles/01
+++ b/testing/infiles/01
@@ -13,6 +13,7 @@ This is text before the first section.
.section "First section"
.index primary secondary
+.index-from "ID" "range"
This is the text of the first section.
We are going to have an index in the middle of a paragraph.
.index "primary two" "secondary two"
@@ -25,6 +26,8 @@ chapter &<<CHAPsecond>>&. Here are some entities, both local and default:
.chapter "Second chapter" "CHAPsecond"
This is the second chapter. Test a block quote:
+.index-see "sights" "visions"
+.index-seealso "sounds" "noises" "off"
.revision "changed"
.blockquote
@@ -49,6 +52,7 @@ The second item.
.next
The third item
.endlist
+.index-to "ID"
.revision off
@@ -215,11 +219,4 @@ $+1
URL &url(http://etc) and another &url(http://etc, text) and so on.
-
-.literal layout
-.pop C
-.literal xml
-<index>
-<title>Index</title>
-</index>
-.literal off
+.makeindex
diff --git a/testing/outfiles/01 b/testing/outfiles/01
index a3adced5c..6199c7225 100644
--- a/testing/outfiles/01
+++ b/testing/outfiles/01
@@ -14,6 +14,9 @@ This is text before the first section.
<primary>primary</primary>
<secondary>secondary</secondary>
</indexterm>
+<indexterm id="ID" class="startofrange">
+<primary>range</primary>
+</indexterm>
This is the text of the first section.
We are going to have an index in the middle of a paragraph.
<indexterm>
@@ -37,6 +40,15 @@ chapter <xref linkend="CHAPsecond"/>. Here are some entities, both local and def
<title>Second chapter</title>
<para>
This is the second chapter. Test a block quote:
+<indexterm>
+<primary>visions</primary>
+<see>sights</see>
+</indexterm>
+<indexterm>
+<primary>noises</primary>
+<secondary>off</secondary>
+<seealso>sounds</seealso>
+</indexterm>
</para>
<blockquote revisionflag="changed">
<para revisionflag="changed">
@@ -79,6 +91,9 @@ The third item
</para>
</listitem>
</orderedlist>
+<para revisionflag="changed">
+<indexterm startref="ID" class="endofrange"/>
+</para>
<orderedlist numeration="lowerroman">
<listitem>
<para>
@@ -268,4 +283,5 @@ URL <emphasis role="bold"><ulink url="http://etc">http://etc</ulink></emphasis>
<index>
<title>Index</title>
</index>
+
</book>
View Lorry Controller Status