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 \i{paragraphs of ordinary text} is very simple: you just
12 write ordinary text in the ordinary way. You can wrap a paragraph
13 across more than one line using \i{line breaks} in the text file,
14 and Halibut will ignore this when it \I{wrapping paragraphs}rewraps
15 the paragraph for each output format. To separate paragraphs, use a
16 \i{blank line} (i.e. two consecutive line breaks). For example, a
17 fragment of Halibut input looking like this:
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 \I{escaping, special
38 characters}\i{special characters}. The only printable characters in
39 Halibut input which will not be treated exactly literally in the
40 output are the \i{backslash} (\c{\\}) and the \i{braces} (\c{\{} and
41 \c{\}}). If you do not use these characters, \e{everything} else you
42 might type in normal ASCII text is perfectly safe. If you do need to
43 use any of those three characters in your document, you will have to
44 precede each one with a backslash. Hence, for example, you could
47 \c This \\ is a backslash, and these are \{braces\}.
49 and Halibut would generate the text
52 This \\ is a backslash, and these are \{braces\}.
55 \H{input-inline} Simple \i{inline formatting commands}
57 Halibut formatting commands all begin with a backslash, followed by
58 a word or character identifying the command. Some of them then use
59 braces to surround one or more pieces of text acted on by the
60 command. (In fact, the \c{\\\\}, \c{\\\{} and \c{\\\}} sequences you
61 met in \k{input-basics} are themselves formatting commands.)
63 This section describes some simple formatting commands you can use
64 in Halibut documents. The commands in this section are \e{inline}
65 commands, which means you can use them in the middle of a paragraph.
66 \K{input-para} describes some \e{paragraph} commands, which affect a
67 whole paragraph at a time.
69 Many of these commands are followed by a pair of braces surrounding
70 some text. In all cases, it is perfectly safe to have a \i{line break}
71 (in the input file) within those braces; Halibut will treat that
72 exactly the same as a space. For example, these two paragraphs will
73 be treated identically:
75 \c Here is some \e{emphasised
78 \c Here is some \e{emphasised text}.
80 \S{input-emph} \c{\\e}: Emphasising text
82 Possibly the most obvious piece of formatting you might want to use
83 in a document is \i\e{emphasis}. To emphasise text, you use the
84 \i\c{\\e} command, and follow it up with the text to be emphasised
85 in braces. For example, the first sentence in this paragraph was
86 generated using the Halibut input
88 \c Possibly the most obvious piece of formatting you might want to use
89 \c in a document is \e{emphasis}.
91 \S{input-code} \c{\\c} and \c{\\cw}: Displaying \i{computer code} inline
93 Halibut was primarily designed to produce software manuals. It can
94 be used for other types of document as well, but software manuals
97 In software manuals, you often want to format text in a way that
98 indicates that it is something you might see displayed \i{verbatim}
99 on a computer screen. In printed manuals, this is typically done by
100 setting that text in a font which is obviously \I{fixed-width
101 font}fixed-width. This provides a visual cue that the text being
102 displayed is code, and it also ensures that punctuation marks are
103 clearly separated and shown individually (so that a user can copy
104 the text accurately and conveniently).
106 Halibut provides \e{two} commands for this, which are subtly
107 different. The names of those commands are \i\c{\\c} (\q{code}) and
108 \i\c{\\cw} (\q{\i{weak code}}). You use them just like \c{\\e}, by
109 following them with some text in braces. For example, this...
111 \c This sentence contains some \c{code} and some \cw{weak code}.
116 This sentence contains some \c{code} and some \cw{weak code}.
119 The distinction between code and weak code is mainly important when
120 producing plain text output. Plain text output is typically viewed
121 in a fixed-width font, so there is no need (and no way) to change
122 font in order to make the order of punctuation marks clear. However,
123 marking text as code is also \e{sometimes} done to provide a visual
124 distinction between it and the text around it, so that the reader
125 knows where the literal computer text starts and stops; and in plain
126 text, this cannot be done by changing font, so there needs to be an
129 So in the plain text output format, things marked as code (\c{\\c})
130 will be surrounded by quote marks, so that it's obvious where they
131 start and finish. Things marked as weak code (\c{\\cw}) will not
132 look any different from normal text.
134 I recommend using weak code for any application where it is
135 \e{obvious} that the text is literal computer input or output. For
136 example, if the text is capitalised, that's usually good enough. If
137 I talk about the Pentium's \cw{EAX} and \cw{EDX} registers, for
138 example, you don't need quotes to notice that those are special; so
139 I would write that in Halibut as \q{\c{the Pentium's \\cw\{EAX\} and
140 \\cw\{EDX\} registers}}. But if I'm talking about the Unix command
141 \c{man}, which is an ordinary English word in its own right, a reader
142 might be slightly confused if it appeared in the middle of a
143 sentence undecorated; so I would write that as \q{\c{the Unix command
148 \b \c{\\c} means \q{this text \e{must} be visually distinct from the
149 text around it}. Halibut's various output formats will do this by
150 changing the font if possible, or by using quotes if not.
152 \b \c{\\cw} means \q{it would be nice to display this text in a
153 fixed-width font if possible, but it's not essential}.
155 There is a separate mechanism for displaying computer code in an
156 entire paragraph; see \k{input-codepara} for that one.
158 \S{input-quotes} \c{\\q}: \ii{Quotation marks}
160 Halibut's various output formats don't all use the same conventions
161 for displaying text in ordinary quotation marks (\q{like these}).
162 Some output formats have access to proper matched quote characters,
163 whereas others are restricted to using plain ASCII. Therefore, it is
164 not ideal to use the ordinary ASCII double quote character in your
165 document (although you can if you like).
167 Halibut provides the formatting command \i\c{\\q} to indicate quoted
170 \c Here is some \q{text in quotes}.
172 then Halibut will print
175 Here is some \q{text in quotes}.
178 and in every output format Halibut generates, it will choose the
179 best quote characters available to it in that format.
181 You can still use ordinary ASCII \i{double quotes} if you prefer; or
182 you could even use the \c{\\u} command (see \k{input-unicode}) to
183 generate \i{Unicode matched quotes} (single or double) and fall back
184 to the normal ASCII one if they aren't available. But I recommend
185 using the built-in \c{\\q} command in most cases, because it's
186 simple and does the best it can everywhere.
188 (Note that if you're using the \c{\\c} or \c{\\cw} commands to
189 display literal computer code, you probably \e{will} want to use
190 literal \i{ASCII quote characters}, because it is likely to matter
191 precisely which quote character you use.)
193 \S{input-nonbreaking} \c{\\-} and \c{\\_}: \ii{Non-breaking hyphens}
194 and \I{non-breaking spaces}spaces
196 If you use an ordinary hyphen in the middle of a word (such as
197 \q{built-in}), Halibut's output formats will feel free to break a
198 line after that hyphen when \i{wrapping paragraphs}. This is fine
199 for a word like \q{built-in}, but if you were displaying some
200 literal computer code such as the Emacs command
201 \c{M\-x\_psychoanalyze\-pinhead}, you might prefer to see the whole
202 hyphenated word treated as an unbreakable block. In some cases, you
203 might even want to prevent the \e{space} in that command from
204 becoming a line break.
206 For these purposes, Halibut provides the commands \i\c{\\-} and
207 \i\c{\\_}, which generate a non-breaking hyphen and a non-breaking
208 space respectively. So the above Emacs command might be written as
210 \c the Emacs command \c{M\-x\_psychoanalyze\-pinhead}
212 Unfortunately, some of Halibut's output formats do not support
213 non-breaking hyphens, and others don't support \e{breaking} hyphens!
214 So Halibut cannot promise to honour these commands in all situations.
215 All it can do is make a best effort.
217 \S{input-date} \c{\\date}: Automatic \i{date} generation
219 Sometimes you might want your document to give an up-to-date
220 indication of the date on which it was run through Halibut.
222 Halibut supplies the \i\c{\\date} command to do this. In its
223 simplest form, you simply say
225 \c This document was generated on \date.
227 and Halibut generates something like
230 This document was generated on \date.
233 If you would prefer the date to be generated in a specific format,
234 you can follow the \c{\\date} command with a format specification in
235 braces. The format specification will be run through the standard C
236 function \i\c{strftime}, so any format acceptable to that function
237 is acceptable here as well. I won't document the format here,
238 because the details vary from computer to computer (although there
239 is a standard core which should be supported everywhere). You should
240 look at your local system's manual for \c{strftime} for details.
242 Here's an example which generates the date in the international
243 standard \i{ISO 8601} format:
245 \c This document was generated on \date{%Y-%m-%d %H:%M:%S}.
247 And here's some sample output from that command:
250 This document was generated on \date{%Y-%m-%d %H:%M:%S}.
253 \S{input-weblink} \c{\\W}: \i{WWW hyperlinks}
255 Since one of Halibut's output formats is \i{HTML}, it's obviously
256 useful to be able to provide \I{linking to web sites}links to
257 arbitrary \i{web sites} in a Halibut document.
259 This is done using the \i\c{\\W} command. \c{\\W} expects to be
260 followed by \e{two} sets of braces. In the first set of braces you
261 put a \i{URL}; in the second set you put the text which should be a
262 \i{hyperlink}. For example, you might write
264 \c Try searching on \W{http://www.google.com/}{Google}.
266 and Halibut would generate
269 Try searching on \W{http://www.google.com/}{Google}.
272 Note that hyperlinks, like the non-breaking commands discussed in
273 \k{input-nonbreaking}, are \e{discretionary}: if an output format
274 does not support them then they will just be left out completely. So
275 unless you're \e{only} intending to use the HTML output format, you
276 should avoid storing vital content in the URL part of a \c{\\W}
277 command. The Google example above is reasonable (because most users
278 are likely to be able to find Google for themselves even without a
279 convenient hyperlink leading straight there), but if you really need
280 to direct users to a specific web site, you will need to give the
281 URL in actual displayed text (probably displayed as code as well).
282 However, there's nothing to stop you making it a hyperlink \e{as
283 well} for the convenience of HTML readers.
285 The \c{\\W} command supports a piece of extra syntax to make this
286 convenient for you. You can specify \c{\\c} or \c{\\cw} \e{between}
287 the first and second pairs of braces. For example, you might write
289 \c Google is located at \W{http://www.google.com/}\cw{www.google.com}.
291 and Halibut would produce
294 Google is located at \W{http://www.google.com/}\cw{www.google.com}.
297 \S{input-unicode} \c{\\u}: Specifying arbitrary \i{Unicode}
300 When Halibut is finished, it should have full Unicode support. You
301 should be able to specify any (reasonably well known) \i{character
302 set} for your input document, and Halibut should convert it all to
303 Unicode as it reads it in. Similarly, you should be able to specify
304 the character set you want for each output format and have all the
305 conversion done automatically.
307 Currently, none of this is actually supported. Input text files are
308 assumed to be in \i{ISO 8859-1}, and each output format has its own
309 non-configurable character set (although the HTML output can use the
310 \c{Ӓ} mechanism to output any Unicode character it likes).
312 If you need to specify a Unicode character in your input document
313 which is not supported by the input character set, you can use the
314 \i\c{\\u} command to do this. \c{\\u} expects to be followed by a
315 sequence of hex digits; so that \c{\\u0041}, for example, denotes
316 the Unicode character \cw{0x0041}, which is the capital letter A.
318 If a Unicode character specified in this way is not supported in a
319 particular \e{output} format, you probably don't just want it to be
320 omitted. So you can put a pair of braces after the \c{\\u} command
321 containing \i{fallback text}. For example, to specify an amount of
322 money in euros, you might write this:
324 \c This is likely to cost \u20AC{EUR\_}2500 at least.
326 Halibut will render that as a Euro sign \e{if available}, and
327 the text \q{EUR\_} if not. In the output format you're currently
328 reading in, the above input generates this:
331 This is likely to cost \u20AC{EUR\_}2500 at least.
334 If you read it in other formats, you may see different results.
336 \S{input-xref} \i\c{\\k} and \i\c{\\K}: \ii{Cross-references} to
339 \K{intro-features} mentions that Halibut \I{section numbers}numbers
340 the sections of your document automatically, and can generate
341 cross-references to them on request. \c{\\k} and \c{\\K} are the
342 commands used to generate those cross-references.
344 To use one of these commands, you simply follow it with a pair of
345 braces containing the keyword for the section in question. For
346 example, you might write something like
348 \c \K{input-xref} expands on \k{intro-features}.
350 and Halibut would generate something like
353 \K{input-xref} expands on \k{intro-features}.
356 The \i{keywords} \c{input-xref} and \c{intro-features} are
357 \i{section keywords} used in this manual itself. In your own
358 document, you would have supplied a keyword for each one of your own
359 sections, and you would provide your own keywords for the \c{\\k}
362 The difference between \c{\\k} and \c{\\K} is simply that \c{\\K}
363 starts the cross-reference text with a capital letter; so you would
364 use \c{\\K} at the beginning of a sentence, and \c{\\k} everywhere
367 In output formats which permit it, cross-references act as
368 \i{hyperlinks}, so that clicking the mouse on a cross-reference
369 takes you straight to the referenced section.
371 The \c{\\k} commands are also used for referring to entries in a
372 \i{bibliography} (see \k{input-biblio} for more about
373 bibliographies), and can also be used for referring to an element of
374 a \i{numbered list} by its number (see \k{input-list-number} for
375 more about numbered lists).
377 See \k{input-sections} for more about chapters and sections.
379 \S{input-inline-comment} \i\c{\\#}: Inline comments
381 If you want to include \i{comments} in your Halibut input, to be seen
382 when reading it directly but not copied into the output text, then
383 you can use \c{\\#} to do this. If you follow \c{\\#} with text in
384 braces, that text will be ignored by Halibut.
386 For example, you might write
388 \c The typical behaviour of an antelope \#{do I mean gazelle?} is...
390 and Halibut will simply leave out the aside about gazelles, and will
394 The typical behaviour of an antelope \#{do I mean gazelle?} is...
397 The \c{\\#} command can also be used to produce a whole-paragraph
398 comment; see \k{input-commentpara} for details of that.
400 \H{input-para} \ii{Paragraph-level commands}
402 This section describes Halibut commands which affect an entire
403 paragraph, or sometimes even \e{more} than one paragraph, at a time.
405 \S{input-codepara} \i\c{\\c}: Displaying whole \I{code
406 paragraphs}paragraphs of \i{computer code}
408 \K{input-code} describes a mechanism for displaying computer code in
409 the middle of a paragraph, a few words at a time.
411 However, this is often not enough. Often, in a computer manual, you
412 really want to show several lines of code in a \i{display
415 This is also done using the \c{\\c} command, in a slightly different
416 way. Instead of using it in the middle of a paragraph followed by
417 braces, you can use it at the start of each line of a paragraph. For
418 example, you could write
420 \c \c #include <stdio.h>
422 \c \c int main(int argc, char **argv) {
423 \c \c printf("hello, world\n");
427 and Halibut would generate
431 \c #include <stdio.h>
433 \c int main(int argc, char **argv) {
434 \c printf("hello, world\n");
440 Note that the above paragraph makes use of a backslash and a pair of
441 braces, and does \e{not} need to escape them in the way described in
442 \k{input-basics}. This is because code paragraphs formatted in this
443 way are a special case; the intention is that you can just copy and
444 paste a lump of code out of another program, put \q{\cw{\\c }} at the
445 start of every line, and simply \e{not have to worry} about the
446 details - you don't have to go through the whole block looking for
447 characters to escape.
449 Since a backslash inside a code paragraph generates a literal
450 backslash, this means you cannot use any other Halibut formatting
451 commands inside a code paragraph. In particular, if you want to
452 emphasise a particular word in the paragraph, you can't do that
453 using \c{\\e} (\k{input-emph}) in the normal way.
455 Therefore, Halibut provides an alternative means of \i{emphasis in
456 code paragraphs}. Each line beginning with \c{\\c} can optionally be
457 followed by a single line beginning with \c{\\e}, indicating the
458 emphasis in that line. The emphasis line contains the letters \c{b}
459 and \c{i} (for \q{bold} and \q{italic}, although some output formats
460 might render \c{i} as underlining instead of italics), positioned to
461 line up under the parts of the text that you want emphasised.
463 For example, if you wanted to do \i{syntax highlighting} on the
464 above C code by highlighting the preprocessor command in italic and
465 the keywords in bold, you might do it like this:
467 \c \c #include <stdio.h>
468 \c \e iiiiiiiiiiiiiiiiii
470 \c \c int main(int argc, char **argv) {
472 \c \c printf("hello, world\n");
477 and Halibut would generate:
481 \c #include <stdio.h>
482 \e iiiiiiiiiiiiiiiiii
484 \c int main(int argc, char **argv) {
486 \c printf("hello, world\n");
493 Note that not every \c{\\c} line has to be followed by a \c{\\e}
494 line; they're optional.
496 Also, note that highlighting within a code paragraph is
497 \e{discretionary}. Not all of Halibut's output formats can support
498 it (plain text, in particular, has no sensible way to do it). Unless
499 you know you are using a restricted range of output formats, you
500 should use highlighting in code paragraphs \e{only} as a visual aid,
501 and not rely on it to convey any vital semantic content.
503 \S{input-lists} \c{\\b}, \c{\\n}, \c{\\dt}, \c{\\dd}, \c{\\lcont}:
506 Halibut supports bulletted lists, numbered lists and description
509 \S2{input-list-bullet} \i\c{\\b}: \ii{Bulletted lists}
511 To create a bulletted list, you simply prefix each paragraph
512 describing a bullet point with the command \c{\\b}. For example, this
523 would produce this Halibut output:
535 \S2{input-list-number} \i\c{\\n}: \ii{Numbered lists}
537 Numbered lists are just as simple: instead of \c{\\b}, you use
538 \c{\\n}, and Halibut takes care of getting the numbering right for
549 This produces the Halibut output:
561 The disadvantage of having Halibut sort out the list numbering for
562 you is that if you need to refer to a list item by its number, you
563 can't reliably do so. To get round this, Halibut allows an optional
564 keyword in braces after the \c{\\n} command. This keyword can then
565 be referenced using the \c{\\k} or \c{\\K} command (see
566 \k{input-xref}) to provide the number of the list item. For example:
576 \c \n Now go back to step \k{this-one}.
578 This produces the following output:
589 \n Now go back to step \k{this-one}.
592 \S2{input-list-description} \i\c{\\dt} and \i\c{\\dd}:
593 \ii{Description lists}
595 To write a description list, you prefix alternate paragraphs with
596 the \c{\\dt} (\q{described thing}) and \c{\\dd} (description)
597 commands. For example:
601 \c \dd This is a large bird with a big beak.
607 This produces the following output:
613 \dd This is a large bird with a big beak.
621 \S2{input-list-continuation} \ii{Continuing list items} into further
624 All three of the above list types assume that each list item is a
625 single paragraph. For a short, snappy list in which each item is
626 likely to be only one or two words, this is perfectly sufficient;
627 but occasionally you will find you want to include several
628 paragraphs in a single list item, or even to \I{nested lists}nest
629 other types of paragraph (such as code paragraphs, or other lists)
632 To do this, you use the \i\c{\\lcont} command. This is a command
633 which can span \e{multiple} paragraphs.
635 After the first paragraph of a list item, include the text
636 \c{\\lcont\{}. This indicates that the subsequent paragraph(s) are a
637 \e{continuation} of the list item that has just been seen. So you
638 can include further paragraphs, and eventually include a closing
639 brace \c{\}} to finish the list continuation. After that, you can
640 either continue adding other items to the original list, or stop
641 immediately and return to writing normal paragraphs of text.
643 Here's a (long) example.
647 \c \n One. This item is followed by a code paragraph:
656 \c \n Two. Now when I say \q{two}, I mean:
664 \c \n Two, part three.
670 The output produced by this fragment is:
676 \n One. This item is followed by a code paragraph:
685 \n Two. Now when I say \q{two}, I mean:
701 This syntax seems a little bit inconvenient, and perhaps
702 counter-intuitive: you might expect the enclosing braces to have to
703 go around the \e{whole} list item, rather than everything except the
706 \c{\\lcont} is a recent addition to the Halibut input language;
707 previously, \e{all} lists were required to use no more than one
708 paragraph per list item. So it's certainly true that this feature
709 looks like an afterthought because it \e{is} an afterthought, and
710 it's possible that if I'd been designing the language from scratch
711 with multiple-paragraph list items in mind, I would have made it
714 However, the advantage of doing it this way is that no enclosing
715 braces are required in the \e{common} case: simple lists with only
716 one paragraph per item are really, really easy to write. So I'm not
717 too unhappy with the way it turned out; it obeys the doctrine of
718 making simple things simple, and difficult things possible.
720 Note that \c{\\lcont} can only be used on \c{\\b}, \c{\\n} and
721 \c{\\dd} paragraphs; it cannot be used on \c{\\dt}.
723 \S{input-rule} \i\c{\\rule}: \ii{Horizontal rules}
725 The command \c{\\rule}, appearing on its own as a paragraph, will
726 cause a horizontal rule to be drawn, like this:
734 This produces the following output:
746 \S{input-quote} \i\c{\\quote}: \ii{Indenting multiple paragraphs} as a
749 Quoting verbatim text using a code paragraph (\k{input-codepara}) is
750 not always sufficient for your quoting needs. Sometimes you need to
751 quote some normally formatted text, possibly in multiple paragraphs.
752 This is similar to HTML's \i\cw{<BLOCKQUOTE>} command.
754 To do this, you can use the \c{\\quote} command. Like \c{\\lcont},
755 this is a command which expects to enclose at least one paragraph
756 and possibly more. Simply write \c{\\quote\{} at the beginning of
757 your quoted section, and \c{\}} at the end, and the paragraphs in
758 between will be formatted to indicate that they are a quotation.
760 (This very manual, in fact, uses this feature a lot: all of the
761 examples of Halibut source followed by Halibut output have the
762 output quoted using \c{\\quote}.)
764 Here's some example Halibut input:
766 \c In \q{Through the Looking Glass}, Lewis Carroll wrote:
770 \c \q{The question is,} said Alice, \q{whether you \e{can} make
771 \c words mean so many different things.}
773 \c \q{The question is,} said Humpty Dumpty, \q{who is to be master -
780 The output generated by this is:
784 In \q{Through the Looking Glass}, Lewis Carroll wrote:
788 \q{The question is,} said Alice, \q{whether you \e{can} make
789 words mean so many different things.}
791 \q{The question is,} said Humpty Dumpty, \q{who is to be master -
800 \S{input-sections} \i\c{\\C}, \i\c{\\H}, \i\c{\\S}, \i\c{\\A},
801 \i\c{\\U}: Chapter and \i{section headings}
803 \K{intro-features} mentions that Halibut \I{section
804 numbering}numbers the sections of your document automatically, and
805 can generate cross-references to them on request; \k{input-xref}
806 describes the \c{\\k} and \c{\\K} commands used to generate the
807 cross-references. This section describes the commands used to set up
808 the sections in the first place.
810 A paragraph beginning with the \c{\\C} command defines a chapter
811 heading. The \c{\\C} command expects to be followed by a pair of
812 braces containing a keyword for the chapter; this keyword can then
813 be used with the \c{\\k} and \c{\\K} commands to generate
814 cross-references to the chapter. After the closing brace, the rest
815 of the paragraph is used as the displayed chapter title. So the
816 heading for the current chapter of this manual, for example, is
819 \c \C{input} Halibut input format
821 and this allows me to use the command \c{\\k\{input\}} to generate a
822 cross-reference to that chapter somewhere else.
824 The next level down from \c{\\C} is \c{\\H}, for \q{heading}. This
825 is used in exactly the same way as \c{\\C}, but section headings
826 defined with \c{\\H} are considered to be part of a containing
827 chapter, and will be numbered with a pair of numbers. After \c{\\H}
828 comes \c{\\S}, and if necessary you can then move on to \c{\\S2},
831 For example, here's a sequence of heading commands. Normally these
832 commands would be separated at least by blank lines (because each is
833 a separate paragraph), and probably also by body text; but for the
834 sake of brevity, both of those have been left out in this example.
837 \c \H{foo-intro} Introduction to Foo
838 \c \H{foo-running} Running the Foo program
839 \c \S{foo-inter} Running Foo interactively
840 \c \S{foo-batch} Running Foo in batch mode
841 \c \H{foo-trouble} Troubleshooting Foo
842 \c \C{bar} Using Bar instead of Foo
844 This would define two chapters with keywords \c{foo} and \c{bar},
845 which would end up being called Chapter 1 and Chapter 2 (unless
846 there were other chapters before them). The sections \c{foo-intro},
847 \c{foo-running} and \c{foo-trouble} would be referred to as Section
848 1.1, Section 1.2 and Section 1.3 respectively; the subsections
849 \c{foo-inter} and \c{foo-batch} would be Section 1.2.1 and Section
850 1.2.2. If there had been a \i\c{\\S2} command within one of those,
851 it would have been something like Section 1.2.1.1.
853 If you don't like the switch from \c{\\H} to \c{\\S}, you can use
854 \c{\\S1} as a synonym for \c{\\S} and \c{\\S0} as a synonym for
855 \c{\\H}. Chapters are still designated with \c{\\C}, because they
856 need to be distinguished from other types of chapter such as
857 appendices. (Personally, I like the \c{\\C},\c{\\H},\c{\\S} notation
858 because it encourages me to think of my document as a hard disk :-)
860 You can define an \i{appendix} by using \c{\\A} in place of \c{\\C}.
861 This is no different from a chapter except that it's given a letter
862 instead of a number, and cross-references to it will say \q{Appendix
863 A} instead of \q{Chapter 9}. Subsections of an appendix will be
864 numbered \q{A.1}, \q{A.2}, \q{A.2.1} and so on.
866 \I{renaming sections}If you want a particular section to be referred
867 to as something other than a \q{chapter}, \q{section} or
868 \q{appendix}, you can include a second pair of braces after the
869 keyword. For example, if you're \i{writing a FAQ} chapter and you
870 want cross-references between questions to refer to \q{question
871 1.2.3} instead of \q{section 1.2.3}, you can write each section
874 \c \S{question-about-fish}{Question} What about fish?
876 (The word \q{Question} should be given with an initial capital
877 letter. Halibut will lower-case it when you refer to it using
878 \c{\\k}, and will leave it alone if you use \c{\\K}.)
880 This technique allows you to change the designation of
881 \e{particular} sections. To make an overall change in what \e{every}
882 section is called, see \k{input-config}.
884 Finally, the \c{\\U} command defines an \I{unnumbered
885 chapter}\e{unnumbered} chapter. These sometimes occur in books, for
886 specialist purposes such as \q{Bibliography} or
887 \q{Acknowledgements}. \c{\\U} does not expect a keyword argument,
888 because there is no sensible way to generate an automatic
889 cross-reference to such a chapter anyway.
891 \S{input-blurb} \c{\\copyright}, \c{\\title}, \c{\\versionid}:
892 Miscellaneous \i{blurb commands}
894 These three commands define a variety of \i{special paragraph
895 types}. They are all used in the same way: you put the command at
896 the start of a paragraph, and then just follow it with normal text,
899 \c \title My First Manual
901 The three special paragraph types are:
905 \dd This defines the overall title of the entire document. This
906 title is treated specially in some output formats (for example, it's
907 used in a \cw{<title>} tag in the HTML output), so it needs a
908 special paragraph type to point it out.
910 \dt \i\cw{\\copyright}
912 \dd This command indicates that the paragraph attached to it
913 contains a \i{copyright statement} for the document. This text is
914 displayed inline where it appears, exactly like a normal paragraph;
915 but in some output formats it is given additional special treatment.
916 For example, Windows Help files have a standard slot in which to
917 store a copyright notice, so that other software can display it
920 \dt \i\cw{\\versionid}
922 \dd This command indicates that the paragraph contains a version
923 identifier, such as those produced by CVS (of the form \c{$\#{hope this
924 defuses CVS}Id: thingy.but,v 1.6 2004/01/01 16:47:48 simon Exp $}).
925 This text will be tucked away somewhere unobtrusive, so that anyone
926 wanting to (for example) report errors to the document's author can
927 pick out the \i{version IDs} and send them as part of the report, so
928 that the author can tell at a glance which revision of the document
931 \S{input-commentpara} \i\c{\\#}: Whole-paragraph \i{comments}
933 \K{input-inline-comment} describes the use of the \c{\\#} command to
934 put a short comment in the middle of a paragraph.
936 If you need to use a \e{long} comment, Halibut also allows you to
937 use \c{\\#} without braces, to indicate that an entire paragraph is
938 a comment, like this:
940 \c Here's a (fairly short) paragraph which will be displayed.
942 \c \# Here's a comment paragraph which will not be displayed, no
943 \c matter how long it goes on. All I needed to indicate this was the
944 \c single \# at the start of the paragraph; I don't need one on
945 \c every line or anything like that.
947 \c Here's another displayed paragraph.
949 When run through Halibut, this produces the following output:
953 Here's a (fairly short) paragraph which will be displayed.
955 \# Here's a comment paragraph which will not be displayed, no
956 matter how long it goes on. All I needed to indicate this was the
957 single \# at the start of the paragraph; I don't need one on
958 every line or anything like that.
960 Here's another displayed paragraph.
964 \H{input-biblio} Creating a \i{bibliography}
966 If you need your document to refer to other documents (research
967 papers, books, websites, whatever), you might find a bibliography
970 You can define a bibliography entry using the \i\c{\\B} command. This
971 looks very like the \c{\\C} command and friends: it expects a
972 keyword in braces, followed by some text describing the document
973 being referred to. For example:
975 \c \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
976 \c Published by Paperjam & Notoner, 1993.
978 If this bibliography entry appears in the finished document, it will
979 look something like this:
983 \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs.
984 Published by Paperjam & Notoner, 1993.
988 I say \q{if} above because not all bibliography entries defined
989 using the \c{\\B} command will necessarily appear in the finished
990 document. They only appear if they are \I{citation}referred to by a
991 \i\c{\\k} command (see \k{input-xref}). This allows you to (for
992 example) maintain a single Halibut source file with a centralised
993 database of \e{all} the references you have ever needed in any of
994 your writings, include that file in every document you feed to
995 Halibut, and have it only produce the bibliography entries you
996 actually need for each particular document. (In fact, you might even
997 want this centralised source file to be created automatically by,
998 say, a Perl script from BibTeX input, so that you can share the same
999 bibliography with users of other formatting software.)
1001 If you really want a bibliography entry to appear in the document
1002 even though no text explicitly refers to it, you can do that using
1003 the \i\c{\\nocite} command:
1005 \c \nocite{freds-book}
1007 Normally, each bibliography entry will be referred to (in citations
1008 and in the bibliography itself) by a simple reference number, such
1009 as \k{freds-book}. If you would rather use an alternative reference
1010 notation, such as [Fred1993], you can use the \i\c{\\BR}
1011 (\q{Bibliography Rewrite}) command to specify your own reference
1012 format for a particular book:
1014 \c \BR{freds-book} [Fred1993]
1016 \H{input-index} Creating an \i{index}
1018 Halibut contains a comprehensive indexing mechanism, which attempts
1019 to be reasonably easy to use in the common case in spite of its
1022 \S{input-index-simple} Simple indexing
1024 In normal usage, you should be able to add index terms to your
1025 document simply by using the \i\c{\\i} command to wrap one or two
1026 words at a time. For example, if you write
1028 \c The \i{hippopotamus} is a particularly large animal.
1030 then the index will contain an entry under \q{hippopotamus},
1031 pointing to that sentence (or as close to that sentence as the
1032 output format sensibly permits).
1034 You can wrap more than one word in \c{\\i} as well:
1036 \c We recommend using a \i{torque wrench} for this job.
1038 \S{input-index-special} Special cases of indexing
1040 If you need to index a computer-related term, you can use the
1041 special case \i\c{\\i\\c} (or \i\c{\\i\\cw} if you prefer):
1043 \c The \i\c{grep} command is what you want here.
1045 This will cause the word \q{grep} to appear in code style, as if the
1046 \c{\\i} were not present and the input just said \c{\\c\{grep\}};
1047 the word will also appear in code style in the actual index.
1049 If you want to simultaneously index and emphasise a word, there's
1050 another special case \i\c{\\i\\e}:
1052 \c This is what we call a \i\e{paper jam}.
1054 This will cause the words \q{paper jam} to be emphasised in the
1055 document, but (unlike the behaviour of \c{\\i\\c}) they will \e{not}
1056 be emphasised in the index. This different behaviour is based on an
1057 expectation that most people indexing a word of computer code will
1058 still want it to look like code in the index, whereas most people
1059 indexing an emphasised word will \e{not} want it emphasised in the
1062 (In fact, \e{no} emphasis in the text inside \c{\\i} will be
1063 preserved in the index. If you really want a term in the index to
1064 appear emphasised, you must say so explicitly using \c{\\IM}; see
1065 \k{input-index-rewrite}.)
1067 Sometimes you might want to index a term which is not explicitly
1068 mentioned, but which is highly relevant to the text and you think
1069 that somebody looking up that term in the index might find it useful
1070 to be directed here. To do this you can use the \i\c{\\I} command,
1071 to create an \i{\e{invisible} index tag}:
1073 \c If your printer runs out of toner, \I{replacing toner
1074 \c cartridge}here is what to do:
1076 This input will produce only the output \q{If your printer runs out
1077 of toner, here is what to do}; but an index entry will show up under
1078 \q{replacing toner cartridge}, so that if a user thinks the obvious
1079 place to start in the index is under R for \q{replacing}, they will
1080 find their way here with a minimum of fuss.
1082 (It's worth noting that there is no functional difference between
1083 \c{\\i\{foo\}} and \c{\\I\{foo\}foo}. The simple \c{\\i} case is
1084 only a shorthand for the latter.)
1086 Finally, if you want to index a word at the start of a sentence, you
1087 might very well not want it to show up with a capital letter in the
1088 index. For this, Halibut provides the \i\c{\\ii} command, for
1089 \q{index (case-)insensitively}. You use it like this:
1091 \c \ii{Lions} are at the top of the food chain in this area.
1093 This is equivalent to \c{\\I\{lions\}Lions}; in other words, the
1094 text will say \q{Lions}, but it will show up in the index as
1095 \q{lions}. The text inside \c{\\ii} is converted entirely into lower
1096 case before being added to the index data.
1098 \S{input-index-rewrite} \ii{Fine-tuning the index}
1100 Halibut's index mechanism as described so far still has a few
1103 \b In a reasonably large index, it's often difficult to predict
1104 \I{replicating index terms}which of several words a user will think
1105 of first when trying to look something up. For example, if they want
1106 to know how to replace a toner cartridge, they might look up
1107 \q{replacing} or they might look up \q{toner cartridge}. You
1108 probably don't really want to have to try to figure out which of
1109 those is more likely; instead, what you'd like is to be able to
1110 effortlessly index the same set of document locations under \e{both}
1113 \b Also, you may find you've indexed the same concept under multiple
1114 different \I{merging index terms}index terms; for example, there
1115 might be several instances of \c{\\i\{frog\}} and several of
1116 \c{\\i\{frogs\}}, so that you'd end up with two separate index
1117 entries for what really ought to be the same concept.
1119 \b You might well not want the word \q{\cw{grep}} to appear in the
1120 index without explanation; you might prefer it to say something more
1121 \I{rewriting index terms}verbose such as \q{\cw{grep} command}, so
1122 that a user encountering it in the index has some idea of what it is
1123 \e{without} having to follow up the reference. However, you
1124 certainly don't want to have to write \c{\\I\{\\cw\{grep\}
1125 command\}\\c\{grep\}} every time you want to add an index term for
1126 this! You wanted to write \c{\\i\\c\{grep\}} as shown in the
1127 previous section, and tidy it all up afterwards.
1129 All of these problems can be cleaned up by the \i\c{\\IM} (for
1130 \q{Index Modification}) command. \c{\\IM} expects to be followed by
1131 one or more pairs of braces containing index terms as seen in the
1132 document, and then a piece of text (not in braces) describing how it
1133 should be shown in the index.
1135 So to rewrite the \c{grep} example above, you might do this:
1137 \c \IM{grep} \cw{grep} command
1139 This will arrange that the set of places in the document where you
1140 asked Halibut to index \q{\cw{grep}} will be listed under
1141 \q{\cw{grep} command} rather than just under \q{\cw{grep}}.
1143 You can specify more than one index term in a \c{\\IM} command; so
1144 to merge the index terms \q{frog} and \q{frogs} into a single term,
1147 \c \IM{frog}{frogs} frog
1149 This will arrange that the single index entry \q{frog} will list
1150 \e{all} the places in the document where you asked Halibut to index
1151 either \q{frog} or \q{frogs}.
1153 You can use multiple \c{\\IM} commands to replicate the same set of
1154 document locations in more than one index entry. For example:
1156 \c \IM{replacing toner cartridge} replacing toner cartridge
1157 \c \IM{replacing toner cartridge} toner cartridge, replacing
1159 This will arrange that every place in the document where you have
1160 indexed \q{replacing toner cartridge} will be listed both there
1161 \e{and} under \q{toner cartridge, replacing}, so that no matter
1162 whether the user looks under R or under T they will stil find their
1163 way to the same parts of the document.
1165 In this example, note that although the first \c{\\IM} command
1166 \e{looks} as if it's a tautology, it is still necessary, because
1167 otherwise those document locations will \e{only} be indexed under
1168 \q{toner cartridge, replacing}. If you have \e{no} explicit \c{\\IM}
1169 commands for a particular index term, then Halibut will assume a
1170 default one (typically \c{\\IM\{foo\}\_foo}, although it might be
1171 \c{\\IM\{foo\}\_\\c\{foo\}} if you originally indexed using
1172 \c{\\i\\c}); but as soon as you specify an explicit \c{\\IM},
1173 Halibut discards its default implicit one, and you must then specify
1174 that one explicitly as well if you wanted to keep it.
1176 \H{input-config} \ii{Configuring} Halibut
1178 Halibut uses the \i\c{\\cfg} command to allow you to configure various
1179 aspects of its functionality.
1181 The \c{\\cfg} command expects to be followed by at least one pair of
1182 braces, and usually more after that. The first pair of braces
1183 contains a keyword indicating what aspect of Halibut you want to
1184 configure, and the meaning of the one(s) after that depends on the
1187 The current list of configuration keywords in the main Halibut code
1188 is quite small. Here it is in full:
1190 \dt \I\cw{\\cfg\{chapter\}}\cw{\\cfg\{chapter\}\{}\e{new chapter name}\cw{\}}
1192 \dd This tells Halibut that you don't want to call a chapter a
1193 \I{renaming sections}\I{configuring heading display}chapter any
1194 more. For example, if you give the command
1195 \cw{\\cfg\{chapter\}\{Book\}}, then any chapter defined with the
1196 \c{\\C} command will be labelled \q{Book} rather than \q{Chapter},
1197 both in the section headings and in cross-references. This is
1198 probably most useful if your document is not written in English.
1202 Your replacement name should be given with a capital letter. Halibut
1203 will leave it alone if it appears at the start of a sentence (in a
1204 chapter title, or when \c{\\K} is used), and will lower-case it
1205 otherwise (when \c{\\k} is used).
1209 \dt \I\cw{\\cfg\{section\}}\cw{\\cfg\{section\}\{}\e{new section name}\cw{\}}
1211 \dd Exactly like \c{chapter}, but changes the name given to
1212 subsections of a chapter.
1214 \dt \I\cw{\\cfg\{appendix\}}\cw{\\cfg\{appendix\}\{}\e{new appendix name}\cw{\}}
1216 \dd Exactly like \c{chapter}, but changes the name given to
1219 In addition to these configuration commands, there are also
1220 configuration commands provided by each individual output format.
1221 These configuration commands are discussed along with each output
1222 format, in \k{output}.
1224 The \i{default settings} for the above options are:
1226 \c \cfg{chapter}{Chapter}
1227 \c \cfg{section}{Section}
1228 \c \cfg{appendix}{Appendix}
1230 \H{input-macro} Defining \i{macros}
1232 If there's a complicated piece of Halibut source which you think
1233 you're going to use a lot, you can define your own Halibut command
1234 to produce that piece of source.
1236 In \k{input-unicode}, there is a sample piece of code which prints a
1237 Euro sign, or replaces it with \q{EUR} if the Euro sign is not
1240 \c This is likely to cost \u20AC{EUR\_}2500 at least.
1242 If your document quotes a \e{lot} of prices in Euros, you might not
1243 want to spend all your time typing that out. So you could define a
1244 macro, using the \i\c{\\define} command:
1246 \c \define{eur} \u20AC{EUR\_}
1248 Then you can just write ...
1250 \c This is likely to cost \eur 2500 at least.
1252 ... except that that's not terribly good, because you end up with a
1253 space between the Euro sign and the number. In this case, it's
1254 helpful to use the special \i\c{\\.} command, which is defined to
1255 \I{NOP}\I{doing nothing}do nothing at all! But it acts as a
1256 separator between your macro and the next character:
1258 \c This is likely to cost \eur\.2500 at least.
1260 This way, you will see no space between the Euro sign and the number
1261 (although, of course, there will be space between \q{EUR} and the
1262 number if the Euro sign is not available, because the macro
1263 definition specifically asked for it).