X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/b774705014b73abf1052a937deef534d34ca259d..6e6747065dd221528a52a383f0f99712c8cd82e4:/doc/output.but
diff --git a/doc/output.but b/doc/output.but
index 964f49d..3d9783b 100644
--- a/doc/output.but
+++ b/doc/output.but
@@ -1,3 +1,5 @@
+\versionid $Id$
+
\C{output} Halibut output formats
This chapter describes each of Halibut's current \i{output formats}.
@@ -140,6 +142,14 @@ they will just contain the chapter \e{number}, followed by the
chapter title. If you set this to \c{false}, chapter headings will
be prefixed by \q{Chapter} or equivalent.
+\dt \I{\cw{\\cfg\{text-chapter-shownumber\}}}\cw{\\cfg\{text-chapter-shownumber\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then chapter headings will \e{only}
+contain the chapter title: they will not contain the word
+\q{Chapter} (or whatever other word you have defined in its place),
+and neither will they contain the chapter number. If set to
+\c{false}, this overrides \cw{\\cfg\{text-chapter-numeric\}}.
+
\dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
\dd This specifies the suffix text to be appended to the chapter
@@ -166,6 +176,15 @@ just like the other alignment directives listed above.
contain the word \q{Section} or equivalent (if \c{false}), or should
be numeric only (if \c{true}).
+\dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then section headings at the
+specified level will \e{only} contain the section title: they will
+not contain the word \q{Section} (or whatever other word you have
+defined in its place), and neither will they contain the section
+number. If set to \c{false}, this overrides
+\cw{\\cfg\{text-section-numeric\}}.
+
\dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
\dd Specifies the \I{suffix text, in section titles}suffix text to
@@ -294,16 +313,19 @@ The \i{default settings} for Halibut's plain text output format are:
\c \cfg{text-chapter-align}{left}
\c \cfg{text-chapter-underline}{\u203e}{-}
\c \cfg{text-chapter-numeric}{false}
+\c \cfg{text-chapter-shownumber}{true}
\c \cfg{text-chapter-suffix}{: }
\c
\c \cfg{text-section-align}{0}{leftplus}
\c \cfg{text-section-underline}{0}{}
\c \cfg{text-section-numeric}{0}{true}
+\c \cfg{text-section-shownumber}{0}{true}
\c \cfg{text-section-suffix}{0}{ }
\c
\c \cfg{text-section-align}{1}{leftplus}
\c \cfg{text-section-underline}{1}{}
\c \cfg{text-section-numeric}{1}{true}
+\c \cfg{text-section-shownumber}{1}{true}
\c \cfg{text-section-suffix}{1}{ }
\c
\c ... and so on for all section levels below this ...
@@ -320,9 +342,6 @@ The \i{default settings} for Halibut's plain text output format are:
\H{output-html} HTML
-\# FIXME: this probably needs major revision due to the new HTML
-backend
-
This output format generates an \i{HTML} version of the document. By
default, this will be in multiple files, starting with
\c{Contents.html} and splitting the document into files by chapter
@@ -331,13 +350,12 @@ between HTML files using the configuration commands described in
this section. In particular, you can configure Halibut to output one
single HTML file instead of multiple ones.
-Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
-which is why all of the configuration directives start with the word
-\c{xhtml} rather than \c{html}.
+\I{\cw{\\cfg\{xhtml-anything\}}}Configuration directives with an
+\c{xhtml-} prefix are synonyms for those with an \c{html-} prefix.
\S{output-html-file} Controlling the output file names
-\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-filename\}}}\cw{\\cfg\{html-contents-filename\}\{}\e{filename}\cw{\}}
\dd Sets the \i{output file name} in which to store the top-level
contents page. Since this is the first page a user ought to see when
@@ -345,11 +363,11 @@ beginning to read the document, a good choice in many cases might be
\c{index.html} (although this is not the default, for historical
reasons).
-\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}}
\dd Sets the file name in which to store the document's index.
-\dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
+\dt \I{\cw{\\cfg\{html-template-filename\}}}\cw{\\cfg\{html-template-filename\}\{}\e{template}\cw{\}}
\dd Provides a \i{template} to be used when constructing the file
names of each chapter or section of the document. This template
@@ -379,11 +397,12 @@ If the section has no number (an unnumbered chapter created using
\dt \i\c{%b}
-\dd Expands to the bare number of the section. So in chapter 1 this
-would expand to \cq{1}; in section A.4.3 it would expand to
-\cq{A.4.3}, and so on. If the section has no number (an
-unnumbered chapter created using \c{\\U}), this directive falls back
-to doing the same thing as \c{%N}.
+\dd Expands to the number of the section, in a format suitable for an
+HTML fragment name. The first character of the section type is
+prepended to the section number. So in chapter 1 this would expand to
+\cq{C1}; in section A.4.3 it would expand to \cq{SA.4.3}, and so on.
+If the section has no number (an unnumbered chapter created using
+\c{\\U}), this directive falls back to doing the same thing as \c{%N}.
\dt \i\c{%k}
@@ -394,17 +413,17 @@ no keyword (an unnumbered chapter created using \c{\\U}), this
directive falls back to doing the same thing as \c{%N}.
These formatting directives can also be used in the
-\cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
+\cw{\\cfg\{html-template-fragment\}} configuration directive (see
\k{output-html-misc}).
}
-\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
+\dt \I{\cw{\\cfg\{html-single-filename\}}}\cw{\\cfg\{html-single-filename\}\{}\e{filename}\cw{\}}
\dd Sets the file name in which to store the entire document, if
-Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
+Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to
produce a single self-contained file. Both this directive \e{and}
-\c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
+\c{\\cfg\{html-leaf-level\}\{0\}} are implicitly generated if you
provide a file name parameter after the command-line option
\i\c{--html} (see \k{running-options}).
@@ -421,7 +440,7 @@ sections in the file and/or the sections below it.
The configuration directives listed below allow you to configure the
splitting into files, and the details of the contents sections.
-\dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-level\}}}\cw{\\cfg\{html-leaf-level\}\{}\e{depth}\cw{\}}
\dd This setting indicates the depth of section which should be
given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
@@ -435,7 +454,7 @@ file, and the chapter files will mostly just contain links to their
If you set this option to zero, then the whole document will appear
in a single file. If you do this, Halibut will call that file
-\i\c{Manual.html} instead of \i\c{Contents.html}.
+\i\c{Manual.html} instead of \i\c{Contents.html} by default.
This option is automatically set to zero if you provide a file name
parameter after the command-line option \i\c{--html} (see
@@ -443,12 +462,17 @@ parameter after the command-line option \i\c{--html} (see
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\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+\dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}}
\dd This directive allows you to specify how \I{depth of
-contents}deep the contents section in a particular file should go.
+contents}deep any contents section in a particular level of file
+should go.
\lcont{
@@ -456,29 +480,28 @@ The \e{level} parameter indicates which level of contents section
you are dealing with. 0 denotes the main contents section in the
topmost file \c{Contents.html}; 1 denotes a contents section in a
chapter file; 2 is a contents section in a file containing a \c{\\H}
-heading, and so on. Currently you can't go below level 5 (which
-corresponds to a \c{\\S3} heading).
+heading, and so on.
The \e{depth} parameter indicates the maximum depth of heading which
will be shown in this contents section. Again, 1 denotes a chapter,
2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
-So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
+So, for example: \cw{\\cfg\{html-contents-depth\}\{1\}\{3\}} instructs
Halibut to put contents links in chapter files for all sections down
to \c{\\S} level, but not to go into any more detail than that.
-}
+For backwards compatibility, the alternative syntax
+\cw{\\cfg\{html-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
+is also supported.
-\# FIXME: this is utterly ghastly. For a start, it should include
-\# the level as a separate argument, like the text section config
-\# directives. Secondly, it shouldn't be limited in depth!
+}
-\dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-contains-contents\}}}\cw{\\cfg\{html-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
\dd If you set this to \c{true}, then each leaf file will contain
its own contents section which summarises the text within it.
-\dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
+\dt \I{\cw{\\cfg\{html-leaf-smallest-contents\}}}\cw{\\cfg\{html-leaf-smallest-contents\}\{}\e{number}\cw{\}}
\dd Contents sections in leaf files are not output at all if they
contain very few entries (on the assumption that it just isn't worth
@@ -492,20 +515,47 @@ The directives in this section allow you to supply pieces of
\I{HTML}\i{verbatim HTML} code, which will be included in various
parts of the output files.
-\dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
+Note that none of Halibut's usual character set translation is applied
+to this code; it is assumed to already be in a suitable encoding for
+the target HTML files.
+
+\dt \I{\cw{\\cfg\{html-head-end\}}}\cw{\\cfg\{html-head-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
the \i\cw{
} section of each output HTML file. So this is a
good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
-\dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-local-head\}}}\cw{\\cfg\{html-local-head\}\{}\e{HTML text}\cw{\}}
+
+\dd This configuration directive is local: you specify it within a
+document section, and it acts on that section only.
+
+\lcont{
+
+The text you provide in this directive is placed at the end of the
+\i\cw{} section of whichever output HTML file contains the
+section in which the directive was placed. You can specify this
+directive multiple times in multiple sections if you like.
+
+This directive is particularly useful for constructing \i{MacOS
+on-line help}, which is mostly normal HTML but which requires a
+special \i\cw{} tag in the topmost source
+file. You can arrange this by placing this configuration directive
+in the preamble or the introduction section, something like this:
+
+\c \cfg{html-local-head}{}
+
+}
+
+\dt \I{\cw{\\cfg\{html-body-tag\}}}\cw{\\cfg\{html-body-tag\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is used in place of the
\i\cw{} tag in each output file. So if you wanted to define a
\i{background colour}, for example, you could write
-\cw{\\cfg\{xhtml-body-tag\}\{\}}.
+\cw{\\cfg\{html-body-tag\}\{\}}.
-\dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-start\}}}\cw{\\cfg\{html-body-start\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the
beginning of the \i\cw{} section of each output HTML file. So
@@ -513,41 +563,41 @@ if you intend your HTML files to be part of a web site with a
standard \i{house style}, and the style needs a \i{header} at the
top of every page, this is where you can add that header.
-\dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-body-end\}}}\cw{\\cfg\{html-body-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
-the \i\cw{} section of each output HTML file. So if you intend
-your HTML files to be part of a web site with a standard \i{house
-style}, and the style needs a \i{footer} at the bottom of every
-page, this is where you can add that footer.
+the \i\cw{} section of each output HTML file, before any address
+section. So if you intend your HTML files to be part of a web site
+with a standard \i{house style}, and the style needs a \i{footer} at
+the bottom of every page, this is where you can add that footer.
-\dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-start\}}}\cw{\\cfg\{html-address-start\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the
beginning of the \i\cw{} section at the bottom of each
output HTML file. This might be a good place to put authors'
\i{contact details}, for example.
-\dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-address-end\}}}\cw{\\cfg\{html-address-end\}\{}\e{HTML text}\cw{\}}
\dd The text you provide in this directive is placed at the end of
the \i\cw{} section at the bottom of each output HTML file,
after the version IDs (if present).
-\dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
+\dt \I{\cw{\\cfg\{html-navigation-attributes\}}}\cw{\\cfg\{html-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
\dd The text you provide in this directive is included inside the
\cw{
} tag containing the \i{navigation links} at the top of each
page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
wanted the navigation links to have a particular CSS style, you
could write
-\cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
+\cw{\\cfg\{html-navigation-attributes\}\{class="foo"\}}, and the
navigation-links paragraph would then begin with the tag \cw{
}.
\S{output-html-headings} \ii{Configuring heading display}
-\dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-chapter-numeric\}}}\cw{\\cfg\{html-chapter-numeric\}\{}\e{boolean}\cw{\}}
\dd If this is set to \c{true}, then chapter headings will not
contain the word \q{Chapter} (or whatever other word you have
@@ -556,14 +606,24 @@ they will just contain the chapter \e{number}, followed by the
chapter title. If you set this to \c{false}, chapter headings will
be prefixed by \q{Chapter} or equivalent.
-\dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-chapter-shownumber\}}}\cw{\\cfg\{html-chapter-shownumber\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then chapter headings will \e{only}
+contain the chapter title: they will not contain the word
+\q{Chapter} (or whatever other word you have defined in its place),
+and neither will they contain the chapter number. If set to
+\c{false}, this overrides \cw{\\cfg\{html-chapter-numeric\}}.
+
+\dt \I{\cw{\\cfg\{html-chapter-suffix\}}}\cw{\\cfg\{html-chapter-suffix\}\{}\e{text}\cw{\}}
\dd This specifies the suffix text to be appended to the chapter
number, before displaying the chapter title. For example, if you set
this to \cq{:\_}, then the chapter title might look something
like \q{Chapter 2: Doing Things}.
-\dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+\dt \I{\cw{\\cfg\{html-section-numeric\}}}\cw{\\cfg\{html-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\# {level} can be omitted (defaults to 0). Is this intentional?
\dd Specifies whether section headings at a particular level should
contain the word \q{Section} or equivalent (if \c{false}), or should
@@ -572,17 +632,152 @@ which level of section headings you want to affect: 0 means
first-level headings (\c{\\H}), 1 means second-level headings
(\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
-\dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+\dt \I{\cw{\\cfg\{html-section-shownumber\}}}\cw{\\cfg\{html-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
+
+\dd If this is set to \c{false}, then section headings at the
+specified level will \e{only} contain the section title: they will
+not contain the word \q{Section} (or whatever other word you have
+defined in its place), and neither will they contain the section
+number. If set to \c{false}, this overrides
+\cw{\\cfg\{html-section-numeric\}}.
+
+\dt \I{\cw{\\cfg\{html-section-suffix\}}}\cw{\\cfg\{html-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
+
+\# {level} can be omitted (defaults to 0). Is this intentional?
\dd Specifies the suffix text to be appended to section numbers at a
particular level, before displaying the section title.
+\S{output-html-names} Configuring standard text
+
+These directives let you fine-tune the names Halibut uses in places
+such as the navigation bar to refer to various parts of the document,
+and other standard pieces of text, for instance to change them to a
+different language.
+
+\dt \I{\cw{\\cfg\{html-preamble-text\}}}\cw{\\cfg\{html-preamble-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-contents-text\}}}\cw{\\cfg\{html-contents-text\}\{}\e{text}\cw{\}}
+
+\dt \I{\cw{\\cfg\{html-index-text\}}}\cw{\\cfg\{html-index-text\}\{}\e{text}\cw{\}}
+
+\dd Text used to refer to the preamble (i.e., any paragraphs before
+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{