Previous | Contents | Index | Next

Chapter 4: 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.

4.1 Plain text

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.

4.1.1 Output file name

\cfg{text-filename}{filename}
Sets the 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 --text (see section 2.1).

4.1.2 Indentation and line width

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}
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 section 4.1.3). This width does not include the left indentation set by \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}
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 section 4.1.3).
\cfg{text-indent-code}{indent}
Specifies how many extra characters of indentation (on top of the normal left indent) should be given to code paragraphs.
\cfg{text-list-indent}{indent}
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 plus the value configured by \cfg{text-listitem-indent}.
\cfg{text-listitem-indent}{indent}
Specifies how many extra spaces should be used to indent the body of a list item, over and above the number configured in \cfg{text-list-indent}.
\cfg{text-indent-preamble}{boolean}
When this is set to 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.

4.1.3 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:

left
Align the heading to the very left of the text file (column zero).
leftplus
Align the section title to the left of the main display region (in other words, indented to the level specified by \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
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 ({}) 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}
Specifies the alignment of the overall document title: left, leftplus or centre.
\cfg{text-title-underline}{underline-text}
Specifies how the overall document title should be underlined.
\cfg{text-chapter-align}{alignment}
Specifies the alignment of chapter and appendix headings.
\cfg{text-chapter-underline}{underline-text}
Specifies how chapter and appendix headings should be underlined.
\cfg{text-chapter-numeric}{boolean}
If this is set to 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-suffix}{text}
This specifies the suffix text to be appended to the chapter number, before displaying the chapter title. For example, if you set this to ‘’, then the chapter title might look something like ‘Chapter 2: Doing Things’.
\cfg{text-section-align}{level}{alignment}
Specifies the alignment of section headings at a particular level. 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. The alignment parameter is treated just like the other alignment directives listed above.
\cfg{text-section-underline}{level}{underline-text}
Specifies how to underline section headings at a particular level.
\cfg{text-section-numeric}{level}{boolean}
Specifies whether section headings at a particular level should contain the word ‘Section’ or equivalent (if false), or should be numeric only (if true).
\cfg{text-section-suffix}{level}{text}
Specifies the suffix text to be appended to section numbers at a particular level, before displaying the section title.

4.1.4 Configuring the characters used

\cfg{text-charset}{character set name}
This tells Halibut what 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 fallback text (if any) will be used instead.

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...}]
This specifies the text which should be used as the bullet in bulletted lists. It can be one character (\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...}]
This specifies the text which should be used for drawing horizontal rules (generated by \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...}]
This specifies a set of quote characters for the text backend, overriding any defined by \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...}]
This specifies the characters which should be used to surround emphasised text (written using the \e 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.

4.1.5 Miscellaneous configuration options

\cfg{text-list-suffix}{text}
This text is appended to the number on a numbered list item (see section 3.3.2.2). So if you want to label your lists as ‘1)’, ‘2)’ and so on, then you would write \cfg{text-list-suffix}{)}.
\cfg{text-versionid}{boolean}
If this is set to 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.

4.1.6 Default settings

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-suffix}{: }

\cfg{text-section-align}{0}{leftplus}
\cfg{text-section-underline}{0}{}
\cfg{text-section-numeric}{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-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}

4.2 HTML

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.

Strictly speaking, the output format is XHTML 1.0 Transitional, which is why all of the configuration directives start with the word xhtml rather than html.

4.2.1 Controlling the output file names

\cfg{xhtml-contents-filename}{filename}
Sets the 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 index.html (although this is not the default, for historical reasons).
\cfg{xhtml-index-filename}{filename}
Sets the file name in which to store the document's index.
\cfg{xhtml-template-filename}{template}
Provides a template to be used when constructing the file names of each chapter or section of the document. This template should contain at least one 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 %%.)

The formatting commands used in this template are:

%N
Expands to the visible title of the section, with white space removed. So in a chapter declared as ‘\C{fish} Catching Fish’, this formatting command would expand to ‘CatchingFish’.
%n
Expands to the type and number of the section, without white space. So in chapter 1 this would expand to ‘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
Expands to the bare number of the section. So in chapter 1 this would expand to ‘1’; in section A.4.3 it would expand to ‘A.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
Expands to the internal keyword specified in the section title. So in a chapter declared as ‘\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{xhtml-template-fragment} configuration directive (see section 4.2.5).

