Ahem; let's have all the man page headings at the same level!

[sgt/halibut] / doc / input.but

diff --git a/doc/input.but b/doc/input.but
index e3849e3..6cbc84b 100644 (file)
--- a/doc/input.but
+++ b/doc/input.but
@@ -126,10 +126,10 @@ knows where the literal computer text starts and stops; and in plain
 text, this cannot be done by changing font, so there needs to be an
 alternative way.
 
 text, this cannot be done by changing font, so there needs to be an
 alternative way.
 

-So in the plain text back end, things marked as code (\c{\\c}) will
-be surrounded by quote marks, so that it's obvious where they start
-and finish. Things marked as weak code (\c{\\cw}) will not look any
-different from normal text.
+So in the plain text output format, things marked as code (\c{\\c})
+will be surrounded by quote marks, so that it's obvious where they
+start and finish. Things marked as weak code (\c{\\cw}) will not
+look any different from normal text.

 
 I recommend using weak code for any application where it is
 \e{obvious} that the text is literal computer input or output. For
 
 I recommend using weak code for any application where it is
 \e{obvious} that the text is literal computer input or output. For


@@ -230,6 +230,16 @@ and Halibut generates something like
 This document was generated on \date.
 }
 
 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
 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...
 }
 
 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.
 
 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}.
 }
 
 \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}
 
 \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.
 
 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
 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]
 
 
 \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
 \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\_}
 
 
 \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
 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.
 separator between your macro and the next character:
 
 \c This is likely to cost \eur\.2500 at least.