Fix missing docs for \cfg{paper-contents-indent-step} and
[sgt/halibut] / doc / output.but
index 89eca4e..49a6b05 100644 (file)
@@ -1,3 +1,5 @@
+\versionid $Id$
+
 \C{output} Halibut output formats
 
 This chapter describes each of Halibut's current \i{output formats}.
 \C{output} Halibut output formats
 
 This chapter describes each of Halibut's current \i{output formats}.
@@ -8,12 +10,7 @@ that format.
 \H{output-text} Plain text
 
 This output format generates the document as a single \i{plain text}
 \H{output-text} Plain text
 
 This output format generates the document as a single \i{plain text}
-file.
-
-The output file is currently assumed to be in the \i{ISO 8859-1}
-character set. Any Unicode characters representable in this set will
-be output verbatim; any other characters will not be output and
-their \i{fallback text} (if any) will be used instead.
+file. No table of contents or index is generated.
 
 The precise formatting of the text file can be controlled by a
 variety of configuration directives. They are listed in the
 
 The precise formatting of the text file can be controlled by a
 variety of configuration directives. They are listed in the
@@ -107,18 +104,24 @@ left of that (so that it goes in the margin if there is room).
 
 Also, several of the directives below specify how a title should be
 \I{underlining}underlined. The parameter to one of these directives
 
 Also, several of the directives below specify how a title should be
 \I{underlining}underlined. The parameter to one of these directives
-should be either blank (\cw{\{\}}) or a single character. In the
-latter case, that character will be used to underline the title. So
-you might want to specify, for example,
-\cw{\\text-title-underline\{=\}} but
-\cw{\\text-chapter-underline\{-\}}.
+should be either blank (\cw{\{\}}) or a piece of text which will be
+repeated to produce the underline. So you might want to specify, for
+example, \cw{\\text-title-underline\{=\}} but
+\cw{\\text-chapter-underline\{\-\}}.
+
+You can also specify more than one underline setting, and Halibut
+will choose the first one that the output character set supports.
+So, for example, you could write
+\cw{\\text-chapter-underline\{\\u203e\}\{\-\}}, and Halibut would use
+the Unicode \q{OVERLINE} character where possible and fall back to
+the ASCII minus sign otherwise.
 
 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
 
 \dd Specifies the alignment of the overall document title: \c{left},
 \c{leftplus} or \c{centre}.
 
 
 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
 
 \dd Specifies the alignment of the overall document title: \c{left},
 \c{leftplus} or \c{centre}.
 
-\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how the overall document title should be underlined.
 
 
 \dd Specifies how the overall document title should be underlined.
 
@@ -126,7 +129,7 @@ you might want to specify, for example,
 
 \dd Specifies the alignment of chapter and appendix headings.
 
 
 \dd Specifies the alignment of chapter and appendix headings.
 
-\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how chapter and appendix headings should be underlined.
 
 
 \dd Specifies how chapter and appendix headings should be underlined.
 
@@ -139,11 +142,19 @@ they will just contain the chapter \e{number}, followed by the
 chapter title. If you set this to \c{false}, chapter headings will
 be prefixed by \q{Chapter} or equivalent.
 
 chapter title. If you set this to \c{false}, chapter headings will
 be prefixed by \q{Chapter} or equivalent.
 
+\dt \I{\cw{\\cfg\{text-chapter-shownumber\}}}\cw{\\cfg\{text-chapter-shownumber\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then chapter headings will \e{only}
+contain the chapter title: they will not contain the word
+\q{Chapter} (or whatever other word you have defined in its place),
+and neither will they contain the chapter number. If set to
+\c{false}, this overrides \cw{\\cfg\{text-chapter-numeric\}}.
+
 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
-this to \q{\cw{:\_}}, then the chapter title might look something
+this to \cq{:\_}, then the chapter title might look something
 like \q{Chapter 2: Doing Things}.
 
 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
 like \q{Chapter 2: Doing Things}.
 
 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
@@ -155,7 +166,7 @@ headings you want to affect: 0 means first-level headings (\c{\\H}),
 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
 just like the other alignment directives listed above.
 
 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
 just like the other alignment directives listed above.
 
-\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how to underline section headings at a particular level.
 
 
 \dd Specifies how to underline section headings at a particular level.
 
@@ -165,28 +176,119 @@ just like the other alignment directives listed above.
 contain the word \q{Section} or equivalent (if \c{false}), or should
 be numeric only (if \c{true}).
 
 contain the word \q{Section} or equivalent (if \c{false}), or should
 be numeric only (if \c{true}).
 
+\dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then section headings at the
+specified level will \e{only} contain the section title: they will
+not contain the word \q{Section} (or whatever other word you have
+defined in its place), and neither will they contain the section
+number. If set to \c{false}, this overrides
+\cw{\\cfg\{text-section-numeric\}}.
+
 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
 
 \dd Specifies the \I{suffix text, in section titles}suffix text to
 be appended to section numbers at a particular level, before
 displaying the section title.
 
 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
 
 \dd Specifies the \I{suffix text, in section titles}suffix text to
 be appended to section numbers at a particular level, before
 displaying the section title.
 
-\S{output-text-misc} Miscellaneous configuration options
+\S{output-text-characters} Configuring the characters used
 
 
-\dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
+\dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}}
 
 
-\dd If this is set to \c{true}, \i{version ID paragraphs} (defined
-using the \i\c{\\versionid} command - see \k{input-blurb}) will be
-included at the bottom of the text file. If it is set to \c{false},
-they will be omitted completely.
+\dd This tells Halibut what \i{character set} the output should be
+in. Any Unicode characters representable in this set will be output
+verbatim; any other characters will not be output and their
+\i{fallback text} (if any) will be used instead.
+
+\lcont{
 
 
-\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}
+The character set names are the same as for
+\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
+\cw{\\cfg\{input-charset\}}, this directive affects the \e{entire}
+output; it's not possible to switch encodings halfway through.
+
+}
+
+\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
 
 \dd This specifies the text which should be used as the \i{bullet}
 in bulletted lists. It can be one character
 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
 
 
 \dd This specifies the text which should be used as the \i{bullet}
 in bulletted lists. It can be one character
 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
 
+\lcont{
+
+Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple
+possible options after this command, and Halibut will choose the first one
+which the output character set supports. For example, you might write
+\cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case
+Halibut would use the Unicode \q{BULLET} character where possible,
+fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available,
+and resort to the ASCII asterisk if all else failed.
+
+}
+
+\dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
+
+\dd This specifies the text which should be used for drawing
+\i{horizontal rules} (generated by \i\c{\\rule}; see
+\k{input-rule}). It can be one character, or more than one. The
+string you specify will be repeated to reach the required width, so
+you can specify something like \cq{-=} to get a rule that looks
+like \cw{-=-=-=}.
+
+\lcont{
+
+Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback
+options in this command.
+
+}
+
+\dt \I{\cw{\\cfg\{text-quotes\}}}\cw{\\cfg\{text-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd This specifies a set of quote characters for the text backend,
+overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax
+(see \k{input-config}).
+
+\lcont{
+
+In this backend, these quotes will also be used to mark text enclosed
+in the \c{\\c} command (see \k{input-code}).
+
+}
+
+\dt \I{\cw{\\cfg\{text-emphasis\}}}\cw{\\cfg\{text-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}]
+
+\dd This specifies the characters which should be used to surround
+emphasised text (written using the \c{\\e} command; see
+\k{input-emph}).
+
+\lcont{
+
+You should separately specify the start-emphasis and end-emphasis
+text, each of which can be more than one character if you want.
+Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs
+of fallback options in this command, and Halibut will always use a
+matching pair.
+
+}
+
+\S{output-text-misc} Miscellaneous configuration options
+
+\dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}}
+
+\dd This text is appended to the number on a \i{numbered list} item
+(see \k{input-list-number}). So if you want to label your lists as
+\q{1)}, \q{2)} and so on, then you would write
+\cw{\\cfg\{text-list-suffix\}\{)\}}.
+
+\dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{true}, \i{version ID paragraphs} (defined
+using the \i\c{\\versionid} command - see \k{input-blurb}) will be
+included at the bottom of the text file. If it is set to \c{false},
+they will be omitted completely.
+
 \# FIXME: code indentation is configurable, therefore \quote
 \# indentation probably ought to be as well.
 
 \# FIXME: code indentation is configurable, therefore \quote
 \# indentation probably ought to be as well.
 
