$Cambridge: exim/doc/doc-docbook/AdMarkup.txt,v 1.1 2005/06/16 10:32:31 ph10 Exp $ Asciidoc markup used in the Exim documentation ---------------------------------------------- This file contains a summary of the AsciiDoc markup that is used in the source files of the Exim documentation. The source files are in plain text that can be edited by any text editor. They are converted by the AsciiDoc application into DocBook XML for subsequent processing into the various output formats. This markup requires AsciiDoc release 6.0.3 or later. The advantage of using AsciiDoc format as a "back end" is that is uses relatively simple markup in the majority of the text, making it easier to read and edit. The disadvantage is that it is tricky to deal with complicated formatting - though that is probably true of any markup language - and there are a few gotchas. The Exim documentation uses the default AsciiDoc markup with some additions. I have created a special AsciiDoc configuration file for use with the Exim documentation. You must use this configuration if you want to get sensible results, SPECIAL CHARACTERS When typing paragraphs of text, the following character sequences are recognized as markup if they occur surrounding a "word phrase" within a paragraph. In the list below, ... represents the text that is enclosed. '...' single quotes italic: used for email addresses, domains, local parts, header names, user names *...* asterisks bold used for things like "*Note:*" `...` backticks monospaced text used for literal quoting $...$ dollar Exim variable maps to XML <varname> with leading $ %...% percent Exim option, command line option maps to XML <option> ^...^ circumflex Exim driver name, Unix command, filter command maps to XML <command> ^^...^^ double circumflex C function: maps to XML <function> ^%...%^ circumflex percent parameter: maps to XML <parameter> Not currently used _..._ underscore file name: maps to XML <filename> ``...'' backticks & quotes put word in quotation marks For example, This is an 'italic phrase'. This is a _filename_ and a $variable$. This ``word'' is in quote marks. These quoting characters are recognized only if they are not flanked by alphanumeric characters. Thus, for instance, an apostrophe within a word can be represented as a single quote without any problem. Quoting can be nested, but not overlapped. However, the resulting XML from nested quotes is not always valid, so nesting is best avoided. (For example, `xxx'yyy'xxx` generates an <emphasis> item within a <literal> item, and the DocBook DTD doesn't allow that.) However, one combination that does work is <literal> within an <emphasis>, so that is what you have to use if you want a boldface monospaced font. That is, use *`bold mono`* and not `*bold mono*`. Sigh. There are also some character sequences that are translated into non-Ascii characters: -- en-dash (–) --- em-dash (舒) ~ hard space ( ) !! dagger (†} The two-character sequence ## is turned into nothing. It is useful for disambiguating markup. For example, something like ``quoted ending in 'emphasized''' is ambiguous, and as AsciiDoc looks for the longest markup first, it doesn't do what you want. You have to code this as ``quoted ending in 'emphasized'##'' The dashes are recognized only when surrounded by white space. The special Exim AsciiDoc configuration also translates most apostrophes to a typographic apostrophe (’). There are some cases where this doesn't work, for example, an apostrophe after a word in another font (because the quote character gets in the way). For this purpose, there is a named "attribute" that can be used. Named attributes are substituted inside curly braces. For example, in the filter document there is a reference to an imaginary user called lg303. User names are italicized, so this is always typed as 'lg303' but if an apostrophe-s is needed after it, you have to type 'lg303'{ap}s Another named attribute is {tl}, which turns into a tilde character, because a literal tilde becomes a hard space. A third named attribute is {hh}, which turns into two hyphens, because a literal "--" is converted into an en dash. A fourth named attributs is {pc}, which turns into a percent sign. ESCAPING SPECIAL CHARACTERS Use backslash if you need to escape a special character. ***** GOTCHA ***** Backslash is not special when it precedes any other character. Thus, you need to know which characters are special, which is a pain. COMMENTS You can include comments that will not be copied to the XML document by creating a comment block that is delimited by at least three slashes. For example: /// This is an AsciiDoc comment block. /// URL REFERENCES To refer to a URL, just put it in the text, followed by some text in square brackets to define the displayed text. If that is empty, the URL itself is displayed. For example, here's a reference to http://www.exim.org/[exim home page]. In HTML output, all you see is the display text; in printed output you see something like "exim home page [http://www.exim.org/]". The URL is printed in whatever is the current font, so it can be made bold by putting it in asterisks (for example). FORMAL PARAGRAPHS A formal paragraph has a title. This is normally typeset in bold at the start of the paragraph, and is useful as an alternative to a vertical labelled list (see below). To create such a paragraph, you just put its title first, like this: [title="the title"] Now give the text of the paragraph as usual. CHAPTERS AND SECTIONS AsciiDoc recognizes chapter and sections by looking for underlined lines, with the underlining character used to determine the type of section. This is a chapter title ----------------------- This is a section title ~~~~~~~~~~~~~~~~~~~~~~~ Chapter titles are used for running feet in the PDF form of the manual. Sometimes they are too long, causing them to be split in an ugly way. The solution to this is to define a short title for the chapter, like this: [titleabbrev="short title"] This is a rather long chapter title ----------------------------------- DISPLAYS Displayed blocks in a monospaced font can just be indented: # Exim filter deliver baggins@rivendell.middle-earth.example However, it seems that if the first line in such a block starts with an asterisk or if any lines in the block end in a backslash (as is quite often the case in Exim configuration examples), you have to use a "listing block" or a "literal block" instead of a "literal paragraph". Otherwise an initial asterisk makes AsciiDoc think this is a list item, and a terminating backslash causes lines to be concatenated. Another time when you have to use an explicit block is when a display forms part of a list item. This is because you have to indent such displays more than usual, because the processors don't appear to do this automatically. Listing blocks are delimited by lines of at least three hyphens; literal blocks are delimited by lines of at least four dots. For example: .... /usr/sbin/sendmail -bf myfilter \ -f islington@never.where <test-message .... Such blocks are indented by an amount that is specified in the style sheet, but this amount is always the same, regardless of whether the block is inside a list item (which is itself indented) or not. So if the block is within a list item, it must be explicitly indented as well. Blocks that are between lines of ampersands (at least 3 in each line) are displayed (by default) in the normal font, but with the lines unchanged. Quotes can be used in the block to specify different fonts. For example: &&&& `\n` is replaced by a newline `\r` is replaced by a carriage return `\t` is replaced by a tab &&&& When this kind of output is required within a list of any kind (see below), you must precede it with a line consisting of just a plus sign, because by default any kind of block terminates the list item. CROSS-REFERENCES To set a cross-reference point, enclose the name in double square brackets: [[SECTexample]] To refer to a cross-reference point, enclose the name in double angle brackets: <<SECTexample>> INDEX ENTRIES To create an index entry, include a line like one of these: cindex:[primary text,secondary text] oindex:[primary text,secondary text] at the appropriate point in the text. The first is for the "concept index" and the second is for the "options index". Not all forms of output distinguish between these - sometimes there is just one index. The index for the Exim reference manual has a number of "see also" entries. Rather than invent some fancy AsciiDoc way of doing this, I have just coded them in XML, using the AsciiDoc escape hatch that is described below under FUDGES. LISTS For a bulleted list, start each item in the list with a hyphen or an asterisk followed by a space: - First item. - Second item. For a numbered list, start each item with a dot followed by a space: . First item. . Second item. VERTICAL LABELLED LISTS These are used for Exim command line options and similar things. They map into XML <variablelist> items. Start the list with the item name, followed by two colons, on a line by itself. This is followed by the text for the list item. LISTS CONTAINING MORE THAN ONE PARAGRAPH If there is more than one paragraph in a list item, the second and subsequent ones must be preceded by a line containing just a single "+" character, as otherwise the list is terminated. Literal paragraphs can be included without any special markup. For example: first item:: This is the pararaph that describes the item. We can even have an indented display within the item + but any more paragraphs must be preceded by a plus character (otherwise they aren't included in the list, and won't be properly indented). The "+" notation can also be used to include other kinds of block within a list item. It's needed for all block types except nested lists and literal paragraphs. An alternative approach to lists that contain multiple paragraphs or blocks within each item is to put a line containing just two hyphens immediately before and immediately after the list. For example: -- . First item Second paragraph of first item . Second item And so on -- This is particularly helpful for nested lists (see below). NESTED LISTS You can nest lists of different types. However, if you want to revert to an outer list item at the end of a nested list, you must use the "--" feature described above for the inner list, so that its end can be explicitly marked. For example: . Outer list + Second paragraph in outer list + -- - Inner list item - Inner list second item -- + Another paragraph in the outer list first item . Next item in the outer list TABLES A fixed-width table is started by a line of hyphens that determines the width of the table, interspersed with the following column stop characters: ` backtick align left ' quote align right . dot align centre The data is then aligned with the stop characters. For example: `---`--- 1 2 3 4 -------- Alternatively, if tildes are used instead of hyphens, the data fields are comma-separated. Columns can also be specified numerically instead of by pattern. This is usually used with CSV data. For example: `10`20`30~ one, two, three ~~~~~ This format is useful when the data is full of markup so that its final length bears little relationship to the input (for example, when there are cross references). By default, tables will be rendered with a frame at the top and bottom, and no separators between rows and columns. You can use AsciiDoc "attributes" to change this. Attributes are set by a sequence of name=value items in square brackets, before the thing to which they apply. For example: [frame="none"] `-----`----- 11 22 33 44 ------------ The values for "frame" are "topbot", "sides", "all", or "none". There is also a "grid" attribute, whose possible values are "none", "cols", "rows", or "all". For example: [frame="sides", grid="cols"] The commas between the attribute settings are important; if they are omitted, AsciiDoc ignores the attribute settings. EXIM CONFIGURATION OPTION HEADINGS Each Exim configuration option is formatted with its name, usage, type, and default value on a single line, spread over the line so as to fill it completely. The only way I know of aligning text using DocBook is to use a table. A special table format has been created to handle this special case. For example: `..'= %keep_malformed%, Use: 'main', Type: 'boolean', Default: 'false' === The first line defines four colums using stop characters, followed by an equals character that defines the table's "ruler" character. There is no need to define column widths, because the style forces the columns to fill the page width. The data is comma-separated. CHANGE BARS I haven't yet found a way of doing changebars in the printed versions. However, it is possible to put a green background behind changed text in the HTML version, so the appropriate markup should be used. Before a changed paragraph, insert [revisionflag="changed"] This should precede any index settings at the start of the paragraph. If you want to do this for a display, you must use the "&&&" block described above, because that's the only type that I have set up to support it. FUDGES The current release of "fop", a program for producing PostScript from "formatting objects" (fo) data, which is an intermediate output that can be generated from DocBook XML, is not very good at page layout. For example, it can place a section heading as the last line on a page. I have set up a style that provides a means of forcing a page break in order to get round this. (But in practice, it happens so often that I have given up trying to use it.) At the AsciiDoc level, the markup uses a "backend block", which provides a way of specifying DocBook output directly. Backend blocks are surrounded by lines of plusses, and this particular fudge looks like this: ++++++++++++ <?hard-pagebreak?> ++++++++++++ Backend blocks are used to insert XML comments into the output, to mark the start and end of Exim's command line options. These are used by the x2man script that creates the man page. Philip Hazel Last updated: 10 June 2005