Commit | Line | Data |
---|---|---|
4f578862 | 1 | $Cambridge: exim/doc/doc-docbook/Markup.txt,v 1.2 2006/04/04 14:03:49 ph10 Exp $ |
9b371988 PH |
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>†<emphasis>) | |
58 | &!? double dagger (generates </emphasis>‡<emphasis>) | |
59 | ||
60 | Any Unicode character can be accessed by giving its name or code point in the | |
61 | normal XML fashion. For example, † gives a dagger and © 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 & in the output. Of course, you | |
69 | could also just type & 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 | ||
219 | The first is for the "concept index" and the second is for the "options index". | |
4f578862 PH |
220 | The secondary text is of course optional. Not all forms of output distinguish |
221 | between these - sometimes there is just one index. For the concept index, it is | |
222 | also possible to set "start" and "end" markers so that the entry lists a range | |
223 | of pages. This is how to do 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 to tie 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 | ||
312 | CHANGE BARS | |
313 | ||
314 | I have not yet found a way of producing change bars in the PostScript and PDF | |
315 | versions of the documents. However, it is possible to put a green background | |
316 | behind changed text in the HTML version, so the appropriate markup should be | |
317 | used in the source. There is a facility in xfpt for setting the "revisionflag" | |
318 | attribute on appropriate XML elements. There is also a macro called .new which | |
319 | packages this up for use in three different ways. One or more large text items | |
320 | can be placed between .new and .wen ("wen" is "new" backwards). For example: | |
321 | ||
322 | This paragraph is not flagged as new. | |
323 | .new | |
324 | This is a new paragraph that contains a display: | |
325 | .display | |
326 | whatever | |
327 | .endd | |
328 | This is the next paragraph. | |
329 | .wen | |
330 | Here is the next, unmarked, paragraph. | |
331 | ||
332 | When called without an argument, .new terminates the current paragraph, and | |
333 | .wen always does so. Therefore, even though there are no blank lines before | |
334 | .new or .wen above, the marked text will be in a paragraph of its own. You | |
335 | can, of course, put in blank lines if you wish, and it is probably clearer to | |
336 | do so. | |
337 | ||
338 | If want to mark just a few words inside a paragraph as new, you can call the | |
339 | .new macro with an argument. The macro can be called either as a directive or | |
340 | as an inline macro call, which takes the form of an ampersand followed by the | |
341 | name, with the argument in parentheses. For example: | |
342 | ||
343 | This is a paragraph that has | |
344 | .new "a few marked words" | |
345 | within it. Here are &new(some more) marked words. | |
346 | ||
347 | The effect of this is to generate a <phrase> XML element with the revisionflag | |
348 | attribute set. The .wen macro is not used in this case. | |
349 | ||
350 | If you want to mark a whole table as new, .new and .wen can be used to surround | |
351 | it as described above. However, current DocBook processors do not seem to | |
352 | recognize the "revisionflag" attribute on individual rows and table entries. | |
353 | You can, nevertheless, mark the contents of individual table entries as changed | |
354 | by using an inline macro call. For example: | |
355 | ||
356 | .row "&new(some text)" "...." | |
357 | ||
358 | Each such entry must be separately marked. If there are more than one or two, | |
359 | it may be easier just to mark the entire table. | |
360 | ||
361 | Philip Hazel | |
4f578862 | 362 | Last updated: 30 March 2006 |