X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/0a6347b45815f2ef02120d42a3b3dbf79d289b1d..eefac897f92928aec04583f75ac6ecd243b9a982:/doc/output.but diff --git a/doc/output.but b/doc/output.but index 89eca4e..49a6b05 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}. @@ -8,12 +10,7 @@ that format. \H{output-text} Plain text This output format generates the document as a single \i{plain text} -file. - -The output file is currently assumed to be in the \i{ISO 8859-1} -character set. Any Unicode characters representable in this set will -be output verbatim; any other characters will not be output and -their \i{fallback text} (if any) will be used instead. +file. No table of contents or index is generated. The precise formatting of the text file can be controlled by a variety of configuration directives. They are listed in the @@ -107,18 +104,24 @@ left of that (so that it goes in the margin if there is room). Also, several of the directives below specify how a title should be \I{underlining}underlined. The parameter to one of these directives -should be either blank (\cw{\{\}}) or a single character. In the -latter case, that character will be used to underline the title. So -you might want to specify, for example, -\cw{\\text-title-underline\{=\}} but -\cw{\\text-chapter-underline\{-\}}. +should be either blank (\cw{\{\}}) or a piece of text which will be +repeated to produce the underline. So you might want to specify, for +example, \cw{\\text-title-underline\{=\}} but +\cw{\\text-chapter-underline\{\-\}}. + +You can also specify more than one underline setting, and Halibut +will choose the first one that the output character set supports. +So, for example, you could write +\cw{\\text-chapter-underline\{\\u203e\}\{\-\}}, and Halibut would use +the Unicode \q{OVERLINE} character where possible and fall back to +the ASCII minus sign otherwise. \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}} \dd Specifies the alignment of the overall document title: \c{left}, \c{leftplus} or \c{centre}. -\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}} +\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}} \dd Specifies how the overall document title should be underlined. @@ -126,7 +129,7 @@ you might want to specify, for example, \dd Specifies the alignment of chapter and appendix headings. -\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}} +\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}} \dd Specifies how chapter and appendix headings should be underlined. @@ -139,11 +142,19 @@ 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 number, before displaying the chapter title. For example, if you set -this to \q{\cw{:\_}}, then the chapter title might look something +this to \cq{:\_}, then the chapter title might look something like \q{Chapter 2: Doing Things}. \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}} @@ -155,7 +166,7 @@ headings you want to affect: 0 means first-level headings (\c{\\H}), that (\c{\\S2}), and so on. The \e{alignment} parameter is treated just like the other alignment directives listed above. -\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}} +\dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}} \dd Specifies how to underline section headings at a particular level. @@ -165,28 +176,119 @@ 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 be appended to section numbers at a particular level, before displaying the section title. -\S{output-text-misc} Miscellaneous configuration options +\S{output-text-characters} Configuring the characters used -\dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}} +\dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}} -\dd If this is set to \c{true}, \i{version ID paragraphs} (defined -using the \i\c{\\versionid} command - see \k{input-blurb}) will be -included at the bottom of the text file. If it is set to \c{false}, -they will be omitted completely. +\dd This tells Halibut what \i{character set} the output should be +in. Any Unicode characters representable in this set will be output +verbatim; any other characters will not be output and their +\i{fallback text} (if any) will be used instead. + +\lcont{ -\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}} +The character set names are the same as for +\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike +\cw{\\cfg\{input-charset\}}, this directive affects the \e{entire} +output; it's not possible to switch encodings halfway through. + +} + +\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] \dd This specifies the text which should be used as the \i{bullet} in bulletted lists. It can be one character (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one (\cw{\\cfg\{text-bullet\}\{(*)\}}). +\lcont{ + +Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple +possible options after this command, and Halibut will choose the first one +which the output character set supports. For example, you might write +\cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case +Halibut would use the Unicode \q{BULLET} character where possible, +fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available, +and resort to the ASCII asterisk if all else failed. + +} + +\dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-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}). It can be one character, or more than one. The +string you specify will be repeated to reach the required width, so +you can specify something like \cq{-=} to get a rule that looks +like \cw{-=-=-=}. + +\lcont{ + +Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback +options in this command. + +} + +\dt \I{\cw{\\cfg\{text-quotes\}}}\cw{\\cfg\{text-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}] + +\dd This specifies a set of quote characters for the text backend, +overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax +(see \k{input-config}). + +\lcont{ + +In this backend, these quotes will also be used to mark text enclosed +in the \c{\\c} command (see \k{input-code}). + +} + +\dt \I{\cw{\\cfg\{text-emphasis\}}}\cw{\\cfg\{text-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}] + +\dd This specifies the characters which should be used to surround +emphasised text (written using the \c{\\e} command; see +\k{input-emph}). + +\lcont{ + +You should separately specify the start-emphasis and end-emphasis +text, each of which can be more than one character if you want. +Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs +of fallback options in this command, and Halibut will always use a +matching pair. + +} + +\S{output-text-misc} Miscellaneous configuration options + +\dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}} + +\dd This text is appended to the number on a \i{numbered list} item +(see \k{input-list-number}). So if you want to label your lists as +\q{1)}, \q{2)} and so on, then you would write +\cw{\\cfg\{text-list-suffix\}\{)\}}. + +\dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{true}, \i{version ID paragraphs} (defined +using the \i\c{\\versionid} command - see \k{input-blurb}) will be +included at the bottom of the text file. If it is set to \c{false}, +they will be omitted completely. + \# FIXME: code indentation is configurable, therefore \quote \# indentation probably ought to be as well. @@ -206,25 +308,37 @@ The \i{default settings} for Halibut's plain text output format are: \c \cfg{text-indent-preamble}{false} \c \c \cfg{text-title-align}{centre} -\c \cfg{text-title-underline}{=} +\c \cfg{text-title-underline}{\u2550}{=} \c \c \cfg{text-chapter-align}{left} -\c \cfg{text-chapter-underline}{-} +\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 ... \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{text-charset}{ASCII} +\c \cfg{text-bullet}{\u2022}{-} +\c \cfg{text-rule}{\u2500}{-} +\c \cfg{text-quotes}{\u2018}{\u2019}{`}{'} +\c \cfg{text-emphasis}{_}{_} +\c +\c \cfg{text-list-suffix}{.} +\c \cfg{text-versionid}{true} \H{output-html} HTML @@ -236,25 +350,24 @@ 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 beginning to read the document, a good choice in many cases might be -\c{index.html} (but this is not the default, for historical +\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 @@ -266,50 +379,51 @@ cent sign, you can write \c{%%}.) The formatting commands used in this template are: -\dt \i\c{%N} +\dt \I{%N-upper}\c{%N} \dd Expands to the visible title of the section, with white space -removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching -Fish}}, this formatting command would expand to -\q{\cw{CatchingFish}}. +removed. So in a chapter declared as \cq{\\C\{fish\} Catching +Fish}, this formatting command would expand to +\cq{CatchingFish}. \dt \i\c{%n} \dd Expands to the type and number of the section, without white -space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in -section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on. +space. So in chapter 1 this would expand to \cq{Chapter1}; in +section A.4.3 it would expand to \cq{SectionA.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{%b} -\dd Expands to the bare number of the section. So in chapter 1 this -would expand to \q{\cw{1}}; in section A.4.3 it would expand to -\q{\cw{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} \dd Expands to the internal keyword specified in the section title. -So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this -formatting command would expand to \q{\cw{fish}}. If the section has +So in a chapter declared as \cq{\\C\{fish\} Catching Fish}, this +formatting command would expand to \cq{fish}. If the section has 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}). @@ -326,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 @@ -340,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 @@ -348,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{ @@ -361,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 @@ -397,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 @@ -418,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 @@ -461,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 \q{\cw{:\_}}, then the chapter title might look something +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{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 @@ -477,110 +632,422 @@ 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{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{} tag, this +text is used to separate them. + +\# Under what circumstances can this occur? + +\dt \I{\cw{\\cfg\{html-index-main-separator\}}}\cw{\\cfg\{html-index-main-separator\}\{}\e{text}\cw{\}} + +\dd Separator between index term and references in the index. + +\dt \I{\cw{\\cfg\{html-index-multiple-separator\}}}\cw{\\cfg\{html-index-multiple-separator\}\{}\e{text}\cw{\}} + +\dd Separator between multiple references for a single index term in +the index. + +\dt \I{\cw{\\cfg\{html-pre-versionid\}}}\cw{\\cfg\{html-pre-versionid\}\{}\e{text}\cw{\}} + +\dt \I{\cw{\\cfg\{html-post-versionid\}}}\cw{\\cfg\{html-post-versionid\}\{}\e{text}\cw{\}} + +\dd Text surrounding each output \i{version ID paragraph}. + +\dt \I{\cw{\\cfg\{html-nav-prev-text\}}}\cw{\\cfg\{html-nav-prev-text\}\{}\e{text}\cw{\}} + +\dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}} + +\dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}} + +\dd The text used for the \q{previous page}, \q{next page}, and \q{up} +links on the navigation bar. + +\dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}} + +\dd Separator between links in the navigation bar. + +\S{output-html-characters} Configuring the characters used + +Unlike the other backends, HTML does not have a single +\i\cw{\\cfg\{html-charset\}} directive, as there are several levels of +character encoding to consider. + +The character set names are the same as for +\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike +\cw{\\cfg\{input-charset\}}, these directives affect the \e{entire} +output; it's not possible to switch encodings halfway through. + +\dt \I\cw{\\cfg\{html-output-charset\}}\cw{\\cfg\{html-output-charset\}\{}\e{character set name}\cw{\}} + +\dd The character encoding of the HTML file to be output. Unicode +characters in this encoding's repertoire are included literally rather +than as \i{HTML entities}. + +\dt \I\cw{\\cfg\{html-restrict-charset\}}\cw{\\cfg\{html-restrict-charset\}\{}\e{character set name}\cw{\}} + +\dd Only Unicode characters representable in this character set will be +output; any others will be omitted and use their fallback text, if +any. Characters not in \q{html-output-charset} will be represented as +HTML numeric entities. + +\dt \I{\cw{\\cfg\{html-quotes\}}}\cw{\\cfg\{html-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 +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + \S{output-html-misc} Miscellaneous options -\dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}} +\dt \I\cw{\\cfg\{html-version\}}\cw{\\cfg\{html-version\}\{}\e{version}\cw{\}} + +\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 declared version. The +available variants are: + +\lcont{ + +\dt \cw{html3.2} + +\dd W3C HTML 3.2 + +\dt \cw{html4} + +\dd W3C HTML 4.01 Strict + +\dt \cw{iso-html} + +\dd ISO/IEC 15445:2000 + +\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{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}] \dd This directive lets you specify a \i{template}, with exactly the -same syntax used in \cw{\\cfg\{xhtml-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 within -a particular HTML file. So if you set this to \q{\cw{%k}}, for -example, then each individual section in your document will be +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 +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 internal section keyword. -\dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}} +\lcont{ + +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. + +} + +\dt \I{\cw{\\cfg\{html-versionid\}}}\cw{\\cfg\{html-versionid\}\{}\e{boolean}\cw{\}} \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using the \i\c{\\versionid} command - see \k{input-blurb}) will be included visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML -file. If it is set to \c{false}, they will be omitted completely. +file. If it is set to \c{false}, they will only be included as HTML +comments. -\# FIXME: surely it would be better to include them in HTML -\# comments? The only question is whether they should be _visible_. +\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="next">} 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{ -\dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}} +Some browsers make use of this semantic information, for instance to +allow easy navigation through related pages, and to prefetch the next +page. (Search engines can also make use of it.) 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 bottom of each HTML file will be omitted completely. (This will -therefore also cause \i{version IDs} not to be included.) +therefore also cause \i{version IDs} not to be included visibly.) -\dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}} +\dt \I{\cw{\\cfg\{html-author\}}}\cw{\\cfg\{html-author\}\{}\e{text}\cw{\}} \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META name="author">} tag in the output HTML files, so that browsers which support this can automatically identify the \i{author} of the document. -\dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}} +\dt \I{\cw{\\cfg\{html-description\}}}\cw{\\cfg\{html-description\}\{}\e{text}\cw{\}} \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META name="description">} tag in the output HTML files, so that browsers 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{xhtml-contents-filename}{Contents.html} -\c \cfg{xhtml-index-filename}{IndexPage.html} -\c \cfg{xhtml-template-filename}{%n.html} -\c \cfg{xhtml-single-filename}{Manual.html} -\c \cfg{xhtml-template-fragment}{%b} -\c -\c \cfg{xhtml-leaf-level}{2} -\c \cfg{xhtml-leaf-contains-contents}{false} -\c \cfg{xhtml-leaf-smallest-contents}{4} -\c \cfg{xhtml-contents-depth-0}{2} -\c \cfg{xhtml-contents-depth-1}{3} -\c \cfg{xhtml-contents-depth-2}{4} -\c \cfg{xhtml-contents-depth-3}{5} -\c \cfg{xhtml-contents-depth-4}{6} -\c \cfg{xhtml-contents-depth-5}{7} -\c -\c \cfg{xhtml-head-end}{} -\c \cfg{xhtml-body-tag}{<body>} -\c \cfg{xhtml-body-start}{} -\c \cfg{xhtml-body-end}{} -\c \cfg{xhtml-address-start}{} -\c \cfg{xhtml-address-end}{} -\c \cfg{xhtml-navigation-attributes}{} -\c -\c \cfg{xhtml-versionid}{true} -\c \cfg{xhtml-suppress-address}{false} -\c \cfg{xhtml-author}{} -\c \cfg{xhtml-description}{} -\c -\c \cfg{xhtml-chapter-numeric}{false} -\c \cfg{xhtml-chapter-suffix}{: } -\c -\c \cfg{xhtml-section-numeric}{0}{true} -\c \cfg{xhtml-section-suffix}{0}{ } -\c -\c \cfg{xhtml-section-numeric}{1}{true} -\c \cfg{xhtml-section-suffix}{1}{ } +\c \cfg{html-contents-filename}{Contents.html} +\c \cfg{html-index-filename}{IndexPage.html} +\c \cfg{html-template-filename}{%n.html} +\c \cfg{html-single-filename}{Manual.html} \c +\c \cfg{html-leaf-level}{2} +\c \cfg{html-leaf-contains-contents}{false} +\c \cfg{html-leaf-smallest-contents}{4} +\c \cfg{html-contents-depth}{0}{2} +\c \cfg{html-contents-depth}{1}{3} \c ... and so on for all section levels below this ... \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{html-head-end}{} +\c \cfg{html-body-tag}{<body>} +\c \cfg{html-body-start}{} +\c \cfg{html-body-end}{} +\c \cfg{html-address-start}{} +\c \cfg{html-address-end}{} +\c \cfg{html-navigation-attributes}{} +\c +\c \cfg{html-chapter-numeric}{false} +\c \cfg{html-chapter-shownumber}{true} +\c \cfg{html-chapter-suffix}{: } +\c +\c \cfg{html-section-numeric}{0}{true} +\c \cfg{html-section-shownumber}{0}{true} +\c \cfg{html-section-suffix}{0}{ } +\c +\c \cfg{html-section-numeric}{1}{true} +\c \cfg{html-section-shownumber}{1}{true} +\c \cfg{html-section-suffix}{1}{ } +\c +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{html-preamble-text}{Preamble} +\c \cfg{html-contents-text}{Contents} +\c \cfg{html-index-text}{Index} +\c \cfg{html-title-separator}{ - } +\c \cfg{html-index-main-separator}{: } +\c \cfg{html-index-multiple-separator}{, } +\c \cfg{html-pre-versionid}{[} +\c \cfg{html-post-versionid}{]} +\c \cfg{html-nav-prev-text}{Previous} +\c \cfg{html-nav-next-text}{Next} +\c \cfg{html-nav-up-text}{Up} +\c \cfg{html-nav-separator}{ | } +\c +\c \cfg{html-output-charset}{ASCII} +\c \cfg{html-restrict-charset}{UTF-8} +\c \cfg{html-quotes}{\u2018}{\u2019}{"}{"} +\c +\c \cfg{html-version}{html4} +\c \cfg{html-template-fragment}{%b} +\c \cfg{html-versionid}{true} +\c \cfg{html-rellinks}{true} +\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}. +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: +\S{output-whlp-file} Output file name + \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}} -\dd Sets the \i{output file name} in which to store the man page. +\dd Sets the \i{output file name} in which to store the help file. This directive is implicitly generated if you provide a file name parameter after the command-line option \i\c{--winhelp} (see \k{running-options}). @@ -593,6 +1060,42 @@ Halibut will append it. Halibut will also generate a contents file } +\S{output-whlp-characters} Configuring the characters used + +\dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to use as the \i{bullet} in bulletted lists. +You can specify multiple fallback options. Works exactly like the +\cw{\\cfg\{text-bullet\}} directive (see +\k{output-text-characters}). + +\dt \I{\cw{\\cfg\{winhelp-quotes\}}}\cw{\\cfg\{winhelp-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 +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + +\S{output-whlp-misc} Miscellaneous configuration options + +\dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}} + +\dd Sets the text used to describe the help page containing the blurb +(see \k{input-blurb}) and table of contents. + +\dt +\I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}} + +\dd Specifies the \I{suffix text, in section titles}suffix text to +be appended to section numbers, before displaying the section title. +(Applies to all levels.) + +\dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}} + +\dd This text is appended to the number on a \i{numbered list} item, +in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see +\k{output-text-characters}). + \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}} \dd This directive defines a Windows \i{Help topic} name in the current @@ -618,9 +1121,18 @@ different help contexts which you can use in this way. } +\S{output-whlp-defaults} Default settings + The \i{default settings} for the Windows Help output format are: \c \cfg{winhelp-filename}{output.hlp} +\c +\c \cfg{winhelp-bullet}{\u2022}{-} +\c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"} +\c +\c \cfg{winhelp-contents-titlepage}{Title page} +\c \cfg{winhelp-section-suffix}{: } +\c \cfg{winhelp-list-suffix}{.} and no \c{\\cfg\{winhelp-topic\}} directives anywhere. @@ -632,6 +1144,8 @@ macro package. The available configuration options for this format are as follows: +\S{output-man-file} Output file name + \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}} \dd Sets the \i{output file name} in which to store the man page. @@ -639,6 +1153,8 @@ This directive is implicitly generated if you provide a file name parameter after the command-line option \i\c{--man} (see \k{running-options}). +\S{output-man-identity} Configuring headers and footers + \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}} \dd This directive is used to generate the initial \i{\c{.TH} @@ -662,10 +1178,13 @@ A traditional order for the arguments appears to be: For example, a typical \cw{man} page might contain -\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs} +\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred +\c Bloggs} } +\S{output-man-headings} Configuring heading display + \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}} \dd If this is set to \c{true}, then \i{section headings} in the @@ -704,7 +1223,8 @@ simply says Then you have a file \c{make-foo.but}, and probably others like it as well, each of which looks something like this: -\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs} +\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred +\c Bloggs} \c \c \H{man-foo} \cw{man} page for \c{make-foo} \c @@ -734,9 +1254,646 @@ expect. } +\S{output-man-characters} Configuring the characters used + +\dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}} + +\dd Specifies what character set the output should be in, similarly to +\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}). + +\# FIXME: you're probably on your own in making sure that it's +sensible to output man pages in that charset. + +\dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to use as the \i{bullet} in bulletted lists. +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 +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + +\S{output-man-defaults} Default settings + The \i{default settings} for the \cw{man} page output format are: \c \cfg{man-filename}{output.1} +\c \c \cfg{man-identity}{} +\c \c \cfg{man-headnumbers}{false} \c \cfg{man-mindepth}{0} +\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 Info + +This output format generates files which can be used with the \i{GNU +Info} program. + +There are typically multiple output files: a primary file whose name +usually ends in \c{.info}, and one or more subsidiary files whose +names have numbers on the end, so that they end in \c{.info-1}, +\c{.info-2} and so on. Alternatively, this output format can be +configured to output a single large file containing the whole +document. + +The Info output format supports the following configuration +directives: + +\S{output-info-file} Controlling the output filenames + +\dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}} + +\dd Sets the output file name in which to store the Info file. +This directive is implicitly generated if you provide a file name +parameter after the command-line option \i\c{--info} (see +\k{running-options}). + +\lcont{ + +The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to +your output file name to produce any subsidiary files required. + +Note that Info files refer to their own names internally, so +these files cannot be \I{renaming Info files}renamed after +creation and remain useful. + +} + +\dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}} + +\dd Sets the preferred \i{maximum file size} for each subsidiary +file. As a special case, if you set this to zero, there will be no +subsidiary files and the whole document will be placed in a single +self-contained output file. (However, note that this file can still +not be renamed usefully.) + +\lcont{ + +The preferred maximum file size is only a guideline. Halibut may be +forced to exceed it if a single section of the document is larger +than the maximum size (since individual Info nodes may not be +split between files). + +} + +\S{output-info-dimensions} Indentation and line width + +\dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}} + +\dd Sets the \I{text width}width of the main part of the document, +in characters. Works exactly like the \cw{\\cfg\{text-width\}} +directive (see \k{output-text-dimensions}). + +\dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}} + +\dd Specifies the extra indentation for \I{code paragraphs, +indentation} code paragraphs. Works exactly like the +\cw{\\cfg\{text-indent-code\}} directive (see +\k{output-text-dimensions}). + +\dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}} + +\dd Specifies how much horizontal space to leave in the index node +for the text of \i{index terms}, before displaying the sections the +terms occur in. + +\dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}} + +\dd Specifies the extra indentation before the bullet or number in a +\I{bulletted list, indentation}\I{numbered list, indentation}list +item. Works exactly like the \cw{\\cfg\{text-list-indent\}} +directive (see \k{output-text-dimensions}). + +\dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}} + +\dd Specifies the additional indentation before the body of a list +item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}} +directive (see \k{output-text-dimensions}). + +\S{output-info-headings} Configuring heading display + +\dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}} + +\dd Specifies the suffix text to be appended to each section number +before displaying the section title. For example, if you set this to +\cq{:\_}, then a typical section title might look something like +\q{Section 3.1: Something Like This}. + +\dt \I{\cw{\\cfg\{info-title-underline\}}}\cw{\\cfg\{info-title-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to be used to \I{underlining}underline +the overall document title. Works +very much like the \cw{\\cfg\{text-title-underline\}} directive +(see \k{output-text-headings}). You can specify more than one +option, and Halibut will choose the first one supported by the +character set. + +\dt \I{\cw{\\cfg\{info-chapter-underline\}}}\cw{\\cfg\{info-chapter-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies how chapter and appendix headings should be underlined. + +\dt \I{\cw{\\cfg\{info-section-underline\}}}\cw{\\cfg\{info-section-underline\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies how to underline section headings at a particular level. +The \e{level} parameter specifies 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. + +\S{output-info-characters} Controlling the characters used + +\dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}} + +\dd Specifies what character set the output should be in, similarly to +\cw{\\cfg\{text-charset\}} (see \k{output-text-characters}). + +\# FIXME: if you try sufficiently hard, you can probably find an +output encoding that will break the info format by trampling on its +special characters. So either don't do that, or tell us what we should +do about it. + +\dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to use as the \i{bullet} in bulletted lists. +You can specify multiple fallback options. Works exactly like the +\cw{\\cfg\{text-bullet\}} directive (see +\k{output-text-characters}). + +\dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text used to draw \i{horizontal rules}. You can +specify multiple fallback options. Works exactly like the +\cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}). + +\dt \I{\cw{\\cfg\{info-quotes\}}}\cw{\\cfg\{info-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 +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + +\dt \I{\cw{\\cfg\{info-emphasis\}}}\cw{\\cfg\{info-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}] + +\dd Specifies how to display emphasised text. You can specify +multiple fallback options. Works exactly like the +\cw{\\cfg\{text-emphasis\}} directive (see +\k{output-text-characters}). + +\S{output-info-misc} Miscellaneous configuration options + +\dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}} + +\dd Specifies the text to append to the item numbers in a +\i{numbered list}. Works exactly like the +\cw{\\cfg\{text-list-suffix\}} directive (see +\k{output-text-misc}). + +\dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short +name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}] + +\dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the +header of the Info file. This mechanism is used to automatically +generate the \i{\c{dir} file} at the root of a Unix system's +Info collection. + +\lcont{ + +The parameters to this directive are: + +\dt \e{section} + +\dd Specifies the section of the \c{dir} file in which you want your +document referenced. For example, \q{Development}, or \q{Games}, or +\q{Miscellaneous}. + +\dt \e{short name} + +\dd Specifies a short name for the directory entry, which will +appear at the start of the menu line. + +\dt \e{long name} + +\dd Specifies a long name for the directory entry, which will appear +at the end of the menu line. + +\dt \e{keyword} + +\dd This parameter is optional. If it is present, then the directory +entry will cause a jump to a particular subsection of your document, +rather than starting at the top. The subsection will be the one +referred to by the given keyword (see \k{input-sections} for details +about assigning keywords to document sections). + +For example, in a document describing many game programs, the +configuration directive + +\c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess +\c game}{chess} + +might produce text in the \c{dir} file looking something like this: + +\c Games +\c * Chess: (mygames)Chapter 3. Electronic chess game + +if the output file were called \c{mygames.info} and the keyword +\c{chess} had been used to define Chapter 3 of the document. + +} + +\S{output-info-defaults} Default settings + +The \i{default settings} for the Info output format are: + +\c \cfg{info-filename}{output.info} +\c \cfg{info-max-file-size}{65536} +\c +\c \cfg{info-width}{70} +\c \cfg{info-indent-code}{2} +\c \cfg{info-index-width}{40} +\c \cfg{info-list-indent}{1} +\c \cfg{info-listitem-indent}{3} +\c +\c \cfg{info-section-suffix}{: } +\c \cfg{info-title-underline}{*} +\c \cfg{info-chapter-underline}{=} +\c \cfg{info-section-underline}{0}{-} +\c \cfg{info-section-underline}{1}{.} +\c \cfg{info-section-underline}{2}{.} +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{info-charset}{ASCII} +\c \cfg{info-bullet}{\u2022}{-} +\c \cfg{info-rule}{\u2500}{-} +\c \cfg{info-quotes}{\u2018}{\u2019}{`}{'} +\c \cfg{info-emphasis}{_}{_} +\c +\c \cfg{info-list-suffix}{.} + +and no \cw{\\cfg\{info-dir-entry\}} directives. + +\H{output-paper} Paper formats + +These output formats (currently PDF and PostScript) generate printable +manuals. As such, they share a number of configuration directives. + +\S{output-pdf} \i{PDF} + +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. + +There is one configuration option specific to PDF: + +\dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}} + +\dd Sets the \i{output file name} in which to store the PDF file. +This directive is implicitly generated if you provide a file name +parameter after the command-line option \i\c{--pdf} (see +\k{running-options}). + +The \i{default settings} for the PDF output format are: + +\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). + +\S2{output-paper-pagesize} Page properties + +\dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}} + +\dd Specify the absolute limits of the paper. + +\dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}} + +\dd Specify the margins. Most text appears within these margins, +except: + +\lcont{ + +\b Section numbers, which appear in the left margin. + +\b The footer (containing page numbers), which appears in the bottom +margin. + +} + +\S2{output-paper-line} Vertical spacing + +\dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of space between lines of text within a +paragraph. (So, if the font size is 12pt and there is 2pt of leading, +there will be 14pt between successive baselines.) + +\dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of vertical space between paragraphs. (The +vertical space between paragraphs does \e{not} include +\c{paper-base-leading}.) + +\S2{output-paper-indentation} Indentation + +\dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}} + +\dd Specifies the indentation of the bullet or number in a +\I{bulletted list, indentation}bulletted or \I{numbered list, +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{\}} + +\dd Specifies the \e{extra} indentation for the body of a list item, +over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}. + +\# FIXME: doesn't actually work, AFAICT. + +\dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of indentation for a level of quoting. Used +for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c} +(see \k{input-code}). + +\S2{output-paper-headings} Headings + +\dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}} + +\dd Specifies the space between the top margin and the top of the +chapter heading. (Each chapter begins on a new page.) + +\dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}} + +\dd Specifies the vertical thickness of the black rule under chapter +headings. + +\dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the base of the chapter heading and +the \e{base} of the underlying rule. + +\dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the left margin and the \e{right} +of section numbers (which are in the left margin). + +\S2{output-paper-index} Contents and index + +\dt \I{\cw{\\cfg\{paper-contents-indent-step\}}}\cw{\\cfg\{paper-contents-indent-step\}\{}\e{points}\cw{\}} + +\dd Specifies by how much to indent each entry in the table of +contents per level of subdivision in the document. (In other words, +chapter titles appear at the left of the table of contents, headings +within the chapter are indented by the amount configured here, +subheadings by twice that, and so on.) + +\dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of space on the right of the table of +contents which should be reserved for page numbers only. Headings in +the table of contents which extend into this space will be wrapped. + +\dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}} + +\dd Specifies the horizontal spacing between dots in \i\e{leaders} +(the dotted lines that appear between section headings and page +numbers in the table of contents). + +\dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the bottom margin and the \e{base} +of the footer (which contains page numbers). + +\dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}} + +\dd Specifies the number of columns the index should be divided into. + +\# FIXME: with this set to 1, the right-alignment of some index entry +page numbers in the Halibut manual is decidedly wonky. + +\dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of \I{gutter} horizontal space between index +columns. + +\dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}} + +\dd Specifies the minimum allowable horizontal space between an index +entry and its page number. If the gap is smaller, the page number is +moved to the next line. + +\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. + +Halibut intrinsically knows about some fonts, and these fonts are also +built into all PDF and most PostScript implementations. +These fonts can be used without further formality. Halibut can also use +other fonts, and can \I{embedding fonts}embed them it its PDF and +PostScript output. These other fonts are supplied to Halibut by +simply adding them to the list of input files on its command line. + +To use a \i{Type 1 font} Halibut needs both the font file itself, +in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB) +format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file. The AFM +file must be specified first on the command line. If Halibut gets an +AFM file without a corresponding Type 1 font file, the PostScript and +PDF output files will still use that font, but they won't contain it. + +Using a \i{TrueType font} is rather simpler, and simply requires you to +pass the font file to Halibut. Halibut does place a few restrictions on +TrueType fonts, notably that they must include a \i{Unicode} mapping +table and a PostScript name. + +Fonts are specified using their PostScript names. Running Halibut with +the \i\cw{\-\-list-fonts} option causes it to display the PostScript +names of all the fonts it intrinsically knows about, along with any +fonts the were supplied as input files. + +\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 \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 paragraphs. 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 \i{page numbers}. + +\S2{output-paper-misc} Miscellaneous + +\dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}} + +\dd Specifies the vertical thickness of the rule produced by the +\cw{\\rule} command (see \k{input-rule}). (Note that no extra space is +reserved for thicker rules.) + +\S{output-paper-characters} Configuring the characters used + +\dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to use as the \i{bullet} in bulletted lists. +You can specify multiple fallback options. Works exactly like the +\cw{\\cfg\{text-bullet\}} directive (see +\k{output-text-characters}). + +\dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-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 +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + +\S{output-paper-defaults} Default settings for paper formats + +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}{842} +\c +\c \cfg{paper-left-margin}{72} +\c \cfg{paper-top-margin}{72} +\c \cfg{paper-right-margin}{72} +\c \cfg{paper-bottom-margin}{108} +\c +\c \cfg{paper-base-leading}{1} +\c \cfg{paper-base-para-spacing}{10} +\c +\c \cfg{paper-list-indent}{6} +\c \cfg{paper-listitem-indent}{18} +\c \cfg{paper-quote-indent}{18} +\c +\c \cfg{paper-chapter-top-space}{72} +\c \cfg{paper-chapter-underline-thickness}{3} +\c \cfg{paper-chapter-underline-depth}{14} +\c \cfg{paper-sect-num-left-space}{12} +\c +\c \cfg{paper-contents-indent-step}{24} +\c \cfg{paper-contents-margin}{84} +\c \cfg{paper-leader-separation}{12} +\c \cfg{paper-footer-distance}{32} +\c \cfg{paper-index-columns}{2} +\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} +\c +\c \cfg{paper-bullet}{\u2022}{-} +\c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}