\cfg{xhtml-single-filename}{filename}
Sets the file name in which to store the entire document, if Halibut is configured (using \cfg{xhtml-leaf-level}{0} to produce a single self-contained file. Both this directive and \cfg{xhtml-leaf-level}{0} are implicitly generated if you provide a file name parameter after the command-line option --html (see section 2.1).

4.2.2 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.

\cfg{xhtml-leaf-level}{depth}
This setting indicates the depth of section which should be given a ‘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 and each \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.

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.

\cfg{xhtml-contents-depth-level}{depth}
This directive allows you to specify how deep the contents section in a particular file should go.

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. Currently you can't go below level 5 (which corresponds to a \S3 heading).

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{xhtml-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.

\cfg{xhtml-leaf-contains-contents}{boolean}
If you set this to true, then each leaf file will contain its own contents section which summarises the text within it.
\cfg{xhtml-leaf-smallest-contents}{number}
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.

4.2.3 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.

\cfg{xhtml-head-end}{HTML text}
The text you provide in this directive is placed at the end of the <HEAD> section of each output HTML file. So this is a good place to put, for example, a link to a CSS stylesheet.
\cfg{xhtml-body-tag}{HTML text}
The text you provide in this directive is used in place of the <BODY> tag in each output file. So if you wanted to define a background colour, for example, you could write \cfg{xhtml-body-tag}{<body bg="#123456">}.
\cfg{xhtml-body-start}{HTML text}
The text you provide in this directive is placed at the beginning of the <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{xhtml-body-end}{HTML text}
The text you provide in this directive is placed at the end of the <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 footer at the bottom of every page, this is where you can add that footer.
\cfg{xhtml-address-start}{HTML text}
The text you provide in this directive is placed at the beginning of the <ADDRESS> section at the bottom of each output HTML file. This might be a good place to put authors' contact details, for example.
\cfg{xhtml-address-end}{HTML text}
The text you provide in this directive is placed at the end of the <ADDRESS> section at the bottom of each output HTML file, after the version IDs (if present).
\cfg{xhtml-navigation-attributes}{HTML attributes}
The text you provide in this directive is included inside the <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{xhtml-navigation-attributes}{class="foo"}, and the navigation-links paragraph would then begin with the tag <p class="foo">.

4.2.4 Configuring heading display

\cfg{xhtml-chapter-numeric}{boolean}
If this is set to 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{xhtml-chapter-suffix}{text}
This specifies the suffix text to be appended to the chapter number, before displaying the chapter title. For example, if you set this to ‘’, then the chapter title might look something like ‘Chapter 2: Doing Things’.
\cfg{xhtml-section-numeric}{level}{boolean}
Specifies whether section headings at a particular level should contain the word ‘Section’ or equivalent (if 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{xhtml-section-suffix}{level}{text}
Specifies the suffix text to be appended to section numbers at a particular level, before displaying the section title.

4.2.5 Miscellaneous options

\cfg{xhtml-template-fragment}{template}
This directive lets you specify a template, with exactly the same syntax used in \cfg{xhtml-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.
\cfg{xhtml-versionid}{boolean}
If this is set to 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 be omitted completely.
\cfg{xhtml-suppress-address}{boolean}
If this is set to 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.)
\cfg{xhtml-author}{text}
The text supplied here goes in a <META name="author"> tag in the output HTML files, so that browsers which support this can automatically identify the author of the document.
\cfg{xhtml-description}{text}
The text supplied here goes in a <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.

4.2.6 Default settings

The default settings for Halibut's HTML output format are:

\cfg{xhtml-contents-filename}{Contents.html}
\cfg{xhtml-index-filename}{IndexPage.html}
\cfg{xhtml-template-filename}{%n.html}
\cfg{xhtml-single-filename}{Manual.html}
\cfg{xhtml-template-fragment}{%b}

\cfg{xhtml-leaf-level}{2}
\cfg{xhtml-leaf-contains-contents}{false}
\cfg{xhtml-leaf-smallest-contents}{4}
\cfg{xhtml-contents-depth-0}{2}
\cfg{xhtml-contents-depth-1}{3}
\cfg{xhtml-contents-depth-2}{4}
\cfg{xhtml-contents-depth-3}{5}
\cfg{xhtml-contents-depth-4}{6}
\cfg{xhtml-contents-depth-5}{7}

\cfg{xhtml-head-end}{}
\cfg{xhtml-body-tag}{<body>}
\cfg{xhtml-body-start}{}
\cfg{xhtml-body-end}{}
\cfg{xhtml-address-start}{}
\cfg{xhtml-address-end}{}
\cfg{xhtml-navigation-attributes}{}

\cfg{xhtml-versionid}{true}
\cfg{xhtml-suppress-address}{false}
\cfg{xhtml-author}{}
\cfg{xhtml-description}{}

\cfg{xhtml-chapter-numeric}{false}
\cfg{xhtml-chapter-suffix}{: }

\cfg{xhtml-section-numeric}{0}{true}
\cfg{xhtml-section-suffix}{0}{ }

\cfg{xhtml-section-numeric}{1}{true}
\cfg{xhtml-section-suffix}{1}{ }

... and so on for all section levels below this ...

4.3 Windows Help

This output format generates data that can be used by the Windows Help program WINHELP.EXE. There are two actual files generated, one ending in .hlp and the other ending in .cnt.

Currently, the output is harcoded to be in the ‘Win1252’ character set.

The Windows Help output format supports the following configuration directives:

4.3.1 Output file name

\cfg{winhelp-filename}{filename}
Sets the output file name in which to store the man page. This directive is implicitly generated if you provide a file name parameter after the command-line option --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.

4.3.2 Configuring the characters used

\cfg{winhelp-bullet}{text}[{text}...]
Specifies the text to use as the bullet in bulletted lists. You can specify multiple fallback options. Works exactly like the \cfg{text-bullet} directive (see section 4.1.4).
\cfg{winhelp-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
Specifies the quotation marks to use, overriding any \cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).

4.3.3 Miscellaneous configuration options

\cfg{winhelp-contents-titlepage}{title}
Sets the text used to describe the help page containing the blurb (see section 3.3.6) and table of contents.
\cfg{winhelp-section-suffix}{text}
Specifies the suffix text to be appended to section numbers, before displaying the section title. (Applies to all levels.)
\cfg{winhelp-list-suffix}{text}
This text is appended to the number on a numbered list item, in exactly the same way as \cfg{text-list-suffix} (see section 4.1.4).
\cfg{winhelp-topic}{topic-name}
This directive defines a Windows Help topic name in the current section. Topic names can be used by the program invoking 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.

4.3.4 Default settings

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.

4.4 Unix 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:

4.4.1 Output file name

\cfg{man-filename}{filename}
Sets the output file name in which to store the man page. This directive is implicitly generated if you provide a file name parameter after the command-line option --man (see section 2.1).

4.4.2 Configuring headers and footers

\cfg{man-identity}{text}{text...}
This directive is used to generate the initial .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:

  1. The name of the program.
  2. The (numeric) manual section.
  3. The date that the man page was written.
  4. The name of any containing suite of which the program is a part.
  5. The name of the author of the man page.

For example, a typical man page might contain

\cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
Bloggs}

4.4.3 Configuring heading display

\cfg{man-headnumbers}{boolean}
If this is set to 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}
If this is set to a number greater than 0, then section headings higher than the given depth will not be displayed. If it is set to zero, all section headings will be displayed as normal.

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.

4.4.4 Configuring the characters used

\cfg{man-charset}{character set}
Specifies what character set the output should be in, similarly to \cfg{text-charset} (see section 4.1.4).
\cfg{man-bullet}{text}[{text}...]
Specifies the text to use as the bullet in bulletted lists. You can specify multiple fallback options. Works exactly like the \cfg{text-bullet} directive (see section 4.1.4).
\cfg{man-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
Specifies the quotation marks to use, overriding any \cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).

4.4.5 Default settings

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-quotes}{\u2018}{\u2019}{"}{"}

