Make sure (paragraph)->private_data is defined in all cases, on general

[sgt/halibut] / doc / output.but

diff --git a/doc/output.but b/doc/output.but
index 9b5af88..964f49d 100644 (file)
--- 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}
 \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
 
 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
 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.
 
 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}.
 
 \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.
 
 
 \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.
 
 
 \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.
 
 
 \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
 
 \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{\}}
 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.
 
 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.
 
 
 \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
 
 
 \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}
 \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{
 
 
 \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,
 \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
 \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{
 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{\}}]
 
 
 \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{
 
 
 \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 ... 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-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
 
 
 \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
 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
 \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
 
 \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}.
 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
 \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.
 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}.
 
 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
 
 \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{\}}
 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
 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.
 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}.
 
 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:
 
 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.
 \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
 \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}
 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.
 
 
 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
 


@@ -729,6 +777,8 @@ macro package.
 
 The available configuration options for this format are as follows:
 
 
 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.
 \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}).
 
 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}
 \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
 \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}
 The \i{default settings} for the \cw{man} page output format are:
 
 \c \cfg{man-filename}{output.1}

+\c

 \c \cfg{man-identity}{}
 \c \cfg{man-identity}{}

+\c

 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
 \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}
 
 
 \H{output-info} GNU \c{info}
 


@@ -855,6 +940,8 @@ document.
 The \c{info} output format supports the following configuration
 directives:
 
 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.
 \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,
 \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}).
 
 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
 \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{\}}...]
 \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.
 
 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.
 \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{\}}]
 
 
 \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}).
 
 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}).
 
 \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
 \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}).
 
 \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{\}}]
 
 \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}
 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}
 \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 \cfg{info-listitem-indent}{3}
 \c
 \c \cfg{info-section-suffix}{: }

-\c

 \c \cfg{info-underline}{\u203e}{-}
 \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-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.
 
 
 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 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{\}}
 
 
 \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}
 
 
 \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
 
 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.
 
 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{\}}
 
 
 \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}
 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}{'}{'}