diff options
Diffstat (limited to '3rd-party/xfpt/doc')
-rw-r--r-- | 3rd-party/xfpt/doc/xfpt.1 | 48 | ||||
-rw-r--r-- | 3rd-party/xfpt/doc/xfpt.html | 1463 | ||||
-rw-r--r-- | 3rd-party/xfpt/doc/xfpt.pdf | bin | 0 -> 70341 bytes | |||
-rw-r--r-- | 3rd-party/xfpt/doc/xfpt.xfpt | 1211 |
4 files changed, 2722 insertions, 0 deletions
diff --git a/3rd-party/xfpt/doc/xfpt.1 b/3rd-party/xfpt/doc/xfpt.1 new file mode 100644 index 000000000..756c231fe --- /dev/null +++ b/3rd-party/xfpt/doc/xfpt.1 @@ -0,0 +1,48 @@ +.TH XFPT 1 +.SH NAME +xfpt - make XML from plain text +.SH SYNOPSIS +.B xfpt [options] [source file] +. +.SH DESCRIPTION +.rs +.sp +\fBxfpt\fP converts a marked up text file to XML. The markup is simple and +consists of lines that begin with a dot ("directive lines") and sequences in +the text that begin with an ampersand ("flags"). The flag sequences are not +built-in, but are defined by directives. As well as the in-built directives, +macros can be used to implement higher level concepts. A standard set of macros +and flags that generate DocBook XML is provided. There is a full description in +the \fBxfpt\fP specification, which is distributed as a PDF file, an HTML file, +and as \Bxfpt\fP source. +. +.SH OPTIONS +.rs +.TP 10 +\fB-help\fP +This causes \fBxfpt\fP to output its "usage" information and then exit. +.TP +\fB-o\fP \fIfile\fP +This specifies the output file. The default is the standard output if no source +file is given, and the source file name with a \fI.xml\fP extension otherwise. +.TP +\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 +.sp +Philip Hazel +.br +University Computing Service +.br +Cambridge CB2 3QG, England. +.P +.in 0 +Last updated: 22 March 2007 +.br +Copyright (c) 2007 University of Cambridge. diff --git a/3rd-party/xfpt/doc/xfpt.html b/3rd-party/xfpt/doc/xfpt.html new file mode 100644 index 000000000..344416c33 --- /dev/null +++ b/3rd-party/xfpt/doc/xfpt.html @@ -0,0 +1,1463 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css"> +div.added { background-color: #ffff99; } +div.deleted { text-decoration: line-through; + background-color: #FF7F7F; } +div.changed { background-color: #99ff99; } +div.off { } + +span.added { background-color: #ffff99; } +span.deleted { text-decoration: line-through; + background-color: #FF7F7F; } +span.changed { background-color: #99ff99; } +span.off { } + + + +pre.literallayout { + background-color: #E8E8D0; + padding-left: 0.5cm; + padding-top: 5px; + padding-bottom: 5px; +} + +div[class=changed] pre.literallayout { + background-color: #99ff99; + padding-left: 0.5cm; + padding-top: 5px; + padding-bottom: 5px; +} + +div.literallayout { + background-color: #E8E8D0; + padding-left: 0.5cm; + padding-top: 5px; + padding-bottom: 5px; +} + +div[class=changed] div.literallayout { + background-color: #99ff99; + padding-left: 0.5cm; + padding-top: 5px; + padding-bottom: 5px; +} + +</style> +<title> +The xfpt plain text to XML processor</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /> +</head> +<body> +<div class="book" title="The xfpt plain text to XML processor"> +<div class="titlepage"> +<div> +<div> +<h1 class="title"> +<a id="idm3387464"> +</a> +The xfpt plain text to XML processor</h1> +</div> +<div> +<div class="author"> +<h3 class="author"> +<span class="firstname"> +Philip</span> +<span class="surname"> +Hazel</span> +</h3> +</div> +</div> +<div> +<p class="copyright"> +Copyright © 2012 University of Cambridge</p> +</div> +<div> +<div class="revhistory"> +<table border="1" width="100%" summary="Revision history"> +<tr> +<th align="left" valign="top" colspan="3"> +<strong> +Revision History</strong> +</th> +</tr> +<tr> +<td align="left"> +Revision 0.09</td> +<td align="left"> +18 May 2012</td> +<td align="left"> +PH</td> +</tr> +</table> +</div> +</div> +</div> +<hr /> +</div> +<div class="toc"> +<p> +<strong> +Table of Contents</strong> +</p> +<dl> +<dt> +<span xmlns="" class="chapter"> +<a id="toc0001" href="#ID00"> +1. Introduction</a> +</span> +</dt> +<dd> +<dl> +<dt> +<span xmlns="" class="section"> +<a id="toc0002" href="#ID01"> +1.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"> +<em> +xfpt</em> +</span> +command line</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0003" href="#ID02"> +1.2. A short <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"> +<em> +xfpt</em> +</span> +example</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0004" href="#SECTliteralprocessing"> +1.3. Literal and non-literal processing</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0005" href="#ID04"> +1.4. Format of directive lines</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0006" href="#SECTcallingmacro"> +1.5. Calling macros</a> +</span> +</dt> +</dl> +</dd> +<dt> +<span xmlns="" class="chapter"> +<a id="toc0007" href="#ID06"> +2. Flag sequences</a> +</span> +</dt> +<dd> +<dl> +<dt> +<span xmlns="" class="section"> +<a id="toc0008" href="#ID07"> +2.1. Flag sequences for XML entities and <span xmlns="http://www.w3.org/1999/xhtml" class="emphasis"> +<em> +xfpt</em> +</span> +variables</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0009" href="#ID08"> +2.2. Flag sequences for calling macros</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0010" href="#ID09"> +2.3. Other flag sequences</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0011" href="#ID10"> +2.4. Unrecognized flag sequences</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0012" href="#ID11"> +2.5. Standard flag sequences</a> +</span> +</dt> +</dl> +</dd> +<dt> +<span xmlns="" class="chapter"> +<a id="toc0013" href="#ID12"> +3. Built-in directive processing</a> +</span> +</dt> +<dd> +<dl> +<dt> +<span xmlns="" class="section"> +<a id="toc0014" href="#ID13"> +3.1. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.arg</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0015" href="#ID14"> +3.2. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.eacharg</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0016" href="#ID15"> +3.3. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.echo</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0017" href="#ID16"> +3.4. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.endarg</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0018" href="#ID17"> +3.5. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.endeach</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0019" href="#ID18"> +3.6. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.endinliteral</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0020" href="#ID19"> +3.7. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.flag</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0021" href="#ID20"> +3.8. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.include</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0022" href="#ID21"> +3.9. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.inliteral</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0023" href="#ID22"> +3.10. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.literal</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0024" href="#SECTmacro"> +3.11. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.macro</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0025" href="#ID24"> +3.12. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.nest</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0026" href="#ID25"> +3.13. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.nonl</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0027" href="#ID26"> +3.14. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.pop</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0028" href="#ID27"> +3.15. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.push</strong> +</span> +directive</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<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="#ID29"> +3.17. The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"> +<strong> +.set</strong> +</span> +directive</a> +</span> +</dt> +</dl> +</dd> +<dt> +<span xmlns="" class="chapter"> +<a id="toc0031" href="#CHAPstdmac"> +4. The standard macros for DocBook</a> +</span> +</dt> +<dd> +<dl> +<dt> +<span xmlns="" class="section"> +<a id="toc0032" href="#ID31"> +4.1. Overall setup</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0033" href="#idp3069176"> +4.2. Processing instructions</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0034" href="#ID32"> +4.3. Chapters, sections, and subsections</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0035" href="#ID33"> +4.4. Prefaces, appendixes, and colophons</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0036" href="#idp3081992"> +4.5. Terminating chapters, etc.</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0037" href="#ID34"> +4.6. URL references</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0038" href="#ID35"> +4.7. Itemized lists</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0039" href="#ID36"> +4.8. Ordered lists</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0040" href="#ID37"> +4.9. Variable lists</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0041" href="#ID38"> +4.10. Nested lists</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0042" href="#ID39"> +4.11. Displayed text</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0043" href="#ID40"> +4.12. Block quotes</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0044" href="#SECTrevmacs"> +4.13. Revision markings</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0045" href="#ID42"> +4.14. Informal tables</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0046" href="#ID43"> +4.15. Formal tables</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0047" href="#ID44"> +4.16. Figures and images</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0048" href="#ID45"> +4.17. Footnotes</a> +</span> +</dt> +<dt> +<span xmlns="" class="section"> +<a id="toc0049" href="#ID46"> +4.18. Indexes</a> +</span> +</dt> +</dl> +</dd> +</dl> +</div> +<div class="chapter" title="1. Introduction"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID00">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 class="ulink" 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 +freestanding ASCII document. The input for <span class="emphasis"><em>xfpt</em></span> is very definitely <span class="quote">“<span class="quote">marked +up</span>”</span>. This makes it less ambiguous for large and/or complicated documents. <span class="emphasis"><em>xfpt</em></span> +is also much faster than <span class="emphasis"><em>AsciiDoc</em></span> because it is written in C and does not +rely on pattern matching. +</p><p> +<span class="emphasis"><em>xfpt</em></span> is aimed at users who understand the XML that they are generating. It makes +it easy to include literal XML, either in blocks, or within paragraphs. <span class="emphasis"><em>xfpt</em></span> +restricts itself to two special characters that trigger all its processing. +</p><p> +<span class="emphasis"><em>xfpt</em></span> treats any input line that starts with a dot as a <span class="emphasis"><em>directive</em></span> line. +Directives control the way the input is processed. A small number of directives +are implemented in the program itself. A macro facility makes it possible to +combine these in various ways to define directives for higher-level concepts +such as chapters and sections. A standard macro library that generates a simple +subset of DocBook XML is provided. The only XML element that the program itself +generates is <code class="literal"><para></code>; all the others must be included as literal XML, either +directly in the input text, or, more commonly, as part of the text that is +generated by a macro call. +</p><p> +The ampersand character is special within non-literal text that is processed by +<span class="emphasis"><em>xfpt</em></span>. An ampersand introduces a <span class="emphasis"><em>flag sequence</em></span> that modifies the output. +Ampersand was chosen because it is also special in XML. As well as recognizing +flag sequences that begin with an ampersand, <span class="emphasis"><em>xfpt</em></span> converts grave accents and +apostrophes that appear in non-literal text into typographic opening and +closing quotes, as follows: +</p><div class="literallayout"> + <code class="literal"> ` </code> becomes ‘<br /> + <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, 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 +introduce an argument substitution. +</p><p> +Notwithstanding the previous paragraph, <span class="emphasis"><em>xfpt</em></span> knows that it is generating XML, +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;</code>, <code class="literal">&lt;</code>, or +<code class="literal">&gt;</code>, respectively) is generated. +</p><div class="section" title="1.1 The xfpt command line"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID01">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 four options: +</p><div class="variablelist"><dl><dt><span class="term"><span class="option"><strong>-help</strong></span></span></dt><dd><p> +This option causes <span class="emphasis"><em>xfpt</em></span> to output its <span class="quote">“<span class="quote">usage</span>”</span> message, and exit. +</p></dd><dt><span class="term"><span class="option"><strong>-o</strong></span> <span class="emphasis"><em><output destination></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></dd><dt><span class="term"><span class="option"><strong>-S</strong></span> <span class="emphasis"><em><directory path></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></dd><dt><span class="term"><span class="option"><strong>-v</strong></span></span></dt><dd><p> +This option causes <span class="emphasis"><em>xfpt</em></span> to output its version number and exit. +</p></dd></dl></div></div><div class="section" title="1.2 A short xfpt example"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID02">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 + .include stdmacs + .docbook + .book + + .chapter "The first chapter" + This is the text of the first chapter. Here is an &'italic'& + word, and here is a &*bold*& one. + + .section "This is a section heading" + We can use the &*ilist*& macro to generate an itemized list: + .ilist + The first item in the list. + .next + The last item in the list. + .endlist + + There are also standard macros for ordered lists, literal + layout blocks, code blocks, URL references, index entries, + tables, footnotes, figures, etc. +</pre></div><div class="section" title="1.3 Literal and non-literal processing"><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">“<span class="quote">modes</span>”</span>): +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> +In the default mode, text is processed paragraph by paragraph. +<sup>[<a id="idp58896" href="#ftn.idp58896" class="footnote">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. +</p><p> +Because <span class="emphasis"><em>xfpt</em></span> reads a whole paragraph before processing it, error messages +contain the phrase <span class="quote">“<span class="quote">detected near line <span class="emphasis"><em>nnn</em></span></span>”</span>, where the line number is +typically that of the last line of the paragraph. +</p></li><li class="listitem"><p> +In the <span class="quote">“<span class="quote">literal layout</span>”</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 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"><literallayout></code> +elements. +</p></li><li class="listitem"><p> +In the <span class="quote">“<span class="quote">literal text</span>”</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 +ampersand and angle bracket characters into XML entity references. This mode is +used by the standard <span class="bold"><strong>.code</strong></span> macro to generate <code class="literal"><literallayout></code> elements +that include <code class="literal">class=monospaced</code>. +</p></li><li class="listitem"><p> +In the <span class="quote">“<span class="quote">literal XML</span>”</span> mode, text lines are copied to the output without +modification. This is the easiest way to include a chunk of literal XML in the +output. An example might be the <code class="literal"><bookinfo></code> element, which occurs only once +in a document. It is not worth setting up a macro for a one-off item like this. +</p></li></ul></div><p> +The <span class="bold"><strong>.literal</strong></span> directive switches between the modes. It is not normally used +directly, but instead is incorported into appropriate macro definitions. The +<span class="bold"><strong>.inliteral</strong></span> directive can be used to test the current mode. +</p><p> +Directive lines are recognized and acted upon in all four modes. However, an +unrecognized line that starts with a dot in the literal text or literal XML +mode is treated as data. In the other modes, such a line provokes an error. +</p><p> +If you need to have a data line that begins with a dot in literal layout mode, +you can either specify it by character number, or precede it with some +non-acting markup. These two examples are both valid: +</p><pre class="literallayout"> + &#x2e;start with a dot + &''&.start with a dot +</pre><p> +The second example assumes the standard flags are defined: it precedes the dot +with an empty italic string. However, this is untidy because the empty string +will be carried over into the XML. +</p><p> +In literal text or literal XML mode, it is not possible to have a data line +that starts with a dot followed by the name of a directive or macro. You have +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" title="1.4 Format of directive lines"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID04">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 +are enclosed in single or double quotes. The delimiting quote character can be +included within a quoted string by doubling it. Here are some examples: +</p><pre class="literallayout"> + .literal layout + .set version 0.00 + .row "Jack's house" 'Jill''s house' +</pre><p> +An unrecognized directive line normally causes an error; however, in the +literal text and literal XML modes, an unrecognized line that starts with a +dot is treated as a data line. +</p></div><div class="section" title="1.5 Calling macros"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTcallingmacro">1.5 Calling macros</a></h3></div></div></div><p>Macros are defined by the <span class="bold"><strong>.macro</strong></span> directive, which is described in section +<a class="xref" href="#SECTmacro" title="3.11 The .macro directive">3.11</a>. There are two ways of calling a macro. It can be called in the +same way as a directive, or it can be called from within text that is being +processed. The second case is called an <span class="quote">“<span class="quote">inline macro call</span>”</span>. +</p><p> +When a macro is called as a directive, its name is given after a dot at the +start of a line, and the name may be followed by any number of optional +arguments, in the same way as a built-in directive (see the previous section). +For example: +</p><pre class="literallayout"> + .chapter "Chapter title" chapter-reference +</pre><p> +The contents of the macro, after argument substitution, are processed in +exactly the same way as normal input lines. A macro that is called as a +directive may contain nested macro calls. +</p><p> +When a macro is called from within a text string, its name is given after an +ampersand, and is followed by an opening parenthesis. Arguments, delimited by +commas, can then follow, up to a closing parenthesis. If an argument contains a +comma or a closing parenthesis, it must be quoted. White space after a +separating comma is ignored. The most common example of this type of macro +call is the standard macro for generating a URL reference: +</p><pre class="literallayout"> + Refer to a URL via &url(http://x.example,this text). +</pre><p> +There are differences in the behaviour of macros, depending on which way they +are called. A macro that is called inline may not contain references to other +macros; it must contain only text lines and calls to built-in directives. +Also, newlines that terminate text lines within the macro are not included in +the output. +</p><p> +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 class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.idp58896" href="#idp58896" class="para">1</a>] </sup> +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. +</p></div></div></div><div class="chapter" title="2. Flag sequences"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID06">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 +involve any number of lines. Thus: +</p><div class="literallayout"> + <code class="literal">The quick &&&</code><br /> + <code class="literal"> brown &&&</code><br /> + <code class="literal"> fox.</code><br /> +</div><p> +produces exactly the same output as: +</p><pre class="literallayout"> + The quick brown fox. +</pre><div class="section" title="2.1 Flag sequences for XML entities and xfpt variables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID07">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: +</p><pre class="literallayout"> + This is an Ohm sign: &#x2126;. + This is a degree sign: &#176;. +</pre><p> +If an ampersand is followed by a letter, a sequence of letters, digits, and +dots is read. If this is terminated by a semicolon, the characters between the +ampersand and the semicolon are interpreted as an entity name. This can be: +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> +The name of an inbuilt <span class="emphasis"><em>xfpt</em></span> variable. At present, there is only one of these, +called <code class="literal">xfpt.rev</code>. Its use is described with the <span class="bold"><strong>.revision</strong></span> directive +below. +</p></li><li class="listitem"><p> +The name of a user variable that has been set by the <span class="bold"><strong>.set</strong></span> directive, also +described below. +</p></li><li class="listitem"><p> +The name of an XML entity. This is assumed if the name is not recognized as one +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: &Ohm;. +</pre></li></ul></div></div><div class="section" title="2.2 Flag sequences for calling macros"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID08">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 class="xref" href="#SECTcallingmacro" title="1.5 Calling macros">1.5</a> for more details. +</p></div><div class="section" title="2.3 Other flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID09">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. +</p><p> +Lines are scanned from left to right when flags are being interpreted. If +there is any ambiguity when a text string is being scanned, the longest flag +sequence wins. Thus, it is possible (as in the standard flag sequences) to +define both <code class="literal">&<</code> and <code class="literal">&<<</code> as flags, provided that you never want to +follow the first of them with a <code class="literal"><</code> character. +</p><p> +You can define flags that start with <code class="literal">&#</code>, but these must be used with care, +lest they be misinterpreted as numerical references to XML entities. +</p><p> +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">&&</code> +is defined as a standalone flag with with the replacement text <code class="literal">&amp;</code>. +</p><p> +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. For example, in the standard definitions, <code class="literal">&'</code> and +<code class="literal">'&</code> are defined as a flag pair for enclosing text in an <code class="literal"><emphasis></code> +element. +</p><p> +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><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"><emphasis></code> within <code class="literal"><literal></code>, though it does allow <code class="literal"><literal></code> within +<code class="literal"><emphasis></code>. +</p></div><div class="section" title="2.4 Unrecognized flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID10">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" title="2.5 Standard flag sequences"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID11">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">&& </code> becomes <code class="literal"> &amp;</code> (ampersand)<br /> + <code class="literal">&-- </code> becomes <code class="literal"> &ndash;</code> (en-dash)<br /> + <code class="literal">&~ </code> becomes <code class="literal"> &nbsp;</code> (‘hard’ space)<br /> +</div><p> +These are the flag pairs 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">&"..."& </code> becomes <code class="literal"><quote>...</quote></code><br /> + <code class="literal">&'...'& </code> becomes <code class="literal"><emphasis>...</emphasis></code><br /> + <code class="literal">&*...*& </code> becomes <code class="literal"><emphasis role="bold">...</emphasis></code><br /> + <code class="literal">&`...`& </code> becomes <code class="literal"><literal>...</literal></code><br /> + <code class="literal">&_..._& </code> becomes <code class="literal"><filename>...</filename></code><br /> + <code class="literal">&(...)& </code> becomes <code class="literal"><command>...</command></code><br /> + <code class="literal">&[...]& </code> becomes <code class="literal"><function>...</function></code><br /> + <code class="literal">&%...%& </code> becomes <code class="literal"><option>...</option></code><br /> + <code class="literal">&$...$& </code> becomes <code class="literal"><varname>...</varname></code><br /> + <code class="literal">&<...>& </code> becomes <code class="literal"><...></code><br /> + <code class="literal">&<<...>>& </code> becomes <code class="literal"><xref linkend="..."/></code><br /> +</div><p> +For example, if you want to include a literal XML element in your output, you +can do it like this: <code class="literal">&<element>&</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" title="3. Built-in directive processing"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="ID12">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 class="xref" href="#CHAPstdmac" title="4. The standard macros for DocBook">4</a>. +</p><div class="section" title="3.1 The .arg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID13">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 +arguments and the given argument is not an empty string. If the number is +negative (minus sign present), subsequent lines are skipped if the macro has +been called with fewer than that number of arguments, or with an empty string +for the given argument. For example: +</p><pre class="literallayout"> + .macro example + .arg 2 + Use these lines if there are at least 2 arguments + and the second one is not empty. Normally there would + be a reference to the 2nd argument. + .endarg + .arg -2 + Use this line unless there are at least 2 arguments + and the second one is not empty. + .endarg + .endmacro +</pre><p> +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><p> +The <span class="bold"><strong>.arg</strong></span> directive may be nested. +</p></div><div class="section" title="3.2 The .eacharg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID14">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. 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. +</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, +and are not processed at all. When these lines are being processed, the +remaining macro arguments can be referenced relative to the current argument. +<code class="literal">$+1</code> refers to the current argument, <code class="literal">$+2</code> to the next argument, and so +on. +</p><p> +The <span class="bold"><strong>.endeach</strong></span> directive may also be followed by a number, again defaulting +to 1. When <span class="bold"><strong>.endeach</strong></span> is reached, the current argument number is incremented +by that number. If there are still unused arguments available, the lines +between <span class="bold"><strong>.eacharg</strong></span> and <span class="bold"><strong>.endeach</strong></span> are processed again. +</p><p> +This example is taken from the coding for the standard <span class="bold"><strong>.row</strong></span> macro, which +generates an <code class="literal"><entry></code> element for each of its arguments: +</p><pre class="literallayout"> + .eacharg + &<entry>&$+1&</entry>& + .endeach +</pre><p> +This example is taken from the coding for the standard <span class="bold"><strong>.itable</strong></span> macro, which +processes arguments in pairs to define the table’s columns, starting from the +fifth argument: +</p><pre class="literallayout"> + .eacharg 5 + &<colspec colwidth="$+1" align="$+2"/>& + .endeach 2 +</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" title="3.3 The .echo directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID15">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" title="3.4 The .endarg directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID16">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" title="3.5 The .endeach directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID17">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" title="3.6 The .endinliteral directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID18">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" title="3.7 The .flag directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID19">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"> + .flag && "&amp;" + .flag &" "& "<quote>" "</quote>" +</pre><p> +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" title="3.8 The .include directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID20">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. If +<span class="bold"><strong>.include</strong></span> is used inside a macro, it is evaluated each time the macro is +called, and thus can be used to include a different file on each occasion. +</p></div><div class="section" title="3.9 The .inliteral directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID21">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">“<span class="quote">layout</span>”</span>, <span class="quote">“<span class="quote">text</span>”</span>, <span class="quote">“<span class="quote">off</span>”</span>, or <span class="quote">“<span class="quote">xml</span>”</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" title="3.10 The .literal directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID22">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">“<span class="quote">layout</span>”</span>, <span class="quote">“<span class="quote">text</span>”</span>, <span class="quote">“<span class="quote">off</span>”</span>, or +<span class="quote">“<span class="quote">xml</span>”</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">“<span class="quote">off</span>”</span> mode, in +which text is processed paragraph by paragraph, and flags are recognized. +Section <a class="xref" href="#SECTliteralprocessing" title="1.3 Literal and non-literal processing">1.3</a> describes how input lines are processed in +the four modes. +</p></div><div class="section" title="3.11 The .macro directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTmacro">3.11 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. 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 class="xref" href="#SECTcallingmacro" title="1.5 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 +argument. See also <span class="bold"><strong>.eacharg</strong></span> above for the use of <code class="literal">$+</code> to refer to +relative arguments when looping through them. A reference to an argument that +is not supplied, and is not given a default, results in an empty substitution. +</p><p> +There is also a facility for a conditional substitution. A reference to an +argument of the form: +</p><div class="literallayout"> +<code class="literal">$=</code><span class="emphasis"><em><digits><delimiter><text><delimiter></em></span><br /> +</div><p> +inserts the text if the argument is defined and is not an empty string, and +nothing otherwise. The text is itself scanned for flags and argument +substitutions. The delimiter must be a single character that does not appear in +the text. For example: +</p><pre class="literallayout"> +&<chapter$=2+ id="$2"+>& +</pre><p> +If this appears in a macro that is called with only one argument, the result +is: +</p><pre class="literallayout"> +<chapter> +</pre><p> +but if the second argument is, say <code class="literal">abcd</code>, the result is: +</p><pre class="literallayout"> +<chapter id="abcd"> +</pre><p> +This conditional feature can be used with both absolute and relative argument +references. +</p><p> +If a dollar character is required as data within the body of a macro, it must +be doubled. For example: +</p><pre class="literallayout"> + .macro price + The price is $$1. + .endmacro +</pre><p> +If you redefine an existing macro, the new definition overrides the old. There +is no way to revert to the previous definition. If you define a macro whose +name is the same as the name of a built-in directive you will not be able to +call it, because <span class="emphasis"><em>xfpt</em></span> looks for built-in directives before it looks for macros. +</p><p> +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" title="3.12 The .nest directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID24">3.12 The <span xmlns="http://www.w3.org/1999/xhtml" class="bold"><strong>.nest</strong></span> directive</a></h3></div></div></div><p>This directive must be followed by one of the words <span class="quote">“<span class="quote">begin</span>”</span> or <span class="quote">“<span class="quote">end</span>”</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><pre class="literallayout"> + .macro footnote + &<footnote>& + .nest begin + .endmacro +</pre><p> +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">“<span class="quote">not in a paragraph</span>”</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 class="section" title="3.13 The .nonl directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID25">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 an input line 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" title="3.14 The .pop directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID26">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. In some cases (see the <span class="bold"><strong>.push</strong></span> directive below) a warning message is +given. +</p><p> +Each string on the stack may, optionally, be associated with an upper case +letter. If <span class="bold"><strong>.pop</strong></span> is followed by an upper case letter, it searches down the +stack for a string with the same letter. If it cannot find one, it does +nothing. Otherwise, it pops off, processes, and writes out all the strings down +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" title="3.15 The .push directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID27">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 or the end of the +line, that letter is associated with the string that is pushed, which consists +either of a quoted string, or the rest of the line. After a quoted string, the +word ‘check’ may appear. In this case, if the string has not been popped off +the stack by the end of processing, a warning message is output. This facility +is used by the standard macros to give warnings for unclosed items such as +<span class="bold"><strong>.ilist</strong></span>. +</p><p> +For example, the <span class="bold"><strong>.chapter</strong></span> macro contains this line: +</p><pre class="literallayout"> + .push C &</chapter>& +</pre><p> +Earlier in the macro there is the line: +</p><pre class="literallayout"> + .pop C +</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. The +<span class="bold"><strong>.ilist</strong></span> macro contains this line: +</p><pre class="literallayout"> + .push L "&</itemizedlist>&" check +</pre><p> +Item lists are terminatated by <span class="bold"><strong>.endlist</strong></span>, which contains: +</p><pre class="literallayout"> + .pop L +</pre><p> +However, if <span class="bold"><strong>.endlist</strong></span> is accidentally omitted (or <span class="bold"><strong>.ilist</strong></span> is accidentally +included), the appearance of ‘check’ means that a warning is issued to alert +the user to a possible problem. +</p></div><div class="section" title="3.16 The .revision directive"><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. +</p><p> +The <span class="bold"><strong>.revision</strong></span> directive must be followed by one of the words <span class="quote">“<span class="quote">changed</span>”</span>, +<span class="quote">“<span class="quote">added</span>”</span>, <span class="quote">“<span class="quote">deleted</span>”</span>, or <span class="quote">“<span class="quote">off</span>”</span>. For any value other than <span class="quote">“<span class="quote">off</span>”</span>, it causes +the internal variable <span class="emphasis"><em>xfpt.rev</em></span> to be set to <code class="literal">revisionflag=</code> followed by +the given argument. If the argument is <span class="quote">“<span class="quote">off</span>”</span>, the internal variable is +emptied. +</p><p> +The contents of <span class="emphasis"><em>xfpt.rev</em></span> are included in every <code class="literal"><para></code> element that <span class="emphasis"><em>xfpt</em></span> +generates. In addition, a number of the standard macros contain references to +<span class="emphasis"><em>xfpt.rev</em></span> in appropriate places. Thus, setting: +</p><pre class="literallayout"> + .revision changed +</pre><p> +should cause all subsequent text to be marked up with <code class="literal">revisionflag</code> +attributes, until +</p><pre class="literallayout"> + .revision off +</pre><p> +is encountered. Unfortunately, at the time of writing, not all DocBook +processing software pays attention to the <code class="literal">revisionflag</code> attribute. +Furthermore, some software grumbles that it is <span class="quote">“<span class="quote">unexpected</span>”</span> on some elements, +though it does still seem to process it correctly. +</p><p> +For handling the most common case (setting and unsetting <span class="quote">“<span class="quote">changed</span>”</span>), the +standard macros <span class="bold"><strong>.new</strong></span> and <span class="bold"><strong>.wen</strong></span> are provided (see section +<a class="xref" href="#SECTrevmacs" title="4.13 Revision markings">4.13</a>). +</p></div><div class="section" title="3.17 The .set directive"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID29">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: +</p><pre class="literallayout"> + .set version 4.99 +</pre><p> +This could be referenced as <code class="literal">&version;</code>. If a variable is given the name of +an XML entity, you will not be able to refer to the XML entity, because local +variables take precedence. There is no way to delete a local variable after it +has been defined. +</p></div></div><div class="chapter" title="4. The standard macros for DocBook"><div class="titlepage"><div><div><h2 class="title"><a href="#" id="CHAPstdmac">4. The standard macros for DocBook</a></h2></div></div></div><p>A set of simple macros for commonly needed DocBook features is provided in +<span class="emphasis"><em>xfpt</em></span>’s library. This may be extended as experience with <span class="emphasis"><em>xfpt</em></span> accumulates. The +standard macros assume that the standard flags are defined, so a document that +is going to use these features should start with: +</p><pre class="literallayout"> + .include stdflags + .include stdmacs +</pre><p> +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" title="4.1 Overall setup"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID31">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"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +</pre><p> +The <span class="bold"><strong>.book</strong></span> macro has no arguments. It generates <code class="literal"><book></code> and pushes +<code class="literal"></book></code> onto the stack so that it will be output at the end. +</p></div><div class="section" title="4.2 Processing instructions"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="idp3069176">4.2 Processing instructions</a></h3></div></div></div><p>XML processing instructions such as <code class="literal"><?sdop</code> <code class="literal">toc_sections="no"?></code> can, of +course, be written written literally between <code class="literal">.literal</code> <code class="literal">xml</code> and +<code class="literal">.literal</code> <code class="literal">off</code>. If there are a lot of them, this is perhaps the most +convenient approach. A macro called <span class="bold"><strong>.pi</strong></span> is provided as an easy way of +setting up a short processing instruction. Its first argument is the name of +the processor for which the instruction is intended, and its second argument is +the contents of the instruction, for example: +</p><pre class="literallayout"> + .pi sdop 'toc_sections="yes,yes,no"' +</pre><p> +This generates <code class="literal"><?sdop</code> <code class="literal">toc_sections="yes,yes,no"?></code>. +</p></div><div class="section" title="4.3 Chapters, sections, and subsections"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID32">4.3 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 +string, it is set as an ID, and can be used in cross-references. For example: +</p><pre class="literallayout"> + .chapter "Introduction" +</pre><p> +sets no ID, but +</p><pre class="literallayout"> + .section "A section title" "SECTdemo" +</pre><p> +can be referenced from elsewhere in the document by a phrase such as: +</p><pre class="literallayout"> + see section &<<SECTdemo>>& +</pre><p> +When the title of a chapter of section is being used as a running head or foot +(for example), it may be too long to fit comfortably into the available space. +DocBook provides the facility for a title abbreviation to be specified to deal +with this problem. If a third argument is given to one of these macros, it +causes a <code class="literal"><titleabbrev></code> element to be generated. In this case, a second +argument must also be provided, but if you do not need an ID, the second +argument can be an empty string. For example: +</p><pre class="literallayout"> + .chapter "This chapter has quite a long title" "" "Long title" +</pre><p> +Where and when the abbreviation is used in place of the full title is +controlled by the stylesheet when the XML is processed. +</p></div><div class="section" title="4.4 Prefaces, appendixes, and colophons"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID33">4.4 Prefaces, appendixes, and colophons</a></h3></div></div></div><p>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">“<span class="quote">Preface</span>”</span> and <span class="quote">“<span class="quote">Colophon</span>”</span>. +</p></div><div class="section" title="4.5 Terminating chapters, etc."><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="idp3081992">4.5 Terminating chapters, etc.</a></h3></div></div></div><p>The macros for chapters, sections, appendixes, etc. use the stack to ensure +that each one is terminated at the correct point, without the need for an +explicit terminator. For example, starting a new section automatically +terminates an open subsection and a previous section. +</p><p> +Occasionally, however, there is a need to force an explicit termination. The +<span class="bold"><strong>.endchapter</strong></span>, <span class="bold"><strong>.endsection</strong></span>, <span class="bold"><strong>.endsubsection</strong></span>, <span class="bold"><strong>.endpreface</strong></span>, +<span class="bold"><strong>.endappendix</strong></span>, and <span class="bold"><strong>.endcolophon</strong></span> macros provide this facility. For +example, if you want to include an XML processing instruction after a preface, +but before the start of the following chapter, you must terminate the preface +with <span class="bold"><strong>.endpreface</strong></span>. Otherwise a processing instruction that precedes the next +<span class="bold"><strong>.chapter</strong></span> will end up inside the <code class="literal"><preface></code> element. You should not +include any actual text items at these points. +</p></div><div class="section" title="4.6 URL references"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID34">4.6 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"><ulink></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: +</p><pre class="literallayout"> + More details are &url(http://x.example, here). +</pre><p> +This generates the following XML: +</p><pre class="literallayout"> + More details are <ulink url="http://x.example">here</ulink>. +</pre><p> +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"></ulink></code>, which in most cases (such as the example above), you +do not want. +</p></div><div class="section" title="4.7 Itemized lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID35">4.7 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 +<code class="literal"><itemizedlist></code> element that is generated. The mark names that can be used +depend on the software that processes the resulting XML. For HTML output, +<span class="quote">“<span class="quote">square</span>”</span> and <span class="quote">“<span class="quote">opencircle</span>”</span> work in some browsers. +</p><p> +The text for the first item follows the macro call. The start of the next item +is indicated by the <span class="bold"><strong>.next</strong></span> macro, and the end of the list by <span class="bold"><strong>.endlist</strong></span>. +For example: +</p><pre class="literallayout"> + .ilist + This is the first item. + .next + This is the next item. + .endlist +</pre><p> +There may be more than one paragraph in an item. +</p></div><div class="section" title="4.8 Ordered lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID36">4.8 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"> +<code class="literal">arabic </code> arabic numerals<br /> +<code class="literal">loweralpha </code> lower case letters<br /> +<code class="literal">lowerroman </code> lower case roman numerals<br /> +<code class="literal">upperalpha </code> upper case letters<br /> +<code class="literal">upperroman </code> upper case roman numerals<br /> +</div><p> +The text for the first item follows the macro call. The start of the next item +is indicated by the <span class="bold"><strong>.next</strong></span> macro, and the end of the list by <span class="bold"><strong>.endlist</strong></span>. +For example: +</p><pre class="literallayout"> + .olist lowerroman + This is the first item. + .next + This is the next item. + .endlist +</pre><p> +There may be more than one paragraph in an item. +</p></div><div class="section" title="4.9 Variable lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID37">4.9 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 +one optional argument. If present, it defines a title for the list. +</p><p> +Each entry is defined by a <span class="bold"><strong>.vitem</strong></span> macro, whose arguments are the terms. +This is followed by the body of the entry. The list is terminated by the +<span class="bold"><strong>.endlist</strong></span> macro. For example: +</p><pre class="literallayout"> + .vlist "Font filename extensions" + .vitem "TTF" + TrueType fonts. + .vitem "PFA" "PFB" + PostScript fonts. + .endlist +</pre><p> +As for the other lists, there may be more than one paragraph in an item. +</p></div><div class="section" title="4.10 Nested lists"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID38">4.10 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" title="4.11 Displayed text"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID39">4.11 Displayed text</a></h3></div></div></div><p>In displayed text each non-directive input line generates one output line. The +<code class="literal"><literallayout></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. +</p><p> +The macro <span class="bold"><strong>.display</strong></span> is followed by lines that are processed in the same way +as normal paragraphs: flags are interpreted, and so there may be font changes +and so on. The lines are processed in literal layout mode. For example: +</p><pre class="literallayout"> + .display + &`-o`& set output destination + &`-S`& set library path + .endd +</pre><p> +The output is as follows: +</p><div class="literallayout"> + <code class="literal">-o</code> set output destination<br /> + <code class="literal">-S</code> set library path<br /> +</div><p> +The macro <span class="bold"><strong>.code</strong></span> is followed lines that are not processed in any way, except +to turn ampersands and angle brackets into XML entities. The lines are +processed in literal text mode. In addition, <code class="literal">class="monospaced"</code> is added to +the <code class="literal"><literallayout></code> element, so that the lines are displayed in a +monospaced font. For example: +</p><pre class="literallayout"> + .code + z = sqrt(x*x + y*y); + .endd +</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" title="4.12 Block quotes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID40">4.12 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"><blockquote></code> element. +</p></div><div class="section" title="4.13 Revision markings"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="SECTrevmacs">4.13 Revision markings</a></h3></div></div></div><p>Two macros are provided to simplify setting and unsetting the <span class="quote">“<span class="quote">changed</span>”</span> +revision marking (see section <a class="xref" href="#SECTrevision" title="3.16 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"> + This paragraph is not flagged as changed. + .new + This is a changed paragraph that contains a display: + .display + whatever + .endd + This is the next paragraph. + .wen + Here is the next, unmarked, paragraph. +</pre><p> +When called like this, without an argument, in ordinary text, <span class="bold"><strong>.new</strong></span> +terminates the current paragraph, and <span class="bold"><strong>.wen</strong></span> always does so. Therefore, even +though there are no blank lines before <span class="bold"><strong>.new</strong></span> or <span class="bold"><strong>.wen</strong></span> above, the revised +text will end up in a paragraph of its own. (You can, of course, put in blank +lines if you wish.) +</p><p> +If want to indicate that just a few words inside a paragraph are revised, you +can call the <span class="bold"><strong>new</strong></span> macro with an argument. The macro can be called either as +a directive or inline: +</p><pre class="literallayout"> + This is a paragraph that has + .new "a few marked words" + within it. Here are &new(some more) marked words. +</pre><p> +The effect of this is to generate a <code class="literal"><phrase></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><p> +You can use the <span class="bold"><strong>.new</strong></span>/<span class="bold"><strong>.wen</strong></span> macro pair to generate a <code class="literal"><phrase></code> element +inside a section of displayed text. For example: +</p><pre class="literallayout"> + .display + This line is not flagged as changed. + .new + This line is flagged as changed. + .wen + This line is not flagged as changed. + .endd +</pre><p> +This usage works with both <span class="bold"><strong>.display</strong></span> and <span class="bold"><strong>.code</strong></span>. Within a <span class="bold"><strong>.display</strong></span> +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><p> +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 class="section" title="4.14 Informal tables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID42">4.14 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. +</p><p> +The <span class="bold"><strong>.itable</strong></span> macro has four basic arguments: +</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> +The frame requirement for the table, which may be one of the words <span class="quote">“<span class="quote">all</span>”</span>, +<span class="quote">“<span class="quote">bottom</span>”</span>, <span class="quote">“<span class="quote">none</span>”</span> (the default), <span class="quote">“<span class="quote">sides</span>”</span>, <span class="quote">“<span class="quote">top</span>”</span>, or <span class="quote">“<span class="quote">topbot</span>”</span>. +</p></li><li class="listitem"><p> +The <span class="quote">“<span class="quote">colsep</span>”</span> value for the table. The default is <span class="quote">“<span class="quote">0</span>”</span>, meaning no vertical +separator lines between columns. The value <span class="quote">“<span class="quote">1</span>”</span> requests vertical separator +lines. +</p></li><li class="listitem"><p> +The <span class="quote">“<span class="quote">rowsep</span>”</span> value for the table. The default is <span class="quote">“<span class="quote">0</span>”</span>, meaning no horizontal +lines between rows. The value <span class="quote">“<span class="quote">1</span>”</span> requests horizontal separator lines. +</p></li><li class="listitem"><p> +The number of columns. +</p></li></ol></div><p> +These arguments must be followed by two arguments for each column. The first +specifies the column width, and the second its aligmnent. A column width can be +specified as an absolute dimension such as 36pt or 2in, or as a proportional +measure, which has the form of a number followed by an asterisk. The two forms +can be mixed – see the DocBook specification for details. +</p><p> +Straightforward column alignments can be specified as <span class="quote">“<span class="quote">center</span>”</span>, <span class="quote">“<span class="quote">left</span>”</span>, or +<span class="quote">“<span class="quote">right</span>”</span>. DocBook also has some other possibilities, but sadly they do not +seem to include <span class="quote">“<span class="quote">centre</span>”</span>. +</p><p> +Each row of the table is specified using a <span class="bold"><strong>.row</strong></span> macro; the entries in +the row are the macros’s arguments. The table is terminated by <span class="bold"><strong>.endtable</strong></span>, +which has no arguments. For example: +</p><pre class="literallayout"> + .itable all 1 1 2 1in left 2in center + .row "cell 11" "cell 12" + .row "cell 21" "cell 22" + .endtable +</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 resulting table looks like +this: +</p><div class="informaltable"><table border="1"><colgroup><col width="1in" align="left" /><col width="2in" 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"><entry></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"><phrase></code> element with <code class="literal">revisionflag</code> +set. +</p></div><div class="section" title="4.15 Formal tables"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID43">4.15 Formal tables</a></h3></div></div></div><p>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><pre 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 class="section" title="4.16 Figures and images"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID44">4.16 Figures and images</a></h3></div></div></div><p>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><p> +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"><mediaobject></code> element containing an +<code class="literal"><imageobject></code>. The first argument is the name of the file containing the +image. The remaining arguments are optional; an empty string must be +supplied as a placeholder when one that is not required is followed by one that +is set. +</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> +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></li><li class="listitem"><p> +The third argument specifies an alignment for the image. It must be one of +<code class="literal">left</code> (default), <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></li><li class="listitem"><p> +The fourth and fifth arguments specify the depth and width, respectively. How +these values are handled depends on the processing software. +</p></li></ul></div><p> +Here is an example of the input for a figure, with all the image options +defaulted: +</p><pre class="literallayout"> + .figure "My figure's title" "FIGfirst" + .image figure01.eps + .endfigure +</pre><p> +Here is another example, where the figure is reduced to 80% and centred: +</p><pre class="literallayout"> + .figure "A reduced figure" + .image figure02.eps 80 center + .endfigure +</pre></div><div class="section" title="4.17 Footnotes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID45">4.17 Footnotes</a></h3></div></div></div><p>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><pre class="literallayout"> + The &'quick + .footnote + That's really fast. + .endf + brown'& fox. +</pre><p> +The correct markup for this example is: +</p><pre class="literallayout"> + The &'quick'& + .footnote + That's really fast. + .endf + &'brown'& fox. +</pre></div><div class="section" title="4.18 Indexes"><div class="titlepage"><div><div><h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="#" id="ID46">4.18 Indexes</a></h3></div></div></div><p>The <span class="bold"><strong>.index</strong></span> macro generates <code class="literal"><indexterm></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 +mostly called as a directive, at the start of a relevant paragraph. For +example: +</p><pre class="literallayout"> + .index goose "wild chase" + The chasing of wild geese... +</pre><p> +You can generate <span class="quote">“<span class="quote">see</span>”</span> and <span class="quote">“<span class="quote">see also</span>”</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>. The first argument of these +macros is the text for the <span class="quote">“<span class="quote">see</span>”</span>. For example: +</p><pre class="literallayout"> + .index-see "chase" "wild goose" +</pre><p> +This generates: +</p><pre class="literallayout"> + <indexterm> + <primary>wild goose</primary> + <see>chase</see> + </indexterm> +</pre><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" + ... <lines of text> ... + .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 +<span class="quote">“<span class="quote">Index</span>”</span>. The second, if present, causes a <code class="literal">role=</code> attribute to be added to +the <code class="literal"><index></code> element that is generated. For this to be useful, you need to +generate <code class="literal"><indexterm></code> elements that have similar <code class="literal">role=</code> attributes. The +standard <span class="bold"><strong>index</strong></span> macro cannot do this. If you want to generate multiple +indexes using this mechanism, it is best to define your own macros for each +index type. For example: +</p><pre class="literallayout"> + .macro cindex + &<indexterm role="concept">& + &<primary>&$1&</primary>& + .arg 2 + &<secondary>&$2&</secondary>& + .endarg + &</indexterm>& + .endmacro +</pre><p> +This defines a <span class="bold"><strong>.cindex</strong></span> macro for the <span class="quote">“<span class="quote">concept</span>”</span> index. At the end of the +document you might have: +</p><pre class="literallayout"> + .makeindex "Concept index" "concept" + .makeindex +</pre><p> +As long as the processing software can handle multiple indexes, this causes two +indexes to be generated. The first is entitled <span class="quote">“<span class="quote">Concept index</span>”</span>, and contains +only those index entries that were generated by the <span class="bold"><strong>.cindex</strong></span> macro. The +second contains all index entries. +</p></div></div></div></body></html> diff --git a/3rd-party/xfpt/doc/xfpt.pdf b/3rd-party/xfpt/doc/xfpt.pdf Binary files differnew file mode 100644 index 000000000..5e68b1a7c --- /dev/null +++ b/3rd-party/xfpt/doc/xfpt.pdf diff --git a/3rd-party/xfpt/doc/xfpt.xfpt b/3rd-party/xfpt/doc/xfpt.xfpt new file mode 100644 index 000000000..58bbccd09 --- /dev/null +++ b/3rd-party/xfpt/doc/xfpt.xfpt @@ -0,0 +1,1211 @@ +.include stdflags +.include stdmacs + +. We are going to type the name xfpt rather a lot. Make it easier: +.set X "<emphasis>xfpt</emphasis>" + + +. ---------------------------------------------------------------------------- +.docbook +.book + +.literal xml +<bookinfo> +<title>The xfpt plain text to XML processor</title> +<titleabbrev>xfpt</titleabbrev> +<date>18 May 2012</date> +<author> + <firstname>Philip</firstname> + <surname>Hazel</surname> +</author> +<authorinitials>PH</authorinitials> +<revhistory><revision><revnumber>0.09</revnumber><date>18 May 2012</date><authorinitials>PH</authorinitials></revision></revhistory> +<copyright><year>2012</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 + + + +. ---------------------------------------------------------------------------- +.chapter "Introduction" ID00 +&X; 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 &'AsciiDoc'& (&url(http://www.methods.co.nz/asciidoc/)), +&X; does not try to produce XML from a document that is also usable as a +freestanding ASCII document. The input for &X; is very definitely &"marked +up"&. This makes it less ambiguous for large and/or complicated documents. &X; +is also much faster than &'AsciiDoc'& because it is written in C and does not +rely on pattern matching. + +&X; is aimed at users who understand the XML that they are generating. It makes +it easy to include literal XML, either in blocks, or within paragraphs. &X; +restricts itself to two special characters that trigger all its processing. + +&X; treats any input line that starts with a dot as a &'directive'& line. +Directives control the way the input is processed. A small number of directives +are implemented in the program itself. A macro facility makes it possible to +combine these in various ways to define directives for higher-level concepts +such as chapters and sections. A standard macro library that generates a simple +subset of DocBook XML is provided. The only XML element that the program itself +generates is &`<para>`&; all the others must be included as literal XML, either +directly in the input text, or, more commonly, as part of the text that is +generated by a macro call. + +The ampersand character is special within non-literal text that is processed by +&X;. An ampersand introduces a &'flag sequence'& that modifies the output. +Ampersand was chosen because it is also special in XML. As well as recognizing +flag sequences that begin with an ampersand, &X; converts grave accents and +apostrophes that appear in non-literal text into typographic opening and +closing quotes, as follows: + +.display + &` ` `& becomes ` + &` ' `& becomes ' +.endd + +Within normal input text, ampersand, grave accent, and apostrophe are the only +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 +introduce an argument substitution. + +Notwithstanding the previous paragraph, &X; knows that it is generating XML, +and in all cases when a literal ampersand or angle bracket is required in the +output, the appropriate XML entity reference (&`&&`&, &`&<`&, or +&`&>`&, respectively) is generated. + + +.section "The &X; command line" ID01 +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 four options: + +.vlist +.vitem &%-help%& +This option causes &X; to output its &"usage"& message, and exit. + +.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. + +.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. + +.vitem &%-v%& +This option causes &X; to output its version number and exit. +.endlist + + +.section "A short &X; example" ID02 +Here is a very short example of a complete &X; input file that uses some of the +standard macros and flags: +.code + .include stdflags + .include stdmacs + .docbook + .book + + .chapter "The first chapter" + This is the text of the first chapter. Here is an &'italic'& + word, and here is a &*bold*& one. + + .section "This is a section heading" + We can use the &*ilist*& macro to generate an itemized list: + .ilist + The first item in the list. + .next + The last item in the list. + .endlist + + There are also standard macros for ordered lists, literal + layout blocks, code blocks, URL references, index entries, + tables, footnotes, figures, etc. +.endd + + + +.section "Literal and non-literal processing" "SECTliteralprocessing" ID03 +&X; processes non-directive input lines in one of four ways (known as +&"modes"&): + +.ilist +In the default mode, text is processed paragraph by paragraph. +.footnote +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. + +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 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 +are recognized. The only modification &X; makes to the text is to turn +ampersand and angle bracket characters into XML entity references. This mode is +used by the standard &*.code*& macro to generate &`<literallayout>`& elements +that include &`class=monospaced`&. + +.next +In the &"literal XML"& mode, text lines are copied to the output without +modification. This is the easiest way to include a chunk of literal XML in the +output. An example might be the &`<bookinfo>`& element, which occurs only once +in a document. It is not worth setting up a macro for a one-off item like this. +.endlist + +The &*.literal*& directive switches between the modes. It is not normally used +directly, but instead is incorported into appropriate macro definitions. The +&*.inliteral*& directive can be used to test the current mode. + +Directive lines are recognized and acted upon in all four modes. However, an +unrecognized line that starts with a dot in the literal text or literal XML +mode is treated as data. In the other modes, such a line provokes an error. + +If you need to have a data line that begins with a dot in literal layout mode, +you can either specify it by character number, or precede it with some +non-acting markup. These two examples are both valid: +.code + .start with a dot + &''&.start with a dot +.endd +The second example assumes the standard flags are defined: it precedes the dot +with an empty italic string. However, this is untidy because the empty string +will be carried over into the XML. + +In literal text or literal XML mode, it is not possible to have a data line +that starts with a dot followed by the name of a directive or macro. You have +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. + + +.section "Format of directive lines" ID04 +If an input line starts with a dot followed by a space, it is ignored by &X;. +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 +are enclosed in single or double quotes. The delimiting quote character can be +included within a quoted string by doubling it. Here are some examples: +.code + .literal layout + .set version 0.00 + .row "Jack's house" 'Jill''s house' +.endd +An unrecognized directive line normally causes an error; however, in the +literal text and literal XML modes, an unrecognized line that starts with a +dot is treated as a data line. + + + +.section "Calling macros" "SECTcallingmacro" ID05 +Macros are defined by the &*.macro*& directive, which is described in section +&<<SECTmacro>>&. There are two ways of calling a macro. It can be called in the +same way as a directive, or it can be called from within text that is being +processed. The second case is called an &"inline macro call"&. + +When a macro is called as a directive, its name is given after a dot at the +start of a line, and the name may be followed by any number of optional +arguments, in the same way as a built-in directive (see the previous section). +For example: +.code + .chapter "Chapter title" chapter-reference +.endd +The contents of the macro, after argument substitution, are processed in +exactly the same way as normal input lines. A macro that is called as a +directive may contain nested macro calls. + +When a macro is called from within a text string, its name is given after an +ampersand, and is followed by an opening parenthesis. Arguments, delimited by +commas, can then follow, up to a closing parenthesis. If an argument contains a +comma or a closing parenthesis, it must be quoted. White space after a +separating comma is ignored. The most common example of this type of macro +call is the standard macro for generating a URL reference: +.code + Refer to a URL via &url(http://x.example,this text). +.endd + +There are differences in the behaviour of macros, depending on which way they +are called. A macro that is called inline may not contain references to other +macros; it must contain only text lines and calls to built-in directives. +Also, newlines that terminate text lines within the macro are not included in +the output. + +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 &*.new*& and &*.index*& macros in the +standard library are examples of macros that are designed be called either way. + + + + + +. ---------------------------------------------------------------------------- +.chapter "Flag sequences" ID06 +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 +involve any number of lines. Thus: + +.display + &`The quick &&&`& + &` brown &&&`& + &` fox.`& +.endd + +produces exactly the same output as: + +.code + The quick brown fox. +.endd + + +.section "Flag sequences for XML entities and &X; variables" ID07 +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 &`x`&. For +example: +.code + This is an Ohm sign: Ω. + This is a degree sign: °. +.endd +If an ampersand is followed by a letter, a sequence of letters, digits, and +dots is read. If this is terminated by a semicolon, the characters between the +ampersand and the semicolon are interpreted as an entity name. This can be: +.ilist +The name of an inbuilt &X; variable. At present, there is only one of these, +called &`xfpt.rev`&. Its use is described with the &*.revision*& directive +below. +.next +The name of a user variable that has been set by the &*.set*& directive, also +described below. +.next +The name of an XML entity. This is assumed if the name is not recognized as one +of the previous types. In this case, the input text is passed to the output +without modification. For example: +.code + This is an Ohm sign: &Ohm;. +.endd +.endlist + + +.section "Flag sequences for calling macros" ID08 +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 &<<SECTcallingmacro>>& for more details. + + + +.section "Other flag sequences" ID09 +Any other flag sequences that are needed must be defined by means of the +&*.flag*& 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. + +Lines are scanned from left to right when flags are being interpreted. If +there is any ambiguity when a text string is being scanned, the longest flag +sequence wins. Thus, it is possible (as in the standard flag sequences) to +define both &`&&<`& and &`&&<<`& as flags, provided that you never want to +follow the first of them with a &`<`& character. + +You can define flags that start with &`&&#`&, but these must be used with care, +lest they be misinterpreted as numerical references to XML entities. + +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, &`&&&&`& +is defined as a standalone flag with with the replacement text &`&&`&. + +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. For example, in the standard definitions, &`&&'`& and +&`'&&`& are defined as a flag pair for enclosing text in an &`<emphasis>`& +element. + +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. + +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" ID10 +If an ampersand is not followed by a character sequence in one of the forms +described in the preceding sections, an error occurs. + + +.section "Standard flag sequences" ID11 +These are the standalone flag sequences that are defined in the &_stdflags_& +file in the &X; library: +.display + &`&&&& `& becomes &` &&`& (ampersand) + &`&&-- `& becomes &` &–`& (en-dash) + &`&&~ `& becomes &` & `& (`hard' space) +.endd +These are the flag pairs that are defined in the &_stdflags_& file in the &X; +library: +.display + &`&&"..."&& `& becomes &`<quote>...</quote>`& + &`&&'...'&& `& becomes &`<emphasis>...</emphasis>`& + &`&&*...*&& `& becomes &`<emphasis role="bold">...</emphasis>`& + &`&&`...`&& `& becomes &`<literal>...</literal>`& + &`&&_..._&& `& becomes &`<filename>...</filename>`& + &`&&(...)&& `& becomes &`<command>...</command>`& + &`&&[...]&& `& becomes &`<function>...</function>`& + &`&&%...%&& `& becomes &`<option>...</option>`& + &`&&$...$&& `& becomes &`<varname>...</varname>`& + &`&&<...>&& `& becomes &`<...>`& + &`&&<<...>>&& `& becomes &`<xref linkend="..."/>`& +.endd +For example, if you want to include a literal XML element in your output, you +can do it like this: &`&&<element>&&`&. If you want to include a longer +sequence of literal XML, changing to the literal XML mode may be more +convenient. + + + + +. ---------------------------------------------------------------------------- +.chapter "Built-in directive processing" ID12 +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 descriptions +of the standard macros in chapter &<<CHAPstdmac>>&. + + +.section "The &*.arg*& directive" ID13 +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 &*.endarg*& directive, are +skipped unless the macro has been called with at least that number of +arguments and the given argument is not an empty string. If the number is +negative (minus sign present), subsequent lines are skipped if the macro has +been called with fewer than that number of arguments, or with an empty string +for the given argument. For example: +.code + .macro example + .arg 2 + Use these lines if there are at least 2 arguments + and the second one is not empty. Normally there would + be a reference to the 2nd argument. + .endarg + .arg -2 + Use this line unless there are at least 2 arguments + and the second one is not empty. + .endarg + .endmacro +.endd +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. + +The &*.arg*& directive may be nested. + + +.section "The &*.eacharg*& directive" ID14 +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. 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, +and are not processed at all. When these lines are being processed, the +remaining macro arguments can be referenced relative to the current argument. +&`$+1`& refers to the current argument, &`$+2`& to the next argument, and so +on. + +The &*.endeach*& directive may also be followed by a number, again defaulting +to 1. When &*.endeach*& is reached, the current argument number is incremented +by that number. If there are still unused arguments available, the lines +between &*.eacharg*& and &*.endeach*& are processed again. + +This example is taken from the coding for the standard &*.row*& macro, which +generates an &`<entry>`& element for each of its arguments: +.code + .eacharg + &<entry>&$+1&</entry>& + .endeach +.endd +This example is taken from the coding for the standard &*.itable*& macro, which +processes arguments in pairs to define the table's columns, starting from the +fifth argument: +.code + .eacharg 5 + &<colspec colwidth="$+1" align="$+2"/>& + .endeach 2 +.endd +The &*.eacharg*& directive may in principle be nested, though this does not +seem useful in practice. + + +.section "The &*.echo*& directive" ID15 +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. + + +.section "The &*.endarg*& directive" ID16 +See the description of &*.arg*& above. + + +.section "The &*.endeach*& directive" ID17 +See the description of &*.eacharg*& above. + + +.section "The &*.endinliteral*& directive" ID18 +See the description of &*.inliteral*& below. + + +.section "The &*.flag*& directive" ID19 +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: +.code + .flag && "&" + .flag &" "& "<quote>" "</quote>" +.endd +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. + + +.section "The &*.include*& directive" ID20 +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 &X; +library is prepended. Otherwise, the path is used unaltered. If +&*.include*& is used inside a macro, it is evaluated each time the macro is +called, and thus can be used to include a different file on each occasion. + + +.section "The &*.inliteral*& directive" ID21 +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 +literal mode does not correspond to the word, subsequent lines, up to a +&*.endinliteral*& directive, are skipped. The &*.inliteral*& directive may be +nested. + + +.section "The &*.literal*& directive" ID22 +This must be followed by one of the words &"layout"&, &"text"&, &"off"&, or +&"xml"&. It forces an end to a previous paragraph, if there is one, and then +switches between processing modes. The default mode is the &"off"& mode, in +which text is processed paragraph by paragraph, and flags are recognized. +Section &<<SECTliteralprocessing>>& describes how input lines are processed in +the four modes. + + +.section "The &*.macro*& directive" "SECTmacro" ID23 +This directive is used to define macros. It must be followed by a macro name, +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 +argument. See also &*.eacharg*& above for the use of &`$+`& to refer to +relative arguments when looping through them. A reference to an argument that +is not supplied, and is not given a default, results in an empty substitution. + +There is also a facility for a conditional substitution. A reference to an +argument of the form: +.display +&`$=`&&'<digits><delimiter><text><delimiter>'& +.endd +inserts the text if the argument is defined and is not an empty string, and +nothing otherwise. The text is itself scanned for flags and argument +substitutions. The delimiter must be a single character that does not appear in +the text. For example: +.code +&<chapter$=2+ id="$2"+>& +.endd +If this appears in a macro that is called with only one argument, the result +is: +.code +<chapter> +.endd +but if the second argument is, say &`abcd`&, the result is: +.code +<chapter id="abcd"> +.endd +This conditional feature can be used with both absolute and relative argument +references. + +If a dollar character is required as data within the body of a macro, it must +be doubled. For example: +.code + .macro price + The price is $$1. + .endmacro +.endd + +If you redefine an existing macro, the new definition overrides the old. There +is no way to revert to the previous definition. If you define a macro whose +name is the same as the name of a built-in directive you will not be able to +call it, because &X; looks for built-in directives before it looks for macros. + +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. + + +.section "The &*.nest*& directive" ID24 +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. + + +.section "The &*.nonl*& directive" ID25 +This directive must be followed by a single string argument. It is processed +as an input line 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 &*.new*& macro in the standard macros. + + +.section "The &*.pop*& directive" ID26 +&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 +remain on the stack are popped off, processed for flags, and written to the +output. In some cases (see the &*.push*& directive below) a warning message is +given. + +Each string on the stack may, optionally, be associated with an upper case +letter. If &*.pop*& is followed by an upper case letter, it searches down the +stack for a string with the same letter. If it cannot find one, it does +nothing. Otherwise, it pops off, processes, and writes out all the strings down +to and including the one that matches. + +If &*.pop*& 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. + + +.section "The &*.push*& directive" ID27 +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 or the end of the +line, that letter is associated with the string that is pushed, which consists +either of a quoted string, or the rest of the line. After a quoted string, the +word `check' may appear. In this case, if the string has not been popped off +the stack by the end of processing, a warning message is output. This facility +is used by the standard macros to give warnings for unclosed items such as +&*.ilist*&. + +For example, the &*.chapter*& macro contains this line: +.code + .push C &</chapter>& +.endd +Earlier in the macro there is the line: +.code + .pop C +.endd +This arrangement ensures that any previous chapter is terminated before +starting a new one, and also when the end of the input is reached. The +&*.ilist*& macro contains this line: +.code + .push L "&</itemizedlist>&" check +.endd +Item lists are terminatated by &*.endlist*&, which contains: +.code + .pop L +.endd +However, if &*.endlist*& is accidentally omitted (or &*.ilist*& is accidentally +included), the appearance of `check' means that a warning is issued to alert +the user to a possible problem. + +.section "The &*.revision*& directive" "SECTrevision" ID28 +This directive is provided to make it easy to set the &`revisionflag`& +attribute on XML elements in a given portion of the document. The DocBook +specification states that the &`revisionflag`& attribute is common to all +elements. + +The &*.revision*& directive must be followed by one of the words &"changed"&, +&"added"&, &"deleted"&, or &"off"&. For any value other than &"off"&, it causes +the internal variable &'xfpt.rev'& to be set to &`revisionflag=`& followed by +the given argument. If the argument is &"off"&, the internal variable is +emptied. + +The contents of &'xfpt.rev'& are included in every &`<para>`& element that &X; +generates. In addition, a number of the standard macros contain references to +&'xfpt.rev'& in appropriate places. Thus, setting: +.code + .revision changed +.endd +should cause all subsequent text to be marked up with &`revisionflag`& +attributes, until +.code + .revision off +.endd +is encountered. Unfortunately, at the time of writing, not all DocBook +processing software pays attention to the &`revisionflag`& attribute. +Furthermore, some software grumbles that it is &"unexpected"& on some elements, +though it does still seem to process it correctly. + +For handling the most common case (setting and unsetting &"changed"&), the +standard macros &*.new*& and &*.wen*& are provided (see section +&<<SECTrevmacs>>&). + + +.section "The &*.set*& directive" ID29 +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: +.code + .set version 4.99 +.endd +This could be referenced as &`&&version;`&. If a variable is given the name of +an XML entity, you will not be able to refer to the XML entity, because local +variables take precedence. There is no way to delete a local variable after it +has been defined. + + + +. ---------------------------------------------------------------------------- +.chapter "The standard macros for DocBook" "CHAPstdmac" "Standard macros" ID30 +A set of simple macros for commonly needed DocBook features is provided in +&X;'s library. This may be extended as experience with &X; accumulates. The +standard macros assume that the standard flags are defined, so a document that +is going to use these features should start with: +.code + .include stdflags + .include stdmacs +.endd +All the standard macros except &*new*&, &*index*&, and &*url*& are intended to +be called as directive lines. Their names are therefore shown with a leading +dot in the discussion below. + +.section "Overall setup" ID31 +There are two macros that should be used only once, at the start of the +document. The &*.docbook*& macro has no arguments. It inserts into the output +file the standard header material for a DocBook XML file, which is: +.code +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +.endd +The &*.book*& macro has no arguments. It generates &`<book>`& and pushes +&`</book>`& onto the stack so that it will be output at the end. + + +.section "Processing instructions" +XML processing instructions such as &`<?sdop`& &`toc_sections="no"?>`& can, of +course, be written written literally between &`.literal`& &`xml`& and +&`.literal`& &`off`&. If there are a lot of them, this is perhaps the most +convenient approach. A macro called &*.pi*& is provided as an easy way of +setting up a short processing instruction. Its first argument is the name of +the processor for which the instruction is intended, and its second argument is +the contents of the instruction, for example: +.code + .pi sdop 'toc_sections="yes,yes,no"' +.endd +This generates &`<?sdop`& &`toc_sections="yes,yes,no"?>`&. + + +.section "Chapters, sections, and subsections" ID32 +Chapters, sections, and subsections are supported by three macros that all +operate in the same way. They are &*.chapter*&, &*.section*&, and +&*.subsection*&. 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 +string, it is set as an ID, and can be used in cross-references. For example: +.code + .chapter "Introduction" +.endd +sets no ID, but +.code + .section "A section title" "SECTdemo" +.endd +can be referenced from elsewhere in the document by a phrase such as: +.code + see section &<<SECTdemo>>& +.endd +When the title of a chapter of section is being used as a running head or foot +(for example), it may be too long to fit comfortably into the available space. +DocBook provides the facility for a title abbreviation to be specified to deal +with this problem. If a third argument is given to one of these macros, it +causes a &`<titleabbrev>`& element to be generated. In this case, a second +argument must also be provided, but if you do not need an ID, the second +argument can be an empty string. For example: +.code + .chapter "This chapter has quite a long title" "" "Long title" +.endd +Where and when the abbreviation is used in place of the full title is +controlled by the stylesheet when the XML is processed. + + +.section "Prefaces, appendixes, and colophons" ID33 +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"&. + + +.section "Terminating chapters, etc." +The macros for chapters, sections, appendixes, etc. use the stack to ensure +that each one is terminated at the correct point, without the need for an +explicit terminator. For example, starting a new section automatically +terminates an open subsection and a previous section. + +Occasionally, however, there is a need to force an explicit termination. The +&*.endchapter*&, &*.endsection*&, &*.endsubsection*&, &*.endpreface*&, +&*.endappendix*&, and &*.endcolophon*& macros provide this facility. For +example, if you want to include an XML processing instruction after a preface, +but before the start of the following chapter, you must terminate the preface +with &*.endpreface*&. Otherwise a processing instruction that precedes the next +&*.chapter*& will end up inside the &`<preface>`& element. You should not +include any actual text items at these points. + + + +.section "URL references" ID34 +The &*url*& macro generates URL references, and is intended to be called inline +within the text that is being processed. It generates a &`<ulink>`& 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: +.code + More details are &url(http://x.example, here). +.endd +This generates the following XML: +.code + More details are <ulink url="http://x.example">here</ulink>. +.endd +If the second argument is absent, the contents of the first argument are used +instead. If &*url*& is called as a directive, there will be a newline in the +output after &`</ulink>`&, which in most cases (such as the example above), you +do not want. + + + +.section "Itemized lists" ID35 +The &*.ilist*& 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 &`mark=`& attribute to the +&`<itemizedlist>`& element that is generated. The mark names that can be used +depend on the software that processes the resulting XML. For HTML output, +&"square"& and &"opencircle"& work in some browsers. + +The text for the first item follows the macro call. The start of the next item +is indicated by the &*.next*& macro, and the end of the list by &*.endlist*&. +For example: +.code + .ilist + This is the first item. + .next + This is the next item. + .endlist +.endd +There may be more than one paragraph in an item. + + +.section "Ordered lists" ID36 +The &*.olist*& 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: +.display +&`arabic `& arabic numerals +&`loweralpha `& lower case letters +&`lowerroman `& lower case roman numerals +&`upperalpha `& upper case letters +&`upperroman `& upper case roman numerals +.endd +The text for the first item follows the macro call. The start of the next item +is indicated by the &*.next*& macro, and the end of the list by &*.endlist*&. +For example: +.code + .olist lowerroman + This is the first item. + .next + This is the next item. + .endlist +.endd +There may be more than one paragraph in an item. + + +.section "Variable lists" ID37 +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 &*.vlist*& macro, which has +one optional argument. If present, it defines a title for the list. + +Each entry is defined by a &*.vitem*& macro, whose arguments are the terms. +This is followed by the body of the entry. The list is terminated by the +&*.endlist*& macro. For example: +.code + .vlist "Font filename extensions" + .vitem "TTF" + TrueType fonts. + .vitem "PFA" "PFB" + PostScript fonts. + .endlist +.endd +As for the other lists, there may be more than one paragraph in an item. + + +.section "Nested lists" ID38 +Lists may be nested as required. Some DocBook processors automatically choose +different bullets for nested itemized lists, but others do not. The +&*.endlist*& 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. + + +.section "Displayed text" ID39 +In displayed text each non-directive input line generates one output line. The +&`<literallayout>`& 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. + +The macro &*.display*& is followed by lines that are processed in the same way +as normal paragraphs: flags are interpreted, and so there may be font changes +and so on. The lines are processed in literal layout mode. For example: +.code + .display + &`-o`& set output destination + &`-S`& set library path + .endd +.endd +The output is as follows: +.display + &`-o`& set output destination + &`-S`& set library path +.endd + +The macro &*.code*& is followed lines that are not processed in any way, except +to turn ampersands and angle brackets into XML entities. The lines are +processed in literal text mode. In addition, &`class="monospaced"`& is added to +the &`<literallayout>`& element, so that the lines are displayed in a +monospaced font. For example: +.code + .code + z = sqrt(x*x + y*y); + .endd +.endd + +As the examples illustrate, both kinds of display are terminated by the +&*.endd*& macro. + + + +.section "Block quotes" ID40 +The macro pair &*.blockquote*& and &*.endblockquote*& are used to wrap the +lines between them in a &`<blockquote>`& element. + + +.section "Revision markings" "SECTrevmacs" ID41 +Two macros are provided to simplify setting and unsetting the &"changed"& +revision marking (see section &<<SECTrevision>>&). When the revised text is +substantial (for example, a complete paragraph, table, display, or section), it +can be placed between &*.new*& and &*.wen*&, as in this example: +.code + This paragraph is not flagged as changed. + .new + This is a changed paragraph that contains a display: + .display + whatever + .endd + This is the next paragraph. + .wen + Here is the next, unmarked, paragraph. +.endd +When called like this, without an argument, in ordinary text, &*.new*& +terminates the current paragraph, and &*.wen*& always does so. Therefore, even +though there are no blank lines before &*.new*& or &*.wen*& above, the revised +text will end up in a paragraph of its own. (You can, of course, put in blank +lines if you wish.) + +If want to indicate that just a few words inside a paragraph are revised, you +can call the &*new*& macro with an argument. The macro can be called either as +a directive or inline: +.code + This is a paragraph that has + .new "a few marked words" + within it. Here are &new(some more) marked words. +.endd +The effect of this is to generate a &`<phrase>`& XML element with the +&`revisionflag`& attribute set. The &*.wen*& macro is not used in this case. + +You can use the &*.new*&/&*.wen*& macro pair to generate a &`<phrase>`& element +inside a section of displayed text. For example: +.code + .display + This line is not flagged as changed. + .new + This line is flagged as changed. + .wen + This line is not flagged as changed. + .endd +.endd +This usage works with both &*.display*& and &*.code*&. Within a &*.display*& +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. + +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. + + +.section "Informal tables" ID42 +The &*.itable*& 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. + +The &*.itable*& macro has four basic arguments: +.olist +The frame requirement for the table, which may be one of the words &"all"&, +&"bottom"&, &"none"& (the default), &"sides"&, &"top"&, or &"topbot"&. +.next +The &"colsep"& value for the table. The default is &"0"&, meaning no vertical +separator lines between columns. The value &"1"& requests vertical separator +lines. +.next +The &"rowsep"& value for the table. The default is &"0"&, meaning no horizontal +lines between rows. The value &"1"& requests horizontal separator lines. +.next +The number of columns. +.endlist +These arguments must be followed by two arguments for each column. The first +specifies the column width, and the second its aligmnent. A column width can be +specified as an absolute dimension such as 36pt or 2in, or as a proportional +measure, which has the form of a number followed by an asterisk. The two forms +can be mixed &-- see the DocBook specification for details. + +Straightforward column alignments can be specified as &"center"&, &"left"&, or +&"right"&. DocBook also has some other possibilities, but sadly they do not +seem to include &"centre"&. + +Each row of the table is specified using a &*.row*& macro; the entries in +the row are the macros's arguments. The table is terminated by &*.endtable*&, +which has no arguments. For example: + +.code + .itable all 1 1 2 1in left 2in center + .row "cell 11" "cell 12" + .row "cell 21" "cell 22" + .endtable +.endd + +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 resulting table looks like +this: + +.itable all 1 1 2 1in left 2in center +.row "cell 11" "cell 12" +.row "cell 21" "cell 22" +.endtable + +The &*.row*& macro does not set the &`revisionflag`& attribute in the +&`<entry>`& elements that it generates because this appears to be ignored by +all current XML processors. However, you can use an inline call of the &*new*& +macro within an entry to generate a &`<phrase>`& element with &`revisionflag`& +set. + + +.section "Formal tables" ID43 +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" ID44 +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; an empty string must be +supplied as a placeholder when one that is not required is followed by one that +is set. + +.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`& (default), &`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" ID45 +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 + + +.section "Indexes" ID46 +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 +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 +mostly called as a directive, at the start of a relevant paragraph. For +example: +.code + .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*&. 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 + +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 +arguments. The first is the title for the index, for which the default is +&"Index"&. The second, if present, causes a &`role=`& attribute to be added to +the &`<index>`& element that is generated. For this to be useful, you need to +generate &`<indexterm>`& elements that have similar &`role=`& attributes. The +standard &*index*& macro cannot do this. If you want to generate multiple +indexes using this mechanism, it is best to define your own macros for each +index type. For example: +.code + .macro cindex + &<indexterm role="concept">& + &<primary>&$1&</primary>& + .arg 2 + &<secondary>&$2&</secondary>& + .endarg + &</indexterm>& + .endmacro +.endd +This defines a &*.cindex*& macro for the &"concept"& index. At the end of the +document you might have: +.code + .makeindex "Concept index" "concept" + .makeindex +.endd +As long as the processing software can handle multiple indexes, this causes two +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 === |