X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/da090173a115e3450b23e6b84aa98972c4f1619e..e0e55d4168c693e814dbeea1604acd01d330c61f:/doc/output.but?ds=sidebyside

diff --git a/doc/output.but b/doc/output.but
index 9b5af88..964f49d 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 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
@@ -115,7 +110,7 @@ example, \cw{\\text-title-underline\{=\}} but
 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
+\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.
 
@@ -124,7 +119,7 @@ the ASCII minus sign otherwise.
 \dd Specifies the alignment of the overall document title: \c{left},
 \c{leftplus} or \c{centre}.
 
-\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how the overall document title should be underlined.
 
@@ -132,7 +127,7 @@ the ASCII minus sign otherwise.
 
 \dd Specifies the alignment of chapter and appendix headings.
 
-\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how chapter and appendix headings should be underlined.
 
@@ -149,7 +144,7 @@ be prefixed by \q{Chapter} or equivalent.
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
-this to \q{\cw{:\_}}, then the chapter title might look something
+this to \cq{:\_}, then the chapter title might look something
 like \q{Chapter 2: Doing Things}.
 
 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
@@ -161,7 +156,7 @@ headings you want to affect: 0 means first-level headings (\c{\\H}),
 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
 just like the other alignment directives listed above.
 
-\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}}
+\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}}
 
 \dd Specifies how to underline section headings at a particular level.
 
@@ -179,6 +174,22 @@ displaying the section title.
 
 \S{output-text-characters} Configuring the characters used
 
+\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-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}
@@ -188,12 +199,9 @@ in bulletted lists. It can be one character
 
 \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
+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,
@@ -207,7 +215,7 @@ and resort to the ASCII asterisk if all else failed.
 \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
+you can specify something like \cq{-=} to get a rule that looks
 like \cw{-=-=-=}.
 
 \lcont{
@@ -219,28 +227,14 @@ 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}).
+\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{
 
-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.)
+In this backend, these quotes will also be used to mark text enclosed
+in the \c{\\c} command (see \k{input-code}).
 
 }
 