@@ -206,25 +308,37 @@ The \i{default settings} for Halibut's plain text output format are:
 \c \cfg{text-indent-preamble}{false}
 \c
 \c \cfg{text-title-align}{centre}
 \c \cfg{text-indent-preamble}{false}
 \c
 \c \cfg{text-title-align}{centre}
-\c \cfg{text-title-underline}{=}
+\c \cfg{text-title-underline}{\u2550}{=}
 \c
 \c \cfg{text-chapter-align}{left}
 \c
 \c \cfg{text-chapter-align}{left}
-\c \cfg{text-chapter-underline}{-}
+\c \cfg{text-chapter-underline}{\u203e}{-}
 \c \cfg{text-chapter-numeric}{false}
 \c \cfg{text-chapter-numeric}{false}
+\c \cfg{text-chapter-shownumber}{true}
 \c \cfg{text-chapter-suffix}{: }
 \c
 \c \cfg{text-section-align}{0}{leftplus}
 \c \cfg{text-section-underline}{0}{}
 \c \cfg{text-section-numeric}{0}{true}
 \c \cfg{text-chapter-suffix}{: }
 \c
 \c \cfg{text-section-align}{0}{leftplus}
 \c \cfg{text-section-underline}{0}{}
 \c \cfg{text-section-numeric}{0}{true}
+\c \cfg{text-section-shownumber}{0}{true}
 \c \cfg{text-section-suffix}{0}{ }
 \c
 \c \cfg{text-section-align}{1}{leftplus}
 \c \cfg{text-section-underline}{1}{}
 \c \cfg{text-section-numeric}{1}{true}
 \c \cfg{text-section-suffix}{0}{ }
 \c
 \c \cfg{text-section-align}{1}{leftplus}
 \c \cfg{text-section-underline}{1}{}
 \c \cfg{text-section-numeric}{1}{true}
+\c \cfg{text-section-shownumber}{1}{true}
 \c \cfg{text-section-suffix}{1}{ }
 \c
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
 \c \cfg{text-section-suffix}{1}{ }
 \c
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{text-charset}{ASCII}
+\c \cfg{text-bullet}{\u2022}{-}
+\c \cfg{text-rule}{\u2500}{-}
+\c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
+\c \cfg{text-emphasis}{_}{_}
+\c
+\c \cfg{text-list-suffix}{.}
+\c \cfg{text-versionid}{true}
 
 \H{output-html} HTML
 
 
 \H{output-html} HTML
 
@@ -236,25 +350,24 @@ between HTML files using the configuration commands described in
 this section. In particular, you can configure Halibut to output one
 single HTML file instead of multiple ones.
 
 this section. In particular, you can configure Halibut to output one
 single HTML file instead of multiple ones.
 
-Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
-which is why all of the configuration directives start with the word
-\c{xhtml} rather than \c{html}.
+\I{\cw{\\cfg\{xhtml-anything\}}}Configuration directives with an
+\c{xhtml-} prefix are synonyms for those with an \c{html-} prefix.
 
 \S{output-html-file} Controlling the output file names
 
 
 \S{output-html-file} Controlling the output file names
 
-\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-filename\}}}\cw{\\cfg\{html-contents-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the \i{output file name} in which to store the top-level
 contents page. Since this is the first page a user ought to see when
 beginning to read the document, a good choice in many cases might be
 
 \dd Sets the \i{output file name} in which to store the top-level
 contents page. Since this is the first page a user ought to see when
 beginning to read the document, a good choice in many cases might be
-\c{index.html} (but this is not the default, for historical
+\c{index.html} (although this is not the default, for historical
 reasons).
 
 reasons).
 
-\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the file name in which to store the document's index.
 
 
 \dd Sets the file name in which to store the document's index.
 
-\dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
+\dt \I{\cw{\\cfg\{html-template-filename\}}}\cw{\\cfg\{html-template-filename\}\{}\e{template}\cw{\}}
 
 \dd Provides a \i{template} to be used when constructing the file
 names of each chapter or section of the document. This template
 
 \dd Provides a \i{template} to be used when constructing the file
 names of each chapter or section of the document. This template
@@ -266,50 +379,51 @@ cent sign, you can write \c{%%}.)
 
 The formatting commands used in this template are:
 
 
 The formatting commands used in this template are:
 
-\dt \i\c{%N}
+\dt \I{%N-upper}\c{%N}
 
 \dd Expands to the visible title of the section, with white space
 
 \dd Expands to the visible title of the section, with white space
-removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
-Fish}}, this formatting command would expand to
-\q{\cw{CatchingFish}}.
+removed. So in a chapter declared as \cq{\\C\{fish\} Catching
+Fish}, this formatting command would expand to
+\cq{CatchingFish}.
 
 \dt \i\c{%n}
 
 \dd Expands to the type and number of the section, without white
 
 \dt \i\c{%n}
 
 \dd Expands to the type and number of the section, without white
-space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
-section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
+space. So in chapter 1 this would expand to \cq{Chapter1}; in
+section A.4.3 it would expand to \cq{SectionA.4.3}, and so on.
 If the section has no number (an unnumbered chapter created using
 \c{\\U}), this directive falls back to doing the same thing as
 \c{%N}.
 
 \dt \i\c{%b}
 
 If the section has no number (an unnumbered chapter created using
 \c{\\U}), this directive falls back to doing the same thing as
 \c{%N}.
 
 \dt \i\c{%b}
 
-\dd Expands to the bare number of the section. So in chapter 1 this
-would expand to \q{\cw{1}}; in section A.4.3 it would expand to
-\q{\cw{A.4.3}}, and so on. If the section has no number (an
-unnumbered chapter created using \c{\\U}), this directive falls back
-to doing the same thing as \c{%N}.
+\dd Expands to the number of the section, in a format suitable for an
+HTML fragment name. The first character of the section type is
+prepended to the section number. So in chapter 1 this would expand to
+\cq{C1}; in section A.4.3 it would expand to \cq{SA.4.3}, and so on.
+If the section has no number (an unnumbered chapter created using
+\c{\\U}), this directive falls back to doing the same thing as \c{%N}.
 
 \dt \i\c{%k}
 
 \dd Expands to the internal keyword specified in the section title.
 
 \dt \i\c{%k}
 
 \dd Expands to the internal keyword specified in the section title.
-So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
-formatting command would expand to \q{\cw{fish}}. If the section has
+So in a chapter declared as \cq{\\C\{fish\} Catching Fish}, this
+formatting command would expand to \cq{fish}. If the section has
 no keyword (an unnumbered chapter created using \c{\\U}), this
 directive falls back to doing the same thing as \c{%N}.
 
 These formatting directives can also be used in the
 no keyword (an unnumbered chapter created using \c{\\U}), this
 directive falls back to doing the same thing as \c{%N}.
 
 These formatting directives can also be used in the
-\cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
+\cw{\\cfg\{html-template-fragment\}} configuration directive (see
 \k{output-html-misc}).
 
 }
 
 \k{output-html-misc}).
 
 }
 
-\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-single-filename\}}}\cw{\\cfg\{html-single-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the file name in which to store the entire document, if
 
 \dd Sets the file name in which to store the entire document, if
-Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
+Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to
 produce a single self-contained file. Both this directive \e{and}
 produce a single self-contained file. Both this directive \e{and}
-\c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
+\c{\\cfg\{html-leaf-level\}\{0\}} are implicitly generated if you
 provide a file name parameter after the command-line option
 \i\c{--html} (see \k{running-options}).
 
 provide a file name parameter after the command-line option
 \i\c{--html} (see \k{running-options}).
 
@@ -326,7 +440,7 @@ sections in the file and/or the sections below it.
 The configuration directives listed below allow you to configure the
 splitting into files, and the details of the contents sections.
 
 The configuration directives listed below allow you to configure the
 splitting into files, and the details of the contents sections.
 
-\dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-level\}}}\cw{\\cfg\{html-leaf-level\}\{}\e{depth}\cw{\}}
 
 \dd This setting indicates the depth of section which should be
 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
 
 \dd This setting indicates the depth of section which should be
 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
