X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/fc8e7adbb194aca9bee7e1c76283b90af302618f..75697cf31cbb6a89c251bdf1f78b7ffa0b65e7a5:/doc/output.but diff --git a/doc/output.but b/doc/output.but index 986f53d..964f49d 100644 --- a/doc/output.but +++ b/doc/output.but @@ -8,12 +8,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 +102,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 +127,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. @@ -143,7 +144,7 @@ be prefixed by \q{Chapter} or equivalent. \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 +156,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. @@ -171,22 +172,104 @@ be numeric only (if \c{true}). 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. -\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}} +\lcont{ + +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,10 +289,10 @@ 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-suffix}{: } \c @@ -225,9 +308,21 @@ The \i{default settings} for Halibut's plain text output format are: \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 +\# 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 @@ -266,18 +361,18 @@ 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}. @@ -285,16 +380,16 @@ 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 \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 +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}. \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}. @@ -465,10 +560,10 @@ be prefixed by \q{Chapter} or equivalent. \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\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} \dd Specifies whether section headings at a particular level should contain the word \q{Section} or equivalent (if \c{false}), or should @@ -477,7 +572,7 @@ 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\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} \dd Specifies the suffix text to be appended to section numbers at a particular level, before displaying the section title. @@ -490,7 +585,7 @@ particular level, before displaying the section title. same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see \k{output-html-file}), to be used for the anchor names (\i\cw{}) used to allow URLs to refer to specific sections -within a particular HTML file. So if you set this to \q{\cw{%k}}, +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. @@ -575,9 +670,14 @@ This output format generates data that can be used by the \i{Windows Help} program \cw{WINHELP.EXE}. There are two actual files generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. +Currently, the output is harcoded to be in the \q{\i{Win1252}} +character set. + 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. @@ -593,6 +693,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 +754,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 +777,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 +786,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} @@ -667,6 +816,8 @@ For example, a typical \cw{man} page might contain } +\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 @@ -736,12 +887,43 @@ 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-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-quotes}{\u2018}{\u2019}{"}{"} \H{output-info} GNU \c{info} @@ -758,6 +940,8 @@ document. The \c{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 \c{info} file. @@ -793,6 +977,105 @@ 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-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to be used to underline section titles. Works +very much like the \cw{\\cfg\{text-chapter-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. + +\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{\}}] @@ -845,12 +1128,42 @@ if the output file were called \c{mygames.info} and the keyword } -\H{output-ps} \i{PostScript} +\S{output-info-defaults} Default settings + +The \i{default settings} for the \c{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-underline}{\u203e}{-} +\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 PostScript and PDF) generate printable +manuals. As such, they share a number of configuration directives. + +\S{output-ps} \i{PostScript} This output format generates a printable manual in PostScript format. -This format is currently very new and is not yet configurable. There -is only one available configuration option: +There is one configuration option specific to PostScript: \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} @@ -863,7 +1176,7 @@ The \i{default settings} for the PostScript output format are: \c \cfg{ps-filename}{output.ps} -\H{output-pdf} \i{PDF} +\S{output-pdf} \i{PDF} This output format generates a printable manual in PDF format. This should look exactly identical to the PostScript output (see @@ -871,8 +1184,7 @@ should look exactly identical to the PostScript output (see provide an outline of all the document's sections and clickable cross-references between sections. -This format is currently very new and is not yet configurable. There -is only one available configuration option: +There is one configuration option specific to PDF: \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}} @@ -884,3 +1196,215 @@ parameter after the command-line option \i\c{--pdf} (see The \i{default settings} for the PDF output format are: \c \cfg{pdf-filename}{output.pdf} + +\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}numbers \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 \#{XXX check} and the +top of the chapter heading. (Each chapter begins on a new page.) + +\# FIXME: the first page of the Index gets mangled if this is +set to zero. + +\# FIXME: exact relationship to top-margin? + +\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-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}} + +\# FIXME: I do not know what dees one does. (I couldn't get either of +them to do anything obvious, although the source indicates they should +do something.) + +\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} Fonts + +\dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the font size of body text. + +\# FIXME: actually, this doesn't appear to do anything at all - most +font sizes are still hardcoded. + +\dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the font size to use for page numbers. + +\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}{841} +\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-index-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-font-size}{12} +\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}{'}{'}