X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/43f61c25ffd4b1e5403c4ae6d49e6a0a39fd4444..62a4b06bbf769ad4fad537a6facf9a23cecba1f8:/doc/running.but diff --git a/doc/running.but b/doc/running.but index d8c0d4c..6d6cb7a 100644 --- a/doc/running.but +++ b/doc/running.but @@ -1,29 +1,33 @@ +\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}. @@ -39,6 +43,10 @@ have configured Halibut to generate a single file, it will be called \c{output.info-2} etc., will be files suitable for use with GNU \c{info}. +\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 @@ -75,9 +83,10 @@ line, using the \c{-C} option). \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{ @@ -117,6 +126,18 @@ additional files \c{output.info-1}, \c{output.info-2} and so on. } +\dt \i\cw{--pdf}[\cw{=}\e{filename}] + +\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{--ps}[\cw{=}\e{filename}] + +\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 produce \e{all} of its output formats. @@ -139,6 +160,18 @@ will translate into the configuration directive \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 @@ -148,12 +181,37 @@ identically to \c{--text -Ctext-filename:myfile.txt}. The Windows 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