X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/16ea3abeef2cdf062cd0270d920fc5ed47f94ff9..febdf756993ef8acdcb8b9c54b3b0a7eeb2abced:/doc/output.but?ds=sidebyside diff --git a/doc/output.but b/doc/output.but index 591952f..68fc04e 100644 --- a/doc/output.but +++ b/doc/output.but @@ -1,122 +1,137 @@ \C{output} Halibut output formats -This chapter describes each of Halibut's current output formats. It -gives some general information about the format, and also describes -all the configuration directives which are specific to that format. +This chapter describes each of Halibut's current \i{output formats}. +It gives some general information about the format, and also +describes all the \i{configuration directives} which are specific to +that format. \H{output-text} Plain text -This output format generates the document as a single plain text -file, under the name \c{output.txt}. - -The output file is currently assumed to be in the 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 fallback text (if any) will be used instead. +This output format generates the document as a single \i{plain text} +file. No index is generated. The precise formatting of the text file can be controlled by a variety of configuration directives. They are listed in the following subsections. +\S{output-text-file} Output file name + +\dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}} + +\dd Sets the \i{output file name} in which to store the text file. +This directive is implicitly generated if you provide a file name +parameter after the command-line option \i\c{--text} (see +\k{running-options}). + \S{output-text-dimensions} Indentation and line width This section describes the configuration directives which control -the horizontal dimensions of the output text file: how much +the \i{horizontal dimensions} of the output text file: how much paragraphs are indented by and how long the lines are. -\dt \cw{\\cfg\{text-width\}\{}\e{width}\cw{\}} +\dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}} -\dd Sets the width of the main part of the document, in characters. -This width will be used for wrapping paragraphs and for centring -titles (if you have asked for titles to be centred - see -\k{output-text-headings}). This width does \e{not} include the left -indentation set by \cw{\\cfg\{text-indent\}}; if you specify an +\dd Sets the \I{text width}width of the main part of the document, +in characters. This width will be used for wrapping paragraphs and +for centring titles (if you have asked for titles to be centred - +see \k{output-text-headings}). This width does \e{not} include the +left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an indent of 8 and a width of 64, your maximum output line length will be 72. -\dt \cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}} +\dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}} -\dd Sets the left indentation for the document. If you set this to -zero, your document will look like an ordinary text file as someone -with a text editor might have written it; if you set it above zero, -the text file will have a margin down the left in the style of some -printed manuals, and you can then configure the section numbers to -appear in this margin (see \k{output-text-headings}). +\dd Sets the left \i{indentation} for the document. If you set this +to zero, your document will look like an ordinary text file as +someone with a text editor might have written it; if you set it +above zero, the text file will have a \i{margin} down the left in +the style of some printed manuals, and you can then configure the +section numbers to appear in this margin (see +\k{output-text-headings}). -\dt \cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}} +\dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}} \dd Specifies how many extra characters of indentation (on top of -the normal left indent) should be given to code paragraphs. +the normal left indent) should be given to \I{code paragraphs, +indentation} code paragraphs. -\dt \cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}} +\dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}} \dd Specifies how many extra spaces should be used to indent the -bullet or number in a bulletted or numbered list. The actual body of -the list item will be indented by this much \e{plus} the value -configured by \cw{\\cfg\{text-listitem-indent\}}. +bullet or number in a \I{bulletted list, indentation}bulletted or +\I{numbered list, indentation}numbered \I{list, indentation}list. +The actual body of the list item will be indented by this much +\e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}. -\dt \cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}} +\dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}} \dd Specifies how many extra spaces should be used to indent the body of a list item, over and above the number configured in \cw{\\cfg\{text-list-indent\}}. -\dt \cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}} +\dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}} -\dd When this is set to \c{true}, the document preamble (i.e. any +\dd When this is set to \c{true}, the document \i{preamble} (i.e. any paragraphs appearing before the first chapter heading) will be indented to the level specified by \cw{\\cfg\{text-indent\}}. If this setting is \c{false}, the document preamble will not be indented at all from the left margin. -\S{output-text-headings} Configuring heading display +\S{output-text-headings} \ii{Configuring heading display} The directives in this section allow you to configure the appearance of the title, chapter and section headings in your text file. -Several of the directives listed below specify the alignment of a -heading. These alignment options have three possible values: +Several of the directives listed below specify the \i{alignment} of +a heading. These alignment options have three possible values: -\dt \c{left} +\dt \i\c{left} \dd Align the heading to the very left of the text file (column zero). -\dt \c{leftplus} +\dt \i\c{leftplus} \dd Align the section title to the left of the main display region (in other words, indented to the level specified by \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the left of that (so that it goes in the margin if there is room). -\dt \c{centre} +\dt \i\c{centre} \dd Centre the heading. Also, several of the directives below specify how a title should be -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\{-\}}. +\I{underlining}underlined. The parameter to one of these directives +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\{\-\}}. -\dt \cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}} +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 \cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}} +\dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}} \dd Specifies how the overall document title should be underlined. -\dt \cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}} +\dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}} \dd Specifies the alignment of chapter and appendix headings. -\dt \cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}} +\dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}} \dd Specifies how chapter and appendix headings should be underlined. -\dt \cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}} +\dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-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 @@ -125,14 +140,14 @@ they will just contain the chapter \e{number}, followed by the chapter title. If you set this to \c{false}, chapter headings will be prefixed by \q{Chapter} or equivalent. -\dt \cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}} +\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 like \q{Chapter 2: Doing Things}. -\dt \cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}} +\dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}} \dd Specifies the alignment of section headings at a particular level. The \e{level} parameter specifies which level of section @@ -141,36 +156,119 @@ 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 \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-character}\cw{\}} \dd Specifies how to underline section headings at a particular level. -\dt \cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} +\dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-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 be numeric only (if \c{true}). -\dt \cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} +\dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-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. +\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-characters} Configuring the characters used + +\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 \q{\cw{-=}} 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 \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}, version ID paragraphs (defined using the -\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 \cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}} +\lcont{ -\dd This specifies the text which should be used as the bullet in -bulletted lists. It can be one character -(\cw{\\cfg\{text-bullet\}\{-\}}), or more than one -(\cw{\\cfg\{text-bullet\}\{(*)\}}). +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-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. @@ -179,8 +277,10 @@ bulletted lists. It can be one character \S{output-text-defaults} Default settings -The default settings for Halibut's plain text output format are: +The \i{default settings} for Halibut's plain text output format are: +\c \cfg{text-filename}{output.txt} +\c \c \cfg{text-width}{68} \c \cfg{text-indent}{7} \c \cfg{text-indent-code}{2} @@ -189,10 +289,10 @@ The 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 @@ -208,22 +308,103 @@ The 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-bullet}{\u2022}{-} +\c \cfg{text-rule}{\u2500}{-} +\c \cfg{text-quotes}{\u2018}{\u2019}{`}{'} +\c \cfg{text-emphasis}{_}{_} +\c +\c \cfg{text-charset}{ASCII} +\c \cfg{text-list-suffix}{.} +\c \cfg{text-versionid}{true} \H{output-html} HTML -This output format generates an HTML version of the document. By +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 and/or subsection. You can configure precisely how the text is split 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, in which case it will be -called \c{Manual.html} (but you can rename it easily enough). +single HTML file instead of multiple ones. -Strictly speaking, the output format is XHTML 1.0 Transitional, +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}. +\S{output-html-file} Controlling the output file names + +\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-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} (although this is not the default, for historical +reasons). + +\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-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{\}} + +\dd Provides a \i{template} to be used when constructing the file +names of each chapter or section of the document. This template +should contain at least one \i\e{formatting command}, in the form of +a per cent sign followed by a letter. (If you need a literal per +cent sign, you can write \c{%%}.) + +\lcont{ + +The formatting commands used in this template are: + +\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}}. + +\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. +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}. + +\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 +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 +\k{output-html-misc}). + +} + +\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-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 +produce a single self-contained file. Both this directive \e{and} +\c{\\cfg\{xhtml-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}). + \S{output-html-split} Controlling the splitting into HTML files By default, the HTML output from Halibut is split into multiple @@ -237,27 +418,34 @@ 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 \cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}} \dd This setting indicates the depth of section which should be -given a \q{leaf} file (a file with no sub-files). So if you set it -to 1, for example, then every chapter will be given its own HTML -file, plus a top-level contents file. If you set this to 2, then -each chapter \e{and} each \c{\\H} section will have a file, and the -chapter files will mostly just contain links to their sub-files. +given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if +you set it to 1, for example, then every chapter will be given its +own HTML file, plus a top-level \i{contents file}. If you set this +to 2, then each chapter \e{and} each \c{\\H} section will have a +file, and the chapter files will mostly just contain links to their +\i{sub-file}s. \lcont{ 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 -\c{Manual.html} instead of \c{Contents.html}. +\i\c{Manual.html} instead of \i\c{Contents.html}. + +This option is automatically set to zero if you provide a file name +parameter after the command-line option \i\c{--html} (see +\k{running-options}), because you have specified a single file name +and so Halibut assumes you want the whole document to be placed in +that file. } -\dt \cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}} -\dd This directive allows you to specify how deep the contents -section in a particular file should go. +\dd This directive allows you to specify how \I{depth of +contents}deep the contents section in a particular file should go. \lcont{ @@ -282,12 +470,12 @@ to \c{\\S} level, but not to go into any more detail than that. \# the level as a separate argument, like the text section config \# directives. Secondly, it shouldn't be limited in depth! -\dt \cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-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 \cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-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 @@ -298,64 +486,65 @@ generating it at all. \S{output-html-html} Including pieces of your own HTML The directives in this section allow you to supply pieces of -verbatim HTML code, which will be included in various parts of the -output files. +\I{HTML}\i{verbatim HTML} code, which will be included in various +parts of the output files. -\dt \cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}} \dd The text you provide in this directive is placed at the end of -the \cw{
} section of each output HTML file. So this is a good -place to put, for example, a link to a CSS stylesheet. +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 \cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}} \dd The text you provide in this directive is used in place of the -\cw{} tag in each output file. So if you wanted to define a -background colour, for example, you could write +\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\}\{\}}. -\dt \cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}} \dd The text you provide in this directive is placed at the -beginning of the \cw{} section of each output HTML file. So if -you intend your HTML files to be part of a web site with a standard -house style, and the style needs a header at the top of every page, -this is where you can add that header. +beginning 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{header} at the +top of every page, this is where you can add that header. -\dt \cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}} -\dd The text you provide in this directive is placed at the -end of the \cw{} section of each output HTML file. So if -you intend your HTML files to be part of a web site with a standard -house style, and the style needs a footer at the bottom of every page, -this is where you can add that footer. +\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. -\dt \cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}} \dd The text you provide in this directive is placed at the -beginning of the \cw{} section at the bottom of each output -HTML file. This might be a good place to put authors' contact -details, for example. +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 \cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}} -\dd The text you provide in this directive is placed at the -end of the \cw{} section at the bottom of each output -HTML file, after the version IDs (if present). +\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 \cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}} +\dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}} \dd The text you provide in this directive is included inside the -\cw{} tag containing the navigation links at the top of each page -(\q{Previous} / \q{Contents} / \q{Next}). So if you wanted the -navigation links to have a particular CSS style, you could write +\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 navigation-links paragraph would then begin with the tag \cw{