Commit | Line | Data |
---|---|---|
9b371988 PH |
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>†<emphasis>) | |
56 | &!? double dagger (generates </emphasis>‡<emphasis>) | |
57 | ||
58 | Any Unicode character can be accessed by giving its name or code point in the | |
59 | normal XML fashion. For example, † gives a dagger and © 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 & in the output. Of course, you | |
67 | could also just type & 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" | |
f89d2485 | 216 | .vindex "&$variable_name$&" |
9b371988 | 217 | |
f89d2485 PH |
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: | |
4f578862 PH |
224 | |
225 | .scindex IID "primary text" "secondary text" | |
226 | <intervening text, should be several pages> | |
227 | .ecindex IID | |
228 | ||
f89d2485 | 229 | The IID must be some unique string that ties the entries together. |
9b371988 PH |
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 | ||
f89d2485 | 312 | CHANGE BARS (REVISION MARKINGS) |
9b371988 PH |
313 | |
314 | I have not yet found a way of producing change bars in the PostScript and PDF | |
f89d2485 PH |
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" | |
9b371988 PH |
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 | ||
3cb1b51e PH |
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!! | |
db9452a9 | 345 | |
9b371988 PH |
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 | ||
f89d2485 PH |
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 | ||
9b371988 PH |
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 | ||
f89d2485 PH |
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. | |
9b371988 PH |
373 | |
374 | Philip Hazel | |
f89d2485 | 375 | Last updated: 10 April 2007 |