@@ -340,7 +454,7 @@ file, and the chapter files will mostly just contain links to their
 
 If you set this option to zero, then the whole document will appear
 in a single file. If you do this, Halibut will call that file
 
 If you set this option to zero, then the whole document will appear
 in a single file. If you do this, Halibut will call that file
-\i\c{Manual.html} instead of \i\c{Contents.html}.
+\i\c{Manual.html} instead of \i\c{Contents.html} by default.
 
 This option is automatically set to zero if you provide a file name
 parameter after the command-line option \i\c{--html} (see
 
 This option is automatically set to zero if you provide a file name
 parameter after the command-line option \i\c{--html} (see
@@ -348,12 +462,17 @@ parameter after the command-line option \i\c{--html} (see
 and so Halibut assumes you want the whole document to be placed in
 that file.
 
 and so Halibut assumes you want the whole document to be placed in
 that file.
 
+You can also specify the special name \c{infinity} (or \c{infinite}
+or \c{inf}) if you want to ensure that \e{every} section and
+subsection ends up in a separate file no matter how deep you go.
+
 }
 
 }
 
-\dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}}
 
 \dd This directive allows you to specify how \I{depth of
 
 \dd This directive allows you to specify how \I{depth of
-contents}deep the contents section in a particular file should go.
+contents}deep any contents section in a particular level of file
+should go.
 
 \lcont{
 
 
 \lcont{
 
@@ -361,29 +480,28 @@ The \e{level} parameter indicates which level of contents section
 you are dealing with. 0 denotes the main contents section in the
 topmost file \c{Contents.html}; 1 denotes a contents section in a
 chapter file; 2 is a contents section in a file containing a \c{\\H}
 you are dealing with. 0 denotes the main contents section in the
 topmost file \c{Contents.html}; 1 denotes a contents section in a
 chapter file; 2 is a contents section in a file containing a \c{\\H}
-heading, and so on. Currently you can't go below level 5 (which
-corresponds to a \c{\\S3} heading).
+heading, and so on.
 
 The \e{depth} parameter indicates the maximum depth of heading which
 will be shown in this contents section. Again, 1 denotes a chapter,
 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
 
 
 The \e{depth} parameter indicates the maximum depth of heading which
 will be shown in this contents section. Again, 1 denotes a chapter,
 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
 
-So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
+So, for example: \cw{\\cfg\{html-contents-depth\}\{1\}\{3\}} instructs
 Halibut to put contents links in chapter files for all sections down
 to \c{\\S} level, but not to go into any more detail than that.
 
 Halibut to put contents links in chapter files for all sections down
 to \c{\\S} level, but not to go into any more detail than that.
 
-}
+For backwards compatibility, the alternative syntax
+\cw{\\cfg\{html-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+is also supported.
 
 
-\# FIXME: this is utterly ghastly. For a start, it should include
-\# the level as a separate argument, like the text section config
-\# directives. Secondly, it shouldn't be limited in depth!
+}
 
 
-\dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-contains-contents\}}}\cw{\\cfg\{html-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
 
 \dd If you set this to \c{true}, then each leaf file will contain
 its own contents section which summarises the text within it.
 
 
 \dd If you set this to \c{true}, then each leaf file will contain
 its own contents section which summarises the text within it.
 
-\dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-smallest-contents\}}}\cw{\\cfg\{html-leaf-smallest-contents\}\{}\e{number}\cw{\}}
 
 \dd Contents sections in leaf files are not output at all if they
 contain very few entries (on the assumption that it just isn't worth
 
 \dd Contents sections in leaf files are not output at all if they
 contain very few entries (on the assumption that it just isn't worth
@@ -397,20 +515,47 @@ The directives in this section allow you to supply pieces of
 \I{HTML}\i{verbatim HTML} code, which will be included in various
 parts of the output files.
 
 \I{HTML}\i{verbatim HTML} code, which will be included in various
 parts of the output files.
 
-\dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
+Note that none of Halibut's usual character set translation is applied
+to this code; it is assumed to already be in a suitable encoding for
+the target HTML files.
+
+\dt \I{\cw{\\cfg\{html-head-end\}}}\cw{\\cfg\{html-head-end\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the end of
 the \i\cw{<HEAD>} section of each output HTML file. So this is a
 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
 
 
 \dd The text you provide in this directive is placed at the end of
 the \i\cw{<HEAD>} section of each output HTML file. So this is a
 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
 
-\dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-local-head\}}}\cw{\\cfg\{html-local-head\}\{}\e{HTML text}\cw{\}}
+
+\dd This configuration directive is local: you specify it within a
+document section, and it acts on that section only.
+
+\lcont{
+
+The text you provide in this directive is placed at the end of the
+\i\cw{<HEAD>} section of whichever output HTML file contains the
+section in which the directive was placed. You can specify this
+directive multiple times in multiple sections if you like.
+
+This directive is particularly useful for constructing \i{MacOS
+on-line help}, which is mostly normal HTML but which requires a
+special \i\cw{<META NAME="AppleTitle">} tag in the topmost source
+file. You can arrange this by placing this configuration directive
+in the preamble or the introduction section, something like this:
+
+\c \cfg{html-local-head}{<meta name="AppleTitle"
+\c content="MyApp Help">}
+
+}
+
+\dt \I{\cw{\\cfg\{html-body-tag\}}}\cw{\\cfg\{html-body-tag\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is used in place of the
 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
 \i{background colour}, for example, you could write
 
 \dd The text you provide in this directive is used in place of the
 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
 \i{background colour}, for example, you could write
-\cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
+\cw{\\cfg\{html-body-tag\}\{<body bg="#123456">\}}.
 
 
-\dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-start\}}}\cw{\\cfg\{html-body-start\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the
 beginning of the \i\cw{<BODY>} section of each output HTML file. So
 
 \dd The text you provide in this directive is placed at the
 beginning of the \i\cw{<BODY>} section of each output HTML file. So
@@ -418,41 +563,41 @@ if you intend your HTML files to be part of a web site with a
 standard \i{house style}, and the style needs a \i{header} at the
 top of every page, this is where you can add that header.
 
 standard \i{house style}, and the style needs a \i{header} at the
 top of every page, this is where you can add that header.
 
-\dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-end\}}}\cw{\\cfg\{html-body-end\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the end of
 
 \dd The text you provide in this directive is placed at the end of
-the \i\cw{<BODY>} section of each output HTML file. So if you intend
-your HTML files to be part of a web site with a standard \i{house
-style}, and the style needs a \i{footer} at the bottom of every
-page, this is where you can add that footer.
+the \i\cw{<BODY>} section of each output HTML file, before any address
+section. So if you intend your HTML files to be part of a web site
+with a standard \i{house style}, and the style needs a \i{footer} at
+the bottom of every page, this is where you can add that footer.
 
 
-\dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-start\}}}\cw{\\cfg\{html-address-start\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the
 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
 output HTML file. This might be a good place to put authors'
 \i{contact details}, for example.
 
 
 \dd The text you provide in this directive is placed at the
 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
 output HTML file. This might be a good place to put authors'
 \i{contact details}, for example.
 
-\dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-end\}}}\cw{\\cfg\{html-address-end\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the end of
 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
 after the version IDs (if present).
 
 
 \dd The text you provide in this directive is placed at the end of
 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
 after the version IDs (if present).
 
-\dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
+\dt \I{\cw{\\cfg\{html-navigation-attributes\}}}\cw{\\cfg\{html-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
 
 \dd The text you provide in this directive is included inside the
 \cw{<P>} tag containing the \i{navigation links} at the top of each
 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
 wanted the navigation links to have a particular CSS style, you
 could write
 
 \dd The text you provide in this directive is included inside the
 \cw{<P>} tag containing the \i{navigation links} at the top of each
 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
 wanted the navigation links to have a particular CSS style, you
 could write
-\cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
+\cw{\\cfg\{html-navigation-attributes\}\{class="foo"\}}, and the
 navigation-links paragraph would then begin with the tag \cw{<p
 class="foo">}.
 
 \S{output-html-headings} \ii{Configuring heading display}
 
 navigation-links paragraph would then begin with the tag \cw{<p
 class="foo">}.
 
 \S{output-html-headings} \ii{Configuring heading display}
 
-\dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-chapter-numeric\}}}\cw{\\cfg\{html-chapter-numeric\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, then chapter headings will not
 contain the word \q{Chapter} (or whatever other word you have
 
 \dd If this is set to \c{true}, then chapter headings will not
 contain the word \q{Chapter} (or whatever other word you have
@@ -461,14 +606,24 @@ they will just contain the chapter \e{number}, followed by the
 chapter title. If you set this to \c{false}, chapter headings will
 be prefixed by \q{Chapter} or equivalent.
 
 chapter title. If you set this to \c{false}, chapter headings will
 be prefixed by \q{Chapter} or equivalent.
 
-\dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-chapter-shownumber\}}}\cw{\\cfg\{html-chapter-shownumber\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then chapter headings will \e{only}
+contain the chapter title: they will not contain the word
+\q{Chapter} (or whatever other word you have defined in its place),
+and neither will they contain the chapter number. If set to
+\c{false}, this overrides \cw{\\cfg\{html-chapter-numeric\}}.
+
+\dt \I{\cw{\\cfg\{html-chapter-suffix\}}}\cw{\\cfg\{html-chapter-suffix\}\{}\e{text}\cw{\}}
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
-this to \q{\cw{:\_}}, then the chapter title might look something
+this to \cq{:\_}, then the chapter title might look something
 like \q{Chapter 2: Doing Things}.
 
 like \q{Chapter 2: Doing Things}.
 
-\dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-section-numeric\}}}\cw{\\cfg\{html-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\# {level} can be omitted (defaults to 0). Is this intentional?
 
 \dd Specifies whether section headings at a particular level should
 contain the word \q{Section} or equivalent (if \c{false}), or should
 
 \dd Specifies whether section headings at a particular level should
 contain the word \q{Section} or equivalent (if \c{false}), or should
@@ -477,110 +632,422 @@ which level of section headings you want to affect: 0 means
 first-level headings (\c{\\H}), 1 means second-level headings
 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
 
 first-level headings (\c{\\H}), 1 means second-level headings
 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
 
-\dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-section-shownumber\}}}\cw{\\cfg\{html-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then section headings at the
+specified level will \e{only} contain the section title: they will
+not contain the word \q{Section} (or whatever other word you have
+defined in its place), and neither will they contain the section
+number. If set to \c{false}, this overrides
+\cw{\\cfg\{html-section-numeric\}}.
+
+\dt \I{\cw{\\cfg\{html-section-suffix\}}}\cw{\\cfg\{html-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+
+\# {level} can be omitted (defaults to 0). Is this intentional?
 
 \dd Specifies the suffix text to be appended to section numbers at a
 particular level, before displaying the section title.
 
 
 \dd Specifies the suffix text to be appended to section numbers at a
 particular level, before displaying the section title.
 
+\S{output-html-names} Configuring standard text
+
+These directives let you fine-tune the names Halibut uses in places
+such as the navigation bar to refer to various parts of the document,
+and other standard pieces of text, for instance to change them to a
+different language.
+
+\dt \I{\cw{\\cfg\{html-preamble-text\}}}\cw{\\cfg\{html-preamble-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-contents-text\}}}\cw{\\cfg\{html-contents-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-index-text\}}}\cw{\\cfg\{html-index-text\}\{}\e{text}\cw{\}}
+
+\dd Text used to refer to the preamble (i.e., any paragraphs before
+the first chapter heading), contents, and index respectively, in the
+navigation bar, contents, and index.
+
+\lcont{
+
+(\c{html-contents-text} and \c{html-index-text} override the
+cross-format configuration keywords \c{contents} and \c{index} (see
+\k{input-config}, if both appear. They are legacy keywords preserved
+for backwards compatibility; you should generally use \c{contents}
+and \c{index}.)
+
+}
+
+\dt \I{\cw{\\cfg\{html-title-separator\}}}\cw{\\cfg\{html-title-separator\}\{}\e{text}\cw{\}}
+
+\dd If multiple headings are used in a file's \cw{<TITLE>} tag, this
+text is used to separate them.
+
+\# Under what circumstances can this occur?
+
+\dt \I{\cw{\\cfg\{html-index-main-separator\}}}\cw{\\cfg\{html-index-main-separator\}\{}\e{text}\cw{\}}
+
+\dd Separator between index term and references in the index.
+
+\dt \I{\cw{\\cfg\{html-index-multiple-separator\}}}\cw{\\cfg\{html-index-multiple-separator\}\{}\e{text}\cw{\}}
+
+\dd Separator between multiple references for a single index term in
+the index.
+
+\dt \I{\cw{\\cfg\{html-pre-versionid\}}}\cw{\\cfg\{html-pre-versionid\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-post-versionid\}}}\cw{\\cfg\{html-post-versionid\}\{}\e{text}\cw{\}}
+
+\dd Text surrounding each output \i{version ID paragraph}.
+
+\dt \I{\cw{\\cfg\{html-nav-prev-text\}}}\cw{\\cfg\{html-nav-prev-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}}
+
+\dd The text used for the \q{previous page}, \q{next page}, and \q{up}
+links on the navigation bar.
+
+\dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}}
+
+\dd Separator between links in the navigation bar.
+
+\S{output-html-characters} Configuring the characters used
+
+Unlike the other backends, HTML does not have a single
+\i\cw{\\cfg\{html-charset\}} directive, as there are several levels of
+character encoding to consider.
+
+The character set names are the same as for
+\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
+\cw{\\cfg\{input-charset\}}, these directives affect the \e{entire}
+output; it's not possible to switch encodings halfway through.
+
+\dt \I\cw{\\cfg\{html-output-charset\}}\cw{\\cfg\{html-output-charset\}\{}\e{character set name}\cw{\}}
+
+\dd The character encoding of the HTML file to be output. Unicode
+characters in this encoding's repertoire are included literally rather
+than as \i{HTML entities}.
+
+\dt \I\cw{\\cfg\{html-restrict-charset\}}\cw{\\cfg\{html-restrict-charset\}\{}\e{character set name}\cw{\}}
+
+\dd Only Unicode characters representable in this character set will be
+output; any others will be omitted and use their fallback text, if
+any. Characters not in \q{html-output-charset} will be represented as
+HTML numeric entities.
+
+\dt \I{\cw{\\cfg\{html-quotes\}}}\cw{\\cfg\{html-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
 \S{output-html-misc} Miscellaneous options
 
 \S{output-html-misc} Miscellaneous options
 
-\dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
+\dt \I\cw{\\cfg\{html-version\}}\cw{\\cfg\{html-version\}\{}\e{version}\cw{\}}
+
+\dd Identifies the precise version of HTML that is output. This
+affects the declaration within the HTML, and also has minor effects on
+the body of the HTML so that it is valid for the declared version. The
+available variants are:
+
+\lcont{
+
+\dt \cw{html3.2}
+
+\dd W3C HTML 3.2
+
+\dt \cw{html4}
+
+\dd W3C HTML 4.01 Strict
+
+\dt \cw{iso-html}
+
+\dd ISO/IEC 15445:2000
+
+\dt \cw{xhtml1.0transitional}
+
+\dd W3C XHTML 1.0 Transitional
+
+\dt \cw{xhtml1.0strict}
+
+\dd W3C XHTML 1.0 Strict
+
+}
+
+\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}]
 
 \dd This directive lets you specify a \i{template}, with exactly the
 
 \dd This directive lets you specify a \i{template}, with exactly the
