mdw@git.distorted.org.uk Git - sgt/halibut/blob - doc/running.but

   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.