4.5 GNU info

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:

4.5.1 Controlling the output filenames

\cfg{info-filename}{filename}
Sets the output file name in which to store the info file. This directive is implicitly generated if you provide a file name parameter after the command-line option --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}
Sets the preferred maximum file size for each subsidiary file. As a special case, if you set this to zero, there will be no subsidiary files and the whole document will be placed in a single self-contained output file. (However, note that this file can still not be renamed usefully.)

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).

4.5.2 Indentation and line width

\cfg{info-width}{width}
Sets the width of the main part of the document, in characters. Works exactly like the \cfg{text-width} directive (see section 4.1.2).
\cfg{info-indent-code}{indent}
Specifies the extra indentation for code paragraphs. Works exactly like the \cfg{text-indent-code} directive (see section 4.1.2).
\cfg{info-index-width}{width}
Specifies how much horizontal space to leave in the index node for the text of index terms, before displaying the sections the terms occur in.
\cfg{info-list-indent}{indent}
Specifies the extra indentation before the bullet or number in a list item. Works exactly like the \cfg{text-list-indent} directive (see section 4.1.2).
\cfg{info-listitem-indent}{indent}
Specifies the additional indentation before the body of a list item. Works exactly like the \cfg{text-listitem-indent} directive (see section 4.1.2).

