Previous | Contents | Index | Next
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 output format generates the document as a single plain text 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 following subsections.
\cfg{text-filename}{filename}
--text (see section 2.1).
This section describes the configuration directives which control the horizontal dimensions of the output text file: how much paragraphs are indented by and how long the lines are.
\cfg{text-width}{width}
\cfg{text-indent}; if you specify an indent of 8 and a width of 64, your maximum output line length will be 72.
\cfg{text-indent}{indent}
\cfg{text-indent-code}{indent}
\cfg{text-list-indent}{indent}
\cfg{text-listitem-indent}.
\cfg{text-listitem-indent}{indent}
\cfg{text-list-indent}.
\cfg{text-indent-preamble}{boolean}
true, the document preamble (i.e. any paragraphs appearing before the first chapter heading) will be indented to the level specified by \cfg{text-indent}. If this setting is false, the document preamble will not be indented at all from the left margin.
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:
left
leftplus
\cfg{text-indent}). The section number is placed to the left of that (so that it goes in the margin if there is room).
centre
Also, several of the directives below specify how a title should be underlined. The parameter to one of these directives should be either blank ({}) or a piece of text which will be repeated to produce the underline. So you might want to specify, for example, \text-title-underline{=} but \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 \text-chapter-underline{\u203e}{-}, and Halibut would use the Unicode ‘OVERLINE’ character where possible and fall back to the ASCII minus sign otherwise.
\cfg{text-title-align}{alignment}
left, leftplus or centre.
\cfg{text-title-underline}{underline-text}
\cfg{text-chapter-align}{alignment}
\cfg{text-chapter-underline}{underline-text}
\cfg{text-chapter-numeric}{boolean}
true, then chapter headings will not contain the word ‘Chapter’ (or whatever other word you have defined in its place - see section 3.3.5 and section 3.6); they will just contain the chapter number, followed by the chapter title. If you set this to false, chapter headings will be prefixed by ‘Chapter’ or equivalent.
\cfg{text-chapter-shownumber}{boolean}
false, then chapter headings will only contain the chapter title: they will not contain the word ‘Chapter’ (or whatever other word you have defined in its place), and neither will they contain the chapter number. If set to false, this overrides \cfg{text-chapter-numeric}.
\cfg{text-chapter-suffix}{text}
: ’, then the chapter title might look something like ‘Chapter 2: Doing Things’.
\cfg{text-section-align}{level}{alignment}
\H), 1 means second-level headings (\S), 2 means the level below that (\S2), and so on. The alignment parameter is treated just like the other alignment directives listed above.
\cfg{text-section-underline}{level}{underline-text}
\cfg{text-section-numeric}{level}{boolean}
false), or should be numeric only (if true).
\cfg{text-section-shownumber}{level}{boolean}
false, then section headings at the specified level will only contain the section title: they will not contain the word ‘Section’ (or whatever other word you have defined in its place), and neither will they contain the section number. If set to false, this overrides \cfg{text-section-numeric}.
\cfg{text-section-suffix}{level}{text}
\cfg{text-charset}{character set name}
The character set names are the same as for \cfg{input-charset} (see section 3.6). However, unlike \cfg{input-charset}, this directive affects the entire output; it's not possible to switch encodings halfway through.
\cfg{text-bullet}{text}[{text...}]
\cfg{text-bullet}{-}), or more than one (\cfg{text-bullet}{(*)}).
Like \cfg{quotes} (see section 3.6), 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 \cfg{text-bullet}{\u2022}{\u00b7}{*}, in which case Halibut would use the Unicode ‘BULLET’ character where possible, fall back to the ISO-8859-1 ‘MIDDLE DOT’ if that wasn't available, and resort to the ASCII asterisk if all else failed.
\cfg{text-rule}{text}[{text...}]
\rule; see section 3.3.3). 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 ‘-=’ to get a rule that looks like -=-=-=.
Like \cfg{text-bullet}, you can specify multiple fallback options in this command.
\cfg{text-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes}. It has the same syntax (see section 3.6).
In this backend, these quotes will also be used to mark text enclosed in the \c command (see section 3.2.2).
\cfg{text-emphasis}{start-emph}{end-emph}[{start-emph}{end-emph...}]
\e command; see section 3.2.1).
\cfg{text-strong}{start-strong}{end-strong}[{start-strong}{end-strong...}]
\s command; see section 3.2.1).
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 \cfg{text-quotes}, you can specify multiple pairs of fallback options in this command, and Halibut will always use a matching pair.
\cfg{text-list-suffix}{text}
\cfg{text-list-suffix}{)}.
\cfg{text-versionid}{boolean}
true, version ID paragraphs (defined using the \versionid command - see section 3.3.6) will be included at the bottom of the text file. If it is set to false, they will be omitted completely.
The default settings for Halibut's plain text output format are:
\cfg{text-filename}{output.txt}
\cfg{text-width}{68}
\cfg{text-indent}{7}
\cfg{text-indent-code}{2}
\cfg{text-list-indent}{1}
\cfg{text-listitem-indent}{3}
\cfg{text-indent-preamble}{false}
\cfg{text-title-align}{centre}
\cfg{text-title-underline}{\u2550}{=}
\cfg{text-chapter-align}{left}
\cfg{text-chapter-underline}{\u203e}{-}
\cfg{text-chapter-numeric}{false}
\cfg{text-chapter-shownumber}{true}
\cfg{text-chapter-suffix}{: }
\cfg{text-section-align}{0}{leftplus}
\cfg{text-section-underline}{0}{}
\cfg{text-section-numeric}{0}{true}
\cfg{text-section-shownumber}{0}{true}
\cfg{text-section-suffix}{0}{ }
\cfg{text-section-align}{1}{leftplus}
\cfg{text-section-underline}{1}{}
\cfg{text-section-numeric}{1}{true}
\cfg{text-section-shownumber}{1}{true}
\cfg{text-section-suffix}{1}{ }
... and so on for all section levels below this ...
\cfg{text-charset}{ASCII}
\cfg{text-bullet}{\u2022}{-}
\cfg{text-rule}{\u2500}{-}
\cfg{text-quotes}{\u2018}{\u2019}{`}{'}
\cfg{text-emphasis}{_}{_}
\cfg{text-list-suffix}{.}
\cfg{text-versionid}{true}
This output format generates an HTML version of the document. By default, this will be in multiple files, starting with 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.
Configuration directives with an xhtml- prefix are synonyms for those with an html- prefix.
\cfg{html-contents-filename}{filename}
index.html (although this is not the default, for historical reasons).
\cfg{html-index-filename}{filename}
\cfg{html-template-filename}{template}
%%.)
The formatting commands used in this template are:
%N
\C{fish} Catching Fish’, this formatting command would expand to ‘CatchingFish’.
%n
Chapter1’; in section A.4.3 it would expand to ‘SectionA.4.3’, and so on. If the section has no number (an unnumbered chapter created using \U), this directive falls back to doing the same thing as %N.
%b
C1’; in section A.4.3 it would expand to ‘SA.4.3’, and so on. If the section has no number (an unnumbered chapter created using \U), this directive falls back to doing the same thing as %N.
%k
\C{fish} Catching Fish’, this formatting command would expand to ‘fish’. If the section has no keyword (an unnumbered chapter created using \U), this directive falls back to doing the same thing as %N.
These formatting directives can also be used in the \cfg{html-template-fragment} configuration directive (see section 4.2.7).
\cfg{html-single-filename}{filename}
\cfg{html-leaf-level}{0}) to produce a single self-contained file. Both this directive and \cfg{html-leaf-level}{0} are implicitly generated if you provide a file name parameter after the command-line option --html (see section 2.1).
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.
\cfg{html-leaf-level}{depth}
\H section will have a file, and the chapter files will mostly just contain links to their sub-files.
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 Manual.html instead of Contents.html by default.
This option is automatically set to zero if you provide a file name parameter after the command-line option --html (see section 2.1), because you have specified a single file name and so Halibut assumes you want the whole document to be placed in that file.
You can also specify the special name infinity (or infinite or inf) if you want to ensure that every section and subsection ends up in a separate file no matter how deep you go.
\cfg{html-contents-depth}{level}{depth}
The level parameter indicates which level of contents section you are dealing with. 0 denotes the main contents section in the topmost file Contents.html; 1 denotes a contents section in a chapter file; 2 is a contents section in a file containing a \H heading, and so on.
The depth parameter indicates the maximum depth of heading which will be shown in this contents section. Again, 1 denotes a chapter, 2 is a \H heading, 3 is a \S heading, and so on.
So, for example: \cfg{html-contents-depth}{1}{3} instructs Halibut to put contents links in chapter files for all sections down to \S level, but not to go into any more detail than that.
For backwards compatibility, the alternative syntax \cfg{html-contents-depth-level}{depth} is also supported.
\cfg{html-leaf-contains-contents}{boolean}
true, then each leaf file will contain its own contents section which summarises the text within it.
\cfg{html-leaf-smallest-contents}{number}
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.
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.
\cfg{html-head-end}{HTML text}
<HEAD> section of each output HTML file. So this is a good place to put, for example, a link to a CSS stylesheet.
\cfg{html-local-head}{HTML text}
The text you provide in this directive is placed at the end of the <HEAD> 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 MacOS on-line help, which is mostly normal HTML but which requires a special <META NAME="AppleTitle"> 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:
\cfg{html-local-head}{<meta name="AppleTitle"
content="MyApp Help">}
\cfg{html-body-tag}{HTML text}
<BODY> tag in each output file. So if you wanted to define a background colour, for example, you could write \cfg{html-body-tag}{<body bg="#123456">}.
\cfg{html-body-start}{HTML text}
<BODY> 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.
\cfg{html-body-end}{HTML text}
<BODY> 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 house style, and the style needs a footer at the bottom of every page, this is where you can add that footer.
\cfg{html-address-start}{HTML text}
<ADDRESS> section at the bottom of each output HTML file. This might be a good place to put authors' contact details, for example.
\cfg{html-address-end}{HTML text}
<ADDRESS> section at the bottom of each output HTML file, after the version IDs (if present).
\cfg{html-navigation-attributes}{HTML attributes}
<P> tag containing the navigation links at the top of each page (‘Previous’ / ‘Contents’ / ‘Next’). So if you wanted the navigation links to have a particular CSS style, you could write \cfg{html-navigation-attributes}{class="foo"}, and the navigation-links paragraph would then begin with the tag <p class="foo">.
\cfg{html-chapter-numeric}{boolean}
true, then chapter headings will not contain the word ‘Chapter’ (or whatever other word you have defined in its place - see section 3.3.5 and section 3.6); they will just contain the chapter number, followed by the chapter title. If you set this to false, chapter headings will be prefixed by ‘Chapter’ or equivalent.
\cfg{html-chapter-shownumber}{boolean}
false, then chapter headings will only contain the chapter title: they will not contain the word ‘Chapter’ (or whatever other word you have defined in its place), and neither will they contain the chapter number. If set to false, this overrides \cfg{html-chapter-numeric}.
\cfg{html-chapter-suffix}{text}
: ’, then the chapter title might look something like ‘Chapter 2: Doing Things’.
\cfg{html-section-numeric}{level}{boolean}
false), or should be numeric only (if true). The level parameter specifies which level of section headings you want to affect: 0 means first-level headings (\H), 1 means second-level headings (\S), 2 means the level below that (\S2), and so on.
\cfg{html-section-shownumber}{level}{boolean}
false, then section headings at the specified level will only contain the section title: they will not contain the word ‘Section’ (or whatever other word you have defined in its place), and neither will they contain the section number. If set to false, this overrides \cfg{html-section-numeric}.
\cfg{html-section-suffix}{level}{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.
\cfg{html-preamble-text}{text}
\cfg{html-contents-text}{text}
\cfg{html-index-text}{text}
(html-contents-text and html-index-text override the cross-format configuration keywords contents and index (see section 3.6, if both appear. They are legacy keywords preserved for backwards compatibility; you should generally use contents and index.)
\cfg{html-title-separator}{text}
<TITLE> tag, this text is used to separate them.
\cfg{html-index-main-separator}{text}
\cfg{html-index-multiple-separator}{text}
\cfg{html-pre-versionid}{text}
\cfg{html-post-versionid}{text}
\cfg{html-nav-prev-text}{text}
\cfg{html-nav-next-text}{text}
\cfg{html-nav-up-text}{text}
\cfg{html-nav-separator}{text}
Unlike the other backends, HTML does not have a single \cfg{html-charset} directive, as there are several levels of character encoding to consider.
The character set names are the same as for \cfg{input-charset} (see section 3.6). However, unlike \cfg{input-charset}, these directives affect the entire output; it's not possible to switch encodings halfway through.
\cfg{html-output-charset}{character set name}
\cfg{html-restrict-charset}{character set name}
\cfg{html-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).
\cfg{html-version}{version}
html3.2
html4
iso-html
xhtml1.0transitional
xhtml1.0strict
\cfg{html-template-fragment}{template}[{template}{...}]
\cfg{html-template-filename} (see section 4.2.1), to be used for the anchor names (<A NAME="...">) used to allow URLs to refer to specific sections within a particular HTML file. So if you set this to ‘%k’, for example, then each individual section in your document will be addressable by means of a URL ending in a # followed by your internal section keyword.
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.
\cfg{html-versionid}{boolean}
true, version ID paragraphs (defined using the \versionid command - see section 3.3.6) will be included visibly in the <ADDRESS> section at the bottom of each HTML file. If it is set to false, they will only be included as HTML comments.
\cfg{html-rellinks}{boolean}
true, machine-readable relational links will be emitted in each HTML file (<LINK REL="next"> and so on within the <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).
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.
\cfg{html-suppress-navlinks}{boolean}
true, the usual navigation links within the body of each HTML file (near the top of the rendered page) will be suppressed.
\cfg{html-suppress-address}{boolean}
true, the <ADDRESS> section at the bottom of each HTML file will be omitted completely. (This will therefore also cause version IDs not to be included visibly.)
\cfg{html-author}{text}
<META name="author"> tag in the output HTML files, so that browsers which support this can automatically identify the author of the document.
\cfg{html-description}{text}
<META name="description"> tag in the output HTML files, so that browsers which support this can easily pick out a brief description of the document.
The default settings for Halibut's HTML output format are:
\cfg{html-contents-filename}{Contents.html}
\cfg{html-index-filename}{IndexPage.html}
\cfg{html-template-filename}{%n.html}
\cfg{html-single-filename}{Manual.html}
\cfg{html-leaf-level}{2}
\cfg{html-leaf-contains-contents}{false}
\cfg{html-leaf-smallest-contents}{4}
\cfg{html-contents-depth}{0}{2}
\cfg{html-contents-depth}{1}{3}
... and so on for all section levels below this ...
\cfg{html-head-end}{}
\cfg{html-body-tag}{<body>}
\cfg{html-body-start}{}
\cfg{html-body-end}{}
\cfg{html-address-start}{}
\cfg{html-address-end}{}
\cfg{html-navigation-attributes}{}
\cfg{html-chapter-numeric}{false}
\cfg{html-chapter-shownumber}{true}
\cfg{html-chapter-suffix}{: }
\cfg{html-section-numeric}{0}{true}
\cfg{html-section-shownumber}{0}{true}
\cfg{html-section-suffix}{0}{ }
\cfg{html-section-numeric}{1}{true}
\cfg{html-section-shownumber}{1}{true}
\cfg{html-section-suffix}{1}{ }
... and so on for all section levels below this ...
\cfg{html-preamble-text}{Preamble}
\cfg{html-contents-text}{Contents}
\cfg{html-index-text}{Index}
\cfg{html-title-separator}{ - }
\cfg{html-index-main-separator}{: }
\cfg{html-index-multiple-separator}{, }
\cfg{html-pre-versionid}{[}
\cfg{html-post-versionid}{]}
\cfg{html-nav-prev-text}{Previous}
\cfg{html-nav-next-text}{Next}
\cfg{html-nav-up-text}{Up}
\cfg{html-nav-separator}{ | }
\cfg{html-output-charset}{ASCII}
\cfg{html-restrict-charset}{UTF-8}
\cfg{html-quotes}{\u2018}{\u2019}{"}{"}
\cfg{html-version}{html4}
\cfg{html-template-fragment}{%b}
\cfg{html-versionid}{true}
\cfg{html-rellinks}{true}
\cfg{html-suppress-navlinks{false}
\cfg{html-suppress-address}{false}
\cfg{html-author}{}
\cfg{html-description}{}
This output format generates a .chm file suitable for use with the Windows HTML Help system.
Older versions of Halibut could only generate HTML Help by writing out a set of source files acceptable to the MS help compiler. Nowadays Halibut can generate CHM directly, so that's no longer necessary. However, the legacy method is still available if you need it; see section 4.3.6 for details.
\cfg{chm-filename}{filename}
--chm (see section 2.1).
As the name suggests, an HTML Help file is mostly a compressed container for HTML files. So the CHM back end shares a great deal of its code with the HTML back end, and as a result, it supports the same range of format configuration options.
(One exception to this general rule is that the configuration options relating to generating HTML Help compiler input are not supported in CHM mode, because they wouldn't make any sense! The html-mshtmlhelp-* options described in section 4.3.6 have no analogue starting chm-.)
However, because HTML and CHM are used in different ways, you may need to configure the two back ends differently. So in CHM mode, Halibut supports all the same configuration directives described in section 4.2, but with their names changed so that they begin with ‘chm-’ in place of ‘html-’. This lets you maintain two sets of configuration independently; for example, you could specify \cfg{html-chapter-numeric}{true} and \cfg{chm-chapter-numeric}{false} in the same source file, and then when you ran Halibut with both the --html and --chm options, it would produce purely numeric chapter titles in the HTML output but not in the CHM file.
If you do decide to apply a piece of configuration across both these back ends, you can prefix it with ‘htmlall-’ instead of ‘html-’ or ‘chm-’. For example, \cfg{htmlall-chapter-numeric}{true} will enable purely numeric chapter titles in both the HTML and CHM output.
CHM files are mostly a container for HTML, and the HTML files inside them are allowed to cross-refer to all the usual other kinds of file that HTML might refer to, such as images, stylesheets and even Javascript. If you want to make use of this capability, you need to tell Halibut what extra files it needs to incorporate into the CHM container.
\cfg{chm-extra-file}{filename}
\cfg{chm-extra-file}{filename}{name inside CHM}
In the first form of the directive, the file will be given the same name within the CHM's internal namespace (i.e. for the purposes of linking to it from HTML files) as Halibut used to load it from disk. If you need to include the file with a different internal name, you can use the second form of the directive, which separately specifies the name under which Halibut should look for the input file and the name it should give it inside the CHM.
You can specify this directive multiple times, to include more than one file.
As well as ordinary HTML, there are also two special files inside a CHM, containing the table of contents and the index. Halibut generates these automatically, and you normally don't have to worry about them. However, it is just possible (though very unlikely!) that you might find they conflict with the name of some file you wanted to include in the CHM yourself, and hence, Halibut provides configuration options to change them if you need to.
\cfg{chm-contents-name}{filename}
\cfg{chm-index-name}{filename}
The default settings for Halibut's CHM output format are mostly the same as for the standard HTML output. However, a few defaults are changed to be more in line with the way CHM wants to do things.
\cfg{chm-filename}{output.chm}
\cfg{chm-contents-name}{contents.hhc}
\cfg{chm-index-name}{index.hhk}
\cfg{chm-leaf-level}{infinite}
\cfg{chm-suppress-navlinks{true}
\cfg{chm-suppress-address}{true}
Before Halibut gained the ability to write out CHM files directly, it used a more cumbersome system in which you could run it in HTML mode and enable some extra options that would write out supporting files needed by the official Windows HTML Help compiler, so that you could still generate a CHM file from your Halibut source in multiple build steps.
This legacy system for HTML Help generation is still supported, partly to avoid backwards-compatibility breakage for anyone already using it, and also because it permits more flexibility in the resulting CHM files: Halibut's own CHM file generation makes some fixed decisions about window layout and styling, whereas if you use the official help compiler you can start from Halibut's default project file and make whatever manual changes you like to that sort of thing.
To enable the generation of MS HTML Help auxiliary files, use the following configuration directives:
\cfg{html-mshtmlhelp-project}{filename}
.hhp (although Halibut will not enforce this). If you use this option, you must also use the html-mshtmlhelp-chm option to specify the desired name of the compiled help file.
\cfg{html-mshtmlhelp-chm}{filename}
.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 html-mshtmlhelp-project option to request a help project file in the first place.
\cfg{html-mshtmlhelp-contents}{filename}
.hhc (although Halibut will not enforce this). This option will be ignored if you have not also specified a help project file.
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.
\cfg{html-mshtmlhelp-index}{filename}
.hhk (although Halibut will not enforce this). This option will be ignored if you have not also specified a help project file.
Specifying this option suppresses the generation of an HTML-based index file (see \cfg{html-index-filename} in section 4.2.1).
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 (HHC.EXE), or load into the MS HTML Help Workshop (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. If you use Halibut's direct CHM output, this is done for you automatically (see section 4.3.5); but if you're using the HTML output mode then I recommend the following changes.
\cfg{html-leaf-level}{infinite}, because HTML Help works best with lots of small files (‘topics’) rather than a few large ones. In particular, the contents and index mechanisms can only reference files, not subsections within files.
\cfg{html-suppress-navlinks}{true}, because HTML Help has its own navigation facilities and it looks a bit strange to duplicate them.
\cfg{html-suppress-address}{true}, because the <ADDRESS> section makes less sense in a help file than it does on a web page.
This output format generates data that can be used by the legacy Windows Help program WINHLP32.EXE. There are two actual files generated, one ending in .hlp and the other ending in .cnt.
This legacy Windows Help format was discontinued in 2006 in favour of HTML Help, which Halibut can also generate. You probably want to use that instead for any new project. See section 4.3 for more information on this.
Currently, the Windows Help output is hardcoded to be in the ‘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:
\cfg{winhelp-filename}{filename}
--winhelp (see section 2.1).
Your output file name should end with .hlp; if it doesn't, Halibut will append it. Halibut will also generate a contents file (ending in .cnt) alongside the file name you specify.
\cfg{winhelp-bullet}{text}[{text}...]
\cfg{text-bullet} directive (see section 4.1.4).
\cfg{winhelp-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).
\cfg{winhelp-contents-titlepage}{title}
\cfg{winhelp-section-suffix}{text}
\cfg{winhelp-list-suffix}{text}
\cfg{text-list-suffix} (see section 4.1.4).
\cfg{winhelp-topic}{topic-name}
WINHELP.EXE to jump straight to a particular section. So you can use this for context-sensitive help.
For example, if you used this directive in a particular section:
\cfg{winhelp-topic}{savingfiles}
then a Windows application could invoke Windows Help to jump to that particular section in the help file like this:
WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
(DWORD)"JI(`',`savingfiles')");
You can use this configuration directive many times, in many different subsections of your document, in order to define a lot of different help contexts which you can use in this way.
The default settings for the Windows Help output format are:
\cfg{winhelp-filename}{output.hlp}
\cfg{winhelp-bullet}{\u2022}{-}
\cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
\cfg{winhelp-contents-titlepage}{Title page}
\cfg{winhelp-section-suffix}{: }
\cfg{winhelp-list-suffix}{.}
and no \cfg{winhelp-topic} directives anywhere.
man pages
This output format generates a Unix man page. That is to say, it generates nroff input designed to work with the -mandoc macro package.
The available configuration options for this format are as follows:
\cfg{man-filename}{filename}
--man (see section 2.1).
\cfg{man-identity}{text}{text...}
.TH directive that appears at the top of a man page. It expects to be followed by some number of brace pairs containing text, which will be used in the headers and footers of the formatted output.
A traditional order for the arguments appears to be:
man page was written.
man page.
For example, a typical man page might contain
\cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
Bloggs}
\cfg{man-headnumbers}{boolean}
true, then section headings in the man page will have their section numbers displayed as usual. If set to false, the section numbers will be omitted. (man pages traditionally have section names such as ‘SYNOPSIS’, ‘OPTIONS’ and ‘BUGS’, and do not typically number them, so false is the setting which conforms most closely to normal man style.)
\cfg{man-mindepth}{depth}
The point of this is so that you can use the same Halibut input file to generate a quick-reference man page for a program, and to include that man page as an appendix in your program's full manual. If you are to include the man page as an appendix, then the internal headings within the page will probably need to be at \H or \S level; therefore, when you format that input file on its own to create the man page itself, you will need to have defined a \C and possibly a \H heading beforehand, which you don't want to see displayed.
Here's an example. You might have a file appendix.but, which simply says
\A{manpages} \cw{man} pages for the Foo tool suite
\cfg{man-mindepth}{2}
Then you have a file make-foo.but, and probably others like it as well, each of which looks something like this:
\cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
Bloggs}
\H{man-foo} \cw{man} page for \c{make-foo}
\S{man-foo-name} NAME
\c{make-foo} - create Foo files for the Foo tool suite
\S{man-foo-synopsis} SYNOPSIS
... and so on ...
So when you're generating your main manual, you can include appendix.but followed by make-foo.but and any other man pages you have, and your man pages will be formatted neatly as part of an appendix. Then, in a separate run of Halibut, you can just do
halibut appendix.but make-foo.but
and this will generate a man page output.1, in which the headings ‘man pages for the Foo tool suite’ and ‘man page for make-foo’ will not be displayed because of the man-mindepth directive. So the first visible heading in the output man page will be ‘NAME’, exactly as a user would expect.
\cfg{man-charset}{character set}
\cfg{text-charset} (see section 4.1.4).
\cfg{man-bullet}{text}[{text}...]
\cfg{text-bullet} directive (see section 4.1.4).
\cfg{man-rule}{text}[{text...}]
\rule; see section 3.3.3) when the manual page is rendered into text. It should only be one character long, but otherwise it works like the \cfg{text-rule} directive (see section 4.1.4).
\cfg{man-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).
The default settings for the man page output format are:
\cfg{man-filename}{output.1}
\cfg{man-identity}{}
\cfg{man-headnumbers}{false}
\cfg{man-mindepth}{0}
\cfg{man-charset}{ASCII}
\cfg{man-bullet}{\u2022}{o}
\cfg{man-rule}{\u2500}{-}
\cfg{man-quotes}{\u2018}{\u2019}{"}{"}
This output format generates files which can be used with the GNU Info program.
There are typically multiple output files: a primary file whose name usually ends in .info, and one or more subsidiary files whose names have numbers on the end, so that they end in .info-1, .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:
\cfg{info-filename}{filename}
--info (see section 2.1).
The suffixes -1, -2, -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 renamed after creation and remain useful.
\cfg{info-max-file-size}{bytes}
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).
\cfg{info-width}{width}
\cfg{text-width} directive (see section 4.1.2).
\cfg{info-indent-code}{indent}
\cfg{text-indent-code} directive (see section 4.1.2).
\cfg{info-index-width}{width}
\cfg{info-list-indent}{indent}
\cfg{text-list-indent} directive (see section 4.1.2).
\cfg{info-listitem-indent}{indent}
\cfg{text-listitem-indent} directive (see section 4.1.2).
\cfg{info-section-suffix}{text}
: ’, then a typical section title might look something like ‘Section 3.1: Something Like This’.
\cfg{info-title-underline}{text}[{text}...]
\cfg{text-title-underline} directive (see section 4.1.3). You can specify more than one option, and Halibut will choose the first one supported by the character set.
\cfg{info-chapter-underline}{text}[{text}...]
\cfg{info-section-underline}{level}{text}[{text}...]
\H), 1 means second-level headings (\S), 2 means the level below that (\S2), and so on.
\cfg{info-charset}{character set}
\cfg{text-charset} (see section 4.1.4).
\cfg{info-bullet}{text}[{text}...]
\cfg{text-bullet} directive (see section 4.1.4).
\cfg{info-rule}{text}[{text}...]
\cfg{text-rule} directive (see section 4.1.4).
\cfg{info-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).
\cfg{info-emphasis}{start-emph}{end-emph}[{start-emph}{end-emph...}]
\cfg{text-emphasis} directive (see section 4.1.4).
\cfg{info-strong}{start-strong}{end-strong}[{start-strong}{end-strong...}]
\cfg{text-emphasis} directive (see section 4.1.4).
\cfg{info-list-suffix}{text}
\cfg{text-list-suffix} directive (see section 4.1.5).
\cfg{info-dir-entry}{section}{short name}{long name}[{keyword}]
INFO-DIR-ENTRY section and places it in the header of the Info file. This mechanism is used to automatically generate the dir file at the root of a Unix system's Info collection.
The parameters to this directive are:
dir file in which you want your document referenced. For example, ‘Development’, or ‘Games’, or ‘Miscellaneous’.
For example, in a document describing many game programs, the configuration directive
\cfg{info-dir-entry}{Games}{Chess}{Electronic chess
game}{chess}
might produce text in the dir file looking something like this:
Games
* Chess: (mygames)Chapter 3. Electronic chess game
if the output file were called mygames.info and the keyword chess had been used to define Chapter 3 of the document.
The default settings for the Info output format are:
\cfg{info-filename}{output.info}
\cfg{info-max-file-size}{65536}
\cfg{info-width}{70}
\cfg{info-indent-code}{2}
\cfg{info-index-width}{40}
\cfg{info-list-indent}{1}
\cfg{info-listitem-indent}{3}
\cfg{info-section-suffix}{: }
\cfg{info-title-underline}{*}
\cfg{info-chapter-underline}{=}
\cfg{info-section-underline}{0}{-}
\cfg{info-section-underline}{1}{.}
\cfg{info-section-underline}{2}{.}
... and so on for all section levels below this ...
\cfg{info-charset}{ASCII}
\cfg{info-bullet}{\u2022}{-}
\cfg{info-rule}{\u2500}{-}
\cfg{info-quotes}{\u2018}{\u2019}{`}{'}
\cfg{info-emphasis}{_}{_}
\cfg{info-strong}{*}{*}
\cfg{info-list-suffix}{.}
and no \cfg{info-dir-entry} directives.
These output formats (currently PDF and PostScript) generate printable manuals. As such, they share a number of configuration directives.
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:
\cfg{pdf-filename}{filename}
--pdf (see section 2.1).
The default settings for the PDF output format are:
\cfg{pdf-filename}{output.pdf}
This output format generates a printable manual in PostScript format. This should look exactly identical to the PDF output (see section 4.7.2), and uses pdfmark to arrange that if converted to PDF it will contain the same interactive features.
There is one configuration option specific to PostScript:
\cfg{ps-filename}{filename}
--ps (see section 2.1).
The default settings for the PostScript output format are:
\cfg{ps-filename}{output.ps}
All measurements are in PostScript points (72 points to the inch).
\cfg{paper-page-width}{points}
\cfg{paper-page-height}{points}
\cfg{paper-left-margin}{points}
\cfg{paper-top-margin}{points}
\cfg{paper-right-margin}{points}
\cfg{paper-bottom-margin}{points}
\cfg{paper-base-leading}{points}
\cfg{paper-base-para-spacing}{points}
paper-base-leading.)
\cfg{paper-list-indent}{points}
\cfg{text-list-indent} (see section 4.1.2).
\cfg{paper-listitem-indent}{points}
\cfg{paper-list-indent}.
\cfg{paper-quote-indent}{points}
\quote (see section 3.3.4) and code quotes with \c (see section 3.2.2).
\cfg{paper-chapter-top-space}{points}
\cfg{paper-chapter-underline-thickness}{points}
\cfg{paper-chapter-underline-depth}{points}
\cfg{paper-sect-num-left-space}{points}
\cfg{paper-contents-indent-step}{points}
\cfg{paper-contents-margin}{points}
\cfg{paper-leader-separation}{points}
\cfg{paper-footer-distance}{points}
\cfg{paper-index-columns}{columns}
\cfg{paper-index-gutter}{points}
\cfg{paper-index-minsep}{points}
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 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 Type 1 font Halibut needs both the font file itself, in either hexadecimal (PFA) or IBM PC (PFB) format, and an Adobe Font Metrics (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 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 Unicode mapping table and a PostScript name.
Fonts are specified using their PostScript names. Running Halibut with the --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.
Font sizes are specified in PostScript points (72 to the inch).
\cfg{paper-title-fonts}{normal-font}[{emph-font}[{code-font}]]
\cfg{paper-title-font-size}{points}
\cfg{paper-chapter-fonts}{normal-font}[{emph-font}[{code-font}]]
\cfg{paper-chapter-font-size}{points}
\cfg{paper-section-fonts}{level}{normal-font}[{emph-font}[{code-font}]]
\cfg{paper-section-font-size}{level}{points}
\cfg{paper-base-fonts}{normal-font}[{emph-font}[{code-font}]]
\cfg{paper-base-font-size}{points}
\cfg{paper-code-fonts}{bold-font}[{italic-font}[{normal-font}]]
\cfg{paper-code-font-size}{points}
\cfg{paper-pagenum-font-size}{points}
\cfg{paper-rule-thickness}{points}
\rule command (see section 3.3.3). (Note that no extra space is reserved for thicker rules.)
\cfg{paper-bullet}{text}[{text}...]
\cfg{text-bullet} directive (see section 4.1.4).
\cfg{paper-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
\cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).
The default page size corresponds to 210 × 297 mm, i.e., A4 paper.
\cfg{paper-page-width}{595}
\cfg{paper-page-height}{842}
\cfg{paper-left-margin}{72}
\cfg{paper-top-margin}{72}
\cfg{paper-right-margin}{72}
\cfg{paper-bottom-margin}{108}
\cfg{paper-base-leading}{1}
\cfg{paper-base-para-spacing}{10}
\cfg{paper-list-indent}{6}
\cfg{paper-listitem-indent}{18}
\cfg{paper-quote-indent}{18}
\cfg{paper-chapter-top-space}{72}
\cfg{paper-chapter-underline-thickness}{3}
\cfg{paper-chapter-underline-depth}{14}
\cfg{paper-sect-num-left-space}{12}
\cfg{paper-contents-indent-step}{24}
\cfg{paper-contents-margin}{84}
\cfg{paper-leader-separation}{12}
\cfg{paper-footer-distance}{32}
\cfg{paper-index-columns}{2}
\cfg{paper-index-gutter}{36}
\cfg{paper-index-minsep}{18}
\cfg{paper-base-fonts}{Times-Roman}{Times-Italic}{Courier}
\cfg{paper-base-font-size}{12}
\cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier}
\cfg{paper-code-font-size}{12}
\cfg{paper-title-fonts}{Helvetica-Bold}
{Helvetica-BoldOblique}{Courier-Bold}
\cfg{paper-title-font-size}{24}
\cfg{paper-chapter-fonts}{Helvetica-Bold}
{Helvetica-BoldOblique}{Courier-Bold}
\cfg{paper-chapter-font-size}{20}
\cfg{paper-section-fonts}{0}{Helvetica-Bold}
{Helvetica-BoldOblique}{Courier-Bold}
\cfg{paper-section-font-size}{0}{16}
\cfg{paper-section-fonts}{1}{Helvetica-Bold}
{Helvetica-BoldOblique}{Courier-Bold}
\cfg{paper-section-font-size}{1}{14}
\cfg{paper-section-fonts}{2}{Helvetica-Bold}
{Helvetica-BoldOblique}{Courier-Bold}
\cfg{paper-section-font-size}{2}{13}
... and so on for all section levels below this ...
\cfg{paper-pagenum-font-size}{12}
\cfg{paper-rule-thickness}{1}
\cfg{paper-bullet}{\u2022}{-}
\cfg{paper-quotes}{\u2018}{\u2019}{'}{'}