11f2edfa |
1 | \C{running} Running Halibut |
2 | |
0a6347b4 |
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. |
11f2edfa |
6 | |
7 | \c $ halibut intro.but getting-started.but reference.but index.but |
8 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
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 | |
0a6347b4 |
38 | \H{running-options} \ii{Command-line options} |
39 | |
40 | Halibut supports command-line options in case you don't want to use |
41 | all of Halibut's \i{output formats}, or you want to configure the |
42 | names of your \i{output files}, or you want to supply additional |
43 | configuration on the command line. The supported options are listed |
44 | here. |
45 | |
46 | Firstly, there are options which indicate which of the output |
47 | formats you want Halibut to generate: |
48 | |
49 | \dt \i\cw{--text}[\cw{=}\e{filename}] |
50 | |
51 | \dd Specifies that you want to generate plain text output. You can |
52 | optionally specify a file name (e.g. \c{--text=myfile.txt}), in |
53 | which case Halibut will change the name of the output file as well. |
54 | |
55 | \dt \i\cw{--html}[\cw{=}\e{filename}] |
56 | |
57 | \dd Specifies that you want to generate HTML output. You can |
58 | optionally specify a file name (e.g. \c{--html=myfile.html}), in |
59 | which case Halibut will change the name of the output file as well. |
60 | Specifying a file name here will also cause the HTML to be output in |
61 | \e{only} one file, instead of the usual behaviour of producing |
62 | multiple files with links between them. If you want to produce |
63 | multiple files and configure their names, you will need to use the |
64 | more complete file name configuration directives given in |
65 | \k{output-html-file} (although you may want to do so on the command |
66 | line, using the \c{-C} option). |
67 | |
68 | \dt \i\cw{--xhtml}[\cw{=}\e{filename}] |
69 | |
70 | \dd Synonym for \c{--html}. |
71 | |
72 | \dt \i\cw{--winhelp}[\cw{=}\e{filename}] |
73 | |
74 | \dd Specifies that you want to generate plain text output. You can |
75 | optionally specify a file name (e.g. \c{--winhelp=myfile.hlp}), in |
76 | which case Halibut will change the name of the output file as well. |
77 | |
78 | \lcont{ |
79 | |
80 | Your output file name should end with \c{.hlp}; if it doesn't, |
81 | Halibut will append it. Halibut will also generate a contents file |
82 | (ending in \c{.cnt}) alongside the file name you specify. |
83 | |
84 | } |
85 | |
86 | \dt \i\cw{--whlp}[\cw{=}\e{filename}] |
87 | |
88 | \dd Synonym for \c{--winhelp}. |
89 | |
90 | \dt \i\cw{--hlp}[\cw{=}\e{filename}] |
91 | |
92 | \dd Synonym for \c{--winhelp}. |
93 | |
94 | \dt \i\cw{--man}[\cw{=}\e{filename}] |
95 | |
96 | \dd Specifies that you want to generate plain text output. You can |
97 | optionally specify a file name (e.g. \c{--man=myfile.5}), in which |
98 | case Halibut will change the name of the output file as well. |
99 | |
67617323 |
100 | If you do not specify any of the above options, Halibut will simply |
101 | produce \e{all} of its output formats. |
102 | |
0a6347b4 |
103 | Also, there is an option which allows you to specify an arbitrary |
104 | \i\c{\\cfg} configuration directive (see \k{input-config}): |
105 | |
106 | \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...] |
107 | |
108 | \dd The text following \c{-C} is expected to be a colon-separated |
109 | list of strings. (If you need a literal colon, you can escape it |
110 | with a backslash: \c{\\:}. If you need a literal \e{backslash}, you |
111 | can do the same: \c{\\\\}.) These strings are used as the parts of a |
112 | \c{\\cfg} directive. So, for example, the option |
113 | |
114 | \lcont{ |
115 | |
116 | \c -Ctext-section-align:2:leftplus |
117 | |
118 | will translate into the configuration directive |
119 | |
120 | \c \cfg{text-section-align}{2}{leftplus} |
121 | |
122 | } |
123 | |
124 | The options which set the output file names actually work by |
125 | implicitly generating these configuration directives. When you |
126 | specify \c{--text=myfile.txt}, for example, Halibut treats it |
127 | identically to \c{--text -Ctext-filename:myfile.txt}. The Windows |
128 | Help and man page formats work similarly. HTML is slightly |
129 | different, since it also arranges for single-file output if you pass |
130 | a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to |
131 | \c{--html -Cxhtml-single-filename:myfile.html -Cxhtml-leaf-level:0}. |
132 | (See \k{output} for explanations of all these configuration |
133 | directives.) |
134 | |
135 | In addition to these, there are also a few other options: |
136 | |
137 | \dt \i\cw{--help} |
138 | |
139 | \dd Print a brief help message and exit immediately. (Don't confuse |
140 | this with \c{--winhelp}!) |
141 | |
142 | \dt \i\cw{--version} |
143 | |
144 | \dd Print information about Halibut's version number and exit |
145 | immediately. |
146 | |
147 | \dt \i\cw{--licence} |
148 | |
149 | \dd Display Halibut's licence (see also \k{licence}) and exit |
150 | immediately. |
151 | |
152 | \dt \cw{--license} |
153 | |
154 | \dd US English alternative spelling of \c{--licence}. |
155 | |
156 | \dt \i\cw{--precise} |
157 | |
158 | \dd Report column numbers as well as line numbers when reporting |
159 | errors in the Halibut input files. |