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: Top,  Up: (dir),  Next: Chapter 1

Halibut User Manual
*******************

Halibut is a free (MIT-licensed) documentation production system, able
to generate multiple output formats from the same input data. This
document is its user manual.

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.

* Menu:

* Chapter 1:: Introduction to Halibut
* Chapter 2:: Running Halibut
* Chapter 3:: Halibut input format
* Chapter 4:: Halibut output formats
* Appendix A:: Halibut Licence
* Appendix B:: Halibut man page
* Index::

File: halibut.info,  Node: Chapter 1,  Prev: Top,  Up: Top,  Next: Section 1.1

Chapter 1: Introduction to Halibut
==================================

Halibut is a multi-format documentation processing system.

What that means is that you write your document once, in Halibut's
input format, and then the Halibut program processes it into several
output formats which all contain the same text. So, for example,
if you want your application to have a Windows help file, and you
also want the same documentation available in HTML on your web site,
Halibut can do that for you.

* Menu:

* Section 1.1:: Output formats supported by Halibut
* Section 1.2:: Features supported by Halibut

File: halibut.info,  Node: Section 1.1,  Prev: Chapter 1,  Up: Chapter 1,  Next: Section 1.2

Section 1.1: Output formats supported by Halibut
------------------------------------------------

Currently Halibut supports the following output formats:

 -  Plain ASCII text.

 -  HTML.

 -  Unix man page format.

 -  GNU Info format.

 -  PDF.

 -  PostScript.

 -  Windows HTML Help (.CHM).

 -  Old-style Windows Help (.HLP).


File: halibut.info,  Node: Section 1.2,  Prev: Section 1.1,  Up: Chapter 1,  Next: Chapter 2

Section 1.2: Features supported by Halibut
------------------------------------------

Here's a list of Halibut's notable features.

 -  Halibut automatically assigns sequential numbers to your chapters,
    sections and subsections, and keeps track of them for you. You
    supply a _keyword_ for each section, and then you can generate
    cross-references to that section using the keyword, and Halibut
    will substitute the correct section number. Also, in any output
    format where it makes sense, the cross-references will be
    hyperlinks to that section of the document.

 -  Halibut has some support for Unicode: you can include arbitrary
    Unicode characters in your document, and specify fallback text in
    case any output format doesn't support that character.

 -  Halibut's indexing support is comprehensive and carefully
    designed. It's easy to use in the simple case, but has powerful
    features that should make it possible to maintain a high-quality
    and useful index.


File: halibut.info,  Node: Chapter 2,  Prev: Section 1.2,  Up: Top,  Next: Section 2.1

Chapter 2: Running Halibut
==========================

In the simplest case, running Halibut is very easy. You provide a set
of input files on its command line, and it produces a set of output
files.

  $ halibut intro.but gettingstarted.but reference.but index.but

This will generate a large set of output files:

 -  `output.txt' will be a plain text version of the input document.

 -  `output.chm' will be a Windows HTML Help version of the same
    thing. (Note that to do this Halibut does not require any external
    software such as a Help compiler. It _directly_ generates Windows
    HTML Help files, and therefore it doesn't need to be run on
    Windows to do so: it can generate them even when run from an
    automated script on a Unix machine.)

 -  `output.hlp' and `output.cnt' will be an old-style Windows Help
    version of the same thing. (Most of the text is in `output.hlp';
    `output.cnt' contains additional contents data used by the Windows
    help topic selector. If you lose the latter, the former should
    still be usable, but it will look less modern.)

 -  `output.1' will be a Unix man page.

 -  The set of files `*.html' will contain an HTML version of the
    document. If you have configured Halibut to generate more than
    one HTML file (the default), then the file `Contents.html' will
    be the topmost one that users should be directed to initially. If
    you have configured Halibut to generate a single file, it will be
    called `Manual.html'.

 -  `output.info', and some additional files `output.info-1',
    `output.info-2' etc., will be files suitable for use with GNU
    `info'.

 -  `output.pdf' will be a printable PDF manual.

 -  `output.ps' will be a printable PostScript manual.

* Menu:

* Section 2.1:: Command-line options

File: halibut.info,  Node: Section 2.1,  Prev: Chapter 2,  Up: Chapter 2,  Next: Chapter 3

Section 2.1: Command-line options
---------------------------------

Halibut supports command-line options in case you don't want to use
all of Halibut's output formats, or you want to configure the names of
your output files, or you want to supply additional configuration on
the command line. The supported options are listed here.

Firstly, there are options which indicate which of the output formats
you want Halibut to generate:

