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

diff --git a/doc/input.but b/doc/input.but
index d99f5ce..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
@@ -140,12 +142,12 @@ I recommend using weak code for any application where it is
 example, if the text is capitalised, that's usually good enough. If
 I talk about the Pentium's \cw{EAX} and \cw{EDX} registers, for
 example, you don't need quotes to notice that those are special; so
-I would write that in Halibut as \q{\c{the Pentium's \\cw\{EAX\} and
-\\cw\{EDX\} registers}}. But if I'm talking about the Unix command
+I would write that in Halibut as \cq{the Pentium's \\cw\{EAX\} and
+\\cw\{EDX\} registers}. But if I'm talking about the Unix command
 \c{man}, which is an ordinary English word in its own right, a reader
 might be slightly confused if it appeared in the middle of a
-sentence undecorated; so I would write that as \q{\c{the Unix command
-\\c\{man\}}}.
+sentence undecorated; so I would write that as \cq{the Unix command
+\\c\{man\}}.
 
 In summary:
 
@@ -159,12 +161,18 @@ fixed-width font if possible, but it's not essential}.
 In really extreme cases, you might want Halibut to use \i{quotation
 marks} even in output formats which can change font. In
 \k{input-date}, for example, I mention the special formatting
-command \q{\cw{\\.}}. If that appeared at the end of a sentence
+command \cq{\\.}. If that appeared at the end of a sentence
 \e{without} the quotes, then the two adjacent full stops would look
-pretty strange even if they were obviously in different fonts. So I
-used the \c{\\q} command to provide my own set of quotes, and then
-used \c{\\cw} rather than \c{\\c} to ensure that none of Halibut's
-output formats would add another set of quotes:
+pretty strange even if they were obviously in different fonts.
+
+For this, Halibut supports the \i\c{\\cq} command, which is exactly
+equivalent to using \c{\\q} to provide quotes and then using
+\c{\\cw} inside the quotes. So in the paragraph above, for example,
+I wrote
+
+\c the special formatting command \cq{\\.}.
+
+and I could equivalently have written
 
 \c the special formatting command \q{\cw{\\.}}.
 
@@ -256,9 +264,9 @@ but if you try to follow it with an alphabetic or numeric character
 (such as writing \c{\\dateZ}) then Halibut will assume you are
 trying to invoke the name of a macro command you have defined
 yourself, and will complain if no such command exists. To get round
-this you can use the special \q{\cw{\\.}} do-nothing command. See
+this you can use the special \cq{\\.} do-nothing command. See
 \k{input-macro} for more about general Halibut command syntax and
-\q{\cw{\\.}}.
+\cq{\\.}.
 
 If you would prefer the date to be generated in a specific format,
 you can follow the \c{\\date} command with a format specification in
@@ -481,7 +489,7 @@ Note that the above paragraph makes use of a backslash and a pair of
 braces, and does \e{not} need to escape them in the way described in
 \k{input-basics}. This is because code paragraphs formatted in this
 way are a special case; the intention is that you can just copy and
-paste a lump of code out of your program, put \q{\cw{\\c }} at the
+paste a lump of code out of your program, put \cq{\\c } at the
 start of every line, and simply \e{not have to worry} about the
 details - you don't have to go through the whole block looking for
 characters to escape.
@@ -666,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
 
@@ -958,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}
@@ -1176,7 +1194,7 @@ might be several instances of \c{\\i\{frog\}} and several of
 \c{\\i\{frogs\}}, so that you'd end up with two separate index
 entries for what really ought to be the same concept.
 
-\b You might well not want the word \q{\cw{grep}} to appear in the
+\b You might well not want the word \cq{grep} to appear in the
 index without explanation; you might prefer it to say something more
 \I{rewriting index terms}verbose such as \q{\cw{grep} command}, so
 that a user encountering it in the index has some idea of what it is
@@ -1197,8 +1215,8 @@ So to rewrite the \c{grep} example above, you might do this:
 \c \IM{grep} \cw{grep} command
 
 This will arrange that the set of places in the document where you
-asked Halibut to index \q{\cw{grep}} will be listed under
-\q{\cw{grep} command} rather than just under \q{\cw{grep}}.
+asked Halibut to index \cq{grep} will be listed under
+\q{\cw{grep} command} rather than just under \cq{grep}.
 
 You can specify more than one index term in a \c{\\IM} command; so
 to merge the index terms \q{frog} and \q{frogs} into a single term,
@@ -1277,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{\}}
 
@@ -1309,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
@@ -1320,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,
@@ -1385,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}