1 \C{running} Running Halibut
3 \I{running Halibut}In the simplest case, running Halibut is very
4 simple. You provide a set of input files on its \i{command line},
5 and it produces a set of output files.
7 \c $ halibut intro.but getting-started.but reference.but index.but
8 \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
10 This will generate a large set of \i{output files}:
12 \b \i\c{output.txt} will be a \i{plain text} version of the input
15 \b \i\c{output.hlp} and \i\c{output.cnt} will be a \i{Windows Help}
16 version of the same thing. (Most of the text is in \c{output.hlp};
17 \c{output.cnt} contains additional contents data used by the Windows
18 help topic selector. If you lose the latter, the former should still
19 be usable, but it will look less modern.)
22 Note that Halibut does not require any external software such as a
23 \i{Help compiler}. It \e{directly} generates Windows Help files, and
24 therefore it doesn't need to be run on Windows to do so: it can
25 generate them even when run from an automated script on a Unix
29 \b \c{output.1} will be a Unix \i{\cw{man} page}.
31 \b The set of files \c{*.html} will contain an \i{HTML} version of
32 the document. If you have configured Halibut to generate more than
33 one HTML file (the default), then the file \c{Contents.html} will be
34 the topmost one that users should be directed to initially. If you
35 have configured Halibut to generate a single file, it will be called
38 \b \c{output.info}, and some additional files \c{output.info-1},
39 \c{output.info-2} etc., will be files suitable for use with GNU
42 \b \c{output.ps} will be a printable PostScript manual.
44 \b \c{output.pdf} will be a printable PDF manual.
46 \H{running-options} \ii{Command-line options}
48 Halibut supports command-line options in case you don't want to use
49 all of Halibut's \i{output formats}, or you want to configure the
50 names of your \i{output files}, or you want to supply additional
51 configuration on the command line. The supported options are listed
54 Firstly, there are options which indicate which of the output
55 formats you want Halibut to generate:
57 \dt \i\cw{--text}[\cw{=}\e{filename}]
59 \dd Specifies that you want to generate plain text output. You can
60 optionally specify a file name (e.g. \c{--text=myfile.txt}), in
61 which case Halibut will change the name of the output file as well.
63 \dt \i\cw{--html}[\cw{=}\e{filename}]
65 \dd Specifies that you want to generate HTML output. You can
66 optionally specify a file name (e.g. \c{--html=myfile.html}), in
67 which case Halibut will change the name of the output file as well.
68 Specifying a file name here will also cause the HTML to be output in
69 \e{only} one file, instead of the usual behaviour of producing
70 multiple files with links between them. If you want to produce
71 multiple files and configure their names, you will need to use the
72 more complete file name configuration directives given in
73 \k{output-html-file} (although you may want to do so on the command
74 line, using the \c{-C} option).
76 \dt \i\cw{--xhtml}[\cw{=}\e{filename}]
78 \dd Synonym for \c{--html}.
80 \dt \i\cw{--winhelp}[\cw{=}\e{filename}]
82 \dd Specifies that you want to generate Windows Help output. You can
83 optionally specify a file name (e.g. \c{--winhelp=myfile.hlp}), in
84 which case Halibut will change the name of the output file as well.
88 Your output file name should end with \c{.hlp}; if it doesn't,
89 Halibut will append it. Halibut will also generate a contents file
90 (ending in \c{.cnt}) alongside the file name you specify.
94 \dt \i\cw{--whlp}[\cw{=}\e{filename}]
96 \dd Synonym for \c{--winhelp}.
98 \dt \i\cw{--hlp}[\cw{=}\e{filename}]
100 \dd Synonym for \c{--winhelp}.
102 \dt \i\cw{--man}[\cw{=}\e{filename}]
104 \dd Specifies that you want to generate \cw{man} page output. You
105 can optionally specify a file name (e.g. \c{--man=myfile.5}), in
106 which case Halibut will change the name of the output file as well.
108 \dt \i\cw{--info}[\cw{=}\e{filename}]
110 \dd Specifies that you want to generate GNU \c{info} output. You can
111 optionally specify a file name (e.g. \c{--info=myfile.info}), in
112 which case Halibut will change the name of the output file as well.
116 Unless the \c{info} output format is configured not to (see
117 \k{output-info}), Halibut will divide the \c{info} output into many
118 small files. The extra files will have numeric suffixes on their
119 names; so, for example, \c{output.info} might be accompanied by
120 additional files \c{output.info-1}, \c{output.info-2} and so on.
124 \dt \i\cw{--ps}[\cw{=}\e{filename}]
126 \dd Specifies that you want to generate PostScript output. You
127 can optionally specify a file name (e.g. \c{--man=myfile.ps}), in
128 which case Halibut will change the name of the output file as well.
130 \dt \i\cw{--pdf}[\cw{=}\e{filename}]
132 \dd Specifies that you want to generate PDF output. You
133 can optionally specify a file name (e.g. \c{--man=myfile.pdf}), in
134 which case Halibut will change the name of the output file as well.
136 If you do not specify any of the above options, Halibut will simply
137 produce \e{all} of its output formats.
139 Also, there is an option which allows you to specify an arbitrary
140 \i\c{\\cfg} configuration directive (see \k{input-config}):
142 \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...]
144 \dd The text following \c{-C} is expected to be a colon-separated
145 list of strings. (If you need a literal colon, you can escape it
146 with a backslash: \c{\\:}. If you need a literal \e{backslash}, you
147 can do the same: \c{\\\\}.) These strings are used as the parts of a
148 \c{\\cfg} directive. So, for example, the option
152 \c -Ctext-section-align:2:leftplus
154 will translate into the configuration directive
156 \c \cfg{text-section-align}{2}{leftplus}
160 The options which set the output file names actually work by
161 implicitly generating these configuration directives. When you
162 specify \c{--text=myfile.txt}, for example, Halibut treats it
163 identically to \c{--text -Ctext-filename:myfile.txt}. The Windows
164 Help and man page formats work similarly. HTML is slightly
165 different, since it also arranges for single-file output if you pass
166 a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to
167 \c{--html -Cxhtml-single-filename:myfile.html -Cxhtml-leaf-level:0}.
168 (See \k{output} for explanations of all these configuration
171 In addition to these, there are also a few other options:
175 \dd Print a brief help message and exit immediately. (Don't confuse
176 this with \c{--winhelp}!)
180 \dd Print information about Halibut's version number and exit
185 \dd Display Halibut's licence (see also \k{licence}) and exit
190 \dd US English alternative spelling of \c{--licence}.
194 \dd Report column numbers as well as line numbers when reporting
195 errors in the Halibut input files.