+\versionid $Id$
+
\C{output} Halibut output formats
This chapter describes each of Halibut's current \i{output formats}.
\H{output-text} Plain text
This output format generates the document as a single \i{plain text}
-file. No index is generated.
+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
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
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{\}}
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
\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{
\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 ...
this section. In particular, you can configure Halibut to output one
single HTML file instead of multiple ones.
-Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
-which is why all of the configuration directives start with the word
-\c{xhtml} rather than \c{html}.
+\I{\cw{\\cfg\{xhtml-anything\}}}Configuration directives with an
+\c{xhtml-} prefix are synonyms for those with an \c{html-} prefix.
\S{output-html-file} Controlling the output file names
-\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-filename\}}}\cw{\\cfg\{html-contents-filename\}\{}\e{filename}\cw{\}}
\dd Sets the \i{output file name} in which to store the top-level
contents page. Since this is the first page a user ought to see when
\c{index.html} (although this is not the default, for historical
reasons).
-\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}}
\dd Sets the file name in which to store the document's index.
-\dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
+\dt \I{\cw{\\cfg\{html-template-filename\}}}\cw{\\cfg\{html-template-filename\}\{}\e{template}\cw{\}}
\dd Provides a \i{template} to be used when constructing the file
names of each chapter or section of the document. This template
\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}.
\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
-unnumbered chapter created using \c{\\U}), this directive falls back
-to doing the same thing as \c{%N}.
+\dd Expands to the number of the section, in a format suitable for an
+HTML fragment name. The first character of the section type is
+prepended to the section number. So in chapter 1 this would expand to
+\cq{C1}; in section A.4.3 it would expand to \cq{SA.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}.
These formatting directives can also be used in the
-\cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
+\cw{\\cfg\{html-template-fragment\}} configuration directive (see
\k{output-html-misc}).
}
-\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-single-filename\}}}\cw{\\cfg\{html-single-filename\}\{}\e{filename}\cw{\}}
\dd Sets the file name in which to store the entire document, if
-Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
+Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to
produce a single self-contained file. Both this directive \e{and}
-\c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
+\c{\\cfg\{html-leaf-level\}\{0\}} are implicitly generated if you
provide a file name parameter after the command-line option
\i\c{--html} (see \k{running-options}).
The configuration directives listed below allow you to configure the
splitting into files, and the details of the contents sections.
-\dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-level\}}}\cw{\\cfg\{html-leaf-level\}\{}\e{depth}\cw{\}}
\dd This setting indicates the depth of section which should be
given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
If you set this option to zero, then the whole document will appear
in a single file. If you do this, Halibut will call that file
-\i\c{Manual.html} instead of \i\c{Contents.html}.
+\i\c{Manual.html} instead of \i\c{Contents.html} by default.
This option is automatically set to zero if you provide a file name
parameter after the command-line option \i\c{--html} (see
and so Halibut assumes you want the whole document to be placed in
that file.
+You can also specify the special name \c{infinity} (or \c{infinite}
+or \c{inf}) if you want to ensure that \e{every} section and
+subsection ends up in a separate file no matter how deep you go.
+
}
-\dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}}
\dd This directive allows you to specify how \I{depth of
-contents}deep the contents section in a particular file should go.
+contents}deep any contents section in a particular level of file
+should go.
\lcont{
you are dealing with. 0 denotes the main contents section in the
topmost file \c{Contents.html}; 1 denotes a contents section in a
chapter file; 2 is a contents section in a file containing a \c{\\H}
-heading, and so on. Currently you can't go below level 5 (which
-corresponds to a \c{\\S3} heading).
+heading, and so on.
The \e{depth} parameter indicates the maximum depth of heading which
will be shown in this contents section. Again, 1 denotes a chapter,
2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
-So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
+So, for example: \cw{\\cfg\{html-contents-depth\}\{1\}\{3\}} instructs
Halibut to put contents links in chapter files for all sections down
to \c{\\S} level, but not to go into any more detail than that.
-}
+For backwards compatibility, the alternative syntax
+\cw{\\cfg\{html-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+is also supported.
-\# FIXME: this is utterly ghastly. For a start, it should include
-\# the level as a separate argument, like the text section config
-\# directives. Secondly, it shouldn't be limited in depth!
+}
-\dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-contains-contents\}}}\cw{\\cfg\{html-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
\dd If you set this to \c{true}, then each leaf file will contain
its own contents section which summarises the text within it.
-\dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-smallest-contents\}}}\cw{\\cfg\{html-leaf-smallest-contents\}\{}\e{number}\cw{\}}
\dd Contents sections in leaf files are not output at all if they
contain very few entries (on the assumption that it just isn't worth
\I{HTML}\i{verbatim HTML} code, which will be included in various
parts of the output files.
-\dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
+Note that none of Halibut's usual character set translation is applied
+to this code; it is assumed to already be in a suitable encoding for
+the target HTML files.
+
+\dt \I{\cw{\\cfg\{html-head-end\}}}\cw{\\cfg\{html-head-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
the \i\cw{<HEAD>} section of each output HTML file. So this is a
good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
-\dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-local-head\}}}\cw{\\cfg\{html-local-head\}\{}\e{HTML text}\cw{\}}
+
+\dd This configuration directive is local: you specify it within a
+document section, and it acts on that section only.
+
+\lcont{
+
+The text you provide in this directive is placed at the end of the
+\i\cw{<HEAD>} section of whichever output HTML file contains the
+section in which the directive was placed. You can specify this
+directive multiple times in multiple sections if you like.
+
+This directive is particularly useful for constructing \i{MacOS
+on-line help}, which is mostly normal HTML but which requires a
+special \i\cw{<META NAME="AppleTitle">} tag in the topmost source
+file. You can arrange this by placing this configuration directive
+in the preamble or the introduction section, something like this:
+
+\c \cfg{html-local-head}{<meta name="AppleTitle"
+\c content="MyApp Help">}
+
+}
+
+\dt \I{\cw{\\cfg\{html-body-tag\}}}\cw{\\cfg\{html-body-tag\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is used in place of the
\i\cw{<BODY>} tag in each output file. So if you wanted to define a
\i{background colour}, for example, you could write
-\cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
+\cw{\\cfg\{html-body-tag\}\{<body bg="#123456">\}}.
-\dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-start\}}}\cw{\\cfg\{html-body-start\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the
beginning of the \i\cw{<BODY>} section of each output HTML file. So
standard \i{house style}, and the style needs a \i{header} at the
top of every page, this is where you can add that header.
-\dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-end\}}}\cw{\\cfg\{html-body-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
-the \i\cw{<BODY>} section of each output HTML file. So if you intend
-your HTML files to be part of a web site with a standard \i{house
-style}, and the style needs a \i{footer} at the bottom of every
-page, this is where you can add that footer.
+the \i\cw{<BODY>} section of each output HTML file, before any address
+section. So if you intend your HTML files to be part of a web site
+with a standard \i{house style}, and the style needs a \i{footer} at
+the bottom of every page, this is where you can add that footer.
-\dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-start\}}}\cw{\\cfg\{html-address-start\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the
beginning of the \i\cw{<ADDRESS>} section at the bottom of each
output HTML file. This might be a good place to put authors'
\i{contact details}, for example.
-\dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-end\}}}\cw{\\cfg\{html-address-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
after the version IDs (if present).
-\dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
+\dt \I{\cw{\\cfg\{html-navigation-attributes\}}}\cw{\\cfg\{html-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
\dd The text you provide in this directive is included inside the
\cw{<P>} tag containing the \i{navigation links} at the top of each
page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
wanted the navigation links to have a particular CSS style, you
could write
-\cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
+\cw{\\cfg\{html-navigation-attributes\}\{class="foo"\}}, and the
navigation-links paragraph would then begin with the tag \cw{<p
class="foo">}.
\S{output-html-headings} \ii{Configuring heading display}
-\dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-chapter-numeric\}}}\cw{\\cfg\{html-chapter-numeric\}\{}\e{boolean}\cw{\}}
\dd If this is set to \c{true}, then chapter headings will not
contain the word \q{Chapter} (or whatever other word you have
chapter title. If you set this to \c{false}, chapter headings will
be prefixed by \q{Chapter} or equivalent.
-\dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
+\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
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{\}}
+\dt \I{\cw{\\cfg\{html-section-numeric\}}}\cw{\\cfg\{html-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\# {level} can be omitted (defaults to 0). Is this intentional?
\dd Specifies whether section headings at a particular level should
contain the word \q{Section} or equivalent (if \c{false}), or should
first-level headings (\c{\\H}), 1 means second-level headings
(\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
-\dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+\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?
\dd Specifies the suffix text to be appended to section numbers at a
particular level, before displaying the section title.
+\S{output-html-names} Configuring standard text
+
+These directives let you fine-tune the names Halibut uses in places
+such as the navigation bar to refer to various parts of the document,
+and other standard pieces of text, for instance to change them to a
+different language.
+
+\dt \I{\cw{\\cfg\{html-preamble-text\}}}\cw{\\cfg\{html-preamble-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-contents-text\}}}\cw{\\cfg\{html-contents-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-index-text\}}}\cw{\\cfg\{html-index-text\}\{}\e{text}\cw{\}}
+
+\dd Text used to refer to the preamble (i.e., any paragraphs before
+the first chapter heading), contents, and index respectively, in the
+navigation bar, contents, and index.
+
+\lcont{
+
+(\c{html-contents-text} and \c{html-index-text} override the
+cross-format configuration keywords \c{contents} and \c{index} (see
+\k{input-config}, if both appear. They are legacy keywords preserved
+for backwards compatibility; you should generally use \c{contents}
+and \c{index}.)
+
+}
+
+\dt \I{\cw{\\cfg\{html-title-separator\}}}\cw{\\cfg\{html-title-separator\}\{}\e{text}\cw{\}}
+
+\dd If multiple headings are used in a file's \cw{<TITLE>} tag, this
+text is used to separate them.
+
+\# Under what circumstances can this occur?
+
+\dt \I{\cw{\\cfg\{html-index-main-separator\}}}\cw{\\cfg\{html-index-main-separator\}\{}\e{text}\cw{\}}
+
+\dd Separator between index term and references in the index.
+
+\dt \I{\cw{\\cfg\{html-index-multiple-separator\}}}\cw{\\cfg\{html-index-multiple-separator\}\{}\e{text}\cw{\}}
+
+\dd Separator between multiple references for a single index term in
+the index.
+
+\dt \I{\cw{\\cfg\{html-pre-versionid\}}}\cw{\\cfg\{html-pre-versionid\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-post-versionid\}}}\cw{\\cfg\{html-post-versionid\}\{}\e{text}\cw{\}}
+
+\dd Text surrounding each output \i{version ID paragraph}.
+
+\dt \I{\cw{\\cfg\{html-nav-prev-text\}}}\cw{\\cfg\{html-nav-prev-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}}
+
+\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 Separator between links in the navigation bar.
+
+\S{output-html-characters} Configuring the characters used
+
+Unlike the other backends, HTML does not have a single
+\i\cw{\\cfg\{html-charset\}} directive, as there are several levels of
+character encoding to consider.
+
+The character set names are the same as for
+\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
+\cw{\\cfg\{input-charset\}}, these directives affect the \e{entire}
+output; it's not possible to switch encodings halfway through.
+
+\dt \I\cw{\\cfg\{html-output-charset\}}\cw{\\cfg\{html-output-charset\}\{}\e{character set name}\cw{\}}
+
+\dd The character encoding of the HTML file to be output. Unicode
+characters in this encoding's repertoire are included literally rather
+than as \i{HTML entities}.
+
+\dt \I\cw{\\cfg\{html-restrict-charset\}}\cw{\\cfg\{html-restrict-charset\}\{}\e{character set name}\cw{\}}
+
+\dd Only Unicode characters representable in this character set will be
+output; any others will be omitted and use their fallback text, if
+any. Characters not in \q{html-output-charset} will be represented as
+HTML numeric entities.
+
+\dt \I{\cw{\\cfg\{html-quotes\}}}\cw{\\cfg\{html-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-html-misc} Miscellaneous options
-\dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
+\dt \I\cw{\\cfg\{html-version\}}\cw{\\cfg\{html-version\}\{}\e{version}\cw{\}}
+
+\dd Identifies the precise version of HTML that is output. This
+affects the declaration within the HTML, and also has minor effects on
+the body of the HTML so that it is valid for the declared version. The
+available variants are:
+
+\lcont{
+
+\dt \cw{html3.2}
+
+\dd W3C HTML 3.2
+
+\dt \cw{html4}
+
+\dd W3C HTML 4.01 Strict
+
+\dt \cw{iso-html}
+
+\dd ISO/IEC 15445:2000
+
+\dt \cw{xhtml1.0transitional}
+
+\dd W3C XHTML 1.0 Transitional
+
+\dt \cw{xhtml1.0strict}
+
+\dd W3C XHTML 1.0 Strict
+
+}
+
+\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}]
\dd This directive lets you specify a \i{template}, with exactly the
-same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
+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
-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.
-\dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
+\lcont{
+
+If more than one template is specified, anchors are generated in all
+the specified formats; Halibut's own cross-references are generated
+with the first template.
+
+Characters that are not permitted in anchor names are stripped. If
+there are no valid characters left, or a fragment is non-unique,
+Halibut starts inventing fragment names and suffixes as appropriate.
+
+Note that there are potentially fragment names that are not controlled
+by this mechanism, such as index references.
+
+}
+
+\dt \I{\cw{\\cfg\{html-versionid\}}}\cw{\\cfg\{html-versionid\}\{}\e{boolean}\cw{\}}
\dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
the \i\c{\\versionid} command - see \k{input-blurb}) will be included
visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
-file. If it is set to \c{false}, they will be omitted completely.
+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.
+
+}
-\# FIXME: surely it would be better to include them in HTML
-\# comments? The only question is whether they should be _visible_.
+\dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}}
-\dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
+\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{\}}
\dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
bottom of each HTML file will be omitted completely. (This will
-therefore also cause \i{version IDs} not to be included.)
+therefore also cause \i{version IDs} not to be included visibly.)
-\dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-author\}}}\cw{\\cfg\{html-author\}\{}\e{text}\cw{\}}
\dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
name="author">} tag in the output HTML files, so that browsers which
support this can automatically identify the \i{author} of the document.
-\dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-description\}}}\cw{\\cfg\{html-description\}\{}\e{text}\cw{\}}
\dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
name="description">} tag in the output HTML files, so that browsers
which support this can easily pick out a brief \I{description, of
document}description of the document.
+\S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help}
+
+The HTML files output from Halibut's HTML back end can be used as
+input to the MS Windows HTML Help compiler. In order to do this, you
+also need some auxiliary files: a project file, and (probably) a
+contents file and an index file. Halibut can optionally generate
+those as well.
+
+To enable the generation of MS HTML Help auxiliary files, use the
+following configuration directives:
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help project file with the
+specified name. You will almost certainly want the filename to end
+in the extension \c{.hhp} (although Halibut will not enforce this).
+If you use this option, you must also use the
+\cw{html-mshtmlhelp-chm} option to specify the desired name of the
+compiled help file.
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}}
+
+\dd Specifies the desired name of the compiled HTML Help file. You
+will almost certainly want this to have the extension \c{.chm}
+(although Halibut will not enforce this). The name you specify here
+will be written into the help project file. If you specify this
+option, you must also use the \cw{html-mshtmlhelp-project} option to
+request a help project file in the first place.
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help contents file with the
+specified name, and refer to it in the help project file. You will
+almost certainly want the filename to end in the extension \c{.hhc}
+(although Halibut will not enforce this). This option will be
+ignored if you have not also specified a help project file.
+
+\lcont{
+
+Creating a contents file like this causes the HTML Help viewer to
+display a contents tree in the pane to the left of the main text
+window. You can choose to generate an HTML Help project without this
+feature, in which case the user will still be able to navigate
+around the document by using the ordinary internal links in the HTML
+files themselves just as if it were a web page. However, using a
+contents file is recommended.
+
+}
+
+\dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}}
+
+\dd Instructs Halibut to output an HTML Help index file with the
+specified name, and refer to it in the help project file. You will
+almost certainly want the filename to end in the extension \c{.hhk}
+(although Halibut will not enforce this). This option will be
+ignored if you have not also specified a help project file.
+
+\lcont{
+
+Specifying this option suppresses the generation of an HTML-based
+index file (see \cw{\\cfg\{html-index-filename\}} in
+\k{output-html-file}).
+
+Creating an index file like this causes the HTML Help viewer to
+provide a list of index terms in a pane to the left of the main text
+window. You can choose to generate an HTML Help project without this
+feature, in which case a conventional HTML index will be generated
+instead (assuming you have any index terms at all defined) and the
+user will still be able to use that. However, using an index file is
+recommended.
+
+Halibut will not output an index file at all, or link to one from
+the help project file, if your document contains no index entries.
+
+}
+
+If you use the above options, Halibut will output a help project
+file which you should be able to feed straight to the command-line
+MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help
+Workshop (\cw{HHW.EXE}).
+
+You may also wish to alter other HTML configuration options to make
+the resulting help file look more like a help file and less like a
+web page. A suggested set of additional configuration options for
+HTML Help is as follows:
+
+\b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help
+works best with lots of small files (\q{topics}) rather than a few
+large ones. In particular, the contents and index mechanisms can
+only reference files, not subsections within files.
+
+\b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress
+the contents list above the main text of each bottom-level file.
+
+\b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help
+has its own navigation facilities and it looks a bit strange to
+duplicate them.
+
+\b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the
+\cw{<ADDRESS>} section makes less sense in a help file than it does
+on a web page.
+
\S{output-html-defaults} Default settings
The \i{default settings} for Halibut's HTML output format are:
-\c \cfg{xhtml-contents-filename}{Contents.html}
-\c \cfg{xhtml-index-filename}{IndexPage.html}
-\c \cfg{xhtml-template-filename}{%n.html}
-\c \cfg{xhtml-single-filename}{Manual.html}
-\c \cfg{xhtml-template-fragment}{%b}
+\c \cfg{html-contents-filename}{Contents.html}
+\c \cfg{html-index-filename}{IndexPage.html}
+\c \cfg{html-template-filename}{%n.html}
+\c \cfg{html-single-filename}{Manual.html}
\c
-\c \cfg{xhtml-leaf-level}{2}
-\c \cfg{xhtml-leaf-contains-contents}{false}
-\c \cfg{xhtml-leaf-smallest-contents}{4}
-\c \cfg{xhtml-contents-depth-0}{2}
-\c \cfg{xhtml-contents-depth-1}{3}
-\c \cfg{xhtml-contents-depth-2}{4}
-\c \cfg{xhtml-contents-depth-3}{5}
-\c \cfg{xhtml-contents-depth-4}{6}
-\c \cfg{xhtml-contents-depth-5}{7}
-\c
-\c \cfg{xhtml-head-end}{}
-\c \cfg{xhtml-body-tag}{<body>}
-\c \cfg{xhtml-body-start}{}
-\c \cfg{xhtml-body-end}{}
-\c \cfg{xhtml-address-start}{}
-\c \cfg{xhtml-address-end}{}
-\c \cfg{xhtml-navigation-attributes}{}
+\c \cfg{html-leaf-level}{2}
+\c \cfg{html-leaf-contains-contents}{false}
+\c \cfg{html-leaf-smallest-contents}{4}
+\c \cfg{html-contents-depth}{0}{2}
+\c \cfg{html-contents-depth}{1}{3}
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
\c
-\c \cfg{xhtml-versionid}{true}
-\c \cfg{xhtml-suppress-address}{false}
-\c \cfg{xhtml-author}{}
-\c \cfg{xhtml-description}{}
+\c \cfg{html-head-end}{}
+\c \cfg{html-body-tag}{<body>}
+\c \cfg{html-body-start}{}
+\c \cfg{html-body-end}{}
+\c \cfg{html-address-start}{}
+\c \cfg{html-address-end}{}
+\c \cfg{html-navigation-attributes}{}
\c
-\c \cfg{xhtml-chapter-numeric}{false}
-\c \cfg{xhtml-chapter-suffix}{: }
+\c \cfg{html-chapter-numeric}{false}
+\c \cfg{html-chapter-shownumber}{true}
+\c \cfg{html-chapter-suffix}{: }
\c
-\c \cfg{xhtml-section-numeric}{0}{true}
-\c \cfg{xhtml-section-suffix}{0}{ }
+\c \cfg{html-section-numeric}{0}{true}
+\c \cfg{html-section-shownumber}{0}{true}
+\c \cfg{html-section-suffix}{0}{ }
\c
-\c \cfg{xhtml-section-numeric}{1}{true}
-\c \cfg{xhtml-section-suffix}{1}{ }
+\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 ...
\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\c \cfg{html-preamble-text}{Preamble}
+\c \cfg{html-contents-text}{Contents}
+\c \cfg{html-index-text}{Index}
+\c \cfg{html-title-separator}{ - }
+\c \cfg{html-index-main-separator}{: }
+\c \cfg{html-index-multiple-separator}{, }
+\c \cfg{html-pre-versionid}{[}
+\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-restrict-charset}{UTF-8}
+\c \cfg{html-quotes}{\u2018}{\u2019}{"}{"}
+\c
+\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}{}
\H{output-whlp} Windows Help
This output format generates data that can be used by the \i{Windows
-Help} program \cw{WINHELP.EXE}. There are two actual files
+Help} program \cw{WINHLP32.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.
+Note that as of 2006, MS is discontinuing the Windows Help format in
+favour of the newer HTML Help format (\c{.chm} files). Halibut is
+not currently able to generate \c{.chm} files directly, but its HTML
+back end can write out project files suitable for use as input to
+the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more
+information on this.
+
+Currently, the Windows Help output is hardcoded to be in the
+\q{\i{Win1252}} character set. (If anyone knows how character sets
+are encoded in Windows Help files, we'd appreciate help.)
The Windows Help output format supports the following configuration
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}).
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-rule\}}}\cw{\\cfg\{man-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
+
+\dd This specifies the text which should be used for drawing
+\i{horizontal rules} (generated by \i\c{\\rule}; see
+\k{input-rule}) when the manual page is rendered into text.
+It should only be one character long, but otherwise
+it works like the \cw{\\cfg\{text-rule\}} 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
\c
\c \cfg{man-charset}{ASCII}
\c \cfg{man-bullet}{\u2022}{o}
+\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).
}
\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{\}}...]
+\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-index-width}{40}
\c \cfg{info-list-indent}{1}
\c \cfg{info-listitem-indent}{3}
-zc
+\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}{-}
and no \cw{\\cfg\{info-dir-entry\}} directives.
-\H{output-ps} \i{PostScript}
+\H{output-paper} Paper formats
+
+These output formats (currently PDF and PostScript) generate printable
+manuals. As such, they share a number of configuration directives.
+
+\S{output-pdf} \i{PDF}
+
+This output format generates a printable manual in PDF format. In
+addition, it uses some PDF interactive features to
+provide an outline of all the document's sections and clickable
+cross-references between sections.
+
+There is one configuration option specific to PDF:
+
+\dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the PDF file.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--pdf} (see
+\k{running-options}).
+
+The \i{default settings} for the PDF output format are:
+
+\c \cfg{pdf-filename}{output.pdf}
+
+\S{output-ps} \i{PostScript}
This output format generates a printable manual in PostScript format.
+This should look exactly identical to the PDF output (see
+\k{output-ps}), and uses \i\c{pdfmark} to arrange that if converted
+to PDF it will contain the same interactive features.
-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{\}}
\c \cfg{ps-filename}{output.ps}
-\H{output-pdf} \i{PDF}
+\S{output-paper-dimensions} Configuring layout and \i{measurements}
-This output format generates a printable manual in PDF format. This
-should look exactly identical to the PostScript output (see
-\k{output-ps}), but also uses some PDF interactive features to
-provide an outline of all the document's sections and clickable
-cross-references between sections.
+All measurements are in PostScript \i{points} (72 points to the inch).
-This format is currently very new and is not yet configurable. There
-is only one available configuration option:
+\S2{output-paper-pagesize} Page properties
-\dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
-\dd Sets the \i{output file name} in which to store the PDF file.
-This directive is implicitly generated if you provide a file name
-parameter after the command-line option \i\c{--pdf} (see
-\k{running-options}).
+\dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
-The \i{default settings} for the PDF output format are:
+\dd Specify the absolute limits of the paper.
-\c \cfg{pdf-filename}{output.pdf}
+\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}numbered \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 and the top of the
+chapter heading. (Each chapter begins on a new page.)
+
+\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-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{\}}
+
+\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{\}}
+
+\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} \ii{Fonts}
+
+The directives in this section control which fonts Halibut uses for
+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.
+
+Halibut intrinsically knows about some fonts, and these fonts are also
+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-title-fonts\}}}\cw{\\cfg\{paper-title-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in the document title.
+
+\dt \I{\cw{\\cfg\{paper-title-font-size\}}}\cw{\\cfg\{paper-title-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of the document title.
+
+\dt \I{\cw{\\cfg\{paper-chapter-fonts\}}}\cw{\\cfg\{paper-chapter-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in chapter titles.
+
+\dt \I{\cw{\\cfg\{paper-chapter-font-size\}}}\cw{\\cfg\{paper-chapter-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of chapter titles.
+
+\dt \I{\cw{\\cfg\{paper-section-fonts\}}}\cw{\\cfg\{paper-section-fonts\}\{}\e{level}\cw{\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in section headings at the \e{level}
+specified.
+
+\dt \I{\cw{\\cfg\{paper-section-font-size\}}}\cw{\\cfg\{paper-section-font-size\}\{}\e{level}\cw{\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of section headings at the \e{level}
+specified.
+
+\dt \I{\cw{\\cfg\{paper-base-fonts\}}}\cw{\\cfg\{paper-base-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
+
+\dd Specifies the fonts to use for text in the body text.
+
+\dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of body text.
+
+\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 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.
+
+\dt \I{\cw{\\cfg\{paper-code-font-size\}}}\cw{\\cfg\{paper-code-font-size\}\{}\e{points}\cw{\}}
+
+\dd Specifies the \i{font size} of text in code paragraphs.
+
+\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 \i{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}{842}
+\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-indent-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-fonts}{Times-Roman}{Times-Italic}{Courier}
+\c \cfg{paper-base-font-size}{12}
+\c \cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier}
+\c \cfg{paper-code-font-size}{12}
+\c \cfg{paper-title-fonts}{Helvetica-Bold}
+\c {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-title-font-size}{24}
+\c \cfg{paper-chapter-fonts}{Helvetica-Bold}
+\c {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-chapter-font-size}{20}
+\c \cfg{paper-section-fonts}{0}{Helvetica-Bold}
+\c {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{0}{16}
+\c \cfg{paper-section-fonts}{1}{Helvetica-Bold}
+\c {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{1}{14}
+\c \cfg{paper-section-fonts}{2}{Helvetica-Bold}
+\c {Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{2}{13}
+\c ... and so on for all section levels below this ...
+\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\c
+\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}{'}{'}
~mdw / sgt / halibut / blobdiff