Jacob pointed out various important facts missing from the Halibut

manual. Added them.

git-svn-id: svn://svn.tartarus.org/sgt/halibut@4038 cda61777-01e9-0310-a592-d414129be87e

diff --git a/doc/index.but b/doc/index.but
index 4d5ef5b..75aadba 100644 (file)
--- a/doc/index.but
+++ b/doc/index.but
@@ -346,3 +346,14 @@ directive
 \IM{--version} \c{--version} command-line option
 \IM{--licence} \c{--licence} command-line option
 \IM{--precise} \c{--precise} command-line option
+
+\IM{command syntax} commands, general syntax of
+\IM{command syntax} formatting commands, general syntax of
+\IM{command syntax} syntax of general formatting commands
+\IM{command syntax} general syntax of formatting commands
+
+\IM{keyword syntax} keywords, syntax of
+\IM{keyword syntax} section keywords, syntax of
+\IM{keyword syntax} chapter keywords, syntax of
+\IM{keyword syntax} heading keywords, syntax of
+\IM{keyword syntax} syntax of keywords

diff --git a/doc/input.but b/doc/input.but
index 25b6c3e..6cbc84b 100644 (file)
--- a/doc/input.but
+++ b/doc/input.but
@@ -230,6 +230,16 @@ and Halibut generates something like
 This document was generated on \date.
 }
 
+You can follow the \c{\\date} command directly with punctuation (as
+in this example, where it is immediately followed by a full stop),
+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 \c{\\.} do-nothing command. See
+\k{input-macro} for more about general Halibut command syntax and
+\c{\\.}.
+
 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
 braces. The format specification will be run through the standard C
@@ -394,6 +404,14 @@ generate nothing but
 The typical behaviour of an antelope \#{do I mean gazelle?} is...
 }
 
+This command will respect nested braces, so you can use it to
+comment out sections of Halibut markup:
+
+\c This function is \#{very, \e{very}} important.
+
+In this example, the comment lasts until the final closing brace (so
+that the whole \q{very, \e{very}} section is commented out).
+
 The \c{\\#} command can also be used to produce a whole-paragraph
 comment; see \k{input-commentpara} for details of that.
 
@@ -589,6 +607,12 @@ Here's a list:
 \n Now go back to step \k{this-one}.
 }
 
+The keyword you supply after \c{\\n} is allowed to contain escaped
+special characters (\c{\\\\}, \c{\\\{} and \c{\\\}}), but should not
+contain any other Halibut markup. It is intended to be a word or two
+of ordinary text. (This also applies to keywords used in other
+commands, such as \c{\\B} and \c{\\C}).
+
 \S2{input-list-description} \i\c{\\dt} and \i\c{\\dd}:
 \ii{Description lists}
 
@@ -821,6 +845,12 @@ written as
 and this allows me to use the command \c{\\k\{input\}} to generate a
 cross-reference to that chapter somewhere else.
 
+The \I{keyword syntax}keyword you supply after one of these commands
+is allowed to contain escaped special characters (\c{\\\\}, \c{\\\{}
+and \c{\\\}}), but should not contain any other Halibut markup. It
+is intended to be a word or two of ordinary text. (This also applies
+to keywords used in other commands, such as \c{\\B} and \c{\\n}).
+
 The next level down from \c{\\C} is \c{\\H}, for \q{heading}. This
 is used in exactly the same way as \c{\\C}, but section headings
 defined with \c{\\H} are considered to be part of a containing
@@ -1013,6 +1043,12 @@ format for a particular book:
 
 \c \BR{freds-book} [Fred1993]
 
+The keyword you supply after \c{\\B} is allowed to contain escaped
+special characters (\c{\\\\}, \c{\\\{} and \c{\\\}}), but should not
+contain any other Halibut markup. It is intended to be a word or two
+of ordinary text. (This also applies to keywords used in other
+commands, such as \c{\\n} and \c{\\C}).
+
 \H{input-index} Creating an \i{index}
 
 Halibut contains a comprehensive indexing mechanism, which attempts
@@ -1245,14 +1281,23 @@ macro, using the \i\c{\\define} command:
 
 \c \define{eur} \u20AC{EUR\_}
 
+Your macro names may include Roman alphabetic characters
+(\c{a}-\c{z}, \c{A}-\c{Z}) and ordinary Arabic numerals
+(\c{0}-\c{9}), but nothing else. (This is general \I{command
+syntax}syntax for all of Halibut's commands, except for a few
+special ones such as \c{\\_} and \c{\\-} which consist of a single
+punctuation character only.)
+
 Then you can just write ...
 
 \c This is likely to cost \eur 2500 at least.
 
 ... except that that's not terribly good, because you end up with a
-space between the Euro sign and the number. In this case, it's
-helpful to use the special \i\c{\\.} command, which is defined to
-\I{NOP}\I{doing nothing}do nothing at all! But it acts as a
+space between the Euro sign and the number. (If you had written
+\c{\\eur2500}, Halibut would have tried to interpret it as a macro
+command called \c{eur2500}, which you didn't define.) In this case,
+it's helpful to use the special \i\c{\\.} command, which is defined
+to \I{NOP}\I{doing nothing}do nothing at all! But it acts as a
 separator between your macro and the next character:
 
 \c This is likely to cost \eur\.2500 at least.