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