X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/2a2375dbd59337c00fb90c903b0af3669520d9dd..f6220253b2e31a88862b8beae822ff11cc5576ab:/doc/output.but

diff --git a/doc/output.but b/doc/output.but
index c9614cd..4df4502 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -624,6 +624,16 @@ different language.
 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
@@ -1497,18 +1507,89 @@ columns.
 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.
+
+\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.
 
-\# FIXME: actually, this doesn't appear to do anything at all - most
-font sizes are still hardcoded.
+\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
 
@@ -1540,7 +1621,7 @@ 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}{841} 
+\c \cfg{paper-page-height}{842} 
 \c
 \c \cfg{paper-left-margin}{72} 
 \c \cfg{paper-top-margin}{72} 
@@ -1567,7 +1648,23 @@ The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
 \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}{Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-title-font-size}{24}
+\c \cfg{paper-chapter-fonts}{Helvetica-Bold}{Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-chapter-font-size}{20}
+\c \cfg{paper-section-fonts}{0}{Helvetica-Bold}{Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{0}{16}
+\c \cfg{paper-section-fonts}{1}{Helvetica-Bold}{Helvetica-BoldOblique}{Courier-Bold}
+\c \cfg{paper-section-font-size}{1}{14}
+\c \cfg{paper-section-fonts}{2}{Helvetica-Bold}{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}