4.5.3 Configuring heading display

\cfg{info-section-suffix}{text}
Specifies the suffix text to be appended to each section number before displaying the section title. For example, if you set this to ‘’, then a typical section title might look something like ‘Section 3.1: Something Like This’.
\cfg{info-underline}{text}[{text}...]
Specifies the text to be used to underline section titles. Works very much like the \cfg{text-chapter-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.

4.5.4 Controlling the characters used

\cfg{info-charset}{character set}
Specifies what character set the output should be in, similarly to \cfg{text-charset} (see section 4.1.4).
\cfg{info-bullet}{text}[{text}...]
Specifies the text to use as the bullet in bulletted lists. You can specify multiple fallback options. Works exactly like the \cfg{text-bullet} directive (see section 4.1.4).
\cfg{info-rule}{text}[{text}...]
Specifies the text used to draw horizontal rules. You can specify multiple fallback options. Works exactly like the \cfg{text-rule} directive (see section 4.1.4).
\cfg{info-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
Specifies the quotation marks to use, overriding any \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...}]
Specifies how to display emphasised text. You can specify multiple fallback options. Works exactly like the \cfg{text-emphasis} directive (see section 4.1.4).

4.5.5 Miscellaneous configuration options

\cfg{info-list-suffix}{text}
Specifies the text to append to the item numbers in a numbered list. Works exactly like the \cfg{text-list-suffix} directive (see section 4.1.5).
\cfg{info-dir-entry}{section}{short name}{long name}[{keyword}]
Constructs an 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:

section
Specifies the section of the dir file in which you want your document referenced. For example, ‘Development’, or ‘Games’, or ‘Miscellaneous’.
short name
Specifies a short name for the directory entry, which will appear at the start of the menu line.
long name
Specifies a long name for the directory entry, which will appear at the end of the menu line.
keyword
This parameter is optional. If it is present, then the directory entry will cause a jump to a particular subsection of your document, rather than starting at the top. The subsection will be the one referred to by the given keyword (see section 3.3.5 for details about assigning keywords to document sections).

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.

4.5.6 Default settings

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-underline}{\u203e}{-}

