+\versionid $Id$
+
\C{running} Running Halibut
\I{running Halibut}In the simplest case, running Halibut is very
-simple. You provide a set of input files on its \i{command line},
-and it produces a set of output files.
+easy. You provide a set of input files on its \i{command line}, and
+it produces a set of output files.
-\c $ halibut intro.but getting-started.but reference.but index.but
-\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+\c $ halibut intro.but gettingstarted.but reference.but index.but
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
This will generate a large set of \i{output files}:
\b \i\c{output.txt} will be a \i{plain text} version of the input
document.
-\b \i\c{output.hlp} and \i\c{output.cnt} will be a \i{Windows Help}
-version of the same thing. (Most of the text is in \c{output.hlp};
-\c{output.cnt} contains additional contents data used by the Windows
-help topic selector. If you lose the latter, the former should still
-be usable, but it will look less modern.)
+\b \i\c{output.hlp} and \i\c{output.cnt} will be an old-style
+\i{Windows Help} version of the same thing. (Most of the text is in
+\c{output.hlp}; \c{output.cnt} contains additional contents data
+used by the Windows help topic selector. If you lose the latter, the
+former should still be usable, but it will look less modern.)
\lcont{
-Note that Halibut does not require any external software such as a
-\i{Help compiler}. It \e{directly} generates Windows Help files, and
-therefore it doesn't need to be run on Windows to do so: it can
-generate them even when run from an automated script on a Unix
-machine.
+
+Note that to do this Halibut does not require any external software
+such as a \i{Help compiler}. It \e{directly} generates old-style
+Windows Help files, and therefore it doesn't need to be run on
+Windows to do so: it can generate them even when run from an
+automated script on a Unix machine.
+
}
\b \c{output.1} will be a Unix \i{\cw{man} page}.
\c{output.info-2} etc., will be files suitable for use with GNU
\c{info}.
-\b \c{output.ps} will be a printable PostScript manual.
-
\b \c{output.pdf} will be a printable PDF manual.
+\b \c{output.ps} will be a printable PostScript manual.
+
\H{running-options} \ii{Command-line options}
Halibut supports command-line options in case you don't want to use
\dt \i\cw{--winhelp}[\cw{=}\e{filename}]
-\dd Specifies that you want to generate Windows Help output. You can
-optionally specify a file name (e.g. \c{--winhelp=myfile.hlp}), in
-which case Halibut will change the name of the output file as well.
+\dd Specifies that you want to generate old-style Windows Help
+output. You can optionally specify a file name (e.g.
+\c{--winhelp=myfile.hlp}), in which case Halibut will change the
+name of the output file as well.
\lcont{
}
-\dt \i\cw{--ps}[\cw{=}\e{filename}]
+\dt \i\cw{--pdf}[\cw{=}\e{filename}]
-\dd Specifies that you want to generate PostScript output. You
-can optionally specify a file name (e.g. \c{--man=myfile.ps}), in
+\dd Specifies that you want to generate PDF output. You
+can optionally specify a file name (e.g. \c{--pdf=myfile.pdf}), in
which case Halibut will change the name of the output file as well.
-\dt \i\cw{--pdf}[\cw{=}\e{filename}]
+\dt \i\cw{--ps}[\cw{=}\e{filename}]
-\dd Specifies that you want to generate PDF output. You
-can optionally specify a file name (e.g. \c{--man=myfile.pdf}), in
+\dd Specifies that you want to generate PostScript output. You
+can optionally specify a file name (e.g. \c{--ps=myfile.ps}), in
which case Halibut will change the name of the output file as well.
If you do not specify any of the above options, Halibut will simply
\c \cfg{text-section-align}{2}{leftplus}
+(Note that your shell may also take an interest in backslashes,
+particularly under Unix. You may find that the backslash with which
+you escape a colon must be doubled in order to make the shell pass
+it to Halibut at all, and to pass a doubled backslash to Halibut you
+might have to type four backslashes on your shell command line. This
+is not part of Halibut's own behaviour, and it cannot do anything
+about it.)
+
+Configuration directives created in this way take effect after all
+other input has been processed. (In most cases, this has the effect of
+overriding any other instances of the directive in the input.)
+
}
The options which set the output file names actually work by
Help and man page formats work similarly. HTML is slightly
different, since it also arranges for single-file output if you pass
a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to
-\c{--html -Cxhtml-single-filename:myfile.html -Cxhtml-leaf-level:0}.
+\c{--html -Chtml-single-filename:myfile.html -Chtml-leaf-level:0}.
(See \k{output} for explanations of all these configuration
directives.)
In addition to these, there are also a few other options:
+\dt \i\cw{--input-charset}\cw{=}\e{charset}
+
+\dd Changes the default assumed \i{character set} for all input files from
+ASCII to something else. (\cw{-Cinput-charset} cannot be used for
+this, as \cw{-C} directives are processed after all other input, so
+wouldn't affect any files.)
+
+\lcont{
+
+Any \cw{\\cfg\{input-charset\}} directives within input files override
+this option.
+
+See \k{input-config} for more information about the input character set.
+
+}
+
+\dt \I{character sets, enumerating}\i\cw{--list-charsets}
+
+\dd List character sets known to Halibut.
+
+\dt \i\cw{--list-fonts}
+
+\dd List fonts known to Halibut, both those it intrinsically knows about
+and those found in its input files.
+
\dt \i\cw{--help}
\dd Print a brief help message and exit immediately. (Don't confuse
~mdw / sgt / halibut / blobdiff