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\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}}
\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} 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
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{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}{}
\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 hardcoded to be in the \q{\i{Win1252}}
-character set. (If anyone knows how character sets are encoded in
-Windows Help, we'd appreciate help.)
+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:
\H{output-paper} Paper formats
-These output formats (currently PostScript and PDF) generate printable
+These output formats (currently PDF and PostScript) generate printable
manuals. As such, they share a number of configuration directives.
\S{output-pdf} \i{PDF}
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 and must be ones whose metrics are compiled into
-Halibut. 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}
+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).
~mdw / sgt / halibut / blobdiff