| 1 | \C{running} Running Halibut |
| 2 | |
| 3 | \I{running Halibut}In the simplest case, running Halibut is very |
| 4 | easy. You provide a set of input files on its \i{command line}, and |
| 5 | it produces a set of output files. |
| 6 | |
| 7 | \c $ halibut intro.but gettingstarted.but reference.but index.but |
| 8 | \e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb |
| 9 | |
| 10 | This will generate a large set of \i{output files}: |
| 11 | |
| 12 | \b \i\c{output.txt} will be a \i{plain text} version of the input |
| 13 | document. |
| 14 | |
| 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}; |
| 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 |
| 23 | \i{Help compiler}. It \e{directly} generates Windows Help files, and |
| 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 | |
| 29 | \b \c{output.1} will be a Unix \i{\cw{man} page}. |
| 30 | |
| 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 |
| 36 | \c{Manual.html}. |
| 37 | |
| 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 | |
| 42 | \b \c{output.ps} will be a printable PostScript manual. |
| 43 | |
| 44 | \b \c{output.pdf} will be a printable PDF manual. |
| 45 | |
| 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 | |
| 82 | \dd Specifies that you want to generate Windows Help output. You can |
| 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 | |
| 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 | } |
| 123 | |
| 124 | \dt \i\cw{--ps}[\cw{=}\e{filename}] |
| 125 | |
| 126 | \dd Specifies that you want to generate PostScript output. You |
| 127 | can optionally specify a file name (e.g. \c{--ps=myfile.ps}), in |
| 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 |
| 133 | can optionally specify a file name (e.g. \c{--pdf=myfile.pdf}), in |
| 134 | which case Halibut will change the name of the output file as well. |
| 135 | |
| 136 | If you do not specify any of the above options, Halibut will simply |
| 137 | produce \e{all} of its output formats. |
| 138 | |
| 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 | |
| 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 | |
| 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. |