Note that no index is generated by the text backend.
[sgt/halibut] / doc / output.but
index 591952f..68fc04e 100644 (file)
 \C{output} Halibut output formats
 
 \C{output} Halibut output formats
 
-This chapter describes each of Halibut's current output formats. It
-gives some general information about the format, and also describes
-all the configuration directives which are specific to that format.
+This chapter describes each of Halibut's current \i{output formats}.
+It gives some general information about the format, and also
+describes all the \i{configuration directives} which are specific to
+that format.
 
 \H{output-text} Plain text
 
 
 \H{output-text} Plain text
 
-This output format generates the document as a single plain text
-file, under the name \c{output.txt}.
-
-The output file is currently assumed to be in the 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 fallback text (if any) will be used instead.
+This output format generates the document as a single \i{plain text}
+file. No index is generated.
 
 The precise formatting of the text file can be controlled by a
 variety of configuration directives. They are listed in the
 following subsections.
 
 
 The precise formatting of the text file can be controlled by a
 variety of configuration directives. They are listed in the
 following subsections.
 
+\S{output-text-file} Output file name
+
+\dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the text file.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--text} (see
+\k{running-options}).
+
 \S{output-text-dimensions} Indentation and line width
 
 This section describes the configuration directives which control
 \S{output-text-dimensions} Indentation and line width
 
 This section describes the configuration directives which control
-the horizontal dimensions of the output text file: how much
+the \i{horizontal dimensions} of the output text file: how much
 paragraphs are indented by and how long the lines are.
 
 paragraphs are indented by and how long the lines are.
 
-\dt \cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
+\dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
 
 
-\dd Sets the width of the main part of the document, in characters.
-This width will be used for wrapping paragraphs and for centring
-titles (if you have asked for titles to be centred - see
-\k{output-text-headings}). This width does \e{not} include the left
-indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
+\dd Sets the \I{text width}width of the main part of the document,
+in characters. This width will be used for wrapping paragraphs and
+for centring titles (if you have asked for titles to be centred -
+see \k{output-text-headings}). This width does \e{not} include the
+left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
 indent of 8 and a width of 64, your maximum output line length will
 be 72.
 
 indent of 8 and a width of 64, your maximum output line length will
 be 72.
 
-\dt \cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
+\dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
 
 
-\dd Sets the left indentation for the document. If you set this to
-zero, your document will look like an ordinary text file as someone
-with a text editor might have written it; if you set it above zero,
-the text file will have a margin down the left in the style of some
-printed manuals, and you can then configure the section numbers to
-appear in this margin (see \k{output-text-headings}).
+\dd Sets the left \i{indentation} for the document. If you set this
+to zero, your document will look like an ordinary text file as
+someone with a text editor might have written it; if you set it
+above zero, the text file will have a \i{margin} down the left in
+the style of some printed manuals, and you can then configure the
+section numbers to appear in this margin (see
+\k{output-text-headings}).
 
 
-\dt \cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
+\dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
 
 \dd Specifies how many extra characters of indentation (on top of
 
 \dd Specifies how many extra characters of indentation (on top of
-the normal left indent) should be given to code paragraphs.
+the normal left indent) should be given to \I{code paragraphs,
+indentation} code paragraphs.
 
 
-\dt \cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
+\dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
 
 \dd Specifies how many extra spaces should be used to indent the
 
 \dd Specifies how many extra spaces should be used to indent the
-bullet or number in a bulletted or numbered list. The actual body of
-the list item will be indented by this much \e{plus} the value
-configured by \cw{\\cfg\{text-listitem-indent\}}.
+bullet or number in a \I{bulletted list, indentation}bulletted or
+\I{numbered list, indentation}numbered \I{list, indentation}list.
+The actual body of the list item will be indented by this much
+\e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}.
 
 
-\dt \cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
+\dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
 
 \dd Specifies how many extra spaces should be used to indent the
 body of a list item, over and above the number configured in
 \cw{\\cfg\{text-list-indent\}}.
 
 
 \dd Specifies how many extra spaces should be used to indent the
 body of a list item, over and above the number configured in
 \cw{\\cfg\{text-list-indent\}}.
 
