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
}
-\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}
+\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\{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
\lcont{
-Note that no checking is done that the anchor name is valid HTML. So
-if you use \cq{%k}, for example, you may need to restrict your use of
-keyword names.
+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.
}
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}
\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 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}
+
+\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.
-\# FIXME: actually, this doesn't appear to do anything at all - most
-font sizes are still hardcoded.
+\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{\}}
+
+\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