Make whitespace strings compare euqal to zero. fixes: bug #749
[exim.git] / doc / doc-docbook / Markup.txt
1 $Cambridge: exim/doc/doc-docbook/Markup.txt,v 1.5 2007/04/11 15:26:09 ph10 Exp $
2
3 XFPT MARKUP USED IN THE EXIM DOCUMENTATION
4 ------------------------------------------
5
6 This file contains a summary of the xfpt markup that is used in the source
7 files of the Exim documentation. The source files are in plain text that can be
8 edited by any text editor. They are converted by the xfpt application into
9 DocBook XML for subsequent processing into the various output formats.
10
11 The advantage of using xfpt format as a "back end" is that is uses relatively
12 simple markup in the majority of the text, making it easier to read and edit.
13 The disadvantage is that it is tricky to deal with complicated formatting,
14 though that is probably true of any markup language, and is certainly true of
15 XML itself.
16
17 The Exim documentation uses standard xfpt DocBook markup with a few additions.
18 The definitions of the additions that are used in spec.xfpt and filter.xfpt,
19 respectively, appear at the start of each of those files. In this file we
20 describe all the markup briefly, both the standard and additional items. See
21 the xfpt specification for more details.
22
23 Markup in xfpt is indicated in one of two ways: lines that start with a dot are
24 interpreted specially ("directive lines"), and ampersand characters within the
25 text always introduce a markup item. Recognized sequences that start with an
26 ampersand are called "flags". Some of these have "partners" that do not
27 necessarily start with an ampersand, but these must always appear after a flag
28 that starts with an ampersand. There are no other forms of markup.
29
30 There are two text characters that are not printed as their Ascii graphics.
31 These are the grave accent and the single quote. They are automatically
32 converted into opening and closing typographic quote characters in non-literal
33 text. Other input characters that are not part of some markup always stand for
34 themselves.
35
36
37 CONTINUATION LINES
38
39 Any line of input can be continued onto the next line by ending the first line
40 with the sequence &&&. The line break and any leading spaces at the start of
41 the following line are ignored. This processing happens as the lines are read
42 in, before any other processing.
43
44
45 SPECIAL CHARACTERS IN TEXT
46
47 The following flag sequences are translated to non-Ascii characters:
48
49   &--     en-dash (generates –)
50   &~      hard space (generates  )
51
52 The following two flags are for use on Exim option definitions. They are
53 designed for use within italic text; however, they terminate and restart the
54 italic so that the daggers themselves are roman. These flags do not work
55 outside italic text.
56
57   &!!     dagger         (generates </emphasis>&dagger;<emphasis>)
58   &!?     double dagger  (generates </emphasis>&Dagger;<emphasis>)
59
60 Any Unicode character can be accessed by giving its name or code point in the
61 normal XML fashion. For example, &dagger; gives a dagger and &copy; gives a
62 copyright symbol.
63
64
65 AMPERSANDS AS DATA
66
67 If you really do want an ampersand character in the text, you must type two
68 ampersands. This is a flag that expands to &amp; in the output. Of course, you
69 could also just type &amp; yourself; the flag is just for convenience.
70
71
72 PAIRED FLAGS
73
74 There are several sequences that use pairs of markup flags, surrounding some
75 enclosed text, which is represented as ... in the following list:
76
77   &'...'&    italic: maps to <emphasis>...</emphasis>
78              used for email addresses, domains, local
79              parts, header names, user names
80
81   &*...*&    bold: maps to <emphasis role="bold">...</emphasis>
82              used for things like &*Note:*&
83
84   &`...`&    monospaced text: maps to <literal>...</literal>
85              used for literal quoting in mixed-font text
86
87   &$...$&    Exim variable: maps to <varname>$...</varname>
88              note that the leading dollar is automatically inserted
89
90   &%...%&    Exim option, command line option: maps to <option>...</option>
91
92   &(...)&    Exim driver name, Unix command name, filter command name:
93              maps to <command>...</command>
94
95   &[...]&    C function: maps to <function>...</function>
96
97   &_..._&    file name: maps to <filename>...</filename>
98
99   &"..."&    put word in quotation marks: maps to <quote>...</quote>
100
101 For example,
102
103   This is an &'italic phrase'&. This is a &_filename_& and a &$variable$&.
104   This &"word"& is in quote marks.
105
106 It is important to use &"..."& rather than literal quotes so that different
107 renditions can be used for different forms of output.
108
109 These markup items can be nested, but not overlapped. However, the resulting
110 XML from nested constructions is not always valid, so nesting is best avoided
111 if possible. For example, &`xxx&'yyy'&xxx`& generates an <emphasis> item within
112 a <literal> item, and the DocBook DTD does not allow that. However, a
113 combination that does work is <literal> within an <emphasis>, so that is what
114 you have to use if you want an italic or boldface monospaced font. For example,
115 you have to use &*&`bold mono`&*& and not &`&*bold mono*&`&.
116
117
118 LITERAL XML
119
120 You can include blocks of literal XML between these two directive lines:
121
122   .literal xml
123   ...
124   .literal off
125
126 There are some examples at the start of the Exim specification. You can also
127 include individual XML elements by enclosing them in &<...>& but at the time of
128 writing there are no examples of this usage in the Exim documentation.
129
130
131 COMMENTS
132
133 You can include comments that will not be copied to the XML document by
134 starting a line with a dot followed by a space. You can include comments that
135 are copied to the XML by either of the literal XML methods just described.
136
137
138 URL REFERENCES
139
140 To refer to a URL, use &url, followed by parentheses that can enclose one or
141 two arguments, comma separated. The second, if present, is used as the
142 displayed text. If there is only one argument, it is used both as the displayed
143 text and as the URL. For example, here is a reference to
144 &url(http://www.exim.org/,the exim home page). In HTML output, all you see is
145 the display text; in printed output you see something like "the exim home page
146 [http://www.exim.org/]". The URL is printed in a bold font.
147
148
149 CHAPTERS AND SECTIONS
150
151 The directives .chapter and .section mark the beginnings of chapters and
152 sections. They are followed by a title in quotes, and optionally by up to two
153 more arguments. Either single or double quotes can be used, and if you need a
154 quote of the type being used as a delimiter within the string, it must be
155 doubled. (Quotes are not in fact needed if the title contains no white space,
156 but this is rare.)
157
158 The second argument, if present and not an empty string, is an id for
159 cross-references. For example:
160
161   .chapter "Environment for running local transports" "CHAPenvironment"
162
163 To refer to a cross-reference point, enclose the name in &<<...>>&. For
164 example:
165
166   See section &<<SECTexample>>&.
167
168 Chapter titles are used for running feet in the PostScript and PDF forms of the
169 manual. Sometimes they are too long, causing them to be split in an ugly way.
170 The solution to this is to define a short title for the running feet as the
171 third argument for .chapter or .section, like this:
172
173   .chapter "Environment for running local transports" "CHAPenvironment" &&&
174            "Environment for local transports"
175
176 Note the use of &&& in this example to continue the logical input line. If you
177 need to specify a third argument without a second argument, the second argument
178 must be given as an empty string in quotes.
179
180
181 DISPLAYS
182
183 There are two forms of text display. Displayed blocks of literal text are
184 started by .code and terminated by .endd:
185
186   .code
187   # Exim filter
188   deliver baggins@rivendell.middle-earth.example
189   .endd
190
191 No flags are recognized in such blocks, which are displayed in a monospaced
192 font.
193
194 Blocks of text between .display and .endd are displayed in the current font,
195 with the lines processed for flags as in normal paragraphs, but keeping the
196 line layout. Flags can be used in the block to specify different fonts or
197 special characters. For example:
198
199   .display
200   &`\n`&   is replaced by a newline
201   &`\r`&   is replaced by a carriage return
202   &`\t`&   is replaced by a tab
203   .endd
204
205
206 BLOCK QUOTES
207
208 Text between .blockquote and .endblockquote is forced to start a new paragraph
209 and is wrapped in a <blockquote> element.
210
211
212 INDEX ENTRIES
213
214 To create an index entry, include a line like one of these:
215
216   .cindex "primary text" "secondary text"
217   .oindex "primary text" "secondary text"
218   .vindex "&$variable_name$&"
219
220 The first is for the "concept index", the second is for the "options index",
221 and the third is for the "variables" index. The secondary text is of course
222 optional. Not all forms of output distinguish between these - sometimes there
223 is just one index. For the concept index, it is also possible to set "start"
224 and "end" markers so that the entry lists a range of pages. This is how to do
225 that:
226
227   .scindex IID "primary text" "secondary text"
228   <intervening text, should be several pages>
229   .ecindex IID
230
231 The IID must be some unique string that ties the entries together.
232
233 The index for the Exim reference manual has a number of "see also" entries.
234 These are coded in raw XML at the start of the source file.
235
236
237 LISTS
238
239 Bulleted (itemized) lists are started by .ilist, and ordered (numbered) lists
240 are started by .olist, which can be followed by "arabic", "loweralpha",
241 "lowerroman", "upperalpha", or "upperroman" to indicate the type of numeration
242 that is wanted. Each new item is started by .next, and the whole list is
243 terminated by .endlist. Lists can be nested. For example:
244
245   .ilist
246   The first item in the itemized list.
247   .olist lowerroman
248   The first item in the nested, numbered list
249   .next
250   The next item in the nested, numbered list.
251   .endlist
252   Continuing with the first item in the itemized list.
253   .next
254   The next item in the itemized list.
255   .endlist
256
257 Variable lists are used for Exim command line options and similar things. They
258 map into XML <variablelist> items. Start the list with .vlist and end it with
259 .endlist. Each item starts with a .vitem line, followed by its description. The
260 argument to .vitem must be quoted if it contains spaces. For example:
261
262   .vlist
263   .vitem &*--*&
264   This is a pseudo-option whose only purpose is to terminate the options and
265   therefore to cause subsequent command line items to be treated as arguments
266   rather than options, even if they begin with hyphens.
267
268   .vitem &*--help*&
269   This option causes Exim to output a few sentences stating what it is.
270   The same output is generated if the Exim binary is called with no options and
271   no arguments.
272   ...
273   .endlist
274
275
276 TABLES
277
278 The .itable macro directive in xfpt can be used to specify an informal table.
279 See the specification for details. The Exim specification uses this directly in
280 one place, but most of its tables contain only two columns, for which a
281 cut-down macro called .table2 has been defined. Its arguments are the widths of
282 the columns, defaulting to 190pt and 300pt, which are suitable for the many
283 tables that appear at the start of the global options definition chapter. Each
284 row in a table is defined by a .row macro, and the table ends with .endtable.
285 For example:
286
287   .table2 100pt
288   .row &_OptionLists.txt_&   "list of all options in alphabetical order"
289   .row &_dbm.discuss.txt_&   "discussion about DBM libraries"
290   ...
291   .endtable
292
293 This example overrides the width of the first column. The first arguments of
294 the .row macro do not need quotes, because they contain no white space, but
295 quotes could have been used.
296
297
298 EXIM CONFIGURATION OPTION HEADINGS
299
300 Each Exim configuration option is formatted with its name, usage, type, and
301 default value on a single output line, spread over the line so as to fill it
302 completely. The only way I know of aligning text using DocBook is to use a
303 table. The .option macro defines such a table and inserts its four arguments
304 into the cells. For example:
305
306   .option acl_not_smtp_mime main string&!! unset
307   This option causes...
308
309 The macro contains the font definitions and the heading words "Use", "Type",
310 and "Default", so you do not have to supply them. Notice the use of the &!!
311 flag to put a dagger after the word "string".
312
313
314 CHANGE BARS (REVISION MARKINGS)
315
316 I have not yet found a way of producing change bars in the PostScript and PDF
317 versions of the documents when they are generated using the "fop" command.
318 However, the revision marks do work when these formats are produced using my
319 own "sdop" processor. Also, it is possible to put a green background behind
320 changed text in the HTML version, so the appropriate markup should be used in
321 the source. There is a facility in xfpt for setting the "revisionflag"
322 attribute on appropriate XML elements. There is also a macro called .new which
323 packages this up for use in three different ways. One or more large text items
324 can be placed between .new and .wen ("wen" is "new" backwards). For example:
325
326   This paragraph is not flagged as new.
327   .new
328   This is a new paragraph that contains a display:
329   .display
330   whatever
331   .endd
332   This is the next paragraph.
333   .wen
334   Here is the next, unmarked, paragraph.
335
336 When called without an argument, .new terminates the current paragraph, and
337 .wen always does so. Therefore, even though there are no blank lines before
338 .new or .wen above, the marked text will be in a paragraph of its own. You
339 can, of course, put in blank lines if you wish, and it is probably clearer to
340 do so.
341
342 !!WARNING WARNING WARNING!!
343 If there are index directives, put them after rather than before .new because
344 otherwise you are likely to get an empty paragraph, which shows up as unwanted
345 vertical whitespace.
346 !!WARNING WARNING WARNING!!
347
348 If want to mark just a few words inside a paragraph as new, you can call the
349 .new macro with an argument. The macro can be called either as a directive or
350 as an inline macro call, which takes the form of an ampersand followed by the
351 name, with the argument in parentheses. For example:
352
353   This is a paragraph that has
354   .new "a few marked words"
355   within it. Here are &new(some more) marked words.
356
357 The effect of this is to generate a <phrase> XML element with the revisionflag
358 attribute set. The .wen macro is not used in this case.
359
360 You can also use .new/.wen inside .display and .code sections, and &new() will
361 work inside lines in a .display section. It will not work in a .code section,
362 because all text is literal.
363
364 If you want to mark a whole table as new, .new and .wen can be used to surround
365 it as described above. However, current DocBook processors do not seem to
366 recognize the "revisionflag" attribute on individual rows and table entries.
367 You can, nevertheless, mark the contents of individual table entries as changed
368 by using an inline macro call. For example:
369
370   .row "&new(some text)" "...."
371
372 This works as required when the XML is processed by "sdop" rather than "fop" to
373 generate PostScript and PDF. Each such entry must be separately marked. If
374 there are more than one or two, it may be easier just to mark the entire table.
375
376 Philip Hazel
377 Last updated: 10 April 2007