This Info file generated by Halibut, version 1.3

INFO-DIR-SECTION Documentation
START-INFO-DIR-ENTRY
* Halibut: (halibut).   Multi-format documentation processing system
END-INFO-DIR-ENTRY

This manual is copyright 2004-2017 Simon Tatham. All rights reserved.
You may distribute this documentation under the MIT licence. See
*Note Appendix A:: for the licence text in full.

[Halibut version 1.3]

File: halibut.info,  Node: Section 3.6,  Prev: Section 3.5.4,  Up: Chapter 3,  Next: Section 3.7

Section 3.6: Configuring Halibut
--------------------------------

Halibut uses the `\cfg' command to allow you to configure various
aspects of its functionality.

The `\cfg' command expects to be followed by at least one pair of
braces, and usually more after that. The first pair of braces contains
a keyword indicating what aspect of Halibut you want to configure, and
the meaning of the one(s) after that depends on the first keyword.

Each output format supports a range of configuration options of its
own (and some configuration is shared between similar output formats -
the PDF and PostScript formats share most of their configuration, as
described in *Note Section 4.7::). The configuration keywords for each
output format are listed in the manual section for that format; see
*Note Chapter 4::.

There are also a small number of configuration options which apply
across all output formats:

\cfg{chapter}{_new chapter name_}

    This tells Halibut that you don't want to call a chapter
    a chapter any more. For example, if you give the command
    \cfg{chapter}{Book}, then any chapter defined with the `\C'
    command will be labelled `Book' rather than `Chapter', both in the
    section headings and in cross-references. This is probably most
    useful if your document is not written in English.

    Your replacement name should be given with a capital letter.
    Halibut will leave it alone if it appears at the start of a
    sentence (in a chapter title, or when `\K' is used), and will
    lower-case it otherwise (when `\k' is used).

\cfg{section}{_new section name_}

    Exactly like `chapter', but changes the name given to subsections
    of a chapter.

\cfg{appendix}{_new appendix name_}

    Exactly like `chapter', but changes the name given to appendices.

\cfg{contents}{_new contents name_}

    This changes the name given to the contents section (by default
    `Contents') in back ends which generate one.

\cfg{index}{_new index name_}

    This changes the name given to the index section (by default
    `Index') in back ends which generate one.

\cfg{input-charset}{_character set name_}

    This tells Halibut what character set you are writing your input
    file in. By default, it is assumed to be US-ASCII (meaning _only_
    plain ASCII, with no accented characters at all).

    You can specify any well-known name for any supported character
    set. For example, `iso-8859-1', `iso8859-1' and `iso_8859-1' are
    all recognised, `GB2312' and `EUC-CN' both work, and so on. (You
    can list character sets known to Halibut with by invoking it with
    the --list-charsets option; see *Note Section 2.1::.)

    This directive takes effect immediately after the `\cfg' command.
    All text after that until the end of the input file is expected
    to be in the new character set. You can even change character set
    several times within a file if you really want to.

    When Halibut reads the input file, everything you type will be
    converted into Unicode from the character set you specify here,
    will be processed as Unicode by Halibut internally, and will be
    written to the various output formats in whatever character sets
    they deem appropriate.

\cfg{quotes}{_open-quote_}{_close-quote_}[{_open-quote_}{_close-
quote_...}]

    This specifies the quote characters which should be used. You
    should separately specify the open and close quote marks; each
    quote mark can be one character (\cfg{quotes}{`}{'}), or more than
    one (\cfg{quotes}{<<}{>>}).

    \cfg{quotes} can be overridden by configuration directives
    for each individual backend (see *Note Chapter 4::); it is a
    convenient way of setting quote characters for all backends at
    once.

    All backends use these characters in response to the `\q' command
    (see *Note Section 3.2.3::). Some (such as the text backend) use
    them for other purposes too.

    You can specify multiple fallback options in this command (a pair
    of open and close quotes, each in their own braces, then another
    pair, then another if you like), and Halibut will choose the first
    pair which the output character set supports (Halibut will always
    use a matching pair). (This is to allow you to configure quote
    characters 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

      \cfg{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 _both_ open and close quotes. (No known character set
    is that silly; I mention it only as an example.)

    \cfg{quotes} (and the backend-specific versions) apply to the
    _entire_ output; it's not possible to change quote characters
    partway through the output.

In addition to these configuration commands, there are also
configuration commands provided by each individual output format.
These configuration commands are discussed along with each output
format, in *Note Chapter 4::.

The default settings for the above options are:

  \cfg{chapter}{Chapter}
  \cfg{section}{Section}
  \cfg{appendix}{Appendix}
  \cfg{contents}{Contents}
  \cfg{index}{Index}
  \cfg{input-charset}{ASCII}

The default for \cfg{input-charset} can be changed with the --input-
charset option; see *Note Section 2.1::. The default settings for
\cfg{quotes} are backend-specific; see *Note Chapter 4::.


File: halibut.info,  Node: Section 3.7,  Prev: Section 3.6,  Up: Chapter 3,  Next: Chapter 4

Section 3.7: Defining macros
----------------------------

If there's a complicated piece of Halibut source which you think
you're going to use a lot, you can define your own Halibut command to
produce that piece of source.

In *Note Section 3.2.7::, there is a sample piece of code which
prints a Euro sign, or replaces it with `EUR' if the Euro sign is not
available:

  This is likely to cost \u20AC{EUR\_}2500 at least.

If your document quotes a _lot_ of prices in Euros, you might not want
to spend all your time typing that out. So you could define a macro,
using the `\define' command:

  \define{eur} \u20AC{EUR\_}

Your macro names may include Roman alphabetic characters (`a'-`z',
`A'-`Z') and ordinary Arabic numerals (`0'-`9'), but nothing else.
(This is general syntax for all of Halibut's commands, except for
a few special ones such as `\_' and `\-' which consist of a single
punctuation character only.)

