X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/b774705014b73abf1052a937deef534d34ca259d..refs/heads/master:/doc/input.but

diff --git a/doc/input.but b/doc/input.but
index 4166ee7..8cf4b8a 100644
--- a/doc/input.but
+++ b/doc/input.but
@@ -1,3 +1,5 @@
+\versionid $Id$
+
 \C{input} Halibut input format
 
 This chapter describes the format in which you should write
@@ -672,6 +674,16 @@ This produces the following output:
 
 }
 
+If you really want to, you are allowed to use \c{\\dt} and \c{\\dd}
+without strictly interleaving them (multiple consecutive \c{\\dt}s
+or consecutive \c{\\dd}s, or a description list starting with
+\c{\\dd} or ending with \c{\\dt}). This is probably most useful if
+you are listing a sequence of things with \c{\\dt}, but only some of
+them actually need \c{\\dd} descriptions. You should \e{not} use
+multiple consecutive \c{\\dd}s to provide a multi-paragraph
+definition of something; that's what \c{\\lcont} is for, as
+explained in \k{input-list-continuation}.
+
 \S2{input-list-continuation} \ii{Continuing list items} into further
 paragraphs
 
@@ -964,7 +976,7 @@ The three special paragraph types are:
 
 \dd This defines the overall title of the entire document. This
 title is treated specially in some output formats (for example, it's
-used in a \cw{<title>} tag in the HTML output), so it needs a
+used in a \cw{<TITLE>} tag in the HTML output), so it needs a
 special paragraph type to point it out.
 
 \dt \i\cw{\\copyright}
@@ -1283,8 +1295,15 @@ contains a keyword indicating what aspect of Halibut you want to
 configure, and the meaning of the one(s) after that depends on the
 first keyword.
 
-The current list of configuration keywords in the main Halibut code
-is quite small. Here it is in full:
+Each output format supports a range of configuration options of its
+own (and some configuration is shared between similar output formats
+- the PDF and PostScript formats share most of their configuration,
+as described in \k{output-paper}). The configuration keywords for
+each output format are listed in the manual section for that format;
+see \k{output}.
+
+There are also a small number of configuration options which apply
+across all output formats:
 
 \dt \I\cw{\\cfg\{chapter\}}\cw{\\cfg\{chapter\}\{}\e{new chapter name}\cw{\}}
 
@@ -1315,6 +1334,16 @@ subsections of a chapter.
 \dd Exactly like \c{chapter}, but changes the name given to
 appendices.
 
+\dt \I\cw{\\cfg\{contents\}}\cw{\\cfg\{contents\}\{}\e{new contents name}\cw{\}}
+
+\dd This changes the name given to the contents section (by default
+\q{Contents}) in back ends which generate one.
+
+\dt \I\cw{\\cfg\{index\}}\cw{\\cfg\{index\}\{}\e{new index name}\cw{\}}
+
+\dd This changes the name given to the index section (by default
+\q{Index}) in back ends which generate one.
+
 \dt \I\cw{\\cfg\{input-charset\}}\cw{\\cfg\{input-charset\}\{}\e{character set name}\cw{\}}
 
 \dd This tells Halibut what \i{character set} you are writing your
@@ -1326,11 +1355,13 @@ input file in. By default, it is assumed to be US-ASCII (meaning
 You can specify any well-known name for any supported character set.
 For example, \c{iso-8859-1}, \c{iso8859-1} and \c{iso_8859-1} are
 all recognised, \c{GB2312} and \c{EUC-CN} both work, and so on.
+(You can list character sets known to Halibut with by invoking it
+with the \cw{--list-charsets} option; see \k{running-options}.)
 
 This directive takes effect immediately after the \c{\\cfg} command.
-All text after that in the file is expected to be in the new
-character set. You can even change character set several times
-within a file if you really want to.
+All text after that until the end of the input file is expected to be
+in the new character set. You can even change character set several
+times within a file if you really want to. 
 
 When Halibut reads the input file, everything you type will be
 converted into \i{Unicode} from the character set you specify here,
@@ -1391,10 +1422,14 @@ The \i{default settings} for the above options are:
 \c \cfg{chapter}{Chapter}
 \c \cfg{section}{Section}
 \c \cfg{appendix}{Appendix}
+\c \cfg{contents}{Contents}
+\c \cfg{index}{Index}
 \c \cfg{input-charset}{ASCII}
 
-(The default settings for \cw{\\cfg\{quotes\}} are backend-specific;
-see \k{output}.)
+The default for \cw{\\cfg\{input-charset\}} can be changed with the
+\cw{--input-charset} option; see \k{running-options}. The default
+settings for \cw{\\cfg\{quotes\}} are backend-specific; see
+\k{output}.
 
 \H{input-macro} Defining \i{macros}