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"
The first is for the "concept index" and the second is for the "options 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"
.ecindex IID
The IID must be some unique string to tie 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 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
I have not yet found a way of producing change bars in the PostScript and PDF
versions of the documents. However, 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: 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.
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 XML element with the revisionflag
attribute set. The .wen macro is not used in this case.
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)" "...."
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: 31 July 2006