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{\}}
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
\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 declare version. The
+the body of the HTML so that it is valid for the declared version. The
available variants are:
\lcont{
-\b \cw{html3.2}
+\dt \cw{html3.2}
+
+\dd W3C HTML 3.2
+
+\dt \cw{html4}
-\b \cw{html4}
+\dd W3C HTML 4.01 Strict
-\b \cw{iso-html}
+\dt \cw{iso-html}
-\b \cw{xhtml1.0transitional}
+\dd ISO/IEC 15445:2000
-\b \cw{xhtml1.0strict}
+\dt \cw{xhtml1.0transitional}
+
+\dd W3C XHTML 1.0 Transitional
+
+\dt \cw{xhtml1.0strict}
+
+\dd W3C XHTML 1.0 Strict
}
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="}\e{next}\cw{">} 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. 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-version}{html4}
\c \cfg{html-template-fragment}{%b}
\c \cfg{html-versionid}{true}
+\c \cfg{html-include-rellinks}{false}
+\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-ps} \i{PostScript}
-
-This output format generates a printable manual in PostScript format.
-
-There is one configuration option specific to PostScript:
-
-\dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
-
-\dd Sets the \i{output file name} in which to store the PostScript
-file. This directive is implicitly generated if you provide a file
-name parameter after the command-line option \i\c{--ps} (see
-\k{running-options}).
-
-The \i{default settings} for the PostScript output format are:
-
-\c \cfg{ps-filename}{output.ps}
-
\S{output-pdf} \i{PDF}
-This output format generates a printable manual in PDF format. This
-should look exactly identical to the PostScript output (see
-\k{output-ps}), but also uses some PDF interactive features to
+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.
\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.
+
+There is one configuration option specific to PostScript:
+
+\dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the PostScript
+file. This directive is implicitly generated if you provide a file
+name parameter after the command-line option \i\c{--ps} (see
+\k{running-options}).
+
+The \i{default settings} for the PostScript output format are:
+
+\c \cfg{ps-filename}{output.ps}
+
\S{output-paper-dimensions} Configuring layout and \i{measurements}
All measurements are in PostScript \i{points} (72 points to the inch).
\dd Specifies the indentation of the bullet or number in a
\I{bulletted list, indentation}bulletted or \I{numbered list,
-indentation}numbers \I{list, indentation}list, similarly to
+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{\}}
entry and its page number. If the gap is smaller, the page number is
moved to the next line.
-\S2{output-paper-fonts} Fonts
+\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. Fonts are named using their
+PostScript names.
+
+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 font file in either hexadecimal (\I{PFA
+files}PFA) or IBM PC (\I{PFB files}PFB) format. To provide
+an AFM, PFA, or PFB file to Halibut, simply name it on Halibut's command
+line. If a PFA or PFB file is specified, the corresponding AFM file
+must come first.
+
+\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 font size of body text.
+\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 paragraps. 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{\}}
-\# FIXME: actually, this doesn't appear to do anything at all - most
-font sizes are still hardcoded.
+\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 page numbers.
+\dd Specifies the font size to use for \i{page numbers}.
\S2{output-paper-misc} Miscellaneous
\i{A4 paper}.
\c \cfg{paper-page-width}{595}
-\c \cfg{paper-page-height}{841}
+\c \cfg{paper-page-height}{842}
\c
\c \cfg{paper-left-margin}{72}
\c \cfg{paper-top-margin}{72}
\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}
~mdw / sgt / halibut / blobdiff