3 \C{running} Running Halibut
5 \I{running Halibut}In the simplest case, running Halibut is very
6 easy. You provide a set of input files on its \i{command line}, and
7 it produces a set of output files.
9 \c $ halibut intro.but gettingstarted.but reference.but index.but
10 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
12 This will generate a large set of \i{output files}:
14 \b \i\c{output.txt} will be a \i{plain text} version of the input
17 \b \i\c{output.hlp} and \i\c{output.cnt} will be a \i{Windows Help}
18 version of the same thing. (Most of the text is in \c{output.hlp};
19 \c{output.cnt} contains additional contents data used by the Windows
20 help topic selector. If you lose the latter, the former should still
21 be usable, but it will look less modern.)
24 Note that Halibut does not require any external software such as a
25 \i{Help compiler}. It \e{directly} generates Windows Help files, and
26 therefore it doesn't need to be run on Windows to do so: it can
27 generate them even when run from an automated script on a Unix
31 \b \c{output.1} will be a Unix \i{\cw{man} page}.
33 \b The set of files \c{*.html} will contain an \i{HTML} version of
34 the document. If you have configured Halibut to generate more than
35 one HTML file (the default), then the file \c{Contents.html} will be
36 the topmost one that users should be directed to initially. If you
37 have configured Halibut to generate a single file, it will be called
40 \b \c{output.info}, and some additional files \c{output.info-1},
41 \c{output.info-2} etc., will be files suitable for use with GNU
44 \b \c{output.ps} will be a printable PostScript manual.
46 \b \c{output.pdf} will be a printable PDF manual.
48 \H{running-options} \ii{Command-line options}
50 Halibut supports command-line options in case you don't want to use
51 all of Halibut's \i{output formats}, or you want to configure the
52 names of your \i{output files}, or you want to supply additional
53 configuration on the command line. The supported options are listed
56 Firstly, there are options which indicate which of the output
57 formats you want Halibut to generate:
59 \dt \i\cw{--text}[\cw{=}\e{filename}]
61 \dd Specifies that you want to generate plain text output. You can
62 optionally specify a file name (e.g. \c{--text=myfile.txt}), in
63 which case Halibut will change the name of the output file as well.
65 \dt \i\cw{--html}[\cw{=}\e{filename}]
67 \dd Specifies that you want to generate HTML output. You can
68 optionally specify a file name (e.g. \c{--html=myfile.html}), in
69 which case Halibut will change the name of the output file as well.
70 Specifying a file name here will also cause the HTML to be output in
71 \e{only} one file, instead of the usual behaviour of producing
72 multiple files with links between them. If you want to produce
73 multiple files and configure their names, you will need to use the
74 more complete file name configuration directives given in
75 \k{output-html-file} (although you may want to do so on the command
76 line, using the \c{-C} option).
78 \dt \i\cw{--xhtml}[\cw{=}\e{filename}]
80 \dd Synonym for \c{--html}.
82 \dt \i\cw{--winhelp}[\cw{=}\e{filename}]
84 \dd Specifies that you want to generate Windows Help output. You can
85 optionally specify a file name (e.g. \c{--winhelp=myfile.hlp}), in
86 which case Halibut will change the name of the output file as well.
90 Your output file name should end with \c{.hlp}; if it doesn't,
91 Halibut will append it. Halibut will also generate a contents file
92 (ending in \c{.cnt}) alongside the file name you specify.
96 \dt \i\cw{--whlp}[\cw{=}\e{filename}]
98 \dd Synonym for \c{--winhelp}.
100 \dt \i\cw{--hlp}[\cw{=}\e{filename}]
102 \dd Synonym for \c{--winhelp}.
104 \dt \i\cw{--man}[\cw{=}\e{filename}]
106 \dd Specifies that you want to generate \cw{man} page output. You
107 can optionally specify a file name (e.g. \c{--man=myfile.5}), in
108 which case Halibut will change the name of the output file as well.
110 \dt \i\cw{--info}[\cw{=}\e{filename}]
112 \dd Specifies that you want to generate GNU \c{info} output. You can
113 optionally specify a file name (e.g. \c{--info=myfile.info}), in
114 which case Halibut will change the name of the output file as well.
118 Unless the \c{info} output format is configured not to (see
119 \k{output-info}), Halibut will divide the \c{info} output into many
120 small files. The extra files will have numeric suffixes on their
121 names; so, for example, \c{output.info} might be accompanied by
122 additional files \c{output.info-1}, \c{output.info-2} and so on.
126 \dt \i\cw{--ps}[\cw{=}\e{filename}]
128 \dd Specifies that you want to generate PostScript output. You
129 can optionally specify a file name (e.g. \c{--ps=myfile.ps}), in
130 which case Halibut will change the name of the output file as well.
132 \dt \i\cw{--pdf}[\cw{=}\e{filename}]
134 \dd Specifies that you want to generate PDF output. You
135 can optionally specify a file name (e.g. \c{--pdf=myfile.pdf}), in
136 which case Halibut will change the name of the output file as well.
138 If you do not specify any of the above options, Halibut will simply
139 produce \e{all} of its output formats.
141 Also, there is an option which allows you to specify an arbitrary
142 \i\c{\\cfg} configuration directive (see \k{input-config}):
144 \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...]
146 \dd The text following \c{-C} is expected to be a colon-separated
147 list of strings. (If you need a literal colon, you can escape it
148 with a backslash: \c{\\:}. If you need a literal \e{backslash}, you
149 can do the same: \c{\\\\}.) These strings are used as the parts of a
150 \c{\\cfg} directive. So, for example, the option
154 \c -Ctext-section-align:2:leftplus
156 will translate into the configuration directive
158 \c \cfg{text-section-align}{2}{leftplus}
160 (Note that your shell may also take an interest in backslashes,
161 particularly under Unix. You may find that the backslash with which
162 you escape a colon must be doubled in order to make the shell pass
163 it to Halibut at all, and to pass a doubled backslash to Halibut you
164 might have to type four backslashes on your shell command line. This
165 is not part of Halibut's own behaviour, and it cannot do anything
168 Configuration directives created in this way take effect after all
169 other input has been processed. (In most cases, this has the effect of
170 overriding any other instances of the directive in the input.)
174 The options which set the output file names actually work by
175 implicitly generating these configuration directives. When you
176 specify \c{--text=myfile.txt}, for example, Halibut treats it
177 identically to \c{--text -Ctext-filename:myfile.txt}. The Windows
178 Help and man page formats work similarly. HTML is slightly
179 different, since it also arranges for single-file output if you pass
180 a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to
181 \c{--html -Chtml-single-filename:myfile.html -Chtml-leaf-level:0}.
182 (See \k{output} for explanations of all these configuration
185 In addition to these, there are also a few other options:
187 \dt \i\cw{--input-charset}\cw{=}\e{charset}
189 \dd Changes the default assumed \i{character set} for all input files from
190 ASCII to something else. (\cw{-Cinput-charset} cannot be used for
191 this, as \cw{-C} directives are processed after all other input, so
192 wouldn't affect any files.)
196 Any \cw{\\cfg\{input-charset\}} directives within input files override
199 See \k{input-config} for more information about the input character set.
203 \dt \I{character sets, enumerating}\i\cw{--list-charsets}
205 \dd List character sets known to Halibut.
209 \dd Print a brief help message and exit immediately. (Don't confuse
210 this with \c{--winhelp}!)
214 \dd Print information about Halibut's version number and exit
219 \dd Display Halibut's licence (see also \k{licence}) and exit
224 \dd US English alternative spelling of \c{--licence}.
228 \dd Report column numbers as well as line numbers when reporting
229 errors in the Halibut input files.