-same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
-\k{output-html-file}), to be used for the anchor names (\i\cw{A
-NAME="..."}) used to allow URLs to refer to specific sections within
-a particular HTML file. So if you set this to \q{\cw{%k}}, for
-example, then each individual section in your document will be
+same syntax used in \cw{\\cfg\{html-template-filename\}} (see
+\k{output-html-file}), to be used for the anchor names (\i\cw{<A
+NAME="...">}) used to allow URLs to refer to specific sections
+within a particular HTML file. So if you set this to \cq{%k},
+for example, then each individual section in your document will be
 addressable by means of a URL ending in a \c{#} followed by your
 internal section keyword.
 
 addressable by means of a URL ending in a \c{#} followed by your
 internal section keyword.
 
-\dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
+\lcont{
+
+If more than one template is specified, anchors are generated in all
+the specified formats; Halibut's own cross-references are generated
+with the first template.
+
+Characters that are not permitted in anchor names are stripped. If
+there are no valid characters left, or a fragment is non-unique,
+Halibut starts inventing fragment names and suffixes as appropriate.
+
+Note that there are potentially fragment names that are not controlled
+by this mechanism, such as index references.
+
+}
+
+\dt \I{\cw{\\cfg\{html-versionid\}}}\cw{\\cfg\{html-versionid\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
 
 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
-file. If it is set to \c{false}, they will be omitted completely.
+file. If it is set to \c{false}, they will only be included as HTML
+comments.
 
 
-\# FIXME: surely it would be better to include them in HTML
-\# comments? The only question is whether they should be _visible_.
+\dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{true}, machine-readable relational links will
+be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK
+REL="next">} and so on within the \i\cw{<HEAD>} section)
+providing links to related files. The same set of links are provided
+as in the navigation bar (with which this should not be confused).
+
+\lcont{
 
 
-\dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
+Some browsers make use of this semantic information, for instance to
+allow easy navigation through related pages, and to prefetch the next
+page. (Search engines can also make use of it.) However, many browsers
+ignore this markup, so it would be unwise to rely on it for
+navigation.
+
+The use and rendering of this information is entirely up to the
+browser; none of the other Halibut options for the navigation bar will
+have any effect.
+
+}
+
+\dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{true}, the usual \i{navigation links} within
+the \e{body} of each HTML file (near the top of the rendered page) will
+be suppressed.
+
+\dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
 bottom of each HTML file will be omitted completely. (This will
 
 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
 bottom of each HTML file will be omitted completely. (This will
-therefore also cause \i{version IDs} not to be included.)
+therefore also cause \i{version IDs} not to be included visibly.)
 
 
-\dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-author\}}}\cw{\\cfg\{html-author\}\{}\e{text}\cw{\}}
 
 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
 name="author">} tag in the output HTML files, so that browsers which
 support this can automatically identify the \i{author} of the document.
 
 
 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
 name="author">} tag in the output HTML files, so that browsers which
 support this can automatically identify the \i{author} of the document.
 
