X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/339cbe09f017eb521e1d623b70a59b902dbc4711..c554651464773994d9731a6fdd3be58b9a242eb8:/doc/output.but

diff --git a/doc/output.but b/doc/output.but
index 5c70e72..9b5af88 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -8,7 +8,7 @@ that format.
 \H{output-text} Plain text
 
 This output format generates the document as a single \i{plain text}
-file, under the name \i\c{output.txt}.
+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
@@ -19,6 +19,15 @@ 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
@@ -98,11 +107,17 @@ 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
-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{\}}
 
@@ -162,8 +177,98 @@ be numeric only (if \c{true}).
 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{
+
+You can specify multiple possible options (each in their own pair of
+braces) after this command, and Halibut will choose the first one
+which the output character set supports. (This is to allow you to
+configure the bullet character once, generate output in several
+different character sets, and have Halibut constantly adapt to make
+the best use of the current encoding.) 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 the quote characters which should be used in
+response to the \c{\\q} command (see \k{input-quotes}). These quotes
+will also be used to mark text enclosed in the \c{\\c} command (see
+\k{input-code}).
+
+\lcont{
+
+You should separately specify the open and close quote characters,
+each of which can be more than one character if you want. Also, like
+\cw{\\cfg\{text-bullet\}}, you can specify multiple fallback options
+in this command (a pair of open and close quotes, then another pair,
+then another if you like); Halibut will always use a matching pair.
+For example, you might write
+
+\c \cfg{text-quotes}{\u201c}{\u201d}{"}{"}
+
+and Halibut would use the Unicode matched double quote characters if
+possible, and fall back to ASCII double quotes otherwise. If the
+output character set were to contain U+201C but not U+201D, then
+Halibut would fall back to using the ASCII double quote character as
+\e{both} open and close quotes. (No known character set is that
+silly; I mention it only as an example.)
+
+}
+
+\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
@@ -171,13 +276,6 @@ 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.
 
-\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\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\}\{(*)\}}).
-
 \# FIXME: code indentation is configurable, therefore \quote
 \# indentation probably ought to be as well.
 
@@ -187,6 +285,8 @@ in bulletted lists. It can be one character
 
 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}
@@ -195,10 +295,10 @@ 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-title-underline}{=}
+\c \cfg{text-title-underline}{\u2550}{=}
 \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
@@ -214,6 +314,14 @@ The \i{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 \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
 
@@ -223,13 +331,85 @@ default, this will be in multiple files, starting with
 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 \i{XHTML} 1.0 Transitional,
 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
@@ -259,6 +439,12 @@ 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}.
 
+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 \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
@@ -379,7 +565,7 @@ 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 \I{\cw{\\cfg\{xhtml-section-numeric\}}}\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
@@ -388,13 +574,24 @@ 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.
 
-\dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\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
 
+\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.
+
 \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
@@ -428,6 +625,12 @@ document}description of the document.
 
 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}
@@ -466,17 +669,26 @@ The \i{default settings} for Halibut's HTML output format are:
 \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 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.)
-
-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:
+Help} program \cw{WINHELP.EXE}. There are two actual files
+generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
+
+The Windows Help output format supports the following configuration
+directives:
+
+\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.
+
+}
 
 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
 
@@ -503,6 +715,12 @@ 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}
+
+and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
+
 \H{output-man} Unix \cw{man} pages
 
 This output format generates a Unix \i{\cw{man} page}. That is to say,
@@ -511,6 +729,13 @@ macro package.
 
 The available configuration options for this format are as follows:
 
+\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 \i{\c{.TH}
@@ -534,7 +759,8 @@ A traditional order for the arguments appears to be:
 
 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}
 
 }
 
@@ -576,7 +802,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:
 
-\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 
@@ -608,6 +835,252 @@ expect.
 
 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}
+
+\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-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. 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-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}