-\dt \cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
 
 
-\dd When this is set to \c{true}, the document preamble (i.e. any
+\dd When this is set to \c{true}, the document \i{preamble} (i.e. any
 paragraphs appearing before the first chapter heading) will be
 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
 this setting is \c{false}, the document preamble will not be
 indented at all from the left margin.
 
 paragraphs appearing before the first chapter heading) will be
 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
 this setting is \c{false}, the document preamble will not be
 indented at all from the left margin.
 
-\S{output-text-headings} Configuring heading display
+\S{output-text-headings} \ii{Configuring heading display}
 
 The directives in this section allow you to configure the appearance
 of the title, chapter and section headings in your text file.
 
 
 The directives in this section allow you to configure the appearance
 of the title, chapter and section headings in your text file.
 
-Several of the directives listed below specify the alignment of a
-heading. These alignment options have three possible values:
+Several of the directives listed below specify the \i{alignment} of
+heading. These alignment options have three possible values:
 
 
-\dt \c{left}
+\dt \i\c{left}
 
 \dd Align the heading to the very left of the text file (column zero).
 
 
 \dd Align the heading to the very left of the text file (column zero).
 
-\dt \c{leftplus}
+\dt \i\c{leftplus}
 
 \dd Align the section title to the left of the main display region
 (in other words, indented to the level specified by
 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
 left of that (so that it goes in the margin if there is room).
 
 
 \dd Align the section title to the left of the main display region
 (in other words, indented to the level specified by
 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
 left of that (so that it goes in the margin if there is room).
 
-\dt \c{centre}
+\dt \i\c{centre}
 
 \dd Centre the heading.
 
 Also, several of the directives below specify how a title should be
 
 \dd Centre the heading.
 
 Also, several of the directives below specify how a title should be
-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\{-\}}.
+\I{underlining}underlined. The parameter to one of these directives
+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\{\-\}}.
 
 
-\dt \cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
+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}.
 
 
 \dd Specifies the alignment of the overall document title: \c{left},
 \c{leftplus} or \c{centre}.
 
-\dt \cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
 
 \dd Specifies how the overall document title should be underlined.
 
 
 \dd Specifies how the overall document title should be underlined.
 
-\dt \cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
+\dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
 
 \dd Specifies the alignment of chapter and appendix headings.
 
 
 \dd Specifies the alignment of chapter and appendix headings.
 
-\dt \cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
 
 \dd Specifies how chapter and appendix headings should be underlined.
 
 
 \dd Specifies how chapter and appendix headings should be underlined.
 
-\dt \cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-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
@@ -125,14 +140,14 @@ 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 \cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
+\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
 like \q{Chapter 2: Doing Things}.
 
 
 \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
 like \q{Chapter 2: Doing Things}.
 
-\dt \cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
 
 \dd Specifies the alignment of section headings at a particular
 level. The \e{level} parameter specifies which level of section
 
 \dd Specifies the alignment of section headings at a particular
 level. The \e{level} parameter specifies which level of section
@@ -141,36 +156,119 @@ 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 \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-character}\cw{\}}
 
 \dd Specifies how to underline section headings at a particular level.
 
 
 \dd Specifies how to underline section headings at a particular level.
 
-\dt \cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
 
 \dd Specifies whether section headings at a particular level should
 contain the word \q{Section} or equivalent (if \c{false}), or should
 be numeric only (if \c{true}).
 
 
 \dd Specifies whether section headings at a particular level should
 contain the word \q{Section} or equivalent (if \c{false}), or should
 be numeric only (if \c{true}).
 
-\dt \cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
 
 
-\dd Specifies the suffix text to be appended to section numbers at a
-particular level, before displaying the section title.
+\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-characters} Configuring the characters used
+
+\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\}\{(*)\}}).
+
+\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 \q{\cw{-=}} 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
 
 
 \S{output-text-misc} Miscellaneous configuration options
 