-\dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-description\}}}\cw{\\cfg\{html-description\}\{}\e{text}\cw{\}}
 
 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
 name="description">} tag in the output HTML files, so that browsers
 which support this can easily pick out a brief \I{description, of
 document}description of the document.
 
 
 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
 name="description">} tag in the output HTML files, so that browsers
 which support this can easily pick out a brief \I{description, of
 document}description of the document.
 
+\S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help}
+
+The HTML files output from Halibut's HTML back end can be used as
+input to the MS Windows HTML Help compiler. In order to do this, you
+also need some auxiliary files: a project file, and (probably) a
+contents file and an index file. Halibut can optionally generate
+those as well.
+
+To enable the generation of MS HTML Help auxiliary files, use the
+following configuration directives:
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help project file with the
+specified name. You will almost certainly want the filename to end
+in the extension \c{.hhp} (although Halibut will not enforce this).
+If you use this option, you must also use the
+\cw{html-mshtmlhelp-chm} option to specify the desired name of the
+compiled help file.
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}}
+
+\dd Specifies the desired name of the compiled HTML Help file. You
+will almost certainly want this to have the extension \c{.chm}
+(although Halibut will not enforce this). The name you specify here
+will be written into the help project file. If you specify this
+option, you must also use the \cw{html-mshtmlhelp-project} option to
+request a help project file in the first place.
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help contents file with the
+specified name, and refer to it in the help project file. You will
+almost certainly want the filename to end in the extension \c{.hhc}
+(although Halibut will not enforce this). This option will be
+ignored if you have not also specified a help project file.
+
+\lcont{
+
+Creating a contents file like this causes the HTML Help viewer to
+display a contents tree in the pane to the left of the main text
+window. You can choose to generate an HTML Help project without this
+feature, in which case the user will still be able to navigate
+around the document by using the ordinary internal links in the HTML
+files themselves just as if it were a web page. However, using a
+contents file is recommended.
+
+}
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help index file with the
+specified name, and refer to it in the help project file. You will
+almost certainly want the filename to end in the extension \c{.hhk}
+(although Halibut will not enforce this). This option will be
+ignored if you have not also specified a help project file.
+
+\lcont{
+
+Specifying this option suppresses the generation of an HTML-based
+index file (see \cw{\\cfg\{html-index-filename\}} in
+\k{output-html-file}).
+
+Creating an index file like this causes the HTML Help viewer to
+provide a list of index terms in a pane to the left of the main text
+window. You can choose to generate an HTML Help project without this
+feature, in which case a conventional HTML index will be generated
+instead (assuming you have any index terms at all defined) and the
+user will still be able to use that. However, using an index file is
+recommended.
+
+Halibut will not output an index file at all, or link to one from
+the help project file, if your document contains no index entries.
+
+}
+
+If you use the above options, Halibut will output a help project
+file which you should be able to feed straight to the command-line
+MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help
+Workshop (\cw{HHW.EXE}).
+
+You may also wish to alter other HTML configuration options to make
+the resulting help file look more like a help file and less like a
+web page. A suggested set of additional configuration options for
+HTML Help is as follows:
+
+\b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help
+works best with lots of small files (\q{topics}) rather than a few
+large ones. In particular, the contents and index mechanisms can
+only reference files, not subsections within files.
+
+\b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress
+the contents list above the main text of each bottom-level file.
+
+\b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help
+has its own navigation facilities and it looks a bit strange to
+duplicate them.
+
+\b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the
+\cw{<ADDRESS>} section makes less sense in a help file than it does
+on a web page.
+
 \S{output-html-defaults} Default settings
 
 The \i{default settings} for Halibut's HTML output format are:
 
 \S{output-html-defaults} Default settings
 
 The \i{default settings} for Halibut's HTML output format are:
 
-\c \cfg{xhtml-contents-filename}{Contents.html}
-\c \cfg{xhtml-index-filename}{IndexPage.html}
-\c \cfg{xhtml-template-filename}{%n.html}
-\c \cfg{xhtml-single-filename}{Manual.html}
-\c \cfg{xhtml-template-fragment}{%b}
-\c
-\c \cfg{xhtml-leaf-level}{2}
-\c \cfg{xhtml-leaf-contains-contents}{false}
-\c \cfg{xhtml-leaf-smallest-contents}{4}
-\c \cfg{xhtml-contents-depth-0}{2}
-\c \cfg{xhtml-contents-depth-1}{3}
-\c \cfg{xhtml-contents-depth-2}{4}
-\c \cfg{xhtml-contents-depth-3}{5}
-\c \cfg{xhtml-contents-depth-4}{6}
-\c \cfg{xhtml-contents-depth-5}{7}
-\c
-\c \cfg{xhtml-head-end}{}
-\c \cfg{xhtml-body-tag}{<body>}
-\c \cfg{xhtml-body-start}{}
-\c \cfg{xhtml-body-end}{}
-\c \cfg{xhtml-address-start}{}
-\c \cfg{xhtml-address-end}{}
-\c \cfg{xhtml-navigation-attributes}{}
-\c
-\c \cfg{xhtml-versionid}{true}
-\c \cfg{xhtml-suppress-address}{false}
-\c \cfg{xhtml-author}{}
-\c \cfg{xhtml-description}{}
-\c
-\c \cfg{xhtml-chapter-numeric}{false}
-\c \cfg{xhtml-chapter-suffix}{: }
-\c
-\c \cfg{xhtml-section-numeric}{0}{true}
-\c \cfg{xhtml-section-suffix}{0}{ }
-\c
-\c \cfg{xhtml-section-numeric}{1}{true}
-\c \cfg{xhtml-section-suffix}{1}{ }
+\c \cfg{html-contents-filename}{Contents.html}
+\c \cfg{html-index-filename}{IndexPage.html}
+\c \cfg{html-template-filename}{%n.html}
+\c \cfg{html-single-filename}{Manual.html}
 \c
 \c
