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 | |
339cbe09 |
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}; |
11f2edfa |
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.) |
22 | |
23 | \lcont{ |
24 | Note that Halibut does not require any external software such as a |
339cbe09 |
25 | \i{Help compiler}. It \e{directly} generates Windows Help files, and |
11f2edfa |
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 |
28 | machine. |
29 | } |
30 | |
339cbe09 |
31 | \b \c{output.1} will be a Unix \i{\cw{man} page}. |
11f2edfa |
32 | |
339cbe09 |
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 |
11f2edfa |
38 | \c{Manual.html}. |
39 | |
43f61c25 |
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 |
42 | \c{info}. |
43 | |
0287083a |
44 | \b \c{output.ps} will be a printable PostScript manual. |
45 | |
46 | \b \c{output.pdf} will be a printable PDF manual. |
47 | |
0a6347b4 |
48 | \H{running-options} \ii{Command-line options} |
49 | |
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 |
54 | here. |
55 | |
56 | Firstly, there are options which indicate which of the output |
57 | formats you want Halibut to generate: |
58 | |
59 | \dt \i\cw{--text}[\cw{=}\e{filename}] |
60 | |
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. |
64 | |
65 | \dt \i\cw{--html}[\cw{=}\e{filename}] |
66 | |
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). |
77 | |
78 | \dt \i\cw{--xhtml}[\cw{=}\e{filename}] |
79 | |
80 | \dd Synonym for \c{--html}. |
81 | |
82 | \dt \i\cw{--winhelp}[\cw{=}\e{filename}] |
83 | |
43f61c25 |
84 | \dd Specifies that you want to generate Windows Help output. You can |
0a6347b4 |
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. |
87 | |
88 | \lcont{ |
89 | |
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. |
93 | |
94 | } |
95 | |
96 | \dt \i\cw{--whlp}[\cw{=}\e{filename}] |
97 | |
98 | \dd Synonym for \c{--winhelp}. |
99 | |
100 | \dt \i\cw{--hlp}[\cw{=}\e{filename}] |
101 | |
102 | \dd Synonym for \c{--winhelp}. |
103 | |
104 | \dt \i\cw{--man}[\cw{=}\e{filename}] |
105 | |
43f61c25 |
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. |
109 | |
110 | \dt \i\cw{--info}[\cw{=}\e{filename}] |
111 | |
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. |
115 | |
116 | \lcont{ |
117 | |
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. |
123 | |
124 | } |
0a6347b4 |
125 | |
0287083a |
126 | \dt \i\cw{--ps}[\cw{=}\e{filename}] |
127 | |
128 | \dd Specifies that you want to generate PostScript output. You |
4395e204 |
129 | can optionally specify a file name (e.g. \c{--ps=myfile.ps}), in |
0287083a |
130 | which case Halibut will change the name of the output file as well. |
131 | |
132 | \dt \i\cw{--pdf}[\cw{=}\e{filename}] |
133 | |
134 | \dd Specifies that you want to generate PDF output. You |
4395e204 |
135 | can optionally specify a file name (e.g. \c{--pdf=myfile.pdf}), in |
0287083a |
136 | which case Halibut will change the name of the output file as well. |
137 | |
67617323 |
138 | If you do not specify any of the above options, Halibut will simply |
139 | produce \e{all} of its output formats. |
140 | |
0a6347b4 |
141 | Also, there is an option which allows you to specify an arbitrary |
142 | \i\c{\\cfg} configuration directive (see \k{input-config}): |
143 | |
144 | \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...] |
145 | |
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 |
151 | |
152 | \lcont{ |
153 | |
154 | \c -Ctext-section-align:2:leftplus |
155 | |
156 | will translate into the configuration directive |
157 | |
158 | \c \cfg{text-section-align}{2}{leftplus} |
159 | |
fc8e7adb |
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 |
166 | about it.) |
167 | |
675958c3 |
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.) |
171 | |
0a6347b4 |
172 | } |
173 | |
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 |
cb0b173d |
181 | \c{--html -Chtml-single-filename:myfile.html -Chtml-leaf-level:0}. |
0a6347b4 |
182 | (See \k{output} for explanations of all these configuration |
183 | directives.) |
184 | |
185 | In addition to these, there are also a few other options: |
186 | |
675958c3 |
187 | \dt \i\cw{--input-charset}\cw{=}\e{charset} |
188 | |
12bb4069 |
189 | \dd Changes the default assumed \i{character set} for all input files from |
675958c3 |
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.) |
193 | |
194 | \lcont{ |
195 | |
196 | Any \cw{\\cfg\{input-charset\}} directives within input files override |
197 | this option. |
198 | |
199 | See \k{input-config} for more information about the input character set. |
200 | |
201 | } |
202 | |
f336fa9a |
203 | \dt \I{character sets, enumerating}\i\cw{--list-charsets} |
204 | |
205 | \dd List character sets known to Halibut. |
206 | |
0a6347b4 |
207 | \dt \i\cw{--help} |
208 | |
209 | \dd Print a brief help message and exit immediately. (Don't confuse |
210 | this with \c{--winhelp}!) |
211 | |
212 | \dt \i\cw{--version} |
213 | |
214 | \dd Print information about Halibut's version number and exit |
215 | immediately. |
216 | |
217 | \dt \i\cw{--licence} |
218 | |
219 | \dd Display Halibut's licence (see also \k{licence}) and exit |
220 | immediately. |
221 | |
222 | \dt \cw{--license} |
223 | |
224 | \dd US English alternative spelling of \c{--licence}. |
225 | |
226 | \dt \i\cw{--precise} |
227 | |
228 | \dd Report column numbers as well as line numbers when reporting |
229 | errors in the Halibut input files. |