| 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" |
| 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 |