+\c \cfg{html-leaf-level}{2}
+\c \cfg{html-leaf-contains-contents}{false}
+\c \cfg{html-leaf-smallest-contents}{4}
+\c \cfg{html-contents-depth}{0}{2}
+\c \cfg{html-contents-depth}{1}{3}
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{html-head-end}{}
+\c \cfg{html-body-tag}{<body>}
+\c \cfg{html-body-start}{}
+\c \cfg{html-body-end}{}
+\c \cfg{html-address-start}{}
+\c \cfg{html-address-end}{}
+\c \cfg{html-navigation-attributes}{}
+\c
+\c \cfg{html-chapter-numeric}{false}
+\c \cfg{html-chapter-shownumber}{true}
+\c \cfg{html-chapter-suffix}{: }
+\c
+\c \cfg{html-section-numeric}{0}{true}
+\c \cfg{html-section-shownumber}{0}{true}
+\c \cfg{html-section-suffix}{0}{ }
+\c
+\c \cfg{html-section-numeric}{1}{true}
+\c \cfg{html-section-shownumber}{1}{true}
+\c \cfg{html-section-suffix}{1}{ }
+\c
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{html-preamble-text}{Preamble}
+\c \cfg{html-contents-text}{Contents}
+\c \cfg{html-index-text}{Index}
+\c \cfg{html-title-separator}{ - }
+\c \cfg{html-index-main-separator}{: }
+\c \cfg{html-index-multiple-separator}{, }
+\c \cfg{html-pre-versionid}{[}
+\c \cfg{html-post-versionid}{]}
+\c \cfg{html-nav-prev-text}{Previous}
+\c \cfg{html-nav-next-text}{Next}
+\c \cfg{html-nav-up-text}{Up}
+\c \cfg{html-nav-separator}{ | }
+\c
+\c \cfg{html-output-charset}{ASCII}
+\c \cfg{html-restrict-charset}{UTF-8}
+\c \cfg{html-quotes}{\u2018}{\u2019}{"}{"}
+\c
+\c \cfg{html-version}{html4}
+\c \cfg{html-template-fragment}{%b}
+\c \cfg{html-versionid}{true}
+\c \cfg{html-rellinks}{true}
+\c \cfg{html-suppress-navlinks{false}
+\c \cfg{html-suppress-address}{false}
+\c \cfg{html-author}{}
+\c \cfg{html-description}{}
 
 \H{output-whlp} Windows Help
 
 This output format generates data that can be used by the \i{Windows
 
 \H{output-whlp} Windows Help
 
 This output format generates data that can be used by the \i{Windows
-Help} program \cw{WINHELP.EXE}. There are two actual files
+Help} program \cw{WINHLP32.EXE}. There are two actual files
 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
 
 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
 
+Note that as of 2006, MS is discontinuing the Windows Help format in
+favour of the newer HTML Help format (\c{.chm} files). Halibut is
+not currently able to generate \c{.chm} files directly, but its HTML
+back end can write out project files suitable for use as input to
+the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more
+information on this.
+
+Currently, the Windows Help output is hardcoded to be in the
+\q{\i{Win1252}} character set. (If anyone knows how character sets
+are encoded in Windows Help files, we'd appreciate help.)
+
 The Windows Help output format supports the following configuration
 directives:
 
 The Windows Help output format supports the following configuration
 directives:
 
+\S{output-whlp-file} Output file name
+
 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
 
 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
 
-\dd Sets the \i{output file name} in which to store the man page.
+\dd Sets the \i{output file name} in which to store the help file.
 This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--winhelp} (see
 \k{running-options}).
 This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--winhelp} (see
 \k{running-options}).
@@ -593,6 +1060,42 @@ Halibut will append it. Halibut will also generate a contents file
 
 }
 
 
 }
 
+\S{output-whlp-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see
+\k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{winhelp-quotes\}}}\cw{\\cfg\{winhelp-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-whlp-misc} Miscellaneous configuration options
+
+\dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
+
+\dd Sets the text used to describe the help page containing the blurb
+(see \k{input-blurb}) and table of contents.
+
+\dt
+\I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
+
+\dd Specifies the \I{suffix text, in section titles}suffix text to
+be appended to section numbers, before displaying the section title.
+(Applies to all levels.)
+
+\dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
+
+\dd This text is appended to the number on a \i{numbered list} item,
+in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
+\k{output-text-characters}).
+
 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
 
 \dd This directive defines a Windows \i{Help topic} name in the current
 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
 
 \dd This directive defines a Windows \i{Help topic} name in the current
@@ -618,9 +1121,18 @@ different help contexts which you can use in this way.
 
 }
 
 
 }
 
+\S{output-whlp-defaults} Default settings
+
 The \i{default settings} for the Windows Help output format are:
 
 \c \cfg{winhelp-filename}{output.hlp}
 The \i{default settings} for the Windows Help output format are:
 
 \c \cfg{winhelp-filename}{output.hlp}
+\c
+\c \cfg{winhelp-bullet}{\u2022}{-}
+\c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
+\c
+\c \cfg{winhelp-contents-titlepage}{Title page}
+\c \cfg{winhelp-section-suffix}{: }
+\c \cfg{winhelp-list-suffix}{.}
 
 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
 
 
 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
 
@@ -632,6 +1144,8 @@ macro package.
 
 The available configuration options for this format are as follows:
 
 
 The available configuration options for this format are as follows:
 
+\S{output-man-file} Output file name
+
 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the \i{output file name} in which to store the man page.
 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the \i{output file name} in which to store the man page.
@@ -639,6 +1153,8 @@ This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--man} (see
 \k{running-options}).
 
 parameter after the command-line option \i\c{--man} (see
 \k{running-options}).
 
+\S{output-man-identity} Configuring headers and footers
+
 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
 
 \dd This directive is used to generate the initial \i{\c{.TH}
 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
 
 \dd This directive is used to generate the initial \i{\c{.TH}
@@ -662,10 +1178,13 @@ A traditional order for the arguments appears to be:
 
 For example, a typical \cw{man} page might contain
 
 
 For example, a typical \cw{man} page might contain
 
-\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs}
+\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
+\c Bloggs}
 
 }
 
 
 }
 
+\S{output-man-headings} Configuring heading display
+
 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, then \i{section headings} in the
 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, then \i{section headings} in the
@@ -704,7 +1223,8 @@ simply says
 Then you have a file \c{make-foo.but}, and probably others like it
 as well, each of which looks something like this:
 
 Then you have a file \c{make-foo.but}, and probably others like it
 as well, each of which looks something like this:
 
-\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs}
+\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
+\c Bloggs}
 \c
 \c \H{man-foo} \cw{man} page for \c{make-foo}
 \c 
 \c
 \c \H{man-foo} \cw{man} page for \c{make-foo}
 \c 
@@ -734,9 +1254,646 @@ expect.
 
 }
 
 
 }
 
