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

diff --git a/doc/output.but b/doc/output.but
index 986f53d..68fc04e 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -8,12 +8,7 @@ that format.
 \H{output-text} Plain text
 
 This output format generates the document as a single \i{plain text}
-file.
-
-The output file is currently assumed to be in the \i{ISO 8859-1}
-character set. Any Unicode characters representable in this set will
-be output verbatim; any other characters will not be output and
-their \i{fallback text} (if any) will be used instead.
+file. No index is generated.
 
 The precise formatting of the text file can be controlled by a
 variety of configuration directives. They are listed in the
@@ -107,11 +102,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{\}}
 
@@ -171,8 +172,97 @@ 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{
+
+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
 
+\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{
+
+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
@@ -180,13 +270,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.
 
@@ -206,10 +289,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
@@ -225,6 +308,15 @@ 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-charset}{ASCII}
+\c \cfg{text-list-suffix}{.}
+\c \cfg{text-versionid}{true}
 
 \H{output-html} HTML
 
@@ -266,7 +358,7 @@ cent sign, you can write \c{%%}.)
 
 The formatting commands used in this template are:
 
-\dt \i\c{%N}
+\dt \I{%N-upper}\c{%N}
 
 \dd Expands to the visible title of the section, with white space
 removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
@@ -468,7 +560,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
@@ -477,7 +569,7 @@ 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.
@@ -575,6 +667,8 @@ 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 supports the following configuration
 directives:
 
@@ -593,6 +687,38 @@ Halibut will append it. Halibut will also generate a contents file
 
 }
 
+\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
@@ -621,6 +747,11 @@ 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.
 
@@ -736,12 +867,36 @@ expect.
 
 }
 
+\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-charset}{ASCII}
+\c \cfg{man-bullet}{\u2022}{o}
+\c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
 
 \H{output-info} GNU \c{info}
 
@@ -776,6 +931,97 @@ 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
@@ -845,6 +1091,31 @@ if the output file were called \c{mygames.info} and the keyword
 
 }
 
+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.