Then you can just write ...

  This is likely to cost \eur 2500 at least.

... except that that's not terribly good, because you end up with
a space between the Euro sign and the number. (If you had written
`\eur2500', Halibut would have tried to interpret it as a macro
command called `eur2500', which you didn't define.) In this case,
it's helpful to use the special `\.' command, which is defined to do
nothing at all! But it acts as a separator between your macro and the
next character:

  This is likely to cost \eur\.2500 at least.

This way, you will see no space between the Euro sign and the number
(although, of course, there will be space between `EUR' and the number
if the Euro sign is not available, because the macro definition
specifically asked for it).


File: halibut.info,  Node: Chapter 4,  Prev: Section 3.7,  Up: Top,  Next: Section 4.1

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.

* Menu:

* Section 4.1:: Plain text
* Section 4.2:: HTML
* Section 4.3:: Windows HTML Help
* Section 4.4:: Legacy Windows Help
* Section 4.5:: Unix man pages
* Section 4.6:: GNU Info
* Section 4.7:: Paper formats

File: halibut.info,  Node: Section 4.1,  Prev: Chapter 4,  Up: Chapter 4,  Next: Section 4.1.1

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

* Menu:

* Section 4.1.1:: Output file name
* Section 4.1.2:: Indentation and line width
* Section 4.1.3:: Configuring heading display
* Section 4.1.4:: Configuring the characters used
* Section 4.1.5:: Miscellaneous configuration options
* Section 4.1.6:: Default settings

File: halibut.info,  Node: Section 4.1.1,  Prev: Section 4.1,  Up: Section 4.1,  Next: Section 4.1.2

Section 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
    *Note Section 2.1::).


File: halibut.info,  Node: Section 4.1.2,  Prev: Section 4.1.1,  Up: Section 4.1,  Next: Section 4.1.3

Section 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
    *Note 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
    *Note 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.


File: halibut.info,  Node: Section 4.1.3,  Prev: Section 4.1.2,  Up: Section 4.1,  Next: Section 4.1.4

Section 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 *Note Section 3.3.5:: and *Note 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_}

    If this is set to `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_}

    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-shownumber}{_level_}{_boolean_}

    If this is set to `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_}

    Specifies the suffix text to be appended to section numbers at a
    particular level, before displaying the section title.


File: halibut.info,  Node: Section 4.1.4,  Prev: Section 4.1.3,  Up: Section 4.1,  Next: Section 4.1.5

Section 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 *Note 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 *Note 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
    *Note 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 *Note Section 3.6::).

    In this backend, these quotes will also be used to mark text
    enclosed in the `\c' command (see *Note 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
    *Note Section 3.2.1::).

