Running Halibut

Previous | Contents | Index | Next

- Chapter 2: Running Halibut
  - 2.1 Command-line options

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

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