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

   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.