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