| 1 | \versionid $Id$ |
| 2 | |
| 3 | \C{running} Running Halibut |
| 4 | |
| 5 | \I{running Halibut}In the simplest case, running Halibut is very |
| 6 | easy. You provide a set of input files on its \i{command line}, and |
| 7 | it produces a set of output files. |
| 8 | |
| 9 | \c $ halibut intro.but gettingstarted.but reference.but index.but |
| 10 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 11 | |
| 12 | This will generate a large set of \i{output files}: |
| 13 | |
| 14 | \b \i\c{output.txt} will be a \i{plain text} version of the input |
| 15 | document. |
| 16 | |
| 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.) |
| 22 | |
| 23 | \lcont{ |
| 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 | |
| 31 | } |
| 32 | |
| 33 | \b \c{output.1} will be a Unix \i{\cw{man} page}. |
| 34 | |
| 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 |
| 40 | \c{Manual.html}. |
| 41 | |
| 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 |
| 44 | \c{info}. |
| 45 | |
| 46 | \b \c{output.pdf} will be a printable PDF manual. |
| 47 | |
| 48 | \b \c{output.ps} will be a printable PostScript manual. |
| 49 | |
| 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 |
| 64 | optionally specify a file name (e.g. \c{\-\-text=myfile.txt}), in |
| 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 |
| 70 | optionally specify a file name (e.g. \c{\-\-html=myfile.html}), in |
| 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 | |
| 86 | \dd Specifies that you want to generate old-style Windows Help |
| 87 | output. You can optionally specify a file name (e.g. |
| 88 | \c{\-\-winhelp=myfile.hlp}), in which case Halibut will change the |
| 89 | name of the output file as well. |
| 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 | |
| 101 | \dd Synonym for \c{\-\-winhelp}. |
| 102 | |
| 103 | \dt \i\cw{--hlp}[\cw{=}\e{filename}] |
| 104 | |
| 105 | \dd Synonym for \c{\-\-winhelp}. |
| 106 | |
| 107 | \dt \i\cw{--man}[\cw{=}\e{filename}] |
| 108 | |
| 109 | \dd Specifies that you want to generate \cw{man} page output. You |
| 110 | can optionally specify a file name (e.g. \c{\-\-man=myfile.5}), in |
| 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 |
| 116 | optionally specify a file name (e.g. \c{\-\-info=myfile.info}), in |
| 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 |
| 125 | additional files \c{output.info\-1}, \c{output.info\-2} and so on. |
| 126 | |
| 127 | } |
| 128 | |
| 129 | \dt \i\cw{--pdf}[\cw{=}\e{filename}] |
| 130 | |
| 131 | \dd Specifies that you want to generate PDF output. You |
| 132 | can optionally specify a file name (e.g. \c{\-\-pdf=myfile.pdf}), in |
| 133 | which case Halibut will change the name of the output file as well. |
| 134 | |
| 135 | \dt \i\cw{--ps}[\cw{=}\e{filename}] |
| 136 | |
| 137 | \dd Specifies that you want to generate PostScript output. You |
| 138 | can optionally specify a file name (e.g. \c{\-\-ps=myfile.ps}), in |
| 139 | which case Halibut will change the name of the output file as well. |
| 140 | |
| 141 | If you do not specify any of the above options, Halibut will simply |
| 142 | produce \e{all} of its output formats. |
| 143 | |
| 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 | |
| 149 | \dd The text following \c{\-C} is expected to be a colon-separated |
| 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 | |
| 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 | |
| 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 | |
| 175 | } |
| 176 | |
| 177 | The options which set the output file names actually work by |
| 178 | implicitly generating these configuration directives. When you |
| 179 | specify \c{\-\-text=myfile.txt}, for example, Halibut treats it |
| 180 | identically to \c{\-\-text \-Ctext-filename:myfile.txt}. The Windows |
| 181 | Help and man page formats work similarly. HTML is slightly |
| 182 | different, since it also arranges for single-file output if you pass |
| 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}. |
| 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 | |
| 190 | \dt \i\cw{--input-charset}\cw{=}\e{charset} |
| 191 | |
| 192 | \dd Changes the default assumed \i{character set} for all input files from |
| 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 |
| 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 | |
| 206 | \dt \I{character sets, enumerating}\i\cw{--list-charsets} |
| 207 | |
| 208 | \dd List character sets known to Halibut. |
| 209 | |
| 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 | |
| 215 | \dt \i\cw{--help} |
| 216 | |
| 217 | \dd Print a brief help message and exit immediately. (Don't confuse |
| 218 | this with \c{\-\-winhelp}!) |
| 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 | |
| 232 | \dd US English alternative spelling of \c{\-\-licence}. |
| 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. |