. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the SDoP Manual. It is an xfpt document that is
. converted into DocBook XML for subsequent conversion into printing and online
. formats. The markup used herein is "standard" xfpt markup.
. /////////////////////////////////////////////////////////////////////////////


.include stdflags
.include stdmacs

. /////////////////////////////////////////////////////////////////////////////
. This outputs the standard DocBook boilerplate.
. /////////////////////////////////////////////////////////////////////////////

.docbook

. /////////////////////////////////////////////////////////////////////////////
. These literal XML lines are processing instructions for SDoP. They adjust
. the contents of the page footers, allow table cells to overflow without
. warning if there is no overprinting, and suppress warnings for unknown
. characters (several appear in the tables at the end).
. /////////////////////////////////////////////////////////////////////////////

.literal xml
<?sdop
  foot_right_recto="&chaptertitle; (&chapternumber;)"
  foot_right_verso="&chaptertitle; (&chapternumber;)"
  table_warn_overflow="overprint"
  warn_unsupported_characters="no"
?>
.literal off

. /////////////////////////////////////////////////////////////////////////////
. These definitions set some parameters and save some typing. Remember that
. the <bookinfo> element must also be updated for each new edition.
. /////////////////////////////////////////////////////////////////////////////

.set version "1.10"
.set R "&#x261e;"
.set B "&#x200B;"

. /////////////////////////////////////////////////////////////////////////////
. This generates the outermost <book> element that wraps the entire document.
. /////////////////////////////////////////////////////////////////////////////

.book

. ////////////////////////////////////////////////////////////////////////////
. The <bookinfo> element is provided as raw XML.
. ////////////////////////////////////////////////////////////////////////////

.literal xml
<bookinfo>
<title>SDoP: A Simple DocBook Processor</title>
<titleabbrev>SDoP</titleabbrev>
<date>28 April 2023</date>
<author><firstname>Philip</firstname><surname>Hazel</surname></author>
<authorinitials>PH</authorinitials>
<address>Cambridge, England</address>
<revhistory><revision>
  <revnumber>1.10</revnumber>
  <date>28 April 2023</date>
  <authorinitials>PH</authorinitials>
</revision></revhistory>
<copyright><year>2023</year><holder>Philip Hazel</holder></copyright>
</bookinfo>
.literal off

. /////////////////////////////////////////////////////////////////////////////
. Set up some "see" index entries
. /////////////////////////////////////////////////////////////////////////////

.index-see "heads and feet"     "feet"
.index-see "table of contents"  "contents"


. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////

.chapter "Introduction"
SDoP is a Simple DocBook Processor. It reads DocBook XML input and writes
PostScript output. The output can easily be converted into PDF form by the
&(ps2pdf)& command that comes as part of the GhostScript package. This document
describes SDoP version &version;. Cross-references should be clickable if the
PDF reader you are using supports the feature.

The first version of SDoP was written to support just those features of DocBook
that were needed to format the Exim manual. Further features have been added,
and this version has some support for almost all the elements that are part of
&'Simplified DocBook'&, as defined in the following URL:
.index "Simplified DocBook"
.index "DocBook" "Simplified DocBook"

.display
&<emphasis role="smallfont">&&url(http://docs.huihoo.com/docbook/&&&
simplified-docbook-definitive-guide/sdocbook.html)&</emphasis>&
.endd

.index "DocBook" "omitted features"
The main omissions are support for bibliographies, multiple authors,
subtables within tables, and some element attributes. Chapter
&<<CHAPsuppelems>>& of this document contains a complete list of what SDoP does
support.