-\dt \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}, version ID paragraphs (defined using the
-\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.
 
 
-\dt \cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}
+\lcont{
 
 
-\dd This specifies the text which should be used as the bullet in
-bulletted lists. It can be one character
-(\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
-(\cw{\\cfg\{text-bullet\}\{(*)\}}).
+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-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.
@@ -179,8 +277,10 @@ bulletted lists. It can be one character
 
 \S{output-text-defaults} Default settings
 
 
 \S{output-text-defaults} Default settings
 
-The default settings for Halibut's plain text output format are:
+The \i{default settings} for Halibut's plain text output format are:
 
 
+\c \cfg{text-filename}{output.txt}
+\c
 \c \cfg{text-width}{68}
 \c \cfg{text-indent}{7}
 \c \cfg{text-indent-code}{2}
 \c \cfg{text-width}{68}
 \c \cfg{text-indent}{7}
 \c \cfg{text-indent-code}{2}
@@ -189,10 +289,10 @@ The 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-suffix}{: }
 \c
 \c \cfg{text-chapter-numeric}{false}
 \c \cfg{text-chapter-suffix}{: }
 \c
@@ -208,22 +308,103 @@ The default settings for Halibut's plain text output format are:
 \c
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
 \c
 \c ... and so on for all section levels below this ...
 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{text-bullet}{\u2022}{-}
+\c \cfg{text-rule}{\u2500}{-}
+\c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
+\c \cfg{text-emphasis}{_}{_}
+\c
+\c \cfg{text-charset}{ASCII}
+\c \cfg{text-list-suffix}{.}
+\c \cfg{text-versionid}{true}
 
 \H{output-html} HTML
 
 
 \H{output-html} HTML
 
-This output format generates an HTML version of the document. By
+This output format generates an \i{HTML} version of the document. By
 default, this will be in multiple files, starting with
 \c{Contents.html} and splitting the document into files by chapter
 and/or subsection. You can configure precisely how the text is split
 between HTML files using the configuration commands described in
 this section. In particular, you can configure Halibut to output one
 default, this will be in multiple files, starting with
 \c{Contents.html} and splitting the document into files by chapter
 and/or subsection. You can configure precisely how the text is split
 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, in which case it will be
-called \c{Manual.html} (but you can rename it easily enough).
+single HTML file instead of multiple ones.
 
 
-Strictly speaking, the output format is XHTML 1.0 Transitional,
+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}.
 
 which is why all of the configuration directives start with the word
 \c{xhtml} rather than \c{html}.
 
+\S{output-html-file} Controlling the output file names
+
+\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-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
+\c{index.html} (although this is not the default, for historical
+reasons).
+
+\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
+
+\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{\}}
+
+\dd Provides a \i{template} to be used when constructing the file
+names of each chapter or section of the document. This template
+should contain at least one \i\e{formatting command}, in the form of
+a per cent sign followed by a letter. (If you need a literal per
+cent sign, you can write \c{%%}.)
+
+\lcont{
+
+The formatting commands used in this template are:
+
+\dt \I{%N-upper}\c{%N}
+
+\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}}.
+
+\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.
+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}.
+
+\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
+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
+\k{output-html-misc}).
+
+}
+
+\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the file name in which to store the entire document, if
+Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
+produce a single self-contained file. Both this directive \e{and}
+\c{\\cfg\{xhtml-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}).
+
 \S{output-html-split} Controlling the splitting into HTML files
 
 By default, the HTML output from Halibut is split into multiple
 \S{output-html-split} Controlling the splitting into HTML files
 
 By default, the HTML output from Halibut is split into multiple
@@ -237,27 +418,34 @@ 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 \cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
 
 \dd This setting indicates the depth of section which should be
 
 \dd This setting indicates the depth of section which should be
-given a \q{leaf} file (a file with no sub-files). So if you set it
-to 1, for example, then every chapter will be given its own HTML
-file, plus a top-level contents file. If you set this to 2, then
-each chapter \e{and} each \c{\\H} section will have a file, and the
-chapter files will mostly just contain links to their sub-files.
+given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
+you set it to 1, for example, then every chapter will be given its
+own HTML file, plus a top-level \i{contents file}. If you set this
+to 2, then each chapter \e{and} each \c{\\H} section will have a
+file, and the chapter files will mostly just contain links to their
+\i{sub-file}s.
 
 \lcont{
 
 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
 
 \lcont{
 
 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
-\c{Manual.html} instead of \c{Contents.html}.
+\i\c{Manual.html} instead of \i\c{Contents.html}.
+
+This option is automatically set to zero if you provide a file name
+parameter after the command-line option \i\c{--html} (see
+\k{running-options}), because you have specified a single file name
+and so Halibut assumes you want the whole document to be placed in
+that file.
 
 }
 
 
 }
 