\cfg{text-strong}{_start-strong_}{_end-strong_}[{_start-strong_}{_end-
strong_...}]

    This specifies the characters which should be used to
    surround strong text (written using the `\s' command; see
    *Note 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.


File: halibut.info,  Node: Section 4.1.5,  Prev: Section 4.1.4,  Up: Section 4.1,  Next: Section 4.1.6

Section 4.1.5: Miscellaneous configuration options
..................................................

\cfg{text-list-suffix}{_text_}

    This text is appended to the number on a numbered list item (see
    *Note 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 *Note 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.


File: halibut.info,  Node: Section 4.1.6,  Prev: Section 4.1.5,  Up: Section 4.1,  Next: Section 4.2

Section 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-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}


File: halibut.info,  Node: Section 4.2,  Prev: Section 4.1.6,  Up: Chapter 4,  Next: Section 4.2.1

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

Configuration directives with an `xhtml-' prefix are synonyms for
those with an `html-' prefix.

* Menu:

* Section 4.2.1:: Controlling the output file names
* Section 4.2.2:: Controlling the splitting into HTML files
* Section 4.2.3:: Including pieces of your own HTML
* Section 4.2.4:: Configuring heading display
* Section 4.2.5:: Configuring standard text
* Section 4.2.6:: Configuring the characters used
* Section 4.2.7:: Miscellaneous options
* Section 4.2.8:: Default settings

File: halibut.info,  Node: Section 4.2.1,  Prev: Section 4.2,  Up: Section 4.2,  Next: Section 4.2.2

Section 4.2.1: Controlling the output file names
................................................

\cfg{html-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{html-index-filename}{_filename_}

    Sets the file name in which to store the document's index.

\cfg{html-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 number of the section, in a format suitable for
        an HTML fragment name. The first character of the section type
        is prepended to the section number. So in chapter 1 this would
        expand to `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'

        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{html-template-fragment} configuration directive (see
    *Note Section 4.2.7::).

\cfg{html-single-filename}{_filename_}

    Sets the file name in which to store the entire document, if
    Halibut is configured (using `\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
    *Note Section 2.1::).


File: halibut.info,  Node: Section 4.2.2,  Prev: Section 4.2.1,  Up: Section 4.2,  Next: Section 4.2.3

Section 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{html-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' by default.

    This option is automatically set to zero if you provide a file
    name parameter after the command-line option `--html' (see
    *Note 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_}

    This directive allows you to specify how deep any contents section
    in a particular level of 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.

    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_}

    If you set this to `true', then each leaf file will contain its
    own contents section which summarises the text within it.

\cfg{html-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.


File: halibut.info,  Node: Section 4.2.3,  Prev: Section 4.2.2,  Up: Section 4.2,  Next: Section 4.2.4

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

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_}

    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{html-local-head}{_HTML text_}

    This configuration directive is local: you specify it within a
    document section, and it acts on that section only.

    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_}

    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{html-body-
    tag}{<body bg="#123456">}.

\cfg{html-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{html-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, 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_}

    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{html-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{html-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{html-navigation-attributes}{class="foo"}, and the navigation-
    links paragraph would then begin with the tag <p class="foo">.


File: halibut.info,  Node: Section 4.2.4,  Prev: Section 4.2.3,  Up: Section 4.2,  Next: Section 4.2.5

Section 4.2.4: Configuring heading display
..........................................

\cfg{html-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 *Note Section 3.3.5:: and *Note 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_}

    If this is set to `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_}

    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{html-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{html-section-shownumber}{_level_}{_boolean_}

    If this is set to `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_}

    Specifies the suffix text to be appended to section numbers at a
    particular level, before displaying the section title.


File: halibut.info,  Node: Section 4.2.5,  Prev: Section 4.2.4,  Up: Section 4.2,  Next: Section 4.2.6

Section 4.2.5: Configuring standard 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_}

    Text used to refer to the preamble (i.e., any paragraphs before
    the first chapter heading), contents, and index respectively, in
    the navigation bar, contents, and index.

    (`html-contents-text' and `html-index-text' override the cross-
    format configuration keywords `contents' and `index' (see
    *Note 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_}

    If multiple headings are used in a file's <TITLE> tag, this text
    is used to separate them.

\cfg{html-index-main-separator}{_text_}

    Separator between index term and references in the index.

\cfg{html-index-multiple-separator}{_text_}

    Separator between multiple references for a single index term in
    the index.

