1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375
|
XFPT MARKUP USED IN THE EXIM DOCUMENTATION
------------------------------------------
This file contains a summary of the xfpt 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 xfpt application into
DocBook XML for subsequent processing into the various output formats.
The advantage of using xfpt 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 is certainly true of
XML itself.
The Exim documentation uses standard xfpt DocBook markup with a few additions.
The definitions of the additions that are used in spec.xfpt and filter.xfpt,
respectively, appear at the start of each of those files. In this file we
describe all the markup briefly, both the standard and additional items. See
the xfpt specification for more details.
Markup in xfpt is indicated in one of two ways: lines that start with a dot are
interpreted specially ("directive lines"), and ampersand characters within the
text always introduce a markup item. Recognized sequences that start with an
ampersand are called "flags". Some of these have "partners" that do not
necessarily start with an ampersand, but these must always appear after a flag
that starts with an ampersand. There are no other forms of markup.
There are two text characters that are not printed as their Ascii graphics.
These are the grave accent and the single quote. They are automatically
converted into opening and closing typographic quote characters in non-literal
text. Other input characters that are not part of some markup always stand for
themselves.
CONTINUATION LINES
Any line of input can be continued onto the next line by ending the first line
with the sequence &&&. The line break and any leading spaces at the start of
the following line are ignored. This processing happens as the lines are read
in, before any other processing.
SPECIAL CHARACTERS IN TEXT
The following flag sequences are translated to non-Ascii characters:
&-- en-dash (generates –)
&~ hard space (generates )
The following two flags are for use on Exim option definitions. They are
designed for use within italic text; however, they terminate and restart the
italic so that the daggers themselves are roman. These flags do not work
outside italic text.
&!! dagger (generates </emphasis>†<emphasis>)
&!? double dagger (generates </emphasis>‡<emphasis>)
Any Unicode character can be accessed by giving its name or code point in the
normal XML fashion. For example, † gives a dagger and © gives a
copyright symbol.
AMPERSANDS AS DATA
If you really do want an ampersand character in the text, you must type two
ampersands. This is a flag that expands to & in the output. Of course, you
could also just type & yourself; the flag is just for convenience.
PAIRED FLAGS
There are several sequences that use pairs of markup flags, surrounding some
enclosed text, which is represented as ... in the following list:
&'...'& italic: maps to <emphasis>...</emphasis>
used for email addresses, domains, local
parts, header names, user names
&*...*& bold: maps to <emphasis role="bold">...</emphasis>
used for things like &*Note:*&
&`...`& monospaced text: maps to <literal>...</literal>
used for literal quoting in mixed-font text
&$...$& Exim variable: maps to <varname>$...</varname>
note that the leading dollar is automatically inserted
&%...%& Exim option, command line option: maps to <option>...</option>
&(...)& Exim driver name, Unix command name, filter command name:
maps to <command>...</command>
&[...]& C function: maps to <function>...</function>
&_..._& file name: maps to <filename>...</filename>
&"..."& put word in quotation marks: maps to <quote>...</quote>
For example,
This is an &'italic phrase'&. This is a &_filename_& and a &$variable$&.
This &"word"& is in quote marks.
It is important to use &"..."& rather than literal quotes so that different
renditions can be used for different forms of output.
These markup items can be nested, but not overlapped. However, the resulting
XML from nested constructions is not always valid, so nesting is best avoided
if possible. For example, &`xxx&'yyy'&xxx`& generates an <emphasis> item within
a <literal> item, and the DocBook DTD does not allow that. However, a
combination that does work is <literal> within an <emphasis>, so that is what
you have to use if you want an italic or boldface monospaced font. For example,
you have to use &*&`bold mono`&*& and not &`&*bold mono*&`&.
LITERAL XML
You can include blocks of literal XML between these two directive lines:
.literal xml
...
.literal off
There are some examples at the start of the Exim specification. You can also
include individual XML elements by enclosing them in &<...>& but at the time of
writing there are no examples of this usage in the Exim documentation.
COMMENTS
You can include comments that will not be copied to the XML document by
starting a line with a dot followed by a space. You can include comments that
are copied to the XML by either of the literal XML methods just described.
URL REFERENCES
To refer to a URL, use &url, followed by parentheses that can enclose one or
two arguments, comma separated. The second, if present, is used as the
displayed text. If there is only one argument, it is used both as the displayed
text and as the URL. For example, here is a reference to
&url(http://www.exim.org/,the exim home page). In HTML output, all you see is
the display text; in printed output you see something like "the exim home page
[http://www.exim.org/]". The URL is printed in a bold font.
CHAPTERS AND SECTIONS
The directives .chapter and .section mark the beginnings of chapters and
sections. They are followed by a title in quotes, and optionally by up to two
more arguments. Either single or double quotes can be used, and if you need a
quote of the type being used as a delimiter within the string, it must be
doubled. (Quotes are not in fact needed if the title contains no white space,
but this is rare.)
The second argument, if present and not an empty string, is an id for
cross-references. For example:
.chapter "Environment for running local transports" "CHAPenvironment"
To refer to a cross-reference point, enclose the name in &<<...>>&. For
example:
See section &<<SECTexample>>&.
Chapter titles are used for running feet in the PostScript and PDF forms 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 running feet as the
third argument for .chapter or .section, like this:
.chapter "Environment for running local transports" "CHAPenvironment" &&&
"Environment for local transports"
Note the use of &&& in this example to continue the logical input line. If you
need to specify a third argument without a second argument, the second argument
must be given as an empty string in quotes.
DISPLAYS
There are two forms of text display. Displayed blocks of literal text are
started by .code and terminated by .endd:
.code
# Exim filter
deliver baggins@rivendell.middle-earth.example
.endd
No flags are recognized in such blocks, which are displayed in a monospaced
font.
Blocks of text between .display and .endd are displayed in the current font,
with the lines processed for flags as in normal paragraphs, but keeping the
line layout. Flags can be used in the block to specify different fonts or
special characters. For example:
.display
&`\n`& is replaced by a newline
&`\r`& is replaced by a carriage return
&`\t`& is replaced by a tab
.endd
BLOCK QUOTES
Text between .blockquote and .endblockquote is forced to start a new paragraph
and is wrapped in a <blockquote> element.
INDEX ENTRIES
To create an index entry, include a line like one of these:
.cindex "primary text" "secondary text"
.oindex "primary text" "secondary text"
.vindex "&$variable_name$&"
The first is for the "concept index", the second is for the "options index",
and the third is for the "variables" index. The secondary text is of course
optional. Not all forms of output distinguish between these - sometimes there
is just one index. For the concept index, it is also possible to set "start"
and "end" markers so that the entry lists a range of pages. This is how to do
that:
.scindex IID "primary text" "secondary text"
<intervening text, should be several pages>
.ecindex IID
The IID must be some unique string that ties the entries together.
The index for the Exim reference manual has a number of "see also" entries.
These are coded in raw XML at the start of the source file.
LISTS
Bulleted (itemized) lists are started by .ilist, and ordered (numbered) lists
are started by .olist, which can be followed by "arabic", "loweralpha",
"lowerroman", "upperalpha", or "upperroman" to indicate the type of numeration
that is wanted. Each new item is started by .next, and the whole list is
terminated by .endlist. Lists can be nested. For example:
.ilist
The first item in the itemized list.
.olist lowerroman
The first item in the nested, numbered list
.next
The next item in the nested, numbered list.
.endlist
Continuing with the first item in the itemized list.
.next
The next item in the itemized list.
.endlist
Variable lists are used for Exim command line options and similar things. They
map into XML <variablelist> items. Start the list with .vlist and end it with
.endlist. Each item starts with a .vitem line, followed by its description. The
argument to .vitem must be quoted if it contains spaces. For example:
.vlist
.vitem &*--*&
This is a pseudo-option whose only purpose is to terminate the options and
therefore to cause subsequent command line items to be treated as arguments
rather than options, even if they begin with hyphens.
.vitem &*--help*&
This option causes Exim to output a few sentences stating what it is.
The same output is generated if the Exim binary is called with no options and
no arguments.
...
.endlist
TABLES
The .itable macro directive in xfpt can be used to specify an informal table.
See the specification for details. The Exim specification uses this directly in
one place, but most of its tables contain only two columns, for which a
cut-down macro called .table2 has been defined. Its arguments are the widths of
the columns, defaulting to 190pt and 300pt, which are suitable for the many
tables that appear at the start of the global options definition chapter. Each
row in a table is defined by a .row macro, and the table ends with .endtable.
For example:
.table2 100pt
.row &_OptionLists.txt_& "list of all options in alphabetical order"
.row &_dbm.discuss.txt_& "discussion about DBM libraries"
...
.endtable
This example overrides the width of the first column. The first arguments of
the .row macro do not need quotes, because they contain no white space, but
quotes could have been used.
EXIM CONFIGURATION OPTION HEADINGS
Each Exim configuration option is formatted with its name, usage, type, and
default value on a single output 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. The .option macro defines such a table and inserts its four arguments
into the cells. For example:
.option acl_not_smtp_mime main string&!! unset
This option causes...
The macro contains the font definitions and the heading words "Use", "Type",
and "Default", so you do not have to supply them. Notice the use of the &!!
flag to put a dagger after the word "string".
CHANGE BARS (REVISION MARKINGS)
I have not yet found a way of producing change bars in the PostScript and PDF
versions of the documents when they are generated using the "fop" command.
However, the revision marks do work when these formats are produced using my
own "sdop" processor. Also, it is possible to put a green background behind
changed text in the HTML version, so the appropriate markup should be used in
the source. There is a facility in xfpt for setting the "revisionflag"
attribute on appropriate XML elements. There is also a macro called .new which
packages this up for use in three different ways. One or more large text items
can be placed between .new and .wen ("wen" is "new" backwards). For example:
This paragraph is not flagged as new.
.new
This is a new paragraph that contains a display:
.display
whatever
.endd
This is the next paragraph.
.wen
Here is the next, unmarked, paragraph.
When called without an argument, .new terminates the current paragraph, and
.wen always does so. Therefore, even though there are no blank lines before
.new or .wen above, the marked text will be in a paragraph of its own. You
can, of course, put in blank lines if you wish, and it is probably clearer to
do so.
!!WARNING WARNING WARNING!!
If there are index directives, put them after rather than before .new because
otherwise you are likely to get an empty paragraph, which shows up as unwanted
vertical whitespace.
!!WARNING WARNING WARNING!!
If want to mark just a few words inside a paragraph as new, you can call the
.new macro with an argument. The macro can be called either as a directive or
as an inline macro call, which takes the form of an ampersand followed by the
name, with the argument in parentheses. For example:
This is a paragraph that has
.new "a few marked words"
within it. Here are &new(some more) marked words.
The effect of this is to generate a <phrase> XML element with the revisionflag
attribute set. The .wen macro is not used in this case.
You can also use .new/.wen inside .display and .code sections, and &new() will
work inside lines in a .display section. It will not work in a .code section,
because all text is literal.
If you want to mark a whole table as new, .new and .wen can be used to surround
it as described above. However, current DocBook processors do not seem to
recognize the "revisionflag" attribute on individual rows and table entries.
You can, nevertheless, mark the contents of individual table entries as changed
by using an inline macro call. For example:
.row "&new(some text)" "...."
This works as required when the XML is processed by "sdop" rather than "fop" to
generate PostScript and PDF. Each such entry must be separately marked. If
there are more than one or two, it may be easier just to mark the entire table.
Philip Hazel
Last updated: 10 April 2007
|