3 \C{input} Halibut input format
5 This chapter describes the format in which you should write
6 documents to be processed by Halibut.
8 \H{input-basics} The basics
10 Halibut's input files mostly look like ordinary ASCII text files;
11 you can edit them with any text editor you like.
13 Writing \i{paragraphs of ordinary text} is very simple: you just
14 write ordinary text in the ordinary way. You can wrap a paragraph
15 across more than one line using \i{line breaks} in the text file,
16 and Halibut will ignore this when it \I{wrapping paragraphs}rewraps
17 the paragraph for each output format. To separate paragraphs, use a
18 \i{blank line} (i.e. two consecutive line breaks). For example, a
19 fragment of Halibut input looking like this:
21 \c This is a line of text.
22 \c This is another line of text.
24 \c This line is separated from the previous one by a blank line.
26 will produce two paragraphs looking like this:
29 This is a line of text.
30 This is another line of text.
32 This line is separated from the previous one by a blank line.
35 The first two lines of the input have been merged together into a
36 single paragraph, and the line break in the input file was treated
37 identically to the spaces between the individual words.
39 Halibut is designed to have very few \I{escaping, special
40 characters}\i{special characters}. The only printable characters in
41 Halibut input which will not be treated exactly literally in the
42 output are the \i{backslash} (\c{\\}) and the \i{braces} (\c{\{} and
43 \c{\}}). If you do not use these characters, \e{everything} else you
44 might type in normal ASCII text is perfectly safe. If you do need to
45 use any of those three characters in your document, you will have to
46 precede each one with a backslash. Hence, for example, you could
49 \c This \\ is a backslash, and these are \{braces\}.
51 and Halibut would generate the text
54 This \\ is a backslash, and these are \{braces\}.
57 If you want to write your input file in a character set other than
58 ASCII, you can do so by using the \c{\\cfg\{input-charset\}}
59 command. See \k{input-config} for details of this.
61 \H{input-inline} Simple \i{inline formatting commands}
63 Halibut formatting commands all begin with a backslash, followed by
64 a word or character identifying the command. Some of them then use
65 braces to surround one or more pieces of text acted on by the
66 command. (In fact, the \c{\\\\}, \c{\\\{} and \c{\\\}} sequences you
67 met in \k{input-basics} are themselves formatting commands.)
69 This section describes some simple formatting commands you can use
70 in Halibut documents. The commands in this section are \e{inline}
71 commands, which means you can use them in the middle of a paragraph.
72 \K{input-para} describes some \e{paragraph} commands, which affect a
73 whole paragraph at a time.
75 Many of these commands are followed by a pair of braces surrounding
76 some text. In all cases, it is perfectly safe to have a \i{line break}
77 (in the input file) within those braces; Halibut will treat that
78 exactly the same as a space. For example, these two paragraphs will
79 be treated identically:
81 \c Here is some \e{emphasised
84 \c Here is some \e{emphasised text}.
86 \S{input-emph} \c{\\e}: Emphasising text
88 Possibly the most obvious piece of formatting you might want
89 to use in a document is \i\e{emphasis}.
90 To emphasise text, you use the \i\c{\\e} command, and follow it up
91 with the text to be emphasised in braces. For example, the first
92 sentence in this paragraph was generated using the Halibut input
94 \c Possibly the most obvious piece of formatting you might want
95 \c to use in a document is \e{emphasis}.
97 \S{input-code} \c{\\c} and \c{\\cw}: Displaying \i{computer code} inline
99 Halibut was primarily designed to produce software manuals. It can
100 be used for other types of document as well, but software manuals
103 In software manuals, you often want to format text in a way that
104 indicates that it is something you might see displayed \i{verbatim}
105 on a computer screen. In printed manuals, this is typically done by
106 setting that text in a font which is obviously \I{fixed-width
107 font}fixed-width. This provides a visual cue that the text being
108 displayed is code, and it also ensures that punctuation marks are
109 clearly separated and shown individually (so that a user can copy
110 the text accurately and conveniently).
112 Halibut provides \e{two} commands for this, which are subtly
113 different. The names of those commands are \i\c{\\c} (\q{code}) and
114 \i\c{\\cw} (\q{\i{weak code}}). You use them just like \c{\\e}, by
115 following them with some text in braces. For example, this...
117 \c This sentence contains some \c{code} and some \cw{weak code}.
122 This sentence contains some \c{code} and some \cw{weak code}.
125 The distinction between code and weak code is mainly important when
126 producing plain text output. Plain text output is typically viewed
127 in a fixed-width font, so there is no need (and no way) to change
128 font in order to make the order of punctuation marks clear. However,
129 marking text as code is also \e{sometimes} done to provide a visual
130 distinction between it and the text around it, so that the reader
131 knows where the literal computer text starts and stops; and in plain
132 text, this cannot be done by changing font, so there needs to be an
135 So in the plain text output format, things marked as code (\c{\\c})
136 will be surrounded by quote marks, so that it's obvious where they
137 start and finish. Things marked as weak code (\c{\\cw}) will not
138 look any different from normal text.
140 I recommend using weak code for any application where it is
141 \e{obvious} that the text is literal computer input or output. For
142 example, if the text is capitalised, that's usually good enough. If
143 I talk about the Pentium's \cw{EAX} and \cw{EDX} registers, for
144 example, you don't need quotes to notice that those are special; so
145 I would write that in Halibut as \cq{the Pentium's \\cw\{EAX\} and
146 \\cw\{EDX\} registers}. But if I'm talking about the Unix command
147 \c{man}, which is an ordinary English word in its own right, a reader
148 might be slightly confused if it appeared in the middle of a
149 sentence undecorated; so I would write that as \cq{the Unix command
154 \b \c{\\c} means \q{this text \e{must} be visually distinct from the
155 text around it}. Halibut's various output formats will do this by
156 changing the font if possible, or by using quotes if not.
158 \b \c{\\cw} means \q{it would be nice to display this text in a
159 fixed-width font if possible, but it's not essential}.
161 In really extreme cases, you might want Halibut to use \i{quotation
162 marks} even in output formats which can change font. In
163 \k{input-date}, for example, I mention the special formatting
164 command \cq{\\.}. If that appeared at the end of a sentence
165 \e{without} the quotes, then the two adjacent full stops would look
166 pretty strange even if they were obviously in different fonts.
168 For this, Halibut supports the \i\c{\\cq} command, which is exactly
169 equivalent to using \c{\\q} to provide quotes and then using
170 \c{\\cw} inside the quotes. So in the paragraph above, for example,
173 \c the special formatting command \cq{\\.}.
175 and I could equivalently have written
177 \c the special formatting command \q{\cw{\\.}}.
179 There is a separate mechanism for displaying computer code in an
180 entire paragraph; see \k{input-codepara} for that one.
182 \S{input-quotes} \c{\\q}: \ii{Quotation marks}
184 Halibut's various output formats don't all use the same conventions
185 for displaying text in ordinary quotation marks (\q{like these}).
186 Some output formats have access to proper matched quote characters,
187 whereas others are restricted to using plain ASCII. Therefore, it is
188 not ideal to use the ordinary ASCII double quote character in your
189 document (although you can if you like).
191 Halibut provides the formatting command \i\c{\\q} to indicate quoted
194 \c Here is some \q{text in quotes}.
196 then Halibut will print
199 Here is some \q{text in quotes}.
202 and in every output format Halibut generates, it will choose the
203 best quote characters available to it in that format. (The quote
204 characters to use can be configured with the \c{\\cfg} command.)
206 You can still use the ordinary quote characters of your choice if
207 you prefer; or you could even use the \c{\\u} command (see
208 \k{input-unicode}) to generate \i{Unicode matched quotes} (single or
209 double) in a way which will automatically fall back to the normal
210 ASCII one if they aren't available. But I recommend using the
211 built-in \c{\\q} command in most cases, because it's simple and does
212 the best it can everywhere.
214 If you're using the \c{\\c} or \c{\\cw} commands to display literal
215 computer code, you will probably want to use literal \i{ASCII quote
216 characters}, because it is likely to matter precisely which quote
217 character you use. In fact, Halibut actually \e{disallows} the use
218 of \c{\\q} within either of \c{\\c} and \c{\\cw}, since this
219 simplifies some of the output formats.
221 \S{input-nonbreaking} \c{\\-} and \c{\\_}: \ii{Non-breaking hyphens}
222 and \I{non-breaking spaces}spaces
224 If you use an ordinary hyphen in the middle of a word (such as
225 \q{built-in}), Halibut's output formats will feel free to break a
226 line after that hyphen when \i{wrapping paragraphs}. This is fine
227 for a word like \q{built-in}, but if you were displaying some
228 literal computer code such as the Emacs command
229 \c{M\-x\_psychoanalyze\-pinhead}, you might prefer to see the whole
230 hyphenated word treated as an unbreakable block. In some cases, you
231 might even want to prevent the \e{space} in that command from
232 becoming a line break.
234 For these purposes, Halibut provides the commands \i\c{\\-} and
235 \i\c{\\_}, which generate a non-breaking hyphen and a non-breaking
236 space respectively. So the above Emacs command might be written as
238 \c the Emacs command \c{M\-x\_psychoanalyze\-pinhead}
240 Unfortunately, some of Halibut's output formats do not support
241 non-breaking hyphens, and others don't support \e{breaking} hyphens!
242 So Halibut cannot promise to honour these commands in all situations.
243 All it can do is make a best effort.
245 \S{input-date} \c{\\date}: Automatic \i{date} generation
247 Sometimes you might want your document to give an up-to-date
248 indication of the date on which it was run through Halibut.
250 Halibut supplies the \i\c{\\date} command to do this. In its
251 simplest form, you simply say
253 \c This document was generated on \date.
255 and Halibut generates something like
258 This document was generated on \date.
261 You can follow the \c{\\date} command directly with punctuation (as
262 in this example, where it is immediately followed by a full stop),
263 but if you try to follow it with an alphabetic or numeric character
264 (such as writing \c{\\dateZ}) then Halibut will assume you are
265 trying to invoke the name of a macro command you have defined
266 yourself, and will complain if no such command exists. To get round
267 this you can use the special \cq{\\.} do-nothing command. See
268 \k{input-macro} for more about general Halibut command syntax and
271 If you would prefer the date to be generated in a specific format,
272 you can follow the \c{\\date} command with a format specification in
273 braces. The format specification will be run through the standard C
274 function \i\c{strftime}, so any format acceptable to that function
275 is acceptable here as well. I won't document the format here,
276 because the details vary from computer to computer (although there
277 is a standard core which should be supported everywhere). You should
278 look at your local system's manual for \c{strftime} for details.
280 Here's an example which generates the date in the international
281 standard \i{ISO 8601} format:
283 \c This document was generated on \date{%Y-%m-%d %H:%M:%S}.
285 And here's some sample output from that command:
288 This document was generated on \date{%Y-%m-%d %H:%M:%S}.
291 \S{input-weblink} \c{\\W}: \i{WWW hyperlinks}
293 Since one of Halibut's output formats is \i{HTML}, it's obviously
294 useful to be able to provide \I{linking to web sites}links to
295 arbitrary \i{web sites} in a Halibut document.
297 This is done using the \i\c{\\W} command. \c{\\W} expects to be
298 followed by \e{two} sets of braces. In the first set of braces you
299 put a \i{URL}; in the second set you put the text which should be a
300 \i{hyperlink}. For example, you might write
302 \c Try searching on \W{http://www.google.com/}{Google}.
304 and Halibut would generate
307 Try searching on \W{http://www.google.com/}{Google}.
310 Note that hyperlinks, like the non-breaking commands discussed in
311 \k{input-nonbreaking}, are \e{discretionary}: if an output format
312 does not support them then they will just be left out completely. So
313 unless you're \e{only} intending to use the HTML output format, you
314 should avoid storing vital content in the URL part of a \c{\\W}
315 command. The Google example above is reasonable (because most users
316 are likely to be able to find Google for themselves even without a
317 convenient hyperlink leading straight there), but if you really need
318 to direct users to a specific web site, you will need to give the
319 URL in actual displayed text (probably displayed as code as well).
320 However, there's nothing to stop you making it a hyperlink \e{as
321 well} for the convenience of HTML readers.
323 The \c{\\W} command supports a piece of extra syntax to make this
324 convenient for you. You can specify \c{\\c} or \c{\\cw} \e{between}
325 the first and second pairs of braces. For example, you might write
327 \c Google is at \W{http://www.google.com/}\cw{www.google.com}.
329 and Halibut would produce
332 Google is at \W{http://www.google.com/}\cw{www.google.com}.
335 If you want the link text to be an index term as well, you can also
336 specify \c{\\i} or \c{\\ii}; this has to come before \c{\\c} or
337 \c{\\cw} if both are present. (See \k{input-index} for more about
340 \S{input-unicode} \c{\\u}: Specifying arbitrary \i{Unicode}
343 Halibut has extensive support for Unicode and character set
344 conversion. You can specify any (reasonably well known) \i{character
345 set} for your input document, and Halibut will convert it all to
346 Unicode as it reads it in. See \k{input-config} for more details of
349 If you need to specify a Unicode character in your input document
350 which is not supported by the input character set you have chosen,
351 you can use the \i\c{\\u} command to do this. \c{\\u} expects to be
352 followed by a sequence of hex digits; so that \c{\\u0041}, for
353 example, denotes the Unicode character \cw{0x0041}, which is the
356 If a Unicode character specified in this way is not supported in a
357 particular \e{output} format, you probably don't just want it to be
358 omitted. So you can put a pair of braces after the \c{\\u} command
359 containing \i{fallback text}. For example, to specify an amount of
360 money in euros, you might write this:
362 \c This is likely to cost \u20AC{EUR\_}2500 at least.
364 Halibut will render that as a Euro sign \e{if available}, and
365 the text \q{EUR\_} if not. In the output format you're currently
366 reading in, the above input generates this:
369 This is likely to cost \u20AC{EUR\_}2500 at least.
372 If you read it in other formats, you may see different results.
374 \S{input-xref} \i\c{\\k} and \I{\\K-upper}\c{\\K}:
375 \ii{Cross-references} to other sections
377 \K{intro-features} mentions that Halibut \I{section numbers}numbers
378 the sections of your document automatically, and can generate
379 cross-references to them on request. \c{\\k} and \c{\\K} are the
380 commands used to generate those cross-references.
382 To use one of these commands, you simply follow it with a pair of
383 braces containing the keyword for the section in question. For
384 example, you might write something like
386 \c \K{input-xref} expands on \k{intro-features}.
388 and Halibut would generate something like
391 \K{input-xref} expands on \k{intro-features}.
394 The \i{keywords} \c{input-xref} and \c{intro-features} are
395 \i{section keywords} used in this manual itself. In your own
396 document, you would have supplied a keyword for each one of your own
397 sections, and you would provide your own keywords for the \c{\\k}
400 The difference between \c{\\k} and \c{\\K} is simply that \c{\\K}
401 starts the cross-reference text with a capital letter; so you would
402 use \c{\\K} at the beginning of a sentence, and \c{\\k} everywhere
405 In output formats which permit it, cross-references act as
406 \i{hyperlinks}, so that clicking the mouse on a cross-reference
407 takes you straight to the referenced section.
409 The \c{\\k} commands are also used for referring to entries in a
410 \i{bibliography} (see \k{input-biblio} for more about
411 bibliographies), and can also be used for referring to an element of
412 a \i{numbered list} by its number (see \k{input-list-number} for
413 more about numbered lists).
415 See \k{input-sections} for more about chapters and sections.
417 \S{input-inline-comment} \i\c{\\#}: Inline comments
419 If you want to include \i{comments} in your Halibut input, to be seen
420 when reading it directly but not copied into the output text, then
421 you can use \c{\\#} to do this. If you follow \c{\\#} with text in
422 braces, that text will be ignored by Halibut.
424 For example, you might write
426 \c The typical behaviour of an antelope \#{do I mean
429 and Halibut will simply leave out the aside about gazelles, and will
433 The typical behaviour of an antelope \#{do I mean
437 This command will respect nested braces, so you can use it to
438 comment out sections of Halibut markup:
440 \c This function is \#{very, \e{very}} important.
442 In this example, the comment lasts until the final closing brace (so
443 that the whole \q{very, \e{very}} section is commented out).
445 The \c{\\#} command can also be used to produce a whole-paragraph
446 comment; see \k{input-commentpara} for details of that.
448 \H{input-para} \ii{Paragraph-level commands}
450 This section describes Halibut commands which affect an entire
451 paragraph, or sometimes even \e{more} than one paragraph, at a time.
453 \S{input-codepara} \i\c{\\c}: Displaying whole \I{code
454 paragraphs}paragraphs of \i{computer code}
456 \K{input-code} describes a mechanism for displaying computer code in
457 the middle of a paragraph, a few words at a time.
459 However, this is often not enough. Often, in a computer manual, you
460 really want to show several lines of code in a \i{display
463 This is also done using the \c{\\c} command, in a slightly different
464 way. Instead of using it in the middle of a paragraph followed by
465 braces, you can use it at the start of each line of a paragraph. For
466 example, you could write
468 \c \c #include <stdio.h>
470 \c \c int main(int argc, char **argv) {
471 \c \c printf("hello, world\n");
475 and Halibut would generate
479 \c #include <stdio.h>
481 \c int main(int argc, char **argv) {
482 \c printf("hello, world\n");
488 Note that the above paragraph makes use of a backslash and a pair of
489 braces, and does \e{not} need to escape them in the way described in
490 \k{input-basics}. This is because code paragraphs formatted in this
491 way are a special case; the intention is that you can just copy and
492 paste a lump of code out of your program, put \cq{\\c } at the
493 start of every line, and simply \e{not have to worry} about the
494 details - you don't have to go through the whole block looking for
495 characters to escape.
497 Since a backslash inside a code paragraph generates a literal
498 backslash, this means you cannot use any other Halibut formatting
499 commands inside a code paragraph. In particular, if you want to
500 emphasise a particular word in the paragraph, you can't do that
501 using \c{\\e} (\k{input-emph}) in the normal way.
503 Therefore, Halibut provides an alternative means of \i{emphasis in
504 code paragraphs}. Each line beginning with \c{\\c} can optionally be
505 followed by a single line beginning with \c{\\e}, indicating the
506 emphasis in that line. The emphasis line contains the letters \c{b}
507 and \c{i} (for \q{bold} and \q{italic}, although some output formats
508 might render \c{i} as underlining instead of italics), positioned to
509 line up under the parts of the text that you want emphasised.
511 For example, if you wanted to do \i{syntax highlighting} on the
512 above C code by highlighting the preprocessor command in italic and
513 the keywords in bold, you might do it like this:
515 \c \c #include <stdio.h>
516 \c \e iiiiiiiiiiiiiiiiii
518 \c \c int main(int argc, char **argv) {
520 \c \c printf("hello, world\n");
525 and Halibut would generate:
529 \c #include <stdio.h>
530 \e iiiiiiiiiiiiiiiiii
532 \c int main(int argc, char **argv) {
534 \c printf("hello, world\n");
541 Note that not every \c{\\c} line has to be followed by a \c{\\e}
542 line; they're optional.
544 Also, note that highlighting within a code paragraph is
545 \e{discretionary}. Not all of Halibut's output formats can support
546 it (plain text, in particular, has no sensible way to do it). Unless
547 you know you are using a restricted range of output formats, you
548 should use highlighting in code paragraphs \e{only} as a visual aid,
549 and not rely on it to convey any vital semantic content.
551 \S{input-lists} \c{\\b}, \c{\\n}, \c{\\dt}, \c{\\dd}, \c{\\lcont}:
554 Halibut supports bulletted lists, numbered lists and description
557 \S2{input-list-bullet} \i\c{\\b}: \ii{Bulletted lists}
559 To create a bulletted list, you simply prefix each paragraph
560 describing a bullet point with the command \c{\\b}. For example, this
571 would produce this Halibut output:
583 \S2{input-list-number} \i\c{\\n}: \ii{Numbered lists}
585 Numbered lists are just as simple: instead of \c{\\b}, you use
586 \c{\\n}, and Halibut takes care of getting the numbering right for
597 This produces the Halibut output:
609 The disadvantage of having Halibut sort out the list numbering for
610 you is that if you need to refer to a list item by its number, you
611 can't reliably know the number in advance (because if you later add
612 another item at the start of the list, the numbers will all change).
613 To get round this, Halibut allows an optional keyword in braces
614 after the \c{\\n} command. This keyword can then be referenced using
615 the \c{\\k} or \c{\\K} command (see \k{input-xref}) to provide the
616 number of the list item. For example:
626 \c \n Now go back to step \k{this-one}.
628 This produces the following output:
639 \n Now go back to step \k{this-one}.
642 The keyword you supply after \c{\\n} is allowed to contain escaped
643 special characters (\c{\\\\}, \c{\\\{} and \c{\\\}}), but should not
644 contain any other Halibut markup. It is intended to be a word or two
645 of ordinary text. (This also applies to keywords used in other
646 commands, such as \c{\\B} and \c{\\C}).
648 \S2{input-list-description} \i\c{\\dt} and \i\c{\\dd}:
649 \ii{Description lists}
651 To write a description list, you prefix alternate paragraphs with
652 the \c{\\dt} (\q{described thing}) and \c{\\dd} (description)
653 commands. For example:
657 \c \dd This is a large bird with a big beak.
663 This produces the following output:
669 \dd This is a large bird with a big beak.
677 If you really want to, you are allowed to use \c{\\dt} and \c{\\dd}
678 without strictly interleaving them (multiple consecutive \c{\\dt}s
679 or consecutive \c{\\dd}s, or a description list starting with
680 \c{\\dd} or ending with \c{\\dt}). This is probably most useful if
681 you are listing a sequence of things with \c{\\dt}, but only some of
682 them actually need \c{\\dd} descriptions. You should \e{not} use
683 multiple consecutive \c{\\dd}s to provide a multi-paragraph
684 definition of something; that's what \c{\\lcont} is for, as
685 explained in \k{input-list-continuation}.
687 \S2{input-list-continuation} \ii{Continuing list items} into further
690 All three of the above list types assume that each list item is a
691 single paragraph. For a short, snappy list in which each item is
692 likely to be only one or two words, this is perfectly sufficient;
693 but occasionally you will find you want to include several
694 paragraphs in a single list item, or even to \I{nested lists}nest
695 other types of paragraph (such as code paragraphs, or other lists)
698 To do this, you use the \i\c{\\lcont} command. This is a command
699 which can span \e{multiple} paragraphs.
701 After the first paragraph of a list item, include the text
702 \c{\\lcont\{}. This indicates that the subsequent paragraph(s) are a
703 \e{continuation} of the list item that has just been seen. So you
704 can include further paragraphs, and eventually include a closing
705 brace \c{\}} to finish the list continuation. After that, you can
706 either continue adding other items to the original list, or stop
707 immediately and return to writing normal paragraphs of text.
709 Here's a (long) example.
713 \c \n One. This item is followed by a code paragraph:
722 \c \n Two. Now when I say \q{two}, I mean:
730 \c \n Two, part three.
736 The output produced by this fragment is:
742 \n One. This item is followed by a code paragraph:
751 \n Two. Now when I say \q{two}, I mean:
767 This syntax might seem a little bit inconvenient, and perhaps
768 counter-intuitive: you might expect the enclosing braces to have to
769 go around the \e{whole} list item, rather than everything except the
772 \c{\\lcont} is a recent addition to the Halibut input language;
773 previously, \e{all} lists were required to use no more than one
774 paragraph per list item. So it's certainly true that this feature
775 looks like an afterthought because it \e{is} an afterthought, and
776 it's possible that if I'd been designing the language from scratch
777 with multiple-paragraph list items in mind, I would have made it
780 However, the advantage of doing it this way is that no enclosing
781 braces are required in the \e{common} case: simple lists with only
782 one paragraph per item are really, really easy to write. So I'm not
783 too unhappy with the way it turned out; it obeys the doctrine of
784 making simple things simple, and difficult things possible.
786 Note that \c{\\lcont} can only be used on \c{\\b}, \c{\\n} and
787 \c{\\dd} paragraphs; it cannot be used on \c{\\dt}.
789 \S{input-rule} \i\c{\\rule}: \ii{Horizontal rules}
791 The command \c{\\rule}, appearing on its own as a paragraph, will
792 cause a horizontal rule to be drawn, like this:
800 This produces the following output:
812 \S{input-quote} \i\c{\\quote}: \ii{Indenting multiple paragraphs} as a
815 Quoting verbatim text using a code paragraph (\k{input-codepara}) is
816 not always sufficient for your quoting needs. Sometimes you need to
817 quote some normally formatted text, possibly in multiple paragraphs.
818 This is similar to HTML's \i\cw{<BLOCKQUOTE>} command.
820 To do this, you can use the \c{\\quote} command. Like \c{\\lcont},
821 this is a command which expects to enclose at least one paragraph
822 and possibly more. Simply write \c{\\quote\{} at the beginning of
823 your quoted section, and \c{\}} at the end, and the paragraphs in
824 between will be formatted to indicate that they are a quotation.
826 (This very manual, in fact, uses this feature a lot: all of the
827 examples of Halibut input followed by Halibut output have the output
828 quoted using \c{\\quote}.)
830 Here's some example Halibut input:
832 \c In \q{Through the Looking Glass}, Lewis Carroll wrote:
836 \c \q{The question is,} said Alice, \q{whether you \e{can} make
837 \c words mean so many different things.}
839 \c \q{The question is,} said Humpty Dumpty, \q{who is to be
840 \c master - that's all.}
846 The output generated by this is:
850 In \q{Through the Looking Glass}, Lewis Carroll wrote:
854 \q{The question is,} said Alice, \q{whether you \e{can} make
855 words mean so many different things.}
857 \q{The question is,} said Humpty Dumpty, \q{who is to be
858 master - that's all.}
866 \S{input-sections} \I{\\C-upper}\c{\\C}, \i\c{\\H}, \i\c{\\S},
867 \i\c{\\A}, \I{\\U-upper}\c{\\U}: Chapter and \i{section headings}
869 \K{intro-features} mentions that Halibut \I{section
870 numbering}numbers the sections of your document automatically, and
871 can generate cross-references to them on request; \k{input-xref}
872 describes the \c{\\k} and \c{\\K} commands used to generate the
873 cross-references. This section describes the commands used to set up
874 the sections in the first place.
876 A paragraph beginning with the \c{\\C} command defines a chapter
877 heading. The \c{\\C} command expects to be followed by a pair of
878 braces containing a keyword for the chapter; this keyword can then
879 be used with the \c{\\k} and \c{\\K} commands to generate
880 cross-references to the chapter. After the closing brace, the rest
881 of the paragraph is used as the displayed chapter title. So the
882 heading for the current chapter of this manual, for example, is
885 \c \C{input} Halibut input format
887 and this allows me to use the command \c{\\k\{input\}} to generate a
888 cross-reference to that chapter somewhere else.
890 The \I{keyword syntax}keyword you supply after one of these commands
891 is allowed to contain escaped special characters (\c{\\\\}, \c{\\\{}
892 and \c{\\\}}), but should not contain any other Halibut markup. It
893 is intended to be a word or two of ordinary text. (This also applies
894 to keywords used in other commands, such as \c{\\B} and \c{\\n}).
896 The next level down from \c{\\C} is \c{\\H}, for \q{heading}. This
897 is used in exactly the same way as \c{\\C}, but section headings
898 defined with \c{\\H} are considered to be part of a containing
899 chapter, and will be numbered with a pair of numbers. After \c{\\H}
900 comes \c{\\S}, and if necessary you can then move on to \c{\\S2},
903 For example, here's a sequence of heading commands. Normally these
904 commands would be separated at least by blank lines (because each is
905 a separate paragraph), and probably also by body text; but for the
906 sake of brevity, both of those have been left out in this example.
909 \c \H{foo-intro} Introduction to Foo
910 \c \H{foo-running} Running the Foo program
911 \c \S{foo-inter} Running Foo interactively
912 \c \S{foo-batch} Running Foo in batch mode
913 \c \H{foo-trouble} Troubleshooting Foo
914 \c \C{bar} Using Bar instead of Foo
916 This would define two chapters with keywords \c{foo} and \c{bar},
917 which would end up being called Chapter 1 and Chapter 2 (unless
918 there were other chapters before them). The sections \c{foo-intro},
919 \c{foo-running} and \c{foo-trouble} would be referred to as Section
920 1.1, Section 1.2 and Section 1.3 respectively; the subsections
921 \c{foo-inter} and \c{foo-batch} would be Section 1.2.1 and Section
922 1.2.2. If there had been a \i\c{\\S2} command within one of those,
923 it would have been something like Section 1.2.1.1.
925 If you don't like the switch from \c{\\H} to \c{\\S}, you can use
926 \c{\\S1} as a synonym for \c{\\S} and \c{\\S0} as a synonym for
927 \c{\\H}. Chapters are still designated with \c{\\C}, because they
928 need to be distinguished from other types of chapter such as
929 appendices. (Personally, I like the \c{\\C},\c{\\H},\c{\\S} notation
930 because it encourages me to think of my document as a hard disk :-)
932 You can define an \i{appendix} by using \c{\\A} in place of \c{\\C}.
933 This is no different from a chapter except that it's given a letter
934 instead of a number, and cross-references to it will say \q{Appendix
935 A} instead of \q{Chapter 9}. Subsections of an appendix will be
936 numbered \q{A.1}, \q{A.2}, \q{A.2.1} and so on.
938 \I{renaming sections}If you want a particular section to be referred
939 to as something other than a \q{chapter}, \q{section} or
940 \q{appendix}, you can include a second pair of braces after the
941 keyword. For example, if you're \i{writing a FAQ} chapter and you
942 want cross-references between questions to refer to \q{question
943 1.2.3} instead of \q{section 1.2.3}, you can write each section
946 \c \S{question-about-fish}{Question} What about fish?
948 (The word \q{Question} should be given with an initial capital
949 letter. Halibut will lower-case it when you refer to it using
950 \c{\\k}, and will leave it alone if you use \c{\\K}.)
952 This technique allows you to change the designation of
953 \e{particular} sections. To make an overall change in what \e{every}
954 section is called, see \k{input-config}.
956 Finally, the \c{\\U} command defines an \I{unnumbered
957 chapter}\e{unnumbered} chapter. These sometimes occur in books, for
958 specialist purposes such as \q{Bibliography} or
959 \q{Acknowledgements}. \c{\\U} does not expect a keyword argument,
960 because there is no sensible way to generate an automatic
961 cross-reference to such a chapter anyway.
963 \S{input-blurb} \c{\\copyright}, \c{\\title}, \c{\\versionid}:
964 Miscellaneous \i{blurb commands}
966 These three commands define a variety of \i{special paragraph
967 types}. They are all used in the same way: you put the command at
968 the start of a paragraph, and then just follow it with normal text,
971 \c \title My First Manual
973 The three special paragraph types are:
977 \dd This defines the overall title of the entire document. This
978 title is treated specially in some output formats (for example, it's
979 used in a \cw{<title>} tag in the HTML output), so it needs a
980 special paragraph type to point it out.
982 \dt \i\cw{\\copyright}
984 \dd This command indicates that the paragraph attached to it
985 contains a \i{copyright statement} for the document. This text is
986 displayed inline where it appears, exactly like a normal paragraph;
987 but in some output formats it is given additional special treatment.
988 For example, Windows Help files have a standard slot in which to
989 store a copyright notice, so that other software can display it
992 \dt \i\cw{\\versionid}
994 \dd This command indicates that the paragraph contains a version
995 identifier, such as those produced by CVS (of the form \c{$\#{hope this
996 defuses CVS}Id: thingy.but,v 1.6 2004/01/01 16:47:48 simon Exp $}).
997 This text will be tucked away somewhere unobtrusive, so that anyone
998 wanting to (for example) report errors to the document's author can
999 pick out the \i{version IDs} and send them as part of the report, so
1000 that the author can tell at a glance which revision of the document
1003 \S{input-commentpara} \i\c{\\#}: Whole-paragraph \i{comments}
1005 \K{input-inline-comment} describes the use of the \c{\\#} command to
1006 put a short comment in the middle of a paragraph.
1008 If you need to use a \e{long} comment, Halibut also allows you to
1009 use \c{\\#} without braces, to indicate that an entire paragraph is
1010 a comment, like this:
1012 \c Here's a (fairly short) paragraph which will be displayed.
1014 \c \# Here's a comment paragraph which will not be displayed, no
1015 \c matter how long it goes on. All I needed to indicate this was
1016 \c the single \# at the start of the paragraph; I don't need one
1017 \c on every line or anything like that.
1019 \c Here's another displayed paragraph.
1021 When run through Halibut, this produces the following output:
1025 Here's a (fairly short) paragraph which will be displayed.
1027 \# Here's a comment paragraph which will not be displayed, no
1028 matter how long it goes on. All I needed to indicate this was
1029 the single \# at the start of the paragraph; I don't need one
1030 on every line or anything like that.
1032 Here's another displayed paragraph.
1036 \H{input-biblio} Creating a \i{bibliography}
1038 If you need your document to refer to other documents (research
1039 papers, books, websites, whatever), you might find a bibliography
1042 You can define a bibliography entry using the \I{\\B-upper}\c{\\B}
1043 command. This looks very like the \c{\\C} command and friends: it
1044 expects a keyword in braces, followed by some text describing the
1045 document being referred to. For example:
1047 \c \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
1048 \c Published by Paperjam & Notoner, 1993.
1050 If this bibliography entry appears in the finished document, it will
1051 look something like this:
1055 \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
1056 Published by Paperjam & Notoner, 1993.
1060 I say \q{if} above because not all bibliography entries defined
1061 using the \c{\\B} command will necessarily appear in the finished
1062 document. They only appear if they are \I{citation}referred to by a
1063 \i\c{\\k} command (see \k{input-xref}). This allows you to (for
1064 example) maintain a single Halibut source file with a centralised
1065 database of \e{all} the references you have ever needed in any of
1066 your writings, include that file in every document you feed to
1067 Halibut, and have it only produce the bibliography entries you
1068 actually need for each particular document. (In fact, you might even
1069 want this centralised source file to be created automatically by,
1070 say, a Perl script from BibTeX input, so that you can share the same
1071 bibliography with users of other formatting software.)
1073 If you really want a bibliography entry to appear in the document
1074 even though no text explicitly refers to it, you can do that using
1075 the \i\c{\\nocite} command:
1077 \c \nocite{freds-book}
1079 Normally, each bibliography entry will be referred to (in citations
1080 and in the bibliography itself) by a simple reference number, such
1081 as \k{freds-book}. If you would rather use an alternative reference
1082 notation, such as [Fred1993], you can use the \i\c{\\BR}
1083 (\q{Bibliography Rewrite}) command to specify your own reference
1084 format for a particular book:
1086 \c \BR{freds-book} [Fred1993]
1088 The keyword you supply after \c{\\B} is allowed to contain escaped
1089 special characters (\c{\\\\}, \c{\\\{} and \c{\\\}}), but should not
1090 contain any other Halibut markup. It is intended to be a word or two
1091 of ordinary text. (This also applies to keywords used in other
1092 commands, such as \c{\\n} and \c{\\C}).
1094 \H{input-index} Creating an \i{index}
1096 Halibut contains a comprehensive indexing mechanism, which attempts
1097 to be reasonably easy to use in the common case in spite of its
1100 \S{input-index-simple} Simple indexing
1102 In normal usage, you should be able to add index terms to your
1103 document simply by using the \i\c{\\i} command to wrap one or two
1104 words at a time. For example, if you write
1106 \c The \i{hippopotamus} is a particularly large animal.
1108 then the index will contain an entry under \q{hippopotamus},
1109 pointing to that sentence (or as close to that sentence as the
1110 output format sensibly permits).
1112 You can wrap more than one word in \c{\\i} as well:
1114 \c We recommend using a \i{torque wrench} for this job.
1116 \S{input-index-special} Special cases of indexing
1118 If you need to index a computer-related term, you can use the
1119 special case \i\c{\\i\\c} (or \i\c{\\i\\cw} if you prefer):
1121 \c The \i\c{grep} command is what you want here.
1123 This will cause the word \q{grep} to appear in code style, as if the
1124 \c{\\i} were not present and the input just said \c{\\c\{grep\}};
1125 the word will also appear in code style in the actual index.
1127 If you want to simultaneously index and emphasise a word, there's
1128 another special case \i\c{\\i\\e}:
1130 \c This is what we call a \i\e{paper jam}.
1132 This will cause the words \q{paper jam} to be emphasised in the
1133 document, but (unlike the behaviour of \c{\\i\\c}) they will \e{not}
1134 be emphasised in the index. This different behaviour is based on an
1135 expectation that most people indexing a word of computer code will
1136 still want it to look like code in the index, whereas most people
1137 indexing an emphasised word will \e{not} want it emphasised in the
1140 (In fact, \e{no} emphasis in the text inside \c{\\i} will be
1141 preserved in the index. If you really want a term in the index to
1142 appear emphasised, you must say so explicitly using \c{\\IM}; see
1143 \k{input-index-rewrite}.)
1145 Sometimes you might want to index a term which is not explicitly
1146 mentioned, but which is highly relevant to the text and you think
1147 that somebody looking up that term in the index might find it useful
1148 to be directed here. To do this you can use the \I{\\I-upper}\c{\\I}
1149 command, to create an \i{\e{invisible} index tag}:
1151 \c If your printer runs out of toner, \I{replacing toner
1152 \c cartridge}here is what to do:
1154 This input will produce only the output \q{If your printer runs out
1155 of toner, here is what to do}; but an index entry will show up under
1156 \q{replacing toner cartridge}, so that if a user thinks the obvious
1157 place to start in the index is under R for \q{replacing}, they will
1158 find their way here with a minimum of fuss.
1160 (It's worth noting that there is no functional difference between
1161 \c{\\i\{foo\}} and \c{\\I\{foo\}foo}. The simple \c{\\i} case is
1162 only a shorthand for the latter.)
1164 Finally, if you want to index a word at the start of a sentence, you
1165 might very well not want it to show up with a capital letter in the
1166 index. For this, Halibut provides the \i\c{\\ii} command, for
1167 \q{index (case-)insensitively}. You use it like this:
1169 \c \ii{Lions} are at the top of the food chain in this area.
1171 This is equivalent to \c{\\I\{lions\}Lions}; in other words, the
1172 text will say \q{Lions}, but it will show up in the index as
1173 \q{lions}. The text inside \c{\\ii} is converted entirely into lower
1174 case before being added to the index data.
1176 \S{input-index-rewrite} \ii{Fine-tuning the index}
1178 Halibut's index mechanism as described so far still has a few
1181 \b In a reasonably large index, it's often difficult to predict
1182 \I{replicating index terms}which of several words a user will think
1183 of first when trying to look something up. For example, if they want
1184 to know how to replace a toner cartridge, they might look up
1185 \q{replacing} or they might look up \q{toner cartridge}. You
1186 probably don't really want to have to try to figure out which of
1187 those is more likely; instead, what you'd like is to be able to
1188 effortlessly index the same set of document locations under \e{both}
1191 \b Also, you may find you've indexed the same concept under multiple
1192 different \I{merging index terms}index terms; for example, there
1193 might be several instances of \c{\\i\{frog\}} and several of
1194 \c{\\i\{frogs\}}, so that you'd end up with two separate index
1195 entries for what really ought to be the same concept.
1197 \b You might well not want the word \cq{grep} to appear in the
1198 index without explanation; you might prefer it to say something more
1199 \I{rewriting index terms}verbose such as \q{\cw{grep} command}, so
1200 that a user encountering it in the index has some idea of what it is
1201 \e{without} having to follow up the reference. However, you
1202 certainly don't want to have to write \c{\\I\{\\cw\{grep\}
1203 command\}\\c\{grep\}} every time you want to add an index term for
1204 this! You wanted to write \c{\\i\\c\{grep\}} as shown in the
1205 previous section, and tidy it all up afterwards.
1207 All of these problems can be cleaned up by the \i\c{\\IM} (for
1208 \q{Index Modification}) command. \c{\\IM} expects to be followed by
1209 one or more pairs of braces containing index terms as seen in the
1210 document, and then a piece of text (not in braces) describing how it
1211 should be shown in the index.
1213 So to rewrite the \c{grep} example above, you might do this:
1215 \c \IM{grep} \cw{grep} command
1217 This will arrange that the set of places in the document where you
1218 asked Halibut to index \cq{grep} will be listed under
1219 \q{\cw{grep} command} rather than just under \cq{grep}.
1221 You can specify more than one index term in a \c{\\IM} command; so
1222 to merge the index terms \q{frog} and \q{frogs} into a single term,
1225 \c \IM{frog}{frogs} frog
1227 This will arrange that the single index entry \q{frog} will list
1228 \e{all} the places in the document where you asked Halibut to index
1229 either \q{frog} or \q{frogs}.
1231 You can use multiple \c{\\IM} commands to replicate the same set of
1232 document locations in more than one index entry. For example:
1234 \c \IM{replacing toner cartridge} replacing toner cartridge
1235 \c \IM{replacing toner cartridge} toner cartridge, replacing
1237 This will arrange that every place in the document where you have
1238 indexed \q{replacing toner cartridge} will be listed both there
1239 \e{and} under \q{toner cartridge, replacing}, so that no matter
1240 whether the user looks under R or under T they will stil find their
1241 way to the same parts of the document.
1243 In this example, note that although the first \c{\\IM} command
1244 \e{looks} as if it's a tautology, it is still necessary, because
1245 otherwise those document locations will \e{only} be indexed under
1246 \q{toner cartridge, replacing}. If you have \e{no} explicit \c{\\IM}
1247 commands for a particular index term, then Halibut will assume a
1248 default one (typically \c{\\IM\{foo\}\_foo}, although it might be
1249 \c{\\IM\{foo\}\_\\c\{foo\}} if you originally indexed using
1250 \c{\\i\\c}); but as soon as you specify an explicit \c{\\IM},
1251 Halibut discards its default implicit one, and you must then specify
1252 that one explicitly as well if you wanted to keep it.
1254 \S{input-index-case} Indexing terms that differ only in case
1256 The \e{tags} you use to define an index term (that is, the text in
1257 the braces after \c{\\i}, \c{\\I} and \c{\\IM}) are treated
1258 case-insensitively by Halibut. So if, as in this manual itself, you
1259 need two index terms that differ only in case, doing this will not
1262 \c The \i\c{\\c} command defines computer code.
1264 \c The \i\c{\\C} command defines a chapter.
1266 Halibut will treat these terms as the same, and will fold the two
1267 sets of references into one combined list (although it will warn you
1268 that it is doing this). The idea is to ensure that people who forget
1269 to use \c{\\ii} find out about it rather than Halibut silently
1270 generating a bad index; checking an index for errors is very hard
1271 work, so Halibut tries to avoid errors in the first place as much as
1274 If you do come across this situation, you will need to define two
1275 distinguishable index terms. What I did in this manual was something
1278 \c The \i\c{\\c} command defines computer code.
1280 \c The \I{\\C-upper}\c{\\C} command defines a chapter.
1282 \c \IM{\\C-upper} \c{\\C}
1284 The effect of this will be two separate index entries, one reading
1285 \c{\\c} and the other reading \c{\\C}, pointing to the right places.
1287 \H{input-config} \ii{Configuring} Halibut
1289 Halibut uses the \i\c{\\cfg} command to allow you to configure various
1290 aspects of its functionality.
1292 The \c{\\cfg} command expects to be followed by at least one pair of
1293 braces, and usually more after that. The first pair of braces
1294 contains a keyword indicating what aspect of Halibut you want to
1295 configure, and the meaning of the one(s) after that depends on the
1298 The current list of configuration keywords in the main Halibut code
1299 is quite small. Here it is in full:
1301 \dt \I\cw{\\cfg\{chapter\}}\cw{\\cfg\{chapter\}\{}\e{new chapter name}\cw{\}}
1303 \dd This tells Halibut that you don't want to call a chapter a
1304 \I{renaming sections}\I{configuring heading display}chapter any
1305 more. For example, if you give the command
1306 \cw{\\cfg\{chapter\}\{Book\}}, then any chapter defined with the
1307 \c{\\C} command will be labelled \q{Book} rather than \q{Chapter},
1308 both in the section headings and in cross-references. This is
1309 probably most useful if your document is not written in English.
1313 Your replacement name should be given with a capital letter. Halibut
1314 will leave it alone if it appears at the start of a sentence (in a
1315 chapter title, or when \c{\\K} is used), and will lower-case it
1316 otherwise (when \c{\\k} is used).
1320 \dt \I\cw{\\cfg\{section\}}\cw{\\cfg\{section\}\{}\e{new section name}\cw{\}}
1322 \dd Exactly like \c{chapter}, but changes the name given to
1323 subsections of a chapter.
1325 \dt \I\cw{\\cfg\{appendix\}}\cw{\\cfg\{appendix\}\{}\e{new appendix name}\cw{\}}
1327 \dd Exactly like \c{chapter}, but changes the name given to
1330 \dt \I\cw{\\cfg\{contents\}}\cw{\\cfg\{contents\}\{}\e{new contents name}\cw{\}}
1332 \dd This changes the name given to the contents section (by default
1333 \q{Contents}) in back ends which generate one.
1335 \dt \I\cw{\\cfg\{index\}}\cw{\\cfg\{index\}\{}\e{new index name}\cw{\}}
1337 \dd This changes the name given to the index section (by default
1338 \q{Index}) in back ends which generate one.
1340 \dt \I\cw{\\cfg\{input-charset\}}\cw{\\cfg\{input-charset\}\{}\e{character set name}\cw{\}}
1342 \dd This tells Halibut what \i{character set} you are writing your
1343 input file in. By default, it is assumed to be US-ASCII (meaning
1344 \e{only} plain \i{ASCII}, with no accented characters at all).
1348 You can specify any well-known name for any supported character set.
1349 For example, \c{iso-8859-1}, \c{iso8859-1} and \c{iso_8859-1} are
1350 all recognised, \c{GB2312} and \c{EUC-CN} both work, and so on.
1351 (You can list character sets known to Halibut with by invoking it
1352 with the \cw{--list-charsets} option; see \k{running-options}.)
1354 This directive takes effect immediately after the \c{\\cfg} command.
1355 All text after that until the end of the input file is expected to be
1356 in the new character set. You can even change character set several
1357 times within a file if you really want to.
1359 When Halibut reads the input file, everything you type will be
1360 converted into \i{Unicode} from the character set you specify here,
1361 will be processed as Unicode by Halibut internally, and will be
1362 written to the various output formats in whatever character sets
1363 they deem appropriate.
1367 \dt \I\cw{\\cfg\{quotes\}}\cw{\\cfg\{quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
1369 \dd This specifies the quote characters which should be used. You
1370 should separately specify the open and close quote marks; each
1371 quote mark can be one character (\cw{\\cfg\{quotes\}\{`\}\{'\}}), or
1372 more than one (\cw{\\cfg\{quotes\}\{<<\}\{>>\}}).
1376 \cw{\\cfg\{quotes\}} can be overridden by configuration directives for
1377 each individual backend (see \k{output}); it is a convenient way of
1378 setting quote characters for all backends at once.
1380 All backends use these characters in response to the \c{\\q} command
1381 (see \k{input-quotes}). Some (such as the text backend) use them for
1384 You can specify multiple fallback options in this command (a pair of
1385 open and close quotes, each in their own braces, then another pair,
1386 then another if you like), and Halibut will choose the first pair
1387 which the output character set supports (Halibut will always use a
1388 matching pair). (This is to allow you to configure quote characters
1389 once, generate output in several different character sets, and have
1390 Halibut constantly adapt to make the best use of the current
1391 encoding.) For example, you might write
1393 \c \cfg{quotes}{\u201c}{\u201d}{"}{"}
1395 and Halibut would use the Unicode matched double quote characters if
1396 possible, and fall back to ASCII double quotes otherwise. If the
1397 output character set were to contain U+201C but not U+201D, then
1398 Halibut would fall back to using the ASCII double quote character as
1399 \e{both} open and close quotes. (No known character set is that
1400 silly; I mention it only as an example.)
1402 \cw{\\cfg\{quotes\}} (and the backend-specific versions) apply to the
1403 \e{entire} output; it's not possible to change quote characters
1404 partway through the output.
1408 In addition to these configuration commands, there are also
1409 configuration commands provided by each individual output format.
1410 These configuration commands are discussed along with each output
1411 format, in \k{output}.
1413 The \i{default settings} for the above options are:
1415 \c \cfg{chapter}{Chapter}
1416 \c \cfg{section}{Section}
1417 \c \cfg{appendix}{Appendix}
1418 \c \cfg{contents}{Contents}
1419 \c \cfg{index}{Index}
1420 \c \cfg{input-charset}{ASCII}
1422 The default for \cw{\\cfg\{input-charset\}} can be changed with the
1423 \cw{--input-charset} option; see \k{running-options}. The default
1424 settings for \cw{\\cfg\{quotes\}} are backend-specific; see
1427 \H{input-macro} Defining \i{macros}
1429 If there's a complicated piece of Halibut source which you think
1430 you're going to use a lot, you can define your own Halibut command
1431 to produce that piece of source.
1433 In \k{input-unicode}, there is a sample piece of code which prints a
1434 Euro sign, or replaces it with \q{EUR} if the Euro sign is not
1437 \c This is likely to cost \u20AC{EUR\_}2500 at least.
1439 If your document quotes a \e{lot} of prices in Euros, you might not
1440 want to spend all your time typing that out. So you could define a
1441 macro, using the \i\c{\\define} command:
1443 \c \define{eur} \u20AC{EUR\_}
1445 Your macro names may include Roman alphabetic characters
1446 (\c{a}-\c{z}, \c{A}-\c{Z}) and ordinary Arabic numerals
1447 (\c{0}-\c{9}), but nothing else. (This is general \I{command
1448 syntax}syntax for all of Halibut's commands, except for a few
1449 special ones such as \c{\\_} and \c{\\-} which consist of a single
1450 punctuation character only.)
1452 Then you can just write ...
1454 \c This is likely to cost \eur 2500 at least.
1456 ... except that that's not terribly good, because you end up with a
1457 space between the Euro sign and the number. (If you had written
1458 \c{\\eur2500}, Halibut would have tried to interpret it as a macro
1459 command called \c{eur2500}, which you didn't define.) In this case,
1460 it's helpful to use the special \i\c{\\.} command, which is defined
1461 to \I{NOP}\I{doing nothing}do nothing at all! But it acts as a
1462 separator between your macro and the next character:
1464 \c This is likely to cost \eur\.2500 at least.
1466 This way, you will see no space between the Euro sign and the number
1467 (although, of course, there will be space between \q{EUR} and the
1468 number if the Euro sign is not available, because the macro
1469 definition specifically asked for it).