\C{output} Halibut output formats 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 \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. 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 \i{horizontal dimensions} of the output text file: how much paragraphs are indented by and how long the lines are. \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}} \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 \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}} \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 \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 \I{code paragraphs, indentation} code paragraphs. \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 \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 \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 \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}} \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} \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 \i{alignment} of a heading. These alignment options have three possible values: \dt \i\c{left} \dd Align the heading to the very left of the text file (column zero). \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 \i\c{centre} \dd Centre the heading. 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 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{\}} \dd Specifies how the overall document title should be underlined. \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 \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 \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 defined in its place - see \k{input-sections} and \k{input-config}); 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-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 \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 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. 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{\}} \dd Specifies how to underline section headings at a particular level. \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 \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-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{ You can specify multiple possible options (each in their own pair of braces) after this command, and Halibut will choose the first one which the output character set supports. (This is to allow you to configure the bullet character once, generate output in several different character sets, and have Halibut constantly adapt to make the best use of the current encoding.) 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 the quote characters which should be used in response to the \c{\\q} command (see \k{input-quotes}). These quotes will also be used to mark text enclosed in the \c{\\c} command (see \k{input-code}). \lcont{ You should separately specify the open and close quote characters, each of which can be more than one character if you want. Also, like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback options in this command (a pair of open and close quotes, then another pair, then another if you like); Halibut will always use a matching pair. For example, you might write \c \cfg{text-quotes}{\u201c}{\u201d}{"}{"} and Halibut would use the Unicode matched double quote characters if possible, and fall back to ASCII double quotes otherwise. If the output character set were to contain U+201C but not U+201D, then Halibut would fall back to using the ASCII double quote character as \e{both} open and close quotes. (No known character set is that silly; I mention it only as an example.) } \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. \# FIXME: text-indent-* should be consistently named. \S{output-text-defaults} Default settings 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} \c \cfg{text-list-indent}{1} \c \cfg{text-listitem-indent}{3} \c \cfg{text-indent-preamble}{false} \c \c \cfg{text-title-align}{centre} \c \cfg{text-title-underline}{\u2550}{=} \c \c \cfg{text-chapter-align}{left} \c \cfg{text-chapter-underline}{\u203e}{-} \c \cfg{text-chapter-numeric}{false} \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-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-suffix}{1}{ } \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-list-suffix}{.} \c \cfg{text-versionid}{true} \H{output-html} HTML 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. 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\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 files. Each file typically contains a single chapter or section and everything below it, unless subsections of that chapter are themselves split off into further files. Most files also contain a contents section, giving hyperlinks to the 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{\}} \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 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 \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 \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 \I{depth of contents}deep the contents section in a particular file should go. \lcont{ 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). 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 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. } \# 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{\}} \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{\}} \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 bothering). This directive configures the minimum number of entries required in a leaf contents section to make Halibut bother 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 \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{\}} \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{\}} \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\}\{\}}. \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 \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 \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 \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 \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 \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{\}} \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{\}} \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 navigation-links paragraph would then begin with the tag \cw{