-\dt \cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
 
 
-\dd This directive allows you to specify how deep the contents
-section in a particular file should go.
+\dd This directive allows you to specify how \I{depth of
+contents}deep the contents section in a particular file should go.
 
 \lcont{
 
 
 \lcont{
 
@@ -282,12 +470,12 @@ to \c{\\S} level, but not to go into any more detail than that.
 \# the level as a separate argument, like the text section config
 \# directives. Secondly, it shouldn't be limited in depth!
 
 \# the level as a separate argument, like the text section config
 \# directives. Secondly, it shouldn't be limited in depth!
 
-\dt \cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-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 \cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-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
@@ -298,64 +486,65 @@ generating it at all.
 \S{output-html-html} Including pieces of your own HTML
 
 The directives in this section allow you to supply pieces of
 \S{output-html-html} Including pieces of your own HTML
 
 The directives in this section allow you to supply pieces of
-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 \cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-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 \cw{<HEAD>} section of each output HTML file. So this is a good
-place to put, for example, a link to a CSS stylesheet.
+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 \cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is used in place of the
 
 \dd The text you provide in this directive is used in place of the
-\cw{<BODY>} tag in each output file. So if you wanted to define a
-background colour, for example, you could write
+\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\{xhtml-body-tag\}\{<body bg="#123456">\}}.
 
-\dt \cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the
 
 \dd The text you provide in this directive is placed at the
-beginning of the \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
-house style, and the style needs a header at the top of every page,
-this is where you can add that header.
+beginning 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{header} at the
+top of every page, this is where you can add that header.
 
 
-\dt \cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
 
 
-\dd The text you provide in this directive is placed at the
-end of the \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
-house style, and the style needs a footer at the bottom of every page,
-this is where you can add that footer.
+\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.
 
 
-\dt \cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
 
 \dd The text you provide in this directive is placed at the
 
 \dd The text you provide in this directive is placed at the
-beginning of the \cw{<ADDRESS>} section at the bottom of each output
-HTML file. This might be a good place to put authors' contact
-details, for example.
+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 \cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
 
 
-\dd The text you provide in this directive is placed at the
-end of the \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 \cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
 
 \dd The text you provide in this directive is included inside the
 
 \dd The text you provide in this directive is included inside the
-\cw{<P>} tag containing the navigation links at the top of each page
-(\q{Previous} / \q{Contents} / \q{Next}). So if you wanted the
-navigation links to have a particular CSS style, you could write
+\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
 navigation-links paragraph would then begin with the tag \cw{<p
 class="foo">}.
 
 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
 navigation-links paragraph would then begin with the tag \cw{<p
 class="foo">}.
 
-\S{output-html-headings} Configuring heading display
+\S{output-html-headings} \ii{Configuring heading display}
 
 
-\dt \cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-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
@@ -364,14 +553,14 @@ 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 \cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-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
 like \q{Chapter 2: Doing Things}.
 
 
 \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
 like \q{Chapter 2: Doing Things}.
 
-\dt \cw{\\cfg\{xhtml-section-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
 
 \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
@@ -380,45 +569,63 @@ 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 \cw{\\cfg\{xhtml-section-suffix\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
 
 \dd Specifies the suffix text to be appended to section numbers at a
 particular level, before displaying the section title.
 
 \S{output-html-misc} Miscellaneous options
 
 
 \dd Specifies the suffix text to be appended to section numbers at a
 particular level, before displaying the section title.
 
 \S{output-html-misc} Miscellaneous options
 
-\dt \cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
+
+\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
+addressable by means of a URL ending in a \c{#} followed by your
+internal section keyword.
 
 
-\dd If this is set to \c{true}, version ID paragraphs (defined using
-the \c{\\versionid} command - see \k{input-blurb}) will be included
-visibly in the \cw{<ADDRESS>} section at the bottom of each HTML
+\dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-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
 file. If it is set to \c{false}, they will be omitted completely.
 
 \# FIXME: surely it would be better to include them in HTML
 \# comments? The only question is whether they should be _visible_.
 
 file. If it is set to \c{false}, they will be omitted completely.
 
 \# FIXME: surely it would be better to include them in HTML
 \# comments? The only question is whether they should be _visible_.
 
-\dt \cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
 
 
-\dd If this is set to \c{true}, the \cw{<ADDRESS>} section at the
+\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
 bottom of each HTML file will be omitted completely. (This will
-therefore also cause version IDs not to be included.)
+therefore also cause \i{version IDs} not to be included.)
 
 
-\dt \cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
 
 
-\dd The text supplied here goes in a \cw{<META name="author">} tag
-in the output HTML files, so that browsers which support this can
-automatically identify the 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 \cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
 
 
-\dd The text supplied here goes in a \cw{<META name="description">}
-tag in the output HTML files, so that browsers which support this
-can easily pick out a brief 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-defaults} Default settings
 
 
 \S{output-html-defaults} Default settings
 
-The default settings for Halibut's HTML output format are:
+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-leaf-level}{2}
 \c \cfg{xhtml-leaf-contains-contents}{false}
 \c \cfg{xhtml-leaf-smallest-contents}{4}
@@ -456,25 +663,68 @@ The default settings for Halibut's HTML output format are:
 
 \H{output-whlp} Windows Help
 
 
 \H{output-whlp} Windows Help
 
-This output format generates data that can be used by the Windows
-Help program \cw{WINHELP.EXE}. There are two actual files generated,
-called \c{output.hlp} and \c{output.cnt}. (You can rename them both
-with no problems; they don't depend on keeping those filenames. You
-just have to make sure that the two names are related in this way,
-so that \c{.hlp} on the end of one name is replaced by \c{.cnt} on
-the end of the other.)
+This output format generates data that can be used by the \i{Windows
+Help} program \cw{WINHELP.EXE}. There are two actual files
+generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
+
+The output is in the \q{\i{Win1252}} character set.
 
 
-The Windows Help output format is currently not configurable at all;
-all formatting decisions are fixed. However, there is one
-configuration directive you can use, which is not so much
-\e{configuration} as extra functionality:
+The Windows Help output format supports the following configuration
+directives:
 
 
-\dt \cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\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.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--winhelp} (see
+\k{running-options}).
+
+\lcont{
+
+Your output file name should end with \c{.hlp}; if it doesn't,
+Halibut will append it. Halibut will also generate a contents file
+(ending in \c{.cnt}) alongside the file name you specify.
+
+}
 
 
-\dd This directive defines a Windows Help topic name in the current
+\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-misc}).
+
+\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}).
+
+\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
 section. Topic names can be used by the program invoking
 \cw{WINHELP.EXE} to jump straight to a particular section. So you
 section. Topic names can be used by the program invoking
 \cw{WINHELP.EXE} to jump straight to a particular section. So you
