Install all the files that comprise the new DocBook way of making the
[exim.git] / doc / doc-docbook / AdMarkup.txt
1 $Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.1 2005/06/16 10:32:31 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    (&#x2013;)
78   ---    em-dash    (&#x8212;)
79   ~      hard space (&#x00a0;)
80   !!     dagger     (&#x2020;}
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 (&#x2019;). 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
134 URL REFERENCES
135
136 To refer to a URL, just put it in the text, followed by some text in square
137 brackets to define the displayed text. If that is empty, the URL itself is
138 displayed. For example, here's a reference to http://www.exim.org/[exim home
139 page]. In HTML output, all you see is the display text; in printed output you
140 see something like "exim home page [http://www.exim.org/]". The URL is printed
141 in whatever is the current font, so it can be made bold by putting it in
142 asterisks (for example).
143
144
145 FORMAL PARAGRAPHS
146
147 A formal paragraph has a title. This is normally typeset in bold at the start
148 of the paragraph, and is useful as an alternative to a vertical labelled list
149 (see below). To create such a paragraph, you just put its title first, like
150 this:
151
152   [title="the title"]
153   Now give the text of the paragraph as usual.
154
155
156 CHAPTERS AND SECTIONS
157
158 AsciiDoc recognizes chapter and sections by looking for underlined lines, with
159 the underlining character used to determine the type of section.
160
161   This is a chapter title
162   -----------------------
163
164   This is a section title
165   ~~~~~~~~~~~~~~~~~~~~~~~
166
167 Chapter titles are used for running feet in the PDF form of the manual.
168 Sometimes they are too long, causing them to be split in an ugly way. The
169 solution to this is to define a short title for the chapter, like this:
170
171   [titleabbrev="short title"]
172   This is a rather long chapter title
173   -----------------------------------
174
175
176 DISPLAYS
177
178 Displayed blocks in a monospaced font can just be indented:
179
180   # Exim filter
181   deliver baggins@rivendell.middle-earth.example
182
183 However, it seems that if the first line in such a block starts with an
184 asterisk or if any lines in the block end in a backslash (as is quite often the
185 case in Exim configuration examples), you have to use a "listing block" or a
186 "literal block" instead of a "literal paragraph". Otherwise an initial asterisk
187 makes AsciiDoc think this is a list item, and a terminating backslash causes
188 lines to be concatenated.
189
190 Another time when you have to use an explicit block is when a display forms
191 part of a list item. This is because you have to indent such displays more than
192 usual, because the processors don't appear to do this automatically.
193
194 Listing blocks are delimited by lines of at least three hyphens; literal blocks
195 are delimited by lines of at least four dots. For example:
196
197 ....
198 /usr/sbin/sendmail -bf myfilter \
199    -f islington@never.where <test-message
200 ....
201
202 Such blocks are indented by an amount that is specified in the style sheet, but
203 this amount is always the same, regardless of whether the block is inside a
204 list item (which is itself indented) or not. So if the block is within a list
205 item, it must be explicitly indented as well.
206
207 Blocks that are between lines of ampersands (at least 3 in each line) are
208 displayed (by default) in the normal font, but with the lines unchanged. Quotes
209 can be used in the block to specify different fonts. For example:
210
211 &&&&
212 `\n`   is replaced by a newline
213 `\r`   is replaced by a carriage return
214 `\t`   is replaced by a tab
215 &&&&
216
217 When this kind of output is required within a list of any kind (see below), you
218 must precede it with a line consisting of just a plus sign, because by default
219 any kind of block terminates the list item.
220
221
222 CROSS-REFERENCES
223
224 To set a cross-reference point, enclose the name in double square brackets:
225
226   [[SECTexample]]
227
228 To refer to a cross-reference point, enclose the name in double angle brackets:
229
230   <<SECTexample>>
231
232
233 INDEX ENTRIES
234
235 To create an index entry, include a line like one of these:
236
237   cindex:[primary text,secondary text]
238   oindex:[primary text,secondary text]
239
240 at the appropriate point in the text. The first is for the "concept index" and
241 the second is for the "options index". Not all forms of output distinguish
242 between these - sometimes there is just one index.
243
244 The index for the Exim reference manual has a number of "see also" entries.
245 Rather than invent some fancy AsciiDoc way of doing this, I have just coded
246 them in XML, using the AsciiDoc escape hatch that is described below under
247 FUDGES.
248
249
250 LISTS
251
252 For a bulleted list, start each item in the list with a hyphen or an asterisk
253 followed by a space:
254
255   - First item.
256   - Second item.
257
258 For a numbered list, start each item with a dot followed by a space:
259
260   . First item.
261   . Second item.
262
263
264 VERTICAL LABELLED LISTS
265
266 These are used for Exim command line options and similar things. They map into
267 XML <variablelist> items. Start the list with the item name, followed by two
268 colons, on a line by itself. This is followed by the text for the list item.
269
270
271 LISTS CONTAINING MORE THAN ONE PARAGRAPH
272
273 If there is more than one paragraph in a list item, the second and subsequent
274 ones must be preceded by a line containing just a single "+" character, as
275 otherwise the list is terminated. Literal paragraphs can be included without
276 any special markup. For example:
277
278   first item::
279   This is the pararaph that describes the item.
280
281     We can even have an indented display
282     within the item
283   +
284   but any more paragraphs must be preceded by a plus character
285   (otherwise they aren't included in the list, and won't be
286   properly indented).
287
288 The "+" notation can also be used to include other kinds of block within a list
289 item. It's needed for all block types except nested lists and literal
290 paragraphs.
291
292 An alternative approach to lists that contain multiple paragraphs or blocks
293 within each item is to put a line containing just two hyphens immediately
294 before and immediately after the list. For example:
295
296   --
297   . First item
298
299   Second paragraph of first item
300
301   . Second item
302
303   And so on
304   --
305
306 This is particularly helpful for nested lists (see below).
307
308
309 NESTED LISTS
310
311 You can nest lists of different types. However, if you want to revert to an
312 outer list item at the end of a nested list, you must use the "--" feature
313 described above for the inner list, so that its end can be explicitly marked.
314 For example:
315
316   . Outer list
317   +
318   Second paragraph in outer list
319   +
320   --
321   - Inner list item
322   - Inner list second item
323   --
324   +
325   Another paragraph in the outer list first item
326
327   . Next item in the outer list
328
329
330 TABLES
331
332 A fixed-width table is started by a line of hyphens that determines the width
333 of the table, interspersed with the following column stop characters:
334
335   ` backtick   align left
336   ' quote      align right
337   . dot        align centre
338
339 The data is then aligned with the stop characters. For example:
340
341   `---`---
342   1   2
343   3   4
344   --------
345
346 Alternatively, if tildes are used instead of hyphens, the data fields are
347 comma-separated. Columns can also be specified numerically instead of by
348 pattern. This is usually used with CSV data. For example:
349
350   `10`20`30~
351   one, two, three
352   ~~~~~
353
354 This format is useful when the data is full of markup so that its final length
355 bears little relationship to the input (for example, when there are cross
356 references).
357
358 By default, tables will be rendered with a frame at the top and bottom, and no
359 separators between rows and columns. You can use AsciiDoc "attributes" to
360 change this. Attributes are set by a sequence of name=value items in square
361 brackets, before the thing to which they apply. For example:
362
363   [frame="none"]
364   `-----`-----
365   11    22
366   33    44
367   ------------
368
369 The values for "frame" are "topbot", "sides", "all", or "none". There is also a
370 "grid" attribute, whose possible values are "none", "cols", "rows", or "all".
371 For example:
372
373   [frame="sides", grid="cols"]
374
375 The commas between the attribute settings are important; if they are omitted,
376 AsciiDoc ignores the attribute settings.
377
378
379 EXIM CONFIGURATION OPTION HEADINGS
380
381 Each Exim configuration option is formatted with its name, usage, type, and
382 default value on a single line, spread over the line so as to fill it
383 completely. The only way I know of aligning text using DocBook is to use a
384 table. A special table format has been created to handle this special case. For
385 example:
386
387   `..'=
388   %keep_malformed%, Use: 'main', Type: 'boolean', Default: 'false'
389   ===
390
391 The first line defines four colums using stop characters, followed by an equals
392 character that defines the table's "ruler" character. There is no need to
393 define column widths, because the style forces the columns to fill the page
394 width. The data is comma-separated.
395
396
397 CHANGE BARS
398
399 I haven't yet found a way of doing changebars in the printed versions. However,
400 it is possible to put a green background behind changed text in the HTML
401 version, so the appropriate markup should be used. Before a changed paragraph,
402 insert
403
404   [revisionflag="changed"]
405
406 This should precede any index settings at the start of the paragraph. If you
407 want to do this for a display, you must use the "&&&" block described above,
408 because that's the only type that I have set up to support it.
409
410
411 FUDGES
412
413 The current release of "fop", a program for producing PostScript from
414 "formatting objects" (fo) data, which is an intermediate output that can be
415 generated from DocBook XML, is not very good at page layout. For example, it
416 can place a section heading as the last line on a page. I have set up a style
417 that provides a means of forcing a page break in order to get round this. (But
418 in practice, it happens so often that I have given up trying to use it.)
419
420 At the AsciiDoc level, the markup uses a "backend block", which provides a way
421 of specifying DocBook output directly. Backend blocks are surrounded by lines
422 of plusses, and this particular fudge looks like this:
423
424   ++++++++++++
425   <?hard-pagebreak?>
426   ++++++++++++
427
428 Backend blocks are used to insert XML comments into the output, to mark the
429 start and end of Exim's command line options. These are used by the x2man
430 script that creates the man page.
431
432
433 Philip Hazel
434 Last updated: 10 June 2005