SDoP supports illustrations, supplied as separate files, in several formats.
Encapsulated PostScript (.eps) is always supported. If the relevant libraries
are found when SDoP is being built, JPEG and PNG files are supported. There is
also some inbuilt support for Scalable Vector Graphics (.svg) files. This makes
use of the &(nanosvg)& source library
(&url(https://github.com/memononen/nanosvg)), modified to support text items.
For details, see section &<<SECTillfig>>& below.

I wrote SDoP because at that time the available non-commercial processors for
converting DocBook into PostScript or PDF were not only slow and cumbersome,
but also did not produce satisfactory output (see chapter &<<CHAPtypeset>>&). I
included `simple' in the program's name for the following reasons:
.ilist
SDoP does not check that the input conforms to a DocBook DTD, though it does
check that element starting and ending tags are correctly nested. Few people
write XML by hand, and what is generated by program is likely to be correct.
There are programs such as &(xmllint)& that can be used to validate XML if you
want to check your source before giving it to SDoP.
.next
SDoP is a single program, written in C, that does not rely on external
information, except for a few associated data files. This makes it very fast.
When it was first written it could process the Exim manual (466 pages) in under
2.5 seconds on the author's workstation; in contrast, using &(xmlto)& to
generate `formatting objects' and then &(fop)& to make PostScript took around 2
minutes.
.next
SDoP makes no use of complicated stylesheets such as XSL, though the way it
formats the output can be adjusted to some extent by means of embedded
processing instructions (see chapter &<<CHAPprocinst>>&).
.endlist


.section "Installing SDoP"
.index "installing SDoP"
You should be able to build and install SDoP using the traditional commands:
.code
./configure
make
make install
.endd
.index "JPEG support"
.index "PNG support"
The installation consists of one binary, one &'man'& page, and a directory
containing SDoP's data files (see chapter &<<CHAPdatafiles>>&). This is usually
installed as &(/usr/local/share/sdop)&. SDoP is automatically compiled with
support for handling JPEG and/or PNG images if the &(libjpeg)& and/or
&(libpng)& libraries, respectively, are installed. You can disable this support
by adding &`--disable-jpeg`& and/or &`--disable-png`& to the &`./configure`&
command.



.section "The SDoP command line"
.index "command line"
The SDoP command line is of the following form:
.display
&`sdop`& [&'options'&] [&'source file'&]
.endd
.index "input" "specifying"
.index "output" "specifying"
If no source file is given, the source is read from the standard input.
Output is by default written to the standard output if the source is the
standard input; otherwise it is written to a file whose name is the same as the
source, but with the extension changed to &_.ps_&. However, the destination can
be specified explicitly by the &%-o%& option.

.index "&$SDOP_SHARE$&"
.index "data files" "specifying location"
The &$SDOP_SHARE$& environment variable can be set to a colon-separated list of
directories that are searched, in order, when SDoP needs to read one of its
data files (see chapter &<<CHAPdatafiles>>&). If the required file is not found
in one of these directories, the default directory (often
&_/usr/local/share/sdop/_&) is searched. The &%-S%& option can be used to
override &$SDOP_SHARE$&.

.vlist
.vitem &%-d%&
.index "&*-d*& option"
.index "debugging option"
This option causes a small amount of debugging output to be written to the
standard error stream. More detailed output can be obtained by adding &'+name'&
after &%-d%&; a list of debugging names can be found from the &%--help%&
option.

.vitem "&%-help%& or &%--help%&"
.index "&*--help*& option"
This causes SDoP to list the available options and then exit.

.vitem &%-o%&&~<&'output-file'&>
.index "&*-o*& option"
This option overrides the default output destination. If the output is
specified as a single hyphen character, the standard output is used.

.vitem &%-p%&&~<&'page-list'&>
.index "&*-p*& option"
.index "output, selecting pages"
.index "page" "selection option"
This option restricts the output to just those pages that are listed. The pages
are counted from the start of the body of the document, that is, after any
front matter (title pages, table of contents, preface). In other words, they
are a book's `normal' page numbers.

A comma is used to separate items in a page list, and each item can be a single
page number or a hyphen-separated range. The page numbers must be in numerical
order. If either of the words `odd' or `even' appears anywhere in the list,
the entire output is restricted to either odd or even pages, respectively. If
both appear, there is no restriction. For example:
.code
sdop -p odd,23,35-50,99 myfile.xml
.endd
If `odd' or `even' is given with no page numbers, and there is no &%-pf%&
option, all odd or even pages (respectively), including front matter pages, are
output.

.index "bookmark information"
.index "cross-reference information"
.index "index" "page number links"
By default, SDoP includes bookmark information and link information for
cross-references and index page numbers in the output, for use when the
PostScript is converted to PDF. However, this feature is disabled when &%-p%&
or &%-pf%& is used, because the output is then incomplete.


.vitem &%-pf%&&~<&'page-list'&>
.index "&*-pf*& option"
.index "output, selecting pages"
.index "page" "selection option"
This option is like &%-p%&, except that the pages are counted from the very
start of the output, that is, this option is used to select pages from the
book's front matter. Unlike &%-p%&, `odd' and `even' may not appear in the
page list for &%-pf%&. However, you can use &%-p%& (with or without a page
list) in the same command as &%-pf%&, for example:
.code
sdop -p odd -pf 5-11 myfile.xml
.endd
This outputs just the odd pages from those selected from the front matter.

.vitem &%-q%&
.index "&*-q*& option"
.index "warnings" "suppressing"
This suppresses the default warnings that SDoP outputs for unsupported DocBook
elements and attributes, all of which are ignored. It overrides any setting
that may be in an SDoP processing instruction within the source document.

.vitem &%-qc%&
.index "&*-qc*& option"
.index "warnings" "suppressing"
This suppresses the default warnings that SDoP outputs for any unsupported
characters that it encounters. It overrides any setting that may be in an SDoP
processing instruction within the source document. Unsupported characters are
those that are not available in the PostScript fonts.

.vitem "&%-S%&&~<&'directory list'&>"
.index "&*-S*& option"
.index "data files" "specifying location"
This option supplies a colon-separated list of directories that are to be
searched, in order, when SDoP needs to read one of its data files (see chapter
&<<CHAPdatafiles>>&). If the required file is not found in one of these
directories, the default directory (often &_/usr/local/share/sdop/_&) is
searched.
.index "&$SDOP_SHARE$&"
This option overrides a value taken from the &$SDOP_SHARE$& environment
variable.

.vitem "&%-v%& or &%--version%&"
.index "&*-v*& option"
.index "&*--version*& option"
.index "version number, output of"
This causes SDoP to output its version number and to list any optional
facilities (such as JPEG support) that are available, and then exit.

.vitem &%-w%&
.index "&*-w*& option"
.index "warnings" "requesting"
This requests warning messages for unsupported DocBook elements and attributes
(the inverse of &%-q%&). It overrides any setting that may be in an SDoP
processing instruction within the source document.

.vitem &%-wc%&
.index "&*-wc*& option"
.index "warnings" "requesting"
This requests warnings for unsupported characters (the inverse of &%-qc%&). It
overrides any setting that may be in an SDoP processing instruction within the
source document. Unsupported characters are those that are not present in the
PostScript fonts.
.endlist


.section "SDoP input"
.index "input" "format of"
.index "Unicode"
SDoP expects its input to be XML, encoded in Unicode, using UTF-8 for
characters whose code points have a value that is greater than 127. SDoP
interprets XML elements (for example, &`<chapter>`&) as specified by DocBook,
though it makes no attempt to validate the input against a DocBook DTD. There
are programs such as &(xmllint)& that can be used for validation if you want
check your source before giving it to SDoP.

You can feed SDoP fragmentary input containing, for example, just a sequence of
&`<para>`& elements, and it will try to make sense of it. However, if the
nesting of elements contradicts the DocBook DTD, the results may not be what
you expect.

The elements that are recognized are listed below in chapter
&<<CHAPsuppelems>>&. Recognition of an element does not mean that SDoP actually
does any processing for it. For example, &`<trademark>`& is recognized, but has
no effect on the output. Unrecognized elements are completely ignored, though
by default SDoP outputs a list of them to the standard error stream at the end
of processing. This can be suppressed by means of the
.index "&*-q*& option"
.index "warnings" "suppressing"
&%-q%& command line option, or the &*warn_unsupported*& parameter (&R;
&<<SECTwarnings>>&).

SDoP recognizes a number of standard entities such as &`&&amp;`& (which
represents a literal ampersand character). These are listed in chapter
&<<CHAPsuppents>>& below. In addition, there are some special entities that are
useful for referencing text strings for title pages, the table of contents,
headers, and footers (&R; &<<CHAPusingbi>>&, &<<SECTtabofcont>>&,
&<<SECThandf>>&).


.section "SDoP output"
.index "output" "format of"
.index "&*-p*& option"
.index "&*-pf*& option"
SDoP outputs an entire book or article as a single PostScript file. This can be
viewed by applications such as GhostScript, or printed by PostScript-compatible
printers. The file can also be turned into a PDF using (for example) the
&(ps2pdf)& command that comes as part of the GhostScript package.
.index "PDF bookmarks"
.index "PDF cross-references"
The PDF format supports bookmarks that are normally displayed in a sidebar, and
also clickable links within the document. Fortunately, there is a scheme for
including appropriate information in a PostScript file such that, when it is
turned into a PDF, bookmarks and clickable links are generated.
.index "&*-p*& option"
.index "&*-pf*& option"
Except when the output is restricted to specific pages by the &%-p%& or &%-pf%&
options, SDoP generates such information automatically, as follows:

.ilist
If a table of contents is being generated, bookmarks are created for chapters
and sections. It is possible, by making use of the &*toc_printed_sections*&
parameter (&R; &<<SECTtoc>>&), to include more entries in the PDF
bookmarks than are in the printed table of contents.
.next
If there are any &`<xref>`& items in the input, clickable links are generated
for their text.
.next
If an index is generated, the page numbers it contains are made into clickable
links.
.endlist
The last two facilities can be suppressed by setting the &*xref_links*&
parameter to &`no`&. The colour of these links is by default the same colour as
the surrounding text, but it can be explicitly specified by &*xref_rgb*&.

The complete output for a fully-featured book consists of the following sets of
pages:
.index "book" "title pages"
.olist
A title page and its reverse; this is output if there is a &`<book>`& element
that has an associated &`<title>`& element, or if a title is supplied in a
&`<bookinfo>`& element (&R; &<<SECTtitlepages>>&).
.next
A table of contents; this is omitted if it would be empty. The
&*toc_sections*&, &*toc_printed_sections*&, and &*index_headings_pdf_toc*&
parameters (&R; &<<SECTtoc>>&, &<<SECTindex>>&) control what is included.
.next
One or more `prefaces' (for example, a preface and a foreword), if present in
the input.
.next
The main body of the book; this is always output.
.next
One or more appendices, if present in the input.
.next
One or more indexes; these are output at the points where the &`<index>`&
elements appear in the document. However, an index is not generated if there
are no relevant &`<indexterm>`& elements.
.next
One or more colophons, if present in the input.
.endlist
You can mix multiple indexes, chapters, and appendices in an arbitrary order,
though this feature is rarely needed,

.index "article" "title material"
An article is similar to a single chapter of a book. The output for an article
does not have a title page or table of contents. The article's title material
appears at the top of the first body page. An article cannot contain prefaces,
indexes, or colophons. An appendix is treated as a new section, whereas in a
book it is treated as a new chapter.



.section "SDoP Errors"
.index "errors, in input"
Error and warning messages are written to the standard error stream. If there
are more than 40 warnings, subsequent ones are suppressed, with a message to
say this is happening. If there are more than 40 errors, processing is
abandoned. For some disastrous errors, processing is abandoned immediately.

Certain errors are not serious enough to stop processing of the input file, but
would cause problems if any output were attempted. A message is output to say
that nothing has been generated. In other error cases (for example, line length
overflow), as well as after warnings, output is generated, but a message is
written to say that it might be flawed.

The return code from SDoP is the system value EXIT_SUCCESS (usually zero) if
there have been no problems more serious than a warning; otherwise it is
EXIT_FAILURE (usually 1).



. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Processing Instructions" "CHAPprocinst"
.index-from "ID1" "processing instructions"
XML allows for &'processing instructions'& to be embedded in sources. A
processing instruction is of the form shown in this example:
.code
<?sdop table_warn_overflow="never" toc_sections="yes,no"?>
.endd
After the initial &`<?`& the name of the application for which this instruction
is intended appears. All other applications that process the input should
completely ignore the item. SDoP pays attention only to those that start with
&`<?sdop`&.

.index "processing instructions" "parameter types"
A processing instruction can contain any number of parameter settings and may
extend over more than one line. Each parameter specifies a value as a quoted
string, the interpretation of which depends on the particular parameter. SDoP's
processing parameters are of three kinds:
.ilist
&'Preprocessing'& parameters modify the input before the main processing
takes place.
.next
&'Global'& parameters apply throughout the document. An example might be an
instruction about the format of the table of contents. SDoP scans the input
for these parameters early on. If the same parameter is set more than once, it
is the last value that is used.
.next
&'Local'& parameters are processed inline with the text. They apply only to
what follows. For example, the use of hyphenation can be turned on and off for
different parts of the document.
.endlist

There is one restriction on SDoP's processing instructions: they must not
appear between a &`<book>`& and a &`<bookinfo>`& element or between an
&`<article>`& and an &`<articleinfo>`& element.



.section "Including other files"
.index "including other files"
.index "files" "including"
A preprocessing instruction is available for including an external file at a
given point in the input. The format is:
.display
&`<?sdop include="`&&'filename'&&`"?>`&
.endd
This could be used to bring in an SDoP `style' definition (a collection of
processing instructions) that is held externally. The &(include)& instruction
is processed immediately after the main input has been read.



.section "Skipping parts of the input" "SECTskippart"
.index "input" "skipping parts of"
There is a facility for skipping parts of the input. At present this feature is
of little use outside the title templates (&R; &<<SECTtitlepages>>&,
&<<SECTarttitle>>&). There are two forms of conditional:
.display
&`<?sdop ifdef="`&&'name'&&`"?>`&
&'...lines of input...'&
&`<?sdop endif=""?>`&
&nbsp;
&`<?sdop ifndef="`&&'name'&&`"?>`&
&'...lines of input...'&
&`<?sdop endif=""?>`&
.endd
In the first form, the intermediate lines are processed if an entity with the
given name exists and contains a non-empty string. The second form applies the
opposite condition. For example, a title page template might contain this:
.code
<?sdop ifdef="book_subtitle"?>
<row>
<entry>
<emphasis role="booktitle2">&book_subtitle;</emphasis>
</entry>
</row>
<?sdop endif=""?>
.endd
This example inserts a row containing the book's subtitle in the table that is
used for the title page, but only if a subtitle has been specified.

The conditional parameters are obeyed after extracting information from the
&`<bookinfo>`& or &`<article>`& element, if present, and after processing any
global instructions. They may be nested arbitrarily deep.


.section "Changing font styles" "SECTchfontstyle"
.index "fonts" "changing styles"
A number of parameters whose names end with &*_style*& make it easy to change
the styles of fonts that are used for certain DocBook elements, without
affecting other font features such as size or font family. For example, to
specify the style that is to be used for the text of &`<command>`& elements:
.code
<?sdop command_style="bold"?>
.endd
The recognized values that can be specified for these parameters are: &`bold`&,
&`bolditalic`&, &`italic`&, &`mono`&, &`monobold`&, &`monobolditalic`&,
&`monoitalic`&, and &`roman`&.


.section "Changing font families" "SECTchfontfam"
.index "fonts" "changing families"
The font families that are used by default are Times, Helvetica, and Courier.
These can be changed by the processing parameters &*serif_family*&,
&*sanserif_family*&, and &*monospace_family*&. For example:
.code
<?sdop serif_family="Palatino"
       sanserif_family="AvantGarde"?>
.endd
However, the family specified must be one that SDoP knows about, so that it can
generate appropriate suffixes for bold, italic, and roman fonts. The currently
known families are: AvantGarde, Bookman, Courier, Helvetica, NewCenturySchlbk,
Palatino, Times, and Utopia.
.index "fonts" "metric files"
In addition, the font metric (AFM) files for the specific fonts must be
available in SDoP's shared data files (&R; &<<SECTmetrics>>&).

There is a facility for accessing characters from individual special fonts that
are not available in the standard families, for example a font of musical
characters. This uses an extension of the &`<emphasis>`& element (&R;
&<<SECTexotic>>&).


.section "Specifying fonts sizes and styles" "SECTchindfont"
.index "fonts" "specifying"
There are a number of processing parameters with names starting &*font_*& that
allow you to specify a font size and style for a specific type of text. For
example:
.code
<?sdop font_chapter="20,2,serif,bolditalic"?>
.endd
The first figure is the point size of the font, and the second is the
additional vertical spacing (leading) that is associated with the font. For
single fonts such as the one used for chapter titles, up to four
comma-separated values can be given, as in the example above. Omitting a value
leaves the related parameter unchanged. For example,
.code
<?sdop font_section="13"?>
.endd
sets the size of section titles, without changing the leading, family or
style. The third value must be &`serif`&, &`sanserif`&, or &`monospaced`&, and
the fourth must be the name of a font style (&R; &<<SECTchfontstyle>>&).


.section "Specifying font sets" "SECTchfontset"
.index "fonts" "specifying sets of"
Some &*font_*& parameters control sets of fonts. For example, &*font_main*&
defines the set of eight fonts (four normal, four monospaced) used for the main
text. In these cases only three values are used &-- and the third is in fact
ignored for the monospaced fonts. For example:
.code
<?sdop font_main="12,1,sanserif"?>
.endd
This specifies that the main text is to use 12-point, sanserif fonts, with 1
point of leading. There are also some parameters that affect only the
monospaced set of fonts, thus allowing them to be a different size (for
example). In these settings, the style should not be used, as it could lead to
weird effects.


.section "Overall scaling"
.index "fonts" "overall scaling"
A parameter called &*scale_typesize_base*& can be used to change all the font
sizes and leading by the same factor. The value is the font size for normal
text. For example:
.code
<?sdop scale_typesize_base="12"?>
.endd
The default size is 11 points, so the above example would multiple all fonts
sizes and leadings by 12/11. The scaling is applied after any individual size
changes specified by &*font_*& parameters. If you change the overall type
sizes, you might also need to change some of the indentation parameters.



.section "Dimensions"
.index "dimensions, format of"
Whenever a processing instruction sets a dimension (for example, the vertical
space for a page footer), the value must be given as a fixed-point number,
optionally followed by one of the abbreviations &`pt`& (points),
&`pc`& (picas), &`in`& (inches), &`mm`& (millimetres), or &`cm`& (centimetres).
If no units are given, points are assumed. For example:
.code
<?sdop foot_length="0.9in"?>
.endd


.section "Changing indentation" "SECTchindent"
.index "indent" "format for changing"
There are a number of processing parameters whose names end with &*_indent*&
that allow you to change the indentation for certain kinds of text. Up to three
dimensions can be given for most of them. For example:
.code
<?sdop blockquote_indent="1in,2cm,4pt"
.endd
The first dimension is the indent for the first lines of paragraphs; the second
applies to the remaining lines, and the third is an &'endent'&, that is, an
leftwards indent at the end of each line. The values may be negative, causing
text to stick out over the normal ends of lines. One parameter,
&*table_indent*&, has just a single dimension to set the indentation for
subsequent tables.


.section "Lists of parameters"
.index-from ID11 "processing instructions" "parameters, lists of"
The following sections list all the parameters that may be present in
processing instructions. Those that are marked as local can be used to apply
different values in different parts of the document, whereas the global
parameters set a single value for the whole document.


.subsection "Block quotations"
.vlist
.vitem "&*blockquote_indent*& (global)"
.index "block quotes" "changing parameters"
.index "indent" "block quotes"
This specifies the indentation parameters for block quotes (&R;
&<<SECTchindent>>&). The default value is &`"24,24,24"`&.

.vitem "&*blockquote_ruled*& (global)"
This specifies whether a block quote should be preceded and followed by
horizontal rules. The value must be &`yes`& or &`no`& (the default).

.vitem "&*blockquote_title_justify*& (global)"
This specifies the justification for block quote titles. The value must be
&`left`&, &`right`&, or &`centre`& (the default).
.endlist


.subsection "Chapters and sections"
.vlist
.vitem "&*chapter_skip_head*& (local)"
.index "chapter" "skipping page heading"
.index "page heading" "skipping at chapter start"
.index "heading, page" "skipping at chapter start"
The value of this parameter must be &`yes`& or &`no`& (default). When the value
is &`yes`&, page headings are omitted at the start of chapters. This parameter
must be set before the first chapter to which it applies. If this is in the
middle of the book, the best place is immediately before the relevant
&`<chapter>`& element.

.vitem "&*numbertitles*& (local)"
.index "title numbering, specifying"
The value of this parameter is split up into up to 10 comma-separated
substrings, each of which must be &`yes`& or &`no`&. If there are fewer than 10
substrings, the remainder are assumed to be &`no`&. The first substring
determines whether or not chapters are to be numbered. The remaining substrings
control sections, subsections, subsubsections, etc. By default, only chapters,
sections, and subsections are numbered in a book. In an article, there is no
numbering by default. You can change this by setting this parameter, and it
works even if the setting precedes the &`<article>`& element.
.endlist


.subsection "Cross-references"
.vlist
.vitem "&*xref_links*& (global)"
.index "cross-references" "clickable links"
The value of this parameter must be &`yes`& (default) or &`no`&. If it is set
to &`no`&, information for generating clickable links for cross-references and
index page numbers in a PDF is not included in the PostScript output. Note that
the use of the &%-p%& and &%-pf%& command line options also suppresses this
output.

.vitem "&*xref_rgb*& (global)"
.index "cross-references" "colour of links"
.index "colour" "cross-reference links"
This parameter specifies the colour of the text of cross-references and index
page numbers that are made into clickable links when the output is converted to
a PDF. For example:
.code
<?sdop xref_rgb="0,0,1"?>
.endd
The value of the parameter is a red-green-blue triple of values between 0 and
1; the above example sets the colour to blue. If this parameter is not set, the
text colour is determined in the same way as normal text (&R;
&<<SECTcolour>>&).
.endlist


.subsection "Examples in the text"
.vlist
.vitem "&*example_number_format*& (local)"
.index "example" "format of numeration"
This parameter controls the format of example numbers that are (optionally)
added to example titles, and can also be inserted as cross-references. The
value is a string that can contain up to two instances of &`%s`&. If there is
just one, the example number, counting from the start of the document, is
inserted. If there are two, the first is replaced by the chapter number, and
the second by the example number, counting from the start of the chapter. The
default setting is &`%s-%s`&, leading to example numbers of the form &`2-7`&.

.vitem "&*example_title_format*& (local)"
.index "example" "format of title"
This parameter controls the format of example titles. Its value is inserted
before the text given in the &`<title>`& elelment of a example. The string may
contain a single instance of &`%s`&, which is is replaced by the example number,
in the format defined by &*example_number_format*&. The default setting is the
string &`Example`& &`%s:`& followed by a terminating space.

.vitem "&*example_title_justify*& (local)"
The value of this parameter specifies how example titles are formatted. Its
value must be one of the words &`left`&, &`right`&, &`centre`& (or &`center`&),
or &`both`&, with the default being &`centre`&. If a example contains a
&`<mediaobject>`&, its alignment is taken as the example's alignment. Otherwise
the example is assumed to be left justified.

.vitem "&*example_title_width*& (local)"
This parameter controls the width of example titles. Text that is longer than
the width is split into multiple lines. The default is to take the width of a
&`<mediaobject>`& if available, otherwise the page width. The value may be an
absolute dimension, or the word &`object`&, signifying the default.
.endlist


.subsection "Figures in the text" "SECTfigure"
.vlist
.vitem "&*figure_number_format*& (local)"
.index "figures" "format of numeration"
This parameter controls the format of figure numbers that are (optionally)
added to figure titles, and can also be inserted as cross-references. The value
is a string that can contain up to two instances of &`%s`&. If there is just
one, the figure number, counting from the start of the document, is inserted.
If there are two, the first is replaced by the chapter number, and the second
by the figure number, counting from the start of the chapter. The default
setting is &`%s-%s`&, leading to figure numbers of the form &`4-5`&.

.vitem "&*figure_title_format*& (local)"
.index "figures" "format of titles"
This parameter controls the format of figure titles. Its value is inserted
before the text given in the &`<title>`& element of a figure. The string may
contain a single instance of &`%s`&, which is is replaced by the figure number,
in the format defined by &*figure_number_format*&. The default setting is the
string &`Figure`& &`%s:`& followed by a terminating space.

.vitem "&*figure_title_justify*& (local)"
The value of this parameter specifies how figure titles are formatted. Its
value must be one of the words &`left`&, &`right`&, &`centre`& (or &`center`&),
or &`both`&, with the default being &`centre`&. If a figure contains a
&`<mediaobject>`&, its alignment is taken as the figure's alignment. Otherwise
the figure is assumed to be left justified. The title is formatted and
positioned in relation to the figure, according to the value of
&*figure_title_justify*&. For example, if the figure is left aligned and the
title is centred, it is centred with the figure if possible (it may not be
possible for an overlong title), not with the page.

.vitem "&*figure_title_width*& (local)"
This parameter controls the width of figure titles. Text that is longer than
the width is split into multiple lines. The default is to take the width of a
&`<mediaobject>`& if available, otherwise the page width. The value may be an
absolute dimension, or the word &`object`&, signifying the default. For many
figures the default works well. However, for small figures it may be necessary
to specify a width that is greater than the width of the figure.
.endlist


.subsection "Font specification" "SECTfontspec"
.index-from "ID2" "font-specifying parameters" "list of"
The local parameters in this section should not be changed within a footnote.
.vlist
.vitem "&*command_style*& (global)"
This sets the style of font to be used for &`<command>`& elements (&R;
&<<SECTchfontstyle>>&). The default is italic.

.vitem "&*font_blockquote_title*& (global)"
This specifies the font for blockquote titles. The default value is
&`"11,1,serif,bold"`&.

.vitem "&*font_booktitle1*& (global)" "&*font_booktitle2*& (global)" &&&
       "&*font_booktitle3*& (global)" "&*font_booktitle4*& (global)"
.index "book" "title pages, fonts for"
These four parameters specify the fonts that can be used for different levels
of title on book title pages (&R; &<<SECTchindfont>>&). The defaults are all
sanserif bold, with respective sizes and leading &`"24,2"`&, &`"18,1.5"`&,
&`"15,1.25"`&, and &`"13,1"`&.

.vitem "&*font_chapter*& (global)"
.index "chapter" "font for title"
This specifies the font for chapter titles, which is also used for article
titles. The default value is &`"16,0,sanserif,bold"`&.

.vitem "&*font_chapter_subtitle*& (global)"
This specifies the font for chapter subtitles, which is also used for article
subtitles. The default value is &`"12,0,sanserif,bold"`&.

.vitem "&*font_figure_title*& (global)"
.index "figures" "font for titles"
This specifies the font for figure titles. The default value is
&`"11,1,serif,italic"`&.

.vitem "&*font_footnote*& (global)"
.index "footnotes" "fonts for"
This specifies the set of eight fonts that are used for footnotes (&R;
&<<SECTchfontset>>&). The default value is &`"9,1,serif"`&.

.vitem "&*font_footnotemono*& (global)"
This specifies just the set of four monospaced fonts that are used for
footnotes. The default value is &`"9,1"`&.

.vitem "&*font_formalpara_title*& (global)"
.index "formal paragraphs" "font for titles"
This specifies the font for formal paragraph titles. The default value is
&`"11,1,serif,bold"`&.

.vitem "&*font_headfoot*& (global)"
.index "heads and feet" "fonts, specifying"
This specifies the set of eight fonts that are used in heads and feet. The
default value is &`"11,1,serif"`&.

.vitem "&*font_headfootmono*& (global)"
This specifies just the set of four monospaced fonts that are used for
heads and feet. The default value is &`"11,1"`&.

.vitem "&*font_ilist_tag*& (local)"
This specifies the font that is used for the `tags' in subsequent idenfified
lists. The default value is whatever is set for &*font_main*&; the style can
also be changed by &*ilist_tag_style*&.

.vitem "&*font_index*& (global)"
.index "index" "fonts"
This specifies the set of eight fonts that are used for the text in indexes.
The default is &`"9.6,1,serif"`&.

.vitem "&*font_index_section*& (global)"
This specifies the font that is used for `section titles' in indexes. The
default is &`"11.5,0,sanserif,bold"`&.

.vitem "&*font_indexmono*& (global)"
This specifies just the set of four monospaced fonts that are used for the text
in indexes. The default is &`"9.6,1"`&.

.vitem "&*font_main*& (global)"
.index "fonts" "main text"
This specifies the set of eight fonts that are used for the main body text. The
default is &`"11,1,serif"`&.

.vitem "&*font_mainmono*& (global)"
This specifies just the set of four monospaced fonts that are used for the main
body text. The default is &`"11,1"`&.

.vitem "&*font_note_title*& (global)"
.index "note" "title, fonts for"
This specifies the font for note titles. The default value is
&`"11,1,serif,italic"`&.

.vitem "&*font_olist_tag*& (local)"
This specifies the font that is used for the `tags' in subsequent ordered
lists. The default value is whatever is set for &*font_main*&; the style can
also be changed by &*olist_tag_style*&.

.vitem "&*font_section*& (global)"
.index "section titles, fonts for"
This specifies the font that is used for top-level section titles. The default
is &`"13,0,sanserif,bold"`&.

.vitem "&*font_subsection*& (global)"
.index "subsection titles, fonts for"
This specifies the font that is used for section titles other than those at the
top level. The default is &`"11,0,sanserif,bold"`&.

.vitem "&*font_sidebar_title*& (global)"
.index "sidebar" "title, fonts for"
This specifies the font for sidebar titles. The default value is
&`"11,1,serif,bold"`&.

.vitem "&*font_small_main*& (global)"
.index "fonts" "small main text"
This specifies the set of eight fonts that are used for `small' main body
text (&R; &<<SECTsmallfont>>&). The default is &`"9,1,serif"`&.

.vitem "&*font_small_mainmono*& (global)"
This specifies just the set of four monospaced fonts that are used for
`small' main body text (&R; &<<SECTsmallfont>>&). The default is &`"9,1"`&.

.vitem "&*font_table_title*& (global)"
.index "tables" "titles, fonts for"
This specifies the font for table titles. The default value is
&`"11,1,serif,italic"`&.

.vitem "&*font_title*& (global)"
.index "book" "title pages, fonts for"
This specifies the set of eight fonts that are used for any text that appears
on title pages, except where such text is explicitly marked as being in a title
font by the use of &`<emphasis>`& (&R; &<<SECTtitlepages>>&). Normally the
fonts set by &*font_title*& are used for general information on the reverse of
a title page. The default value is &`"11,1,serif"`&.

.vitem "&*font_title_section*& (global)"
This specifies the font that is used for any section headings on title pages.
These might be used to separate information on the reverse of a title page.
The default value is &`"11.5,0,sanserif,bold"`&.

.vitem "&*font_titlemono*& (global)"
This specifies just the set of four monospaced fonts that are used for text on
title pages. The default value is &`"11,1"`&.

.vitem "&*font_toc*& (global)"
.index "table of contents" "fonts for"
This specifies the set of eight fonts that are used for the text of the table
of contents. The default value is &`"11,1,sanserif"`&.

.vitem "&*font_toc_fill*& (global)"
This specifies the font that is used for the `filler' in table of contents
lines. The default value is &`"11,0,serif,roman"`&.

.vitem "&*font_tocmono*& (global)"
This specifies just the set of four monospaced fonts that are used for text in
tables of contents. The default value is &`"11,0"`&.

.vitem "&*function_style*& (global)"
This sets the style of font to be used for &`<function>`& elements (&R;
&<<SECTchfontstyle>>&). The default is italic.

.vitem "&*ilist_tag_rgb*& (local)"
.index "itemized list" "tag colour"
.index "colour" "itemized list tag"
This specifies the colour of the tags for itemized lists (default black). The
value is a comma-separated triple of red-green-blue values in the range 0 to 1.

.vitem "&*ilist_tag_style*& (local)"
.index "itemized list" "tag font style"
This parameter sets the font style (&R; &<<SECTchfontstyle>>&) for the
identification `tags' on each item of an itemized list. The default is
taken from &*font_main*&, and can also be changed by &*font_ilist_tag*&.

.vitem "&*monospace_family*& (global)"
The value of this parameter must be the name of one of the known font families
(&R; &<<SECTchfontfam>>&). The default is Courier. It is used for monospaced
text. The results are unpredictable if the fonts are not in fact monospaced.

.vitem "&*olist_tag_rgb*& (local)"
.index "ordered list" "tag colour"
.index "colour" "ordered list tag"
This specifies the colour of the tags for ordered lists (default black). The
value is a comma-separated triple of red-green-blue values in the range 0 to 1.

.vitem "&*olist_tag_style*& (local)"
.index "ordered list" "tag font style"
This parameter sets the font style (&R; &<<SECTchfontstyle>>&) for the
numeration on each item of an ordered list. The default is taken from
&*font_main*&, and can also be changed by &*font_olist_tag*&.

.vitem "&*option_style*& (global)"
This sets the style of font to be used for &`<option>`& elements (&R;
&<<SECTchfontstyle>>&). The default is bold.

.vitem "&*replaceable_style*& (global)"
This sets the style of font to be used for &`<replaceable>`& elements (&R;
&<<SECTchfontstyle>>&). The default is italic.

.vitem "&*sanserif_family*& (global)"
.index "fonts" "sanserif family"
The value of this parameter must be the name of one of the known font families
(&R; &<<SECTchfontfam>>&). The default is Helvetica.

.vitem "&*scale_typesize_base*& (global)"
.index "fonts" "scaling"
This parameter can be used to scale all the font sizes at once. The value is a
point size for `normal' text. For example:
.code
<?sdop scale_typesize_base="13"?>
.endd
This changes the normal font size from 11 to 13 points, and scales other fonts
(for chapter titles, etc.) in proportion. This scaling is applied after
specific font sizes have been set up by the &*font_*&&'xxx'& parameters. It is
useful for making small adjustments to the default font sizes; if the change is
large, you may have to adjust other spacing such as the indents.

.vitem "&*serif_family*& (global)"
.index "fonts" "serif family"
The value of this parameter must be the name of one of the known font families
(&R; &<<SECTchfontfam>>&). The default is Times.

.vitem "&*userinput_style*& (global)"
This sets the style of font to be used for &`<userinput>`& elements (&R;
&<<SECTchfontstyle>>&). The default is monospaced.

.vitem "&*varname_style*& (global)"
This sets the style of font to be used for &`<varname>`& elements (&R;
&<<SECTchfontstyle>>&). The default is italic.
.endlist
.index-to "ID2"


.subsection "Heads and feet" "SECTheadfoot"
.vlist
.vitem "&*foot_centre_recto*& (local)" "&*foot_centre_verso*& (local)"   &&&
       "&*foot_left_recto*& (local)"   "&*foot_left_verso*& (local)"     &&&
       "&*foot_right_recto*& (local)"  "&*foot_right_verso*& (local)"
.index "heads and feet" "text for, main pages"
These parameters set texts for use in page footers on righthand (recto) and
lefthand (verso) pages (&R; &<<SECThandf>>&). The default value for the two
centre parameters is &`"&&arabicpage;"`&, which inserts an arabic page number.
The others default to empty strings. You normally need to force a new page
before changing footer contents in the middle of a document.

.vitem "&*foot_length*& (global)"
.index "heads and feet" "vertical space"
This sets the amount of vertical space that is reserved for the footer at the
bottom of each page. The default is 24 points.

.vitem "&*head_centre_recto*& (local)" "&*head_centre_verso*& (local)"  &&&
       "&*head_left_recto*& (local)"   "&*head_left_verso*& (local)"    &&&
       "&*head_right_recto*& (local)"  "&*head_right_verso*& (local)"
These parameters set texts for use in page headers on righthand (recto) and
lefthand (verso) pages (&R; &<<SECThandf>>&). They all default to empty
strings.

.vitem "&*head_length*& (global)"
This sets the amount of vertical space that is reserved for the header at the
top of each page. The default is zero, which causes no header to be output.

.vitem "&*preface_foot_centre_recto*& (local)" &&&
       "&*preface_foot_centre_verso*& (local)" &&&
       "&*preface_foot_left_recto*& (local)"   &&&
       "&*preface_foot_left_verso*& (local)"   &&&
       "&*preface_foot_right_recto*& (local)"  &&&
       "&*preface_foot_right_verso*& (local)"
.index "heads and feet" "text for, preface pages"
These parameters set texts for use in preface page footers on righthand (recto)
and lefthand (verso) pages (&R; &<<SECThandf>>&). The default value for the two
centre parameters is &`"&&romanpage;"`&, which inserts an roman page number.
The others default to empty strings. You normally need to force a new page
before changing footer contents in the middle of a document.

.vitem "&*preface_head_centre_recto*& (local)" &&&
       "&*preface_head_centre_verso*& (local)" &&&
       "&*preface_head_left_recto*& (local)"   &&&
       "&*preface_head_left_verso*& (local)"   &&&
       "&*preface_head_right_recto*& (local)"  &&&
       "&*preface_head_right_verso*& (local)"
These parameters set texts for use in preface page headers on righthand (recto)
and lefthand (verso) pages (&R; &<<SECThandf>>&). They all default to empty
strings.
.endlist


.subsection "Indexes" "SECTindex"
.vlist
.vitem "&*index_headings*& (local)"
.index "index" "disabling headings"
The value of this parameter must be &`yes`& (default) or &`no`&. The default is
to insert headings into indexes when the leading letter of the entries changes,
unless every entry starts with the same character. No headings are inserted if
the value is &`no`&. These headings never appear in a printed table of
contents, but they may be present in PDF tables of contents (see next
parameter).

.vitem "&*index_headings_pdf_toc*& (local)"
.index "index" "headings in PDF table of contents"
The value of this parameter must be &`yes`& or &`no`& (default). It is
inspected only if &*index_headings*& is is set and a table of contents is being
created. If it is &`yes`&, entries for each index heading (change of letter)
are created for a PDF table of contents.

.vitem "&*index_sort_omit*& (global)"
.index "index" "sort, omitting characters"
This specifies a list of characters that are to be ignored when sorting index
entries. The default is to ignore the `break permitted here' (U+0082), `no
break here' (U+0083), zero-width space (U+200B) and opening and
closing double quote (U+201C and U+201D) characters. Setting this parameter
completely replaces the list of characters.
.code
<?sdop index_sort_omit="[]*&lsquo;"?>
.endd
This example ignores only square brackets, asterisk, and opening single quote.
As the example shows, you can use entity names in the list. However, only those
entities that represent a single character are permitted.
.endlist


.subsection "Lists: itemized, ordered and variable"
Parameters for specifying the colour and font style for itemized and ordered
list `tags' are described in the section on fonts (&R; &<<SECTfontspec>>&).
The parameters in this section should not be changed within a footnote.

.vlist
.vitem "&*ilist_indent*& (global)"
.index "itemized list" "indent"
.index "indent" "itemized lists"
This specifies the indent parameters for itemized lists (&R;
&<<SECTchindent>>&). The default value is &`"12,12,0"`&.

.vitem "&*olist_format*& (local)"
.index "ordered list" "format of numeration"
The value of this parameter controls what is printed when numbering an ordered
list. The format of item numbers is controlled by the &%numeration%& attribute
of the &`<orderedlist>`& element &-- this parameter controls the additional
characters (for example, punctuation) that are added. It may contain entity
names, and must contain &`%s`& at the point where the item number is to be
inserted. The default value is &`(%s)`&, which outputs the number in
parentheses. The font style for the whole string can be specified by the
&*olist_style*& parameter.

.vitem "&*olist_indent*& (global)"
.index "ordered list" "indent"
.index "indent" "ordered lists"
This specifies the indent parameters for ordered lists (&R;
&<<SECTchindent>>&). The default value is &`"24,24,0"`&.

.vitem "&*vlist_indent*& (global)"
.index "variable list" "indent"
.index "indent" "variable lists"
This sets the indent parameters for the paragraphs in a variable list (&R;
&<<SECTchindent>>&). The default is &`"14,14,0"`&.

.vitem "&*vlist_term_indent*& (global)"
.index "variable list" "term indent"
.index "indent" "variable list terms"
This sets the indent parameters for &`<term>`& items within a variable list
(&R; &<<SECTchindent>>&). The default is &`"0,0,0"`&.

.vitem "&*vlist_title_indent*& (global)"
.index "variable list" "title indent"
.index "indent" "variable list titles"
This sets the indent parameters for the title of a variable list (&R;
&<<SECTchindent>>&). The default is &`"0,0,0"`&.
.endlist


.subsection "Literal blocks" "SECTliteral"
.vlist
.vitem "&*literal_indent*& (global)"
.index "literal layout indent"
.index "indent" "literal blocks"
This specifies the indent parameters for blocks of literal text (&R;
&<<SECTchindent>>&). The default value is &`"12,12,0"`&.

.vitem "&*literal_indent_fudge*& (global)"
The value of this parameter must be &`yes`& (default) or &`no`&. It controls
the handling of lines within &`<literallayout>`& elements. If this facility is
turned on, and there is a common indent for every line, it is removed. For
example:
.code
<literallayout>
  abcd efgh
       ijkl
</literallayout>
.endd
is treated as if it were:
.code
<literallayout>
abcd efgh
     ijkl
</literallayout>
.endd
This feature exists because SDoP automatically indents literal blocks within
other indented items such as lists, whereas some other DocBook processors do
not. Input that was created for other processors may therefore contain explicit
indents that are not needed for SDoP and which, if heeded, lead to excessive
indentation.
.endlist


.subsection "Notes"
.vlist
.vitem "&*note_indent*& (global)"
.index "note" "indent"
.index "indent" "notes"
.index "note" "parameters"
This specifies the indentation parameters for notes (&R;
&<<SECTchindent>>&). The default value is &`"24,24,24"`&.

.vitem "&*note_ruled*& (global)"
This specifies whether a note should be preceded and followed by
horizontal rules. The value must be &`yes`& or &`no`& (the default).

.vitem "&*note_title_justify*& (global)"
This specifies the justification for note titles. The value must be
&`left`&, &`right`&, or &`centre`& (the default).
.endlist


.subsection "Page layout"
.index-from "ID12" "page" "layout parameters"
.vlist
.vitem "&*format*& (local)"
.index "new page, forcing"
.index "page" "forcing new"
The only recognized value for this parameter at present is &`newpage`&. It
forces a new page in the output.

.vitem "&*main_even_pages*& (global)"
.index "page" "padding"
The value of this parameter must be &`yes`& or &`no`& (default). If it is set
to &`yes`&, SDoP ensures that the main body of the output fills an even number
of pages, adding a blank page at the end if necessary.

.vitem "&*margin_bottom*& (global)"
.index "margin" "bottom of page"
This specifies the amount of space at the bottom of each page. The default is
60 points (a bit less than an inch).

.vitem "&*margin_left_recto*& (global)"
.index "margin" "left of page"
This specifies the amount of space at the lefthand side of righthand pages. The
default is 72 points (one inch).

.vitem "&*margin_left_verso*& (global)"
This specifies the amount of space at the lefthand side of lefthand pages. The
default is 72 points (one inch).

.vitem "&*page_columns*& (local)"
.index "columns, specifying"
This parameter sets the number of columns on the page (default 1). It is used
automatically to print indexes in two columns, and that is the main use for
which it was implemented. It is not a very sophisticated implementation. A page
break is forced if the number of columns is changed when text is currently
being formatted into a column other than the first.

.vitem "&*page_column_separation*& (local)"
This parameter specifies the separation between multiple columns on the page.
The default value is 16 points.

.vitem "&*page_foot_line_width*& (global)"
.index "heads and feet" "line width"
This specifies the width of lines in footers at the bottom of each page. The
default is the value of &*page_line_width*&.

.vitem "&*page_full_length*& (global)"
.index "page" "length"
This specifies the full length of the page that is used for printing, including
any heads and feet. The default is 720 points (10 inches).

.vitem "&*page_head_line_width*& (global)"
This specifies the width of lines in headers at the top of each page. The
default is the value of &*page_line_width*&.

.vitem "&*page_line_width*& (global)"
.index "page" "width"
This specifies the width of lines on the page. The default is 450 points (6.25
inches).

.vitem "&*paper_size*& (global)"
.index "paper size"
.index "PostScript" "/PageSize setting"
If this parameter is set, it causes a &`/PageSize`& setting to be included in
the PostScript. It is not necessary for normal output, but can be useful if
SDoP is used to make a PDF for a slideshow (see chapter &<<CHAPslides>>&). The
value must be two numbers &'in points'&, separated by the letter &`x`&. For
example:
.code
<?sdop paper_size="900x660"?>
.endd
The first number specifies the width and the second the depth.
.endlist

.index-to "ID12"


.subsection "Paragraphs"
.vlist
.vitem "&*formalpara_indent*& (global)"
.index "formal paragraphs" "indent"
.index "indent" "formal paragraphs"
This specifies the indent parameters for formal paragraphs (&R;
&<<SECTchindent>>&). The default value is &`"0,0,0"`&.

.vitem "&*para_indent*& (global)"
.index "paragraph indent"
.index "indent" "paragraphs"
This specifies the indent parameters for normal paragraphs (&R;
&<<SECTchindent>>&). The default value is &`"0,0,0"`&.
.endlist


.subsection "Side bars"
.vlist
.vitem "&*sidebar_indent*& (global)"
.index "sidebar" "indent"
.index "indent" "sidebars"
.index "sidebar" "parameters"
This specifies the indentation parameters for sidebars (&R;
&<<SECTchindent>>&). The default value is &`"24,24,24"`&.

.vitem "&*sidebar_ruled*& (global)"
This specifies whether a sidebar should be preceded and followed by
horizontal rules. The value must be &`yes`& or &`no`& (the default).

.vitem "&*sidebar_title_justify*& (global)"
This specifies the justification for sidebar titles. The value must be
&`left`&, &`right`&, or &`centre`& (the default).
.endlist


.subsection "Subscripts and superscripts" "SECTsubsuper"
.vlist
.vitem "&*subscript_small*& (local)"
.index "subscripts" "font size"
If the value of this parameter is &`yes`& (the default), subscripts are printed
in a small font. At present, the footnote font is used for this. If the value
is &`no`&, subscripts are printed at normal size. This parameter is ignored
when printing titles; the title font is always used.

.vitem "&*subscript_down*& (local)"
.index "subscripts" "position of"
The value of this parameter must be a number in the range 1&--127. It specifies
the percentage of the line depth by which subscripts are lowered. The default
value is 33.

.vitem "&*superscript_small*& (local)"
.index "superscripts" "font size"
If the value of this parameter is &`yes`& (the default), superscripts are
printed in a small font. At present, the footnote font is used for this. If the
value is &`no`&, superscripts are printed at normal size. This parameter is
ignored when printing titles; the title font is always used.

.vitem "&*superscript_up*& (local)"
.index "superscripts" "position of"
The value of this parameter must be a number in the range 1&--127. It specifies
the percentage of the line depth by which superscripts are raised. The default
value is 33.
.endlist


.subsection "Tables in the text" "SECTintexttables"
.vlist
.vitem "&*table_indent*& (local)"
.index "tables" "indentation"
.index "indent" "tables"
This parameter's data is a single dimension that specifies an indent for all
subsequent tables in the document.

.vitem "&*table_number_format*& (local)"
.index "tables" "numeration"
This parameter controls the format of table numbers that are (optionally) added
to table titles, and can also be inserted as cross-references. The value is a
string that can contain up to two instances of &`%s`&. If there is just one,
the table number, counting from the start of the document, is inserted. If
there are two, the first is replaced by the chapter number, and the second by
the table number, counting from the start of the chapter. The default setting
is &`%s-%s`&, leading to table numbers of the form &`2-7`&.

.vitem "&*table_title_format*& (local)"
.index "tables" "title format"
This parameter controls the format of table titles. Its value is inserted
before the text given in the &`<title>`& elelment of a table. The string may
contain a single instance of &`%s`&, which is is replaced by the table number,
in the format defined by &*table_number_format*&. The default setting is the
string &`Table`& &`%s:`& followed by a terminating space.

.vitem "&*table_title_justify*& (local)"
The value of this parameter specifies how table titles are formatted. Its value
must be one of the words &`left`&, &`right`&, &`centre`& (or &`center`&), or
&`both`&, with the default being &`left`&. The title is formatted and
positioned in relation to the table. For example, if the title is centred, it
is centred with the table if possible (it may not be possible for an overlong
title), not with the page.

.vitem "&*table_title_width*& (local)"
This parameter controls the width of table titles. Text that is longer than the
width is split into multiple lines. The default is the width of the table. The
value may be an absolute dimension, or the word &`object`&, signifying the
default.

.vitem "&*table_warn_overflow*& (local)"
.index "tables" "cell overflow warnings"
This parameter controls what happens when a cell in a table overflows (&R;
&<<SECTtables>>&). Text in table cells can be split into multiple lines if it
contains any splitting points; the overflow case occurs when the text cannot be
split. The value of this parameter must be &`always`& (default), &`never`&, or
&`overprint`&. In the default case, a cell overflow is a hard error, and a
warning message is always output. Conversely, if &`never`& is specified, the
overflow is ignored.

If the value is &`overprint`&, a warning is generated only when the overflow
actually causes overprinting of the contents of an adjacent cell, or of a
separator (vertical line) between the two cells. In other words, when there is
no cell separator, one cell may overflow into the next, provided that its text
does not actually overprint the adjacent cell's text.
.endlist


.subsection "Table of contents" "SECTtoc"
.index-from "ID3" "table of contents" "parameters"
.vlist
.vitem "&*toc_chapter_blanks*& (global)"
The value of this parameter controls the spacing around chapter entries in the
table of contents. It consists of two &`yes`&/&`no`& substrings, separated by a
comma. The default value is:
.code
<?sdop toc_chapter_blanks="yes,yes"?>
.endd
If the first substring is &`yes`&, a blank line is inserted before each chapter
line in the table of contents, except for the first chapter. If the second
substring is &`yes`& a blank line is inserted before the first section line
that follows a chapter line. Missing substrings are interpreted as &`no`&.

.vitem "&*toc_even_pages*& (global)"
The value of this parameter must be &`yes`& (default) or &`no`&. If it is set
to &`yes`&, SDoP ensures that the table of contents fills an even number of
pages, adding a blank page at the end if necessary.

.vitem "&*toc_fill_leftspace*& (global)"
The value of this parameter is a dimension (default 2 points). It specifies the
amount of space to leave after an entry in the table of contents before
starting the `filler' sequence (typically a row of dots).

.vitem "&*toc_fill_rightspace*& (global)"
The value of this parameter is a dimension (default 4 points). It specifies the
amount of space to leave after the `filler' sequence in an entry in the table
of contents, immediately before the page number.

.vitem "&*toc_fill_string*& (global)"
The value of this parameter is a literal string (default &`"."`&). It specifies
the string that is replicated to create the `filler' in table of contents
lines.

.vitem "&*toc_foot_centre_recto*& (global)" &&&
       "&*toc_foot_centre_verso*& (global)" &&&
       "&*toc_foot_left_recto*& (global)"   &&&
       "&*toc_foot_left_verso*& (global)"   &&&
       "&*toc_foot_right_recto*& (global)"  &&&
       "&*toc_foot_right_verso*& (global)"
.index "heads and feet" "text for, contents pages"
These parameters set texts for use in table of contents page footers on
righthand (recto) and lefthand (verso) pages (&R; &<<SECThandf>>&). The default
value for the two centre parameters is &`"&&romanpage;"`&, which inserts an
roman page number. The others default to empty strings. These are global
processing parameters because there is no way of changing them in the middle
of a table of contents.

.vitem "&*toc_head_centre_recto*& (global)" &&&
       "&*toc_head_centre_verso*& (global)" &&&
       "&*toc_head_left_recto*& (global)"   &&&
       "&*toc_head_left_verso*& (global)"   &&&
       "&*toc_head_right_recto*& (global)"  &&&
       "&*toc_head_right_verso*& (global)"
These parameters set texts for use in table of contents page headers on
righthand (recto) and lefthand (verso) pages (&R; &<<SECThandf>>&). They all
default to empty strings. These are global processing parameters because
there is no way of changing them in the middle of a table of contents.

.vitem "&*toc_line_chapter_strings*& (global)"
The value of this parameter is split into six, comma-separated substrings. They
control the format of lines in the table of contents that refer to chapters. If
a literal comma is required in one of the substrings, it must be preceded by an
ampersand. Here is a totally unrealistic example (a realistic one would be too
wide for the page):
.code
<?sdop toc_line_chapter_strings="A&,A,BB,CC,DD,EE,FF"?>
.endd
The six strings are used to construct the table of contents line as follows:
.ilist
The first string is always used at the start of the line;
.next
If chapter numbers are being included in the table of contents, the second
string is inserted, followed by the chapter number and the third string. If
chapter numbers are not being included, the second and third strings are
ignored.
.next
Then come the chapter title and the fourth string.
.next
At this point, a suitable number of copies of the filler string, as defined by
&*toc_fill_string*&, are inserted.
.next
The line ends with the fifth string, the page number, and finally the sixth
string.
.endlist
The default values for the strings are:

.itable none 0 0 3 10pt left 196pt left 244pt left
.row "" "&`<emphasis role='bold'>`&"  "Start of line"
.row "" "(&'empty'&)"                 "Before chapter number"
.row "" "&`.&&nbsp;&&nbsp;`&"         "After chapter number"
.row "" "&`</emphasis>`&"             "After title"
.row "" "&`<emphasis role='bold'>`&"  "Before page number"
.row "" "&`</emphasis>`&"             "After page number"
.endtable
The entity &`&&nbsp;`& is a `non-breaking space', that is, it is a space that
is treated as if it were a printing character.

.vitem "&*toc_line_sect1_strings*& (global)"
The value of this parameter is treated in the same way as
&*toc_line_chapter_strings*&, except that it applies to first-level section
lines in the table of contents. The default values for the strings are:

.itable none 0 0 3 10pt left 196pt left 244pt left
.row "" "&`&&nbsp;&&nbsp;&&nbsp;&&nbsp;`&"  "Start of line"
.row "" "(&'empty'&)"                   "Before section number"
.row "" "&`&&nbsp;&&nbsp;`&"            "After section number"
.row "" "(&'empty'&)"                   "After title"
.row "" "(&'empty'&)"                   "Before page number"
.row "" "(&'empty'&)"                   "After page number"
.endtable

.vitem "&*toc_line_sect2_strings*& (global)"
The value of this parameter is treated in the same way as
&*toc_line_chapter_strings*&, except that it applies to second-level
(subsection) and any lower level section lines in the table of contents. The
default values for the strings are the same as for first-level sections, except
that the initial indent is eight spaces rather than four.

.vitem "&*toc_printed_sections*& (local)"
.index "table of contents" "specifying what is printed"
.index "PDF bookmarks"
This parameter works in conjunction with &*toc_sections*&. Its default value is
the same as for &*toc_sections*&, and it is altered whenever &*toc_sections*&
is changed. If you want &*toc_&B;printed_&B;sections*& to be different, you
must set it after setting &*toc_sections*& (each time, if there is more than
one setting). The value of &*toc_printed_sections*& is in the same format as
&*toc_sections*&, but it can only specify fewer items. This makes it possible
to limit the table of contents that is printed (that is, forms part of the
document's text), while at the same time retaining a more comprehensive version
in the output file for conversion to a PDF table of bookmarks. For example:
.code
<?sdop toc_sections="yes,yes,yes,no"
  toc_printed_sections="yes,yes,no"?>
.endd
This example restricts the printed table of contents to chapters and sections,
but includes subsections as well in a PDF version.

.vitem "&*toc_sections*& (local)"
.index "table of contents" "specifying what is included"
The value of this parameter must be a sequence of up to 10 comma-separated
substrings. It controls which parts of the document are to be listed in the
table of contents. As it is a local processing parameter, the choice can be
different in different parts of the document. For example, you can include
section titles in the table of contents in the body of the book, but not for
the preface. If you set &*toc_sections*& without setting
&*toc_printed_sections*&, the selection applies both to what is printed, and to
what is included in the online bookmarks if the output is converted to PDF.

The first substring applies to chapters and chapter-like parts such as
appendices. Subsequent substrings apply to successive levels of nested
sections, until one of them is &`no`&. If the first value is &`no`&, no table
of contents is output. In this case, no bookmark information is available in
the PostScript, so if it is converted to PDF, there is no PDF table of
bookmarks either.

There are two default values, one for prefaces, and one for the body of the
document. For prefaces, the default is:
.code
<?sdop toc_sections="yes,no"?>
.endd
That is, only the preface title is included by default in the table of
contents. Any sections within the preface are omitted. For the rest of the
document, the default value is:
.code
<?sdop toc_sections="yes,yes,yes,no"?>
.endd
This includes chapters, sections, and subsections, but nothing deeper.
The way settings of this parameter are processed is as follows:
.ilist
Before processing the prefaces, the preface default is set. A setting
that precedes the first preface can be used to override the default. Thus,
for example, if you have &`<?sdop toc_sections="no"?>`& before the first
preface, it will not be included in the table of contents. Subsequent settings
that are within the prefaces apply to the following preface material.
.next
After the prefaces have been processed, the body default is set. A setting that
precedes the first preface again overrides this, but settings that are within
the prefaces are now ignored. The preface material is skipped, and the rest of
the document is processed. Subsequent settings apply to the body material that
follows them.
.endlist

Note in particular that a setting preceding the first preface applies both to
the preface and to the main body of the document. If you want something
different for the body, you must include another setting after the prefaces.

.vitem "&*toc_title*& (global)"
The value of this parameter is used as the title for the table of contents. The
default is &`Contents`&.
.endlist
.index-to "ID3"


.subsection "Warnings" "SECTwarnings"
.vlist
.vitem "&*warn_unsupported*& (global)"
.index "warnings" "controlling"
The value of this parameter must be &`yes`& (default) or &`no`&. If it is set
to &`yes`&, SDoP outputs a list of unrecognized DocBook elements and parameters
to the standard error at the end of processing. This setting can be overridden
by the use of &%-q%& or &%-w%& on the command line.

.vitem "&*warn_unsupported_characters*& (global)"
The value of this parameter must be &`yes`& (default) or &`no`&. If it is set
to &`yes`&, SDoP outputs a warning message the first time it encounters a
character that is not supported. An unsupported character is one that is not
present in the current PostScript font. This setting can be overridden by the
use of &%-qc%& or &%-wc%& on the command line.
.endlist


.subsection "Other parameters" "SECTotherpin"
The remaining processing parameters are listed here in alphabetical order.

.vlist
.vitem "&*background_rgb*& (global)"
.index "background colour"
.index "colour" "background"
This sets a colour for the background of each page. Its intended use is for
when SDoP is being used to create slides rather than printed pages (see chapter
&<<CHAPslides>>&). It is necessary also to set &*paper_size*& so that SDoP
knows the area that is to be coloured. The value is a comma-separated triple of
red-green-blue values in the range 0 to 1.

.vitem "&*extra_leading*& (local)"
.index "space" "extra between lines"
.index "leading, extra"
This parameter's data must be a dimension. It specifies an extra amount of
vertical space that is to be inserted between the lines of the next and
subsequent paragraphs.

.vitem "&*hyphenate*& (local)"
.index "hyphenation" "disabling"
The value of this parameter must be &`yes`& (default) or &`no`&. When it
is set to &`yes`&, hyphenation is enabled (&R; &<<SECThyphenation>>&).

.vitem "&*kern*& (local)"
.index "kerning" "disabling"
The value of this parameter must be &`yes`& (default) or &`no`&. If it
is set to &`yes`&, kerning of adjacent letters in words is enabled. Kerning
adjusts the spacing between letters to make the result look nicer.
.endlist


.subsection "Obsolete synonyms"
.index "processing instructions" "parameters, obsolete synonyms"
As SDoP has developed, the names of some parameters have been changed to
be more appropriate to their function. The old names still work, but cause
warnings to be generated.

.literal xml
<?sdop table_indent="10pt"?>
.literal off

.itable all 1 1 2 100 left 100 left
.row "&'Old name'&"           "&'New name'&"
.row "&*ilist_font*&"         "&*ilist_tag_style*&"
.row "&*olist_font*&"         "&*olist_tag_style*&"
.row "&*olist_format*&"       "&*olist_tag_format*&"
.row "&*orderedlist_format*&" "&*olist_tag_format*&"
.row "&*term_indent*&"        "&*vlist_term_indent*&"
.row "&*command_font*&"       "&*command_style*&"
.row "&*function_font*&"      "&*function_style*&"
.row "&*option_font*&"        "&*option_style*&"
.row "&*replaceable_font*&"   "&*replaceable_style*&"
.row "&*userinput_font*&"     "&*userinput_style*&"
.row "&*varname_font*&"       "&*varname_style*&"
.endtable

.literal xml
<?sdop table_indent="0"?>
.literal off
.index-to "ID1"
.index-to "ID11"



. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Using information from &`<bookinfo>`& or &`<articleinfo>`&" &&&
  "CHAPusingbi" "Using &`<`&&'xxx'&&`info>`& information"
.index "&*bookinfo*& data"
.index "&*articleinfo*& data"
Information is extracted from the &`<bookinfo>`& or &`<articleinfo>`& elements
and made available for insertion at arbitrary places in the document in two
different ways:
.olist
Simple text strings are placed in special entities; for example, the data from
the &`<surname>`& element inside &`<author>`& is inserted anywhere that
&`&&author_surname;`& appears.
.next
.index "insertions from &*bookinfo*& and &*articleinfo*&"
Two more complicated items that contain further entities are inserted by one of
the following processing instructions:
.code
<?sdop insert="legalnotice"?>
<?sdop insert="revdescription"?>
.endd
If there are multiple occurrences of &`<legalnotice>`& or &`<revdescription>`&,
they are inserted in order of definition.
.endlist

Both kinds of insert can appear anywhere in the document, though they are most
commonly found in title pages. The special entities are shown in the table
below. If no title, subtitle, or title abbreviation is provided in the
&`<bookinfo>`& element, values from the &`<book>`& element are used if they
exist. In other words, &`<bookinfo>`& overrides &`<book>`&.

The names of the entities do not change for &`<article>`&s, even though the
information is taken from &`<articleinfo>`& rather than &`<bookinfo>`&. For
example, you must use &`&&book_title;`& to insert the article's title.
.index "entities" "set from &*bookinfo*& and &*articleinfo*&"

.itable none 0 0 3 10pt left 196pt left 244pt left
.row "" &`&&author_address;`&
.row "" &`&&author_corpauthor;`&
.row "" &`&&author_firstname;`&
.row "" &`&&author_honorific;`&
.row "" &`&&author_initials;`&
.row "" &`&&author_jobtitle;`&
.row "" &`&&author_lineage;`&
.row "" &`&&author_orgname;`&
.row "" &`&&author_othername;`&
.row "" &`&&author_surname;`&
.row "" &`&&book_cpyholder;`&
.row "" &`&&book_cpyyear;`&
.row "" &`&&book_date;`&
.row "" &`&&book_edition;`&
.row "" &`&&book_issuenum;`&
.row "" &`&&book_pubdate;`&
.row "" &`&&book_publishername;`&
.row "" &`&&book_releaseinfo;`&
.row "" &`&&book_revauthorinitials;`&
.row "" &`&&book_revdate;`&
.row "" &`&&book_revnumber;`&
.row "" &`&&book_subtitle;`&
.row "" &`&&book_title;`&
.row "" &`&&book_titleabbrev;`&
.row "" &`&&book_volumenum;`&
.row "" &`&&editor_firstname;`&
.row "" &`&&editor_honorific;`&
.row "" &`&&editor_initials;`&
.row "" &`&&editor_jobtitle;`&
.row "" &`&&editor_lineage;`&
.row "" &`&&editor_orgname;`&
.row "" &`&&editor_othername;`&
.row "" &`&&editor_surname;`&
.row "" &`&&othercredit_firstname;`&
.row "" &`&&othercredit_honorific;`&
.row "" &`&&othercredit_initials;`&
.row "" &`&&othercredit_jobtitle;`&
.row "" &`&&othercredit_lineage;`&
.row "" &`&&othercredit_orgname;`&
.row "" &`&&othercredit_othername;`&
.row "" &`&&othercredit_surname;`&
.endtable




. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "SDoP data files" "CHAPdatafiles"
.index "data files"
.index "files" "data for SDoP"
.index "&*-S*& option"
.index "&$SDOP_SHARE$&"
SDoP uses a number of auxiliary data files in its processing. The distributed
versions are normally installed in a public directory such as
&_/usr/local/share/sdop/_&. The &$SDOP_SHARE$& environment variable or the
&%-S%& command line option can be used to supply a list of directories to
search before the standard one, thereby providing a means for individual users
to override the default files. This chapter discusses the uses that are made of
the different files.


.section "PostScript header file"
.index "PostScript" "header file"
.index "files" "PostScript header"
At the start of SDoP's output, it writes a copy of the file &_PSheader_& (with
PostScript comments removed). This is a typical PostScript header file that
defines some PostScript functions for use by the following code. In particular,
it contains a function for loading fonts and adjusting their encodings.


.section "Font metrics" "SECTmetrics"
.index "font metric files"
.index "files" "font metrics"
Any typsetting program needs to know the metrics of the fonts it is using. SDoP
is distributed with AFM files for all the standard Adobe fonts in a
subdirectory called &_fontmetrics_&. For example, the file for the Times Roman
font is in &_fontmetrics/Times-Roman.afm_&. If you want to use other fonts, you
must either install their AFM files in this directory, or use the &%-S%&
command line option or &$SDOP_SHARE$& environment variable to specify where
they are (&R; &<<SECTexotic>>&).


.section "Hyphenation dictionary" "SECThydict"
.index "hyphenation" "dictionary file"
.index "files" "hyphenation dictionary"
SDoP does hyphenation by means of a dictionary. A dictionary for British
English is installed in the file &_HyphenData_&. The source of this file, and
the program that prepares it for use are also distributed (see chapter
&<<CHAPmainhydic>>&).


.section "Title pages for books" "SECTtitlepages"
.index "title page template"
.index "book" "title page template"
.index "files" "template for book title"
The file &_titletemplate_& is a template for the title pages of a book.
There are some special entities and an `insert' facility that can be used in
the title pages to insert data obtained from the &`<bookinfo>`& element (see
chapter &<<CHAPusingbi>>&).

The distibuted version of &_titletemplate_& is an input fragment that defines
two tables, one for each of two pages. The tables are defined in XML, but there
are also a number of SDoP conditional processing parameters that control what
is output on the title pages (&R; &<<SECTskippart>>&), depending on what data
has been supplied. If no book title is available, no title pages are output.

The &`<emphasis>`& element can be used in title pages with
&`role="booktitle`&&'n'&&`"`&, where &'n'& is a number between 1 and 4. This
selects one of four different sizes of title font: 24, 16, 18, or 13 points.

You can provide your own title page layout by copying &_titletemplate_& to
another file, editing it to your own requirements, and passing the name of the
directory where it resides to SDoP using the &%-S%& command line option.


.section "Article titles" "SECTarttitle"
.index "article" "title template"
.index "files" "template for article title"
The file &_arttemplate_& is a template for the title material of an article,
which appears at the top of the first page if an article title has been
defined. The distributed version is an input fragment that defines a single
table containing the heading material. It is similar to the first table used
for a book's title page, as described in the previous section, except that the
values of the special entities are obtained from the &`<articleinfo>`& element
rather than &`<bookinfo>`&. Nevertheless, the same entity names are used (for
example, &`&&book_date;`& rather than &`&&article_date;`&).


.section "Table of contents" "SECTtabofcont"
.index "table of contents" "template for"
The table of contents is mostly generated dynamically as a &`<table>`& that is
processed internally by SDoP. However, the start of the table of contents
`chapter' and the beginning of the &`<table>`& is obtained from a file called
&_toctemplate_&. You are unlikely to want to modify this, except perhaps to
change the format of the title. The special entity &`&&toc_title;`& contains
the string set by the &*toc_title*& global processing parameter (&R;
&<<SECTtoc>>&). The default is &`Contents`&. If you just want to
change this text, use the processing parameter.


.section "Headers and footers" "SECThandf"
.index-from "ID5" "heads and feet"
.index "heads and feet" "templates for"
.index "files" "templates for heads and feet"
A page header or footer is output only if space has been reserved for it. By
default, SDoP reserves 24 points of vertical space for a footer, but no header.
The &*head_length*& and &*foot_length*& processing parameters can be used to
ajust the allocations. When headers are in use, those on pages that start
chapters can be independently suppressed by setting the &*chapter_skip_head*&
processing parameter to &`yes`&.

.index "preface, heads and feet for"
.index "table of contents" "heads and feet for"
There are two files called &_headtable_& and &_foottable_& that define head and
foot lines for the body of the document and any appendixes, indexes, and
colophons. There are similar files called &_headtable-t_& and &_foottable-t_&
for the table of contents, and a third set called &_headtable-p_& and
&_foottable-p_& for the preface(s).

A two-level substitution process is used for head and foot lines. This makes it
possible to have different heads and feet on left-hand and right-hand pages,
while also making it easy to change their contents by means of local processing
parameter settings. However, if you want to change the overall layout of heads
of feet, you have to provide new template files.

.index "entities" "for heads and feet"
.index "heads and feet" "entities for use in"
In the supplied templates, an XML table is used, containing references to the
following special entities:

.itable none 0 0 3 10pt left 100pt left 244pt left
.row "" &`&footcentre;`&    "centre foot text"
.row "" &`&footleft;`&      "left foot text"
.row "" &`&footright;`&     "right foot text"
.row "" &`&headcentre;`&    "centre head text"
.row "" &`&headleft;`&      "left head text"
.row "" &`&headright;`&     "right head text"
.endtable

As their names suggest, these are placed in table cells that are respectively
left-, centre-, and right-justified. The values of these entities for the main
body of the book and the preface(s) can be set by local processing parameters
(&R; &<<SECTheadfoot>>&). This means they can be varied during the course of
the document; it is usually necessary to force a new page before changing the
contents of the footer.

For the table of contents, the values are set by global processing parameters
(&R; &<<SECTtoc>>&), because there is no way to change them in the
middle of the table of contents.

References to other entities are permitted in the values set for the above
special entities. The default for the main body pages is to print an arabic
page number in the centre of the footer, equivalent to:
.code
<?sdop foot_centre_recto="&arabicpage;"
       foot_centre_verso="&arabicpage;"?>
.endd
This setting means that, on both right-hand (recto) and left-hand (verso)
pages, the value of &`&footcentre;`& is &`&&arabicpage;`&. If you want to
have page numbers on the left and right instead, you could use:
.code
<?sdop foot_centre_recto=""
       foot_centre_verso=""
<?sdop foot_right_recto="&arabicpage;"
       foot_left_verso="&arabicpage;"?>
.endd
It is not possible to include markup when changing the values of these strings.
If you want to change the markup in headers or footers, you have to provide
your own template files.

Other useful entities that are available in header and footer lines are
&`&&chapternumber;`&, &`&&chaptertitle`&, &`&&sectionnumber`&, and
&`&&sectiontitle`&. In the case of titles, the value is taken from a
&`<titleabbrev>`& element if present, otherwise from &`<title>`&. Here is an
example of a processing instruction that adds the chapter title and number to
footer lines, on the right and left, respectively:
.code
<?sdop
  foot_right_recto="&chaptertitle; (&chapternumber;)"
  foot_left_verso="&chaptertitle; (&chapternumber;)"
?>
.endd
During chapter-like components such as prefaces, appendices, indexes, and
colophons, the title is placed in &`&&chaptertitle`&.

In an article, &`&&chaptertitle`& contains the title of the article. In an
appendix in an article, the title is placed in &`&&sectiontitle`&, because it
behaves like a section and does not start a new page.

You can use &`&&romanpage;`& to obtain the page number as a roman numeral. This
is used in the default settings for the table of contents and the preface(s),
where the page number is printed in italic.

If you want to use a rule (a horizontal line) in a header or a footer, you can
do so by providing your own template file containing a suitable table with a
top or bottom frame line.

.index-to "ID5"


.section "Index sorting" "SECTindexcollate"
.index "index" "collating sequence"
.index "files" "index collation sequence"
The file called &_indexcollate_& controls the order in which index items are
sorted. There are comments in the file that explain its format. You can change
the index sorting order by overriding this file.




. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Typesetting features" "CHAPtypeset"
.index-from "ID6" "typesetting features"
This chapter discusses some of the typesetting features of SDoP. The lack of
some of these facilities in other processors was one of the reasons for writing
SDoP.

.section "Vertical white space"
.index "space" "vertical"
.index "space" "zero-width"
.index "space" "hard"
Additional vertical white space can be obtained by inserting a paragraph
containing just a single `hard space' character (U+00A0). A smaller amount of
vertical space can be obtained by inserting a paragraph containing just a
single `zero-width space' character (U+200B). SDoP treats this case
specially, removing the line containing the space so that only the pre- and
post-paragraph spaces remain.


.section "Indentation for literal blocks"
.index "indent" "literal blocks"
SDoP automatically indents literal blocks within indented items. For example,
paragraphs in a list are indented; if a &`<literallayout>`& block is part of a
list item, SDoP indents it by the list item's indent, in addition to any indent
for the literal block itself.

Some other DocBook processors do not do this. They always set literal blocks
with reference to the lefthand edge of the page. Consequently, input that was
created for such other processors may contain extra indents for literal blocks
that are not needed when it is processed by SDoP. To avoid excessive
indentation, SDoP automatically removes an indent that is common to every line
in a literal block. This feature can be turned off by setting the global
processing parameter &*literal_indent_fudge*& to &`no`& (&R;
&<<SECTliteral>>&).


.section "Pagination"
SDoP never outputs a section title as the last line on a page (chapter titles
are always at the head of a page). A table that contains just a single row is
treated as a sort of heading and is also not printed at the end of a page. SDoP
generally avoids printing just one line of a multi-line paragraph as either the
first or last line of a page (such lines are known as `widow' and `orphan'
lines, respectively).


.section "Line splitting and hyphenation" "SECThyphenation"
.index "hyphenation" "processing details"
.index "line splitting"
Some other applications do overly-aggressive hyphenation. If a word that does
not fit into a line can be hyphenated, they always split it. This leads to far
too much hyphenation. SDoP attempts hyphenation only when the line is very
`loose' &-- that is, the ratio of space to text in the line is high, which
would make it look ugly if no more text were added.

When it encounters a very loose line, SDoP first looks for explicit hyphens
within the next word. If any are found, it tries to split the word at one of
them. If this fails (because the shortest initial part of the word still makes
the line overflow), no hyphenation occurs. There are four explicit hyphen
characters:
.ilist
.index "hyphen" "hard"
A `hard' hyphen is the normal hyphen character (U+002D). It is output
whether or not the word is split immediately after it.
.next
.index "hyphen" "soft"
The `soft' hyphen character (U+00AD) indicates a potential hyphenation point,
but is output only if the word is actually split at that point. It is omitted
when there is no split.
.next
.index "hyphen" "invisible"
.index "kerning" "zero width space"
The `zero width space' character (U+200B) also indicates a potential
hyphenation point. Unlike the soft hyphen, however, nothing is inserted if the
word is split at that point. It is useful, for example, for allowing technical
`words' containing underscores to be split after the underscore without any
insertion. When the spaces in a line are stretched to justify a line, zero
width spaces are not affected. However, a zero width space does prevent kerning
between the preceding and following characters.
.next
.index "hyphenation" "BPH character"
.index "kerning" "BPH character"
The Unicode character called BPH (`break permitted here') is treated in
exactly the same way as a zero width space, except that, when the word is not
split, it does not prevent kerning between the preceding and following
characters.
.endlist

If no explicit hyphens are found, SDoP tries automatic hyphenation. SDoP does
not automatically hyphenate the last word in a paragraph, or any word that
contains capital letters. If you need to hyphenate such a word (for example, a
long word at the start of a sentence), you must insert one or more soft hyphen
characters.

.index "hyphenation" "disabling"
Both forms of hyphenation can be disabled by a processing instruction (&R;
&<<SECTotherpin>>&). This is a local processing instruction, so hyphenation
can be turned on and off as often as you like throughout the document. SDoP
uses a dictionary for automatic hyphenation (&R; &<<SECThydict>>&,
&<<CHAPmainhydic>>&).

.index "hyphenation" "NBH character"
It is also possible to disable automatic hyphenation at specific points in
individual words by including the `no break here' character (NBH, U+0083).
For example, the word `elec-tri-fi-cation' has three automatic hyphenation
points, as shown. If you input it as &`elec&&#x83;trification`&, the first of
them is disabled. The inclusion of NBH does not prevent kerning between the
previous and following characters.


.section "Fine adjustments to lines"
Once it has formatted a paragraph, SDoP does a second pass over the lines to
look for instances where a very tight, but not hyphenated, line is followed by
a very loose line. If it finds such a pair of lines, it checks to see whether
it is possible to move the last word from the first line onto the second line
without making the first line unacceptably loose. This is a rare occurrence,
but when it works it can make the paragraph look a lot nicer.


.section "Ligatures"
.index "ligatures"
SDoP automatically uses the single character `fi' (U+FB01) whenever the
letter `f' is followed by the letter `i' and the font is not monospaced and
does contain the ligature character.


.section "Kerning"
.index "kerning"
SDoP uses the kerning information in a font's AFM file to move certain pairs of
characters closer together or further apart, in order to improve the appearance
of the text. There is a local processing setting that can suppress this for all
or part of a document (&R; &<<SECTotherpin>>&). Kerning between two
individual characters can be suppressed by inserting a zero width space between
them. The `break permitted here' and `no break here' characters do not
suppress kerning.


.section "The <emphasis> element" "SECTemphasis"
.index-from "ID7" "&*emphasis*&"
.index "fonts" "italic"
.index "fonts" "bold"
.index "fonts" "roman"
The &`<emphasis>`& element with no attributes specifies italic; the attribute
&`role="bold"`& specifies a boldface font. Also supported is &`role="roman"`&,
which can be useful for overriding a bold or italic font caused by an element
such as &`<varname>`&.

.index "colour" "text"
The &`role`& attribute can also be used to specify special fonts or coloured
text. In the template for the title page (the data file &(titletemplate)&) the
form &`role="booktitle`&&'n'&&`"`&, where &'n'& is a number between 1 and 4,
can appear. This selects one of four different sizes of title font.


.section "Using a small font" "SECTsmallfont"
.index "fonts" "small"
A normal font, but at a smaller that normal size, can be specified by:
.code
<emphasis role="smallfont">
.endd
The actual size of font can be set by the &*font_small_main*& processing
parameter.


.section "Using exotic fonts" "SECTexotic"
.index "fonts" "exotic"
.index "fonts" "specifying special"
In the main text, the &`role`& attribute can be used to specify the use of a
special font. The format for this is:
.display
&`<emphasis role="`&&'exotic-font-name/size/leading'&&`">`&
.endd
The leading (`ledding', not `leeding') is a minimum amount of extra vertical
white space that is inserted above each line that contains characters from this
font. (The default font size is 11 points, with 1 point of leading.)

If the size and leading are omitted, the values from the current font are used.
The size can be given as zero to mean `the current size' if just additional
leading is needed. Fonts with standard encoding are re-encoded as Unicode; for
others, only characters in the range 0&--255 are supported, in their native
encoding. For example, to include a treble clef at a 9-point size from the
musical font that is part of &'Philip's Music Writer'&, you could use:
.code
<emphasis role="PMW-Music/9">!</emphasis>
.endd
The treble clef is encoded as character 33 (an exclamation mark in Unicode) in
the PMW-Music font. If you use a special font in this way, you must ensure that
its AFM file is available in a directory that you pass to SDoP via the &%-S%&
command line option or &$SDOP_SHARE$& environment variable, or in the
&(fontmetrics)& subdirectory of such a directory.


.section "Specifying coloured text" SECTcolour
.index "colour" "text"
You can specify that text is to be coloured like this:
.code
<emphasis role="rgb=r,g,b">...</emphasis>
.endd
The colour is defined by the three red-green-blue values, in the range 0 to 1.
For example:
.code
This is a <emphasis role="rgb=1,0,0">red</emphasis> word.
.endd
The colour of text that forms a cross-reference or an index page number that is
turned into a clickable link when the output is converted to a PDF can be
separately specified by setting the &*xref_rgb*& parameter. This overrides any
&`<emphasis>`& setting.

.index-to "ID7"


.section "Change bars"
.index "change bars"
SDoP supports the &`revisionflag`& option on elements, but the only value that
is recognized is `changed'. The effect is to print a vertical change bar at
the right hand side of the affected text.


.section "Itemized lists"
.index "itemized list" "mark"
If no &`mark`& option is present on an &`<itemizedlist>`& element, SDoP uses a
bullet (U+00B7) for top level lists, a dash (U+2212) for the first nested
level, and a small circle (the letter `o') for the next level. SDoP
recognizes the words &`bullet`&, &`dash`&, and &`opencircle`& as values for
&`mark`&. You can also give a Unicode code point, for example, &`U+261E`&. The
font style for the mark can be set via the &*ilist_tag_style*& parameter, or
the entire font (size, type, style) can be set via the &*font_ilist_tag*&
parameter.


.section "Ordered lists"
.index "ordered list" "numbering"
The &*olist_format*& parameter controls what is printed when numbering an
ordered list. It specifies a text string that contains &`%s`& at the point
where the item number is to be inserted. The default value is &`(%s)`&. The
format of the item number itself (roman, arabic, alphabetic) is controlled by
the &%numeration%& attribute of the &`<orderedlist>`& element. The font style
for the whole string (default roman) can be specified by the
&*olist_tag_style*& parameter, or the entire font (size, type, style) can be
set via the &*font_olist_tag*& parameter.


.section "Tables" "SECTtables"
.index "tables" "parameters for"
Space is left at the beginning and end of the entries in each column of a
table. This reduces the column widths as specified in the XML. Vertical space
is left between rows, above the top of the frame, and below the bottom of the
frame (in cases where a top and bottom frame line is drawn). The thickness of
the frame is in principle variable, but none of these values are yet adjustable
(though they may be in a later release):

.itable none 0 0 3 10pt left 140pt left 244pt left
.row ""  "Left entry space"      "5pt"
.row ""  "Right entry space"     "5pt"
.row ""  "Row separation space"  "5pt"
.row ""  "Top frame space"       "0pt"
.row ""  "Bottom frame space"    "4pt"
.row ""  "Frame thickness"       "0.5pt"
.endtable

Tables are by default set flush left on the page, but they can be indented by
setting the &*table_indent*& processing parameter. There are a number of other
processing parameters that can be used to control the way table titles are
handled (&R; &<<SECTintexttables>>&). A further parameter can be used to alter
the way SDoP diagnoses table cells that overflow. Setting:
.code
<?sdop table_warn_overflow="never"?>
.endd
suppresses all cell overflow warnings, whereas setting:
.code
<?sdop table_warn_overflow="overprint"?>
.endd
suppresses cell overflow warnings in two circumstances when there is no actual
text collision, provided that no separator is being printed between the
relevant columns:
.olist
The overflowing cell is not the last on the line, is left justified, and the
next cell is not left justified.
.next
The overflowing cell is not the first on the line, is right justified, and the
previous cell is not right justified.
.endlist

Both of these settings affect only what follows them; they can be changed
as often as you like during the course of a document.

.index "character alignment in tables"
.index "tables" "character alignment"
There is support for aligning cells by reference to a specific character (for
example, to align monetary values on the decimal point). This takes the form of
support for &`align="char"`& and the &`char`& and &`charoff`& attributes of the
&`<tgroup>`&, &`<colspec>`&, and &`<entry>`& elements. The default values for
&`char`& and &`charoff`& are &`"."`& and &`"50"`&, respectively. The value of
&`char`& can be an entity name. If the aligning character is not found in a
cell's text, SDoP behaves as if it were present at the end of the string. If
character alignment would cause overflow or underflow, an error is generated
and right or left alignment (respectively) is used instead.



.section "Footnotes"
.index "footnotes"
Up to nine footnotes per page are fully supported, keyed by the numbers 1&--9.
If there are more than nine footnotes on a page, the lines containing
footnote references greater than nine may be poorly spaced. A warning message
is output. This is another example of the `simple' approach that SDoP takes.
.footnote
Footnote numbering is a chicken-and-egg problem. Paragraphs have to be
formatted before they can be assigned to pages. SDoP assumes that a footnote
reference will be a single digit. Only after the page breaks are determined can
the footnotes be numbered, and an extra digit alters the length of the line. If
the line is justified and the extra digit can be accommodated by reducing the
stretch for each space, all is well, but this cannot be guaranteed.
.endnote
If a &`<footnote>`& element is at the start of an input line, the newline
character at the end of the previous line is ignored, so that the footnote key
is hard up against the preceding word.


.section "Illustrations and figures" "SECTillfig"
.index "illustrations, parameters for"
.index "figures" "parameters for"
The &`<textobject>`& and &`<imageobject>`& elements within a
&`<mediaobject>`& element are supported. For images, the &`<imagedata>`&
element supports only the &`fileref`& attribute for the source of the image
data and the &`format`& attribute to specify a format. If no format is given,
the file name extension is used. The formats currently recognized are EPS for
encapsulated PostScript, SVG for Scalar Vector Graphics, JPEG or JPG for a JPEG
image (if &(libjpeg)& is available), and PNG for a PNG image (if &(libpng)&
is available). SVG support is new to release 1.10, and is fairly basic. If you
have an SVG image that SDoP does not render correctly, a workaround is to use
an image processor such as &(ImageMagick)& to convert it to one of the other
formats. A program for testing SDoP's SVG support, called &(svgtest)&, is built
with SDoP, but not installed. You can find it in the build &_src_& directory.
It takes an SVG file name as an argument, and writes free-standing PostScript
to the standard output.

SDoP recognizes the &`align`&, &`depth`&, &`width`&, &`scale`&, and
&`scalefit`& attributes on an &`<imagedata>`& element. If either of the width
and depth are not given, they are taken from the bounding box data of the
image, if available. If an explicit depth is greater than the bounding box
depth, the image is vertically centred in the given depth.

If &`scalefit`& is set to 1, the image is scaled to fit the explicit width, if
given, otherwise to the explicit depth, if given, otherwise to the page width.

Occasionally, an image may not appear exactly where you want it; this can
happen if the bounding box values in the data are not quite right. A facility
for adjusting the position of an image is therefore provided. If the
&`<imageobject>`& element has a &`role`& attribute that consists of one or two
dimensions, comma separated, they are used to ajust the position of the image.
The values may be negative. The first dimension moves the image right or left,
and the second, if present, up or down.

There is support for the &`<figure>`& element, and there are a number of
processing parameters that can be used to control the format and alignment of
figure titles (&R; &<<SECTfigure>>&). However, figures are always set
inline; there is no support for floating figures.


.section "Subscripts and superscripts"
.index "subscripts"
.index "superscripts"
Subscripts and superscripts are supported. By default, in body text, they are
printed in a small font, and are lowered or raised by 33% of the line depth,
respectively. In titles, they are raised or lowered, but the font is unchanged.
There are local processing parameters that can be used to adjust the amount of
raising or lowering, and to disable the use of a small font in body text ((&R;
&<<SECTsubsuper>>&).


.section "Indexes"
.index "index" "parameters for"
A document may contain multiple indexes, interspersed with chapters and
appendices if required. The entries for a particular index are identified by
the use of the &`role`& option on &`<indexterm>`& and &`<index>`& elements.
Unlike some other DocBook processors, SDoP respects font-changing elements such
as &`<emphasis>`& and &`<filename>`& in index entries. It is possible to alter
the order in which index elements sort by overriding the default collation file
(&R; &<<SECTindexcollate>>&).

When comparing index items, both for sorting, and so that it can amalgamate
multiple page numbers into a single entry, SDoP requires not only that the text
be identical, but also that the same font (at the same size) is used, and also
that the colour and any sub- or superscripting is the same.

Indexes are printed in two columns, using slightly smaller fonts than the body
of the document by default. An index is omitted if there are no relevant
entries. If there are at least two different leading characters in the index
entries, headings are inserted before those that start with a symbol, those
that start with a digit, and those that start with each individual letter. If
all the entries start with the same character, no heading is inserted (this
might be the case in an index of variables, for example, where they all start
with &`$`&). Headings can be manually disabled by setting the processing
parameter &*index_headings*& to &`no`&. Index headings never appear in the
printed table of contents, but they can be requested for the PDF table of
contents by setting &*index_headings_pdf_toc*&.

By default, the page numbers in indexes are identified in the PostScript output
such that they are turned into clickable links if it is converted to a PDF.
This can be disabled by setting &*xref_links*& to &`no`&.

Apart from the index sorting order, which is controlled by one of SDoP's data
files (&R; &<<SECTindexcollate>>&), and the list of characters that are ignored
when sorting (set by the &*index_sort_omit*& parameter), no other
characteristics of indexes are at present configurable.

.index-to "ID6"


. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Making Slides" "CHAPslides"
.index "slides, parameters for"
As well as generating PostScript for printed page images, SDoP can be used to
generate PostScript that, when converted to a PDF, can be used for slideshows.
To do this you need to adjust some of the processing parameters. The following
is an example:
.code
<?sdop background_rgb="0.8,0.8,1.0"
       page_foot_line_width="840"
       page_full_length="620"
       page_line_width="810"
       paper_size="900x660"
       font_main="26"
       font_mainmono="24"
       font_chapter="32"
       font_toc="18,1,serif"
       foot_centre_recto=""
       foot_centre_verso=""
       foot_right_recto="&arabicpage;"
       foot_right_verso="&arabicpage;"
       ilist_indent="24,24,0"
       margin_bottom="20"
       margin_left_recto="45"
       margin_left_verso="45"
       numbertitles="no"
       toc_sections="no"
?>
.endd
This sets up a pale background, adjusts sizes and widths, and arranges that
slide (page) numbers are in the bottom lefthand corner. Each slide can then be
defined as a `chapter'.



. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Supported DocBook elements" "CHAPsuppelems"
.index-from "ID8" "elements" "supported"
The named entities and Unicode characters that SDoP supports are listed in the
following two chapters. As well as elements and entities, SDoP recognizes these
special XML constructs:

.itable none 0 0 3 10pt left 150pt left 150pt left
.row "" "&`<!...!>`&"         "XML heading: ignored"
.row "" "&`<!--...-->`&"      "XML comment: ignored"
.row "" "&`<![CDATA[...]]>`&" "Literal character data"
.endtable

The following table lists the DocBook elements that are supported, in whole or
in part, by SDoP. In some cases, though the element is recognized, it causes no
change of processing. Examples of elements of this type are &`<abbrev>`&,
&`<acronym>`&, and &`<trademark>`&. Elements that are defined for Simplified
DocBook are marked with a dagger.

.itable none 0 0 4 10pt left 16pt left 124pt left 300pt left
.row "" ""         "&*Element*&"        "&*Comment*&"
.row "" "&dagger;" "&`abbrev`&"         "Ignored"
.row "" "&dagger;" "&`abstract`&"       "Ignored"
.row "" "&dagger;" "&`acronym`&"        "Ignored"
.row "" ""         "&`address`&"
.row "" "&dagger;" "&`affiliation`&"
.row "" "&dagger;" "&`appendix`&"       "Supports &`id`&"
.row "" "&dagger;" "&`article`&"
.row "" "&dagger;" "&`articleinfo`&"
.row "" "&dagger;" "&`attribution`&"
.row "" "&dagger;" "&`audiodata`&"      "Ignored"
.row "" "&dagger;" "&`audioobject`&"    "Ignored"
.row "" "&dagger;" "&`author`&"
.row "" "&dagger;" "&`authorblurb`&"    "Ignored"
.row "" "&dagger;" "&`authorinitials`&"
.row "" "&dagger;" "&`blockquote`&"
.row "" ""         "&`book`&"
.row "" ""         "&`bookinfo`&"
.row "" "&dagger;" "&`caption`&"
.row "" ""         "&`chapter`&"        "Supports &`id`&"
.row "" "&dagger;" "&`citetitle`&"      "Treated as &`<emphasis>`&"
.row "" ""         "&`colophon`&"
.row "" "&dagger;" "&`colspec`&"        "Supports &`align`&, &`char`&, &&&
                                         &`charoff`&, &`colwidth`&, &&&
                                         &`colsep`&"
.row "" "&dagger;" "&`command`&"
.row "" "&dagger;" "&`computeroutput`&" "Treated as &`<literal>`&"
.row "" "&dagger;" "&`copyright`&"      "Supported in &`<articleinfo>`& and &&&
                                         &`<bookinfo>`&"
.row "" "&dagger;" "&`corpauthor`&"
.row "" "&dagger;" "&`date`&"
.row "" "&dagger;" "&`edition`&"
.row "" "&dagger;" "&`editor`&"
.row "" "&dagger;" "&`email`&"          "Italic by default"
.row "" "&dagger;" "&`emphasis`&"       "Supports &`role`&"
.row "" "&dagger;" "&`entry`&"          "Supports &`align`&, &`char`&, &&&
                                         &`charoff`&"
.row "" "&dagger;" "&`epigraph`&"       "Works like &`<blockquote>`&"
.row "" "&dagger;" "&`example`&"        "Supports &`id`&"
.row "" "&dagger;" "&`figure`&"         "Supports &`id`&"
.row "" "&dagger;" "&`filename`&"
.row "" "&dagger;" "&`firstname`&"
.row "" "&dagger;" "&`footnote`&"
.row "" "&dagger;" "&`footnoteref`&"    "Only on same page as the footnote"
.row "" ""         "&`formalpara`&"
.row "" ""         "&`function`&"
.row "" "&dagger;" "&`holder`&"
.row "" "&dagger;" "&`honorific`&"
.row "" "&dagger;" "&`imagedata`&"      "Supports &`align`&, &`depth`&, &&&
                                         &`fileref`&, &`format`&, &&&
                                         &`scale`&, &`scalefit`&, &`width`&"
.row "" "&dagger;" "&`imageobject`&"
.row "" ""         "&`index`&"          "Supports &`role`&"
.row "" ""         "&`indexterm`&"      "Supports &`class`&, &`id`&, &`role`&"
.row "" ""         "&`informalfigure`&"
.row "" "&dagger;" "&`informaltable`&"  "Supports &`frame`&, &`colsep`&, &&&
                                         &`rowsep`&"
.row "" "&dagger;" "&`inlinemediaobject`&" "Treated as &`<mediaobject>`&"
.row "" "&dagger;" "&`issuenum`&"
.row "" "&dagger;" "&`itemizedlist`&"   "Supports &`mark`&"
.row "" "&dagger;" "&`jobtitle`&"
.row "" "&dagger;" "&`keyword`&"        "Ignored"
.row "" "&dagger;" "&`keywordset`&"     "Ignored"
.row "" "&dagger;" "&`legalnotice`&"
.row "" "&dagger;" "&`lineage`&"
.row "" "&dagger;" "&`lineannotation`&" "Uses a small italic font"
.row "" "&dagger;" "&`link`&"           "Ignored"
.row "" "&dagger;" "&`listitem`&"
.row "" "&dagger;" "&`literal`&"
.row "" "&dagger;" "&`literallayout`&"  "Supports &`class`&"
.row "" "&dagger;" "&`mediaobject`&"
.row "" "&dagger;" "&`note`&"           "Works like &`<blockquote>`&"
.row "" "&dagger;" "&`objectinfo`&"     "Ignored"
.row "" "&dagger;" "&`option`&"
.row "" "&dagger;" "&`orderedlist`&"    "Supports &`numeration`&"
.row "" "&dagger;" "&`orgname`&"
.row "" "&dagger;" "&`othercredit`&"
.row "" "&dagger;" "&`othername`&"
.row "" "&dagger;" "&`para`&"
.row "" "&dagger;" "&`phrase`&"
.row "" ""         "&`preface`&"
.row "" ""         "&`primary`&"
.row "" "&dagger;" "&`programlisting`&" "Treated as &`<screen>`&"
.row "" "&dagger;" "&`pubdate`&"
.row "" "&dagger;" "&`publishername`&"
.row "" "&dagger;" "&`quote`&"
.row "" "&dagger;" "&`releaseinfo`&"
.row "" "&dagger;" "&`replaceable`&"    "Italic by default"
.row "" "&dagger;" "&`revdescription`&"
.row "" "&dagger;" "&`revhistory`&"
.row "" "&dagger;" "&`revision`&"
.row "" "&dagger;" "&`revnumber`&"
.row "" "&dagger;" "&`revremark`&"      "Ignored"
.row "" "&dagger;" "&`row`&"            "Supports &`rowsep`&"
.row "" ""         "&`screen`&"
.row "" ""         "&`secondary`&"
.row "" "&dagger;" "&`section`&"        "Supports &`id`&"
.row "" "&dagger;" "&`sectioninfo`&"    "Ignored"
.row "" ""         "&`sect`&&'n'&"      "Treated as &`<section>`&"
.row "" ""         "&`see`&"
.row "" ""         "&`seealso`&"
.row "" "&dagger;" "&`sidebar`&"        "Works like &`<blockquote>`&"
.row "" ""         "&`simpara`&"
.row "" "&dagger;" "&`subject`&"        "Ignored"
.row "" "&dagger;" "&`subjectset`&"     "Ignored"
.row "" "&dagger;" "&`subjectterm`&"    "Ignored"
.row "" ""         "&`subscript`&"      "No small font in titles; ignored &&&
                                         in table of contents"
.row "" "&dagger;" "&`subtitle`&"       "For articles, chapters, appendixes, &&&
                                         and indexes"
.row "" ""         "&`superscript`&"    "No small font in titles; ignored &&&
                                         in table of contents"
.row "" "&dagger;" "&`surname`&"
.row "" "&dagger;" "&`systemitem`&"     "Ignored"
.row "" "&dagger;" "&`table`&"          "Supports &`frame`&, &`colsep`&, &&&
                                         &`rowsep`&"
.row "" "&dagger;" "&`tbody`&"
.row "" "&dagger;" "&`term`&"
.row "" ""         "&`tertiary`&"
.row "" "&dagger;" "&`textobject`&"
.row "" "&dagger;" "&`tfoot`&"
.row "" "&dagger;" "&`tgroup`&"         "Supports &`align`&, &`char`&, &&&
                                         &`charoff`&, &`cols`&, &`colsep`&, &&&
                                         &`rowsep`&"
.row "" "&dagger;" "&`thead`&"
.row "" "&dagger;" "&`title`&"
.row "" "&dagger;" "&`titleabbrev`&"
.row "" "&dagger;" "&`trademark`&"      "Ignored"
.row "" "&dagger;" "&`ulink`&"          "Supports &`url`&"
.row "" "&dagger;" "&`userinput`&"      "Monospaced by default"
.row "" "&dagger;" "&`variablelist`&"
.row "" "&dagger;" "&`varlistentry`&"
.row "" ""         "&`varname`&"
.row "" "&dagger;" "&`videodata`&"      "Ignored"
.row "" "&dagger;" "&`videoobject`&"    "Ignored"
.row "" "&dagger;" "&`volumenum`&"
.row "" "&dagger;" "&`xref`&"           "Supports &`linkend`&"
.row "" "&dagger;" "&`year`&"
.endtable


In an &`<article>`& element, &`<id>`& and &`<class>`& attributes are
recognized, but ignored.

The Simplified DocBook elements that are not supported are &`<authorgroup>`&,
&`<biblio`&&'xxx'&&`>`&, &`<entrytbl>`&, and &`<spanspec>`&.

.index-to "ID8"


. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Supported DocBook entities" "CHAPsuppents"
.index-from "ID9" "entities" "supported"
Individual data characters can always be specified by their numerical code
points using the entity notation &`&&#`&&'n'&&`;`& (where &'n'& is a decimal
number) or &`&&#x`&&'n'&&`;`& (where &'n'& is a hexadecimal number). The latter
form is more common because Unicode code points are normally listed in
hexadecimal. For example, a copyright symbol can be specified as &`&&#xA9;`&.
SDoP also recognizes a number of named entities that represent special
characters. They are shown in the table below. Additional special entity names
are recognized in header, footer, title page, and table of contents templates
(&R; &<<SECThandf>>&, &<<SECTtitlepages>>&, &<<SECTtabofcont>>&).


.itable none 0 0 5 10pt left 80pt left 80pt centre 60pt centre 100pt left
.row "" "&nbsp;&nbsp;&nbsp;&nbsp;&&&
         &*Name*&"       "&*Code point*&"  "&*Character*&"
.row "" "&`&&AElig;`&"   "&`U+00C6`&"      "&AElig;"
.row "" "&`&&Aacute;`&"  "&`U+00C1`&"      "&Aacute;"
.row "" "&`&&Abreve;`&"  "&`U+0102`&"      "&Abreve;"
.row "" "&`&&Acirc;`&"   "&`U+00C2`&"      "&Acirc;"
.row "" "&`&&Agrave;`&"  "&`U+00C0`&"      "&Agrave;"
.row "" "&`&&Amacr;`&"   "&`U+0100`&"      "&Amacr;"
.row "" "&`&&Aogon;`&"   "&`U+0104`&"      "&Aogon;"
.row "" "&`&&Aring;`&"   "&`U+00C5`&"      "&Aring;"
.row "" "&`&&Atilde;`&"  "&`U+00C3`&"      "&Atilde;"
.row "" "&`&&Auml;`&"    "&`U+00C4`&"      "&Auml;"
.row "" "&`&&Cacute;`&"  "&`U+0106`&"      "&Cacute;"
.row "" "&`&&Ccaron;`&"  "&`U+010C`&"      "&Ccaron;"
.row "" "&`&&Ccedil;`&"  "&`U+00C7`&"      "&Ccedil;"
.row "" "&`&&Ccirc;`&"   "&`U+0108`&"      "&Ccirc;"
.row "" "&`&&Cdot;`&"    "&`U+010A`&"      "&Cdot;"
.row "" "&`&&Dagger;`&"  "&`U+2021`&"      "&Dagger;"
.row "" "&`&&Dcaron;`&"  "&`U+010E`&"      "&Dcaron;"
.row "" "&`&&Dstrok;`&"  "&`U+0110`&"      "&Dstrok;"
.row "" "&`&&ENG;`&"     "&`U+014A`&"      "&ENG;"
.row "" "&`&&ETH;`&"     "&`U+00D0`&"      "&ETH;"
.row "" "&`&&Eacute;`&"  "&`U+00C9`&"      "&Eacute;"
.row "" "&`&&Ecaron;`&"  "&`U+011A`&"      "&Ecaron;"
.row "" "&`&&Ecirc;`&"   "&`U+00CA`&"      "&Ecirc;"
.row "" "&`&&Edot;`&"    "&`U+0116`&"      "&Edot;"
.row "" "&`&&Egrave;`&"  "&`U+00C8`&"      "&Egrave;"
.row "" "&`&&Emacr;`&"   "&`U+0112`&"      "&Emacr;"
.row "" "&`&&Eogon;`&"   "&`U+0118`&"      "&Eogon;"
.row "" "&`&&Euml;`&"    "&`U+00CB`&"      "&Euml;"
.row "" "&`&&Euro;`&"    "&`U+20AC`&"      "&Euro;"
.row "" "&`&&Gbreve;`&"  "&`U+011E`&"      "&Gbreve;"
.row "" "&`&&Gcedil;`&"  "&`U+0122`&"      "&Gcedil;"
.row "" "&`&&Gcirc;`&"   "&`U+011C`&"      "&Gcirc;"
.row "" "&`&&Gdot;`&"    "&`U+0120`&"      "&Gdot;"
.row "" "&`&&Hcirc;`&"   "&`U+0124`&"      "&Hcirc;"
.row "" "&`&&Hstrok;`&"  "&`U+0126`&"      "&Hstrok;"
.row "" "&`&&IJlig;`&"   "&`U+0132`&"      "&IJlig;"
.row "" "&`&&Iacute;`&"  "&`U+00CD`&"      "&Iacute;"
.row "" "&`&&Icirc;`&"   "&`U+00CE`&"      "&Icirc;"
.row "" "&`&&Idot;`&"    "&`U+0130`&"      "&Idot;"
.row "" "&`&&Igrave;`&"  "&`U+00CC`&"      "&Igrave;"
.row "" "&`&&Imacr;`&"   "&`U+012A`&"      "&Imacr;"
.row "" "&`&&Iogon;`&"   "&`U+012E`&"      "&Iogon;"
.row "" "&`&&Itilde;`&"  "&`U+0128`&"      "&Itilde;"
.row "" "&`&&Iuml;`&"    "&`U+00CF`&"      "&Iuml;"
.row "" "&`&&Jcirc;`&"   "&`U+0134`&"      "&Jcirc;"
.row "" "&`&&Kcedil;`&"  "&`U+0136`&"      "&Kcedil;"
.row "" "&`&&Lacute;`&"  "&`U+0139`&"      "&Lacute;"
.row "" "&`&&Lcaron;`&"  "&`U+013D`&"      "&Lcaron;"
.row "" "&`&&Lcedil;`&"  "&`U+013B`&"      "&Lcedil;"
.row "" "&`&&Lmidot;`&"  "&`U+013F`&"      "&Lmidot;"
.row "" "&`&&Lstrok;`&"  "&`U+0141`&"      "&Lstrok;"
.row "" "&`&&Nacute;`&"  "&`U+0143`&"      "&Nacute;"
.row "" "&`&&Ncaron;`&"  "&`U+0147`&"      "&Ncaron;"
.row "" "&`&&Ncedil;`&"  "&`U+0145`&"      "&Ncedil;"
.row "" "&`&&Ntilde;`&"  "&`U+00D1`&"      "&Ntilde;"
.row "" "&`&&OElig;`&"   "&`U+0152`&"      "&OElig;"
.row "" "&`&&Oacute;`&"  "&`U+00D3`&"      "&Oacute;"
.row "" "&`&&Ocirc;`&"   "&`U+00D4`&"      "&Ocirc;"
.row "" "&`&&Odblac;`&"  "&`U+0150`&"      "&Odblac;"
.row "" "&`&&Ograve;`&"  "&`U+00D2`&"      "&Ograve;"
.row "" "&`&&Omacr;`&"   "&`U+014C`&"      "&Omacr;"
.row "" "&`&&Oslash;`&"  "&`U+00D8`&"      "&Oslash;"
.row "" "&`&&Otilde;`&"  "&`U+00D5`&"      "&Otilde;"
.row "" "&`&&Ouml;`&"    "&`U+00D6`&"      "&Ouml;"
.row "" "&`&&Racute;`&"  "&`U+0154`&"      "&Racute;"
.row "" "&`&&Rcaron;`&"  "&`U+0158`&"      "&Rcaron;"
.row "" "&`&&Rcedil;`&"  "&`U+0156`&"      "&Rcedil;"
.row "" "&`&&Sacute;`&"  "&`U+015A`&"      "&Sacute;"
.row "" "&`&&Scaron;`&"  "&`U+0160`&"      "&Scaron;"
.row "" "&`&&Scedil;`&"  "&`U+015E`&"      "&Scedil;"
.row "" "&`&&Scirc;`&"   "&`U+015C`&"      "&Scirc;"
.row "" "&`&&THORN;`&"   "&`U+00DE`&"      "&THORN;"
.row "" "&`&&Tcaron;`&"  "&`U+0164`&"      "&Tcaron;"
.row "" "&`&&Tcedil;`&"  "&`U+0162`&"      "&Tcedil;"
.row "" "&`&&Tstrok;`&"  "&`U+0166`&"      "&Tstrok;"
.row "" "&`&&Uacute;`&"  "&`U+00DA`&"      "&Uacute;"
.row "" "&`&&Ubreve;`&"  "&`U+016C`&"      "&Ubreve;"
.row "" "&`&&Ucirc;`&"   "&`U+00DB`&"      "&Ucirc;"
.row "" "&`&&Udblac;`&"  "&`U+0170`&"      "&Udblac;"
.row "" "&`&&Ugrave;`&"  "&`U+00D9`&"      "&Ugrave;"
.row "" "&`&&Umacr;`&"   "&`U+016A`&"      "&Umacr;"
.row "" "&`&&Uogon;`&"   "&`U+0172`&"      "&Uogon;"
.row "" "&`&&Uring;`&"   "&`U+016E`&"      "&Uring;"
.row "" "&`&&Utilde;`&"  "&`U+0168`&"      "&Utilde;"
.row "" "&`&&Uuml;`&"    "&`U+00DC`&"      "&Uuml;"
.row "" "&`&&Wcirc;`&"   "&`U+0174`&"      "&Wcirc;"
.row "" "&`&&Yacute;`&"  "&`U+00DD`&"      "&Yacute;"
.row "" "&`&&Ycirc;`&"   "&`U+0176`&"      "&Ycirc;"
.row "" "&`&&Yuml;`&"    "&`U+0178`&"      "&Yuml;"
.row "" "&`&&Zacute;`&"  "&`U+0179`&"      "&Zacute;"
.row "" "&`&&Zcaron;`&"  "&`U+017D`&"      "&Zcaron;"
.row "" "&`&&Zdot;`&"    "&`U+017B`&"      "&Zdot;"
.row "" "&`&&aacute;`&"  "&`U+00E1`&"      "&aacute;"
.row "" "&`&&abreve;`&"  "&`U+0103`&"      "&abreve;"
.row "" "&`&&acirc;`&"   "&`U+00E2`&"      "&acirc;"
.row "" "&`&&aelig;`&"   "&`U+00E6`&"      "&aelig;"
.row "" "&`&&agrave;`&"  "&`U+00E0`&"      "&agrave;"
.row "" "&`&&amacr;`&"   "&`U+0101`&"      "&amacr;"
.row "" "&`&&amp;`&"     "&`U+0026`&"      "&amp;"
.row "" "&`&&aogon;`&"   "&`U+0105`&"      "&aogon;"
.row "" "&`&&apos;`&"    "&`U+0027`&"      "&apos;"
.row "" "&`&&aring;`&"   "&`U+00E5`&"      "&aring;"
.row "" "&`&&atilde;`&"  "&`U+00E3`&"      "&atilde;"
.row "" "&`&&auml;`&"    "&`U+00E4`&"      "&auml;"
.row "" "&`&&brvbar;`&"  "&`U+00A6`&"      "&brvbar;"
.row "" "&`&&cacute;`&"  "&`U+0107`&"      "&cacute;"
.row "" "&`&&ccaron;`&"  "&`U+010D`&"      "&ccaron;"
.row "" "&`&&ccedil;`&"  "&`U+00E7`&"      "&ccedil;"
.row "" "&`&&ccirc;`&"   "&`U+0109`&"      "&ccirc;"
.row "" "&`&&cdot;`&"    "&`U+0A0B`&"      "&cdot;"
.row "" "&`&&cent;`&"    "&`U+00A2`&"      "&cent;"
.row "" "&`&&check;`&"   "&`U+2713`&"      "&check;"
.row "" "&`&&clubs;`&"   "&`U+2663`&"      "&clubs;"
.row "" "&`&&copy;`&"    "&`U+00A9`&"      "&copy;"
.row "" "&`&&cross;`&"   "&`U+2717`&"      "&cross;"
.row "" "&`&&curren;`&"  "&`U+00A4`&"      "&curren;"
.row "" "&`&&dagger;`&"  "&`U+2020`&"      "&dagger;"
.row "" "&`&&darr;`&"    "&`U+2193`&"      "&darr;"
.row "" "&`&&dcaron;`&"  "&`U+010F`&"      "&dcaron;"
.row "" "&`&&deg;`&"     "&`U+00B0`&"      "&deg;"
.row "" "&`&&diams;`&"   "&`U+2666`&"      "&diams;"
.row "" "&`&&divide;`&"  "&`U+00F7`&"      "&divide;"
.row "" "&`&&dstrok;`&"  "&`U+0111`&"      "&dstrok;"
.row "" "&`&&eacute;`&"  "&`U+00E9`&"      "&eacute;"
.row "" "&`&&ecaron;`&"  "&`U+011B`&"      "&ecaron;"
.row "" "&`&&ecirc;`&"   "&`U+00EA`&"      "&ecirc;"
.row "" "&`&&edot;`&"    "&`U+0117`&"      "&edot;"
.row "" "&`&&egrave;`&"  "&`U+00E8`&"      "&egrave;"
.row "" "&`&&emacr;`&"   "&`U+0113`&"      "&emacr;"
.row "" "&`&&eng;`&"     "&`U+014B`&"      "&eng;"
.row "" "&`&&eogon;`&"   "&`U+0119`&"      "&eogon;"
.row "" "&`&&eth;`&"     "&`U+00F0`&"      "&eth;"
.row "" "&`&&euml;`&"    "&`U+00EB`&"      "&euml;"
.row "" "&`&&filig;`&"   "&`U+FB01`&"      "&filig;"
.row "" "&`&&fllig;`&"   "&`U+FB02`&"      "&fllig;"
.row "" "&`&&frac12;`&"  "&`U+00BD`&"      "&frac12;"
.row "" "&`&&frac14;`&"  "&`U+00BC`&"      "&frac14;"
.row "" "&`&&frac34;`&"  "&`U+00BE`&"      "&frac34;"
.row "" "&`&&gbreve;`&"  "&`U+011F`&"      "&gbreve;"
.row "" "&`&&gcirc;`&"   "&`U+011D`&"      "&gcirc;"
.row "" "&`&&gdot;`&"    "&`U+0121`&"      "&gdot;"
.row "" "&`&&gt;`&"      "&`U+003E`&"      "&gt;"
.row "" "&`&&half;`&"    "&`U+00BD`&"      "&half;"
.row "" "&`&&hcirc;`&"   "&`U+0125`&"      "&hcirc;"
.row "" "&`&&hearts;`&"  "&`U+2665`&"      "&hearts;"
.row "" "&`&&hellip;`&"  "&`U+2026`&"      "&hellip;"
.row "" "&`&&hstrok;`&"  "&`U+0127`&"      "&hstrok;"
.row "" "&`&&iacute;`&"  "&`U+00ED`&"      "&iacute;"
.row "" "&`&&icirc;`&"   "&`U+00EE`&"      "&icirc;"
.row "" "&`&&iexcl;`&"   "&`U+00A1`&"      "&iexcl;"
.row "" "&`&&igrave;`&"  "&`U+00EC`&"      "&igrave;"
.row "" "&`&&ijlig;`&"   "&`U+0133`&"      "&ijlig;"
.row "" "&`&&imacr;`&"   "&`U+012B`&"      "&imacr;"
.row "" "&`&&inodot;`&"  "&`U+0131`&"      "&inodot;"
.row "" "&`&&iogon;`&"   "&`U+012F`&"      "&iogon;"
.row "" "&`&&iquest;`&"  "&`U+00BF`&"      "&iquest;"
.row "" "&`&&itilde;`&"  "&`U+0129`&"      "&itilde;"
.row "" "&`&&iuml;`&"    "&`U+00EF`&"      "&iuml;"
.row "" "&`&&jcirc;`&"   "&`U+0135`&"      "&jcirc;"
.row "" "&`&&kcedil;`&"  "&`U+0137`&"      "&kcedil;"
.row "" "&`&&kgreen;`&"  "&`U+0138`&"      "&kgreen;"
.row "" "&`&&lacute;`&"  "&`U+013A`&"      "&lacute;"
.row "" "&`&&laquo;`&"   "&`U+00AB`&"      "&laquo;"
.row "" "&`&&larr;`&"    "&`U+2190`&"      "&larr;"
.row "" "&`&&lcaron;`&"  "&`U+013E`&"      "&lcaron;"
.row "" "&`&&lcedil;`&"  "&`U+013C`&"      "&lcedil;"
.row "" "&`&&ldquo;`&"   "&`U+201C`&"      "&ldquo;"
.row "" "&`&&ldquor;`&"  "&`U+201E`&"      "&ldquor;"
.row "" "&`&&lmidot;`&"  "&`U+0140`&"      "&lmidot;"
.row "" "&`&&loz;`&"     "&`U+25CA`&"      "&loz;"
.row "" "&`&&lsquo;`&"   "&`U+2018`&"      "&lsquo;"
.row "" "&`&&lsquor;`&"  "&`U+201A`&"      "&lsquor;"
.row "" "&`&&lstrok;`&"  "&`U+0142`&"      "&lstrok;"
.row "" "&`&&lt;`&"      "&`U+003C`&"      "&lt;"
.row "" "&`&&malt;`&"    "&`U+2720`&"      "&malt;"
.row "" "&`&&mdash;`&"   "&`U+2014`&"      "&mdash;"
.row "" "&`&&micro;`&"   "&`U+00B5`&"      "&micro;"
.row "" "&`&&middot;`&"  "&`U+00B7`&"      "&middot;"
.row "" "&`&&mldr;`&"    "&`U+2026`&"      "&mldr;"
.row "" "&`&&nacute;`&"  "&`U+0144`&"      "&nacute;"
.row "" "&`&&napos;`&"   "&`U+0149`&"      "&napos;"
.row "" "&`&&nbsp;`&"    "&`U+00A0`&"      "&'hard space'&"
.row "" "&`&&ncaron;`&"  "&`U+0148`&"      "&ncaron;"
.row "" "&`&&ncedil;`&"  "&`U+0146`&"      "&ncedil;"
.row "" "&`&&ndash;`&"   "&`U+2013`&"      "&ndash;"
.row "" "&`&&not;`&"     "&`U+00AC`&"      "&not;"
.row "" "&`&&ntilde;`&"  "&`U+00F1`&"      "&ntilde;"
.row "" "&`&&oacute;`&"  "&`U+00F3`&"      "&oacute;"
.row "" "&`&&ocirc;`&"   "&`U+00F4`&"      "&ocirc;"
.row "" "&`&&odblac;`&"  "&`U+0151`&"      "&odblac;"
.row "" "&`&&oelig;`&"   "&`U+0153`&"      "&oelig;"
.row "" "&`&&ograve;`&"  "&`U+00F2`&"      "&ograve;"
.row "" "&`&&omacr;`&"   "&`U+014D`&"      "&omacr;"
.row "" "&`&&ordf;`&"    "&`U+00AA`&"      "&ordf;"
.row "" "&`&&ordm;`&"    "&`U+00BA`&"      "&ordm;"
.row "" "&`&&oslash;`&"  "&`U+00F8`&"      "&oslash;"
.row "" "&`&&otilde;`&"  "&`U+00F5`&"      "&otilde;"
.row "" "&`&&ouml;`&"    "&`U+00F6`&"      "&ouml;"
.row "" "&`&&para;`&"    "&`U+00B6`&"      "&para;"
.row "" "&`&&phone;`&"   "&`U+260E`&"      "&phone;"
.row "" "&`&&plusmn;`&"  "&`U+00B1`&"      "&plusmn;"
.row "" "&`&&pound;`&"   "&`U+00A3`&"      "&pound;"
.row "" "&`&&quot;`&"    "&`U+0022`&"      "&quot;"
.row "" "&`&&racute;`&"  "&`U+0155`&"      "&racute;"
.row "" "&`&&raquo;`&"   "&`U+00BB`&"      "&raquo;"
.row "" "&`&&rarr;`&"    "&`U+2192`&"      "&rarr;"
.row "" "&`&&rcaron;`&"  "&`U+0159`&"      "&rcaron;"
.row "" "&`&&rcedil;`&"  "&`U+0157`&"      "&rcedil;"
.row "" "&`&&rdquo;`&"   "&`U+201D`&"      "&rdquo;"
.row "" "&`&&rdquor;`&"  "&`U+201D`&"      "&rdquor;" "(same as &`&&rdquo;`&)"
.row "" "&`&&reg;`&"     "&`U+00AE`&"      "&reg;"
.row "" "&`&&rsquo;`&"   "&`U+2019`&"      "&rsquo;"
.row "" "&`&&rsquor;`&"  "&`U+2019`&"      "&rsquor;" "(same as &`&&rsquo;`&)"
.row "" "&`&&sacute;`&"  "&`U+015B`&"      "&sacute;"
.row "" "&`&&scaron;`&"  "&`U+0161`&"      "&scaron;"
.row "" "&`&&scedil;`&"  "&`U+015F`&"      "&scedil;"
.row "" "&`&&scirc;`&"   "&`U+015D`&"      "&scirc;"
.row "" "&`&&sect;`&"    "&`U+00A7`&"      "&sect;"
.row "" "&`&&sext;`&"    "&`U+2736`&"      "&sext;"
.row "" "&`&&shy;`&"     "&`U+00AD`&"      "&shy;"
.row "" "&`&&spades;`&"  "&`U+2660`&"      "&spades;"
.row "" "&`&&sup1;`&"    "&`U+00B9`&"      "&sup1;"
.row "" "&`&&sup2;`&"    "&`U+00B2`&"      "&sup2;"
.row "" "&`&&sup3;`&"    "&`U+00B3`&"      "&sup3;"
.row "" "&`&&szlig;`&"   "&`U+00DF`&"      "&szlig;"
.row "" "&`&&tcaron;`&"  "&`U+0165`&"      "&tcaron;"
.row "" "&`&&tcedil;`&"  "&`U+0163`&"      "&tcedil;"
.row "" "&`&&thorn;`&"   "&`U+00FE`&"      "&thorn;"
.row "" "&`&&times;`&"   "&`U+00D7`&"      "&times;"
.row "" "&`&&trade;`&"   "&`U+2122`&"      "&trade;"
.row "" "&`&&tstrok;`&"  "&`U+0167`&"      "&tstrok;"
.row "" "&`&&uacute;`&"  "&`U+00FA`&"      "&uacute;"
.row "" "&`&&uarr;`&"    "&`U+2191`&"      "&uarr;"
.row "" "&`&&ubreve;`&"  "&`U+016D`&"      "&ubreve;"
.row "" "&`&&ucirc;`&"   "&`U+00FB`&"      "&ucirc;"
.row "" "&`&&udblac;`&"  "&`U+0171`&"      "&udblac;"
.row "" "&`&&ugrave;`&"  "&`U+00F9`&"      "&ugrave;"
.row "" "&`&&umacr;`&"   "&`U+016B`&"      "&umacr;"
.row "" "&`&&uogon;`&"   "&`U+0173`&"      "&uogon;"
.row "" "&`&&uring;`&"   "&`U+016F`&"      "&uring;"
.row "" "&`&&utilde;`&"  "&`U+0169`&"      "&utilde;"
.row "" "&`&&uuml;`&"    "&`U+00FC`&"      "&uuml;"
.row "" "&`&&wcirc;`&"   "&`U+0175`&"      "&wcirc;"
.row "" "&`&&yacute;`&"  "&`U+00FD`&"      "&yacute;"
.row "" "&`&&ycirc;`&"   "&`U+0177`&"      "&ycirc;"
.row "" "&`&&yen;`&"     "&`U+00A5`&"      "&yen;"
.row "" "&`&&yuml;`&"    "&`U+00FF`&"      "&yuml;"
.row "" "&`&&zacute;`&"  "&`U+017A`&"      "&zacute;"
.row "" "&`&&zcaron;`&"  "&`U+017E`&"      "&zcaron;"
.row "" "&`&&zdot;`&"    "&`U+017C`&"      "&zdot;"
.endtable

.index-to "ID9"


. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Supported Unicode characters" "CHAPsuppchars"
.index-from "ID10" "Unicode" "supported characters"
SDoP supports all the Unicode characters that are in the common Adobe
PostScript fonts and their compatible equivalents, plus some additional
characters from the &'Symbol'& and &'ZapfDingbats'& fonts. You do not have to
specify anything to cause SDoP to use the special fonts; they are used
automatically for characters that are not in the ordinary fonts. When it
encounters a character for which it does not have a PostScript equivalent, SDoP
prints the rarely-used `currency symbol' &#xA4;.

All printing characters in the &'C0 Controls and Basic Latin'& code page
(U+0020&--U+007E, corresponding to ASCII) and in the &'C1 Controls and Latin-1
Supplement'& code page (U+00A0&--U+00FF, corresponding to ISO 8859-1) are
supported, including `hard space' (U+00A0), `soft hyphen' (U+00AD), `break
permitted here' (U+0082), and `no break here' (U+0083). SDop also supports
`zero width space' (U+200B).

All characters in the &'Latin Extended-A'& page (U+0100&--U+017F) are also
supported. However, some of them are not in the original Adobe PostScript
fonts, but are present in later versions and in compatible equivalent fonts.
Nothing is printed for these characters in fonts that lack them:

.itable none 0 0 5 10pt left 1* left 3* left 1* left 3* left
.row "" &`U+0108`& "C with circumflex"            &`U+013F`& "L with middle dot"
.row "" &`U+0109`& "c with circumflex"            &`U+0140`& "l with middle dot"
.row "" &`U+010A`& "C with dot above"             &`U+0149`& "n with leading apostrophe"
.row "" &`U+010B`& "c with dot above"             &`U+014A`& "capital &""eng""& (N with hook)"
.row "" &`U+0114`& "E with breve"                 &`U+014B`& "lower case &""eng""& (n with hook)"
.row "" &`U+0115`& "e with breve"                 &`U+014E`& "O with breve"
.row "" &`U+011c`& "G with circumflex"            &`U+014F`& "o with breve"
.row "" &`U+011d`& "g with circumflex"            &`U+015C`& "S with circumflex"
.row "" &`U+0120`& "G with dot above"             &`U+015D`& "s with circumflex"
.row "" &`U+0121`& "g with dot above"             &`U+0162`& "T with cedilla"
.row "" &`U+0124`& "H with circumflex"            &`U+0163`& "t with cedilla"
.row "" &`U+0125`& "h with circumflex"            &`U+0166`& "T with bar"
.row "" &`U+0126`& "H with bar"                   &`U+0167`& "t with bar"
.row "" &`U+0127`& "h with bar"                   &`U+0168`& "U with tilde"
.row "" &`U+0128`& "I with tilde"                 &`U+0169`& "u with tilde"
.row "" &`U+0129`& "i with tilde"                 &`U+016C`& "U with breve"
.row "" &`U+012C`& "I with breve"                 &`U+016D`& "u with breve"
.row "" &`U+012D`& "i with breve"                 &`U+0174`& "W with circumflex"
.row "" &`U+0132`& "IJ ligature"                  &`U+0175`& "w with circumflex"
.row "" &`U+0133`& "ij ligature"                  &`U+0176`& "Y with circumflex"
.row "" &`U+0134`& "J with circumflex"            &`U+0177`& "y with circumflex"
.row "" &`U+0135`& "j with circumflex"            &`U+017F`& "long s"
.row "" &`U+0138`& "small &""kra""& (Greenlandic)"
.endtable

The following tables show all the characters that are supported by SDoP. The
first table shows those from the first three Unicode pages (U+0000&--U+017F):

.itable none 0 0 9 10pt left &&&
  1* left 1* left 1* left 1* left 1* left 1* left 1* left 1* left
.row ""  &`U+0020`& space     &`U+00B4`& &#x00B4;  &`U+00F9`& &#x00F9;  &`U+013E`& &#x013E;
.row ""  &`U+0021`& &#x0021;  &`U+00B5`& &#x00B5;  &`U+00FA`& &#x00FA;  &`U+013F`& &#x013F;
.row ""  &`U+0022`& &#x0022;  &`U+00B6`& &#x00B6;  &`U+00FB`& &#x00FB;  &`U+0140`& &#x0140;
.row ""  &`U+0023`& &#x0023;  &`U+00B7`& &#x00B7;  &`U+00FC`& &#x00FC;  &`U+0141`& &#x0141;
.row ""  &`U+0024`& &#x0024;  &`U+00B8`& &#x00B8;  &`U+00FD`& &#x00FD;  &`U+0142`& &#x0142;
.row ""  &`U+0025`& &#x0025;  &`U+00B9`& &#x00B9;  &`U+00FE`& &#x00FE;  &`U+0143`& &#x0143;
.row ""  &`U+0026`& &#x0026;  &`U+00BA`& &#x00BA;  &`U+00FF`& &#x00FF;  &`U+0144`& &#x0144;
.row ""  &`U+0027`& &#x0027;  &`U+00BB`& &#x00BB;  &`U+0100`& &#x0100;  &`U+0145`& &#x0145;
.row ""  &`U+0028`& &#x0028;  &`U+00BC`& &#x00BC;  &`U+0101`& &#x0101;  &`U+0146`& &#x0146;
.row ""  &`U+0029`& &#x0029;  &`U+00BD`& &#x00BD;  &`U+0102`& &#x0102;  &`U+0147`& &#x0147;
.row ""  &`U+002A`& &#x002A;  &`U+00BE`& &#x00BE;  &`U+0103`& &#x0103;  &`U+0148`& &#x0148;
.row ""  &`U+002B`& &#x002B;  &`U+00BF`& &#x00BF;  &`U+0104`& &#x0104;  &`U+0149`& &#x0149;
.row ""  &`U+002C`& &#x002C;  &`U+00C0`& &#x00C0;  &`U+0105`& &#x0105;  &`U+014A`& &#x014A;
.row ""  &`U+002D`& &#x002D;  &`U+00C1`& &#x00C1;  &`U+0106`& &#x0106;  &`U+014B`& &#x014B;
.row ""  &`U+002E`& &#x002E;  &`U+00C2`& &#x00C2;  &`U+0107`& &#x0107;  &`U+014C`& &#x014C;
.row ""  &`U+002F`& &#x002F;  &`U+00C3`& &#x00C3;  &`U+0108`& &#x0108;  &`U+014D`& &#x014D;
.row ""  &`U+0030`& &#x0030;  &`U+00C4`& &#x00C4;  &`U+0109`& &#x0109;  &`U+014E`& &#x014E;
.row ""  &`U+0031`& &#x0031;  &`U+00C5`& &#x00C5;  &`U+010A`& &#x010A;  &`U+014F`& &#x014F;
.row ""  &`U+0032`& &#x0032;  &`U+00C6`& &#x00C6;  &`U+010B`& &#x010B;  &`U+0150`& &#x0150;
.row ""  &`U+0033`& &#x0033;  &`U+00C7`& &#x00C7;  &`U+010C`& &#x010C;  &`U+0151`& &#x0151;
.row ""  &`U+0034`& &#x0034;  &`U+00C8`& &#x00C8;  &`U+010D`& &#x010D;  &`U+0152`& &#x0152;
.row ""  &`U+0035`& &#x0035;  &`U+00C9`& &#x00C9;  &`U+010E`& &#x010E;  &`U+0153`& &#x0153;
.row ""  &`U+0036`& &#x0036;  &`U+00CA`& &#x00CA;  &`U+010F`& &#x010F;  &`U+0154`& &#x0154;
.row ""  &`U+0037`& &#x0037;  &`U+00CB`& &#x00CB;  &`U+0110`& &#x0110;  &`U+0155`& &#x0155;
.row ""  &`U+0038`& &#x0038;  &`U+00CC`& &#x00CC;  &`U+0111`& &#x0111;  &`U+0156`& &#x0156;
.row ""  &`U+0039`& &#x0039;  &`U+00CD`& &#x00CD;  &`U+0112`& &#x0112;  &`U+0157`& &#x0157;
.row ""  &`U+003A`& &#x003A;  &`U+00CE`& &#x00CE;  &`U+0113`& &#x0113;  &`U+0158`& &#x0158;
.row ""  &`U+003B`& &#x003B;  &`U+00CF`& &#x00CF;  &`U+0114`& &#x0114;  &`U+0159`& &#x0159;
.row ""  &`U+003C`& &#x003C;  &`U+00D0`& &#x00D0;  &`U+0115`& &#x0115;  &`U+015A`& &#x015A;
.row ""  &`U+003D`& &#x003D;  &`U+00D1`& &#x00D1;  &`U+0116`& &#x0116;  &`U+015B`& &#x015B;
.row ""  &`U+003E`& &#x003E;  &`U+00D2`& &#x00D2;  &`U+0117`& &#x0117;  &`U+015C`& &#x015C;
.row ""  &`U+003F`& &#x003F;  &`U+00D3`& &#x00D3;  &`U+0118`& &#x0118;  &`U+015D`& &#x015D;
.row ""  &`U+0040`& &#x0040;  &`U+00D4`& &#x00D4;  &`U+0119`& &#x0119;  &`U+015E`& &#x015E;
.row ""  &`U+0041`& &#x0041;  &`U+00D5`& &#x00D5;  &`U+011A`& &#x011A;  &`U+015F`& &#x015F;
.row ""  &nbsp;     &#x2026;  &`U+00D6`& &#x00D6;  &`U+011B`& &#x011B;  &`U+0160`& &#x0160;
.row ""  &`U+005A`& &#x005A;  &`U+00D7`& &#x00D7;  &`U+011C`& &#x011C;  &`U+0161`& &#x0161;
.row ""  &`U+005B`& &#x005B;  &`U+00D8`& &#x00D8;  &`U+011D`& &#x011D;  &`U+0162`& &#x0162;
.row ""  &`U+005C`& &#x005C;  &`U+00D9`& &#x00D9;  &`U+011E`& &#x011E;  &`U+0163`& &#x0163;
.row ""  &`U+005D`& &#x005D;  &`U+00DA`& &#x00DA;  &`U+011F`& &#x011F;  &`U+0164`& &#x0164;
.row ""  &`U+005E`& &#x005E;  &`U+00DB`& &#x00DB;  &`U+0120`& &#x0120;  &`U+0165`& &#x0165;
.row ""  &`U+005F`& &#x005F;  &`U+00DC`& &#x00DC;  &`U+0121`& &#x0121;  &`U+0166`& &#x0166;
.row ""  &`U+0060`& &#x0060;  &`U+00DD`& &#x00DD;  &`U+0122`& &#x0122;  &`U+0167`& &#x0167;
.row ""  &`U+0061`& &#x0061;  &`U+00DE`& &#x00DE;  &`U+0123`& &#x0123;  &`U+0168`& &#x0168;
.row ""  &nbsp;     &#x2026;  &`U+00DF`& &#x00DF;  &`U+0124`& &#x0124;  &`U+0169`& &#x0169;
.row ""  &`U+007A`& &#x007A;  &`U+00E0`& &#x00E0;  &`U+0125`& &#x0125;  &`U+016A`& &#x016A;
.row ""  &`U+007B`& &#x007B;  &`U+00E1`& &#x00E1;  &`U+0126`& &#x0126;  &`U+016B`& &#x016B;
.row ""  &`U+007C`& &#x007C;  &`U+00E2`& &#x00E2;  &`U+0127`& &#x0127;  &`U+016C`& &#x016C;
.row ""  &`U+007D`& &#x007D;  &`U+00E3`& &#x00E3;  &`U+0128`& &#x0128;  &`U+016D`& &#x016D;
.row ""  &`U+007E`& &#x007E;  &`U+00E4`& &#x00E4;  &`U+0129`& &#x0129;  &`U+016E`& &#x016E;
.row ""  &`U+00A0`& space     &`U+00E5`& &#x00E5;  &`U+012A`& &#x012A;  &`U+016F`& &#x016F;
.row ""  &`U+00A1`& &#x00A1;  &`U+00E6`& &#x00E6;  &`U+012B`& &#x012B;  &`U+0170`& &#x0170;
.row ""  &`U+00A2`& &#x00A2;  &`U+00E7`& &#x00E7;  &`U+012C`& &#x012C;  &`U+0171`& &#x0171;
.row ""  &`U+00A3`& &#x00A3;  &`U+00E8`& &#x00E8;  &`U+012D`& &#x012D;  &`U+0172`& &#x0172;
.row ""  &`U+00A4`& &#x00A4;  &`U+00E9`& &#x00E9;  &`U+012E`& &#x012E;  &`U+0173`& &#x0173;
.row ""  &`U+00A5`& &#x00A5;  &`U+00EA`& &#x00EA;  &`U+012F`& &#x012F;  &`U+0174`& &#x0174;
.row ""  &`U+00A6`& &#x00A6;  &`U+00EB`& &#x00EB;  &`U+0130`& &#x0130;  &`U+0175`& &#x0175;
.row ""  &`U+00A7`& &#x00A7;  &`U+00EC`& &#x00EC;  &`U+0131`& &#x0131;  &`U+0176`& &#x0176;
.row ""  &`U+00A8`& &#x00A8;  &`U+00ED`& &#x00ED;  &`U+0132`& &#x0132;  &`U+0177`& &#x0177;
.row ""  &`U+00A9`& &#x00A9;  &`U+00EE`& &#x00EE;  &`U+0133`& &#x0133;  &`U+0178`& &#x0178;
.row ""  &`U+00AA`& &#x00AA;  &`U+00EF`& &#x00EF;  &`U+0134`& &#x0134;  &`U+0179`& &#x0179;
.row ""  &`U+00AB`& &#x00AB;  &`U+00F0`& &#x00F0;  &`U+0135`& &#x0135;  &`U+017A`& &#x017A;
.row ""  &`U+00AC`& &#x00AC;  &`U+00F1`& &#x00F1;  &`U+0136`& &#x0136;  &`U+017B`& &#x017B;
.row ""  &`U+00AD`& &#x00AD;  &`U+00F2`& &#x00F2;  &`U+0137`& &#x0137;  &`U+017C`& &#x017C;
.row ""  &`U+00AE`& &#x00AE;  &`U+00F3`& &#x00F3;  &`U+0138`& &#x0138;  &`U+017D`& &#x017D;
.row ""  &`U+00AF`& &#x00AF;  &`U+00F4`& &#x00F4;  &`U+0139`& &#x0139;  &`U+017E`& &#x017E;
.row ""  &`U+00B0`& &#x00B0;  &`U+00F5`& &#x00F5;  &`U+013A`& &#x013A;  &`U+017F`& &#x017F;
.row ""  &`U+00B1`& &#x00B1;  &`U+00F6`& &#x00F6;  &`U+013B`& &#x013B;
.row ""  &`U+00B2`& &#x00B2;  &`U+00F7`& &#x00F7;  &`U+013C`& &#x013C;
.row ""  &`U+00B3`& &#x00B3;  &`U+00F8`& &#x00F8;  &`U+013D`& &#x013D;
.endtable

The next table shows the other supported characters that are taken from the
normal PostScript fonts if possible (some older fonts lack some of these
characters). U+021A and U+021B are mapped to &'Tcommaaccent'& and
&'tcommaaccent'&, whereas U+0162 and U+0163 are mapped to &'Tcedilla'& and
&'tcedilla'&. Although Unicode specifies these as alternative glyphs, they look
the same in many fonts.

.itable none 0 0 9 10pt left &&&
  1* left 1* left 1* left 1* left 1* left 1* left 1* left 1* left
.row ""  &`U+0218`& &#x0218;  &`U+0328`& &#x0328;  &`U+2020`& &#x2020; &`U+2211`& &#x2211;
.row ""  &`U+0219`& &#x0219;  &`U+0394`& &#x0394;  &`U+2021`& &#x2021; &`U+2212`& &#x2212;
.row ""  &`U+021A`& &#x021A;  &`U+2013`& &#x2013;  &`U+2026`& &#x2026; &`U+221A`& &#x221A;
.row ""  &`U+021B`& &#x021B;  &`U+2014`& &#x2014;  &`U+2027`& &#x2027; &`U+221E`& &#x221E;
.row ""  &`U+0302`& &#x0302;  &`U+2018`& &#x2018;  &`U+2031`& &#x2031; &`U+2260`& &#x2260;
.row ""  &`U+0303`& &#x0303;  &`U+2019`& &#x2019;  &`U+2039`& &#x2039; &`U+2264`& &#x2264;
.row ""  &`U+0306`& &#x0306;  &`U+201A`& &#x201A;  &`U+203A`& &#x203A; &`U+2265`& &#x2265;
.row ""  &`U+0307`& &#x0307;  &`U+201C`& &#x201C;  &`U+2044`& &#x2044; &`U+25CA`& &#x25CA;
.row ""  &`U+030B`& &#x030B;  &`U+201D`& &#x201D;  &`U+20AC`& &#x20AC; &`U+FB01`& &#xFB01;
.row ""  &`U+0326`& &#x0326;  &`U+201E`& &#x201E;  &`U+2122`& &#x2122; &`U+FB02`& &#xFB02;
.endtable

The next table shows characters that are supported by using the &'Symbol'&
font (in some cases, only if the normal font lacks them):

.itable none 0 0 9 10pt left &&&
  1* left 1* left 1* left 1* left 1* left 1* left 1* left 1* left
.row ""  &`U+0391`& &#x0391;  &`U+03BA`& &#x03BA;  &`U+21B5`& &#x21B5;  &`U+2283`& &#x2283;
.row ""  &`U+0392`& &#x0392;  &`U+03BB`& &#x03BB;  &`U+21D0`& &#x21D0;  &`U+2284`& &#x2284;
.row ""  &`U+0393`& &#x0393;  &`U+03BC`& &#x03BC;  &`U+21D1`& &#x21D1;  &`U+2286`& &#x2286;
.row ""  &`U+0394`& &#x0394;  &`U+03BD`& &#x03BD;  &`U+21D2`& &#x21D2;  &`U+2287`& &#x2287;
.row ""  &`U+0395`& &#x0395;  &`U+03BE`& &#x03BE;  &`U+21D3`& &#x21D3;  &`U+2295`& &#x2295;
.row ""  &`U+0396`& &#x0396;  &`U+03BF`& &#x03BF;  &`U+21D4`& &#x21D4;  &`U+2297`& &#x2297;
.row ""  &`U+0397`& &#x0397;  &`U+03C0`& &#x03C0;  &`U+2200`& &#x2200;  &`U+22A5`& &#x22A5;
.row ""  &`U+0398`& &#x0398;  &`U+03C1`& &#x03C1;  &`U+2202`& &#x2202;  &`U+22C0`& &#x22C0;
.row ""  &`U+0399`& &#x0399;  &`U+03C2`& &#x03C2;  &`U+2203`& &#x2203;  &`U+22C1`& &#x22C1;
.row ""  &`U+039A`& &#x039A;  &`U+03C3`& &#x03C3;  &`U+2205`& &#x2205;  &`U+22C5`& &#x22C5;
.row ""  &`U+039B`& &#x039B;  &`U+03C4`& &#x03C4;  &`U+2207`& &#x2207;  &`U+2320`& &#x2320;
.row ""  &`U+039C`& &#x039C;  &`U+03C5`& &#x03C5;  &`U+2208`& &#x2208;  &`U+2321`& &#x2321;
.row ""  &`U+039D`& &#x039D;  &`U+03C6`& &#x03C6;  &`U+2209`& &#x2209;  &`U+2329`& &#x2329;
.row ""  &`U+039E`& &#x039E;  &`U+03C7`& &#x03C7;  &`U+220D`& &#x220D;  &`U+232A`& &#x232A;
.row ""  &`U+039F`& &#x039F;  &`U+03C8`& &#x03C8;  &`U+220F`& &#x220F;  &`U+239B`& &#x239B;
.row ""  &`U+03A0`& &#x03A0;  &`U+03C9`& &#x03C9;  &`U+2211`& &#x2211;  &`U+239C`& &#x239C;
.row ""  &`U+03A1`& &#x03A1;  &`U+03D1`& &#x03D1;  &`U+2215`& &#x2215;  &`U+239D`& &#x239D;
.row ""  &`U+03A3`& &#x03A3;  &`U+03D2`& &#x03D2;  &`U+221A`& &#x221A;  &`U+239E`& &#x239E;
.row ""  &`U+03A4`& &#x03A4;  &`U+03D5`& &#x03D5;  &`U+221D`& &#x221D;  &`U+239F`& &#x239F;
.row ""  &`U+03A5`& &#x03A5;  &`U+03D6`& &#x03D6;  &`U+221E`& &#x221E;  &`U+23A0`& &#x23A0;
.row ""  &`U+03A6`& &#x03A6;  &`U+12AA`& &#x12AA;  &`U+2220`& &#x2220;  &`U+23A1`& &#x23A1;
.row ""  &`U+03A7`& &#x03A7;  &`U+2032`& &#x2032;  &`U+2229`& &#x2229;  &`U+23A2`& &#x23A2;
.row ""  &`U+03A8`& &#x03A8;  &`U+2033`& &#x2033;  &`U+222A`& &#x222A;  &`U+23A3`& &#x23A3;
.row ""  &`U+03A9`& &#x03A9;  &`U+20AC`& &#x20AC;  &`U+222B`& &#x222B;  &`U+23A4`& &#x23A4;
.row ""  &`U+03B1`& &#x03B1;  &`U+2111`& &#x2111;  &`U+2234`& &#x2234;  &`U+23A5`& &#x23A5;
.row ""  &`U+03B2`& &#x03B2;  &`U+2118`& &#x2118;  &`U+223C`& &#x223C;  &`U+23A6`& &#x23A6;
.row ""  &`U+03B3`& &#x03B3;  &`U+211C`& &#x211C;  &`U+2245`& &#x2245;  &`U+23A7`& &#x23A7;
.row ""  &`U+03B4`& &#x03B4;  &`U+2135`& &#x2135;  &`U+2248`& &#x2248;  &`U+23A8`& &#x23A8;
.row ""  &`U+03B5`& &#x03B5;  &`U+2190`& &#x2190;  &`U+2260`& &#x2260;  &`U+23A9`& &#x23A9;
.row ""  &`U+03B6`& &#x03B6;  &`U+2191`& &#x2191;  &`U+2261`& &#x2261;  &`U+23AB`& &#x23AB;
.row ""  &`U+03B7`& &#x03B7;  &`U+2192`& &#x2192;  &`U+2264`& &#x2264;  &`U+23AC`& &#x23AC;
.row ""  &`U+03B8`& &#x03B8;  &`U+2193`& &#x2193;  &`U+2265`& &#x2265;  &`U+23AD`& &#x23AD;
.row ""  &`U+03B9`& &#x03B9;  &`U+2194`& &#x2194;  &`U+2282`& &#x2282;  &`U+23AE`& &#x23AE;
.endtable

The final table shows characters that are supported by using the
&'ZapfDingbats'& font:

.itable none 0 0 9 10pt left &&&
  1* left 1* left 1* left 1* left 1* left 1* left 1* left 1* left
.row ""  &`U+25A0`& &#x25A0;  &`U+2722`& &#x2722;  &`U+2751`& &#x2751;  &`U+2791`& &#x2791;
.row ""  &`U+25B2`& &#x25B2;  &`U+2723`& &#x2723;  &`U+2752`& &#x2752;  &`U+2792`& &#x2792;
.row ""  &`U+25BC`& &#x25BC;  &`U+2724`& &#x2724;  &`U+2756`& &#x2756;  &`U+2793`& &#x2793;
.row ""  &`U+25C6`& &#x25C6;  &`U+2725`& &#x2725;  &`U+2758`& &#x2758;  &`U+2794`& &#x2794;
.row ""  &`U+25CA`& &#x25CA;  &`U+2726`& &#x2726;  &`U+2759`& &#x2759;  &`U+2798`& &#x2798;
.row ""  &`U+25D7`& &#x25D7;  &`U+2727`& &#x2727;  &`U+275A`& &#x275A;  &`U+2799`& &#x2799;
.row ""  &`U+260E`& &#x260E;  &`U+2729`& &#x2729;  &`U+275B`& &#x275B;  &`U+279A`& &#x279A;
.row ""  &`U+261B`& &#x261B;  &`U+272A`& &#x272A;  &`U+275C`& &#x275C;  &`U+279B`& &#x279B;
.row ""  &`U+261E`& &#x261E;  &`U+272B`& &#x272B;  &`U+275D`& &#x275D;  &`U+279C`& &#x279C;
.row ""  &`U+2660`& &#x2660;  &`U+272C`& &#x272C;  &`U+275E`& &#x275E;  &`U+279D`& &#x279D;
.row ""  &`U+2663`& &#x2663;  &`U+272D`& &#x272D;  &`U+2761`& &#x2761;  &`U+279E`& &#x279E;
.row ""  &`U+2665`& &#x2665;  &`U+272E`& &#x272E;  &`U+2762`& &#x2762;  &`U+279F`& &#x279F;
.row ""  &`U+2666`& &#x2666;  &`U+272F`& &#x272F;  &`U+2763`& &#x2763;  &`U+27A0`& &#x27A0;
.row ""  &`U+26AB`& &#x26AB;  &`U+2730`& &#x2730;  &`U+2764`& &#x2764;  &`U+27A1`& &#x27A1;
.row ""  &`U+2701`& &#x2701;  &`U+2731`& &#x2731;  &`U+2765`& &#x2765;  &`U+27A2`& &#x27A2;
.row ""  &`U+2702`& &#x2702;  &`U+2732`& &#x2732;  &`U+2766`& &#x2766;  &`U+27A3`& &#x27A3;
.row ""  &`U+2703`& &#x2703;  &`U+2733`& &#x2733;  &`U+2767`& &#x2767;  &`U+27A4`& &#x27A4;
.row ""  &`U+2704`& &#x2704;  &`U+2734`& &#x2734;  &`U+2776`& &#x2776;  &`U+27A5`& &#x27A5;
.row ""  &`U+2706`& &#x2706;  &`U+2735`& &#x2735;  &`U+2777`& &#x2777;  &`U+27A6`& &#x27A6;
.row ""  &`U+2707`& &#x2707;  &`U+2736`& &#x2736;  &`U+2778`& &#x2778;  &`U+27A7`& &#x27A7;
.row ""  &`U+2708`& &#x2708;  &`U+2737`& &#x2737;  &`U+2779`& &#x2779;  &`U+27A8`& &#x27A8;
.row ""  &`U+2709`& &#x2709;  &`U+2738`& &#x2738;  &`U+277A`& &#x277A;  &`U+27A9`& &#x27A9;
.row ""  &`U+270C`& &#x270C;  &`U+2739`& &#x2739;  &`U+277B`& &#x277B;  &`U+27AA`& &#x27AA;
.row ""  &`U+270D`& &#x270D;  &`U+273A`& &#x273A;  &`U+277C`& &#x277C;  &`U+27AB`& &#x27AB;
.row ""  &`U+270E`& &#x270E;  &`U+273B`& &#x273B;  &`U+277D`& &#x277D;  &`U+27AC`& &#x27AC;
.row ""  &`U+270F`& &#x270F;  &`U+273C`& &#x273C;  &`U+277E`& &#x277E;  &`U+27AD`& &#x27AD;
.row ""  &`U+2710`& &#x2710;  &`U+273D`& &#x273D;  &`U+277F`& &#x277F;  &`U+27AE`& &#x27AE;
.row ""  &`U+2711`& &#x2711;  &`U+273E`& &#x273E;  &`U+2780`& &#x2780;  &`U+27AF`& &#x27AF;
.row ""  &`U+2712`& &#x2712;  &`U+273F`& &#x273F;  &`U+2781`& &#x2781;  &`U+27B1`& &#x27B1;
.row ""  &`U+2713`& &#x2713;  &`U+2740`& &#x2740;  &`U+2782`& &#x2782;  &`U+27B2`& &#x27B2;
.row ""  &`U+2714`& &#x2714;  &`U+2741`& &#x2741;  &`U+2783`& &#x2783;  &`U+27B3`& &#x27B3;
.row ""  &`U+2715`& &#x2715;  &`U+2742`& &#x2742;  &`U+2784`& &#x2784;  &`U+27B4`& &#x27B4;
.row ""  &`U+2716`& &#x2716;  &`U+2743`& &#x2743;  &`U+2785`& &#x2785;  &`U+27B5`& &#x27B5;
.row ""  &`U+2717`& &#x2717;  &`U+2744`& &#x2744;  &`U+2786`& &#x2786;  &`U+27B6`& &#x27B6;
.row ""  &`U+2718`& &#x2718;  &`U+2745`& &#x2745;  &`U+2787`& &#x2787;  &`U+27B7`& &#x27B7;
.row ""  &`U+2719`& &#x2719;  &`U+2746`& &#x2746;  &`U+2788`& &#x2788;  &`U+27B8`& &#x27B8;
.row ""  &`U+271A`& &#x271A;  &`U+2747`& &#x2747;  &`U+2789`& &#x2789;  &`U+27B9`& &#x27B9;
.row ""  &`U+271B`& &#x271B;  &`U+2748`& &#x2748;  &`U+278A`& &#x278A;  &`U+27BA`& &#x27BA;
.row ""  &`U+271C`& &#x271C;  &`U+2749`& &#x2749;  &`U+278B`& &#x278B;  &`U+27BB`& &#x27BB;
.row ""  &`U+271D`& &#x271D;  &`U+274A`& &#x274A;  &`U+278C`& &#x278C;  &`U+27BC`& &#x27BC;
.row ""  &`U+271E`& &#x271E;  &`U+274B`& &#x274B;  &`U+278D`& &#x278D;  &`U+27BD`& &#x27BD;
.row ""  &`U+271F`& &#x271F;  &`U+274D`& &#x274D;  &`U+278E`& &#x278E;  &`U+27BE`& &#x27BE;
.row ""  &`U+2720`& &#x2720;  &`U+274F`& &#x274F;  &`U+278F`& &#x278F;
.row ""  &`U+2721`& &#x2721;  &`U+2750`& &#x2750;  &`U+2790`& &#x2790;
.endtable

.index-to "ID10"


. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////

.chapter "Maintaining the hyphenation dictionary" "CHAPmainhydic" &&&
         "Hyphenation dictionary"
.index "hyphenation" "dictionary maintenance"
SDoP is distributed with a British English hyphenation dictionary in a file
called &_HyphenData_&. This is installed with the other SDoP data files (often
in &_/usr/local/share/sdop/_&). The distribution also contains tools that
enable you to modify this dictionary, or create entirely different
dictionaries. These tools are not installed as user commands &-- they are built
by `make', but remain in the build &_src_& directory.

The &(buildhy)& program reads a file of hyphenated words and adds indexing
information on the front so that SDoP can then use it as a hyphenation
dictionary. Use it like this:
.display
&`buildhy`& <&'inputfile'&> <&'outputfile'&>
.endd
The input file is a list of words, one per line, in alphabetical order (not
counting the hyphens in the sort). The list that is used to create the
distributed dictionary is supplied in the file &_hyphenlist_&. It starts like
this:
.code
aba-cus
aba-lone
aban-don
aban-doned
aban-doner
aban-don-ment
abase-ment
.endd
The index that is added to the start of the output file (which is otherwise a
copy of the input) is in the form of four-letter entries with the offset of the
relevant point in the dictionary in digits after them. The total number of
entries in the index is output on the first line. The distributed dictionary
starts like this:
.code
1541
abdi148
abdu225
abid309
abol413
abor528
abra576
.endd
You can test a newly-built dictionary using the &(hytest)& program:
.display
&`hytest`& <&'new dictionary'&> [<&'input file'&> [<&'output file'&>]]
.endd
If no input (output) file is given, the standard input (output) is used.
A good test for a new dictionary is to take the input that you originally gave
to &(buildhy)&, remove all the hyphens, feed it to &(hytest)& and check that
you get back the original, hyphenated file. If you do not, the most likely
cause is that the input file is not in the correct alphabetic order.


. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////


. /////////////////////////////////////////////////////////////////////////////
. These literal XML lines are processing instructions for SDoP. Show only the
. title in page footers for the index.
. /////////////////////////////////////////////////////////////////////////////

.literal xml
<?sdop
  format="newpage"
  foot_right_recto="&chaptertitle;"
  foot_right_verso="&chaptertitle;"
?>
.literal off


. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////

.makeindex "Index"

. /////////////////////////////////////////////////////////////////////////////
. /////////////////////////////////////////////////////////////////////////////