--text[=_filename_]

    Specifies that you want to generate plain text output. You can
    optionally specify a file name (e.g. `--text=myfile.txt'), in
    which case Halibut will change the name of the output file as
    well.

--html[=_filename_]

    Specifies that you want to generate HTML output. You can
    optionally specify a file name (e.g. `--html=myfile.html'), in
    which case Halibut will change the name of the output file as
    well. Specifying a file name here will also cause the HTML to
    be output in _only_ one file, instead of the usual behaviour of
    producing multiple files with links between them. If you want to
    produce multiple files and configure their names, you will need
    to use the more complete file name configuration directives given
    in *Note Section 4.2.1:: (although you may want to do so on the
    command line, using the `-C' option).

--xhtml[=_filename_]

    Synonym for `--html'.

--chm[=_filename_]

    Specifies that you want to generate Windows HTML Help output. You
    can optionally specify a file name (e.g. `--chm=myfile.chm'), in
    which case Halibut will change the name of the output file as
    well.

--winhelp[=_filename_]

    Specifies that you want to generate old-style Windows
    Help output. You can optionally specify a file name (e.g.
    `--winhelp=myfile.hlp'), in which case Halibut will change the
    name of the output file as well.

    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.

--whlp[=_filename_]

    Synonym for `--winhelp'.

--hlp[=_filename_]

    Synonym for `--winhelp'.

--man[=_filename_]

    Specifies that you want to generate man page output. You can
    optionally specify a file name (e.g. `--man=myfile.5'), in which
    case Halibut will change the name of the output file as well.

--info[=_filename_]

    Specifies that you want to generate GNU `info' output. You can
    optionally specify a file name (e.g. `--info=myfile.info'), in
    which case Halibut will change the name of the output file as
    well.

    Unless the `info' output format is configured not to (see
    *Note Section 4.6::), Halibut will divide the `info' output into
    many small files. The extra files will have numeric suffixes on
    their names; so, for example, `output.info' might be accompanied
    by additional files `output.info-1', `output.info-2' and so on.

--pdf[=_filename_]

    Specifies that you want to generate PDF output. You can optionally
    specify a file name (e.g. `--pdf=myfile.pdf'), in which case
    Halibut will change the name of the output file as well.

--ps[=_filename_]

    Specifies that you want to generate PostScript output. You can
    optionally specify a file name (e.g. `--ps=myfile.ps'), in which
    case Halibut will change the name of the output file as well.

If you do not specify any of the above options, Halibut will simply
produce _all_ of its output formats.

Also, there is an option which allows you to specify an arbitrary
`\cfg' configuration directive (see *Note Section 3.6::):

-C_config-directive_:_value_[:_value_...]

    The text following `-C' is expected to be a colon-separated list
    of strings. (If you need a literal colon, you can escape it with
    a backslash: `\:'. If you need a literal _backslash_, you can do
    the same: `\\'.) These strings are used as the parts of a `\cfg'
    directive. So, for example, the option

      -Ctext-section-align:2:leftplus

    will translate into the configuration directive

      \cfg{text-section-align}{2}{leftplus}

    (Note that your shell may also take an interest in backslashes,
    particularly under Unix. You may find that the backslash with
    which you escape a colon must be doubled in order to make the
    shell pass it to Halibut at all, and to pass a doubled backslash
    to Halibut you might have to type four backslashes on your shell
    command line. This is not part of Halibut's own behaviour, and it
    cannot do anything about it.)

    Configuration directives created in this way take effect after
    all other input has been processed. (In most cases, this has the
    effect of overriding any other instances of the directive in the
    input.)

The options which set the output file names actually work by
implicitly generating these configuration directives. When you specify
`--text=myfile.txt', for example, Halibut treats it identically to
`--text -Ctext-filename:myfile.txt'. The Windows Help and man page
formats work similarly. HTML is slightly different, since it also
arranges for single-file output if you pass a filename to `--html';
so `--html=myfile.html' is equivalent to `--html -Chtml-single-
filename:myfile.html -Chtml-leaf-level:0'. (See *Note Chapter 4:: for
explanations of all these configuration directives.)

In addition to these, there are also a few other options:

--input-charset=_charset_

    Changes the default assumed character set for all input files from
    ASCII to something else. (-Cinput-charset cannot be used for this,
    as -C directives are processed after all other input, so wouldn't
    affect any files.)

    Any \cfg{input-charset} directives within input files override
    this option.

    See *Note Section 3.6:: for more information about the input
    character set.

--list-charsets

    List character sets known to Halibut.

--list-fonts

    List fonts known to Halibut, both those it intrinsically knows
    about and those found in its input files.

--help

    Print a brief help message and exit immediately. (Don't confuse
    this with `--winhelp'!)

--version

    Print information about Halibut's version number and exit
    immediately.

--licence

    Display Halibut's licence (see also *Note Appendix A::) and exit
    immediately.

--license

    US English alternative spelling of `--licence'.

--precise

    Report column numbers as well as line numbers when reporting
    errors in the Halibut input files.


File: halibut.info,  Node: Chapter 3,  Prev: Section 2.1,  Up: Top,  Next: Section 3.1

Chapter 3: Halibut input format
===============================

This chapter describes the format in which you should write documents
to be processed by Halibut.

* Menu:

* Section 3.1:: The basics
* Section 3.2:: Simple inline formatting commands
* Section 3.3:: Paragraph-level commands
* Section 3.4:: Creating a bibliography
* Section 3.5:: Creating an index
* Section 3.6:: Configuring Halibut
* Section 3.7:: Defining macros

File: halibut.info,  Node: Section 3.1,  Prev: Chapter 3,  Up: Chapter 3,  Next: Section 3.2

Section 3.1: The basics
-----------------------

Halibut's input files mostly look like ordinary ASCII text files; you
can edit them with any text editor you like.

Writing paragraphs of ordinary text is very simple: you just write
ordinary text in the ordinary way. You can wrap a paragraph across
more than one line using line breaks in the text file, and Halibut
will ignore this when it rewraps the paragraph for each output format.
To separate paragraphs, use a blank line (i.e. two consecutive line
breaks). For example, a fragment of Halibut input looking like this:

  This is a line of text.
  This is another line of text.
  
  This line is separated from the previous one by a blank line.

will produce two paragraphs looking like this:

  This is a line of text. This is another line of text.

  This line is separated from the previous one by a blank line.

The first two lines of the input have been merged together into a
single paragraph, and the line break in the input file was treated
identically to the spaces between the individual words.

Halibut is designed to have very few special characters. The only
printable characters in Halibut input which will not be treated
exactly literally in the output are the backslash (`\') and the braces
(`{' and `}'). If you do not use these characters, _everything_ else
you might type in normal ASCII text is perfectly safe. If you do need
to use any of those three characters in your document, you will have
to precede each one with a backslash. Hence, for example, you could
write

  This \\ is a backslash, and these are \{braces\}.

and Halibut would generate the text

  This \ is a backslash, and these are {braces}.

If you want to write your input file in a character set other than
ASCII, you can do so by using the `\cfg{input-charset}' command. See
*Note Section 3.6:: for details of this.


File: halibut.info,  Node: Section 3.2,  Prev: Section 3.1,  Up: Chapter 3,  Next: Section 3.2.1

Section 3.2: Simple inline formatting commands
----------------------------------------------

Halibut formatting commands all begin with a backslash, followed
by a word or character identifying the command. Some of them then
use braces to surround one or more pieces of text acted on by the
command. (In fact, the `\\', `\{' and `\}' sequences you met in
*Note Section 3.1:: are themselves formatting commands.)

This section describes some simple formatting commands you can use
in Halibut documents. The commands in this section are _inline_
commands, which means you can use them in the middle of a paragraph.
*Note Section 3.3:: describes some _paragraph_ commands, which affect
a whole paragraph at a time.

Many of these commands are followed by a pair of braces surrounding
some text. In all cases, it is perfectly safe to have a line break (in
the input file) within those braces; Halibut will treat that exactly
the same as a space. For example, these two paragraphs will be treated
identically:

  Here is some \e{emphasised
  text}.
  
  Here is some \e{emphasised text}.

* Menu:

* Section 3.2.1:: `\e' and `\s': Emphasising text
* Section 3.2.2:: `\c' and `\cw': Displaying computer code inline
* Section 3.2.3:: `\q': Quotation marks
* Section 3.2.4:: `\-' and `\_': Non-breaking hyphens and spaces
* Section 3.2.5:: `\date': Automatic date generation
* Section 3.2.6:: `\W': WWW hyperlinks
* Section 3.2.7:: `\u': Specifying arbitrary Unicode characters
* Section 3.2.8:: `\k' and `\K': Cross-references to other sections
* Section 3.2.9:: `\#': Inline comments

File: halibut.info,  Node: Section 3.2.1,  Prev: Section 3.2,  Up: Section 3.2,  Next: Section 3.2.2

Section 3.2.1: `\e' and `\s': Emphasising text
..............................................

Possibly the most obvious piece of formatting you might want to use
in a document is _emphasis_. To emphasise text, you use the `\e'
command, and follow it up with the text to be emphasised in braces.
For example, the first sentence in this paragraph was generated using
the Halibut input

  Possibly the most obvious piece of formatting you might want
  to use in a document is \e{emphasis}.

A second form of emphasis is supported, called *strong* text. You can
use the `\s' command for this type of emphasis. Typically, in output
formats, `\e' will give italics, and `\s' will give bold.


File: halibut.info,  Node: Section 3.2.2,  Prev: Section 3.2.1,  Up: Section 3.2,  Next: Section 3.2.3

Section 3.2.2: `\c' and `\cw': Displaying computer code inline
..............................................................

Halibut was primarily designed to produce software manuals. It can be
used for other types of document as well, but software manuals are its
speciality.

In software manuals, you often want to format text in a way that
indicates that it is something you might see displayed verbatim on a
computer screen. In printed manuals, this is typically done by setting
that text in a font which is obviously fixed-width. This provides a
visual cue that the text being displayed is code, and it also ensures
that punctuation marks are clearly separated and shown individually
(so that a user can copy the text accurately and conveniently).

Halibut provides _two_ commands for this, which are subtly different.
The names of those commands are `\c' (`code') and `\cw' (`weak code').
You use them just like `\e' and `\s', by following them with some text
in braces. For example, this...

  This sentence contains some \c{code} and some \cw{weak code}.

... produces this:

  This sentence contains some `code' and some weak code.

The distinction between code and weak code is mainly important when
producing plain text output. Plain text output is typically viewed in
a fixed-width font, so there is no need (and no way) to change font in
order to make the order of punctuation marks clear. However, marking
text as code is also _sometimes_ done to provide a visual distinction
between it and the text around it, so that the reader knows where the
literal computer text starts and stops; and in plain text, this cannot
be done by changing font, so there needs to be an alternative way.

So in the plain text output format, things marked as code (`\c') will
be surrounded by quote marks, so that it's obvious where they start
and finish. Things marked as weak code (`\cw') will not look any
different from normal text.

I recommend using weak code for any application where it is _obvious_
that the text is literal computer input or output. For example, if the
text is capitalised, that's usually good enough. If I talk about the
Pentium's EAX and EDX registers, for example, you don't need quotes
to notice that those are special; so I would write that in Halibut as
`the Pentium's \cw{EAX} and \cw{EDX} registers'. But if I'm talking
about the Unix command `man', which is an ordinary English word in
its own right, a reader might be slightly confused if it appeared
in the middle of a sentence undecorated; so I would write that as
`the Unix command \c{man}'.

In summary:

 -  `\c' means `this text _must_ be visually distinct from the text
    around it'. Halibut's various output formats will do this by
    changing the font if possible, or by using quotes if not.

 -  `\cw' means `it would be nice to display this text in a fixed-
    width font if possible, but it's not essential'.

In really extreme cases, you might want Halibut to use quotation
marks even in output formats which can change font. In
*Note Section 3.2.5::, for example, I mention the special formatting
command `\.'. If that appeared at the end of a sentence _without_ the
quotes, then the two adjacent full stops would look pretty strange
even if they were obviously in different fonts.

For this, Halibut supports the `\cq' command, which is exactly
equivalent to using `\q' to provide quotes and then using `\cw' inside
the quotes. So in the paragraph above, for example, I wrote

  the special formatting command \cq{\\.}.

and I could equivalently have written

  the special formatting command \q{\cw{\\.}}.

There is a separate mechanism for displaying computer code in an
entire paragraph; see *Note Section 3.3.1:: for that one.


File: halibut.info,  Node: Section 3.2.3,  Prev: Section 3.2.2,  Up: Section 3.2,  Next: Section 3.2.4

Section 3.2.3: `\q': Quotation marks
....................................

Halibut's various output formats don't all use the same conventions
for displaying text in ordinary quotation marks (`like these'). Some
output formats have access to proper matched quote characters, whereas
others are restricted to using plain ASCII. Therefore, it is not ideal
to use the ordinary ASCII double quote character in your document
(although you can if you like).

Halibut provides the formatting command `\q' to indicate quoted text.
If you write

  Here is some \q{text in quotes}.

then Halibut will print

  Here is some `text in quotes'.

and in every output format Halibut generates, it will choose the best
quote characters available to it in that format. (The quote characters
to use can be configured with the `\cfg' command.)

You can still use the ordinary quote characters of your choice
if you prefer; or you could even use the `\u' command (see
*Note Section 3.2.7::) to generate Unicode matched quotes (single or
double) in a way which will automatically fall back to the normal
ASCII one if they aren't available. But I recommend using the built-in
`\q' command in most cases, because it's simple and does the best it
can everywhere.

If you're using the `\c' or `\cw' commands to display literal computer
code, you will probably want to use literal ASCII quote characters,
because it is likely to matter precisely which quote character you
use. In fact, Halibut actually _disallows_ the use of `\q' within
either of `\c' and `\cw', since this simplifies some of the output
formats.


File: halibut.info,  Node: Section 3.2.4,  Prev: Section 3.2.3,  Up: Section 3.2,  Next: Section 3.2.5

Section 3.2.4: `\-' and `\_': Non-breaking hyphens and spaces
.............................................................

If you use an ordinary hyphen in the middle of a word (such as `built-
in'), Halibut's output formats will feel free to break a line after
that hyphen when wrapping paragraphs. This is fine for a word like
`built-in', but if you were displaying some literal computer code such
as the Emacs command `M-x psychoanalyze-pinhead', you might prefer to
see the whole hyphenated word treated as an unbreakable block. In some
cases, you might even want to prevent the _space_ in that command from
becoming a line break.

For these purposes, Halibut provides the commands `\-' and `\_', which
generate a non-breaking hyphen and a non-breaking space respectively.
So the above Emacs command might be written as

  the Emacs command \c{M\-x\_psychoanalyze\-pinhead}

Unfortunately, some of Halibut's output formats do not support non-
breaking hyphens, and others don't support _breaking_ hyphens! So
Halibut cannot promise to honour these commands in all situations. All
it can do is make a best effort.


File: halibut.info,  Node: Section 3.2.5,  Prev: Section 3.2.4,  Up: Section 3.2,  Next: Section 3.2.6

Section 3.2.5: `\date': Automatic date generation
.................................................

Sometimes you might want your document to give an up-to-date
indication of the date on which it was run through Halibut.

Halibut supplies the `\date' command to do this. In its simplest form,
you simply say

  This document was generated on \date.

and Halibut generates something like

  This document was generated on Mon Jan  5 02:48:23 2026.

You can follow the `\date' command directly with punctuation (as
in this example, where it is immediately followed by a full stop),
but if you try to follow it with an alphabetic or numeric character
(such as writing `\dateZ') then Halibut will assume you are trying
to invoke the name of a macro command you have defined yourself, and
will complain if no such command exists. To get round this you can use
the special `\.' do-nothing command. See *Note Section 3.7:: for more
about general Halibut command syntax and `\.'.

If you would prefer the date to be generated in a specific format, you
can follow the `\date' command with a format specification in braces.
The format specification will be run through the standard C function
`strftime', so any format acceptable to that function is acceptable
here as well. I won't document the format here, because the details
vary from computer to computer (although there is a standard core
which should be supported everywhere). You should look at your local
system's manual for `strftime' for details.

Here's an example which generates the date in the international
standard ISO 8601 format:

  This document was generated on \date{%Y-%m-%d %H:%M:%S}.

And here's some sample output from that command:

  This document was generated on 2026-01-05 02:48:23.


File: halibut.info,  Node: Section 3.2.6,  Prev: Section 3.2.5,  Up: Section 3.2,  Next: Section 3.2.7

Section 3.2.6: `\W': WWW hyperlinks
...................................

Since one of Halibut's output formats is HTML, it's obviously useful
to be able to provide links to arbitrary web sites in a Halibut
document.

This is done using the `\W' command. `\W' expects to be followed by
_two_ sets of braces. In the first set of braces you put a URL; in the
second set you put the text which should be a hyperlink. For example,
you might write

  Try searching on \W{http://www.google.com/}{Google}.

and Halibut would generate

  Try searching on Google.

Note that hyperlinks, like the non-breaking commands discussed in
*Note Section 3.2.4::, are _discretionary_: if an output format does
not support them then they will just be left out completely. So unless
you're _only_ intending to use the HTML output format, you should
avoid storing vital content in the URL part of a `\W' command. The
Google example above is reasonable (because most users are likely
to be able to find Google for themselves even without a convenient
hyperlink leading straight there), but if you really need to direct
users to a specific web site, you will need to give the URL in
actual displayed text (probably displayed as code as well). However,
there's nothing to stop you making it a hyperlink _as well_ for the
convenience of HTML readers.

The `\W' command supports a piece of extra syntax to make this
convenient for you. You can specify `\c' or `\cw' _between_ the first
and second pairs of braces. For example, you might write

  Google is at \W{http://www.google.com/}\cw{www.google.com}.

and Halibut would produce

  Google is at www.google.com.

If you want the link text to be an index term as well, you can also
specify `\i' or `\ii'; this has to come before `\c' or `\cw' if both
are present. (See *Note Section 3.5:: for more about indexing.)


File: halibut.info,  Node: Section 3.2.7,  Prev: Section 3.2.6,  Up: Section 3.2,  Next: Section 3.2.8

Section 3.2.7: `\u': Specifying arbitrary Unicode characters
............................................................

Halibut has extensive support for Unicode and character set
conversion. You can specify any (reasonably well known) character set
for your input document, and Halibut will convert it all to Unicode as
it reads it in. See *Note Section 3.6:: for more details of this.

If you need to specify a Unicode character in your input document
which is not supported by the input character set you have chosen, you
can use the `\u' command to do this. `\u' expects to be followed by
a sequence of hex digits; so that `\u0041', for example, denotes the
Unicode character 0x0041, which is the capital letter A.

If a Unicode character specified in this way is not supported in
a particular _output_ format, you probably don't just want it to
be omitted. So you can put a pair of braces after the `\u' command
containing fallback text. For example, to specify an amount of money
in euros, you might write this:

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

Halibut will render that as a Euro sign _if available_, and the text
`EUR ' if not. In the output format you're currently reading in, the
above input generates this:

  This is likely to cost EUR 2500 at least.

If you read it in other formats, you may see different results.


File: halibut.info,  Node: Section 3.2.8,  Prev: Section 3.2.7,  Up: Section 3.2,  Next: Section 3.2.9

Section 3.2.8: `\k' and `\K': Cross-references to other sections
................................................................

*Note Section 1.2:: mentions that Halibut numbers the sections of your
document automatically, and can generate cross-references to them on
request. `\k' and `\K' are the commands used to generate those cross-
references.

To use one of these commands, you simply follow it with a pair of
braces containing the keyword for the section in question. For
example, you might write something like

  \K{input-xref} expands on \k{intro-features}.

and Halibut would generate something like

  *Note Section 3.2.8:: expands on *Note Section 1.2::.

The keywords `input-xref' and `intro-features' are section keywords
used in this manual itself. In your own document, you would have
supplied a keyword for each one of your own sections, and you would
provide your own keywords for the `\k' command to work on.

The difference between `\k' and `\K' is simply that `\K' starts the
cross-reference text with a capital letter; so you would use `\K' at
the beginning of a sentence, and `\k' everywhere else.

In output formats which permit it, cross-references act as hyperlinks,
so that clicking the mouse on a cross-reference takes you straight to
the referenced section.

The `\k' commands are also used for referring to entries in a
bibliography (see *Note Section 3.4:: for more about bibliographies),
and can also be used for referring to an element of a numbered list
by its number (see *Note Section 3.3.2.2:: for more about numbered
lists).

See *Note Section 3.3.5:: for more about chapters and sections.


File: halibut.info,  Node: Section 3.2.9,  Prev: Section 3.2.8,  Up: Section 3.2,  Next: Section 3.3

Section 3.2.9: `\#': Inline comments
....................................

If you want to include comments in your Halibut input, to be seen when
reading it directly but not copied into the output text, then you can
use `\#' to do this. If you follow `\#' with text in braces, that text
will be ignored by Halibut.

For example, you might write

  The typical behaviour of an antelope \#{do I mean
  gazelle?} is...

and Halibut will simply leave out the aside about gazelles, and will
generate nothing but

  The typical behaviour of an antelope is...

This command will respect nested braces, so you can use it to comment
out sections of Halibut markup:

  This function is \#{very, \e{very}} important.

In this example, the comment lasts until the final closing brace (so
that the whole `very, _very_' section is commented out).

The `\#' command can also be used to produce a whole-paragraph
comment; see *Note Section 3.3.7:: for details of that.


File: halibut.info,  Node: Section 3.3,  Prev: Section 3.2.9,  Up: Chapter 3,  Next: Section 3.3.1

Section 3.3: Paragraph-level commands
-------------------------------------

This section describes Halibut commands which affect an entire
paragraph, or sometimes even _more_ than one paragraph, at a time.

* Menu:

* Section 3.3.1:: `\c': Displaying whole paragraphs of computer code
* Section 3.3.2:: `\b', `\n', `\dt', `\dd', `\lcont': Lists
* Section 3.3.3:: `\rule': Horizontal rules
* Section 3.3.4:: `\quote': Indenting multiple paragraphs as a long quotation
* Section 3.3.5:: `\C', `\H', `\S', `\A', `\U': Chapter and section headings
* Section 3.3.6:: `\copyright', `\title', `\versionid': Miscellaneous blurb commands
* Section 3.3.7:: `\#': Whole-paragraph comments

File: halibut.info,  Node: Section 3.3.1,  Prev: Section 3.3,  Up: Section 3.3,  Next: Section 3.3.2

Section 3.3.1: `\c': Displaying whole paragraphs of computer code
.................................................................

*Note Section 3.2.2:: describes a mechanism for displaying computer
code in the middle of a paragraph, a few words at a time.

However, this is often not enough. Often, in a computer manual, you
really want to show several lines of code in a display paragraph.

This is also done using the `\c' command, in a slightly different way.
Instead of using it in the middle of a paragraph followed by braces,
you can use it at the start of each line of a paragraph. For example,
you could write

  \c #include <stdio.h>
  \c
  \c int main(int argc, char **argv) {
  \c     printf("hello, world\n");
  \c     return 0;
  \c }

and Halibut would generate

    #include <stdio.h>
    
    int main(int argc, char **argv) {
        printf("hello, world\n");
        return 0;
    }

Note that the above paragraph makes use of a backslash and a pair of
braces, and does _not_ need to escape them in the way described in
*Note Section 3.1::. This is because code paragraphs formatted in this
way are a special case; the intention is that you can just copy and
paste a lump of code out of your program, put `\c ' at the start of
every line, and simply _not have to worry_ about the details - you
don't have to go through the whole block looking for characters to
escape.

Since a backslash inside a code paragraph generates a literal
backslash, this means you cannot use any other Halibut formatting
commands inside a code paragraph. In particular, if you want to
emphasise or strengthen a particular word in the paragraph, you can't
do that using `\e' or `\s' (*Note Section 3.2.1::) in the normal way.

Therefore, Halibut provides an alternative means of emphasis in code
paragraphs. Each line beginning with `\c' can optionally be followed
by a single line beginning with `\e', indicating the emphasis in
that line. The emphasis line contains the letters `b' and `i' (for
`bold' and `italic', although some output formats might render `i' as
underlining instead of italics), positioned to line up under the parts
of the text that you want emphasised.

For example, if you wanted to do syntax highlighting on the above
C code by highlighting the preprocessor command in italic and the
keywords in bold, you might do it like this:

  \c #include <stdio.h>
  \e iiiiiiiiiiiiiiiiii
  \c
  \c int main(int argc, char **argv) {
  \e bbb      bbb       bbbb
  \c     printf("hello, world\n");
  \c     return 0;
  \e     bbbbbb
  \c }

and Halibut would generate:

    #include <stdio.h>
    
    int main(int argc, char **argv) {
        printf("hello, world\n");
        return 0;
    }

Note that not every `\c' line has to be followed by a `\e' line;
they're optional.

Also, note that highlighting within a code paragraph is
_discretionary_. Not all of Halibut's output formats can support it
(plain text, in particular, has no sensible way to do it). Unless you
know you are using a restricted range of output formats, you should
use highlighting in code paragraphs _only_ as a visual aid, and not
rely on it to convey any vital semantic content.


File: halibut.info,  Node: Section 3.3.2,  Prev: Section 3.3.1,  Up: Section 3.3,  Next: Section 3.3.2.1

Section 3.3.2: `\b', `\n', `\dt', `\dd', `\lcont': Lists
........................................................

Halibut supports bulletted lists, numbered lists and description
lists.

* Menu:

* Section 3.3.2.1:: `\b': Bulletted lists
* Section 3.3.2.2:: `\n': Numbered lists
* Section 3.3.2.3:: `\dt' and `\dd': Description lists
* Section 3.3.2.4:: Continuing list items into further paragraphs

File: halibut.info,  Node: Section 3.3.2.1,  Prev: Section 3.3.2,  Up: Section 3.3.2,  Next: Section 3.3.2.2

Section 3.3.2.1: `\b': Bulletted lists
......................................

To create a bulletted list, you simply prefix each paragraph
describing a bullet point with the command `\b'. For example, this
Halibut input:

  Here's a list:
  
  \b One.
  
  \b Two.
  
  \b Three.

would produce this Halibut output:

  Here's a list:

   -  One.

   -  Two.

   -  Three.


File: halibut.info,  Node: Section 3.3.2.2,  Prev: Section 3.3.2.1,  Up: Section 3.3.2,  Next: Section 3.3.2.3

Section 3.3.2.2: `\n': Numbered lists
.....................................

Numbered lists are just as simple: instead of `\b', you use `\n',
and Halibut takes care of getting the numbering right for you. For
example:

  Here's a list:
  
  \n One.
  
  \n Two.
  
  \n Three.

This produces the Halibut output:

  Here's a list:

   1. One.

   2. Two.

   3. Three.

The disadvantage of having Halibut sort out the list numbering for you
is that if you need to refer to a list item by its number, you can't
reliably know the number in advance (because if you later add another
item at the start of the list, the numbers will all change). To get
round this, Halibut allows an optional keyword in braces after the
`\n' command. This keyword can then be referenced using the `\k' or
`\K' command (see *Note Section 3.2.8::) to provide the number of the
list item. For example:

  Here's a list:
  
  \n One.
  
  \n{this-one} Two.
  
  \n Three.
  
  \n Now go back to step \k{this-one}.

This produces the following output:

  Here's a list:

   1. One.

   2. Two.

   3. Three.

   4. Now go back to step 2.

The keyword you supply after `\n' is allowed to contain escaped
special characters (`\\', `\{' and `\}'), but should not contain any
other Halibut markup. It is intended to be a word or two of ordinary
text. (This also applies to keywords used in other commands, such as
`\B' and `\C').


File: halibut.info,  Node: Section 3.3.2.3,  Prev: Section 3.3.2.2,  Up: Section 3.3.2,  Next: Section 3.3.2.4

Section 3.3.2.3: `\dt' and `\dd': Description lists
...................................................

To write a description list, you prefix alternate paragraphs with
the `\dt' (`described thing') and `\dd' (description) commands. For
example:

  \dt Pelican
  
  \dd This is a large bird with a big beak.
  
  \dt Panda
  
  \dd This isn't.

This produces the following output:

  Pelican

      This is a large bird with a big beak.

  Panda

      This isn't.

If you really want to, you are allowed to use `\dt' and `\dd'
without strictly interleaving them (multiple consecutive `\dt's or
consecutive `\dd's, or a description list starting with `\dd' or
ending with `\dt'). This is probably most useful if you are listing
a sequence of things with `\dt', but only some of them actually need
`\dd' descriptions. You should _not_ use multiple consecutive `\dd's
to provide a multi-paragraph definition of something; that's what
`\lcont' is for, as explained in *Note Section 3.3.2.4::.


File: halibut.info,  Node: Section 3.3.2.4,  Prev: Section 3.3.2.3,  Up: Section 3.3.2,  Next: Section 3.3.3

Section 3.3.2.4: Continuing list items into further paragraphs
..............................................................

All three of the above list types assume that each list item is a
single paragraph. For a short, snappy list in which each item is
likely to be only one or two words, this is perfectly sufficient; but
occasionally you will find you want to include several paragraphs in
a single list item, or even to nest other types of paragraph (such as
code paragraphs, or other lists) inside a list item.

To do this, you use the `\lcont' command. This is a command which can
span _multiple_ paragraphs.

After the first paragraph of a list item, include the text `\lcont{'.
This indicates that the subsequent paragraph(s) are a _continuation_
of the list item that has just been seen. So you can include further
paragraphs, and eventually include a closing brace `}' to finish the
list continuation. After that, you can either continue adding other
items to the original list, or stop immediately and return to writing
normal paragraphs of text.

Here's a (long) example.

  Here's a list:
  
  \n One. This item is followed by a code paragraph:
  
  \lcont{
  
  \c code
  \c paragraph
  
  }
  
  \n Two. Now when I say \q{two}, I mean:
  
  \lcont{
  
  \n Two, part one.
  
  \n Two, part two.
  
  \n Two, part three.
  
  }
  
  \n Three.

The output produced by this fragment is:

  Here's a list:

   1. One. This item is followed by a code paragraph:

        code
        paragraph

   2. Two. Now when I say `two', I mean:

       1. Two, part one.

       2. Two, part two.

       3. Two, part three.

   3. Three.

This syntax might seem a little bit inconvenient, and perhaps counter-
intuitive: you might expect the enclosing braces to have to go around
the _whole_ list item, rather than everything except the first
paragraph.

`\lcont' is a recent addition to the Halibut input language;
previously, _all_ lists were required to use no more than one
paragraph per list item. So it's certainly true that this feature
looks like an afterthought because it _is_ an afterthought, and it's
possible that if I'd been designing the language from scratch with
multiple-paragraph list items in mind, I would have made it look
different.

However, the advantage of doing it this way is that no enclosing
braces are required in the _common_ case: simple lists with only one
paragraph per item are really, really easy to write. So I'm not too
unhappy with the way it turned out; it obeys the doctrine of making
simple things simple, and difficult things possible.

Note that `\lcont' can only be used on `\b', `\n' and `\dd'
paragraphs; it cannot be used on `\dt'.


File: halibut.info,  Node: Section 3.3.3,  Prev: Section 3.3.2.4,  Up: Section 3.3,  Next: Section 3.3.4

Section 3.3.3: `\rule': Horizontal rules
........................................

The command `\rule', appearing on its own as a paragraph, will cause a
horizontal rule to be drawn, like this:

  Some text.
  
  \rule
  
  Some more text.

This produces the following output:

  Some text.

  --------------------------------------------------------------------

  Some more text.


File: halibut.info,  Node: Section 3.3.4,  Prev: Section 3.3.3,  Up: Section 3.3,  Next: Section 3.3.5

Section 3.3.4: `\quote': Indenting multiple paragraphs as a long
................................................................
quotation
.........

Quoting verbatim text using a code paragraph (*Note Section 3.3.1::)
is not always sufficient for your quoting needs. Sometimes you need to
quote some normally formatted text, possibly in multiple paragraphs.
This is similar to HTML's <BLOCKQUOTE> command.

To do this, you can use the `\quote' command. Like `\lcont', this is a
command which expects to enclose at least one paragraph and possibly
more. Simply write `\quote{' at the beginning of your quoted section,
and `}' at the end, and the paragraphs in between will be formatted to
indicate that they are a quotation.

(This very manual, in fact, uses this feature a lot: all of the
examples of Halibut input followed by Halibut output have the output
quoted using `\quote'.)

Here's some example Halibut input:

  In \q{Through the Looking Glass}, Lewis Carroll wrote:
  
  \quote{
  
  \q{The question is,} said Alice, \q{whether you \e{can} make
  words mean so many different things.}
  
  \q{The question is,} said Humpty Dumpty, \q{who is to be
  master - that's all.}
  
  }
  
  So now you know.

The output generated by this is:

  In `Through the Looking Glass', Lewis Carroll wrote:

    `The question is,' said Alice, `whether you _can_ make words mean
    so many different things.'

    `The question is,' said Humpty Dumpty, `who is to be master -
    that's all.'

  So now you know.


File: halibut.info,  Node: Section 3.3.5,  Prev: Section 3.3.4,  Up: Section 3.3,  Next: Section 3.3.6

Section 3.3.5: `\C', `\H', `\S', `\A', `\U': Chapter and section
................................................................
headings
........

*Note Section 1.2:: mentions that Halibut numbers the sections of your
document automatically, and can generate cross-references to them on
request; *Note Section 3.2.8:: describes the `\k' and `\K' commands
used to generate the cross-references. This section describes the
commands used to set up the sections in the first place.

A paragraph beginning with the `\C' command defines a chapter heading.
The `\C' command expects to be followed by a pair of braces containing
a keyword for the chapter; this keyword can then be used with the `\k'
and `\K' commands to generate cross-references to the chapter. After
the closing brace, the rest of the paragraph is used as the displayed
chapter title. So the heading for the current chapter of this manual,
for example, is written as

  \C{input} Halibut input format

and this allows me to use the command `\k{input}' to generate a cross-
reference to that chapter somewhere else.

The keyword you supply after one of these commands is allowed to
contain escaped special characters (`\\', `\{' and `\}'), but should
not contain any other Halibut markup. It is intended to be a word or
two of ordinary text. (This also applies to keywords used in other
commands, such as `\B' and `\n').

The next level down from `\C' is `\H', for `heading'. This is used
in exactly the same way as `\C', but section headings defined with
`\H' are considered to be part of a containing chapter, and will
be numbered with a pair of numbers. After `\H' comes `\S', and if
necessary you can then move on to `\S2', `\S3' and so on.

For example, here's a sequence of heading commands. Normally these
commands would be separated at least by blank lines (because each is a
separate paragraph), and probably also by body text; but for the sake
of brevity, both of those have been left out in this example.

  \C{foo} Using Foo
  \H{foo-intro} Introduction to Foo
  \H{foo-running} Running the Foo program
  \S{foo-inter} Running Foo interactively
  \S{foo-batch} Running Foo in batch mode
  \H{foo-trouble} Troubleshooting Foo
  \C{bar} Using Bar instead of Foo

This would define two chapters with keywords `foo' and `bar', which
would end up being called Chapter 1 and Chapter 2 (unless there were
other chapters before them). The sections `foo-intro', `foo-running'
and `foo-trouble' would be referred to as Section 1.1, Section 1.2 and
Section 1.3 respectively; the subsections `foo-inter' and `foo-batch'
would be Section 1.2.1 and Section 1.2.2. If there had been a `\S2'
command within one of those, it would have been something like Section
1.2.1.1.

If you don't like the switch from `\H' to `\S', you can use `\S1'
as a synonym for `\S' and `\S0' as a synonym for `\H'. Chapters are
still designated with `\C', because they need to be distinguished
from other types of chapter such as appendices. (Personally, I like
the `\C',`\H',`\S' notation because it encourages me to think of my
document as a hard disk :-)

You can define an appendix by using `\A' in place of `\C'. This is no
different from a chapter except that it's given a letter instead of a
number, and cross-references to it will say `Appendix A' instead of
`Chapter 9'. Subsections of an appendix will be numbered `A.1', `A.2',
`A.2.1' and so on.

If you want a particular section to be referred to as something other
than a `chapter', `section' or `appendix', you can include a second
pair of braces after the keyword. For example, if you're writing a
FAQ chapter and you want cross-references between questions to refer
to `question 1.2.3' instead of `section 1.2.3', you can write each
section heading as

  \S{question-about-fish}{Question} What about fish?

(The word `Question' should be given with an initial capital letter.
Halibut will lower-case it when you refer to it using `\k', and will
leave it alone if you use `\K'.)

This technique allows you to change the designation of _particular_
sections. To make an overall change in what _every_ section is called,
see *Note Section 3.6::.

Finally, the `\U' command defines an _unnumbered_ chapter.
These sometimes occur in books, for specialist purposes such as
`Bibliography' or `Acknowledgements'. `\U' does not expect a keyword
argument, because there is no sensible way to generate an automatic
cross-reference to such a chapter anyway.


File: halibut.info,  Node: Section 3.3.6,  Prev: Section 3.3.5,  Up: Section 3.3,  Next: Section 3.3.7

Section 3.3.6: `\copyright', `\title', `\versionid': Miscellaneous
..................................................................
blurb commands
..............

These three commands define a variety of special paragraph types. They
are all used in the same way: you put the command at the start of a
paragraph, and then just follow it with normal text, like this:

  \title My First Manual

The three special paragraph types are:

\title

    This defines the overall title of the entire document. This title
    is treated specially in some output formats (for example, it's
    used in a <TITLE> tag in the HTML output), so it needs a special
    paragraph type to point it out.

\copyright

    This command indicates that the paragraph attached to it contains
    a copyright statement for the document. This text is displayed
    inline where it appears, exactly like a normal paragraph; but in
    some output formats it is given additional special treatment.
    For example, Windows Help files have a standard slot in which to
    store a copyright notice, so that other software can display it
    prominently.

\versionid

    This command indicates that the paragraph contains a version
    identifier, such as those produced by CVS (of the form
    `$Id: thingy.but,v 1.6 2004/01/01 16:47:48 simon Exp $'). This
    text will be tucked away somewhere unobtrusive, so that anyone
    wanting to (for example) report errors to the document's author
    can pick out the version IDs and send them as part of the report,
    so that the author can tell at a glance which revision of the
    document is being discussed.


File: halibut.info,  Node: Section 3.3.7,  Prev: Section 3.3.6,  Up: Section 3.3,  Next: Section 3.4

Section 3.3.7: `\#': Whole-paragraph comments
.............................................

*Note Section 3.2.9:: describes the use of the `\#' command to put a
short comment in the middle of a paragraph.

If you need to use a _long_ comment, Halibut also allows you to
use `\#' without braces, to indicate that an entire paragraph is a
comment, like this:

  Here's a (fairly short) paragraph which will be displayed.
  
  \# Here's a comment paragraph which will not be displayed, no
  matter how long it goes on. All I needed to indicate this was
  the single \# at the start of the paragraph; I don't need one
  on every line or anything like that.
  
  Here's another displayed paragraph.

When run through Halibut, this produces the following output:

  Here's a (fairly short) paragraph which will be displayed.

  Here's another displayed paragraph.


File: halibut.info,  Node: Section 3.4,  Prev: Section 3.3.7,  Up: Chapter 3,  Next: Section 3.5

Section 3.4: Creating a bibliography
------------------------------------

If you need your document to refer to other documents (research
papers, books, websites, whatever), you might find a bibliography
feature useful.

You can define a bibliography entry using the `\B' command. This
looks very like the `\C' command and friends: it expects a keyword in
braces, followed by some text describing the document being referred
to. For example:

  \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
  Published by Paperjam & Notoner, 1993.

If this bibliography entry appears in the finished document, it will
look something like this:

  [1] `The Taming Of The Mongoose', by Fred Bloggs. Published by
  Paperjam & Notoner, 1993.

I say `if' above because not all bibliography entries defined using
the `\B' command will necessarily appear in the finished document.
They only appear if they are referred to by a `\k' command (see
*Note Section 3.2.8::). This allows you to (for example) maintain a
single Halibut source file with a centralised database of _all_ the
references you have ever needed in any of your writings, include
that file in every document you feed to Halibut, and have it only
produce the bibliography entries you actually need for each particular
document. (In fact, you might even want this centralised source file
to be created automatically by, say, a Perl script from BibTeX input,
so that you can share the same bibliography with users of other
formatting software.)

If you really want a bibliography entry to appear in the document even
though no text explicitly refers to it, you can do that using the
`\nocite' command:

  \nocite{freds-book}

Normally, each bibliography entry will be referred to (in citations
and in the bibliography itself) by a simple reference number, such as
[1]. If you would rather use an alternative reference notation, such
as [Fred1993], you can use the `\BR' (`Bibliography Rewrite') command
to specify your own reference format for a particular book:

  \BR{freds-book} [Fred1993]

The keyword you supply after `\B' is allowed to contain escaped
special characters (`\\', `\{' and `\}'), but should not contain any
other Halibut markup. It is intended to be a word or two of ordinary
text. (This also applies to keywords used in other commands, such as
`\n' and `\C').


File: halibut.info,  Node: Section 3.5,  Prev: Section 3.4,  Up: Chapter 3,  Next: Section 3.5.1

Section 3.5: Creating an index
------------------------------

Halibut contains a comprehensive indexing mechanism, which attempts to
be reasonably easy to use in the common case in spite of its power.

* Menu:

* Section 3.5.1:: Simple indexing
* Section 3.5.2:: Special cases of indexing
* Section 3.5.3:: Fine-tuning the index
* Section 3.5.4:: Indexing terms that differ only in case

File: halibut.info,  Node: Section 3.5.1,  Prev: Section 3.5,  Up: Section 3.5,  Next: Section 3.5.2

Section 3.5.1: Simple indexing
..............................

In normal usage, you should be able to add index terms to your
document simply by using the `\i' command to wrap one or two words at
a time. For example, if you write

  The \i{hippopotamus} is a particularly large animal.

then the index will contain an entry under `hippopotamus', pointing
to that sentence (or as close to that sentence as the output format
sensibly permits).

You can wrap more than one word in `\i' as well:

  We recommend using a \i{torque wrench} for this job.


File: halibut.info,  Node: Section 3.5.2,  Prev: Section 3.5.1,  Up: Section 3.5,  Next: Section 3.5.3

Section 3.5.2: Special cases of indexing
........................................

If you need to index a computer-related term, you can use the special
case `\i\c' (or `\i\cw' if you prefer):

  The \i\c{grep} command is what you want here.

This will cause the word `grep' to appear in code style, as if the
`\i' were not present and the input just said `\c{grep}'; the word
will also appear in code style in the actual index.

If you want to simultaneously index and emphasise a word, there's
another special case `\i\e' (and similarly `\i\s'):

  This is what we call a \i\e{paper jam}.

This will cause the words `paper jam' to be emphasised in the
document, but (unlike the behaviour of `\i\c') they will _not_ be
emphasised in the index. This different behaviour is based on an
expectation that most people indexing a word of computer code will
still want it to look like code in the index, whereas most people
indexing an emphasised word will _not_ want it emphasised in the
index.

(In fact, _no_ emphasis in the text inside `\i' will be preserved
in the index. If you really want a term in the index to appear
emphasised, you must say so explicitly using `\IM'; see
*Note Section 3.5.3::.)

Sometimes you might want to index a term which is not explicitly
mentioned, but which is highly relevant to the text and you think that
somebody looking up that term in the index might find it useful to be
directed here. To do this you can use the `\I' command, to create an
_invisible_ index tag:

  If your printer runs out of toner, \I{replacing toner
  cartridge}here is what to do:

This input will produce only the output `If your printer runs out of
toner, here is what to do'; but an index entry will show up under
`replacing toner cartridge', so that if a user thinks the obvious
place to start in the index is under R for `replacing', they will find
their way here with a minimum of fuss.

(It's worth noting that there is no functional difference between
`\i{foo}' and `\I{foo}foo'. The simple `\i' case is only a shorthand
for the latter.)

Finally, if you want to index a word at the start of a sentence, you
might very well not want it to show up with a capital letter in the
index. For this, Halibut provides the `\ii' command, for `index (case-
)insensitively'. You use it like this:

  \ii{Lions} are at the top of the food chain in this area.

This is equivalent to `\I{lions}Lions'; in other words, the text will
say `Lions', but it will show up in the index as `lions'. The text
inside `\ii' is converted entirely into lower case before being added
to the index data.


File: halibut.info,  Node: Section 3.5.3,  Prev: Section 3.5.2,  Up: Section 3.5,  Next: Section 3.5.4

Section 3.5.3: Fine-tuning the index
....................................

Halibut's index mechanism as described so far still has a few problems
left:

 -  In a reasonably large index, it's often difficult to predict which
    of several words a user will think of first when trying to look
    something up. For example, if they want to know how to replace
    a toner cartridge, they might look up `replacing' or they might
    look up `toner cartridge'. You probably don't really want to have
    to try to figure out which of those is more likely; instead, what
    you'd like is to be able to effortlessly index the same set of
    document locations under _both_ terms.

 -  Also, you may find you've indexed the same concept under multiple
    different index terms; for example, there might be several
    instances of `\i{frog}' and several of `\i{frogs}', so that you'd
    end up with two separate index entries for what really ought to be
    the same concept.

 -  You might well not want the word `grep' to appear in the index
    without explanation; you might prefer it to say something more
    verbose such as `grep command', so that a user encountering it in
    the index has some idea of what it is _without_ having to follow
    up the reference. However, you certainly don't want to have to
    write `\I{\cw{grep} command}\c{grep}' every time you want to add
    an index term for this! You wanted to write `\i\c{grep}' as shown
    in the previous section, and tidy it all up afterwards.

All of these problems can be cleaned up by the `\IM' (for `Index
Modification') command. `\IM' expects to be followed by one or more
pairs of braces containing index terms as seen in the document, and
then a piece of text (not in braces) describing how it should be shown
in the index.

So to rewrite the `grep' example above, you might do this:

  \IM{grep} \cw{grep} command

This will arrange that the set of places in the document where you
asked Halibut to index `grep' will be listed under `grep command'
rather than just under `grep'.

You can specify more than one index term in a `\IM' command; so to
merge the index terms `frog' and `frogs' into a single term, you might
do this:

  \IM{frog}{frogs} frog

This will arrange that the single index entry `frog' will list _all_
the places in the document where you asked Halibut to index either
`frog' or `frogs'.

You can use multiple `\IM' commands to replicate the same set of
document locations in more than one index entry. For example:

  \IM{replacing toner cartridge} replacing toner cartridge
  \IM{replacing toner cartridge} toner cartridge, replacing

This will arrange that every place in the document where you have
indexed `replacing toner cartridge' will be listed both there _and_
under `toner cartridge, replacing', so that no matter whether the user
looks under R or under T they will stil find their way to the same
parts of the document.

In this example, note that although the first `\IM' command _looks_
as if it's a tautology, it is still necessary, because otherwise
those document locations will _only_ be indexed under `toner
cartridge, replacing'. If you have _no_ explicit `\IM' commands for
a particular index term, then Halibut will assume a default one
(typically `\IM{foo} foo', although it might be `\IM{foo} \c{foo}' if
you originally indexed using `\i\c'); but as soon as you specify an
explicit `\IM', Halibut discards its default implicit one, and you
must then specify that one explicitly as well if you wanted to keep
it.


File: halibut.info,  Node: Section 3.5.4,  Prev: Section 3.5.3,  Up: Section 3.5,  Next: Section 3.6

Section 3.5.4: Indexing terms that differ only in case
......................................................

The _tags_ you use to define an index term (that is, the text in the
braces after `\i', `\I' and `\IM') are treated case-insensitively by
Halibut. So if, as in this manual itself, you need two index terms
that differ only in case, doing this will not work:

  The \i\c{\\c} command defines computer code.
  
  The \i\c{\\C} command defines a chapter.

Halibut will treat these terms as the same, and will fold the two sets
of references into one combined list (although it will warn you that
it is doing this). The idea is to ensure that people who forget to
use `\ii' find out about it rather than Halibut silently generating a
bad index; checking an index for errors is very hard work, so Halibut
tries to avoid errors in the first place as much as it can.

If you do come across this situation, you will need to define two
distinguishable index terms. What I did in this manual was something
like this:

  The \i\c{\\c} command defines computer code.
  
  The \I{\\C-upper}\c{\\C} command defines a chapter.
  
  \IM{\\C-upper} \c{\\C}

The effect of this will be two separate index entries, one reading
`\c' and the other reading `\C', pointing to the right places.

