Commit | Line | Data |
---|---|---|
168e428f PH |
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 (–) | |
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 | ||
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 |