\cfg{html-pre-versionid}{_text_}

\cfg{html-post-versionid}{_text_}

    Text surrounding each output version ID paragraph.

\cfg{html-nav-prev-text}{_text_}

\cfg{html-nav-next-text}{_text_}

\cfg{html-nav-up-text}{_text_}

    The text used for the `previous page', `next page', and `up' links
    on the navigation bar.

\cfg{html-nav-separator}{_text_}

    Separator between links in the navigation bar.


File: halibut.info,  Node: Section 4.2.6,  Prev: Section 4.2.5,  Up: Section 4.2,  Next: Section 4.2.7

Section 4.2.6: Configuring the characters used
..............................................

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
*Note 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_}

    The character encoding of the HTML file to be output. Unicode
    characters in this encoding's repertoire are included literally
    rather than as HTML entities.

\cfg{html-restrict-charset}{_character set name_}

    Only Unicode characters representable in this character set will
    be output; any others will be omitted and use their fallback
    text, if any. Characters not in `html-output-charset' will be
    represented as HTML numeric entities.

\cfg{html-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
    *Note Section 4.1.4::).


File: halibut.info,  Node: Section 4.2.7,  Prev: Section 4.2.6,  Up: Section 4.2,  Next: Section 4.2.8

Section 4.2.7: Miscellaneous options
....................................

\cfg{html-version}{_version_}

    Identifies the precise version of HTML that is output. This
    affects the declaration within the HTML, and also has minor
    effects on the body of the HTML so that it is valid for the
    declared version. The available variants are:

    html3.2

        W3C HTML 3.2

    html4

        W3C HTML 4.01 Strict

    iso-html

        ISO/IEC 15445:2000

    xhtml1.0transitional

        W3C XHTML 1.0 Transitional

    xhtml1.0strict

        W3C XHTML 1.0 Strict

\cfg{html-template-fragment}{_template_}[{_template_}{...}]

    This directive lets you specify a template, with exactly
    the same syntax used in \cfg{html-template-filename} (see
    *Note 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_}

    If this is set to `true', version ID paragraphs (defined using the
    `\versionid' command - see *Note 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_}

    If this is set to `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_}

    If this is set to `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_}

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

\cfg{html-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{html-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.


File: halibut.info,  Node: Section 4.2.8,  Prev: Section 4.2.7,  Up: Section 4.2,  Next: Section 4.3

Section 4.2.8: Default settings
...............................

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


File: halibut.info,  Node: Section 4.3,  Prev: Section 4.2.8,  Up: Chapter 4,  Next: Section 4.3.1

Section 4.3: Windows HTML Help
------------------------------

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
*Note Section 4.3.6:: for details.

* Menu:

* Section 4.3.1:: Output file name
* Section 4.3.2:: Configuration shared with the HTML back end
* Section 4.3.3:: Including extra files in the CHM
* Section 4.3.4:: Renaming the CHM internal support files
* Section 4.3.5:: Default settings
* Section 4.3.6:: Generating input to the MS Windows HTML Help compiler

File: halibut.info,  Node: Section 4.3.1,  Prev: Section 4.3,  Up: Section 4.3,  Next: Section 4.3.2

Section 4.3.1: Output file name
...............................

\cfg{chm-filename}{_filename_}

    Sets the output file name in which to store the HTML Help
    file. This directive is implicitly generated if you provide a
    file name parameter after the command-line option `--chm' (see
    *Note Section 2.1::).


File: halibut.info,  Node: Section 4.3.2,  Prev: Section 4.3.1,  Up: Section 4.3,  Next: Section 4.3.3

Section 4.3.2: Configuration shared with the HTML back end
..........................................................

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 *Note 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 *Note 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.


File: halibut.info,  Node: Section 4.3.3,  Prev: Section 4.3.2,  Up: Section 4.3,  Next: Section 4.3.4

Section 4.3.3: Including extra files in the CHM
...............................................

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_}

    Tells Halibut to read an additional input file from _filename_ and
    incorporate it into the 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.


File: halibut.info,  Node: Section 4.3.4,  Prev: Section 4.3.3,  Up: Section 4.3,  Next: Section 4.3.5

Section 4.3.4: Renaming the CHM internal support files
......................................................

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_}

    Controls the name of the internal contents file in the CHM.

\cfg{chm-index-name}{_filename_}

    Controls the name of the internal index file in the CHM.


