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 simple. You provide a set of input files on its \i{command line},
   5 and it produces a set of output files.
   6
   7 \c $ halibut intro.but getting-started.but reference.but index.but
   8 \e   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
   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 \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
 100 If you do not specify any of the above options, Halibut will simply
 101 produce \e{all} of its output formats.
 102
 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.