11f2edfa |
1 | \C{running} Running Halibut |
2 | |
0a6347b4 |
3 | \I{running Halibut}In the simplest case, running Halibut is very |
fc8e7adb |
4 | easy. You provide a set of input files on its \i{command line}, and |
5 | it produces a set of output files. |
11f2edfa |
6 | |
fc8e7adb |
7 | \c $ halibut intro.but gettingstarted.but reference.but index.but |
8 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
11f2edfa |
9 | |
339cbe09 |
10 | This will generate a large set of \i{output files}: |
11f2edfa |
11 | |
339cbe09 |
12 | \b \i\c{output.txt} will be a \i{plain text} version of the input |
11f2edfa |
13 | document. |
14 | |
339cbe09 |
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}; |
11f2edfa |
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.) |
20 | |
21 | \lcont{ |
22 | Note that Halibut does not require any external software such as a |
339cbe09 |
23 | \i{Help compiler}. It \e{directly} generates Windows Help files, and |
11f2edfa |
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 |
26 | machine. |
27 | } |
28 | |
339cbe09 |
29 | \b \c{output.1} will be a Unix \i{\cw{man} page}. |
11f2edfa |
30 | |
339cbe09 |
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 |
11f2edfa |
36 | \c{Manual.html}. |
37 | |
43f61c25 |
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 |
40 | \c{info}. |
41 | |
0287083a |
42 | \b \c{output.ps} will be a printable PostScript manual. |
43 | |
44 | \b \c{output.pdf} will be a printable PDF manual. |
45 | |
0a6347b4 |
46 | \H{running-options} \ii{Command-line options} |
47 | |
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 |
52 | here. |
53 | |
54 | Firstly, there are options which indicate which of the output |
55 | formats you want Halibut to generate: |
56 | |
57 | \dt \i\cw{--text}[\cw{=}\e{filename}] |
58 | |
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. |
62 | |
63 | \dt \i\cw{--html}[\cw{=}\e{filename}] |
64 | |
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). |
75 | |
76 | \dt \i\cw{--xhtml}[\cw{=}\e{filename}] |
77 | |
78 | \dd Synonym for \c{--html}. |
79 | |
80 | \dt \i\cw{--winhelp}[\cw{=}\e{filename}] |
81 | |
43f61c25 |
82 | \dd Specifies that you want to generate Windows Help output. You can |
0a6347b4 |
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. |
85 | |
86 | \lcont{ |
87 | |
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. |
91 | |
92 | } |
93 | |
94 | \dt \i\cw{--whlp}[\cw{=}\e{filename}] |
95 | |
96 | \dd Synonym for \c{--winhelp}. |
97 | |
98 | \dt \i\cw{--hlp}[\cw{=}\e{filename}] |
99 | |
100 | \dd Synonym for \c{--winhelp}. |
101 | |
102 | \dt \i\cw{--man}[\cw{=}\e{filename}] |
103 | |
43f61c25 |
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. |
107 | |
108 | \dt \i\cw{--info}[\cw{=}\e{filename}] |
109 | |
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. |
113 | |
114 | \lcont{ |
115 | |
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. |
121 | |
122 | } |
0a6347b4 |
123 | |
0287083a |
124 | \dt \i\cw{--ps}[\cw{=}\e{filename}] |
125 | |
126 | \dd Specifies that you want to generate PostScript output. You |
4395e204 |
127 | can optionally specify a file name (e.g. \c{--ps=myfile.ps}), in |
0287083a |
128 | which case Halibut will change the name of the output file as well. |
129 | |
130 | \dt \i\cw{--pdf}[\cw{=}\e{filename}] |
131 | |
132 | \dd Specifies that you want to generate PDF output. You |
4395e204 |
133 | can optionally specify a file name (e.g. \c{--pdf=myfile.pdf}), in |
0287083a |
134 | which case Halibut will change the name of the output file as well. |
135 | |
67617323 |
136 | If you do not specify any of the above options, Halibut will simply |
137 | produce \e{all} of its output formats. |
138 | |
0a6347b4 |
139 | Also, there is an option which allows you to specify an arbitrary |
140 | \i\c{\\cfg} configuration directive (see \k{input-config}): |
141 | |
142 | \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...] |
143 | |
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 |
149 | |
150 | \lcont{ |
151 | |
152 | \c -Ctext-section-align:2:leftplus |
153 | |
154 | will translate into the configuration directive |
155 | |
156 | \c \cfg{text-section-align}{2}{leftplus} |
157 | |
fc8e7adb |
158 | (Note that your shell may also take an interest in backslashes, |
159 | particularly under Unix. You may find that the backslash with which |
160 | you escape a colon must be doubled in order to make the shell pass |
161 | it to Halibut at all, and to pass a doubled backslash to Halibut you |
162 | might have to type four backslashes on your shell command line. This |
163 | is not part of Halibut's own behaviour, and it cannot do anything |
164 | about it.) |
165 | |
0a6347b4 |
166 | } |
167 | |
168 | The options which set the output file names actually work by |
169 | implicitly generating these configuration directives. When you |
170 | specify \c{--text=myfile.txt}, for example, Halibut treats it |
171 | identically to \c{--text -Ctext-filename:myfile.txt}. The Windows |
172 | Help and man page formats work similarly. HTML is slightly |
173 | different, since it also arranges for single-file output if you pass |
174 | a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to |
175 | \c{--html -Cxhtml-single-filename:myfile.html -Cxhtml-leaf-level:0}. |
176 | (See \k{output} for explanations of all these configuration |
177 | directives.) |
178 | |
179 | In addition to these, there are also a few other options: |
180 | |
181 | \dt \i\cw{--help} |
182 | |
183 | \dd Print a brief help message and exit immediately. (Don't confuse |
184 | this with \c{--winhelp}!) |
185 | |
186 | \dt \i\cw{--version} |
187 | |
188 | \dd Print information about Halibut's version number and exit |
189 | immediately. |
190 | |
191 | \dt \i\cw{--licence} |
192 | |
193 | \dd Display Halibut's licence (see also \k{licence}) and exit |
194 | immediately. |
195 | |
196 | \dt \cw{--license} |
197 | |
198 | \dd US English alternative spelling of \c{--licence}. |
199 | |
200 | \dt \i\cw{--precise} |
201 | |
202 | \dd Report column numbers as well as line numbers when reporting |
203 | errors in the Halibut input files. |