X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/16ea3abeef2cdf062cd0270d920fc5ed47f94ff9..refs/heads/master:/doc/output.but
diff --git a/doc/output.but b/doc/output.but
index 591952f..49a6b05 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -1,122 +1,139 @@
+\versionid $Id$
+
\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
-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 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
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
-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.
-\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.
-\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
-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
-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\}}.
-\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.
-\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.
-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
+a 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).
-\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).
-\dt \c{centre}
+\dt \i\c{centre}
\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\{\-\}}.
+
+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 \cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
+\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 \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.
-\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.
-\dt \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.
-\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
@@ -125,14 +142,22 @@ 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.
-\dt \cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
+\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
-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 \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
@@ -141,37 +166,129 @@ 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.
-\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-text}\cw{\}}
\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}).
-\dt \cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
-\dd Specifies the suffix text to be appended to section numbers at a
-particular level, before displaying the section title.
+\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\}}.
-\S{output-text-misc} Miscellaneous configuration options
+\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 \cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
+\S{output-text-characters} Configuring the characters used
-\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.
+\dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}}
+
+\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 \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.
-\dd This specifies the text which should be used as the bullet in
-bulletted lists. It can be one character
+}
+
+\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 \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.
@@ -179,8 +296,10 @@ bulletted lists. It can be one character
\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}
@@ -189,40 +308,124 @@ 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-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-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-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-shownumber}{1}{true}
\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
-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
-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.
+
+\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
+
+\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
+\c{index.html} (although this is not the default, for historical
+reasons).
+
+\dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}}
-Strictly speaking, the output format is XHTML 1.0 Transitional,
-which is why all of the configuration directives start with the word
-\c{xhtml} rather than \c{html}.
+\dd Sets the file name in which to store the document's index.
+
+\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
+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 \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
+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}
+
+\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.
+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
+\cw{\\cfg\{html-template-fragment\}} configuration directive (see
+\k{output-html-misc}).
+
+}
+
+\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
+Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to
+produce a single self-contained file. Both this directive \e{and}
+\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}).
\S{output-html-split} Controlling the splitting into HTML files
@@ -237,27 +440,39 @@ 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.
-\dt \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 \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
-\c{Manual.html} instead of \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
+\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.
+
+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 \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 deep the contents
-section in a particular file should go.
+\dd This directive allows you to specify how \I{depth of
+contents}deep any contents section in a particular level of file
+should go.
\lcont{
@@ -265,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}
-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.
-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.
-}
+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 \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.
-\dt \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
@@ -298,64 +512,92 @@ 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
-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{\}}
+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 \cw{
} 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{} 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\{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{} 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{} 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:
-\dt \cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
+\c \cfg{html-local-head}{}
+
+}
+
+\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
-\cw{} tag in each output file. So if you wanted to define a
-background colour, for example, you could write
-\cw{\\cfg\{xhtml-body-tag\}\{\}}.
+\i\cw{} tag in each output file. So if you wanted to define a
+\i{background colour}, for example, you could write
+\cw{\\cfg\{html-body-tag\}\{\}}.
-\dt \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 \cw{} 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{} 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\{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 the \cw{} 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{} 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 \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 \cw{} 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{} 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\{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 \cw{} 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{} 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\{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{
} 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{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
+\cw{
} 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\{html-navigation-attributes\}\{class="foo"\}}, and the
navigation-links paragraph would then begin with the tag \cw{
}.
-\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\{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
@@ -364,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.
-\dt \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
-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 \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
@@ -380,101 +632,476 @@ 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 \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.
+\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{