@@ -315,6 +309,7 @@ The \i{default settings} for Halibut's plain text output format are:
 \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}{`}{'}
@@ -325,6 +320,9 @@ The \i{default settings} for Halibut's plain text output format are:
 
 \H{output-html} HTML
 
+\# FIXME: this probably needs major revision due to the new HTML
+backend
+
 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
@@ -366,15 +364,15 @@ 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}}.
+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 \q{\cw{Chapter1}}; in
-section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
+space. So in chapter 1 this would expand to \cq{Chapter1}; in
+section A.4.3 it would expand to \cq{SectionA.4.3}, and so on.
 If the section has no number (an unnumbered chapter created using
 \c{\\U}), this directive falls back to doing the same thing as
 \c{%N}.
@@ -382,16 +380,16 @@ If the section has no number (an unnumbered chapter created using
 \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
+would expand to \cq{1}; in section A.4.3 it would expand to
+\cq{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
+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}.
 
@@ -562,7 +560,7 @@ be prefixed by \q{Chapter} or equivalent.
 
 \dd This specifies the suffix text to be appended to the chapter
 number, before displaying the chapter title. For example, if you set
-this to \q{\cw{:\_}}, then the chapter title might look something
+this to \cq{:\_}, then the chapter title might look something
 like \q{Chapter 2: Doing Things}.
 
 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
@@ -587,7 +585,7 @@ particular level, before displaying the section title.
 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}},
+within a particular HTML file. So if you set this to \cq{%k},
 for example, then each individual section in your document will be
 addressable by means of a URL ending in a \c{#} followed by your
 internal section keyword.
@@ -672,9 +670,14 @@ 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}.
 
+Currently, the output is harcoded to be in the \q{\i{Win1252}}
+character set.
+
 The Windows Help output format supports the following configuration
 directives:
 
+\S{output-whlp-file} Output file name
+
 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the \i{output file name} in which to store the man page.
@@ -690,6 +693,42 @@ Halibut will append it. Halibut will also generate a contents file
 
 }
 
+\S{output-whlp-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see
+\k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{winhelp-quotes\}}}\cw{\\cfg\{winhelp-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-whlp-misc} Miscellaneous configuration options
+
+\dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
+
+\dd Sets the text used to describe the help page containing the blurb
+(see \k{input-blurb}) and table of contents.
+
+\dt
+\I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
+
+\dd Specifies the \I{suffix text, in section titles}suffix text to
+be appended to section numbers, before displaying the section title.
+(Applies to all levels.)
+
+\dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
+
+\dd This text is appended to the number on a \i{numbered list} item,
+in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
+\k{output-text-characters}).
+
 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
 
 \dd This directive defines a Windows \i{Help topic} name in the current
@@ -715,9 +754,18 @@ different help contexts which you can use in this way.
 
 }
 
+\S{output-whlp-defaults} Default settings
+
 The \i{default settings} for the Windows Help output format are:
 
 \c \cfg{winhelp-filename}{output.hlp}
+\c
+\c \cfg{winhelp-bullet}{\u2022}{-}
+\c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
+\c
+\c \cfg{winhelp-contents-titlepage}{Title page}
+\c \cfg{winhelp-section-suffix}{: }
+\c \cfg{winhelp-list-suffix}{.}
 
 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
 
@@ -729,6 +777,8 @@ macro package.
 
 The available configuration options for this format are as follows:
 
+\S{output-man-file} Output file name
+
 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the \i{output file name} in which to store the man page.
@@ -736,6 +786,8 @@ This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--man} (see
 \k{running-options}).
 
+\S{output-man-identity} Configuring headers and footers
+
 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
 
 \dd This directive is used to generate the initial \i{\c{.TH}
@@ -764,6 +816,8 @@ For example, a typical \cw{man} page might contain
 
 }
 
+\S{output-man-headings} Configuring heading display
+
 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
 
 \dd If this is set to \c{true}, then \i{section headings} in the
@@ -833,12 +887,43 @@ expect.
 
 }
 
+\S{output-man-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
+
+\dd Specifies what character set the output should be in, similarly to
+\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
+
+\# FIXME: you're probably on your own in making sure that it's
+sensible to output man pages in that charset.
+
+\dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{man-quotes\}}}\cw{\\cfg\{man-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-man-defaults} Default settings
+
 The \i{default settings} for the \cw{man} page output format are:
 
 \c \cfg{man-filename}{output.1}
+\c
 \c \cfg{man-identity}{}
+\c
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
+\c
+\c \cfg{man-charset}{ASCII}
+\c \cfg{man-bullet}{\u2022}{o}
+\c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
 
 \H{output-info} GNU \c{info}
 
@@ -855,6 +940,8 @@ document.
 The \c{info} output format supports the following configuration
 directives:
 
+\S{output-info-file} Controlling the output filenames
+
 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
 
 \dd Sets the output file name in which to store the \c{info} file.
@@ -873,6 +960,25 @@ creation and remain useful.
 
 }
 
+\dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
+
+\dd Sets the preferred \i{maximum file size} for each subsidiary
+file. As a special case, if you set this to zero, there will be no
+subsidiary files and the whole document will be placed in a single
+self-contained output file. (However, note that this file can still
+not be renamed usefully.)
+
+\lcont{
+
+The preferred maximum file size is only a guideline. Halibut may be
+forced to exceed it if a single section of the document is larger
+than the maximum size (since individual \c{info} nodes may not be
+split between files).
+
+}
+
+\S{output-info-dimensions} Indentation and line width
+
 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
 
 \dd Sets the \I{text width}width of the main part of the document,
@@ -905,11 +1011,13 @@ directive (see \k{output-text-dimensions}).
 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
 directive (see \k{output-text-dimensions}).
 
+\S{output-info-headings} Configuring heading display
+
 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
 
 \dd Specifies the suffix text to be appended to each section number
 before displaying the section title. For example, if you set this to
-\q{\cw{:\_}}, then a typical section title might look something like
+\cq{:\_}, 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{\}}...]
@@ -920,6 +1028,18 @@ very much like the \cw{\\cfg\{text-chapter-underline\}} directive
 option, and Halibut will choose the first one supported by the
 character set.
 
+\S{output-info-characters} Controlling the characters used
+
+\dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
+
+\dd Specifies what character set the output should be in, similarly to
+\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
+
+\# FIXME: if you try sufficiently hard, you can probably find an
+output encoding that will break the info format by trampling on its
+special characters. So either don't do that, or tell us what we should
+do about it.
+
 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
 
 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
@@ -935,7 +1055,8 @@ specify multiple fallback options. Works exactly like the
 
 \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
+\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}).
 
@@ -946,6 +1067,8 @@ multiple fallback options. Works exactly like the
 \cw{\\cfg\{text-emphasis\}} directive (see
 \k{output-text-characters}).
 
+\S{output-info-misc} Miscellaneous configuration options
+
 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
 
 \dd Specifies the text to append to the item numbers in a
@@ -953,23 +1076,6 @@ multiple fallback options. 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{\}}]
 
@@ -1022,9 +1128,12 @@ if the output file were called \c{mygames.info} and the keyword
 
 }
 
+\S{output-info-defaults} Default settings
+
 The \i{default settings} for the \c{info} output format are:
 
 \c \cfg{info-filename}{output.info}
+\c \cfg{info-max-file-size}{65536}
 \c
 \c \cfg{info-width}{70}
 \c \cfg{info-indent-code}{2}
@@ -1033,24 +1142,28 @@ The \i{default settings} for the \c{info} output format are:
 \c \cfg{info-listitem-indent}{3}
 \c
 \c \cfg{info-section-suffix}{: }
-\c
 \c \cfg{info-underline}{\u203e}{-}
+\c
+\c \cfg{info-charset}{ASCII}
 \c \cfg{info-bullet}{\u2022}{-}
 \c \cfg{info-rule}{\u2500}{-}
 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
 \c \cfg{info-emphasis}{_}{_}
 \c
 \c \cfg{info-list-suffix}{.}
-\c \cfg{info-max-file-size}{65536}
 
 and no \cw{\\cfg\{info-dir-entry\}} directives.
 
-\H{output-ps} \i{PostScript}
+\H{output-paper} Paper formats
+
+These output formats (currently PostScript and PDF) generate printable
+manuals. As such, they share a number of configuration directives.
+
+\S{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:
+There is one configuration option specific to PostScript:
 
 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
 
@@ -1063,7 +1176,7 @@ The \i{default settings} for the PostScript output format are:
 
 \c \cfg{ps-filename}{output.ps}
 
-\H{output-pdf} \i{PDF}
+\S{output-pdf} \i{PDF}
 
 This output format generates a printable manual in PDF format. This
 should look exactly identical to the PostScript output (see
@@ -1071,8 +1184,7 @@ should look exactly identical to the PostScript output (see
 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:
+There is one configuration option specific to PDF:
 
 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
 
@@ -1084,3 +1196,215 @@ parameter after the command-line option \i\c{--pdf} (see
 The \i{default settings} for the PDF output format are:
 
 \c \cfg{pdf-filename}{output.pdf}
+
+\S{output-paper-dimensions} Configuring layout and \i{measurements}
+
+All measurements are in PostScript \i{points} (72 points to the inch).
+
+\S2{output-paper-pagesize} Page properties
+
+\dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
+
+\dd Specify the absolute limits of the paper.
+
+\dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
+
+\dd Specify the margins. Most text appears within these margins,
+except:
+
+\lcont{
+
+\b Section numbers, which appear in the left margin.
+
+\b The footer (containing page numbers), which appears in the bottom
+margin.
+
+}
+
+\S2{output-paper-line} Vertical spacing
+
+\dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of space between lines of text within a
+paragraph. (So, if the font size is 12pt and there is 2pt of leading,
+there will be 14pt between successive baselines.)
+
+\dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of vertical space between paragraphs. (The
+vertical space between paragraphs does \e{not} include
+\c{paper-base-leading}.)
+
+\S2{output-paper-indentation} Indentation
+
+\dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the indentation of the bullet or number in a
+\I{bulletted list, indentation}bulletted or \I{numbered list,
+indentation}numbers \I{list, indentation}list, similarly to
+\cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
+
+\dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \e{extra} indentation for the body of a list item,
+over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
+
+\# FIXME: doesn't actually work, AFAICT.
+
+\dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of indentation for a level of quoting. Used
+for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
+(see \k{input-code}).
+
+\S2{output-paper-headings} Headings
+
+\dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
+
+\dd Specifies the space between the top margin \#{XXX check} and the
+top of the chapter heading. (Each chapter begins on a new page.)
+
+\# FIXME: the first page of the Index gets mangled if this is
+set to zero.
+
+\# FIXME: exact relationship to top-margin?
+
+\dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
+
+\dd Specifies the vertical thickness of the black rule under chapter
+headings.
+
+\dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the base of the chapter heading and
+the \e{base} of the underlying rule.
+
+\dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the left margin and the \e{right}
+of section numbers (which are in the left margin).
+
+\S2{output-paper-index} Contents and index
+
+\dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}}
+
+\dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
+
+\# FIXME: I do not know what dees one does. (I couldn't get either of
+them to do anything obvious, although the source indicates they should
+do something.)
+
+\dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
+
+\dd Specifies the horizontal spacing between dots in \i\e{leaders}
+(the dotted lines that appear between section headings and page
+numbers in the table of contents).
+
+\dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
+
+\dd Specifies the distance between the bottom margin and the \e{base}
+of the footer (which contains page numbers).
+
+\dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
+
+\dd Specifies the number of columns the index should be divided into.
+
+\# FIXME: with this set to 1, the right-alignment of some index entry
+page numbers in the Halibut manual is decidedly wonky.
+
+\dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
+
+\dd Specifies the amount of \I{gutter} horizontal space between index
+columns.
+
+\dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
+
+\dd Specifies the minimum allowable horizontal space between an index
+entry and its page number. If the gap is smaller, the page number is
+moved to the next line.
+
+\S2{output-paper-fonts} Fonts
+
+\dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the font size of body text.
+
+\# FIXME: actually, this doesn't appear to do anything at all - most
+font sizes are still hardcoded.
+
+\dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the font size to use for page numbers.
+
+\S2{output-paper-misc} Miscellaneous
+
+\dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
+
+\dd Specifies the vertical thickness of the rule produced by the
+\cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
+reserved for thicker rules.)
+
+\S{output-paper-characters} Configuring the characters used
+
+\dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies the text to use as the \i{bullet} in bulletted lists.
+You can specify multiple fallback options. Works exactly like the
+\cw{\\cfg\{text-bullet\}} directive (see
+\k{output-text-characters}).
+
+\dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
+
+\dd Specifies the quotation marks to use, overriding any
+\cw{\\cfg\{quotes\}} directive. You can specify multiple
+fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
+directive (see \k{output-text-characters}).
+
+\S{output-paper-defaults} Default settings for paper formats
+
+The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
+\i{A4 paper}.
+
+\c \cfg{paper-page-width}{595} 
+\c \cfg{paper-page-height}{841} 
+\c
+\c \cfg{paper-left-margin}{72} 
+\c \cfg{paper-top-margin}{72} 
+\c \cfg{paper-right-margin}{72} 
+\c \cfg{paper-bottom-margin}{108} 
+\c
+\c \cfg{paper-base-leading}{1} 
+\c \cfg{paper-base-para-spacing}{10} 
+\c
+\c \cfg{paper-list-indent}{6} 
+\c \cfg{paper-listitem-indent}{18} 
+\c \cfg{paper-quote-indent}{18} 
+\c
+\c \cfg{paper-chapter-top-space}{72} 
+\c \cfg{paper-chapter-underline-thickness}{3} 
+\c \cfg{paper-chapter-underline-depth}{14} 
+\c \cfg{paper-sect-num-left-space}{12} 
+\c
+\c \cfg{paper-contents-index-step}{24} 
+\c \cfg{paper-contents-margin}{84} 
+\c \cfg{paper-leader-separation}{12} 
+\c \cfg{paper-footer-distance}{32} 
+\c \cfg{paper-index-columns}{2} 
+\c \cfg{paper-index-gutter}{36} 
+\c \cfg{paper-index-minsep}{18} 
+\c
+\c \cfg{paper-base-font-size}{12} 
+\c \cfg{paper-pagenum-font-size}{12} 
+\c
+\c \cfg{paper-rule-thickness}{1} 
+\c
+\c \cfg{paper-bullet}{\u2022}{-}
+\c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}