+\S{output-man-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
+
+\dd Specifies what character set the output should be in, similarly to
+\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
+
+\# FIXME: you're probably on your own in making sure that it's
+sensible to output man pages in that charset.
+
+\dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{man-rule\}}}\cw{\\cfg\{man-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
+
+\dd This specifies the text which should be used for drawing
+\i{horizontal rules} (generated by \i\c{\\rule}; see
+\k{input-rule}) when the manual page is rendered into text.
+It should only be one character long, but otherwise
+it works like the \cw{\\cfg\{text-rule\}} directive
+(see \k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{man-quotes\}}}\cw{\\cfg\{man-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-man-defaults} Default settings
+
 The \i{default settings} for the \cw{man} page output format are:
 
 \c \cfg{man-filename}{output.1}
 The \i{default settings} for the \cw{man} page output format are:
 
 \c \cfg{man-filename}{output.1}
+\c
 \c \cfg{man-identity}{}
 \c \cfg{man-identity}{}
+\c
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
+\c
+\c \cfg{man-charset}{ASCII}
+\c \cfg{man-bullet}{\u2022}{o}
+\c \cfg{man-rule}{\u2500}{-}
+\c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
+
+\H{output-info} GNU Info
+
+This output format generates files which can be used with the \i{GNU
+Info} program.
+
+There are typically multiple output files: a primary file whose name
+usually ends in \c{.info}, and one or more subsidiary files whose
+names have numbers on the end, so that they end in \c{.info-1},
+\c{.info-2} and so on. Alternatively, this output format can be
+configured to output a single large file containing the whole
+document.
+
+The Info output format supports the following configuration
+directives:
+
+\S{output-info-file} Controlling the output filenames
+
+\dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the output file name in which to store the Info file.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--info} (see
+\k{running-options}).
+
+\lcont{
+
+The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
+your output file name to produce any subsidiary files required.
+
+Note that Info files refer to their own names internally, so
+these files cannot be \I{renaming Info files}renamed after
+creation and remain useful.
+
+}
+
+\dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
+
+\dd Sets the preferred \i{maximum file size} for each subsidiary
+file. As a special case, if you set this to zero, there will be no
+subsidiary files and the whole document will be placed in a single
+self-contained output file. (However, note that this file can still
+not be renamed usefully.)
+
+\lcont{
+
+The preferred maximum file size is only a guideline. Halibut may be
+forced to exceed it if a single section of the document is larger
+than the maximum size (since individual Info nodes may not be
+split between files).
+
+}
+
+\S{output-info-dimensions} Indentation and line width
+
+\dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
+
+\dd Sets the \I{text width}width of the main part of the document,
+in characters. Works exactly like the \cw{\\cfg\{text-width\}}
+directive (see \k{output-text-dimensions}).
+
+\dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
+
+\dd Specifies the extra indentation for \I{code paragraphs,
+indentation} code paragraphs. Works exactly like the
+\cw{\\cfg\{text-indent-code\}} directive (see
+\k{output-text-dimensions}).
+
+\dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
+
+\dd Specifies how much horizontal space to leave in the index node
+for the text of \i{index terms}, before displaying the sections the
+terms occur in.
+
+\dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
+
+\dd Specifies the extra indentation before the bullet or number in a
+\I{bulletted list, indentation}\I{numbered list, indentation}list
+item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
+directive (see \k{output-text-dimensions}).
+
+\dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
+
+\dd Specifies the additional indentation before the body of a list
+item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
+directive (see \k{output-text-dimensions}).
+
+\S{output-info-headings} Configuring heading display
+
+\dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
+
+\dd Specifies the suffix text to be appended to each section number
+before displaying the section title. For example, if you set this to
+\cq{:\_}, then a typical section title might look something like
+\q{Section 3.1: Something Like This}.
+
+\dt \I{\cw{\\cfg\{info-title-underline\}}}\cw{\\cfg\{info-title-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to be used to \I{underlining}underline 
+the overall document title. Works
+very much like the \cw{\\cfg\{text-title-underline\}} directive
+(see \k{output-text-headings}). You can specify more than one
+option, and Halibut will choose the first one supported by the
+character set.
+
+\dt \I{\cw{\\cfg\{info-chapter-underline\}}}\cw{\\cfg\{info-chapter-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies how chapter and appendix headings should be underlined.
+
+\dt \I{\cw{\\cfg\{info-section-underline\}}}\cw{\\cfg\{info-section-underline\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies how to underline section headings at a particular level.
+The \e{level} parameter specifies which level of section
+headings you want to affect: 0 means first-level headings (\c{\\H}),
+1 means second-level headings (\c{\\S}), 2 means the level below
+that (\c{\\S2}), and so on.
+
+\S{output-info-characters} Controlling the characters used
+
+\dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
+
+\dd Specifies what character set the output should be in, similarly to
+\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
+
+\# FIXME: if you try sufficiently hard, you can probably find an
+output encoding that will break the info format by trampling on its
+special characters. So either don't do that, or tell us what we should
+do about it.
+
+\dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see
+\k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text used to draw \i{horizontal rules}. You can
+specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{info-quotes\}}}\cw{\\cfg\{info-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{info-emphasis\}}}\cw{\\cfg\{info-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}]
+
+\dd Specifies how to display emphasised text. You can specify
+multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-emphasis\}} directive (see
+\k{output-text-characters}).
+
+\S{output-info-misc} Miscellaneous configuration options
+
+\dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
+
+\dd Specifies the text to append to the item numbers in a
+\i{numbered list}. Works exactly like the
+\cw{\\cfg\{text-list-suffix\}} directive (see
+\k{output-text-misc}).
+
+\dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
+name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
+
+\dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
+header of the Info file. This mechanism is used to automatically
+generate the \i{\c{dir} file} at the root of a Unix system's
+Info collection.
+
+\lcont{
+
+The parameters to this directive are:
+
+\dt \e{section}
+
+\dd Specifies the section of the \c{dir} file in which you want your
+document referenced. For example, \q{Development}, or \q{Games}, or
+\q{Miscellaneous}.
+
+\dt \e{short name}
+
+\dd Specifies a short name for the directory entry, which will
+appear at the start of the menu line.
+
+\dt \e{long name}
+
+\dd Specifies a long name for the directory entry, which will appear
+at the end of the menu line.
+
+\dt \e{keyword}
+
+\dd This parameter is optional. If it is present, then the directory
+entry will cause a jump to a particular subsection of your document,
+rather than starting at the top. The subsection will be the one
+referred to by the given keyword (see \k{input-sections} for details
+about assigning keywords to document sections).
+
+For example, in a document describing many game programs, the
+configuration directive
+
+\c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
+\c game}{chess}
+
+might produce text in the \c{dir} file looking something like this:
+
+\c Games
+\c * Chess: (mygames)Chapter 3.   Electronic chess game
+
+if the output file were called \c{mygames.info} and the keyword
+\c{chess} had been used to define Chapter 3 of the document.
+
+}
+
+\S{output-info-defaults} Default settings
+
+The \i{default settings} for the Info output format are:
+
+\c \cfg{info-filename}{output.info}
+\c \cfg{info-max-file-size}{65536}
+\c
+\c \cfg{info-width}{70}
+\c \cfg{info-indent-code}{2}
+\c \cfg{info-index-width}{40}
+\c \cfg{info-list-indent}{1}
+\c \cfg{info-listitem-indent}{3}
+\c
+\c \cfg{info-section-suffix}{: }
+\c \cfg{info-title-underline}{*}
+\c \cfg{info-chapter-underline}{=}
+\c \cfg{info-section-underline}{0}{-}
+\c \cfg{info-section-underline}{1}{.}
+\c \cfg{info-section-underline}{2}{.}
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{info-charset}{ASCII}
+\c \cfg{info-bullet}{\u2022}{-}
+\c \cfg{info-rule}{\u2500}{-}
+\c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
+\c \cfg{info-emphasis}{_}{_}
+\c
+\c \cfg{info-list-suffix}{.}
+
+and no \cw{\\cfg\{info-dir-entry\}} directives.
+
+\H{output-paper} Paper formats
+
+These output formats (currently PDF and PostScript) generate printable
+manuals. As such, they share a number of configuration directives.
+
+\S{output-pdf} \i{PDF}
+
+This output format generates a printable manual in PDF format. In
+addition, it uses some PDF interactive features to
+provide an outline of all the document's sections and clickable
+cross-references between sections.
+
+There is one configuration option specific to PDF:
+
+\dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the PDF file.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--pdf} (see
+\k{running-options}).
+
+The \i{default settings} for the PDF output format are:
+
+\c \cfg{pdf-filename}{output.pdf}
+
+\S{output-ps} \i{PostScript}
+
+This output format generates a printable manual in PostScript format.
+This should look exactly identical to the PDF output (see
+\k{output-ps}), and uses \i\c{pdfmark} to arrange that if converted
+to PDF it will contain the same interactive features.
+
+There is one configuration option specific to PostScript:
+
+\dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the PostScript
+file. This directive is implicitly generated if you provide a file
+name parameter after the command-line option \i\c{--ps} (see
+\k{running-options}).
+
+The \i{default settings} for the PostScript output format are:
+
+\c \cfg{ps-filename}{output.ps}
+
+\S{output-paper-dimensions} Configuring layout and \i{measurements}
+
+All measurements are in PostScript \i{points} (72 points to the inch).
+
+\S2{output-paper-pagesize} Page properties
+
+\dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
+
+\dd Specify the absolute limits of the paper.
+
+\dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
+
+\dd Specify the margins. Most text appears within these margins,
+except:
+
+\lcont{
+
+\b Section numbers, which appear in the left margin.
+
+\b The footer (containing page numbers), which appears in the bottom
+margin.
+
+}
+
+\S2{output-paper-line} Vertical spacing
+
+\dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of space between lines of text within a
+paragraph. (So, if the font size is 12pt and there is 2pt of leading,
+there will be 14pt between successive baselines.)
+
+\dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of vertical space between paragraphs. (The
+vertical space between paragraphs does \e{not} include
+\c{paper-base-leading}.)
+
+\S2{output-paper-indentation} Indentation
+
+\dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the indentation of the bullet or number in a
+\I{bulletted list, indentation}bulletted or \I{numbered list,
+indentation}numbered \I{list, indentation}list, similarly to
+\cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
+
+\dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \e{extra} indentation for the body of a list item,
+over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
+
+\# FIXME: doesn't actually work, AFAICT.
+
+\dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of indentation for a level of quoting. Used
+for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
+(see \k{input-code}).
+
+\S2{output-paper-headings} Headings
+
+\dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
+
+\dd Specifies the space between the top margin and the top of the
+chapter heading. (Each chapter begins on a new page.)
+
+\dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
+
+\dd Specifies the vertical thickness of the black rule under chapter
+headings.
+
+\dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the base of the chapter heading and
+the \e{base} of the underlying rule.
+
+\dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the left margin and the \e{right}
+of section numbers (which are in the left margin).
+
+\S2{output-paper-index} Contents and index
+
+\dt \I{\cw{\\cfg\{paper-contents-indent-step\}}}\cw{\\cfg\{paper-contents-indent-step\}\{}\e{points}\cw{\}}
+
+\dd Specifies by how much to indent each entry in the table of
+contents per level of subdivision in the document. (In other words,
+chapter titles appear at the left of the table of contents, headings
+within the chapter are indented by the amount configured here,
+subheadings by twice that, and so on.)
+
+\dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of space on the right of the table of
+contents which should be reserved for page numbers only. Headings in
+the table of contents which extend into this space will be wrapped.
+
+\dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
+
+\dd Specifies the horizontal spacing between dots in \i\e{leaders}
+(the dotted lines that appear between section headings and page
+numbers in the table of contents).
+
+\dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the bottom margin and the \e{base}
+of the footer (which contains page numbers).
+
+\dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
+
+\dd Specifies the number of columns the index should be divided into.
+
+\# FIXME: with this set to 1, the right-alignment of some index entry
+page numbers in the Halibut manual is decidedly wonky.
+
+\dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of \I{gutter} horizontal space between index
+columns.
+
+\dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
+
+\dd Specifies the minimum allowable horizontal space between an index
+entry and its page number. If the gap is smaller, the page number is
+moved to the next line.
+
+\S2{output-paper-fonts} \ii{Fonts}
+
+The directives in this section control which fonts Halibut uses for
+various kinds of text.  Directives for setting the font normally take
+three font names, the first of which is used for normal text, the
+second for emphasised text, and the third for code.  Any fonts which
+aren't specified are left unchanged.
+
+Halibut intrinsically knows about some fonts, and these fonts are also
+built into all PDF and most PostScript implementations.
+These fonts can be used without further formality.  Halibut can also use
+other fonts, and can \I{embedding fonts}embed them it its PDF and
+PostScript output.  These other fonts are supplied to Halibut by
+simply adding them to the list of input files on its command line.
+
+To use a \i{Type 1 font} Halibut needs both the font file itself,
+in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB)
+format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file.  The AFM
+file must be specified first on the command line.  If Halibut gets an
+AFM file without a corresponding Type 1 font file, the PostScript and
+PDF output files will still use that font, but they won't contain it.
+
+Using a \i{TrueType font} is rather simpler, and simply requires you to
+pass the font file to Halibut.  Halibut does place a few restrictions on
+TrueType fonts, notably that they must include a \i{Unicode} mapping
+table and a PostScript name.
+
+Fonts are specified using their PostScript names.  Running Halibut with
+the \i\cw{\-\-list-fonts} option causes it to display the PostScript
+names of all the fonts it intrinsically knows about, along with any
+fonts the were supplied as input files.
+
+\ii{Font sizes} are specified in PostScript \i{points} (72 to the inch).
+
+\dt \I{\cw{\\cfg\{paper-title-fonts\}}}\cw{\\cfg\{paper-title-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in the document title.
+
+\dt \I{\cw{\\cfg\{paper-title-font-size\}}}\cw{\\cfg\{paper-title-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of the document title.
+
+\dt \I{\cw{\\cfg\{paper-chapter-fonts\}}}\cw{\\cfg\{paper-chapter-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in chapter titles.
+
+\dt \I{\cw{\\cfg\{paper-chapter-font-size\}}}\cw{\\cfg\{paper-chapter-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of chapter titles.
+
+\dt \I{\cw{\\cfg\{paper-section-fonts\}}}\cw{\\cfg\{paper-section-fonts\}\{}\e{level}\cw{\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in section headings at the \e{level}
+specified.
+
+\dt \I{\cw{\\cfg\{paper-section-font-size\}}}\cw{\\cfg\{paper-section-font-size\}\{}\e{level}\cw{\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of section headings at the \e{level}
+specified.
+
+\dt \I{\cw{\\cfg\{paper-base-fonts\}}}\cw{\\cfg\{paper-base-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in the body text.
+
+\dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of body text.
+
+\dt \I{\cw{\\cfg\{paper-code-fonts\}}}\cw{\\cfg\{paper-code-fonts\}\{}\e{bold-font}\cw{\}}[\cw{\{}\e{italic-font}\cw{\}}[\cw{\{}\e{normal-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in code paragraphs.  The
+\e{bold-font} is used for bold text, the \e{italic-font} for
+emphasised text, and the \e{normal-font} for normal code.
+
+\dt \I{\cw{\\cfg\{paper-code-font-size\}}}\cw{\\cfg\{paper-code-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of text in code paragraphs.
+
+\dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the font size to use for \i{page numbers}.
+
+\S2{output-paper-misc} Miscellaneous
+
+\dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
+
+\dd Specifies the vertical thickness of the rule produced by the
+\cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
+reserved for thicker rules.)
+
+\S{output-paper-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see
+\k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-paper-defaults} Default settings for paper formats
+
+The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
+\i{A4 paper}.
+
+\c \cfg{paper-page-width}{595} 
+\c \cfg{paper-page-height}{842} 
+\c
+\c \cfg{paper-left-margin}{72} 
+\c \cfg{paper-top-margin}{72} 
+\c \cfg{paper-right-margin}{72} 
+\c \cfg{paper-bottom-margin}{108} 
+\c
+\c \cfg{paper-base-leading}{1} 
+\c \cfg{paper-base-para-spacing}{10} 
+\c
+\c \cfg{paper-list-indent}{6} 
+\c \cfg{paper-listitem-indent}{18} 
+\c \cfg{paper-quote-indent}{18} 
+\c
+\c \cfg{paper-chapter-top-space}{72} 
+\c \cfg{paper-chapter-underline-thickness}{3} 
+\c \cfg{paper-chapter-underline-depth}{14} 
+\c \cfg{paper-sect-num-left-space}{12} 
+\c
+\c \cfg{paper-contents-indent-step}{24} 
+\c \cfg{paper-contents-margin}{84} 
+\c \cfg{paper-leader-separation}{12} 
+\c \cfg{paper-footer-distance}{32} 
+\c \cfg{paper-index-columns}{2} 
+\c \cfg{paper-index-gutter}{36} 
+\c \cfg{paper-index-minsep}{18} 
+\c
+\c \cfg{paper-base-fonts}{Times-Roman}{Times-Italic}{Courier}
+\c \cfg{paper-base-font-size}{12} 
+\c \cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier}
+\c \cfg{paper-code-font-size}{12}
+\c \cfg{paper-title-fonts}{Helvetica-Bold}
+\c     {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-title-font-size}{24}
+\c \cfg{paper-chapter-fonts}{Helvetica-Bold}
+\c     {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-chapter-font-size}{20}
+\c \cfg{paper-section-fonts}{0}{Helvetica-Bold}
+\c     {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{0}{16}
+\c \cfg{paper-section-fonts}{1}{Helvetica-Bold}
+\c     {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{1}{14}
+\c \cfg{paper-section-fonts}{2}{Helvetica-Bold}
+\c     {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{2}{13}
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{paper-pagenum-font-size}{12} 
+\c
+\c \cfg{paper-rule-thickness}{1} 
+\c
+\c \cfg{paper-bullet}{\u2022}{-}
+\c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}