\cfg{info-charset}{ASCII}
\cfg{info-bullet}{\u2022}{-}
\cfg{info-rule}{\u2500}{-}
\cfg{info-quotes}{\u2018}{\u2019}{`}{'}
\cfg{info-emphasis}{_}{_}

\cfg{info-list-suffix}{.}

and no \cfg{info-dir-entry} directives.

4.6 Paper formats

These output formats (currently PostScript and PDF) generate printable manuals. As such, they share a number of configuration directives.

4.6.1 PostScript

This output format generates a printable manual in PostScript format.

There is one configuration option specific to PostScript:

\cfg{ps-filename}{filename}
Sets the output file name in which to store the PostScript file. This directive is implicitly generated if you provide a file name parameter after the command-line option --ps (see section 2.1).

The default settings for the PostScript output format are:

\cfg{ps-filename}{output.ps}

4.6.2 PDF

This output format generates a printable manual in PDF format. This should look exactly identical to the PostScript output (see section 4.6.1), but also 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}
Sets the output file name in which to store the PDF file. This directive is implicitly generated if you provide a file name parameter after the command-line option --pdf (see section 2.1).

The default settings for the PDF output format are:

\cfg{pdf-filename}{output.pdf}

4.6.3 Configuring layout and measurements

All measurements are in PostScript points (72 points to the inch).

4.6.3.1 Page properties

\cfg{paper-page-width}{points}
\cfg{paper-page-height}{points}
Specify the absolute limits of the paper.
\cfg{paper-left-margin}{points}
\cfg{paper-top-margin}{points}
\cfg{paper-right-margin}{points}
\cfg{paper-bottom-margin}{points}
Specify the margins. Most text appears within these margins, except:

4.6.3.2 Vertical spacing

\cfg{paper-base-leading}{points}
Specifies the amount of space between lines of text within a paragraph. (So, if the font size is 12pt and there is 2pt of leading, there will be 14pt between successive baselines.)
\cfg{paper-base-para-spacing}{points}
Specifies the amount of vertical space between paragraphs. (The vertical space between paragraphs does not include paper-base-leading.)

4.6.3.3 Indentation

\cfg{paper-list-indent}{points}
Specifies the indentation of the bullet or number in a bulletted or numbers list, similarly to \cfg{text-list-indent} (see section 4.1.2).
\cfg{paper-listitem-indent}{points}
Specifies the extra indentation for the body of a list item, over and above the amount configured in \cfg{paper-list-indent}.
\cfg{paper-quote-indent}{points}
Specifies the amount of indentation for a level of quoting. Used for \quote (see section 3.3.4) and code quotes with \c (see section 3.2.2).

4.6.3.4 Headings

\cfg{paper-chapter-top-space}{points}
Specifies the space between the top margin and the top of the chapter heading. (Each chapter begins on a new page.)
\cfg{paper-chapter-underline-thickness}{points}
Specifies the vertical thickness of the black rule under chapter headings.
\cfg{paper-chapter-underline-depth}{points}
Specifies the distance between the base of the chapter heading and the base of the underlying rule.
\cfg{paper-sect-num-left-space}{points}
Specifies the distance between the left margin and the right of section numbers (which are in the left margin).

4.6.3.5 Contents and index

\cfg{paper-contents-index-step}{points}
\cfg{paper-contents-margin}{points}
\cfg{paper-leader-separation}{points}
Specifies the horizontal spacing between dots in leaders (the dotted lines that appear between section headings and page numbers in the table of contents).
\cfg{paper-footer-distance}{points}
Specifies the distance between the bottom margin and the base of the footer (which contains page numbers).
\cfg{paper-index-columns}{columns}
Specifies the number of columns the index should be divided into.
\cfg{paper-index-gutter}{points}
Specifies the amount of horizontal space between index columns.
\cfg{paper-index-minsep}{points}
Specifies the minimum allowable horizontal space between an index entry and its page number. If the gap is smaller, the page number is moved to the next line.

4.6.3.6 Fonts

\cfg{paper-base-font-size}{points}
Specifies the font size of body text.
\cfg{paper-pagenum-font-size}{points}
Specifies the font size to use for page numbers.

4.6.3.7 Miscellaneous

\cfg{paper-rule-thickness}{points}
Specifies the vertical thickness of the rule produced by the \rule command (see section 3.3.3). (Note that no extra space is reserved for thicker rules.)

4.6.4 Configuring the characters used

\cfg{paper-bullet}{text}[{text}...]
Specifies the text to use as the bullet in bulletted lists. You can specify multiple fallback options. Works exactly like the \cfg{text-bullet} directive (see section 4.1.4).
\cfg{paper-quotes}{open-quote}{close-quote}[{open-quote}{close-quote...}]
Specifies the quotation marks to use, overriding any \cfg{quotes} directive. You can specify multiple fallback options. Works exactly like the \cfg{text-quotes} directive (see section 4.1.4).

4.6.5 Default settings for paper formats

The default page size corresponds to 210 × 297 mm, i.e., A4 paper.

\cfg{paper-page-width}{595} 
\cfg{paper-page-height}{841} 

\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-index-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-font-size}{12} 
\cfg{paper-pagenum-font-size}{12} 

\cfg{paper-rule-thickness}{1} 

\cfg{paper-bullet}{\u2022}{-}
\cfg{paper-quotes}{\u2018}{\u2019}{'}{'}

Comments to anakin@pobox.com
[$Id: blurb.but,v 1.4 2004/04/09 18:43:02 simon Exp $]
[$Id: licence.but,v 1.3 2004/06/12 20:09:40 simon Exp $]