| 1 | \C{input} Halibut input format |
| 2 | |
| 3 | This chapter describes the format in which you should write |
| 4 | documents to be processed by Halibut. |
| 5 | |
| 6 | \H{input-basics} The basics |
| 7 | |
| 8 | Halibut's input files mostly look like ordinary ASCII text files; |
| 9 | you can edit them with any text editor you like. |
| 10 | |
| 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 |
| 17 | looking like this: |
| 18 | |
| 19 | \c This is a line of text. |
| 20 | \c This is another line of text. |
| 21 | \c |
| 22 | \c This line is separated from the previous one by a blank line. |
| 23 | |
| 24 | will produce two paragraphs looking like this: |
| 25 | |
| 26 | \quote{ |
| 27 | This is a line of text. |
| 28 | This is another line of text. |
| 29 | |
| 30 | This line is separated from the previous one by a blank line. |
| 31 | } |
| 32 | |
| 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. |
| 36 | |
| 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 |
| 45 | |
| 46 | \c This \\ is a backslash, and these are \{braces\}. |
| 47 | |
| 48 | and Halibut would generate the text |
| 49 | |
| 50 | \quote{ |
| 51 | This \\ is a backslash, and these are \{braces\}. |
| 52 | } |
| 53 | |
| 54 | \H{input-inline} Simple inline formatting commands |
| 55 | |
| 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.) |
| 61 | |
| 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. |
| 67 | |
| 68 | \S{input-emph} \c{\\e}: Emphasising text |
| 69 | |
| 70 | Possibly the most obvious piece of formatting you might want to use |
| 71 | in a document is \e{emphasis}. To emphasise text, you use the |
| 72 | \c{\\e} command, and follow it up with the text to be emphasised in |
| 73 | braces. For example, the first sentence in this paragraph was |
| 74 | generated using the Halibut input |
| 75 | |
| 76 | \c Possibly the most obvious piece of formatting you might want to use |
| 77 | \c in a document is \e{emphasis}. |
| 78 | |
| 79 | \S{input-code} \c{\\c} and \c{\\cw}: Displaying computer code inline |
| 80 | |
| 81 | Halibut was primarily designed to produce software manuals. It can |
| 82 | be used for other types of document as well, but software manuals |
| 83 | are its speciality. |
| 84 | |
| 85 | In software manuals, you often want to format text in a way that |
| 86 | indicates that it is something you might see displayed verbatim on |
| 87 | a computer screen. In printed manuals, this is typically done by |
| 88 | setting that text in a font which is obviously fixed-width. This |
| 89 | provides a visual cue that the text being displayed is code, and it |
| 90 | also ensures that punctuation marks are clearly separated and shown |
| 91 | individually (so that a user can copy the text accurately and |
| 92 | conveniently). |
| 93 | |
| 94 | Halibut provides \e{two} commands for this, which are subtly |
| 95 | different. The names of those commands are \c{\\c} (\q{code}) and |
| 96 | \c{\\cw} (\q{weak code}). You use them just like \c{\\e}, by |
| 97 | following them with some text in braces. For example, this... |
| 98 | |
| 99 | \c This sentence contains some \c{code} and some \cw{weak code}. |
| 100 | |
| 101 | ... produces this: |
| 102 | |
| 103 | \quote{ |
| 104 | This sentence contains some \c{code} and some \cw{weak code}. |
| 105 | } |
| 106 | |
| 107 | The distinction between code and weak code is mainly important when |
| 108 | producing plain text output. Plain text output is typically viewed |
| 109 | in a fixed-width font, so there is no need (and no way) to change |
| 110 | font in order to make the order of punctuation marks clear. However, |
| 111 | marking text as code is also \e{sometimes} done to provide a visual |
| 112 | distinction between it and the text around it, so that the reader |
| 113 | knows where the literal computer text starts and stops; and in plain |
| 114 | text, this cannot be done by changing font, so there needs to be an |
| 115 | alternative way. |
| 116 | |
| 117 | So in the plain text back end, things marked as code (\c{\\c}) will |
| 118 | be surrounded by quote marks, so that it's obvious where they start |
| 119 | and finish. Things marked as weak code (\c{\\cw}) will not look any |
| 120 | different from normal text. |
| 121 | |
| 122 | I recommend using weak code for any application where it is |
| 123 | \e{obvious} that the text is literal computer input or output. For |
| 124 | example, if the text is capitalised, that's usually good enough. If |
| 125 | I talk about the Pentium's \cw{EAX} and \cw{EDX} registers, for |
| 126 | example, you don't need quotes to notice that those are special; so |
| 127 | I would write that in Halibut as \q{\c{the Pentium's \\cw\{EAX\} and |
| 128 | \\cw\{EDX\} registers}}. But if I'm talking about the Unix command |
| 129 | \c{man}, which is an ordinary English word in its own right, a reader |
| 130 | might be slightly confused if it appeared in the middle of a |
| 131 | sentence undecorated; so I would write that as \q{\c{the Unix command |
| 132 | \\c\{man\}}}. |
| 133 | |
| 134 | In summary: |
| 135 | |
| 136 | \b \c{\\c} means \q{this text \e{must} be visually distinct from the |
| 137 | text around it}. Halibut's various output formats will do this by |
| 138 | changing the font if possible, or by using quotes if not. |
| 139 | |
| 140 | \b \c{\\cw} means \q{it would be nice to display this text in a |
| 141 | fixed-width font if possible, but it's not essential}. |
| 142 | |
| 143 | There is a separate mechanism for displaying computer code in an |
| 144 | entire paragraph; see \k{input-codepara} for that one. |
| 145 | |
| 146 | \S{input-quotes} \c{\\q}: Quotation marks |
| 147 | |
| 148 | Halibut's various output formats don't all use the same conventions |
| 149 | for displaying text in ordinary quotation marks (\q{like these}). |
| 150 | Some output formats have access to proper matched quote characters, |
| 151 | whereas others are restricted to using plain ASCII. Therefore, it is |
| 152 | not ideal to use the ordinary ASCII double quote character in your |
| 153 | document (although you can if you like). |
| 154 | |
| 155 | Halibut provides the formatting command \c{\\q} to indicate quoted |
| 156 | text. If you write |
| 157 | |
| 158 | \c Here is some \q{text in quotes}. |
| 159 | |
| 160 | then Halibut will print |
| 161 | |
| 162 | \quote{ |
| 163 | Here is some \q{text in quotes}. |
| 164 | } |
| 165 | |
| 166 | and in every output format Halibut generates, it will choose the |
| 167 | best quote characters available to it in that format. |
| 168 | |
| 169 | You can still use ordinary ASCII double quotes if you prefer; or you |
| 170 | could even use the \c{\\u} command (see \k{input-unicode}) to |
| 171 | generate Unicode matched double quotes and fall back to the normal |
| 172 | ASCII one if they aren't available. But I recommend using the |
| 173 | built-in \c{\\q} command in most cases, because it's simple and does |
| 174 | the best it can everywhere. |
| 175 | |
| 176 | (Note that if you're using the \c{\\c} or \c{\\cw} commands to |
| 177 | display literal computer code, you probably \e{will} want to use |
| 178 | literal ASCII quote characters, because it is likely to matter |
| 179 | precisely which quote character you use.) |
| 180 | |
| 181 | \S{input-nonbreaking} \c{\\-} and \c{\\_}: Non-breaking hyphens and |
| 182 | spaces |
| 183 | |
| 184 | If you use an ordinary hyphen in the middle of a word (such as |
| 185 | \q{built-in}), Halibut's output formats will feel free to break a |
| 186 | line after that hyphen when wrapping paragraphs. This is fine for a |
| 187 | word like \q{built-in}, but if you were displaying some literal |
| 188 | computer code such as the Emacs command |
| 189 | \c{M\-x\_psychoanalyze\-pinhead}, you might prefer to see the whole |
| 190 | hyphenated word treated as an unbreakable block. In some cases, you |
| 191 | might even want to prevent the \e{space} in that command from |
| 192 | becoming a line break. |
| 193 | |
| 194 | For these purposes, Halibut provides the commands \c{\\-} and |
| 195 | \c{\\_}, which generate a non-breaking hyphen and a non-breaking |
| 196 | space respectively. So the above Emacs command might be written as |
| 197 | |
| 198 | \c the Emacs command \c{M\-x\_psychoanalyze\-pinhead} |
| 199 | |
| 200 | Unfortunately, some of Halibut's output formats do not support |
| 201 | non-breaking hyphens, and others don't support \e{breaking} hyphens! |
| 202 | So Halibut cannot promise to honour these commands in all situations. |
| 203 | All it can do is make a best effort. |
| 204 | |
| 205 | \S{input-date} \c{\\date}: Automatic date generation |
| 206 | |
| 207 | Sometimes you might want your document to give an up-to-date |
| 208 | indication of the date on which it was run through Halibut. |
| 209 | |
| 210 | Halibut supplies the \c{\\date} command to do this. In its simplest |
| 211 | form, you simply say |
| 212 | |
| 213 | \c This document was generated on \date. |
| 214 | |
| 215 | and Halibut generates something like |
| 216 | |
| 217 | \quote{ |
| 218 | This document was generated on \date. |
| 219 | } |
| 220 | |
| 221 | If you would prefer the date to be generated in a specific format, |
| 222 | you can follow the \c{\\date} command with a format specification in |
| 223 | braces. The format specification will be run through the standard C |
| 224 | function \c{strftime}, so any format acceptable to that function is |
| 225 | acceptable here as well. I won't document the format here, because |
| 226 | the details vary from computer to computer (although there is a |
| 227 | standard core which should be supported everywhere). You should look |
| 228 | at your local system's manual for \c{strftime} for details. |
| 229 | |
| 230 | Here's an example which generates the date in the international |
| 231 | standard ISO 8601 format: |
| 232 | |
| 233 | \c This document was generated on \date{%Y-%m-%d %H:%M:%S}. |
| 234 | |
| 235 | And here's some sample output from that command: |
| 236 | |
| 237 | \quote{ |
| 238 | This document was generated on \date{%Y-%m-%d %H:%M:%S}. |
| 239 | } |
| 240 | |
| 241 | \S{input-weblink} \c{\\W}: WWW hyperlinks |
| 242 | |
| 243 | Since one of Halibut's output formats is HTML, it's obviously useful |
| 244 | to be able to provide links to arbitrary web sites in a Halibut |
| 245 | document. |
| 246 | |
| 247 | This is done using the \c{\\W} command. \c{\\W} expects to be |
| 248 | followed by \e{two} sets of braces. In the first set of braces you |
| 249 | put a URL; in the second set you put the text which should be a |
| 250 | hyperlink. For example, you might write |
| 251 | |
| 252 | \c Try searching on \W{http://www.google.com/}{Google}. |
| 253 | |
| 254 | and Halibut would generate |
| 255 | |
| 256 | \quote{ |
| 257 | Try searching on \W{http://www.google.com/}{Google}. |
| 258 | } |
| 259 | |
| 260 | Note that hyperlinks, like the non-breaking commands discussed in |
| 261 | \k{input-nonbreaking}, are \e{discretionary}: if an output format |
| 262 | does not support them then they will just be left out completely. So |
| 263 | unless you're \e{only} intending to use the HTML output format, you |
| 264 | should avoid storing vital content in the URL part of a \c{\\W} |
| 265 | command. The Google example above is reasonable (because most users |
| 266 | are likely to be able to find Google for themselves even without a |
| 267 | convenient hyperlink leading straight there), but if you really need |
| 268 | to direct users to a specific web site, you will need to give the |
| 269 | URL in actual displayed text (probably displayed as code as well). |
| 270 | However, there's nothing to stop you making it a hyperlink \e{as |
| 271 | well} for the convenience of HTML readers. |
| 272 | |
| 273 | The \c{\\W} command supports a piece of extra syntax to make this |
| 274 | convenient for you. You can specify \c{\\c} or \c{\\cw} \e{between} |
| 275 | the first and second pairs of braces. For example, you might write |
| 276 | |
| 277 | \c Google is located at \W{http://www.google.com/}\cw{www.google.com}. |
| 278 | |
| 279 | and Halibut would produce |
| 280 | |
| 281 | \quote{ |
| 282 | Google is located at \W{http://www.google.com/}\cw{www.google.com}. |
| 283 | } |
| 284 | |
| 285 | \S{input-unicode} \c{\\u}: Specifying arbitrary Unicode characters |
| 286 | |
| 287 | When Halibut is finished, it should have full Unicode support. You |
| 288 | should be able to specify any (reasonably well known) character set |
| 289 | for your input document, and Halibut should convert it all to |
| 290 | Unicode as it reads it in. Similarly, you should be able to specify |
| 291 | the character set you want for each output format and have all the |
| 292 | conversion done automatically. |
| 293 | |
| 294 | Currently, none of this is actually supported. Input text files are |
| 295 | assumed to be in ISO 8859-1, and each output format has its own |
| 296 | non-configurable character set (although the HTML output can use the |
| 297 | \c{Ӓ} mechanism to output any Unicode character it likes). |
| 298 | |
| 299 | If you need to specify a Unicode character in your input document |
| 300 | which is not supported by the input character set, you can use the |
| 301 | \c{\\u} command to do this. \c{\\u} expects to be followed by a |
| 302 | sequence of hex digits; so that \c{\\u0041}, for example, denotes |
| 303 | the Unicode character \cw{0x0041}, which is the capital letter A. |
| 304 | |
| 305 | If a Unicode character specified in this way is not supported in a |
| 306 | particular \e{output} format, you probably don't just want it to be |
| 307 | omitted. So you can put a pair of braces after the \c{\\u} command |
| 308 | containing fallback text. For example, to specify an amount of money |
| 309 | in euros, you might write this: |
| 310 | |
| 311 | \c This is likely to cost \u20AC{EUR }2500 at least. |
| 312 | |
| 313 | Halibut will render that as a Euro sign \e{if available}, and |
| 314 | the text \q{EUR } if not. In the output format you're currently |
| 315 | reading in, the above input generates this: |
| 316 | |
| 317 | \quote{ |
| 318 | This is likely to cost \u20AC{EUR }2500 at least. |
| 319 | } |
| 320 | |
| 321 | If you read it in other formats, you may see different results. |
| 322 | |
| 323 | \S{input-xref} \c{\\k} and \c{\\K}: Cross-references to other sections |
| 324 | |
| 325 | \K{intro-features} mentions that Halibut numbers the sections of |
| 326 | your document automatically, and can generate cross-references to |
| 327 | them on request. \c{\\k} and \c{\\K} are the commands used to |
| 328 | generate those cross-references. |
| 329 | |
| 330 | To use one of these commands, you simply follow it with a pair of |
| 331 | braces containing the keyword for the section in question. For |
| 332 | example, you might write something like |
| 333 | |
| 334 | \c \K{input-xref} expands on \k{intro-features}. |
| 335 | |
| 336 | and Halibut would generate something like |
| 337 | |
| 338 | \quote{ |
| 339 | \K{input-xref} expands on \k{intro-features}. |
| 340 | } |
| 341 | |
| 342 | The keywords \c{input-xref} and \c{intro-features} are section |
| 343 | keywords used in this manual itself. In your own document, you would |
| 344 | have supplied a keyword for each one of your own sections, and you |
| 345 | would provide your own keywords for the \c{\\k} command to work on. |
| 346 | |
| 347 | The difference between \c{\\k} and \c{\\K} is simply that \c{\\K} |
| 348 | starts the cross-reference text with a capital letter; so you would |
| 349 | use \c{\\K} at the beginning of a sentence, and \c{\\k} everywhere |
| 350 | else. |
| 351 | |
| 352 | In output formats which permit it, cross-references act as |
| 353 | hyperlinks, so that clicking the mouse on a cross-reference takes |
| 354 | you straight to the referenced section. |
| 355 | |
| 356 | The \c{\\k} commands are also used for referring to entries in a |
| 357 | bibliography (see \k{input-biblio} for more about bibliographies), |
| 358 | and can also be used for referring to an element of a numbered list |
| 359 | by its number (see \k{input-list-number} for more about numbered |
| 360 | lists). |
| 361 | |
| 362 | See \k{input-sections} for more about chapters and sections. |
| 363 | |
| 364 | \S{input-inline-comment} \c{\\#}: Inline comments |
| 365 | |
| 366 | If you want to include comments in your Halibut input, to be seen |
| 367 | when reading it directly but not copied into the output text, then |
| 368 | you can use \c{\\#} to do this. If you follow \c{\\#} with text in |
| 369 | braces, that text will be ignored by Halibut. |
| 370 | |
| 371 | For example, you might write |
| 372 | |
| 373 | \c The typical behaviour of an antelope \#{do I mean gazelle?} is... |
| 374 | |
| 375 | and Halibut will simply leave out the aside about gazelles, and will |
| 376 | generate nothing but |
| 377 | |
| 378 | \quote{ |
| 379 | The typical behaviour of an antelope \#{do I mean gazelle?} is... |
| 380 | } |
| 381 | |
| 382 | The \c{\\#} command can also be used to produce a whole-paragraph |
| 383 | comment; see \k{input-commentpara} for details of that. |
| 384 | |
| 385 | \H{input-para} Paragraph-level commands |
| 386 | |
| 387 | This section describes Halibut commands which affect an entire |
| 388 | paragraph, or sometimes even \e{more} than one paragraph, at a time. |
| 389 | |
| 390 | \S{input-codepara} \c{\\c}: Displaying whole paragraphs of computer |
| 391 | code |
| 392 | |
| 393 | \K{input-code} describes a mechanism for displaying computer code in |
| 394 | the middle of a paragraph, a few words at a time. |
| 395 | |
| 396 | However, this is often not enough. Often, in a computer manual, you |
| 397 | really want to show several lines of code in a display paragraph. |
| 398 | |
| 399 | This is also done using the \c{\\c} command, in a slightly different |
| 400 | way. Instead of using it in the middle of a paragraph followed by |
| 401 | braces, you can use it at the start of each line of a paragraph. For |
| 402 | example, you could write |
| 403 | |
| 404 | \c \c #include <stdio.h> |
| 405 | \c \c |
| 406 | \c \c int main(int argc, char **argv) { |
| 407 | \c \c printf("hello, world\n"); |
| 408 | \c \c return 0; |
| 409 | \c \c } |
| 410 | |
| 411 | and Halibut would generate |
| 412 | |
| 413 | \quote{ |
| 414 | |
| 415 | \c #include <stdio.h> |
| 416 | \c |
| 417 | \c int main(int argc, char **argv) { |
| 418 | \c printf("hello, world\n"); |
| 419 | \c return 0; |
| 420 | \c } |
| 421 | |
| 422 | } |
| 423 | |
| 424 | Note that the above paragraph makes use of a backslash and a pair of |
| 425 | braces, and does \e{not} need to escape them in the way described in |
| 426 | \k{input-basics}. This is because code paragraphs formatted in this |
| 427 | way are a special case; the intention is that you can just copy and |
| 428 | paste a lump of code out of another program, put \q{\cw{\\c }} at the |
| 429 | start of every line, and simply \e{not have to worry} about the |
| 430 | details - you don't have to go through the whole block looking for |
| 431 | characters to escape. |
| 432 | |
| 433 | Since a backslash inside a code paragraph generates a literal |
| 434 | backslash, this means you cannot use any other Halibut formatting |
| 435 | commands inside a code paragraph. In particular, if you want to |
| 436 | emphasise a particular word in the paragraph, you can't do that |
| 437 | using \c{\\e} (\k{input-emph}) in the normal way. |
| 438 | |
| 439 | Therefore, Halibut provides an alternative means of emphasis in code |
| 440 | paragraphs. Each line beginning with \c{\\c} can optionally be |
| 441 | followed by a single line beginning with \c{\\e}, indicating the |
| 442 | emphasis in that line. The emphasis line contains the letters \c{b} |
| 443 | and \c{i} (for \q{bold} and \q{italic}, although some output formats |
| 444 | might render \c{i} as underlining instead of italics), positioned |
| 445 | to line up under the parts of the text that you want emphasised. |
| 446 | |
| 447 | For example, if you wanted to do syntax highlighting on the above C |
| 448 | code by highlighting the preprocessor command in italic and the |
| 449 | keywords in bold, you might do it like this: |
| 450 | |
| 451 | \c \c #include <stdio.h> |
| 452 | \c \e iiiiiiiiiiiiiiiiii |
| 453 | \c \c |
| 454 | \c \c int main(int argc, char **argv) { |
| 455 | \c \e bbb bbb bbbb |
| 456 | \c \c printf("hello, world\n"); |
| 457 | \c \c return 0; |
| 458 | \c \e bbbbbb |
| 459 | \c \c } |
| 460 | |
| 461 | and Halibut would generate: |
| 462 | |
| 463 | \quote{ |
| 464 | |
| 465 | \c #include <stdio.h> |
| 466 | \e iiiiiiiiiiiiiiiiii |
| 467 | \c |
| 468 | \c int main(int argc, char **argv) { |
| 469 | \e bbb bbb bbbb |
| 470 | \c printf("hello, world\n"); |
| 471 | \c return 0; |
| 472 | \e bbbbbb |
| 473 | \c } |
| 474 | |
| 475 | } |
| 476 | |
| 477 | Note that not every \c{\\c} line has to be followed by a \c{\\e} |
| 478 | line; they're optional. |
| 479 | |
| 480 | Also, note that highlighting within a code paragraph is |
| 481 | \e{discretionary}. Not all of Halibut's output formats can support |
| 482 | it (plain text, in particular, has no sensible way to do it). Unless |
| 483 | you know you are using a restricted range of output formats, you |
| 484 | should use highlighting in code paragraphs \e{only} as a visual aid, |
| 485 | and not rely on it to convey any vital semantic content. |
| 486 | |
| 487 | \S{input-lists} \c{\\b}, \c{\\n}, \c{\\dt}, \c{\\dd}, \c{\\lcont}: Lists |
| 488 | |
| 489 | Halibut supports bulletted lists, numbered lists and description |
| 490 | lists. |
| 491 | |
| 492 | \S2{input-list-bullet} \c{\\b}: Bulletted lists |
| 493 | |
| 494 | To create a bulletted list, you simply prefix each paragraph |
| 495 | describing a bullet point with the command \c{\\b}. For example, this |
| 496 | Halibut input: |
| 497 | |
| 498 | \c Here's a list: |
| 499 | \c |
| 500 | \c \b One. |
| 501 | \c |
| 502 | \c \b Two. |
| 503 | \c |
| 504 | \c \b Three. |
| 505 | |
| 506 | would produce this Halibut output: |
| 507 | |
| 508 | \quote{ |
| 509 | Here's a list: |
| 510 | |
| 511 | \b One. |
| 512 | |
| 513 | \b Two. |
| 514 | |
| 515 | \b Three. |
| 516 | } |
| 517 | |
| 518 | \S2{input-list-number} \c{\\n}: Numbered lists |
| 519 | |
| 520 | Numbered lists are just as simple: instead of \c{\\b}, you use |
| 521 | \c{\\n}, and Halibut takes care of getting the numbering right for |
| 522 | you. For example: |
| 523 | |
| 524 | \c Here's a list: |
| 525 | \c |
| 526 | \c \n One. |
| 527 | \c |
| 528 | \c \n Two. |
| 529 | \c |
| 530 | \c \n Three. |
| 531 | |
| 532 | This produces the Halibut output: |
| 533 | |
| 534 | \quote{ |
| 535 | Here's a list: |
| 536 | |
| 537 | \n One. |
| 538 | |
| 539 | \n Two. |
| 540 | |
| 541 | \n Three. |
| 542 | } |
| 543 | |
| 544 | The disadvantage of having Halibut sort out the list numbering for |
| 545 | you is that if you need to refer to a list item by its number, you |
| 546 | can't reliably do so. To get round this, Halibut allows an optional |
| 547 | keyword in braces after the \c{\\n} command. This keyword can then |
| 548 | be referenced using the \c{\\k} or \c{\\K} command (see |
| 549 | \k{input-xref}) to provide the number of the list item. For example: |
| 550 | |
| 551 | \c Here's a list: |
| 552 | \c |
| 553 | \c \n One. |
| 554 | \c |
| 555 | \c \n{this-one} Two. |
| 556 | \c |
| 557 | \c \n Three. |
| 558 | \c |
| 559 | \c \n Now go back to step \k{this-one}. |
| 560 | |
| 561 | This produces the following output: |
| 562 | |
| 563 | \quote{ |
| 564 | Here's a list: |
| 565 | |
| 566 | \n One. |
| 567 | |
| 568 | \n{this-one} Two. |
| 569 | |
| 570 | \n Three. |
| 571 | |
| 572 | \n Now go back to step \k{this-one}. |
| 573 | } |
| 574 | |
| 575 | \S2{input-list-description} \c{\\dt} and \c{\\dd}: Description lists |
| 576 | |
| 577 | To wrie a description list, you prefix alternate paragraphs with the |
| 578 | \c{\\dt} (\q{described thing}) and \c{\\dd} (description) commands. |
| 579 | For example: |
| 580 | |
| 581 | \c \dt Pelican |
| 582 | \c |
| 583 | \c \dd This is a large bird with a big beak. |
| 584 | \c |
| 585 | \c \dt Panda |
| 586 | \c |
| 587 | \c \dd This isn't. |
| 588 | |
| 589 | This produces the following output: |
| 590 | |
| 591 | \quote{ |
| 592 | |
| 593 | \dt Pelican |
| 594 | |
| 595 | \dd This is a large bird with a big beak. |
| 596 | |
| 597 | \dt Panda |
| 598 | |
| 599 | \dd This isn't. |
| 600 | |
| 601 | } |
| 602 | |
| 603 | \S2{input-list-continuation} Continuing list items into further |
| 604 | paragraphs |
| 605 | |
| 606 | All three of the above list types assume that each list item is a |
| 607 | single paragraph. For a short, snappy list in which each item is |
| 608 | likely to be only one or two words, this is perfectly sufficient; |
| 609 | but occasionally you will find you want to include several |
| 610 | paragraphs in a single list item, or even to nest other types of |
| 611 | paragraph (such as code paragraphs, or other lists) inside a list |
| 612 | item. |
| 613 | |
| 614 | To do this, you use the \c{\\lcont} command. This is a command which |
| 615 | can span \e{multiple} paragraphs. |
| 616 | |
| 617 | After the first paragraph of a list item, include the text |
| 618 | \c{\\lcont\{}. This indicates that the subsequent paragraph(s) are a |
| 619 | \e{continuation} of the list item that has just been seen. So you |
| 620 | can include further paragraphs, and eventually include a closing |
| 621 | brace \c{\}} to finish the list continuation. After that, you can |
| 622 | either continue adding other items to the original list, or stop |
| 623 | immediately and return to writing normal paragraphs of text. |
| 624 | |
| 625 | Here's a (long) example. |
| 626 | |
| 627 | \c Here's a list: |
| 628 | \c |
| 629 | \c \n One. This item is followed by a code paragraph: |
| 630 | \c |
| 631 | \c \lcont{ |
| 632 | \c |
| 633 | \c \c code |
| 634 | \c \c paragraph |
| 635 | \c |
| 636 | \c } |
| 637 | \c |
| 638 | \c \n Two. Now when I say \q{two}, I mean: |
| 639 | \c |
| 640 | \c \lcont{ |
| 641 | \c |
| 642 | \c \n Two, part one. |
| 643 | \c |
| 644 | \c \n Two, part two. |
| 645 | \c |
| 646 | \c \n Two, part three. |
| 647 | \c |
| 648 | \c } |
| 649 | \c |
| 650 | \c \n Three. |
| 651 | |
| 652 | The output produced by this fragment is: |
| 653 | |
| 654 | \quote{ |
| 655 | |
| 656 | Here's a list: |
| 657 | |
| 658 | \n One. This item is followed by a code paragraph: |
| 659 | |
| 660 | \lcont{ |
| 661 | |
| 662 | \c code |
| 663 | \c paragraph |
| 664 | |
| 665 | } |
| 666 | |
| 667 | \n Two. Now when I say \q{two}, I mean: |
| 668 | |
| 669 | \lcont{ |
| 670 | |
| 671 | \n Two, part one. |
| 672 | |
| 673 | \n Two, part two. |
| 674 | |
| 675 | \n Two, part three. |
| 676 | |
| 677 | } |
| 678 | |
| 679 | \n Three. |
| 680 | |
| 681 | } |
| 682 | |
| 683 | This syntax seems a little bit inconvenient, and perhaps |
| 684 | counter-intuitive: you might expect the enclosing braces to have to |
| 685 | go around the \e{whole} list item, rather than everything except the |
| 686 | first paragraph. |
| 687 | |
| 688 | \c{\\lcont} is a recent addition to the Halibut input language; |
| 689 | previously, \e{all} lists were required to use no more than one |
| 690 | paragraph per list item. So it's certainly true that this feature |
| 691 | looks like an afterthought because it \e{is} an afterthought, and |
| 692 | it's possible that if I'd been designing the language from scratch |
| 693 | with multiple-paragraph list items in mind, I would have made it |
| 694 | look different. |
| 695 | |
| 696 | However, the advantage of doing it this way is that no enclosing |
| 697 | braces are required in the \e{common} case: simple lists with only |
| 698 | one paragraph per item are really, really easy to write. So I'm not |
| 699 | too unhappy with the way it turned out; it obeys the doctrine of |
| 700 | making simple things simple, and difficult things possible. |
| 701 | |
| 702 | Note that \c{\\lcont} can only be used on \c{\\b}, \c{\\n} and |
| 703 | \c{\\dd} paragraphs; it cannot be used on \c{\\dt}. |
| 704 | |
| 705 | \S{input-rule} \c{\\rule}: Horizontal rules |
| 706 | |
| 707 | The command \c{\\rule}, appearing on its own as a paragraph, will |
| 708 | cause a horizontal rule to be drawn, like this: |
| 709 | |
| 710 | \c Some text. |
| 711 | \c |
| 712 | \c \rule |
| 713 | \c |
| 714 | \c Some more text. |
| 715 | |
| 716 | This produces the following output: |
| 717 | |
| 718 | \quote{ |
| 719 | |
| 720 | Some text. |
| 721 | |
| 722 | \rule |
| 723 | |
| 724 | Some more text. |
| 725 | |
| 726 | } |
| 727 | |
| 728 | \S{input-quote} \c{\\quote}: Indenting multiple paragraphs as a long |
| 729 | quotation |
| 730 | |
| 731 | Quoting verbatim text using a code paragraph (\k{input-codepara}) is |
| 732 | not always sufficient for your quoting needs. Sometimes you need to |
| 733 | quote some normally formatted text, possibly in multiple paragraphs. |
| 734 | |
| 735 | To do this, you can use the \c{\\quote} command. Like \c{\\lcont}, |
| 736 | this is a command which expects to enclose at least one paragraph |
| 737 | and possibly more. Simply write \c{\\quote\{} at the beginning of |
| 738 | your quoted section, and \c{\}} at the end, and the paragraphs in |
| 739 | between will be formatted to indicate that they are a quotation. |
| 740 | |
| 741 | (This very manual, in fact, uses this feature a lot: all of the |
| 742 | examples of Halibut source followed by Halibut output have the |
| 743 | output quoted using \c{\\quote}.) |
| 744 | |
| 745 | Here's some example Halibut input: |
| 746 | |
| 747 | \c In \q{Through the Looking Glass}, Lewis Carroll wrote: |
| 748 | \c |
| 749 | \c \quote{ |
| 750 | \c |
| 751 | \c \q{The question is,} said Alice, \q{whether you \e{can} make |
| 752 | \c words mean so many different things.} |
| 753 | \c |
| 754 | \c \q{The question is,} said Humpty Dumpty, \q{who is to be master - |
| 755 | \c that's all.} |
| 756 | \c |
| 757 | \c } |
| 758 | \c |
| 759 | \c So now you know. |
| 760 | |
| 761 | The output generated by this is: |
| 762 | |
| 763 | \quote{ |
| 764 | |
| 765 | In \q{Through the Looking Glass}, Lewis Carroll wrote: |
| 766 | |
| 767 | \quote{ |
| 768 | |
| 769 | \q{The question is,} said Alice, \q{whether you \e{can} make |
| 770 | words mean so many different things.} |
| 771 | |
| 772 | \q{The question is,} said Humpty Dumpty, \q{who is to be master - |
| 773 | that's all.} |
| 774 | |
| 775 | } |
| 776 | |
| 777 | So now you know. |
| 778 | |
| 779 | } |
| 780 | |
| 781 | \S{input-sections} \c{\\C}, \c{\\H}, \c{\\S}, \c{\\A}, \c{\\U}: |
| 782 | Chapter and section headings |
| 783 | |
| 784 | \K{intro-features} mentions that Halibut numbers the sections of |
| 785 | your document automatically, and can generate cross-references to |
| 786 | them on request; \k{input-xref} describes the \c{\\k} and \c{\\K} |
| 787 | commands used to generate the cross-references. This section |
| 788 | describes the commands used to set up the sections in the first |
| 789 | place. |
| 790 | |
| 791 | A paragraph beginning with the \c{\\C} command defines a chapter |
| 792 | heading. The \c{\\C} command expects to be followed by a pair of |
| 793 | braces containing a keyword for the chapter; this keyword can then |
| 794 | be used with the \c{\\k} and \c{\\K} commands to generate |
| 795 | cross-references to the chapter. After the closing brace, the rest |
| 796 | of the paragraph is used as the displayed chapter title. So the |
| 797 | heading for the current chapter of this manual, for example, is |
| 798 | written as |
| 799 | |
| 800 | \c \C{input} Halibut input format |
| 801 | |
| 802 | and this allows me to use the command \c{\\k\{input\}} to generate a |
| 803 | cross-reference to that chapter somewhere else. |
| 804 | |
| 805 | The next level down from \c{\\C} is \c{\\H}, for \q{heading}. This |
| 806 | is used in exactly the same way as \c{\\C}, but section headings |
| 807 | defined with \c{\\H} are considered to be part of a containing |
| 808 | chapter, and will be numbered with a pair of numbers. After \c{\\H} |
| 809 | comes \c{\\S}, and if necessary you can then move on to \c{\\S2}, |
| 810 | \c{\\S3} and so on. |
| 811 | |
| 812 | For example, here's a sequence of heading commands. Normally these |
| 813 | commands would be separated at least by blank lines (because each is |
| 814 | a separate paragraph), and probably also by body text; but for the |
| 815 | sake of brevity, both of those have been left out in this example. |
| 816 | |
| 817 | \c \C{foo} Using Foo |
| 818 | \c \H{foo-intro} Introduction to Foo |
| 819 | \c \H{foo-running} Running the Foo program |
| 820 | \c \S{foo-inter} Running Foo interactively |
| 821 | \c \S{foo-batch} Running Foo in batch mode |
| 822 | \c \H{foo-trouble} Troubleshooting Foo |
| 823 | \c \C{bar} Using Bar instead of Foo |
| 824 | |
| 825 | This would define two chapters with keywords \c{foo} and \c{bar}, |
| 826 | which would end up being called Chapter 1 and Chapter 2 (unless |
| 827 | there were other chapters before them). The sections \c{foo-intro}, |
| 828 | \c{foo-running} and \c{foo-trouble} would be referred to as Section |
| 829 | 1.1, Section 1.2 and Section 1.3 respectively; the subsections |
| 830 | \c{foo-inter} and \c{foo-batch} would be Section 1.2.1 and Section |
| 831 | 1.2.2. If there had been a \c{\\S2} command within one of those, it |
| 832 | would have been something like Section 1.2.1.1. |
| 833 | |
| 834 | If you don't like the switch from \c{\\H} to \c{\\S}, you can use |
| 835 | \c{\\S1} as a synonym for \c{\\S} and \c{\\S0} as a synonym for |
| 836 | \c{\\H}. Chapters are still designated with \c{\\C}, because they |
| 837 | need to be distinguished from other types of chapter such as |
| 838 | appendices. (Personally, I like the \c{\\C},\c{\\H},\c{\\S} notation |
| 839 | because it encourages me to think of my document as a hard disk :-) |
| 840 | |
| 841 | You can define an appendix by using \c{\\A} in place of \c{\\C}. |
| 842 | This is no different from a chapter except that it's given a letter |
| 843 | instead of a number, and cross-references to it will say \q{Appendix |
| 844 | A} instead of \q{Chapter 9}. Subsections of an appendix will be |
| 845 | numbered \q{A.1}, \q{A.2}, \q{A.2.1} and so on. |
| 846 | |
| 847 | If you want a particular section to be referred to as something |
| 848 | other than a \q{chapter}, \q{section} or \q{appendix}, you can |
| 849 | include a second pair of braces after the keyword. For example, if |
| 850 | you're writing a FAQ chapter and you want cross-references between |
| 851 | questions to refer to \q{question 1.2.3} instead of \q{section |
| 852 | 1.2.3}, you can write each section heading as |
| 853 | |
| 854 | \c \S{question-about-fish}{Question} What about fish? |
| 855 | |
| 856 | (The word \q{Question} should be given with an initial capital |
| 857 | letter. Halibut will lower-case it when you refer to it using |
| 858 | \c{\\k}, and will leave it alone if you use \c{\\K}.) |
| 859 | |
| 860 | This technique allows you to change the designation of |
| 861 | \e{particular} sections. To make an overall change in what \e{every} |
| 862 | section is called, see \k{input-config}. |
| 863 | |
| 864 | Finally, the \c{\\U} command defines an \e{unnumbered} chapter. |
| 865 | These sometimes occur in books, for specialist purposes such as |
| 866 | \q{Bibliography} or \q{Acknowledgements}. \c{\\U} does not expect a |
| 867 | keyword argument, because there is no sensible way to generate an |
| 868 | automatic cross-reference to such a chapter anyway. |
| 869 | |
| 870 | \S{input-blurb} \c{\\copyright}, \c{\\title}, \c{\\versionid}: |
| 871 | Miscellaneous blurb commands |
| 872 | |
| 873 | These three commands define a variety of special paragraph types. |
| 874 | They are all used in the same way: you put the command at the start |
| 875 | of a paragraph, and then just follow it with normal text, like this: |
| 876 | |
| 877 | \c \title My First Manual |
| 878 | |
| 879 | The three special paragraph types are: |
| 880 | |
| 881 | \dt \c{\\title} |
| 882 | |
| 883 | \dd This defines the overall title of the entire document. This |
| 884 | title is treated specially in some output formats (for example, it's |
| 885 | used in a \cw{<title>} tag in the HTML output), so it needs a |
| 886 | special paragraph type to point it out. |
| 887 | |
| 888 | \dt \c{\\copyright} |
| 889 | |
| 890 | \dd This command indicates that the paragraph attached to it |
| 891 | contains a copyright statement for the document. This text is |
| 892 | usually displayed inline, just before the first chapter title but |
| 893 | after any preamble text before that; but in some output formats it |
| 894 | is given additional special treatment. For example, Windows Help |
| 895 | files have a standard slot in which to store a copyright notice, so |
| 896 | that other software can display it prominently. |
| 897 | |
| 898 | \dt \c{\\versionid} |
| 899 | |
| 900 | \dd This command indicates that the paragraph contains a version |
| 901 | identifier, such as those produced by CVS (of the form \c{$\#{hope this |
| 902 | defuses CVS}Id: thingy.but,v 1.6 2004/01/01 16:47:48 simon Exp $}). |
| 903 | This text will be tucked away somewhere unobtrusive, so that anyone |
| 904 | wanting to (for example) report errors to the document's author can |
| 905 | pick out the version IDs and send them as part of the report, so |
| 906 | that the author can tell at a glance which revision of the document |
| 907 | is being discussed. |
| 908 | |
| 909 | \S{input-commentpara} \c{\\#}: Whole-paragraph comments |
| 910 | |
| 911 | \K{input-inline-comment} describes the use of the \c{\\#} command to |
| 912 | put a short comment in the middle of a paragraph. |
| 913 | |
| 914 | If you need to use a \e{long} comment, Halibut also allows you to |
| 915 | use \c{\\#} without braces, to indicate that an entire paragraph is |
| 916 | a comment, like this: |
| 917 | |
| 918 | \c Here's a (fairly short) paragraph which will be displayed. |
| 919 | \c |
| 920 | \c \# Here's a comment paragraph which will not be displayed, no |
| 921 | \c matter how long it goes on. All I needed to indicate this was the |
| 922 | \c single \# at the start of the paragraph; I don't need one on |
| 923 | \c every line or anything like that. |
| 924 | \c |
| 925 | \c Here's another displayed paragraph. |
| 926 | |
| 927 | When run through Halibut, this produces the following output: |
| 928 | |
| 929 | \quote{ |
| 930 | |
| 931 | Here's a (fairly short) paragraph which will be displayed. |
| 932 | |
| 933 | \# Here's a comment paragraph which will not be displayed, no |
| 934 | matter how long it goes on. All I needed to indicate this was the |
| 935 | single \# at the start of the paragraph; I don't need one on |
| 936 | every line or anything like that. |
| 937 | |
| 938 | Here's another displayed paragraph. |
| 939 | |
| 940 | } |
| 941 | |
| 942 | \H{input-biblio} Creating a bibliography |
| 943 | |
| 944 | If you need your document to refer to other documents (research |
| 945 | papers, books, websites, whatever), you might find a bibliography |
| 946 | feature useful. |
| 947 | |
| 948 | You can define a bibliography entry using the \c{\\B} command. This |
| 949 | looks very like the \c{\\C} command and friends: it expects a |
| 950 | keyword in braces, followed by some text describing the document |
| 951 | being referred to. For example: |
| 952 | |
| 953 | \c \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs. |
| 954 | \c Published by Paperjam & Notoner, 1993. |
| 955 | |
| 956 | If this bibliography entry appears in the finished document, it will |
| 957 | look something like this: |
| 958 | |
| 959 | \quote{ |
| 960 | |
| 961 | \B{freds-book} \q{The Taming Of The Mongoose}, by Fred Bloggs. |
| 962 | Published by Paperjam & Notoner, 1993. |
| 963 | |
| 964 | } |
| 965 | |
| 966 | I say \q{if} above because not all bibliography entries defined |
| 967 | using the \c{\\B} command will necessarily appear in the finished |
| 968 | document. They only appear if they are referred to by a \c{\\k} |
| 969 | command (see \k{input-xref}). This allows you to (for example) |
| 970 | maintain a single Halibut source file with a centralised database of |
| 971 | \e{all} the references you have ever needed in any of your writings, |
| 972 | include that file in every document you feed to Halibut, and have it |
| 973 | only produce the bibliography entries you actually need for each |
| 974 | particular document. (In fact, you might even want this centralised |
| 975 | source file to be created automatically by, say, a Perl script from |
| 976 | BibTeX input, so that you can share the same bibliography with users |
| 977 | of other formatting software.) |
| 978 | |
| 979 | If you really want a bibliography entry to appear in the document |
| 980 | even though no text explicitly refers to it, you can do that using |
| 981 | the \c{\\nocite} command: |
| 982 | |
| 983 | \c \nocite{freds-book} |
| 984 | |
| 985 | Normally, each bibliography entry will be referred to (in citations |
| 986 | and in the bibliography itself) by a simple reference number, such |
| 987 | as \k{freds-book}. If you would rather use an alternative reference |
| 988 | notation, such as [Fred1993], you can use the \c{\\BR} |
| 989 | (\q{Bibliography Rewrite}) command to specify your own reference |
| 990 | format for a particular book: |
| 991 | |
| 992 | \c \BR{freds-book} [Fred1993] |
| 993 | |
| 994 | \H{input-index} Creating an index |
| 995 | |
| 996 | Halibut contains a comprehensive indexing mechanism, which attempts |
| 997 | to be reasonably easy to use in the common case in spite of its |
| 998 | power. |
| 999 | |
| 1000 | \S{input-index-simple} Simple indexing |
| 1001 | |
| 1002 | In normal usage, you should be able to add index terms to your |
| 1003 | document simply by using the \c{\\i} command to wrap one or two |
| 1004 | words at a time. For example, if you write |
| 1005 | |
| 1006 | \c The \i{hippopotamus} is a particularly large animal. |
| 1007 | |
| 1008 | then the index will contain an entry under \q{hippopotamus}, |
| 1009 | pointing to that sentence (or as close to that sentence as the |
| 1010 | output format sensibly permits). |
| 1011 | |
| 1012 | You can wrap more than one word in \c{\\i} as well: |
| 1013 | |
| 1014 | \c We recommend using a \i{torque wrench} for this job. |
| 1015 | |
| 1016 | \S{input-index-special} Special cases of indexing |
| 1017 | |
| 1018 | If you need to index a computer-related term, you can use the |
| 1019 | special case \c{\\i\\c}: |
| 1020 | |
| 1021 | \c The \i\c{grep} command is what you want here. |
| 1022 | |
| 1023 | This will cause the word \q{grep} to appear in code style, as if the |
| 1024 | \c{\\i} were not present and the input just said \c{\\c\{grep\}}; |
| 1025 | the word will also appear in code style in the actual index. |
| 1026 | |
| 1027 | If you want to simultaneously index and emphasise a word, there's |
| 1028 | another special case \c{\\i\\e}: |
| 1029 | |
| 1030 | \c This is what we call a \i\e{paper jam}. |
| 1031 | |
| 1032 | This will cause the words \q{paper jam} to be emphasised in the |
| 1033 | document, but (unlike the behaviour of \c{\\i\\c}) they will \e{not} |
| 1034 | be emphasised in the index. This different behaviour is based on an |
| 1035 | expectation that most people indexing a word of computer code will |
| 1036 | still want it to look like code in the index, whereas most people |
| 1037 | indexing an emphasised word will \e{not} want it emphasised in the |
| 1038 | index. |
| 1039 | |
| 1040 | Sometimes you might want to index a term which is not explicitly |
| 1041 | mentioned, but which is highly relevant to the text and you think |
| 1042 | that somebody looking up that term in the index might find it useful |
| 1043 | to be directed here. To do this you can use the \c{\\I} command, to |
| 1044 | create an \e{invisible} index tag: |
| 1045 | |
| 1046 | \c If your printer runs out of toner, \I{replacing toner |
| 1047 | \c cartridge}here is what to do: |
| 1048 | |
| 1049 | This input will produce only the output \q{If your printer runs out |
| 1050 | of toner, here is what to do}; but an index entry will show up under |
| 1051 | \q{replacing toner cartridge}, so that if a user thinks the obvious |
| 1052 | place to start in the index is under R for \q{replacing}, they will |
| 1053 | find their way here with a minimum of fuss. |
| 1054 | |
| 1055 | (It's worth noting that there is no functional difference between |
| 1056 | \c{\\i\{foo\}} and \c{\\I\{foo\}foo}. The simple \c{\\i} case is |
| 1057 | only a shorthand for the latter.) |
| 1058 | |
| 1059 | Finally, if you want to index a word at the start of a sentence, you |
| 1060 | might very well not want it to show up with a capital letter in the |
| 1061 | index. For this, Halibut provides the \c{\\ii} command, for \q{index |
| 1062 | (case-)insensitively}. You use it like this: |
| 1063 | |
| 1064 | \c \ii{Lions} are at the top of the food chain in this area. |
| 1065 | |
| 1066 | This is equivalent to \c{\\I\{lions\}Lions}; in other words, the |
| 1067 | text will say \q{Lions}, but it will show up in the index as |
| 1068 | \q{lions}. The text inside \c{\\ii} is converted entirely into lower |
| 1069 | case before being added to the index data. |
| 1070 | |
| 1071 | \S{input-index-rewrite} Fine-tuning the index |
| 1072 | |
| 1073 | Halibut's index mechanism as described so far still has a few |
| 1074 | problems left: |
| 1075 | |
| 1076 | \b In a reasonably large index, it's often difficult to predict |
| 1077 | which of several words a user will think of first when trying to |
| 1078 | look something up. For example, if they want to know how to replace |
| 1079 | a toner cartridge, they might look up \q{replacing} or they might |
| 1080 | look up \q{toner cartridge}. You probably don't really want to have |
| 1081 | to try to figure out which of those is more likely; instead, what |
| 1082 | you'd like is to be able to effortlessly index the same set of |
| 1083 | document locations under \e{both} terms. |
| 1084 | |
| 1085 | \b Also, you may find you've indexed the same concept under multiple |
| 1086 | different index terms; for example, there might be several instances |
| 1087 | of \c{\\i\{frog\}} and several of \c{\\i\{frogs\}}, so that you'd |
| 1088 | end up with two separate index entries for what really ought to be |
| 1089 | the same concept. |
| 1090 | |
| 1091 | \b You might well not want the word \q{\cw{grep}} to appear in the |
| 1092 | index without explanation; you might prefer it to say something more |
| 1093 | verbose such as \q{\cw{grep} command}, so that a user encountering |
| 1094 | it in the index has some idea of what it is \e{without} having to |
| 1095 | follow up the reference. However, you certainly don't want to have |
| 1096 | to write \c{\\I\{\\cw\{grep\} command\}\\c\{grep\}} every time you |
| 1097 | want to add an index term for this! You wanted to write |
| 1098 | \c{\\i\\c\{grep\}} as shown in the previous section, and tidy it all |
| 1099 | up afterwards. |
| 1100 | |
| 1101 | All of these problems can be cleaned up by the \c{\\IM} (for |
| 1102 | \q{Index Modification}) command. \c{\\IM} expects to be followed by |
| 1103 | one or more pairs of braces containing index terms as seen in the |
| 1104 | document, and then a piece of text (not in braces) describing how it |
| 1105 | should be shown in the index. |
| 1106 | |
| 1107 | So to rewrite the \c{grep} example above, you might do this: |
| 1108 | |
| 1109 | \c \IM{grep} \cw{grep} command |
| 1110 | |
| 1111 | This will arrange that the set of places in the document where you |
| 1112 | asked Halibut to index \q{\cw{grep}} will be listed under |
| 1113 | \q{\cw{grep} command} rather than just under \q{\cw{grep}}. |
| 1114 | |
| 1115 | You can specify more than one index term in a \c{\\IM} command; so |
| 1116 | to merge the index terms \q{frog} and \q{frogs} into a single term, |
| 1117 | you might do this: |
| 1118 | |
| 1119 | \c \IM{frog}{frogs} frog |
| 1120 | |
| 1121 | This will arrange that the single index entry \q{frog} will list |
| 1122 | \e{all} the places in the document where you asked Halibut to index |
| 1123 | either \q{frog} or \q{frogs}. |
| 1124 | |
| 1125 | You can use multiple \c{\\IM} commands to replicate the same set of |
| 1126 | document locations in more than one index entry. For example: |
| 1127 | |
| 1128 | \c \IM{replacing toner cartridge} replacing toner cartridge |
| 1129 | \c \IM{replacing toner cartridge} toner cartridge, replacing |
| 1130 | |
| 1131 | This will arrange that every place in the document where you have |
| 1132 | indexed \q{replacing toner cartridge} will be listed both there |
| 1133 | \e{and} under \q{toner cartridge, replacing}, so that no matter |
| 1134 | whether the user looks under R or under T they will stil find their |
| 1135 | way to the same parts of the document. |
| 1136 | |
| 1137 | In this example, note that although the first \c{\\IM} command |
| 1138 | \e{looks} as if it's a tautology, it is still necessary, because |
| 1139 | otherwise those document locations will \e{only} be indexed under |
| 1140 | \q{toner cartridge, replacing}. If you have \e{no} explicit \c{\\IM} |
| 1141 | commands for a particular index term, then Halibut will assume a |
| 1142 | default one (typically \c{\\IM\{foo\}\_foo}, although it might be |
| 1143 | \c{\\IM\{foo\}\_\\c\{foo\}} if you originally indexed using |
| 1144 | \c{\\i\\c}); but as soon as you specify an explicit \c{\\IM}, |
| 1145 | Halibut discards its default implicit one, and you must then specify |
| 1146 | that one explicitly as well if you wanted to keep it. |
| 1147 | |
| 1148 | \H{input-config} Configuring Halibut |
| 1149 | |
| 1150 | Halibut uses the \c{\\cfg} command to allow you to configure various |
| 1151 | aspects of its functionality. |
| 1152 | |
| 1153 | The \c{\\cfg} command expects to be followed by at least one pair of |
| 1154 | braces, and usually more after that. The first pair of braces |
| 1155 | contains a keyword indicating what aspect of Halibut you want to |
| 1156 | configure, and the meaning of the one(s) after that depends on the |
| 1157 | first keyword. |
| 1158 | |
| 1159 | The current list of configuration keywords in the main Halibut code |
| 1160 | is quite small. Here it is in full: |
| 1161 | |
| 1162 | \dt \cw{\\cfg\{chapter\}\{}\e{new chapter name}\cw{\}} |
| 1163 | |
| 1164 | \dd This tells Halibut that you don't want to call a chapter a |
| 1165 | chapter any more. For example, if you give the command |
| 1166 | \cw{\\cfg\{chapter\}\{Book\}}, then any chapter defined with the |
| 1167 | \c{\\C} command will be labelled \q{Book} rather than \q{Chapter}, |
| 1168 | both in the section headings and in cross-references. This is |
| 1169 | probably most useful if your document is not written in English. |
| 1170 | |
| 1171 | \dt \cw{\\cfg\{section\}\{}\e{new section name}\cw{\}} |
| 1172 | |
| 1173 | \dd Exactly like \c{chapter}, but changes the name given to |
| 1174 | subsections of a chapter. |
| 1175 | |
| 1176 | \dt \cw{\\cfg\{appendix\}\{}\e{new appendix name}\cw{\}} |
| 1177 | |
| 1178 | \dd Exactly like \c{appendix}, but changes the name given to |
| 1179 | appendices. |
| 1180 | |
| 1181 | In addition to these configuration commands, there are also |
| 1182 | configuration commands provided by each individual output format. |
| 1183 | These configuration commands are discussed along with each output |
| 1184 | format, in FIXME. |
| 1185 | |
| 1186 | \H{input-macro} Defining macros |
| 1187 | |
| 1188 | If there's a complicated piece of Halibut source which you think |
| 1189 | you're going to use a lot, you can define your own Halibut command |
| 1190 | to produce that piece of source. |
| 1191 | |
| 1192 | In \k{input-unicode}, there is a sample piece of code which prints a |
| 1193 | Euro sign, or replaces it with \q{EUR} if the Euro sign is not |
| 1194 | available: |
| 1195 | |
| 1196 | \c This is likely to cost \u20AC{EUR }2500 at least. |
| 1197 | |
| 1198 | If your document quotes a \e{lot} of prices in Euros, you might not |
| 1199 | want to spend all your time typing that out. So you could define a |
| 1200 | macro, using the \c{\\define} command: |
| 1201 | |
| 1202 | \c \define{eur} \u20AC{EUR } |
| 1203 | |
| 1204 | Then you can just write ... |
| 1205 | |
| 1206 | \c This is likely to cost \eur 2500 at least. |
| 1207 | |
| 1208 | ... except that that's not terribly good, because you end up with a |
| 1209 | space between the Euro sign and the number. In this case, it's |
| 1210 | helpful to use the special \c{\\.} command, which is defined to do |
| 1211 | nothing at all! But it acts as a separator between your macro and |
| 1212 | the next character: |
| 1213 | |
| 1214 | \c This is likely to cost \eur\.2500 at least. |
| 1215 | |
| 1216 | This way, you will see no space between the Euro sign and the number |
| 1217 | (although, of course, there will be space between \q{EUR} and the |
| 1218 | number if the Euro sign is not available, because the macro |
| 1219 | definition specifically asked for it). |