Commit | Line | Data |
---|---|---|
068aaea8 | 1 | $Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.2 2005/11/10 12:30:13 ph10 Exp $ |
168e428f PH |
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 | ||
068aaea8 PH |
133 | You can also include one-line comments by starting the line with //. |
134 | ||
168e428f PH |
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 | |
068aaea8 PH |
190 | lines to be concatenated. Also, a blank line in the block generates two output |
191 | items, so that case should also be avoided. | |
168e428f PH |
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 | |
068aaea8 PH |
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. | |
168e428f PH |
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 |