1 \C{output} Halibut output formats
3 This chapter describes each of Halibut's current \i{output formats}.
4 It gives some general information about the format, and also
5 describes all the \i{configuration directives} which are specific to
8 \H{output-text} Plain text
10 This output format generates the document as a single \i{plain text}
13 The output file is currently assumed to be in the \i{ISO 8859-1}
14 character set. Any Unicode characters representable in this set will
15 be output verbatim; any other characters will not be output and
16 their \i{fallback text} (if any) will be used instead.
18 The precise formatting of the text file can be controlled by a
19 variety of configuration directives. They are listed in the
20 following subsections.
22 \S{output-text-file} Output file name
24 \dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}}
26 \dd Sets the \i{output file name} in which to store the text file.
27 This directive is implicitly generated if you provide a file name
28 parameter after the command-line option \i\c{--text} (see
31 \S{output-text-dimensions} Indentation and line width
33 This section describes the configuration directives which control
34 the \i{horizontal dimensions} of the output text file: how much
35 paragraphs are indented by and how long the lines are.
37 \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
39 \dd Sets the \I{text width}width of the main part of the document,
40 in characters. This width will be used for wrapping paragraphs and
41 for centring titles (if you have asked for titles to be centred -
42 see \k{output-text-headings}). This width does \e{not} include the
43 left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
44 indent of 8 and a width of 64, your maximum output line length will
47 \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
49 \dd Sets the left \i{indentation} for the document. If you set this
50 to zero, your document will look like an ordinary text file as
51 someone with a text editor might have written it; if you set it
52 above zero, the text file will have a \i{margin} down the left in
53 the style of some printed manuals, and you can then configure the
54 section numbers to appear in this margin (see
55 \k{output-text-headings}).
57 \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
59 \dd Specifies how many extra characters of indentation (on top of
60 the normal left indent) should be given to \I{code paragraphs,
61 indentation} code paragraphs.
63 \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
65 \dd Specifies how many extra spaces should be used to indent the
66 bullet or number in a \I{bulletted list, indentation}bulletted or
67 \I{numbered list, indentation}numbered \I{list, indentation}list.
68 The actual body of the list item will be indented by this much
69 \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}.
71 \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
73 \dd Specifies how many extra spaces should be used to indent the
74 body of a list item, over and above the number configured in
75 \cw{\\cfg\{text-list-indent\}}.
77 \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
79 \dd When this is set to \c{true}, the document \i{preamble} (i.e. any
80 paragraphs appearing before the first chapter heading) will be
81 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
82 this setting is \c{false}, the document preamble will not be
83 indented at all from the left margin.
85 \S{output-text-headings} \ii{Configuring heading display}
87 The directives in this section allow you to configure the appearance
88 of the title, chapter and section headings in your text file.
90 Several of the directives listed below specify the \i{alignment} of
91 a heading. These alignment options have three possible values:
95 \dd Align the heading to the very left of the text file (column zero).
99 \dd Align the section title to the left of the main display region
100 (in other words, indented to the level specified by
101 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
102 left of that (so that it goes in the margin if there is room).
106 \dd Centre the heading.
108 Also, several of the directives below specify how a title should be
109 \I{underlining}underlined. The parameter to one of these directives
110 should be either blank (\cw{\{\}}) or a piece of text which will be
111 repeated to produce the underline. So you might want to specify, for
112 example, \cw{\\text-title-underline\{=\}} but
113 \cw{\\text-chapter-underline\{\-\}}.
115 You can also specify more than one underline setting, and Halibut
116 will choose the first one that the output character set supports.
117 So, for example, you could write
118 \cw{\\text-chapter-underline\{\u203e\}\{\-\}}, and Halibut would use
119 the Unicode \q{OVERLINE} character where possible and fall back to
120 the ASCII minus sign otherwise.
122 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
124 \dd Specifies the alignment of the overall document title: \c{left},
125 \c{leftplus} or \c{centre}.
127 \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
129 \dd Specifies how the overall document title should be underlined.
131 \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
133 \dd Specifies the alignment of chapter and appendix headings.
135 \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
137 \dd Specifies how chapter and appendix headings should be underlined.
139 \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
141 \dd If this is set to \c{true}, then chapter headings will not
142 contain the word \q{Chapter} (or whatever other word you have
143 defined in its place - see \k{input-sections} and \k{input-config});
144 they will just contain the chapter \e{number}, followed by the
145 chapter title. If you set this to \c{false}, chapter headings will
146 be prefixed by \q{Chapter} or equivalent.
148 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
150 \dd This specifies the suffix text to be appended to the chapter
151 number, before displaying the chapter title. For example, if you set
152 this to \q{\cw{:\_}}, then the chapter title might look something
153 like \q{Chapter 2: Doing Things}.
155 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
157 \dd Specifies the alignment of section headings at a particular
158 level. The \e{level} parameter specifies which level of section
159 headings you want to affect: 0 means first-level headings (\c{\\H}),
160 1 means second-level headings (\c{\\S}), 2 means the level below
161 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
162 just like the other alignment directives listed above.
164 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}}
166 \dd Specifies how to underline section headings at a particular level.
168 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
170 \dd Specifies whether section headings at a particular level should
171 contain the word \q{Section} or equivalent (if \c{false}), or should
172 be numeric only (if \c{true}).
174 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
176 \dd Specifies the \I{suffix text, in section titles}suffix text to
177 be appended to section numbers at a particular level, before
178 displaying the section title.
180 \S{output-text-characters} Configuring the characters used
182 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
184 \dd This specifies the text which should be used as the \i{bullet}
185 in bulletted lists. It can be one character
186 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
187 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
191 You can specify multiple possible options (each in their own pair of
192 braces) after this command, and Halibut will choose the first one
193 which the output character set supports. (This is to allow you to
194 configure the bullet character once, generate output in several
195 different character sets, and have Halibut constantly adapt to make
196 the best use of the current encoding.) For example, you might write
197 \cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case
198 Halibut would use the Unicode \q{BULLET} character where possible,
199 fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available,
200 and resort to the ASCII asterisk if all else failed.
204 \dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
206 \dd This specifies the text which should be used for drawing
207 \i{horizontal rules} (generated by \i\c{\\rule}; see
208 \k{input-rule}). It can be one character, or more than one. The
209 string you specify will be repeated to reach the required width, so
210 you can specify something like \q{\cw{-=}} to get a rule that looks
215 Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback
216 options in this command.
220 \dt \I{\cw{\\cfg\{text-quotes\}}}\cw{\\cfg\{text-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
222 \dd This specifies the quote characters which should be used in
223 response to the \c{\\q} command (see \k{input-quotes}). These quotes
224 will also be used to mark text enclosed in the \c{\\c} command (see
229 You should separately specify the open and close quote characters,
230 each of which can be more than one character if you want. Also, like
231 \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback options
232 in this command (a pair of open and close quotes, then another pair,
233 then another if you like); Halibut will always use a matching pair.
234 For example, you might write
236 \c \cfg{text-quotes}{\u201c}{\u201d}{"}{"}
238 and Halibut would use the Unicode matched double quote characters if
239 possible, and fall back to ASCII double quotes otherwise. If the
240 output character set were to contain U+201C but not U+201D, then
241 Halibut would fall back to using the ASCII double quote character as
242 \e{both} open and close quotes. (No known character set is that
243 silly; I mention it only as an example.)
247 \dt \I{\cw{\\cfg\{text-emphasis\}}}\cw{\\cfg\{text-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}]
249 \dd This specifies the characters which should be used to surround
250 emphasised text (written using the \c{\\e} command; see
255 You should separately specify the start-emphasis and end-emphasis
256 text, each of which can be more than one character if you want.
257 Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs
258 of fallback options in this command, and Halibut will always use a
263 \S{output-text-misc} Miscellaneous configuration options
265 \dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}}
267 \dd This text is appended to the number on a \i{numbered list} item
268 (see \k{input-list-number}). So if you want to label your lists as
269 \q{1)}, \q{2)} and so on, then you would write
270 \cw{\\cfg\{text-list-suffix\}\{)\}}.
272 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
274 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
275 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
276 included at the bottom of the text file. If it is set to \c{false},
277 they will be omitted completely.
279 \# FIXME: code indentation is configurable, therefore \quote
280 \# indentation probably ought to be as well.
282 \# FIXME: text-indent-* should be consistently named.
284 \S{output-text-defaults} Default settings
286 The \i{default settings} for Halibut's plain text output format are:
288 \c \cfg{text-filename}{output.txt}
290 \c \cfg{text-width}{68}
291 \c \cfg{text-indent}{7}
292 \c \cfg{text-indent-code}{2}
293 \c \cfg{text-list-indent}{1}
294 \c \cfg{text-listitem-indent}{3}
295 \c \cfg{text-indent-preamble}{false}
297 \c \cfg{text-title-align}{centre}
298 \c \cfg{text-title-underline}{\u2550}{=}
300 \c \cfg{text-chapter-align}{left}
301 \c \cfg{text-chapter-underline}{\u203e}{-}
302 \c \cfg{text-chapter-numeric}{false}
303 \c \cfg{text-chapter-suffix}{: }
305 \c \cfg{text-section-align}{0}{leftplus}
306 \c \cfg{text-section-underline}{0}{}
307 \c \cfg{text-section-numeric}{0}{true}
308 \c \cfg{text-section-suffix}{0}{ }
310 \c \cfg{text-section-align}{1}{leftplus}
311 \c \cfg{text-section-underline}{1}{}
312 \c \cfg{text-section-numeric}{1}{true}
313 \c \cfg{text-section-suffix}{1}{ }
315 \c ... and so on for all section levels below this ...
316 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
318 \c \cfg{text-bullet}{\u2022}{-}
319 \c \cfg{text-rule}{\u2500}{-}
320 \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
321 \c \cfg{text-emphasis}{_}{_}
323 \c \cfg{text-list-suffix}{.}
324 \c \cfg{text-versionid}{true}
328 This output format generates an \i{HTML} version of the document. By
329 default, this will be in multiple files, starting with
330 \c{Contents.html} and splitting the document into files by chapter
331 and/or subsection. You can configure precisely how the text is split
332 between HTML files using the configuration commands described in
333 this section. In particular, you can configure Halibut to output one
334 single HTML file instead of multiple ones.
336 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
337 which is why all of the configuration directives start with the word
338 \c{xhtml} rather than \c{html}.
340 \S{output-html-file} Controlling the output file names
342 \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
344 \dd Sets the \i{output file name} in which to store the top-level
345 contents page. Since this is the first page a user ought to see when
346 beginning to read the document, a good choice in many cases might be
347 \c{index.html} (although this is not the default, for historical
350 \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
352 \dd Sets the file name in which to store the document's index.
354 \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
356 \dd Provides a \i{template} to be used when constructing the file
357 names of each chapter or section of the document. This template
358 should contain at least one \i\e{formatting command}, in the form of
359 a per cent sign followed by a letter. (If you need a literal per
360 cent sign, you can write \c{%%}.)
364 The formatting commands used in this template are:
366 \dt \I{%N-upper}\c{%N}
368 \dd Expands to the visible title of the section, with white space
369 removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
370 Fish}}, this formatting command would expand to
371 \q{\cw{CatchingFish}}.
375 \dd Expands to the type and number of the section, without white
376 space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
377 section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
378 If the section has no number (an unnumbered chapter created using
379 \c{\\U}), this directive falls back to doing the same thing as
384 \dd Expands to the bare number of the section. So in chapter 1 this
385 would expand to \q{\cw{1}}; in section A.4.3 it would expand to
386 \q{\cw{A.4.3}}, and so on. If the section has no number (an
387 unnumbered chapter created using \c{\\U}), this directive falls back
388 to doing the same thing as \c{%N}.
392 \dd Expands to the internal keyword specified in the section title.
393 So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
394 formatting command would expand to \q{\cw{fish}}. If the section has
395 no keyword (an unnumbered chapter created using \c{\\U}), this
396 directive falls back to doing the same thing as \c{%N}.
398 These formatting directives can also be used in the
399 \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
400 \k{output-html-misc}).
404 \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
406 \dd Sets the file name in which to store the entire document, if
407 Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
408 produce a single self-contained file. Both this directive \e{and}
409 \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
410 provide a file name parameter after the command-line option
411 \i\c{--html} (see \k{running-options}).
413 \S{output-html-split} Controlling the splitting into HTML files
415 By default, the HTML output from Halibut is split into multiple
416 files. Each file typically contains a single chapter or section and
417 everything below it, unless subsections of that chapter are
418 themselves split off into further files.
420 Most files also contain a contents section, giving hyperlinks to the
421 sections in the file and/or the sections below it.
423 The configuration directives listed below allow you to configure the
424 splitting into files, and the details of the contents sections.
426 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
428 \dd This setting indicates the depth of section which should be
429 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
430 you set it to 1, for example, then every chapter will be given its
431 own HTML file, plus a top-level \i{contents file}. If you set this
432 to 2, then each chapter \e{and} each \c{\\H} section will have a
433 file, and the chapter files will mostly just contain links to their
438 If you set this option to zero, then the whole document will appear
439 in a single file. If you do this, Halibut will call that file
440 \i\c{Manual.html} instead of \i\c{Contents.html}.
442 This option is automatically set to zero if you provide a file name
443 parameter after the command-line option \i\c{--html} (see
444 \k{running-options}), because you have specified a single file name
445 and so Halibut assumes you want the whole document to be placed in
450 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
452 \dd This directive allows you to specify how \I{depth of
453 contents}deep the contents section in a particular file should go.
457 The \e{level} parameter indicates which level of contents section
458 you are dealing with. 0 denotes the main contents section in the
459 topmost file \c{Contents.html}; 1 denotes a contents section in a
460 chapter file; 2 is a contents section in a file containing a \c{\\H}
461 heading, and so on. Currently you can't go below level 5 (which
462 corresponds to a \c{\\S3} heading).
464 The \e{depth} parameter indicates the maximum depth of heading which
465 will be shown in this contents section. Again, 1 denotes a chapter,
466 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
468 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
469 Halibut to put contents links in chapter files for all sections down
470 to \c{\\S} level, but not to go into any more detail than that.
474 \# FIXME: this is utterly ghastly. For a start, it should include
475 \# the level as a separate argument, like the text section config
476 \# directives. Secondly, it shouldn't be limited in depth!
478 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
480 \dd If you set this to \c{true}, then each leaf file will contain
481 its own contents section which summarises the text within it.
483 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
485 \dd Contents sections in leaf files are not output at all if they
486 contain very few entries (on the assumption that it just isn't worth
487 bothering). This directive configures the minimum number of entries
488 required in a leaf contents section to make Halibut bother
489 generating it at all.
491 \S{output-html-html} Including pieces of your own HTML
493 The directives in this section allow you to supply pieces of
494 \I{HTML}\i{verbatim HTML} code, which will be included in various
495 parts of the output files.
497 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
499 \dd The text you provide in this directive is placed at the end of
500 the \i\cw{<HEAD>} section of each output HTML file. So this is a
501 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
503 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
505 \dd The text you provide in this directive is used in place of the
506 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
507 \i{background colour}, for example, you could write
508 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
510 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
512 \dd The text you provide in this directive is placed at the
513 beginning of the \i\cw{<BODY>} section of each output HTML file. So
514 if you intend your HTML files to be part of a web site with a
515 standard \i{house style}, and the style needs a \i{header} at the
516 top of every page, this is where you can add that header.
518 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
520 \dd The text you provide in this directive is placed at the end of
521 the \i\cw{<BODY>} section of each output HTML file. So if you intend
522 your HTML files to be part of a web site with a standard \i{house
523 style}, and the style needs a \i{footer} at the bottom of every
524 page, this is where you can add that footer.
526 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
528 \dd The text you provide in this directive is placed at the
529 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
530 output HTML file. This might be a good place to put authors'
531 \i{contact details}, for example.
533 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
535 \dd The text you provide in this directive is placed at the end of
536 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
537 after the version IDs (if present).
539 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
541 \dd The text you provide in this directive is included inside the
542 \cw{<P>} tag containing the \i{navigation links} at the top of each
543 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
544 wanted the navigation links to have a particular CSS style, you
546 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
547 navigation-links paragraph would then begin with the tag \cw{<p
550 \S{output-html-headings} \ii{Configuring heading display}
552 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
554 \dd If this is set to \c{true}, then chapter headings will not
555 contain the word \q{Chapter} (or whatever other word you have
556 defined in its place - see \k{input-sections} and \k{input-config});
557 they will just contain the chapter \e{number}, followed by the
558 chapter title. If you set this to \c{false}, chapter headings will
559 be prefixed by \q{Chapter} or equivalent.
561 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
563 \dd This specifies the suffix text to be appended to the chapter
564 number, before displaying the chapter title. For example, if you set
565 this to \q{\cw{:\_}}, then the chapter title might look something
566 like \q{Chapter 2: Doing Things}.
568 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
570 \dd Specifies whether section headings at a particular level should
571 contain the word \q{Section} or equivalent (if \c{false}), or should
572 be numeric only (if \c{true}). The \e{level} parameter specifies
573 which level of section headings you want to affect: 0 means
574 first-level headings (\c{\\H}), 1 means second-level headings
575 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
577 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
579 \dd Specifies the suffix text to be appended to section numbers at a
580 particular level, before displaying the section title.
582 \S{output-html-misc} Miscellaneous options
584 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
586 \dd This directive lets you specify a \i{template}, with exactly the
587 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
588 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
589 NAME="...">}) used to allow URLs to refer to specific sections
590 within a particular HTML file. So if you set this to \q{\cw{%k}},
591 for example, then each individual section in your document will be
592 addressable by means of a URL ending in a \c{#} followed by your
593 internal section keyword.
595 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
597 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
598 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
599 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
600 file. If it is set to \c{false}, they will be omitted completely.
602 \# FIXME: surely it would be better to include them in HTML
603 \# comments? The only question is whether they should be _visible_.
605 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
607 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
608 bottom of each HTML file will be omitted completely. (This will
609 therefore also cause \i{version IDs} not to be included.)
611 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
613 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
614 name="author">} tag in the output HTML files, so that browsers which
615 support this can automatically identify the \i{author} of the document.
617 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
619 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
620 name="description">} tag in the output HTML files, so that browsers
621 which support this can easily pick out a brief \I{description, of
622 document}description of the document.
624 \S{output-html-defaults} Default settings
626 The \i{default settings} for Halibut's HTML output format are:
628 \c \cfg{xhtml-contents-filename}{Contents.html}
629 \c \cfg{xhtml-index-filename}{IndexPage.html}
630 \c \cfg{xhtml-template-filename}{%n.html}
631 \c \cfg{xhtml-single-filename}{Manual.html}
632 \c \cfg{xhtml-template-fragment}{%b}
634 \c \cfg{xhtml-leaf-level}{2}
635 \c \cfg{xhtml-leaf-contains-contents}{false}
636 \c \cfg{xhtml-leaf-smallest-contents}{4}
637 \c \cfg{xhtml-contents-depth-0}{2}
638 \c \cfg{xhtml-contents-depth-1}{3}
639 \c \cfg{xhtml-contents-depth-2}{4}
640 \c \cfg{xhtml-contents-depth-3}{5}
641 \c \cfg{xhtml-contents-depth-4}{6}
642 \c \cfg{xhtml-contents-depth-5}{7}
644 \c \cfg{xhtml-head-end}{}
645 \c \cfg{xhtml-body-tag}{<body>}
646 \c \cfg{xhtml-body-start}{}
647 \c \cfg{xhtml-body-end}{}
648 \c \cfg{xhtml-address-start}{}
649 \c \cfg{xhtml-address-end}{}
650 \c \cfg{xhtml-navigation-attributes}{}
652 \c \cfg{xhtml-versionid}{true}
653 \c \cfg{xhtml-suppress-address}{false}
654 \c \cfg{xhtml-author}{}
655 \c \cfg{xhtml-description}{}
657 \c \cfg{xhtml-chapter-numeric}{false}
658 \c \cfg{xhtml-chapter-suffix}{: }
660 \c \cfg{xhtml-section-numeric}{0}{true}
661 \c \cfg{xhtml-section-suffix}{0}{ }
663 \c \cfg{xhtml-section-numeric}{1}{true}
664 \c \cfg{xhtml-section-suffix}{1}{ }
666 \c ... and so on for all section levels below this ...
667 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
669 \H{output-whlp} Windows Help
671 This output format generates data that can be used by the \i{Windows
672 Help} program \cw{WINHELP.EXE}. There are two actual files
673 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
675 The Windows Help output format supports the following configuration
678 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
680 \dd Sets the \i{output file name} in which to store the man page.
681 This directive is implicitly generated if you provide a file name
682 parameter after the command-line option \i\c{--winhelp} (see
683 \k{running-options}).
687 Your output file name should end with \c{.hlp}; if it doesn't,
688 Halibut will append it. Halibut will also generate a contents file
689 (ending in \c{.cnt}) alongside the file name you specify.
693 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
695 \dd This directive defines a Windows \i{Help topic} name in the current
696 section. Topic names can be used by the program invoking
697 \cw{WINHELP.EXE} to jump straight to a particular section. So you
698 can use this for \i{context-sensitive help}.
702 For example, if you used this directive in a particular section:
704 \c \cfg{winhelp-topic}{savingfiles}
706 then a Windows application could invoke Windows Help to jump to that
707 particular section in the help file like this:
709 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
710 \c (DWORD)"JI(`',`savingfiles')");
712 You can use this configuration directive many times, in many
713 different subsections of your document, in order to define a lot of
714 different help contexts which you can use in this way.
718 The \i{default settings} for the Windows Help output format are:
720 \c \cfg{winhelp-filename}{output.hlp}
722 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
724 \H{output-man} Unix \cw{man} pages
726 This output format generates a Unix \i{\cw{man} page}. That is to say,
727 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
730 The available configuration options for this format are as follows:
732 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
734 \dd Sets the \i{output file name} in which to store the man page.
735 This directive is implicitly generated if you provide a file name
736 parameter after the command-line option \i\c{--man} (see
737 \k{running-options}).
739 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
741 \dd This directive is used to generate the initial \i{\c{.TH}
742 directive} that appears at the top of a \cw{man} page. It expects to
743 be followed by some number of brace pairs containing text, which will
744 be used in the \i{headers} and \i{footers} of the formatted output.
748 A traditional order for the arguments appears to be:
750 \n The name of the program.
752 \n The (numeric) manual section.
754 \n The date that the \cw{man} page was written.
756 \n The name of any containing suite of which the program is a part.
758 \n The name of the \i{author} of the \cw{man} page.
760 For example, a typical \cw{man} page might contain
762 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
767 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
769 \dd If this is set to \c{true}, then \i{section headings} in the
770 \cw{man} page will have their \i{section numbers} displayed as usual. If
771 set to \c{false}, the section numbers will be omitted. (\cw{man}
772 pages traditionally have section names such as \q{SYNOPSIS},
773 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
774 \c{false} is the setting which conforms most closely to normal
777 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
779 \dd If this is set to a number greater than 0, then section headings
780 \e{higher} than the given depth will not be displayed. If it is set
781 to zero, all section headings will be displayed as normal.
785 The point of this is so that you can use the same Halibut input file
786 to generate a quick-reference \cw{man} page for a program, \e{and} to
787 include that \cw{man} page as an appendix in your program's full manual.
788 If you are to include the \cw{man} page as an appendix, then the internal
789 headings within the page will probably need to be at \c{\\H} or
790 \c{\\S} level; therefore, when you format that input file on its own
791 to create the \cw{man} page itself, you will need to have defined a
792 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
793 want to see displayed.
795 Here's an example. You might have a file \c{appendix.but}, which
798 \c \A{manpages} \cw{man} pages for the Foo tool suite
800 \c \cfg{man-mindepth}{2}
802 Then you have a file \c{make-foo.but}, and probably others like it
803 as well, each of which looks something like this:
805 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
808 \c \H{man-foo} \cw{man} page for \c{make-foo}
810 \c \S{man-foo-name} NAME
812 \c \c{make-foo} - create Foo files for the Foo tool suite
814 \c \S{man-foo-synopsis} SYNOPSIS
819 So when you're generating your main manual, you can include
820 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
821 pages you have, and your \cw{man} pages will be formatted neatly as
822 part of an appendix. Then, in a separate run of Halibut, you can
825 \c halibut appendix.but make-foo.but
827 and this will generate a \cw{man} page \c{output.1}, in which the
828 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
829 page for \c{make-foo}} will not be displayed because of the
830 \c{man-mindepth} directive. So the first visible heading in the
831 output \cw{man} page will be \q{NAME}, exactly as a user would
836 The \i{default settings} for the \cw{man} page output format are:
838 \c \cfg{man-filename}{output.1}
839 \c \cfg{man-identity}{}
840 \c \cfg{man-headnumbers}{false}
841 \c \cfg{man-mindepth}{0}
843 \H{output-info} GNU \c{info}
845 This output format generates files which can be used with the \i{GNU
848 There are typically multiple output files: a primary file whose name
849 usually ends in \c{.info}, and one or more subsidiary files whose
850 names have numbers on the end, so that they end in \c{.info-1},
851 \c{.info-2} and so on. Alternatively, this output format can be
852 configured to output a single large file containing the whole
855 The \c{info} output format supports the following configuration
858 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
860 \dd Sets the output file name in which to store the \c{info} file.
861 This directive is implicitly generated if you provide a file name
862 parameter after the command-line option \i\c{--info} (see
863 \k{running-options}).
867 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
868 your output file name to produce any subsidiary files required.
870 Note that \c{info} files refer to their own names internally, so
871 these files cannot be \I{renaming \c{info} files}renamed after
872 creation and remain useful.
876 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
878 \dd Sets the \I{text width}width of the main part of the document,
879 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
880 directive (see \k{output-text-dimensions}).
882 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
884 \dd Specifies the extra indentation for \I{code paragraphs,
885 indentation} code paragraphs. Works exactly like the
886 \cw{\\cfg\{text-indent-code\}} directive (see
887 \k{output-text-dimensions}).
889 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
891 \dd Specifies how much horizontal space to leave in the index node
892 for the text of \i{index terms}, before displaying the sections the
895 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
897 \dd Specifies the extra indentation before the bullet or number in a
898 \I{bulletted list, indentation}\I{numbered list, indentation}list
899 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
900 directive (see \k{output-text-dimensions}).
902 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
904 \dd Specifies the additional indentation before the body of a list
905 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
906 directive (see \k{output-text-dimensions}).
908 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
910 \dd Specifies the suffix text to be appended to each section number
911 before displaying the section title. For example, if you set this to
912 \q{\cw{:\_}}, then a typical section title might look something like
913 \q{Section 3.1: Something Like This}.
915 \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
917 \dd Specifies the text to be used to underline section titles. Works
918 very much like the \cw{\\cfg\{text-chapter-underline\}} directive
919 (see \k{output-text-headings}). You can specify more than one
920 option, and Halibut will choose the first one supported by the
923 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
925 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
926 You can specify multiple fallback options. Works exactly like the
927 \cw{\\cfg\{text-bullet\}} directive (see
928 \k{output-text-characters}).
930 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
932 \dd Specifies the text used to draw \i{horizontal rules}. You can
933 specify multiple fallback options. Works exactly like the
934 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
936 \dt \I{\cw{\\cfg\{info-quotes\}}}\cw{\\cfg\{info-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
938 \dd Specifies the quotation marks to use. You can specify multiple
939 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
940 directive (see \k{output-text-characters}).
942 \dt \I{\cw{\\cfg\{info-emphasis\}}}\cw{\\cfg\{info-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}]
944 \dd Specifies how to display emphasised text. You can specify
945 multiple fallback options. Works exactly like the
946 \cw{\\cfg\{text-emphasis\}} directive (see
947 \k{output-text-characters}).
949 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
951 \dd Specifies the text to append to the item numbers in a
952 \i{numbered list}. Works exactly like the
953 \cw{\\cfg\{text-list-suffix\}} directive (see
954 \k{output-text-misc}).
956 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
958 \dd Sets the preferred \i{maximum file size} for each subsidiary
959 file. As a special case, if you set this to zero, there will be no
960 subsidiary files and the whole document will be placed in a single
961 self-contained output file. (However, note that this file can still
962 not be renamed usefully.)
966 The preferred maximum file size is only a guideline. Halibut may be
967 forced to exceed it if a single section of the document is larger
968 than the maximum size (since individual \c{info} nodes may not be
969 split between files).
973 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
974 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
976 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
977 header of the Info file. This mechanism is used to automatically
978 generate the \i{\c{dir} file} at the root of a Unix system's
983 The parameters to this directive are:
987 \dd Specifies the section of the \c{dir} file in which you want your
988 document referenced. For example, \q{Development}, or \q{Games}, or
993 \dd Specifies a short name for the directory entry, which will
994 appear at the start of the menu line.
998 \dd Specifies a long name for the directory entry, which will appear
999 at the end of the menu line.
1003 \dd This parameter is optional. If it is present, then the directory
1004 entry will cause a jump to a particular subsection of your document,
1005 rather than starting at the top. The subsection will be the one
1006 referred to by the given keyword (see \k{input-sections} for details
1007 about assigning keywords to document sections).
1009 For example, in a document describing many game programs, the
1010 configuration directive
1012 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1015 might produce text in the \c{dir} file looking something like this:
1018 \c * Chess: (mygames)Chapter 3. Electronic chess game
1020 if the output file were called \c{mygames.info} and the keyword
1021 \c{chess} had been used to define Chapter 3 of the document.
1025 The \i{default settings} for the \c{info} output format are:
1027 \c \cfg{info-filename}{output.info}
1029 \c \cfg{info-width}{70}
1030 \c \cfg{info-indent-code}{2}
1031 \c \cfg{info-index-width}{40}
1032 \c \cfg{info-list-indent}{1}
1033 \c \cfg{info-listitem-indent}{3}
1035 \c \cfg{info-section-suffix}{: }
1037 \c \cfg{info-underline}{\u203e}{-}
1038 \c \cfg{info-bullet}{\u2022}{-}
1039 \c \cfg{info-rule}{\u2500}{-}
1040 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1041 \c \cfg{info-emphasis}{_}{_}
1043 \c \cfg{info-list-suffix}{.}
1044 \c \cfg{info-max-file-size}{65536}
1046 and no \cw{\\cfg\{info-dir-entry\}} directives.
1048 \H{output-ps} \i{PostScript}
1050 This output format generates a printable manual in PostScript format.
1052 This format is currently very new and is not yet configurable. There
1053 is only one available configuration option:
1055 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1057 \dd Sets the \i{output file name} in which to store the PostScript
1058 file. This directive is implicitly generated if you provide a file
1059 name parameter after the command-line option \i\c{--ps} (see
1060 \k{running-options}).
1062 The \i{default settings} for the PostScript output format are:
1064 \c \cfg{ps-filename}{output.ps}
1066 \H{output-pdf} \i{PDF}
1068 This output format generates a printable manual in PDF format. This
1069 should look exactly identical to the PostScript output (see
1070 \k{output-ps}), but also uses some PDF interactive features to
1071 provide an outline of all the document's sections and clickable
1072 cross-references between sections.
1074 This format is currently very new and is not yet configurable. There
1075 is only one available configuration option:
1077 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1079 \dd Sets the \i{output file name} in which to store the PDF file.
1080 This directive is implicitly generated if you provide a file name
1081 parameter after the command-line option \i\c{--pdf} (see
1082 \k{running-options}).
1084 The \i{default settings} for the PDF output format are:
1086 \c \cfg{pdf-filename}{output.pdf}