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

diff --git a/doc/output.but b/doc/output.but
index 35613ca..0bd6393 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
@@ -694,29 +704,39 @@ directive (see \k{output-text-characters}).
 
 \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
@@ -724,9 +744,16 @@ internal section keyword.
 
 \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.
 
 }
 
@@ -1057,6 +1084,15 @@ sensible to output man pages in that charset.
 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
@@ -1077,6 +1113,7 @@ The \i{default settings} for the \cw{man} page output format are:
 \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}
@@ -1403,7 +1440,7 @@ vertical space between paragraphs does \e{not} include
 
 \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{\}}
@@ -1480,18 +1517,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.
 
-\# 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
 
@@ -1523,7 +1631,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} 
@@ -1550,7 +1658,28 @@ 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}
+\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}