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
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
\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 ...
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
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?
\dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}}
-\dd The text used for the \q{previous page} and \q{next page} links on
-the navigation bar.
+\dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}}
+
+\dd The text used for the \q{previous page}, \q{next page}, and \q{up}
+links on the navigation bar.
\dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}}
\dd This directive lets you specify a \i{template}, with exactly the
same syntax used in \cw{\\cfg\{html-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
+\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 \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
file. If it is set to \c{false}, they will only be included as HTML
comments.
+\dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{true}, machine-readable relational links will
+be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK
+REL="next">} and so on within the \i\cw{<HEAD>} section)
+providing links to related files. The same set of links are provided
+as in the navigation bar (with which this should not be confused).
+
+\lcont{
+
+Some browsers make use of this semantic information, for instance to
+allow easy navigation through related pages, and to prefetch the next
+page. (Search engines can also make use of it.) However, many browsers
+ignore this markup, so it would be unwise to rely on it for
+navigation.
+
+The use and rendering of this information is entirely up to the
+browser; none of the other Halibut options for the navigation bar will
+have any effect.
+
+}
+
\dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}}
-\dd If this is set to \c{true}, the usual \i{navigation links} at the
-top of each HTML file will be suppressed.
+\dd If this is set to \c{true}, the usual \i{navigation links} within
+the \e{body} of each HTML file (near the top of the rendered page) will
+be suppressed.
\dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}}
duplicate them.
\b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the
-\cw{<address>} section makes less sense in a help file than it does
+\cw{<ADDRESS>} section makes less sense in a help file than it does
on a web page.
\S{output-html-defaults} Default settings
\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 ...
\c \cfg{html-post-versionid}{]}
\c \cfg{html-nav-prev-text}{Previous}
\c \cfg{html-nav-next-text}{Next}
+\c \cfg{html-nav-up-text}{Up}
\c \cfg{html-nav-separator}{ | }
\c
\c \cfg{html-output-charset}{ASCII}
\c \cfg{html-version}{html4}
\c \cfg{html-template-fragment}{%b}
\c \cfg{html-versionid}{true}
+\c \cfg{html-rellinks}{true}
+\c \cfg{html-suppress-navlinks{false}
\c \cfg{html-suppress-address}{false}
\c \cfg{html-author}{}
\c \cfg{html-description}{}
\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}).
\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
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}).
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.
}
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).
}
\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{\}}
\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{
\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}
\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}{-}
\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{\}}
various kinds of text. Directives for setting the font normally take
three font names, the first of which is used for normal text, the
second for emphasised text, and the third for code. Any fonts which
-aren't specified are left unchanged. Fonts are named using their
-PostScript names.
+aren't specified are left unchanged.
Halibut intrinsically knows about some fonts, and these fonts are also
-built into all PDF and most PostScript implementations. These are:
-
-\b \cw{Times-Roman}
-
-\b \cw{Times-Italic}
-
-\b \cw{Times-Bold}
-
-\b \cw{Times-BoldItalic}
-
-\b \cw{Helvetica}
-
-\b \cw{Helvetica-Oblique}
-
-\b \cw{Helvetica-Bold}
-
-\b \cw{Helvetica-BoldOblique}
-
-\b \cw{Courier}
-
-\b \cw{Courier-Oblique}
-
-\b \cw{Courier-Bold}
-
-\b \cw{Courier-BoldOblique}
-
-These fonts can be used without further formality. To use any other font,
-Halibut needs at least to know its measurements, which are provided in an
-\i{Adobe Font Metrics} (\I{AFM files}AFM) file. Halibut can also
-\I{embedding fonts}embed
-\i{Type 1 fonts} in its PDF and PostScript output if provided with an
-ASCII-format (\I{PFA files}PFA) font file. To provide an AFM or PFA file
-to Halibut, simply name it on Halibut's command line. If both are named,
-the AFM file must come first.
+built into all PDF and most PostScript implementations.
+These fonts can be used without further formality. Halibut can also use
+other fonts, and can \I{embedding fonts}embed them it its PDF and
+PostScript output. These other fonts are supplied to Halibut by
+simply adding them to the list of input files on its command line.
+
+To use a \i{Type 1 font} Halibut needs both the font file itself,
+in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB)
+format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file. The AFM
+file must be specified first on the command line. If Halibut gets an
+AFM file without a corresponding Type 1 font file, the PostScript and
+PDF output files will still use that font, but they won't contain it.
+
+Using a \i{TrueType font} is rather simpler, and simply requires you to
+pass the font file to Halibut. Halibut does place a few restrictions on
+TrueType fonts, notably that they must include a \i{Unicode} mapping
+table and a PostScript name.
+
+Fonts are specified using their PostScript names. Running Halibut with
+the \i\cw{\-\-list-fonts} option causes it to display the PostScript
+names of all the fonts it intrinsically knows about, along with any
+fonts the were supplied as input files.
\ii{Font sizes} are specified in PostScript \i{points} (72 to the inch).
\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.
\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}
~mdw / sgt / halibut / blobdiff