| 1 | $Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.2 2005/11/10 12:30:13 ph10 Exp $ |
| 2 | |
| 3 | Asciidoc markup used in the Exim documentation |
| 4 | ---------------------------------------------- |
| 5 | |
| 6 | This file contains a summary of the AsciiDoc 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 AsciiDoc application into |
| 9 | DocBook XML for subsequent processing into the various output formats. |
| 10 | |
| 11 | This markup requires AsciiDoc release 6.0.3 or later. |
| 12 | |
| 13 | The advantage of using AsciiDoc format as a "back end" is that is uses |
| 14 | relatively simple markup in the majority of the text, making it easier to read |
| 15 | and edit. The disadvantage is that it is tricky to deal with complicated |
| 16 | formatting - though that is probably true of any markup language - and there |
| 17 | are a few gotchas. |
| 18 | |
| 19 | The Exim documentation uses the default AsciiDoc markup with some additions. I |
| 20 | have created a special AsciiDoc configuration file for use with the Exim |
| 21 | documentation. You must use this configuration if you want to get sensible |
| 22 | results, |
| 23 | |
| 24 | |
| 25 | SPECIAL CHARACTERS |
| 26 | |
| 27 | When typing paragraphs of text, the following character sequences are |
| 28 | recognized as markup if they occur surrounding a "word phrase" within a |
| 29 | paragraph. In the list below, ... represents the text that is enclosed. |
| 30 | |
| 31 | '...' single quotes italic: |
| 32 | used for email addresses, domains, local |
| 33 | parts, header names, user names |
| 34 | |
| 35 | *...* asterisks bold |
| 36 | used for things like "*Note:*" |
| 37 | |
| 38 | `...` backticks monospaced text |
| 39 | used for literal quoting |
| 40 | |
| 41 | $...$ dollar Exim variable |
| 42 | maps to XML <varname> with leading $ |
| 43 | |
| 44 | %...% percent Exim option, command line option |
| 45 | maps to XML <option> |
| 46 | |
| 47 | ^...^ circumflex Exim driver name, Unix command, filter command |
| 48 | maps to XML <command> |
| 49 | |
| 50 | ^^...^^ double circumflex C function: maps to XML <function> |
| 51 | |
| 52 | ^%...%^ circumflex percent parameter: maps to XML <parameter> |
| 53 | Not currently used |
| 54 | |
| 55 | _..._ underscore file name: maps to XML <filename> |
| 56 | |
| 57 | ``...'' backticks & quotes put word in quotation marks |
| 58 | |
| 59 | For example, |
| 60 | |
| 61 | This is an 'italic phrase'. This is a _filename_ and a $variable$. |
| 62 | This ``word'' is in quote marks. |
| 63 | |
| 64 | These quoting characters are recognized only if they are not flanked by |
| 65 | alphanumeric characters. Thus, for instance, an apostrophe within a word can be |
| 66 | represented as a single quote without any problem. Quoting can be nested, but |
| 67 | not overlapped. However, the resulting XML from nested quotes is not always |
| 68 | valid, so nesting is best avoided. (For example, `xxx'yyy'xxx` generates an |
| 69 | <emphasis> item within a <literal> item, and the DocBook DTD doesn't allow |
| 70 | that.) However, one combination that does work is <literal> within an |
| 71 | <emphasis>, so that is what you have to use if you want a boldface monospaced |
| 72 | font. That is, use *`bold mono`* and not `*bold mono*`. Sigh. |
| 73 | |
| 74 | There are also some character sequences that are translated into non-Ascii |
| 75 | characters: |
| 76 | |
| 77 | -- en-dash (–) |
| 78 | --- em-dash (舒) |
| 79 | ~ hard space ( ) |
| 80 | !! dagger (†} |
| 81 | |
| 82 | The two-character sequence ## is turned into nothing. It is useful for |
| 83 | disambiguating markup. For example, something like |
| 84 | |
| 85 | ``quoted ending in 'emphasized''' |
| 86 | |
| 87 | is ambiguous, and as AsciiDoc looks for the longest markup first, it doesn't do |
| 88 | what you want. You have to code this as |
| 89 | |
| 90 | ``quoted ending in 'emphasized'##'' |
| 91 | |
| 92 | The dashes are recognized only when surrounded by white space. The special Exim |
| 93 | AsciiDoc configuration also translates most apostrophes to a typographic |
| 94 | apostrophe (’). There are some cases where this doesn't work, for |
| 95 | example, an apostrophe after a word in another font (because the quote |
| 96 | character gets in the way). For this purpose, there is a named "attribute" that |
| 97 | can be used. Named attributes are substituted inside curly braces. |
| 98 | |
| 99 | For example, in the filter document there is a reference to an imaginary user |
| 100 | called lg303. User names are italicized, so this is always typed as 'lg303' but |
| 101 | if an apostrophe-s is needed after it, you have to type |
| 102 | |
| 103 | 'lg303'{ap}s |
| 104 | |
| 105 | Another named attribute is {tl}, which turns into a tilde character, because a |
| 106 | literal tilde becomes a hard space. |
| 107 | |
| 108 | A third named attribute is {hh}, which turns into two hyphens, because a |
| 109 | literal "--" is converted into an en dash. |
| 110 | |
| 111 | A fourth named attributs is {pc}, which turns into a percent sign. |
| 112 | |
| 113 | |
| 114 | ESCAPING SPECIAL CHARACTERS |
| 115 | |
| 116 | Use backslash if you need to escape a special character. |
| 117 | |
| 118 | ***** GOTCHA ***** |
| 119 | Backslash is not special when it precedes any other character. Thus, you need |
| 120 | to know which characters are special, which is a pain. |
| 121 | |
| 122 | |
| 123 | COMMENTS |
| 124 | |
| 125 | You can include comments that will not be copied to the XML document by |
| 126 | creating a comment block that is delimited by at least three slashes. For |
| 127 | example: |
| 128 | |
| 129 | /// |
| 130 | This is an AsciiDoc comment block. |
| 131 | /// |
| 132 | |
| 133 | You can also include one-line comments by starting the line with //. |
| 134 | |
| 135 | |
| 136 | URL REFERENCES |
| 137 | |
| 138 | To refer to a URL, just put it in the text, followed by some text in square |
| 139 | brackets to define the displayed text. If that is empty, the URL itself is |
| 140 | displayed. For example, here's a reference to http://www.exim.org/[exim home |
| 141 | page]. In HTML output, all you see is the display text; in printed output you |
| 142 | see something like "exim home page [http://www.exim.org/]". The URL is printed |
| 143 | in whatever is the current font, so it can be made bold by putting it in |
| 144 | asterisks (for example). |
| 145 | |
| 146 | |
| 147 | FORMAL PARAGRAPHS |
| 148 | |
| 149 | A formal paragraph has a title. This is normally typeset in bold at the start |
| 150 | of the paragraph, and is useful as an alternative to a vertical labelled list |
| 151 | (see below). To create such a paragraph, you just put its title first, like |
| 152 | this: |
| 153 | |
| 154 | [title="the title"] |
| 155 | Now give the text of the paragraph as usual. |
| 156 | |
| 157 | |
| 158 | CHAPTERS AND SECTIONS |
| 159 | |
| 160 | AsciiDoc recognizes chapter and sections by looking for underlined lines, with |
| 161 | the underlining character used to determine the type of section. |
| 162 | |
| 163 | This is a chapter title |
| 164 | ----------------------- |
| 165 | |
| 166 | This is a section title |
| 167 | ~~~~~~~~~~~~~~~~~~~~~~~ |
| 168 | |
| 169 | Chapter titles are used for running feet in the PDF form of the manual. |
| 170 | Sometimes they are too long, causing them to be split in an ugly way. The |
| 171 | solution to this is to define a short title for the chapter, like this: |
| 172 | |
| 173 | [titleabbrev="short title"] |
| 174 | This is a rather long chapter title |
| 175 | ----------------------------------- |
| 176 | |
| 177 | |
| 178 | DISPLAYS |
| 179 | |
| 180 | Displayed blocks in a monospaced font can just be indented: |
| 181 | |
| 182 | # Exim filter |
| 183 | deliver baggins@rivendell.middle-earth.example |
| 184 | |
| 185 | However, it seems that if the first line in such a block starts with an |
| 186 | asterisk or if any lines in the block end in a backslash (as is quite often the |
| 187 | case in Exim configuration examples), you have to use a "listing block" or a |
| 188 | "literal block" instead of a "literal paragraph". Otherwise an initial asterisk |
| 189 | makes AsciiDoc think this is a list item, and a terminating backslash causes |
| 190 | lines to be concatenated. Also, a blank line in the block generates two output |
| 191 | items, so that case should also be avoided. |
| 192 | |
| 193 | Another time when you have to use an explicit block is when a display forms |
| 194 | part of a list item. This is because you have to indent such displays more than |
| 195 | usual, because the processors don't appear to do this automatically. |
| 196 | |
| 197 | Listing blocks are delimited by lines of at least three hyphens; literal blocks |
| 198 | are delimited by lines of at least four dots. For example: |
| 199 | |
| 200 | .... |
| 201 | /usr/sbin/sendmail -bf myfilter \ |
| 202 | -f islington@never.where <test-message |
| 203 | .... |
| 204 | |
| 205 | Such blocks are indented by an amount that is specified in the style sheet, but |
| 206 | this amount is always the same, regardless of whether the block is inside a |
| 207 | list item (which is itself indented) or not. So if the block is within a list |
| 208 | item, it must be explicitly indented as well. |
| 209 | |
| 210 | Blocks that are between lines of ampersands (at least 3 in each line) are |
| 211 | displayed (by default) in the normal font, but with the lines unchanged. Quotes |
| 212 | can be used in the block to specify different fonts. For example: |
| 213 | |
| 214 | &&&& |
| 215 | `\n` is replaced by a newline |
| 216 | `\r` is replaced by a carriage return |
| 217 | `\t` is replaced by a tab |
| 218 | &&&& |
| 219 | |
| 220 | When this kind of output is required within a list of any kind (see below), you |
| 221 | must precede it with a line consisting of just a plus sign, because by default |
| 222 | any kind of block terminates the list item. |
| 223 | |
| 224 | |
| 225 | CROSS-REFERENCES |
| 226 | |
| 227 | To set a cross-reference point, enclose the name in double square brackets: |
| 228 | |
| 229 | [[SECTexample]] |
| 230 | |
| 231 | To refer to a cross-reference point, enclose the name in double angle brackets: |
| 232 | |
| 233 | <<SECTexample>> |
| 234 | |
| 235 | |
| 236 | INDEX ENTRIES |
| 237 | |
| 238 | To create an index entry, include a line like one of these: |
| 239 | |
| 240 | cindex:[primary text,secondary text] |
| 241 | oindex:[primary text,secondary text] |
| 242 | |
| 243 | at the appropriate point in the text. The first is for the "concept index" and |
| 244 | the second is for the "options index". Not all forms of output distinguish |
| 245 | between these - sometimes there is just one index. |
| 246 | |
| 247 | The index for the Exim reference manual has a number of "see also" entries. |
| 248 | Rather than invent some fancy AsciiDoc way of doing this, I have just coded |
| 249 | them in XML, using the AsciiDoc escape hatch that is described below under |
| 250 | FUDGES. |
| 251 | |
| 252 | |
| 253 | LISTS |
| 254 | |
| 255 | For a bulleted list, start each item in the list with a hyphen or an asterisk |
| 256 | followed by a space: |
| 257 | |
| 258 | - First item. |
| 259 | - Second item. |
| 260 | |
| 261 | For a numbered list, start each item with a dot followed by a space: |
| 262 | |
| 263 | . First item. |
| 264 | . Second item. |
| 265 | |
| 266 | |
| 267 | VERTICAL LABELLED LISTS |
| 268 | |
| 269 | These are used for Exim command line options and similar things. They map into |
| 270 | XML <variablelist> items. Start the list with the item name, followed by two |
| 271 | colons, on a line by itself. This is followed by the text for the list item. |
| 272 | |
| 273 | |
| 274 | LISTS CONTAINING MORE THAN ONE PARAGRAPH |
| 275 | |
| 276 | If there is more than one paragraph in a list item, the second and subsequent |
| 277 | ones must be preceded by a line containing just a single "+" character, as |
| 278 | otherwise the list is terminated. Literal paragraphs can be included without |
| 279 | any special markup. For example: |
| 280 | |
| 281 | first item:: |
| 282 | This is the pararaph that describes the item. |
| 283 | |
| 284 | We can even have an indented display |
| 285 | within the item |
| 286 | + |
| 287 | but any more paragraphs must be preceded by a plus character |
| 288 | (otherwise they aren't included in the list, and won't be |
| 289 | properly indented). |
| 290 | |
| 291 | The "+" notation can also be used to include other kinds of block within a list |
| 292 | item. It's needed for all block types except nested lists and literal |
| 293 | paragraphs. |
| 294 | |
| 295 | An alternative approach to lists that contain multiple paragraphs or blocks |
| 296 | within each item is to put a line containing just two hyphens immediately |
| 297 | before and immediately after the list. For example: |
| 298 | |
| 299 | -- |
| 300 | . First item |
| 301 | |
| 302 | Second paragraph of first item |
| 303 | |
| 304 | . Second item |
| 305 | |
| 306 | And so on |
| 307 | -- |
| 308 | |
| 309 | This is particularly helpful for nested lists (see below). |
| 310 | |
| 311 | |
| 312 | NESTED LISTS |
| 313 | |
| 314 | You can nest lists of different types. However, if you want to revert to an |
| 315 | outer list item at the end of a nested list, you must use the "--" feature |
| 316 | described above for the inner list, so that its end can be explicitly marked. |
| 317 | For example: |
| 318 | |
| 319 | . Outer list |
| 320 | + |
| 321 | Second paragraph in outer list |
| 322 | + |
| 323 | -- |
| 324 | - Inner list item |
| 325 | - Inner list second item |
| 326 | -- |
| 327 | + |
| 328 | Another paragraph in the outer list first item |
| 329 | |
| 330 | . Next item in the outer list |
| 331 | |
| 332 | |
| 333 | TABLES |
| 334 | |
| 335 | A fixed-width table is started by a line of hyphens that determines the width |
| 336 | of the table, interspersed with the following column stop characters: |
| 337 | |
| 338 | ` backtick align left |
| 339 | ' quote align right |
| 340 | . dot align centre |
| 341 | |
| 342 | The data is then aligned with the stop characters. For example: |
| 343 | |
| 344 | `---`--- |
| 345 | 1 2 |
| 346 | 3 4 |
| 347 | -------- |
| 348 | |
| 349 | Alternatively, if tildes are used instead of hyphens, the data fields are |
| 350 | comma-separated. Columns can also be specified numerically instead of by |
| 351 | pattern. This is usually used with CSV data. For example: |
| 352 | |
| 353 | `10`20`30~ |
| 354 | one, two, three |
| 355 | ~~~~~ |
| 356 | |
| 357 | This format is useful when the data is full of markup so that its final length |
| 358 | bears little relationship to the input (for example, when there are cross |
| 359 | references). |
| 360 | |
| 361 | By default, tables will be rendered with a frame at the top and bottom, and no |
| 362 | separators between rows and columns. You can use AsciiDoc "attributes" to |
| 363 | change this. Attributes are set by a sequence of name=value items in square |
| 364 | brackets, before the thing to which they apply. For example: |
| 365 | |
| 366 | [frame="none"] |
| 367 | `-----`----- |
| 368 | 11 22 |
| 369 | 33 44 |
| 370 | ------------ |
| 371 | |
| 372 | The values for "frame" are "topbot", "sides", "all", or "none". There is also a |
| 373 | "grid" attribute, whose possible values are "none", "cols", "rows", or "all". |
| 374 | For example: |
| 375 | |
| 376 | [frame="sides", grid="cols"] |
| 377 | |
| 378 | The commas between the attribute settings are important; if they are omitted, |
| 379 | AsciiDoc ignores the attribute settings. |
| 380 | |
| 381 | |
| 382 | EXIM CONFIGURATION OPTION HEADINGS |
| 383 | |
| 384 | Each Exim configuration option is formatted with its name, usage, type, and |
| 385 | default value on a single line, spread over the line so as to fill it |
| 386 | completely. The only way I know of aligning text using DocBook is to use a |
| 387 | table. A special table format has been created to handle this special case. For |
| 388 | example: |
| 389 | |
| 390 | `..'= |
| 391 | %keep_malformed%, Use: 'main', Type: 'boolean', Default: 'false' |
| 392 | === |
| 393 | |
| 394 | The first line defines four colums using stop characters, followed by an equals |
| 395 | character that defines the table's "ruler" character. There is no need to |
| 396 | define column widths, because the style forces the columns to fill the page |
| 397 | width. The data is comma-separated. |
| 398 | |
| 399 | |
| 400 | CHANGE BARS |
| 401 | |
| 402 | I haven't yet found a way of doing changebars in the printed versions. However, |
| 403 | it is possible to put a green background behind changed text in the HTML |
| 404 | version, so the appropriate markup should be used. Before a changed paragraph, |
| 405 | insert |
| 406 | |
| 407 | [revisionflag="changed"] |
| 408 | |
| 409 | This should precede any index settings at the start of the paragraph. If you |
| 410 | want to do this for a display, you must use the "...." or "&&&" blocks |
| 411 | described above, because that's the only types that I have set up to support |
| 412 | it. |
| 413 | |
| 414 | |
| 415 | FUDGES |
| 416 | |
| 417 | The current release of "fop", a program for producing PostScript from |
| 418 | "formatting objects" (fo) data, which is an intermediate output that can be |
| 419 | generated from DocBook XML, is not very good at page layout. For example, it |
| 420 | can place a section heading as the last line on a page. I have set up a style |
| 421 | that provides a means of forcing a page break in order to get round this. (But |
| 422 | in practice, it happens so often that I have given up trying to use it.) |
| 423 | |
| 424 | At the AsciiDoc level, the markup uses a "backend block", which provides a way |
| 425 | of specifying DocBook output directly. Backend blocks are surrounded by lines |
| 426 | of plusses, and this particular fudge looks like this: |
| 427 | |
| 428 | ++++++++++++ |
| 429 | <?hard-pagebreak?> |
| 430 | ++++++++++++ |
| 431 | |
| 432 | Backend blocks are used to insert XML comments into the output, to mark the |
| 433 | start and end of Exim's command line options. These are used by the x2man |
| 434 | script that creates the man page. |
| 435 | |
| 436 | |
| 437 | Philip Hazel |
| 438 | Last updated: 10 June 2005 |