-can use this for context-sensitive help.
+can use this for \i{context-sensitive help}.
 
 \lcont{
 
 
 \lcont{
 
@@ -494,20 +744,38 @@ different help contexts which you can use in this way.
 
 }
 
 
 }
 
+The \i{default settings} for the Windows Help output format are:
+
+\c \cfg{winhelp-filename}{output.hlp}
+\c \cfg{winhelp-contents-titlepage}{Title page}
+\c \cfg{winhelp-section-suffix}{: }
+\c \cfg{winhelp-list-suffix}{.}
+\c \cfg{winhelp-bullet}{\u2022}{-}
+\c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
+
+and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
+
 \H{output-man} Unix \cw{man} pages
 
 \H{output-man} Unix \cw{man} pages
 
-This output format generates a Unix \cw{man} page. That is to say,
-it generates \c{nroff} input designed to work with the \c{-mandoc}
+This output format generates a Unix \i{\cw{man} page}. That is to say,
+it generates \i\c{nroff} input designed to work with the \c{-mandoc}
 macro package.
 
 The available configuration options for this format are as follows:
 
 macro package.
 
 The available configuration options for this format are as follows:
 
-\dt \cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
+\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.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--man} (see
+\k{running-options}).
+
+\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 \c{.TH} directive
-that appears at the top of a \cw{man} page. It expects to be
-followed by some number of brace pairs containing text, which will
-be used in the headers and footers of the formatted output.
+\dd This directive is used to generate the initial \i{\c{.TH}
+directive} that appears at the top of a \cw{man} page. It expects to
+be followed by some number of brace pairs containing text, which will
+be used in the \i{headers} and \i{footers} of the formatted output.
 
 \lcont{
 
 
 \lcont{
 
@@ -521,25 +789,26 @@ A traditional order for the arguments appears to be:
 
 \n The name of any containing suite of which the program is a part.
 
 
 \n The name of any containing suite of which the program is a part.
 
-\n The name of the author of the \cw{man} page.
+\n The name of the \i{author} of the \cw{man} page.
 
 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}
 
 }
 
 
 }
 
