1 \C{input} Halibut input format
3 This chapter describes the format in which you should write
4 documents to be processed by Halibut.
6 \H{input-basics} The basics
8 Halibut's input files mostly look like ordinary ASCII text files;
9 you can edit them with any text editor you like.
11 Writing paragraphs of ordinary text is very simple: you just write
12 ordinary text in the ordinary way. You can wrap a paragraph across
13 more than one line using line breaks in the text file, and Halibut
14 will ignore this when it rewraps the paragraph for each output
15 format. To separate paragraphs, use a blank line (i.e. two
16 consecutive line breaks). For example, a fragment of Halibut input
19 \c This is a line of text.
20 \c This is another line of text.
22 \c This line is separated from the previous one by a blank line.
24 will produce two paragraphs looking like this:
27 This is a line of text.
28 This is another line of text.
30 This line is separated from the previous one by a blank line.
33 The first two lines of the input have been merged together into a
34 single paragraph, and the line break in the input file was treated
35 identically to the spaces between the individual words.
37 Halibut is designed to have very few special characters. The only
38 printable characters in Halibut input which will not be treated
39 exactly literally in the output are the backslash (\c{\\}) and the
40 braces (\c{\{} and \c{\}}). If you do not use these characters,
41 \e{everything} else you might type in normal ASCII text is perfectly
42 safe. If you do need to use any of those three characters in your
43 document, you will have to precede each one with a backslash. Hence,
44 for example, you could write
46 \c This \\ is a backslash, and these are \{braces\}.
48 and Halibut would generate the text
51 This \\ is a backslash, and these are \{braces\}.
54 \H{input-inline} Simple inline formatting commands
56 Halibut formatting commands all begin with a backslash, followed by
57 a word or character identifying the command. Some of them then use
58 braces to surround one or more pieces of text acted on by the
59 command. (In fact, the \c{\\\\}, \c{\\\{} and \c{\\\}} sequences you
60 met in \k{input-basics} are themselves formatting commands.)
62 This section describes some simple formatting commands you can use
63 in Halibut documents. The commands in this section are \e{inline}
64 commands, which means you can use them in the middle of a paragraph.
65 \K{input-para} describes some \e{paragraph} commands, which affect a
66 whole paragraph at a time.
68 Many of these commands are followed by a pair of braces surrounding
69 some text. In all cases, it is perfectly safe to have a line break
70 (in the input file) within those braces; Halibut will treat that
71 exactly the same as a space. For example, these two paragraphs will
72 be treated identically:
74 \c Here is some \e{emphasised
77 \c Here is some \e{emphasised text}.
79 \S{input-emph} \c{\\e}: Emphasising text
81 Possibly the most obvious piece of formatting you might want to use
82 in a document is \e{emphasis}. To emphasise text, you use the
83 \c{\\e} command, and follow it up with the text to be emphasised in
84 braces. For example, the first sentence in this paragraph was
85 generated using the Halibut input
87 \c Possibly the most obvious piece of formatting you might want to use
88 \c in a document is \e{emphasis}.
90 \S{input-code} \c{\\c} and \c{\\cw}: Displaying computer code inline
92 Halibut was primarily designed to produce software manuals. It can
93 be used for other types of document as well, but software manuals
96 In software manuals, you often want to format text in a way that
97 indicates that it is something you might see displayed verbatim on
98 a computer screen. In printed manuals, this is typically done by
99 setting that text in a font which is obviously fixed-width. This
100 provides a visual cue that the text being displayed is code, and it
101 also ensures that punctuation marks are clearly separated and shown
102 individually (so that a user can copy the text accurately and
105 Halibut provides \e{two} commands for this, which are subtly
106 different. The names of those commands are \c{\\c} (\q{code}) and
107 \c{\\cw} (\q{weak code}). You use them just like \c{\\e}, by
108 following them with some text in braces. For example, this...
110 \c This sentence contains some \c{code} and some \cw{weak code}.
115 This sentence contains some \c{code} and some \cw{weak code}.
118 The distinction between code and weak code is mainly important when
119 producing plain text output. Plain text output is typically viewed
120 in a fixed-width font, so there is no need (and no way) to change
121 font in order to make the order of punctuation marks clear. However,
122 marking text as code is also \e{sometimes} done to provide a visual
123 distinction between it and the text around it, so that the reader
124 knows where the literal computer text starts and stops; and in plain
125 text, this cannot be done by changing font, so there needs to be an
128 So in the plain text back end, things marked as code (\c{\\c}) will
129 be surrounded by quote marks, so that it's obvious where they start
130 and finish. Things marked as weak code (\c{\\cw}) will not look any
131 different from normal text.
133 I recommend using weak code for any application where it is
134 \e{obvious} that the text is literal computer input or output. For
135 example, if the text is capitalised, that's usually good enough. If
136 I talk about the Pentium's \cw{EAX} and \cw{EDX} registers, for
137 example, you don't need quotes to notice that those are special; so
138 I would write that in Halibut as \q{\c{the Pentium's \\cw\{EAX\} and
139 \\cw\{EDX\} registers}}. But if I'm talking about the Unix command
140 \c{man}, which is an ordinary English word in its own right, a reader
141 might be slightly confused if it appeared in the middle of a
142 sentence undecorated; so I would write that as \q{\c{the Unix command
147 \b \c{\\c} means \q{this text \e{must} be visually distinct from the
148 text around it}. Halibut's various output formats will do this by
149 changing the font if possible, or by using quotes if not.
151 \b \c{\\cw} means \q{it would be nice to display this text in a
152 fixed-width font if possible, but it's not essential}.
154 There is a separate mechanism for displaying computer code in an
155 entire paragraph; see \k{input-codepara} for that one.
157 \S{input-quotes} \c{\\q}: Quotation marks
159 Halibut's various output formats don't all use the same conventions
160 for displaying text in ordinary quotation marks (\q{like these}).
161 Some output formats have access to proper matched quote characters,
162 whereas others are restricted to using plain ASCII. Therefore, it is
163 not ideal to use the ordinary ASCII double quote character in your
164 document (although you can if you like).
166 Halibut provides the formatting command \c{\\q} to indicate quoted
169 \c Here is some \q{text in quotes}.
171 then Halibut will print
174 Here is some \q{text in quotes}.
177 and in every output format Halibut generates, it will choose the
178 best quote characters available to it in that format.
180 You can still use ordinary ASCII double quotes if you prefer; or you
181 could even use the \c{\\u} command (see \k{input-unicode}) to
182 generate Unicode matched double quotes and fall back to the normal
183 ASCII one if they aren't available. But I recommend using the
184 built-in \c{\\q} command in most cases, because it's simple and does
185 the best it can everywhere.
187 (Note that if you're using the \c{\\c} or \c{\\cw} commands to
188 display literal computer code, you probably \e{will} want to use
189 literal ASCII quote characters, because it is likely to matter
190 precisely which quote character you use.)
192 \S{input-nonbreaking} \c{\\-} and \c{\\_}: Non-breaking hyphens and
195 If you use an ordinary hyphen in the middle of a word (such as
196 \q{built-in}), Halibut's output formats will feel free to break a
197 line after that hyphen when wrapping paragraphs. This is fine for a
198 word like \q{built-in}, but if you were displaying some literal
199 computer code such as the Emacs command
200 \c{M\-x\_psychoanalyze\-pinhead}, you might prefer to see the whole
201 hyphenated word treated as an unbreakable block. In some cases, you
202 might even want to prevent the \e{space} in that command from
203 becoming a line break.
205 For these purposes, Halibut provides the commands \c{\\-} and
206 \c{\\_}, which generate a non-breaking hyphen and a non-breaking
207 space respectively. So the above Emacs command might be written as
209 \c the Emacs command \c{M\-x\_psychoanalyze\-pinhead}
211 Unfortunately, some of Halibut's output formats do not support
212 non-breaking hyphens, and others don't support \e{breaking} hyphens!
213 So Halibut cannot promise to honour these commands in all situations.
214 All it can do is make a best effort.
216 \S{input-date} \c{\\date}: Automatic date generation
218 Sometimes you might want your document to give an up-to-date
219 indication of the date on which it was run through Halibut.
221 Halibut supplies the \c{\\date} command to do this. In its simplest
224 \c This document was generated on \date.
226 and Halibut generates something like
229 This document was generated on \date.
232 If you would prefer the date to be generated in a specific format,
233 you can follow the \c{\\date} command with a format specification in
234 braces. The format specification will be run through the standard C
235 function \c{strftime}, so any format acceptable to that function is
236 acceptable here as well. I won't document the format here, because
237 the details vary from computer to computer (although there is a
238 standard core which should be supported everywhere). You should look
239 at your local system's manual for \c{strftime} for details.
241 Here's an example which generates the date in the international
242 standard ISO 8601 format:
244 \c This document was generated on \date{%Y-%m-%d %H:%M:%S}.
246 And here's some sample output from that command:
249 This document was generated on \date{%Y-%m-%d %H:%M:%S}.
252 \S{input-weblink} \c{\\W}: WWW hyperlinks
254 Since one of Halibut's output formats is HTML, it's obviously useful
255 to be able to provide links to arbitrary web sites in a Halibut
258 This is done using the \c{\\W} command. \c{\\W} expects to be
259 followed by \e{two} sets of braces. In the first set of braces you
260 put a URL; in the second set you put the text which should be a
261 hyperlink. For example, you might write
263 \c Try searching on \W{http://www.google.com/}{Google}.
265 and Halibut would generate
268 Try searching on \W{http://www.google.com/}{Google}.
271 Note that hyperlinks, like the non-breaking commands discussed in
272 \k{input-nonbreaking}, are \e{discretionary}: if an output format
273 does not support them then they will just be left out completely. So
274 unless you're \e{only} intending to use the HTML output format, you
275 should avoid storing vital content in the URL part of a \c{\\W}
276 command. The Google example above is reasonable (because most users
277 are likely to be able to find Google for themselves even without a
278 convenient hyperlink leading straight there), but if you really need
279 to direct users to a specific web site, you will need to give the
280 URL in actual displayed text (probably displayed as code as well).
281 However, there's nothing to stop you making it a hyperlink \e{as
282 well} for the convenience of HTML readers.
284 The \c{\\W} command supports a piece of extra syntax to make this
285 convenient for you. You can specify \c{\\c} or \c{\\cw} \e{between}
286 the first and second pairs of braces. For example, you might write
288 \c Google is located at \W{http://www.google.com/}\cw{www.google.com}.
290 and Halibut would produce
293 Google is located at \W{http://www.google.com/}\cw{www.google.com}.
296 \S{input-unicode} \c{\\u}: Specifying arbitrary Unicode characters
298 When Halibut is finished, it should have full Unicode support. You
299 should be able to specify any (reasonably well known) character set
300 for your input document, and Halibut should convert it all to
301 Unicode as it reads it in. Similarly, you should be able to specify
302 the character set you want for each output format and have all the
303 conversion done automatically.
305 Currently, none of this is actually supported. Input text files are
306 assumed to be in ISO 8859-1, and each output format has its own
307 non-configurable character set (although the HTML output can use the
308 \c{Ӓ} mechanism to output any Unicode character it likes).
310 If you need to specify a Unicode character in your input document
311 which is not supported by the input character set, you can use the
312 \c{\\u} command to do this. \c{\\u} expects to be followed by a
313 sequence of hex digits; so that \c{\\u0041}, for example, denotes
314 the Unicode character \cw{0x0041}, which is the capital letter A.
316 If a Unicode character specified in this way is not supported in a
317 particular \e{output} format, you probably don't just want it to be
318 omitted. So you can put a pair of braces after the \c{\\u} command
319 containing fallback text. For example, to specify an amount of money
320 in euros, you might write this:
322 \c This is likely to cost \u20AC{EUR\_}2500 at least.
324 Halibut will render that as a Euro sign \e{if available}, and
325 the text \q{EUR\_} if not. In the output format you're currently
326 reading in, the above input generates this:
329 This is likely to cost \u20AC{EUR\_}2500 at least.
332 If you read it in other formats, you may see different results.
334 \S{input-xref} \c{\\k} and \c{\\K}: Cross-references to other sections
336 \K{intro-features} mentions that Halibut numbers the sections of
337 your document automatically, and can generate cross-references to
338 them on request. \c{\\k} and \c{\\K} are the commands used to
339 generate those cross-references.
341 To use one of these commands, you simply follow it with a pair of
342 braces containing the keyword for the section in question. For
343 example, you might write something like
345 \c \K{input-xref} expands on \k{intro-features}.
347 and Halibut would generate something like
350 \K{input-xref} expands on \k{intro-features}.
353 The keywords \c{input-xref} and \c{intro-features} are section
354 keywords used in this manual itself. In your own document, you would
355 have supplied a keyword for each one of your own sections, and you
356 would provide your own keywords for the \c{\\k} command to work on.
358 The difference between \c{\\k} and \c{\\K} is simply that \c{\\K}
359 starts the cross-reference text with a capital letter; so you would
360 use \c{\\K} at the beginning of a sentence, and \c{\\k} everywhere
363 In output formats which permit it, cross-references act as
364 hyperlinks, so that clicking the mouse on a cross-reference takes
365 you straight to the referenced section.
367 The \c{\\k} commands are also used for referring to entries in a
368 bibliography (see \k{input-biblio} for more about bibliographies),
369 and can also be used for referring to an element of a numbered list
370 by its number (see \k{input-list-number} for more about numbered
373 See \k{input-sections} for more about chapters and sections.
375 \S{input-inline-comment} \c{\\#}: Inline comments
377 If you want to include comments in your Halibut input, to be seen
378 when reading it directly but not copied into the output text, then
379 you can use \c{\\#} to do this. If you follow \c{\\#} with text in
380 braces, that text will be ignored by Halibut.
382 For example, you might write
384 \c The typical behaviour of an antelope \#{do I mean gazelle?} is...
386 and Halibut will simply leave out the aside about gazelles, and will
390 The typical behaviour of an antelope \#{do I mean gazelle?} is...
393 The \c{\\#} command can also be used to produce a whole-paragraph
394 comment; see \k{input-commentpara} for details of that.
396 \H{input-para} Paragraph-level commands
398 This section describes Halibut commands which affect an entire
399 paragraph, or sometimes even \e{more} than one paragraph, at a time.
401 \S{input-codepara} \c{\\c}: Displaying whole paragraphs of computer
404 \K{input-code} describes a mechanism for displaying computer code in
405 the middle of a paragraph, a few words at a time.
407 However, this is often not enough. Often, in a computer manual, you
408 really want to show several lines of code in a display paragraph.
410 This is also done using the \c{\\c} command, in a slightly different
411 way. Instead of using it in the middle of a paragraph followed by
412 braces, you can use it at the start of each line of a paragraph. For
413 example, you could write
415 \c \c #include <stdio.h>
417 \c \c int main(int argc, char **argv) {
418 \c \c printf("hello, world\n");
422 and Halibut would generate
426 \c #include <stdio.h>
428 \c int main(int argc, char **argv) {
429 \c printf("hello, world\n");
435 Note that the above paragraph makes use of a backslash and a pair of
436 braces, and does \e{not} need to escape them in the way described in
437 \k{input-basics}. This is because code paragraphs formatted in this
438 way are a special case; the intention is that you can just copy and
439 paste a lump of code out of another program, put \q{\cw{\\c }} at the
440 start of every line, and simply \e{not have to worry} about the
441 details - you don't have to go through the whole block looking for
442 characters to escape.
444 Since a backslash inside a code paragraph generates a literal
445 backslash, this means you cannot use any other Halibut formatting
446 commands inside a code paragraph. In particular, if you want to
447 emphasise a particular word in the paragraph, you can't do that
448 using \c{\\e} (\k{input-emph}) in the normal way.
450 Therefore, Halibut provides an alternative means of emphasis in code
451 paragraphs. Each line beginning with \c{\\c} can optionally be
452 followed by a single line beginning with \c{\\e}, indicating the
453 emphasis in that line. The emphasis line contains the letters \c{b}
454 and \c{i} (for \q{bold} and \q{italic}, although some output formats
455 might render \c{i} as underlining instead of italics), positioned
456 to line up under the parts of the text that you want emphasised.
458 For example, if you wanted to do syntax highlighting on the above C
459 code by highlighting the preprocessor command in italic and the
460 keywords in bold, you might do it like this:
462 \c \c #include <stdio.h>
463 \c \e iiiiiiiiiiiiiiiiii
465 \c \c int main(int argc, char **argv) {
467 \c \c printf("hello, world\n");
472 and Halibut would generate:
476 \c #include <stdio.h>
477 \e iiiiiiiiiiiiiiiiii
479 \c int main(int argc, char **argv) {
481 \c printf("hello, world\n");
488 Note that not every \c{\\c} line has to be followed by a \c{\\e}
489 line; they're optional.
491 Also, note that highlighting within a code paragraph is
492 \e{discretionary}. Not all of Halibut's output formats can support
493 it (plain text, in particular, has no sensible way to do it). Unless
494 you know you are using a restricted range of output formats, you
495 should use highlighting in code paragraphs \e{only} as a visual aid,
496 and not rely on it to convey any vital semantic content.
498 \S{input-lists} \c{\\b}, \c{\\n}, \c{\\dt}, \c{\\dd}, \c{\\lcont}: Lists
500 Halibut supports bulletted lists, numbered lists and description
503 \S2{input-list-bullet} \c{\\b}: Bulletted lists
505 To create a bulletted list, you simply prefix each paragraph
506 describing a bullet point with the command \c{\\b}. For example, this
517 would produce this Halibut output:
529 \S2{input-list-number} \c{\\n}: Numbered lists
531 Numbered lists are just as simple: instead of \c{\\b}, you use
532 \c{\\n}, and Halibut takes care of getting the numbering right for
543 This produces the Halibut output:
555 The disadvantage of having Halibut sort out the list numbering for
556 you is that if you need to refer to a list item by its number, you
557 can't reliably do so. To get round this, Halibut allows an optional
558 keyword in braces after the \c{\\n} command. This keyword can then
559 be referenced using the \c{\\k} or \c{\\K} command (see
560 \k{input-xref}) to provide the number of the list item. For example:
570 \c \n Now go back to step \k{this-one}.
572 This produces the following output:
583 \n Now go back to step \k{this-one}.
586 \S2{input-list-description} \c{\\dt} and \c{\\dd}: Description lists
588 To wrie a description list, you prefix alternate paragraphs with the
589 \c{\\dt} (\q{described thing}) and \c{\\dd} (description) commands.
594 \c \dd This is a large bird with a big beak.
600 This produces the following output:
606 \dd This is a large bird with a big beak.
614 \S2{input-list-continuation} Continuing list items into further
617 All three of the above list types assume that each list item is a
618 single paragraph. For a short, snappy list in which each item is
619 likely to be only one or two words, this is perfectly sufficient;
620 but occasionally you will find you want to include several
621 paragraphs in a single list item, or even to nest other types of
622 paragraph (such as code paragraphs, or other lists) inside a list
625 To do this, you use the \c{\\lcont} command. This is a command which
626 can span \e{multiple} paragraphs.
628 After the first paragraph of a list item, include the text
629 \c{\\lcont\{}. This indicates that the subsequent paragraph(s) are a
630 \e{continuation} of the list item that has just been seen. So you
631 can include further paragraphs, and eventually include a closing
632 brace \c{\}} to finish the list continuation. After that, you can
633 either continue adding other items to the original list, or stop
634 immediately and return to writing normal paragraphs of text.
636 Here's a (long) example.
640 \c \n One. This item is followed by a code paragraph:
649 \c \n Two. Now when I say \q{two}, I mean:
657 \c \n Two, part three.
663 The output produced by this fragment is:
669 \n One. This item is followed by a code paragraph:
678 \n Two. Now when I say \q{two}, I mean:
694 This syntax seems a little bit inconvenient, and perhaps
695 counter-intuitive: you might expect the enclosing braces to have to
696 go around the \e{whole} list item, rather than everything except the
699 \c{\\lcont} is a recent addition to the Halibut input language;
700 previously, \e{all} lists were required to use no more than one
701 paragraph per list item. So it's certainly true that this feature
702 looks like an afterthought because it \e{is} an afterthought, and
703 it's possible that if I'd been designing the language from scratch
704 with multiple-paragraph list items in mind, I would have made it
707 However, the advantage of doing it this way is that no enclosing
708 braces are required in the \e{common} case: simple lists with only
709 one paragraph per item are really, really easy to write. So I'm not
710 too unhappy with the way it turned out; it obeys the doctrine of
711 making simple things simple, and difficult things possible.
713 Note that \c{\\lcont} can only be used on \c{\\b}, \c{\\n} and
714 \c{\\dd} paragraphs; it cannot be used on \c{\\dt}.
716 \S{input-rule} \c{\\rule}: Horizontal rules
718 The command \c{\\rule}, appearing on its own as a paragraph, will
719 cause a horizontal rule to be drawn, like this:
727 This produces the following output:
739 \S{input-quote} \c{\\quote}: Indenting multiple paragraphs as a long
742 Quoting verbatim text using a code paragraph (\k{input-codepara}) is
743 not always sufficient for your quoting needs. Sometimes you need to
744 quote some normally formatted text, possibly in multiple paragraphs.
746 To do this, you can use the \c{\\quote} command. Like \c{\\lcont},
747 this is a command which expects to enclose at least one paragraph
748 and possibly more. Simply write \c{\\quote\{} at the beginning of
749 your quoted section, and \c{\}} at the end, and the paragraphs in
750 between will be formatted to indicate that they are a quotation.
752 (This very manual, in fact, uses this feature a lot: all of the
753 examples of Halibut source followed by Halibut output have the
754 output quoted using \c{\\quote}.)
756 Here's some example Halibut input:
758 \c In \q{Through the Looking Glass}, Lewis Carroll wrote:
762 \c \q{The question is,} said Alice, \q{whether you \e{can} make
763 \c words mean so many different things.}
765 \c \q{The question is,} said Humpty Dumpty, \q{who is to be master -
772 The output generated by this is:
776 In \q{Through the Looking Glass}, Lewis Carroll wrote:
780 \q{The question is,} said Alice, \q{whether you \e{can} make
781 words mean so many different things.}
783 \q{The question is,} said Humpty Dumpty, \q{who is to be master -
792 \S{input-sections} \c{\\C}, \c{\\H}, \c{\\S}, \c{\\A}, \c{\\U}:
793 Chapter and section headings
795 \K{intro-features} mentions that Halibut numbers the sections of
796 your document automatically, and can generate cross-references to
797 them on request; \k{input-xref} describes the \c{\\k} and \c{\\K}
798 commands used to generate the cross-references. This section
799 describes the commands used to set up the sections in the first
802 A paragraph beginning with the \c{\\C} command defines a chapter
803 heading. The \c{\\C} command expects to be followed by a pair of
804 braces containing a keyword for the chapter; this keyword can then
805 be used with the \c{\\k} and \c{\\K} commands to generate
806 cross-references to the chapter. After the closing brace, the rest
807 of the paragraph is used as the displayed chapter title. So the
808 heading for the current chapter of this manual, for example, is
811 \c \C{input} Halibut input format
813 and this allows me to use the command \c{\\k\{input\}} to generate a
814 cross-reference to that chapter somewhere else.
816 The next level down from \c{\\C} is \c{\\H}, for \q{heading}. This
817 is used in exactly the same way as \c{\\C}, but section headings
818 defined with \c{\\H} are considered to be part of a containing
819 chapter, and will be numbered with a pair of numbers. After \c{\\H}
820 comes \c{\\S}, and if necessary you can then move on to \c{\\S2},
823 For example, here's a sequence of heading commands. Normally these
824 commands would be separated at least by blank lines (because each is
825 a separate paragraph), and probably also by body text; but for the
826 sake of brevity, both of those have been left out in this example.
829 \c \H{foo-intro} Introduction to Foo
830 \c \H{foo-running} Running the Foo program
831 \c \S{foo-inter} Running Foo interactively
832 \c \S{foo-batch} Running Foo in batch mode
833 \c \H{foo-trouble} Troubleshooting Foo
834 \c \C{bar} Using Bar instead of Foo
836 This would define two chapters with keywords \c{foo} and \c{bar},
837 which would end up being called Chapter 1 and Chapter 2 (unless
838 there were other chapters before them). The sections \c{foo-intro},
839 \c{foo-running} and \c{foo-trouble} would be referred to as Section
840 1.1, Section 1.2 and Section 1.3 respectively; the subsections
841 \c{foo-inter} and \c{foo-batch} would be Section 1.2.1 and Section
842 1.2.2. If there had been a \c{\\S2} command within one of those, it
843 would have been something like Section 1.2.1.1.
845 If you don't like the switch from \c{\\H} to \c{\\S}, you can use
846 \c{\\S1} as a synonym for \c{\\S} and \c{\\S0} as a synonym for
847 \c{\\H}. Chapters are still designated with \c{\\C}, because they
848 need to be distinguished from other types of chapter such as
849 appendices. (Personally, I like the \c{\\C},\c{\\H},\c{\\S} notation
850 because it encourages me to think of my document as a hard disk :-)
852 You can define an appendix by using \c{\\A} in place of \c{\\C}.
853 This is no different from a chapter except that it's given a letter
854 instead of a number, and cross-references to it will say \q{Appendix
855 A} instead of \q{Chapter 9}. Subsections of an appendix will be
856 numbered \q{A.1}, \q{A.2}, \q{A.2.1} and so on.
858 If you want a particular section to be referred to as something
859 other than a \q{chapter}, \q{section} or \q{appendix}, you can
860 include a second pair of braces after the keyword. For example, if
861 you're writing a FAQ chapter and you want cross-references between
862 questions to refer to \q{question 1.2.3} instead of \q{section
863 1.2.3}, you can write each section heading as
865 \c \S{question-about-fish}{Question} What about fish?
867 (The word \q{Question} should be given with an initial capital
868 letter. Halibut will lower-case it when you refer to it using
869 \c{\\k}, and will leave it alone if you use \c{\\K}.)
871 This technique allows you to change the designation of
872 \e{particular} sections. To make an overall change in what \e{every}
873 section is called, see \k{input-config}.
875 Finally, the \c{\\U} command defines an \e{unnumbered} chapter.
876 These sometimes occur in books, for specialist purposes such as
877 \q{Bibliography} or \q{Acknowledgements}. \c{\\U} does not expect a
878 keyword argument, because there is no sensible way to generate an
879 automatic cross-reference to such a chapter anyway.
881 \S{input-blurb} \c{\\copyright}, \c{\\title}, \c{\\versionid}:
882 Miscellaneous blurb commands
884 These three commands define a variety of special paragraph types.
885 They are all used in the same way: you put the command at the start
886 of a paragraph, and then just follow it with normal text, like this:
888 \c \title My First Manual
890 The three special paragraph types are:
894 \dd This defines the overall title of the entire document. This
895 title is treated specially in some output formats (for example, it's
896 used in a \cw{<title>} tag in the HTML output), so it needs a
897 special paragraph type to point it out.
901 \dd This command indicates that the paragraph attached to it
902 contains a copyright statement for the document. This text is
903 usually displayed inline, just before the first chapter title but
904 after any preamble text before that; but in some output formats it
905 is given additional special treatment. For example, Windows Help
906 files have a standard slot in which to store a copyright notice, so
907 that other software can display it prominently.
911 \dd This command indicates that the paragraph contains a version
912 identifier, such as those produced by CVS (of the form \c{$\#{hope this
913 defuses CVS}Id: thingy.but,v 1.6 2004/01/01 16:47:48 simon Exp $}).
914 This text will be tucked away somewhere unobtrusive, so that anyone
915 wanting to (for example) report errors to the document's author can
916 pick out the version IDs and send them as part of the report, so
917 that the author can tell at a glance which revision of the document
920 \S{input-commentpara} \c{\\#}: Whole-paragraph comments
922 \K{input-inline-comment} describes the use of the \c{\\#} command to
923 put a short comment in the middle of a paragraph.
925 If you need to use a \e{long} comment, Halibut also allows you to
926 use \c{\\#} without braces, to indicate that an entire paragraph is
927 a comment, like this:
929 \c Here's a (fairly short) paragraph which will be displayed.
931 \c \# Here's a comment paragraph which will not be displayed, no
932 \c matter how long it goes on. All I needed to indicate this was the
933 \c single \# at the start of the paragraph; I don't need one on
934 \c every line or anything like that.
936 \c Here's another displayed paragraph.
938 When run through Halibut, this produces the following output:
942 Here's a (fairly short) paragraph which will be displayed.
944 \# Here's a comment paragraph which will not be displayed, no
945 matter how long it goes on. All I needed to indicate this was the
946 single \# at the start of the paragraph; I don't need one on
947 every line or anything like that.
949 Here's another displayed paragraph.
953 \H{input-biblio} Creating a bibliography
955 If you need your document to refer to other documents (research
956 papers, books, websites, whatever), you might find a bibliography
959 You can define a bibliography entry using the \c{\\B} command. This
960 looks very like the \c{\\C} command and friends: it expects a
961 keyword in braces, followed by some text describing the document
962 being referred to. For example:
964 \c \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
965 \c Published by Paperjam & Notoner, 1993.
967 If this bibliography entry appears in the finished document, it will
968 look something like this:
972 \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
973 Published by Paperjam & Notoner, 1993.
977 I say \q{if} above because not all bibliography entries defined
978 using the \c{\\B} command will necessarily appear in the finished
979 document. They only appear if they are referred to by a \c{\\k}
980 command (see \k{input-xref}). This allows you to (for example)
981 maintain a single Halibut source file with a centralised database of
982 \e{all} the references you have ever needed in any of your writings,
983 include that file in every document you feed to Halibut, and have it
984 only produce the bibliography entries you actually need for each
985 particular document. (In fact, you might even want this centralised
986 source file to be created automatically by, say, a Perl script from
987 BibTeX input, so that you can share the same bibliography with users
988 of other formatting software.)
990 If you really want a bibliography entry to appear in the document
991 even though no text explicitly refers to it, you can do that using
992 the \c{\\nocite} command:
994 \c \nocite{freds-book}
996 Normally, each bibliography entry will be referred to (in citations
997 and in the bibliography itself) by a simple reference number, such
998 as \k{freds-book}. If you would rather use an alternative reference
999 notation, such as [Fred1993], you can use the \c{\\BR}
1000 (\q{Bibliography Rewrite}) command to specify your own reference
1001 format for a particular book:
1003 \c \BR{freds-book} [Fred1993]
1005 \H{input-index} Creating an index
1007 Halibut contains a comprehensive indexing mechanism, which attempts
1008 to be reasonably easy to use in the common case in spite of its
1011 \S{input-index-simple} Simple indexing
1013 In normal usage, you should be able to add index terms to your
1014 document simply by using the \c{\\i} command to wrap one or two
1015 words at a time. For example, if you write
1017 \c The \i{hippopotamus} is a particularly large animal.
1019 then the index will contain an entry under \q{hippopotamus},
1020 pointing to that sentence (or as close to that sentence as the
1021 output format sensibly permits).
1023 You can wrap more than one word in \c{\\i} as well:
1025 \c We recommend using a \i{torque wrench} for this job.
1027 \S{input-index-special} Special cases of indexing
1029 If you need to index a computer-related term, you can use the
1030 special case \c{\\i\\c} (or \c{\\i\\cw} if you prefer):
1032 \c The \i\c{grep} command is what you want here.
1034 This will cause the word \q{grep} to appear in code style, as if the
1035 \c{\\i} were not present and the input just said \c{\\c\{grep\}};
1036 the word will also appear in code style in the actual index.
1038 If you want to simultaneously index and emphasise a word, there's
1039 another special case \c{\\i\\e}:
1041 \c This is what we call a \i\e{paper jam}.
1043 This will cause the words \q{paper jam} to be emphasised in the
1044 document, but (unlike the behaviour of \c{\\i\\c}) they will \e{not}
1045 be emphasised in the index. This different behaviour is based on an
1046 expectation that most people indexing a word of computer code will
1047 still want it to look like code in the index, whereas most people
1048 indexing an emphasised word will \e{not} want it emphasised in the
1051 Sometimes you might want to index a term which is not explicitly
1052 mentioned, but which is highly relevant to the text and you think
1053 that somebody looking up that term in the index might find it useful
1054 to be directed here. To do this you can use the \c{\\I} command, to
1055 create an \e{invisible} index tag:
1057 \c If your printer runs out of toner, \I{replacing toner
1058 \c cartridge}here is what to do:
1060 This input will produce only the output \q{If your printer runs out
1061 of toner, here is what to do}; but an index entry will show up under
1062 \q{replacing toner cartridge}, so that if a user thinks the obvious
1063 place to start in the index is under R for \q{replacing}, they will
1064 find their way here with a minimum of fuss.
1066 (It's worth noting that there is no functional difference between
1067 \c{\\i\{foo\}} and \c{\\I\{foo\}foo}. The simple \c{\\i} case is
1068 only a shorthand for the latter.)
1070 Finally, if you want to index a word at the start of a sentence, you
1071 might very well not want it to show up with a capital letter in the
1072 index. For this, Halibut provides the \c{\\ii} command, for \q{index
1073 (case-)insensitively}. You use it like this:
1075 \c \ii{Lions} are at the top of the food chain in this area.
1077 This is equivalent to \c{\\I\{lions\}Lions}; in other words, the
1078 text will say \q{Lions}, but it will show up in the index as
1079 \q{lions}. The text inside \c{\\ii} is converted entirely into lower
1080 case before being added to the index data.
1082 \S{input-index-rewrite} Fine-tuning the index
1084 Halibut's index mechanism as described so far still has a few
1087 \b In a reasonably large index, it's often difficult to predict
1088 which of several words a user will think of first when trying to
1089 look something up. For example, if they want to know how to replace
1090 a toner cartridge, they might look up \q{replacing} or they might
1091 look up \q{toner cartridge}. You probably don't really want to have
1092 to try to figure out which of those is more likely; instead, what
1093 you'd like is to be able to effortlessly index the same set of
1094 document locations under \e{both} terms.
1096 \b Also, you may find you've indexed the same concept under multiple
1097 different index terms; for example, there might be several instances
1098 of \c{\\i\{frog\}} and several of \c{\\i\{frogs\}}, so that you'd
1099 end up with two separate index entries for what really ought to be
1102 \b You might well not want the word \q{\cw{grep}} to appear in the
1103 index without explanation; you might prefer it to say something more
1104 verbose such as \q{\cw{grep} command}, so that a user encountering
1105 it in the index has some idea of what it is \e{without} having to
1106 follow up the reference. However, you certainly don't want to have
1107 to write \c{\\I\{\\cw\{grep\} command\}\\c\{grep\}} every time you
1108 want to add an index term for this! You wanted to write
1109 \c{\\i\\c\{grep\}} as shown in the previous section, and tidy it all
1112 All of these problems can be cleaned up by the \c{\\IM} (for
1113 \q{Index Modification}) command. \c{\\IM} expects to be followed by
1114 one or more pairs of braces containing index terms as seen in the
1115 document, and then a piece of text (not in braces) describing how it
1116 should be shown in the index.
1118 So to rewrite the \c{grep} example above, you might do this:
1120 \c \IM{grep} \cw{grep} command
1122 This will arrange that the set of places in the document where you
1123 asked Halibut to index \q{\cw{grep}} will be listed under
1124 \q{\cw{grep} command} rather than just under \q{\cw{grep}}.
1126 You can specify more than one index term in a \c{\\IM} command; so
1127 to merge the index terms \q{frog} and \q{frogs} into a single term,
1130 \c \IM{frog}{frogs} frog
1132 This will arrange that the single index entry \q{frog} will list
1133 \e{all} the places in the document where you asked Halibut to index
1134 either \q{frog} or \q{frogs}.
1136 You can use multiple \c{\\IM} commands to replicate the same set of
1137 document locations in more than one index entry. For example:
1139 \c \IM{replacing toner cartridge} replacing toner cartridge
1140 \c \IM{replacing toner cartridge} toner cartridge, replacing
1142 This will arrange that every place in the document where you have
1143 indexed \q{replacing toner cartridge} will be listed both there
1144 \e{and} under \q{toner cartridge, replacing}, so that no matter
1145 whether the user looks under R or under T they will stil find their
1146 way to the same parts of the document.
1148 In this example, note that although the first \c{\\IM} command
1149 \e{looks} as if it's a tautology, it is still necessary, because
1150 otherwise those document locations will \e{only} be indexed under
1151 \q{toner cartridge, replacing}. If you have \e{no} explicit \c{\\IM}
1152 commands for a particular index term, then Halibut will assume a
1153 default one (typically \c{\\IM\{foo\}\_foo}, although it might be
1154 \c{\\IM\{foo\}\_\\c\{foo\}} if you originally indexed using
1155 \c{\\i\\c}); but as soon as you specify an explicit \c{\\IM},
1156 Halibut discards its default implicit one, and you must then specify
1157 that one explicitly as well if you wanted to keep it.
1159 \H{input-config} Configuring Halibut
1161 Halibut uses the \c{\\cfg} command to allow you to configure various
1162 aspects of its functionality.
1164 The \c{\\cfg} command expects to be followed by at least one pair of
1165 braces, and usually more after that. The first pair of braces
1166 contains a keyword indicating what aspect of Halibut you want to
1167 configure, and the meaning of the one(s) after that depends on the
1170 The current list of configuration keywords in the main Halibut code
1171 is quite small. Here it is in full:
1173 \dt \cw{\\cfg\{chapter\}\{}\e{new chapter name}\cw{\}}
1175 \dd This tells Halibut that you don't want to call a chapter a
1176 chapter any more. For example, if you give the command
1177 \cw{\\cfg\{chapter\}\{Book\}}, then any chapter defined with the
1178 \c{\\C} command will be labelled \q{Book} rather than \q{Chapter},
1179 both in the section headings and in cross-references. This is
1180 probably most useful if your document is not written in English.
1182 \dt \cw{\\cfg\{section\}\{}\e{new section name}\cw{\}}
1184 \dd Exactly like \c{chapter}, but changes the name given to
1185 subsections of a chapter.
1187 \dt \cw{\\cfg\{appendix\}\{}\e{new appendix name}\cw{\}}
1189 \dd Exactly like \c{appendix}, but changes the name given to
1192 In addition to these configuration commands, there are also
1193 configuration commands provided by each individual output format.
1194 These configuration commands are discussed along with each output
1195 format, in \k{output}.
1197 \H{input-macro} Defining macros
1199 If there's a complicated piece of Halibut source which you think
1200 you're going to use a lot, you can define your own Halibut command
1201 to produce that piece of source.
1203 In \k{input-unicode}, there is a sample piece of code which prints a
1204 Euro sign, or replaces it with \q{EUR} if the Euro sign is not
1207 \c This is likely to cost \u20AC{EUR\_}2500 at least.
1209 If your document quotes a \e{lot} of prices in Euros, you might not
1210 want to spend all your time typing that out. So you could define a
1211 macro, using the \c{\\define} command:
1213 \c \define{eur} \u20AC{EUR\_}
1215 Then you can just write ...
1217 \c This is likely to cost \eur 2500 at least.
1219 ... except that that's not terribly good, because you end up with a
1220 space between the Euro sign and the number. In this case, it's
1221 helpful to use the special \c{\\.} command, which is defined to do
1222 nothing at all! But it acts as a separator between your macro and
1225 \c This is likely to cost \eur\.2500 at least.
1227 This way, you will see no space between the Euro sign and the number
1228 (although, of course, there will be space between \q{EUR} and the
1229 number if the Euro sign is not available, because the macro
1230 definition specifically asked for it).