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 single character. In the
111 latter case, that character will be used to underline the title. So
112 you might want to specify, for example,
113 \cw{\\text-title-underline\{=\}} but
114 \cw{\\text-chapter-underline\{-\}}.
116 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
118 \dd Specifies the alignment of the overall document title: \c{left},
119 \c{leftplus} or \c{centre}.
121 \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
123 \dd Specifies how the overall document title should be underlined.
125 \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
127 \dd Specifies the alignment of chapter and appendix headings.
129 \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
131 \dd Specifies how chapter and appendix headings should be underlined.
133 \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
135 \dd If this is set to \c{true}, then chapter headings will not
136 contain the word \q{Chapter} (or whatever other word you have
137 defined in its place - see \k{input-sections} and \k{input-config});
138 they will just contain the chapter \e{number}, followed by the
139 chapter title. If you set this to \c{false}, chapter headings will
140 be prefixed by \q{Chapter} or equivalent.
142 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
144 \dd This specifies the suffix text to be appended to the chapter
145 number, before displaying the chapter title. For example, if you set
146 this to \q{\cw{:\_}}, then the chapter title might look something
147 like \q{Chapter 2: Doing Things}.
149 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
151 \dd Specifies the alignment of section headings at a particular
152 level. The \e{level} parameter specifies which level of section
153 headings you want to affect: 0 means first-level headings (\c{\\H}),
154 1 means second-level headings (\c{\\S}), 2 means the level below
155 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
156 just like the other alignment directives listed above.
158 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}}
160 \dd Specifies how to underline section headings at a particular level.
162 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
164 \dd Specifies whether section headings at a particular level should
165 contain the word \q{Section} or equivalent (if \c{false}), or should
166 be numeric only (if \c{true}).
168 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
170 \dd Specifies the \I{suffix text, in section titles}suffix text to
171 be appended to section numbers at a particular level, before
172 displaying the section title.
174 \S{output-text-misc} Miscellaneous configuration options
176 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
178 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
179 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
180 included at the bottom of the text file. If it is set to \c{false},
181 they will be omitted completely.
183 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}
185 \dd This specifies the text which should be used as the \i{bullet}
186 in bulletted lists. It can be one character
187 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
188 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
190 \# FIXME: code indentation is configurable, therefore \quote
191 \# indentation probably ought to be as well.
193 \# FIXME: text-indent-* should be consistently named.
195 \S{output-text-defaults} Default settings
197 The \i{default settings} for Halibut's plain text output format are:
199 \c \cfg{text-filename}{output.txt}
201 \c \cfg{text-width}{68}
202 \c \cfg{text-indent}{7}
203 \c \cfg{text-indent-code}{2}
204 \c \cfg{text-list-indent}{1}
205 \c \cfg{text-listitem-indent}{3}
206 \c \cfg{text-indent-preamble}{false}
208 \c \cfg{text-title-align}{centre}
209 \c \cfg{text-title-underline}{=}
211 \c \cfg{text-chapter-align}{left}
212 \c \cfg{text-chapter-underline}{-}
213 \c \cfg{text-chapter-numeric}{false}
214 \c \cfg{text-chapter-suffix}{: }
216 \c \cfg{text-section-align}{0}{leftplus}
217 \c \cfg{text-section-underline}{0}{}
218 \c \cfg{text-section-numeric}{0}{true}
219 \c \cfg{text-section-suffix}{0}{ }
221 \c \cfg{text-section-align}{1}{leftplus}
222 \c \cfg{text-section-underline}{1}{}
223 \c \cfg{text-section-numeric}{1}{true}
224 \c \cfg{text-section-suffix}{1}{ }
226 \c ... and so on for all section levels below this ...
227 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
231 This output format generates an \i{HTML} version of the document. By
232 default, this will be in multiple files, starting with
233 \c{Contents.html} and splitting the document into files by chapter
234 and/or subsection. You can configure precisely how the text is split
235 between HTML files using the configuration commands described in
236 this section. In particular, you can configure Halibut to output one
237 single HTML file instead of multiple ones.
239 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
240 which is why all of the configuration directives start with the word
241 \c{xhtml} rather than \c{html}.
243 \S{output-html-file} Controlling the output file names
245 \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
247 \dd Sets the \i{output file name} in which to store the top-level
248 contents page. Since this is the first page a user ought to see when
249 beginning to read the document, a good choice in many cases might be
250 \c{index.html} (although this is not the default, for historical
253 \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
255 \dd Sets the file name in which to store the document's index.
257 \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
259 \dd Provides a \i{template} to be used when constructing the file
260 names of each chapter or section of the document. This template
261 should contain at least one \i\e{formatting command}, in the form of
262 a per cent sign followed by a letter. (If you need a literal per
263 cent sign, you can write \c{%%}.)
267 The formatting commands used in this template are:
271 \dd Expands to the visible title of the section, with white space
272 removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
273 Fish}}, this formatting command would expand to
274 \q{\cw{CatchingFish}}.
278 \dd Expands to the type and number of the section, without white
279 space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
280 section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
281 If the section has no number (an unnumbered chapter created using
282 \c{\\U}), this directive falls back to doing the same thing as
287 \dd Expands to the bare number of the section. So in chapter 1 this
288 would expand to \q{\cw{1}}; in section A.4.3 it would expand to
289 \q{\cw{A.4.3}}, and so on. If the section has no number (an
290 unnumbered chapter created using \c{\\U}), this directive falls back
291 to doing the same thing as \c{%N}.
295 \dd Expands to the internal keyword specified in the section title.
296 So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
297 formatting command would expand to \q{\cw{fish}}. If the section has
298 no keyword (an unnumbered chapter created using \c{\\U}), this
299 directive falls back to doing the same thing as \c{%N}.
301 These formatting directives can also be used in the
302 \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
303 \k{output-html-misc}).
307 \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
309 \dd Sets the file name in which to store the entire document, if
310 Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
311 produce a single self-contained file. Both this directive \e{and}
312 \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
313 provide a file name parameter after the command-line option
314 \i\c{--html} (see \k{running-options}).
316 \S{output-html-split} Controlling the splitting into HTML files
318 By default, the HTML output from Halibut is split into multiple
319 files. Each file typically contains a single chapter or section and
320 everything below it, unless subsections of that chapter are
321 themselves split off into further files.
323 Most files also contain a contents section, giving hyperlinks to the
324 sections in the file and/or the sections below it.
326 The configuration directives listed below allow you to configure the
327 splitting into files, and the details of the contents sections.
329 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
331 \dd This setting indicates the depth of section which should be
332 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
333 you set it to 1, for example, then every chapter will be given its
334 own HTML file, plus a top-level \i{contents file}. If you set this
335 to 2, then each chapter \e{and} each \c{\\H} section will have a
336 file, and the chapter files will mostly just contain links to their
341 If you set this option to zero, then the whole document will appear
342 in a single file. If you do this, Halibut will call that file
343 \i\c{Manual.html} instead of \i\c{Contents.html}.
345 This option is automatically set to zero if you provide a file name
346 parameter after the command-line option \i\c{--html} (see
347 \k{running-options}), because you have specified a single file name
348 and so Halibut assumes you want the whole document to be placed in
353 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
355 \dd This directive allows you to specify how \I{depth of
356 contents}deep the contents section in a particular file should go.
360 The \e{level} parameter indicates which level of contents section
361 you are dealing with. 0 denotes the main contents section in the
362 topmost file \c{Contents.html}; 1 denotes a contents section in a
363 chapter file; 2 is a contents section in a file containing a \c{\\H}
364 heading, and so on. Currently you can't go below level 5 (which
365 corresponds to a \c{\\S3} heading).
367 The \e{depth} parameter indicates the maximum depth of heading which
368 will be shown in this contents section. Again, 1 denotes a chapter,
369 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
371 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
372 Halibut to put contents links in chapter files for all sections down
373 to \c{\\S} level, but not to go into any more detail than that.
377 \# FIXME: this is utterly ghastly. For a start, it should include
378 \# the level as a separate argument, like the text section config
379 \# directives. Secondly, it shouldn't be limited in depth!
381 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
383 \dd If you set this to \c{true}, then each leaf file will contain
384 its own contents section which summarises the text within it.
386 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
388 \dd Contents sections in leaf files are not output at all if they
389 contain very few entries (on the assumption that it just isn't worth
390 bothering). This directive configures the minimum number of entries
391 required in a leaf contents section to make Halibut bother
392 generating it at all.
394 \S{output-html-html} Including pieces of your own HTML
396 The directives in this section allow you to supply pieces of
397 \I{HTML}\i{verbatim HTML} code, which will be included in various
398 parts of the output files.
400 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
402 \dd The text you provide in this directive is placed at the end of
403 the \i\cw{<HEAD>} section of each output HTML file. So this is a
404 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
406 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
408 \dd The text you provide in this directive is used in place of the
409 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
410 \i{background colour}, for example, you could write
411 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
413 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
415 \dd The text you provide in this directive is placed at the
416 beginning of the \i\cw{<BODY>} section of each output HTML file. So
417 if you intend your HTML files to be part of a web site with a
418 standard \i{house style}, and the style needs a \i{header} at the
419 top of every page, this is where you can add that header.
421 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
423 \dd The text you provide in this directive is placed at the end of
424 the \i\cw{<BODY>} section of each output HTML file. So if you intend
425 your HTML files to be part of a web site with a standard \i{house
426 style}, and the style needs a \i{footer} at the bottom of every
427 page, this is where you can add that footer.
429 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
431 \dd The text you provide in this directive is placed at the
432 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
433 output HTML file. This might be a good place to put authors'
434 \i{contact details}, for example.
436 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
438 \dd The text you provide in this directive is placed at the end of
439 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
440 after the version IDs (if present).
442 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
444 \dd The text you provide in this directive is included inside the
445 \cw{<P>} tag containing the \i{navigation links} at the top of each
446 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
447 wanted the navigation links to have a particular CSS style, you
449 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
450 navigation-links paragraph would then begin with the tag \cw{<p
453 \S{output-html-headings} \ii{Configuring heading display}
455 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
457 \dd If this is set to \c{true}, then chapter headings will not
458 contain the word \q{Chapter} (or whatever other word you have
459 defined in its place - see \k{input-sections} and \k{input-config});
460 they will just contain the chapter \e{number}, followed by the
461 chapter title. If you set this to \c{false}, chapter headings will
462 be prefixed by \q{Chapter} or equivalent.
464 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
466 \dd This specifies the suffix text to be appended to the chapter
467 number, before displaying the chapter title. For example, if you set
468 this to \q{\cw{:\_}}, then the chapter title might look something
469 like \q{Chapter 2: Doing Things}.
471 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{boolean}\cw{\}}
473 \dd Specifies whether section headings at a particular level should
474 contain the word \q{Section} or equivalent (if \c{false}), or should
475 be numeric only (if \c{true}). The \e{level} parameter specifies
476 which level of section headings you want to affect: 0 means
477 first-level headings (\c{\\H}), 1 means second-level headings
478 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
480 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{text}\cw{\}}
482 \dd Specifies the suffix text to be appended to section numbers at a
483 particular level, before displaying the section title.
485 \S{output-html-misc} Miscellaneous options
487 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
489 \dd This directive lets you specify a \i{template}, with exactly the
490 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
491 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
492 NAME="...">}) used to allow URLs to refer to specific sections
493 within a particular HTML file. So if you set this to \q{\cw{%k}},
494 for example, then each individual section in your document will be
495 addressable by means of a URL ending in a \c{#} followed by your
496 internal section keyword.
498 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
500 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
501 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
502 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
503 file. If it is set to \c{false}, they will be omitted completely.
505 \# FIXME: surely it would be better to include them in HTML
506 \# comments? The only question is whether they should be _visible_.
508 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
510 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
511 bottom of each HTML file will be omitted completely. (This will
512 therefore also cause \i{version IDs} not to be included.)
514 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
516 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
517 name="author">} tag in the output HTML files, so that browsers which
518 support this can automatically identify the \i{author} of the document.
520 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
522 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
523 name="description">} tag in the output HTML files, so that browsers
524 which support this can easily pick out a brief \I{description, of
525 document}description of the document.
527 \S{output-html-defaults} Default settings
529 The \i{default settings} for Halibut's HTML output format are:
531 \c \cfg{xhtml-contents-filename}{Contents.html}
532 \c \cfg{xhtml-index-filename}{IndexPage.html}
533 \c \cfg{xhtml-template-filename}{%n.html}
534 \c \cfg{xhtml-single-filename}{Manual.html}
535 \c \cfg{xhtml-template-fragment}{%b}
537 \c \cfg{xhtml-leaf-level}{2}
538 \c \cfg{xhtml-leaf-contains-contents}{false}
539 \c \cfg{xhtml-leaf-smallest-contents}{4}
540 \c \cfg{xhtml-contents-depth-0}{2}
541 \c \cfg{xhtml-contents-depth-1}{3}
542 \c \cfg{xhtml-contents-depth-2}{4}
543 \c \cfg{xhtml-contents-depth-3}{5}
544 \c \cfg{xhtml-contents-depth-4}{6}
545 \c \cfg{xhtml-contents-depth-5}{7}
547 \c \cfg{xhtml-head-end}{}
548 \c \cfg{xhtml-body-tag}{<body>}
549 \c \cfg{xhtml-body-start}{}
550 \c \cfg{xhtml-body-end}{}
551 \c \cfg{xhtml-address-start}{}
552 \c \cfg{xhtml-address-end}{}
553 \c \cfg{xhtml-navigation-attributes}{}
555 \c \cfg{xhtml-versionid}{true}
556 \c \cfg{xhtml-suppress-address}{false}
557 \c \cfg{xhtml-author}{}
558 \c \cfg{xhtml-description}{}
560 \c \cfg{xhtml-chapter-numeric}{false}
561 \c \cfg{xhtml-chapter-suffix}{: }
563 \c \cfg{xhtml-section-numeric}{0}{true}
564 \c \cfg{xhtml-section-suffix}{0}{ }
566 \c \cfg{xhtml-section-numeric}{1}{true}
567 \c \cfg{xhtml-section-suffix}{1}{ }
569 \c ... and so on for all section levels below this ...
570 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
572 \H{output-whlp} Windows Help
574 This output format generates data that can be used by the \i{Windows
575 Help} program \cw{WINHELP.EXE}. There are two actual files
576 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
578 The Windows Help output format supports the following configuration
581 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
583 \dd Sets the \i{output file name} in which to store the man page.
584 This directive is implicitly generated if you provide a file name
585 parameter after the command-line option \i\c{--winhelp} (see
586 \k{running-options}).
590 Your output file name should end with \c{.hlp}; if it doesn't,
591 Halibut will append it. Halibut will also generate a contents file
592 (ending in \c{.cnt}) alongside the file name you specify.
596 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
598 \dd This directive defines a Windows \i{Help topic} name in the current
599 section. Topic names can be used by the program invoking
600 \cw{WINHELP.EXE} to jump straight to a particular section. So you
601 can use this for \i{context-sensitive help}.
605 For example, if you used this directive in a particular section:
607 \c \cfg{winhelp-topic}{savingfiles}
609 then a Windows application could invoke Windows Help to jump to that
610 particular section in the help file like this:
612 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
613 \c (DWORD)"JI(`',`savingfiles')");
615 You can use this configuration directive many times, in many
616 different subsections of your document, in order to define a lot of
617 different help contexts which you can use in this way.
621 The \i{default settings} for the Windows Help output format are:
623 \c \cfg{winhelp-filename}{output.hlp}
625 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
627 \H{output-man} Unix \cw{man} pages
629 This output format generates a Unix \i{\cw{man} page}. That is to say,
630 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
633 The available configuration options for this format are as follows:
635 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
637 \dd Sets the \i{output file name} in which to store the man page.
638 This directive is implicitly generated if you provide a file name
639 parameter after the command-line option \i\c{--man} (see
640 \k{running-options}).
642 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
644 \dd This directive is used to generate the initial \i{\c{.TH}
645 directive} that appears at the top of a \cw{man} page. It expects to
646 be followed by some number of brace pairs containing text, which will
647 be used in the \i{headers} and \i{footers} of the formatted output.
651 A traditional order for the arguments appears to be:
653 \n The name of the program.
655 \n The (numeric) manual section.
657 \n The date that the \cw{man} page was written.
659 \n The name of any containing suite of which the program is a part.
661 \n The name of the \i{author} of the \cw{man} page.
663 For example, a typical \cw{man} page might contain
665 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
670 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
672 \dd If this is set to \c{true}, then \i{section headings} in the
673 \cw{man} page will have their \i{section numbers} displayed as usual. If
674 set to \c{false}, the section numbers will be omitted. (\cw{man}
675 pages traditionally have section names such as \q{SYNOPSIS},
676 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
677 \c{false} is the setting which conforms most closely to normal
680 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
682 \dd If this is set to a number greater than 0, then section headings
683 \e{higher} than the given depth will not be displayed. If it is set
684 to zero, all section headings will be displayed as normal.
688 The point of this is so that you can use the same Halibut input file
689 to generate a quick-reference \cw{man} page for a program, \e{and} to
690 include that \cw{man} page as an appendix in your program's full manual.
691 If you are to include the \cw{man} page as an appendix, then the internal
692 headings within the page will probably need to be at \c{\\H} or
693 \c{\\S} level; therefore, when you format that input file on its own
694 to create the \cw{man} page itself, you will need to have defined a
695 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
696 want to see displayed.
698 Here's an example. You might have a file \c{appendix.but}, which
701 \c \A{manpages} \cw{man} pages for the Foo tool suite
703 \c \cfg{man-mindepth}{2}
705 Then you have a file \c{make-foo.but}, and probably others like it
706 as well, each of which looks something like this:
708 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
711 \c \H{man-foo} \cw{man} page for \c{make-foo}
713 \c \S{man-foo-name} NAME
715 \c \c{make-foo} - create Foo files for the Foo tool suite
717 \c \S{man-foo-synopsis} SYNOPSIS
722 So when you're generating your main manual, you can include
723 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
724 pages you have, and your \cw{man} pages will be formatted neatly as
725 part of an appendix. Then, in a separate run of Halibut, you can
728 \c halibut appendix.but make-foo.but
730 and this will generate a \cw{man} page \c{output.1}, in which the
731 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
732 page for \c{make-foo}} will not be displayed because of the
733 \c{man-mindepth} directive. So the first visible heading in the
734 output \cw{man} page will be \q{NAME}, exactly as a user would
739 The \i{default settings} for the \cw{man} page output format are:
741 \c \cfg{man-filename}{output.1}
742 \c \cfg{man-identity}{}
743 \c \cfg{man-headnumbers}{false}
744 \c \cfg{man-mindepth}{0}
746 \H{output-info} GNU \c{info}
748 This output format generates files which can be used with the \i{GNU
751 There are typically multiple output files: a primary file whose name
752 usually ends in \c{.info}, and one or more subsidiary files whose
753 names have numbers on the end, so that they end in \c{.info-1},
754 \c{.info-2} and so on. Alternatively, this output format can be
755 configured to output a single large file containing the whole
758 The \c{info} output format supports the following configuration
761 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
763 \dd Sets the output file name in which to store the \c{info} file.
764 This directive is implicitly generated if you provide a file name
765 parameter after the command-line option \i\c{--info} (see
766 \k{running-options}).
770 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
771 your output file name to produce any subsidiary files required.
773 Note that \c{info} files refer to their own names internally, so
774 these files cannot be \I{renaming \c{info} files}renamed after
775 creation and remain useful.
779 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
781 \dd Sets the preferred \i{maximum file size} for each subsidiary
782 file. As a special case, if you set this to zero, there will be no
783 subsidiary files and the whole document will be placed in a single
784 self-contained output file. (However, note that this file can still
785 not be renamed usefully.)
789 The preferred maximum file size is only a guideline. Halibut may be
790 forced to exceed it if a single section of the document is larger
791 than the maximum size (since individual \c{info} nodes may not be
792 split between files).
796 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
797 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
799 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
800 header of the Info file. This mechanism is used to automatically
801 generate the \i{\c{dir} file} at the root of a Unix system's
806 The parameters to this directive are:
810 \dd Specifies the section of the \c{dir} file in which you want your
811 document referenced. For example, \q{Development}, or \q{Games}, or
816 \dd Specifies a short name for the directory entry, which will
817 appear at the start of the menu line.
821 \dd Specifies a long name for the directory entry, which will appear
822 at the end of the menu line.
826 \dd This parameter is optional. If it is present, then the directory
827 entry will cause a jump to a particular subsection of your document,
828 rather than starting at the top. The subsection will be the one
829 referred to by the given keyword (see \k{input-sections} for details
830 about assigning keywords to document sections).
832 For example, in a document describing many game programs, the
833 configuration directive
835 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
838 might produce text in the \c{dir} file looking something like this:
841 \c * Chess: (mygames)Chapter 3. Electronic chess game
843 if the output file were called \c{mygames.info} and the keyword
844 \c{chess} had been used to define Chapter 3 of the document.
848 \H{output-ps} \i{PostScript}
850 This output format generates a printable manual in PostScript format.
852 This format is currently very new and is not yet configurable. There
853 is only one available configuration option:
855 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
857 \dd Sets the \i{output file name} in which to store the PostScript
858 file. This directive is implicitly generated if you provide a file
859 name parameter after the command-line option \i\c{--ps} (see
860 \k{running-options}).
862 The \i{default settings} for the PostScript output format are:
864 \c \cfg{ps-filename}{output.ps}
866 \H{output-pdf} \i{PDF}
868 This output format generates a printable manual in PDF format. This
869 should look exactly identical to the PostScript output (see
870 \k{output-ps}), but also uses some PDF interactive features to
871 provide an outline of all the document's sections and clickable
872 cross-references between sections.
874 This format is currently very new and is not yet configurable. There
875 is only one available configuration option:
877 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
879 \dd Sets the \i{output file name} in which to store the PDF file.
880 This directive is implicitly generated if you provide a file name
881 parameter after the command-line option \i\c{--pdf} (see
882 \k{running-options}).
884 The \i{default settings} for the PDF output format are:
886 \c \cfg{pdf-filename}{output.pdf}