-\dt \cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
 
 
-\dd If this is set to \c{true}, then section headings in the
-\cw{man} page will have their section numbers displayed as usual. If
+\dd If this is set to \c{true}, then \i{section headings} in the
+\cw{man} page will have their \i{section numbers} displayed as usual. If
 set to \c{false}, the section numbers will be omitted. (\cw{man}
 pages traditionally have section names such as \q{SYNOPSIS},
 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
 \c{false} is the setting which conforms most closely to normal
 \cw{man} style.)
 
 set to \c{false}, the section numbers will be omitted. (\cw{man}
 pages traditionally have section names such as \q{SYNOPSIS},
 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
 \c{false} is the setting which conforms most closely to normal
 \cw{man} style.)
 
-\dt \cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
 
 \dd If this is set to a number greater than 0, then section headings
 \e{higher} than the given depth will not be displayed. If it is set
 
 \dd If this is set to a number greater than 0, then section headings
 \e{higher} than the given depth will not be displayed. If it is set
@@ -567,7 +836,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 
@@ -597,8 +867,291 @@ expect.
 
 }
 
 
 }
 
-The default settings for the \cw{man} page output format are:
+\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-misc}).
+
+\# 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-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}).
+
+The \i{default settings} for the \cw{man} page output format are:
+
+\c \cfg{man-filename}{output.1}
 \c \cfg{man-identity}{}
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
 \c \cfg{man-identity}{}
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
+\c \cfg{man-charset}{ASCII}
+\c \cfg{man-bullet}{\u2022}{o}
+\c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
+
+\H{output-info} GNU \c{info}
+
+This output format generates files which can be used with the \i{GNU
+\c{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 \c{info} output format supports the following configuration
+directives:
+
+\dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the output file name in which to store the \c{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 \c{info} files refer to their own names internally, so
+these files cannot be \I{renaming \c{info} files}renamed after
+creation and remain useful.
+
+}
+
+\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}).
+
+\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-misc}).
+
+\# 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-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
+\q{\cw{:\_}}, then a typical section title might look something like
+\q{Section 3.1: Something Like This}.
+
+\dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to be used to underline section titles. Works
+very much like the \cw{\\cfg\{text-chapter-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-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}).
+
+\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-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 \c{info} nodes may not be
+split between files).
+
+}
+
+\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
+\c{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.
+
+}
+
+The \i{default settings} for the \c{info} output format are:
+
+\c \cfg{info-filename}{output.info}
+\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-charset}{ASCII}
+\c
+\c \cfg{info-section-suffix}{: }
+\c
+\c \cfg{info-underline}{\u203e}{-}
+\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}{.}
+\c \cfg{info-max-file-size}{65536}
+
+and no \cw{\\cfg\{info-dir-entry\}} directives.
+
+\H{output-ps} \i{PostScript}
+
+This output format generates a printable manual in PostScript format.
+
+This format is currently very new and is not yet configurable. There
+is only one available configuration option:
+
+\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}
+
+\H{output-pdf} \i{PDF}
+
+This output format generates a printable manual in PDF format. This
+should look exactly identical to the PostScript output (see
+\k{output-ps}), but also uses some PDF interactive features to
+provide an outline of all the document's sections and clickable
+cross-references between sections.
+
+This format is currently very new and is not yet configurable. There
+is only one available configuration option:
+
+\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}