\S{input-emph} \c{\\e}: Emphasising text
-Possibly the most obvious piece of formatting you might want to use
-in a document is \i\e{emphasis}. To emphasise text, you use the
-\i\c{\\e} command, and follow it up with the text to be emphasised
-in braces. For example, the first sentence in this paragraph was
-generated using the Halibut input
+Possibly the most obvious piece of formatting you might want
+to use in a document is \i\e{emphasis}.
+To emphasise text, you use the \i\c{\\e} command, and follow it up
+with the text to be emphasised in braces. For example, the first
+sentence in this paragraph was generated using the Halibut input
-\c Possibly the most obvious piece of formatting you might want to use
-\c in a document is \e{emphasis}.
+\c Possibly the most obvious piece of formatting you might want
+\c to use in a document is \e{emphasis}.
\S{input-code} \c{\\c} and \c{\\cw}: Displaying \i{computer code} inline
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
\b \c{\\cw} means \q{it would be nice to display this text in a
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
+\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:
+
+\c the special formatting command \q{\cw{\\.}}.
+
There is a separate mechanism for displaying computer code in an
entire paragraph; see \k{input-codepara} for that one.
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 \q{\cw{\\.}} do-nothing command. See
+\k{input-macro} for more about general Halibut command syntax and
+\q{\cw{\\.}}.
+
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
Google is located at \W{http://www.google.com/}\cw{www.google.com}.
}
+If you want the link text to be an index term as well, you can also
+specify \c{\\i} or \c{\\ii}; this has to come before \c{\\c} or
+\c{\\cw} if both are present. (See \k{input-index} for more about
+indexing.)
+
\S{input-unicode} \c{\\u}: Specifying arbitrary \i{Unicode}
characters
For example, you might write
-\c The typical behaviour of an antelope \#{do I mean gazelle?} is...
+\c The typical behaviour of an antelope \#{do I mean
+\c gazelle?} is...
and Halibut will simply leave out the aside about gazelles, and will
generate nothing but
\quote{
-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.
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 another program, put \q{\cw{\\c }} at the
+paste a lump of code out of your program, put \q{\cw{\\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.
The disadvantage of having Halibut sort out the list numbering for
you is that if you need to refer to a list item by its number, you
-can't reliably do so. To get round this, Halibut allows an optional
-keyword in braces after the \c{\\n} command. This keyword can then
-be referenced using the \c{\\k} or \c{\\K} command (see
-\k{input-xref}) to provide the number of the list item. For example:
+can't reliably know the number in advance (because if you later add
+another item at the start of the list, the numbers will all change).
+To get round this, Halibut allows an optional keyword in braces
+after the \c{\\n} command. This keyword can then be referenced using
+the \c{\\k} or \c{\\K} command (see \k{input-xref}) to provide the
+number of the list item. For example:
\c Here's a list:
\c
\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}
}
-This syntax seems a little bit inconvenient, and perhaps
+This syntax might seem a little bit inconvenient, and perhaps
counter-intuitive: you might expect the enclosing braces to have to
go around the \e{whole} list item, rather than everything except the
first paragraph.
between will be formatted to indicate that they are a quotation.
(This very manual, in fact, uses this feature a lot: all of the
-examples of Halibut source followed by Halibut output have the
-output quoted using \c{\\quote}.)
+examples of Halibut input followed by Halibut output have the output
+quoted using \c{\\quote}.)
Here's some example Halibut input:
\c \q{The question is,} said Alice, \q{whether you \e{can} make
\c words mean so many different things.}
\c
-\c \q{The question is,} said Humpty Dumpty, \q{who is to be master -
-\c that's all.}
+\c \q{The question is,} said Humpty Dumpty, \q{who is to be
+\c master - that's all.}
\c
\c }
\c
\q{The question is,} said Alice, \q{whether you \e{can} make
words mean so many different things.}
-\q{The question is,} said Humpty Dumpty, \q{who is to be master -
-that's all.}
+\q{The question is,} said Humpty Dumpty, \q{who is to be
+master - that's all.}
}
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
\dd This command indicates that the paragraph attached to it
contains a \i{copyright statement} for the document. This text is
-usually displayed inline, just before the first chapter title but
-after any preamble text before that; but in some output formats it
-is given additional special treatment. For example, Windows Help
-files have a standard slot in which to store a copyright notice, so
-that other software can display it prominently.
+displayed inline where it appears, exactly like a normal paragraph;
+but in some output formats it is given additional special treatment.
+For example, Windows Help files have a standard slot in which to
+store a copyright notice, so that other software can display it
+prominently.
\dt \i\cw{\\versionid}
\c Here's a (fairly short) paragraph which will be displayed.
\c
\c \# Here's a comment paragraph which will not be displayed, no
-\c matter how long it goes on. All I needed to indicate this was the
-\c single \# at the start of the paragraph; I don't need one on
-\c every line or anything like that.
+\c matter how long it goes on. All I needed to indicate this was
+\c the single \# at the start of the paragraph; I don't need one
+\c on every line or anything like that.
\c
\c Here's another displayed paragraph.
Here's a (fairly short) paragraph which will be displayed.
\# Here's a comment paragraph which will not be displayed, no
-matter how long it goes on. All I needed to indicate this was the
-single \# at the start of the paragraph; I don't need one on
-every line or anything like that.
+matter how long it goes on. All I needed to indicate this was
+the single \# at the start of the paragraph; I don't need one
+on every line or anything like that.
Here's another displayed paragraph.
\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
\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.
~mdw / sgt / halibut / blobdiff