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