0929484e |
1 | \versionid $Id$ |
2 | |
11f2edfa |
3 | \C{running} Running Halibut |
4 | |
0a6347b4 |
5 | \I{running Halibut}In the simplest case, running Halibut is very |
fc8e7adb |
6 | easy. You provide a set of input files on its \i{command line}, and |
7 | it produces a set of output files. |
11f2edfa |
8 | |
fc8e7adb |
9 | \c $ halibut intro.but gettingstarted.but reference.but index.but |
10 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
11f2edfa |
11 | |
339cbe09 |
12 | This will generate a large set of \i{output files}: |
11f2edfa |
13 | |
339cbe09 |
14 | \b \i\c{output.txt} will be a \i{plain text} version of the input |
11f2edfa |
15 | document. |
16 | |
f2ef00b5 |
17 | \b \i\c{output.hlp} and \i\c{output.cnt} will be an old-style |
18 | \i{Windows Help} version of the same thing. (Most of the text is in |
19 | \c{output.hlp}; \c{output.cnt} contains additional contents data |
20 | used by the Windows help topic selector. If you lose the latter, the |
21 | former should still be usable, but it will look less modern.) |
11f2edfa |
22 | |
23 | \lcont{ |
f2ef00b5 |
24 | |
25 | Note that to do this Halibut does not require any external software |
26 | such as a \i{Help compiler}. It \e{directly} generates old-style |
27 | Windows Help files, and therefore it doesn't need to be run on |
28 | Windows to do so: it can generate them even when run from an |
29 | automated script on a Unix machine. |
30 | |
11f2edfa |
31 | } |
32 | |
339cbe09 |
33 | \b \c{output.1} will be a Unix \i{\cw{man} page}. |
11f2edfa |
34 | |
339cbe09 |
35 | \b The set of files \c{*.html} will contain an \i{HTML} version of |
36 | the document. If you have configured Halibut to generate more than |
37 | one HTML file (the default), then the file \c{Contents.html} will be |
38 | the topmost one that users should be directed to initially. If you |
39 | have configured Halibut to generate a single file, it will be called |
11f2edfa |
40 | \c{Manual.html}. |
41 | |
1dad1efc |
42 | \b \c{output.info}, and some additional files \c{output.info\-1}, |
43 | \c{output.info\-2} etc., will be files suitable for use with GNU |
43f61c25 |
44 | \c{info}. |
45 | |
0287083a |
46 | \b \c{output.pdf} will be a printable PDF manual. |
47 | |
dd454546 |
48 | \b \c{output.ps} will be a printable PostScript manual. |
49 | |
0a6347b4 |
50 | \H{running-options} \ii{Command-line options} |
51 | |
52 | Halibut supports command-line options in case you don't want to use |
53 | all of Halibut's \i{output formats}, or you want to configure the |
54 | names of your \i{output files}, or you want to supply additional |
55 | configuration on the command line. The supported options are listed |
56 | here. |
57 | |
58 | Firstly, there are options which indicate which of the output |
59 | formats you want Halibut to generate: |
60 | |
61 | \dt \i\cw{--text}[\cw{=}\e{filename}] |
62 | |
63 | \dd Specifies that you want to generate plain text output. You can |
1dad1efc |
64 | optionally specify a file name (e.g. \c{\-\-text=myfile.txt}), in |
0a6347b4 |
65 | which case Halibut will change the name of the output file as well. |
66 | |
67 | \dt \i\cw{--html}[\cw{=}\e{filename}] |
68 | |
69 | \dd Specifies that you want to generate HTML output. You can |
1dad1efc |
70 | optionally specify a file name (e.g. \c{\-\-html=myfile.html}), in |
0a6347b4 |
71 | which case Halibut will change the name of the output file as well. |
72 | Specifying a file name here will also cause the HTML to be output in |
73 | \e{only} one file, instead of the usual behaviour of producing |
74 | multiple files with links between them. If you want to produce |
75 | multiple files and configure their names, you will need to use the |
76 | more complete file name configuration directives given in |
77 | \k{output-html-file} (although you may want to do so on the command |
78 | line, using the \c{-C} option). |
79 | |
80 | \dt \i\cw{--xhtml}[\cw{=}\e{filename}] |
81 | |
82 | \dd Synonym for \c{--html}. |
83 | |
84 | \dt \i\cw{--winhelp}[\cw{=}\e{filename}] |
85 | |
f2ef00b5 |
86 | \dd Specifies that you want to generate old-style Windows Help |
87 | output. You can optionally specify a file name (e.g. |
1dad1efc |
88 | \c{\-\-winhelp=myfile.hlp}), in which case Halibut will change the |
f2ef00b5 |
89 | name of the output file as well. |
0a6347b4 |
90 | |
91 | \lcont{ |
92 | |
93 | Your output file name should end with \c{.hlp}; if it doesn't, |
94 | Halibut will append it. Halibut will also generate a contents file |
95 | (ending in \c{.cnt}) alongside the file name you specify. |
96 | |
97 | } |
98 | |
99 | \dt \i\cw{--whlp}[\cw{=}\e{filename}] |
100 | |
1dad1efc |
101 | \dd Synonym for \c{\-\-winhelp}. |
0a6347b4 |
102 | |
103 | \dt \i\cw{--hlp}[\cw{=}\e{filename}] |
104 | |
1dad1efc |
105 | \dd Synonym for \c{\-\-winhelp}. |
0a6347b4 |
106 | |
107 | \dt \i\cw{--man}[\cw{=}\e{filename}] |
108 | |
43f61c25 |
109 | \dd Specifies that you want to generate \cw{man} page output. You |
1dad1efc |
110 | can optionally specify a file name (e.g. \c{\-\-man=myfile.5}), in |
43f61c25 |
111 | which case Halibut will change the name of the output file as well. |
112 | |
113 | \dt \i\cw{--info}[\cw{=}\e{filename}] |
114 | |
115 | \dd Specifies that you want to generate GNU \c{info} output. You can |
1dad1efc |
116 | optionally specify a file name (e.g. \c{\-\-info=myfile.info}), in |
43f61c25 |
117 | which case Halibut will change the name of the output file as well. |
118 | |
119 | \lcont{ |
120 | |
121 | Unless the \c{info} output format is configured not to (see |
122 | \k{output-info}), Halibut will divide the \c{info} output into many |
123 | small files. The extra files will have numeric suffixes on their |
124 | names; so, for example, \c{output.info} might be accompanied by |
1dad1efc |
125 | additional files \c{output.info\-1}, \c{output.info\-2} and so on. |
43f61c25 |
126 | |
127 | } |
0a6347b4 |
128 | |
0287083a |
129 | \dt \i\cw{--pdf}[\cw{=}\e{filename}] |
130 | |
131 | \dd Specifies that you want to generate PDF output. You |
1dad1efc |
132 | can optionally specify a file name (e.g. \c{\-\-pdf=myfile.pdf}), in |
0287083a |
133 | which case Halibut will change the name of the output file as well. |
134 | |
dd454546 |
135 | \dt \i\cw{--ps}[\cw{=}\e{filename}] |
136 | |
137 | \dd Specifies that you want to generate PostScript output. You |
1dad1efc |
138 | can optionally specify a file name (e.g. \c{\-\-ps=myfile.ps}), in |
dd454546 |
139 | which case Halibut will change the name of the output file as well. |
140 | |
67617323 |
141 | If you do not specify any of the above options, Halibut will simply |
142 | produce \e{all} of its output formats. |
143 | |
0a6347b4 |
144 | Also, there is an option which allows you to specify an arbitrary |
145 | \i\c{\\cfg} configuration directive (see \k{input-config}): |
146 | |
147 | \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...] |
148 | |
1dad1efc |
149 | \dd The text following \c{\-C} is expected to be a colon-separated |
0a6347b4 |
150 | list of strings. (If you need a literal colon, you can escape it |
151 | with a backslash: \c{\\:}. If you need a literal \e{backslash}, you |
152 | can do the same: \c{\\\\}.) These strings are used as the parts of a |
153 | \c{\\cfg} directive. So, for example, the option |
154 | |
155 | \lcont{ |
156 | |
157 | \c -Ctext-section-align:2:leftplus |
158 | |
159 | will translate into the configuration directive |
160 | |
161 | \c \cfg{text-section-align}{2}{leftplus} |
162 | |
fc8e7adb |
163 | (Note that your shell may also take an interest in backslashes, |
164 | particularly under Unix. You may find that the backslash with which |
165 | you escape a colon must be doubled in order to make the shell pass |
166 | it to Halibut at all, and to pass a doubled backslash to Halibut you |
167 | might have to type four backslashes on your shell command line. This |
168 | is not part of Halibut's own behaviour, and it cannot do anything |
169 | about it.) |
170 | |
675958c3 |
171 | Configuration directives created in this way take effect after all |
172 | other input has been processed. (In most cases, this has the effect of |
173 | overriding any other instances of the directive in the input.) |
174 | |
0a6347b4 |
175 | } |
176 | |
177 | The options which set the output file names actually work by |
178 | implicitly generating these configuration directives. When you |
1dad1efc |
179 | specify \c{\-\-text=myfile.txt}, for example, Halibut treats it |
180 | identically to \c{\-\-text \-Ctext-filename:myfile.txt}. The Windows |
0a6347b4 |
181 | Help and man page formats work similarly. HTML is slightly |
182 | different, since it also arranges for single-file output if you pass |
1dad1efc |
183 | a filename to \c{\-\-html}; so \c{\-\-html=myfile.html} is equivalent to |
184 | \c{\-\-html \-Chtml-single-filename:myfile.html \-Chtml-leaf-level:0}. |
0a6347b4 |
185 | (See \k{output} for explanations of all these configuration |
186 | directives.) |
187 | |
188 | In addition to these, there are also a few other options: |
189 | |
675958c3 |
190 | \dt \i\cw{--input-charset}\cw{=}\e{charset} |
191 | |
12bb4069 |
192 | \dd Changes the default assumed \i{character set} for all input files from |
1dad1efc |
193 | ASCII to something else. (\cw{\-Cinput-charset} cannot be used for |
194 | this, as \cw{\-C} directives are processed after all other input, so |
675958c3 |
195 | wouldn't affect any files.) |
196 | |
197 | \lcont{ |
198 | |
199 | Any \cw{\\cfg\{input-charset\}} directives within input files override |
200 | this option. |
201 | |
202 | See \k{input-config} for more information about the input character set. |
203 | |
204 | } |
205 | |
f336fa9a |
206 | \dt \I{character sets, enumerating}\i\cw{--list-charsets} |
207 | |
208 | \dd List character sets known to Halibut. |
209 | |
62a4b06b |
210 | \dt \i\cw{--list-fonts} |
211 | |
212 | \dd List fonts known to Halibut, both those it intrinsically knows about |
213 | and those found in its input files. |
214 | |
0a6347b4 |
215 | \dt \i\cw{--help} |
216 | |
217 | \dd Print a brief help message and exit immediately. (Don't confuse |
1dad1efc |
218 | this with \c{\-\-winhelp}!) |
0a6347b4 |
219 | |
220 | \dt \i\cw{--version} |
221 | |
222 | \dd Print information about Halibut's version number and exit |
223 | immediately. |
224 | |
225 | \dt \i\cw{--licence} |
226 | |
227 | \dd Display Halibut's licence (see also \k{licence}) and exit |
228 | immediately. |
229 | |
230 | \dt \cw{--license} |
231 | |
1dad1efc |
232 | \dd US English alternative spelling of \c{\-\-licence}. |
0a6347b4 |
233 | |
234 | \dt \i\cw{--precise} |
235 | |
236 | \dd Report column numbers as well as line numbers when reporting |
237 | errors in the Halibut input files. |