File: halibut.info,  Node: Section 4.3.5,  Prev: Section 4.3.4,  Up: Section 4.3,  Next: Section 4.3.6

Section 4.3.5: Default settings
...............................

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}


File: halibut.info,  Node: Section 4.3.6,  Prev: Section 4.3.5,  Up: Section 4.3,  Next: Section 4.4

Section 4.3.6: Generating input to the MS Windows HTML Help compiler
....................................................................

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_}

    Instructs Halibut to output an HTML Help project file with the
    specified name. You will almost certainly want the filename to end
    in the extension `.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_}

    Specifies the desired name of the compiled HTML Help file. You
    will almost certainly want this to have the extension `.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_}

    Instructs Halibut to output an HTML Help contents file with the
    specified name, and refer to it in the help project file. You will
    almost certainly want the filename to end in the extension `.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_}

    Instructs Halibut to output an HTML Help index file with the
    specified name, and refer to it in the help project file. You will
    almost certainly want the filename to end in the extension `.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
    *Note 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 *Note 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.


File: halibut.info,  Node: Section 4.4,  Prev: Section 4.3.6,  Up: Chapter 4,  Next: Section 4.4.1

Section 4.4: Legacy Windows Help
--------------------------------

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 *Note 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:

* Menu:

* Section 4.4.1:: Output file name
* Section 4.4.2:: Configuring the characters used
* Section 4.4.3:: Miscellaneous configuration options
* Section 4.4.4:: Default settings

File: halibut.info,  Node: Section 4.4.1,  Prev: Section 4.4,  Up: Section 4.4,  Next: Section 4.4.2

Section 4.4.1: Output file name
...............................

\cfg{winhelp-filename}{_filename_}

    Sets the output file name in which to store the help file.
    This directive is implicitly generated if you provide a file
    name parameter after the command-line option `--winhelp' (see
    *Note 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.


File: halibut.info,  Node: Section 4.4.2,  Prev: Section 4.4.1,  Up: Section 4.4,  Next: Section 4.4.3

Section 4.4.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 *Note 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
    *Note Section 4.1.4::).


File: halibut.info,  Node: Section 4.4.3,  Prev: Section 4.4.2,  Up: Section 4.4,  Next: Section 4.4.4

Section 4.4.3: Miscellaneous configuration options
..................................................

\cfg{winhelp-contents-titlepage}{_title_}

    Sets the text used to describe the help page containing the blurb
    (see *Note 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
    *Note 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.


File: halibut.info,  Node: Section 4.4.4,  Prev: Section 4.4.3,  Up: Section 4.4,  Next: Section 4.5

Section 4.4.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.


File: halibut.info,  Node: Section 4.5,  Prev: Section 4.4.4,  Up: Chapter 4,  Next: Section 4.5.1

Section 4.5: 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:

* Menu:

* Section 4.5.1:: Output file name
* Section 4.5.2:: Configuring headers and footers
* Section 4.5.3:: Configuring heading display
* Section 4.5.4:: Configuring the characters used
* Section 4.5.5:: Default settings

File: halibut.info,  Node: Section 4.5.1,  Prev: Section 4.5,  Up: Section 4.5,  Next: Section 4.5.2

Section 4.5.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
    *Note Section 2.1::).


File: halibut.info,  Node: Section 4.5.2,  Prev: Section 4.5.1,  Up: Section 4.5,  Next: Section 4.5.3

Section 4.5.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}


File: halibut.info,  Node: Section 4.5.3,  Prev: Section 4.5.2,  Up: Section 4.5,  Next: Section 4.5.4

Section 4.5.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.


File: halibut.info,  Node: Section 4.5.4,  Prev: Section 4.5.3,  Up: Section 4.5,  Next: Section 4.5.5

Section 4.5.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 *Note 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 *Note Section 4.1.4::).

\cfg{man-rule}{_text_}[{_text_...}]

    This specifies the text which should be used for drawing
    horizontal rules (generated by `\rule'; see *Note 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 *Note 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
    *Note Section 4.1.4::).


File: halibut.info,  Node: Section 4.5.5,  Prev: Section 4.5.4,  Up: Section 4.5,  Next: Section 4.6

Section 4.5.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-rule}{\u2500}{-}
  \cfg{man-quotes}{\u2018}{\u2019}{"}{"}

