Notes About Documentation Formatting

This manual is written in docbook. The PDF version of the manual
was generated with Apache fop, which as of this writing, is still
incomplete. There are a few known issues with the PDF version of
the documentation. Hopefully these issues will all be addressed as
fop matures.

There are many bad line breaks. Sometimes words are incorrectly
hyphenated, and line breaks also occur between two dashes in
command line options and even between the two
+ characters of “C++”.

In many of the example listings, there are lines that would be
longer than the shaded boxes in the PDF output. We wrap those
lines and place a backslash (\) character
just before and after the extra line breaks. This is done for
both the HTML and the PDF output even though the long lines are
only a problem for the PDF output.

Some paragraphs appear to have extra indentation. This is
because the formatting software generates a hard space whenever
we have an index term marker in the text.

There are no bookmarks. It would be good if we could create
bookmarks to the chapter headings, but as of this writing, the
documented procedure for doing this does not appear to work.