Revamp of the Halibut error handling mechanism.

[sgt/halibut] / doc / running.but

diff --git a/doc/running.but b/doc/running.but
index f1a3c8c..c0c216f 100644 (file)
--- a/doc/running.but
+++ b/doc/running.but
@@ -14,18 +14,20 @@ 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.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{
 
 \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}.
 }
 
 \b \c{output.1} will be a Unix \i{\cw{man} page}.


@@ -37,14 +39,14 @@ the topmost one that users should be directed to initially. If you
 have configured Halibut to generate a single file, it will be called
 \c{Manual.html}.
 
 have configured Halibut to generate a single file, it will be called
 \c{Manual.html}.
 

-\b \c{output.info}, and some additional files \c{output.info-1},
-\c{output.info-2} etc., will be files suitable for use with GNU
+\b \c{output.info}, and some additional files \c{output.info\-1},
+\c{output.info\-2} etc., will be files suitable for use with GNU

 \c{info}.
 
 \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.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
 \H{running-options} \ii{Command-line options}
 
 Halibut supports command-line options in case you don't want to use


@@ -59,13 +61,13 @@ formats you want Halibut to generate:
 \dt \i\cw{--text}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate plain text output. You can
 \dt \i\cw{--text}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate plain text output. You can

-optionally specify a file name (e.g. \c{--text=myfile.txt}), in
+optionally specify a file name (e.g. \c{\-\-text=myfile.txt}), in

 which case Halibut will change the name of the output file as well.
 
 \dt \i\cw{--html}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate HTML output. You can
 which case Halibut will change the name of the output file as well.
 
 \dt \i\cw{--html}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate HTML output. You can

-optionally specify a file name (e.g. \c{--html=myfile.html}), in
+optionally specify a file name (e.g. \c{\-\-html=myfile.html}), in

 which case Halibut will change the name of the output file as well.
 Specifying a file name here will also cause the HTML to be output in
 \e{only} one file, instead of the usual behaviour of producing
 which case Halibut will change the name of the output file as well.
 Specifying a file name here will also cause the HTML to be output in
 \e{only} one file, instead of the usual behaviour of producing


@@ -81,9 +83,10 @@ line, using the \c{-C} option).
 
 \dt \i\cw{--winhelp}[\cw{=}\e{filename}]
 
 
 \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{
 
 
 \lcont{
 


@@ -95,22 +98,22 @@ Halibut will append it. Halibut will also generate a contents file
 
 \dt \i\cw{--whlp}[\cw{=}\e{filename}]
 
 
 \dt \i\cw{--whlp}[\cw{=}\e{filename}]
 

-\dd Synonym for \c{--winhelp}.
+\dd Synonym for \c{\-\-winhelp}.

 
 \dt \i\cw{--hlp}[\cw{=}\e{filename}]
 
 
 \dt \i\cw{--hlp}[\cw{=}\e{filename}]
 

-\dd Synonym for \c{--winhelp}.
+\dd Synonym for \c{\-\-winhelp}.

 
 \dt \i\cw{--man}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate \cw{man} page output. You
 
 \dt \i\cw{--man}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate \cw{man} page output. You

-can optionally specify a file name (e.g. \c{--man=myfile.5}), in
+can optionally specify a file name (e.g. \c{\-\-man=myfile.5}), in

 which case Halibut will change the name of the output file as well.
 
 \dt \i\cw{--info}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate GNU \c{info} output. You can
 which case Halibut will change the name of the output file as well.
 
 \dt \i\cw{--info}[\cw{=}\e{filename}]
 
 \dd Specifies that you want to generate GNU \c{info} output. You can

-optionally specify a file name (e.g. \c{--info=myfile.info}), in
+optionally specify a file name (e.g. \c{\-\-info=myfile.info}), in

 which case Halibut will change the name of the output file as well.
 
 \lcont{
 which case Halibut will change the name of the output file as well.
 
 \lcont{


@@ -119,20 +122,20 @@ Unless the \c{info} output format is configured not to (see
 \k{output-info}), Halibut will divide the \c{info} output into many
 small files. The extra files will have numeric suffixes on their
 names; so, for example, \c{output.info} might be accompanied by
 \k{output-info}), Halibut will divide the \c{info} output into many
 small files. The extra files will have numeric suffixes on their
 names; so, for example, \c{output.info} might be accompanied by

-additional files \c{output.info-1}, \c{output.info-2} and so on.
+additional files \c{output.info\-1}, \c{output.info\-2} and so on.

 
 }
 
 
 }
 

-\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{--ps=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.
 
 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{--pdf=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
 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


@@ -143,7 +146,7 @@ Also, there is an option which allows you to specify an arbitrary
 
 \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...]
 
 
 \dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...]
 

-\dd The text following \c{-C} is expected to be a colon-separated
+\dd The text following \c{\-C} is expected to be a colon-separated

 list of strings. (If you need a literal colon, you can escape it
 with a backslash: \c{\\:}. If you need a literal \e{backslash}, you
 can do the same: \c{\\\\}.) These strings are used as the parts of a
 list of strings. (If you need a literal colon, you can escape it
 with a backslash: \c{\\:}. If you need a literal \e{backslash}, you
 can do the same: \c{\\\\}.) These strings are used as the parts of a


@@ -173,12 +176,12 @@ overriding any other instances of the directive in the input.)
 
 The options which set the output file names actually work by
 implicitly generating these configuration directives. When you
 
 The options which set the output file names actually work by
 implicitly generating these configuration directives. When you

-specify \c{--text=myfile.txt}, for example, Halibut treats it
-identically to \c{--text -Ctext-filename:myfile.txt}. The Windows
+specify \c{\-\-text=myfile.txt}, for example, Halibut treats it
+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
 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}.
+a filename to \c{\-\-html}; so \c{\-\-html=myfile.html} is equivalent to
+\c{\-\-html \-Chtml-single-filename:myfile.html \-Chtml-leaf-level:0}.

 (See \k{output} for explanations of all these configuration
 directives.)
 
 (See \k{output} for explanations of all these configuration
 directives.)
 


@@ -187,8 +190,8 @@ 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
 \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
+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{
 wouldn't affect any files.)
 
 \lcont{


@@ -200,10 +203,19 @@ 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
 \dt \i\cw{--help}
 
 \dd Print a brief help message and exit immediately. (Don't confuse

-this with \c{--winhelp}!)
+this with \c{\-\-winhelp}!)

 
 \dt \i\cw{--version}
 
 
 \dt \i\cw{--version}
 


@@ -217,7 +229,7 @@ immediately.
 
 \dt \cw{--license}
 
 
 \dt \cw{--license}
 

-\dd US English alternative spelling of \c{--licence}.
+\dd US English alternative spelling of \c{\-\-licence}.

 
 \dt \i\cw{--precise}
 
 
 \dt \i\cw{--precise}