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

diff --git a/doc/output.but b/doc/output.but
index c698a2b..49a6b05 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -142,6 +142,14 @@ 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 \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
@@ -168,6 +176,15 @@ just like the other alignment directives listed above.
 contain the word \q{Section} or equivalent (if \c{false}), or should
 be numeric only (if \c{true}).
 
+\dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-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\{text-section-numeric\}}.
+
 \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
@@ -296,16 +313,19 @@ The \i{default settings} for Halibut's plain text output format are:
 \c \cfg{text-chapter-align}{left}
 \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 ...
@@ -586,6 +606,14 @@ 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 \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
@@ -604,6 +632,15 @@ 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\{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?
@@ -946,12 +983,15 @@ The \i{default settings} for Halibut's HTML output format are:
 \c \cfg{html-navigation-attributes}{}
 \c
 \c \cfg{html-chapter-numeric}{false}
+\c \cfg{html-chapter-shownumber}{true}
 \c \cfg{html-chapter-suffix}{: }
 \c
 \c \cfg{html-section-numeric}{0}{true}
+\c \cfg{html-section-shownumber}{0}{true}
 \c \cfg{html-section-suffix}{0}{ }
 \c
 \c \cfg{html-section-numeric}{1}{true}
+\c \cfg{html-section-shownumber}{1}{true}
 \c \cfg{html-section-suffix}{1}{ }
 \c
 \c ... and so on for all section levels below this ...
@@ -1007,7 +1047,7 @@ directives:
 
 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
 
-\dd Sets the \i{output file name} in which to store the man page.
+\dd Sets the \i{output file name} in which to store the help file.
 This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--winhelp} (see
 \k{running-options}).
@@ -1262,10 +1302,10 @@ The \i{default settings} for the \cw{man} page output format are:
 \c \cfg{man-rule}{\u2500}{-}
 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
 
-\H{output-info} GNU \c{info}
+\H{output-info} GNU Info
 
 This output format generates files which can be used with the \i{GNU
-\c{info}} program.
+Info} program.
 
 There are typically multiple output files: a primary file whose name
 usually ends in \c{.info}, and one or more subsidiary files whose
@@ -1274,14 +1314,14 @@ names have numbers on the end, so that they end in \c{.info-1},
 configured to output a single large file containing the whole
 document.
 
-The \c{info} output format supports the following configuration
+The 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.
+\dd Sets the output file name in which to store the Info file.
 This directive is implicitly generated if you provide a file name
 parameter after the command-line option \i\c{--info} (see
 \k{running-options}).
@@ -1291,8 +1331,8 @@ parameter after the command-line option \i\c{--info} (see
 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
 your output file name to produce any subsidiary files required.
 
-Note that \c{info} files refer to their own names internally, so
-these files cannot be \I{renaming \c{info} files}renamed after
+Note that Info files refer to their own names internally, so
+these files cannot be \I{renaming Info files}renamed after
 creation and remain useful.
 
 }
@@ -1309,7 +1349,7 @@ not be renamed usefully.)
 
 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
+than the maximum size (since individual Info nodes may not be
 split between files).
 
 }
@@ -1357,14 +1397,27 @@ before displaying the section title. For example, if you set this to
 \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{\}}...]
+\dt \I{\cw{\\cfg\{info-title-underline\}}}\cw{\\cfg\{info-title-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
+\dd Specifies the text to be used to \I{underlining}underline 
+the overall document title. Works
+very much like the \cw{\\cfg\{text-title-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-chapter-underline\}}}\cw{\\cfg\{info-chapter-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies how chapter and appendix headings should be underlined.
+
+\dt \I{\cw{\\cfg\{info-section-underline\}}}\cw{\\cfg\{info-section-underline\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
+
+\dd Specifies how to underline section headings at a particular level.
+The \e{level} parameter specifies 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.
+
 \S{output-info-characters} Controlling the characters used
 
 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
@@ -1419,7 +1472,7 @@ name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
 header of the Info file. This mechanism is used to automatically
 generate the \i{\c{dir} file} at the root of a Unix system's
-\c{info} collection.
+Info collection.
 
 \lcont{
 
@@ -1467,7 +1520,7 @@ 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:
+The \i{default settings} for the Info output format are:
 
 \c \cfg{info-filename}{output.info}
 \c \cfg{info-max-file-size}{65536}
@@ -1479,7 +1532,13 @@ 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-underline}{\u203e}{-}
+\c \cfg{info-title-underline}{*}
+\c \cfg{info-chapter-underline}{=}
+\c \cfg{info-section-underline}{0}{-}
+\c \cfg{info-section-underline}{1}{.}
+\c \cfg{info-section-underline}{2}{.}
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
 \c
 \c \cfg{info-charset}{ASCII}
 \c \cfg{info-bullet}{\u2022}{-}
@@ -1628,13 +1687,19 @@ 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-indent-step\}}}\cw{\\cfg\{paper-contents-indent-step\}\{}\e{points}\cw{\}}
+
+\dd Specifies by how much to indent each entry in the table of
+contents per level of subdivision in the document. (In other words,
+chapter titles appear at the left of the table of contents, headings
+within the chapter are indented by the amount configured here,
+subheadings by twice that, and so on.)
 
 \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.)
+\dd Specifies the amount of space on the right of the table of
+contents which should be reserved for page numbers only. Headings in
+the table of contents which extend into this space will be wrapped.
 
 \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
 
@@ -1735,7 +1800,7 @@ specified.
 
 \dt \I{\cw{\\cfg\{paper-code-fonts\}}}\cw{\\cfg\{paper-code-fonts\}\{}\e{bold-font}\cw{\}}[\cw{\{}\e{italic-font}\cw{\}}[\cw{\{}\e{normal-font}\cw{\}}]]
 
-\dd Specifies the fonts to use for text in code paragraps.  The
+\dd Specifies the fonts to use for text in code paragraphs.  The
 \e{bold-font} is used for bold text, the \e{italic-font} for
 emphasised text, and the \e{normal-font} for normal code.
 
@@ -1796,7 +1861,7 @@ The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
 \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-indent-step}{24} 
 \c \cfg{paper-contents-margin}{84} 
 \c \cfg{paper-leader-separation}{12} 
 \c \cfg{paper-footer-distance}{32}