3 \C{output} Halibut output formats
5 This chapter describes each of Halibut's current \i{output formats}.
6 It gives some general information about the format, and also
7 describes all the \i{configuration directives} which are specific to
10 \H{output-text} Plain text
12 This output format generates the document as a single \i{plain text}
13 file. No table of contents or index is generated.
15 The precise formatting of the text file can be controlled by a
16 variety of configuration directives. They are listed in the
17 following subsections.
19 \S{output-text-file} Output file name
21 \dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}}
23 \dd Sets the \i{output file name} in which to store the text file.
24 This directive is implicitly generated if you provide a file name
25 parameter after the command-line option \i\c{--text} (see
28 \S{output-text-dimensions} Indentation and line width
30 This section describes the configuration directives which control
31 the \i{horizontal dimensions} of the output text file: how much
32 paragraphs are indented by and how long the lines are.
34 \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
36 \dd Sets the \I{text width}width of the main part of the document,
37 in characters. This width will be used for wrapping paragraphs and
38 for centring titles (if you have asked for titles to be centred -
39 see \k{output-text-headings}). This width does \e{not} include the
40 left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
41 indent of 8 and a width of 64, your maximum output line length will
44 \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
46 \dd Sets the left \i{indentation} for the document. If you set this
47 to zero, your document will look like an ordinary text file as
48 someone with a text editor might have written it; if you set it
49 above zero, the text file will have a \i{margin} down the left in
50 the style of some printed manuals, and you can then configure the
51 section numbers to appear in this margin (see
52 \k{output-text-headings}).
54 \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
56 \dd Specifies how many extra characters of indentation (on top of
57 the normal left indent) should be given to \I{code paragraphs,
58 indentation} code paragraphs.
60 \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
62 \dd Specifies how many extra spaces should be used to indent the
63 bullet or number in a \I{bulletted list, indentation}bulletted or
64 \I{numbered list, indentation}numbered \I{list, indentation}list.
65 The actual body of the list item will be indented by this much
66 \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}.
68 \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
70 \dd Specifies how many extra spaces should be used to indent the
71 body of a list item, over and above the number configured in
72 \cw{\\cfg\{text-list-indent\}}.
74 \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
76 \dd When this is set to \c{true}, the document \i{preamble} (i.e. any
77 paragraphs appearing before the first chapter heading) will be
78 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
79 this setting is \c{false}, the document preamble will not be
80 indented at all from the left margin.
82 \S{output-text-headings} \ii{Configuring heading display}
84 The directives in this section allow you to configure the appearance
85 of the title, chapter and section headings in your text file.
87 Several of the directives listed below specify the \i{alignment} of
88 a heading. These alignment options have three possible values:
92 \dd Align the heading to the very left of the text file (column zero).
96 \dd Align the section title to the left of the main display region
97 (in other words, indented to the level specified by
98 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
99 left of that (so that it goes in the margin if there is room).
103 \dd Centre the heading.
105 Also, several of the directives below specify how a title should be
106 \I{underlining}underlined. The parameter to one of these directives
107 should be either blank (\cw{\{\}}) or a piece of text which will be
108 repeated to produce the underline. So you might want to specify, for
109 example, \cw{\\text-title-underline\{=\}} but
110 \cw{\\text-chapter-underline\{\-\}}.
112 You can also specify more than one underline setting, and Halibut
113 will choose the first one that the output character set supports.
114 So, for example, you could write
115 \cw{\\text-chapter-underline\{\\u203e\}\{\-\}}, and Halibut would use
116 the Unicode \q{OVERLINE} character where possible and fall back to
117 the ASCII minus sign otherwise.
119 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
121 \dd Specifies the alignment of the overall document title: \c{left},
122 \c{leftplus} or \c{centre}.
124 \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}}
126 \dd Specifies how the overall document title should be underlined.
128 \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
130 \dd Specifies the alignment of chapter and appendix headings.
132 \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}}
134 \dd Specifies how chapter and appendix headings should be underlined.
136 \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
138 \dd If this is set to \c{true}, then chapter headings will not
139 contain the word \q{Chapter} (or whatever other word you have
140 defined in its place - see \k{input-sections} and \k{input-config});
141 they will just contain the chapter \e{number}, followed by the
142 chapter title. If you set this to \c{false}, chapter headings will
143 be prefixed by \q{Chapter} or equivalent.
145 \dt \I{\cw{\\cfg\{text-chapter-shownumber\}}}\cw{\\cfg\{text-chapter-shownumber\}\{}\e{boolean}\cw{\}}
147 \dd If this is set to \c{false}, then chapter headings will \e{only}
148 contain the chapter title: they will not contain the word
149 \q{Chapter} (or whatever other word you have defined in its place),
150 and neither will they contain the chapter number. If set to
151 \c{false}, this overrides \cw{\\cfg\{text-chapter-numeric\}}.
153 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
155 \dd This specifies the suffix text to be appended to the chapter
156 number, before displaying the chapter title. For example, if you set
157 this to \cq{:\_}, then the chapter title might look something
158 like \q{Chapter 2: Doing Things}.
160 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
162 \dd Specifies the alignment of section headings at a particular
163 level. The \e{level} parameter specifies which level of section
164 headings you want to affect: 0 means first-level headings (\c{\\H}),
165 1 means second-level headings (\c{\\S}), 2 means the level below
166 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
167 just like the other alignment directives listed above.
169 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}}
171 \dd Specifies how to underline section headings at a particular level.
173 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
175 \dd Specifies whether section headings at a particular level should
176 contain the word \q{Section} or equivalent (if \c{false}), or should
177 be numeric only (if \c{true}).
179 \dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
181 \dd If this is set to \c{false}, then section headings at the
182 specified level will \e{only} contain the section title: they will
183 not contain the word \q{Section} (or whatever other word you have
184 defined in its place), and neither will they contain the section
185 number. If set to \c{false}, this overrides
186 \cw{\\cfg\{text-section-numeric\}}.
188 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
190 \dd Specifies the \I{suffix text, in section titles}suffix text to
191 be appended to section numbers at a particular level, before
192 displaying the section title.
194 \S{output-text-characters} Configuring the characters used
196 \dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}}
198 \dd This tells Halibut what \i{character set} the output should be
199 in. Any Unicode characters representable in this set will be output
200 verbatim; any other characters will not be output and their
201 \i{fallback text} (if any) will be used instead.
205 The character set names are the same as for
206 \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
207 \cw{\\cfg\{input-charset\}}, this directive affects the \e{entire}
208 output; it's not possible to switch encodings halfway through.
212 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
214 \dd This specifies the text which should be used as the \i{bullet}
215 in bulletted lists. It can be one character
216 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
217 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
221 Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple
222 possible options after this command, and Halibut will choose the first one
223 which the output character set supports. For example, you might write
224 \cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case
225 Halibut would use the Unicode \q{BULLET} character where possible,
226 fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available,
227 and resort to the ASCII asterisk if all else failed.
231 \dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
233 \dd This specifies the text which should be used for drawing
234 \i{horizontal rules} (generated by \i\c{\\rule}; see
235 \k{input-rule}). It can be one character, or more than one. The
236 string you specify will be repeated to reach the required width, so
237 you can specify something like \cq{-=} to get a rule that looks
242 Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback
243 options in this command.
247 \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{\}}]
249 \dd This specifies a set of quote characters for the text backend,
250 overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax
251 (see \k{input-config}).
255 In this backend, these quotes will also be used to mark text enclosed
256 in the \c{\\c} command (see \k{input-code}).
260 \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{\}}]
262 \dd This specifies the characters which should be used to surround
263 emphasised text (written using the \c{\\e} command; see
268 You should separately specify the start-emphasis and end-emphasis
269 text, each of which can be more than one character if you want.
270 Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs
271 of fallback options in this command, and Halibut will always use a
276 \S{output-text-misc} Miscellaneous configuration options
278 \dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}}
280 \dd This text is appended to the number on a \i{numbered list} item
281 (see \k{input-list-number}). So if you want to label your lists as
282 \q{1)}, \q{2)} and so on, then you would write
283 \cw{\\cfg\{text-list-suffix\}\{)\}}.
285 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
287 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
288 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
289 included at the bottom of the text file. If it is set to \c{false},
290 they will be omitted completely.
292 \# FIXME: code indentation is configurable, therefore \quote
293 \# indentation probably ought to be as well.
295 \# FIXME: text-indent-* should be consistently named.
297 \S{output-text-defaults} Default settings
299 The \i{default settings} for Halibut's plain text output format are:
301 \c \cfg{text-filename}{output.txt}
303 \c \cfg{text-width}{68}
304 \c \cfg{text-indent}{7}
305 \c \cfg{text-indent-code}{2}
306 \c \cfg{text-list-indent}{1}
307 \c \cfg{text-listitem-indent}{3}
308 \c \cfg{text-indent-preamble}{false}
310 \c \cfg{text-title-align}{centre}
311 \c \cfg{text-title-underline}{\u2550}{=}
313 \c \cfg{text-chapter-align}{left}
314 \c \cfg{text-chapter-underline}{\u203e}{-}
315 \c \cfg{text-chapter-numeric}{false}
316 \c \cfg{text-chapter-shownumber}{true}
317 \c \cfg{text-chapter-suffix}{: }
319 \c \cfg{text-section-align}{0}{leftplus}
320 \c \cfg{text-section-underline}{0}{}
321 \c \cfg{text-section-numeric}{0}{true}
322 \c \cfg{text-section-shownumber}{0}{true}
323 \c \cfg{text-section-suffix}{0}{ }
325 \c \cfg{text-section-align}{1}{leftplus}
326 \c \cfg{text-section-underline}{1}{}
327 \c \cfg{text-section-numeric}{1}{true}
328 \c \cfg{text-section-shownumber}{1}{true}
329 \c \cfg{text-section-suffix}{1}{ }
331 \c ... and so on for all section levels below this ...
332 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
334 \c \cfg{text-charset}{ASCII}
335 \c \cfg{text-bullet}{\u2022}{-}
336 \c \cfg{text-rule}{\u2500}{-}
337 \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
338 \c \cfg{text-emphasis}{_}{_}
340 \c \cfg{text-list-suffix}{.}
341 \c \cfg{text-versionid}{true}
345 This output format generates an \i{HTML} version of the document. By
346 default, this will be in multiple files, starting with
347 \c{Contents.html} and splitting the document into files by chapter
348 and/or subsection. You can configure precisely how the text is split
349 between HTML files using the configuration commands described in
350 this section. In particular, you can configure Halibut to output one
351 single HTML file instead of multiple ones.
353 \I{\cw{\\cfg\{xhtml-anything\}}}Configuration directives with an
354 \c{xhtml-} prefix are synonyms for those with an \c{html-} prefix.
356 \S{output-html-file} Controlling the output file names
358 \dt \I{\cw{\\cfg\{html-contents-filename\}}}\cw{\\cfg\{html-contents-filename\}\{}\e{filename}\cw{\}}
360 \dd Sets the \i{output file name} in which to store the top-level
361 contents page. Since this is the first page a user ought to see when
362 beginning to read the document, a good choice in many cases might be
363 \c{index.html} (although this is not the default, for historical
366 \dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}}
368 \dd Sets the file name in which to store the document's index.
370 \dt \I{\cw{\\cfg\{html-template-filename\}}}\cw{\\cfg\{html-template-filename\}\{}\e{template}\cw{\}}
372 \dd Provides a \i{template} to be used when constructing the file
373 names of each chapter or section of the document. This template
374 should contain at least one \i\e{formatting command}, in the form of
375 a per cent sign followed by a letter. (If you need a literal per
376 cent sign, you can write \c{%%}.)
380 The formatting commands used in this template are:
382 \dt \I{%N-upper}\c{%N}
384 \dd Expands to the visible title of the section, with white space
385 removed. So in a chapter declared as \cq{\\C\{fish\} Catching
386 Fish}, this formatting command would expand to
391 \dd Expands to the type and number of the section, without white
392 space. So in chapter 1 this would expand to \cq{Chapter1}; in
393 section A.4.3 it would expand to \cq{SectionA.4.3}, and so on.
394 If the section has no number (an unnumbered chapter created using
395 \c{\\U}), this directive falls back to doing the same thing as
400 \dd Expands to the number of the section, in a format suitable for an
401 HTML fragment name. The first character of the section type is
402 prepended to the section number. So in chapter 1 this would expand to
403 \cq{C1}; in section A.4.3 it would expand to \cq{SA.4.3}, and so on.
404 If the section has no number (an unnumbered chapter created using
405 \c{\\U}), this directive falls back to doing the same thing as \c{%N}.
409 \dd Expands to the internal keyword specified in the section title.
410 So in a chapter declared as \cq{\\C\{fish\} Catching Fish}, this
411 formatting command would expand to \cq{fish}. If the section has
412 no keyword (an unnumbered chapter created using \c{\\U}), this
413 directive falls back to doing the same thing as \c{%N}.
415 These formatting directives can also be used in the
416 \cw{\\cfg\{html-template-fragment\}} configuration directive (see
417 \k{output-html-misc}).
421 \dt \I{\cw{\\cfg\{html-single-filename\}}}\cw{\\cfg\{html-single-filename\}\{}\e{filename}\cw{\}}
423 \dd Sets the file name in which to store the entire document, if
424 Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to
425 produce a single self-contained file. Both this directive \e{and}
426 \c{\\cfg\{html-leaf-level\}\{0\}} are implicitly generated if you
427 provide a file name parameter after the command-line option
428 \i\c{--html} (see \k{running-options}).
430 \S{output-html-split} Controlling the splitting into HTML files
432 By default, the HTML output from Halibut is split into multiple
433 files. Each file typically contains a single chapter or section and
434 everything below it, unless subsections of that chapter are
435 themselves split off into further files.
437 Most files also contain a contents section, giving hyperlinks to the
438 sections in the file and/or the sections below it.
440 The configuration directives listed below allow you to configure the
441 splitting into files, and the details of the contents sections.
443 \dt \I{\cw{\\cfg\{html-leaf-level\}}}\cw{\\cfg\{html-leaf-level\}\{}\e{depth}\cw{\}}
445 \dd This setting indicates the depth of section which should be
446 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
447 you set it to 1, for example, then every chapter will be given its
448 own HTML file, plus a top-level \i{contents file}. If you set this
449 to 2, then each chapter \e{and} each \c{\\H} section will have a
450 file, and the chapter files will mostly just contain links to their
455 If you set this option to zero, then the whole document will appear
456 in a single file. If you do this, Halibut will call that file
457 \i\c{Manual.html} instead of \i\c{Contents.html} by default.
459 This option is automatically set to zero if you provide a file name
460 parameter after the command-line option \i\c{--html} (see
461 \k{running-options}), because you have specified a single file name
462 and so Halibut assumes you want the whole document to be placed in
465 You can also specify the special name \c{infinity} (or \c{infinite}
466 or \c{inf}) if you want to ensure that \e{every} section and
467 subsection ends up in a separate file no matter how deep you go.
471 \dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}}
473 \dd This directive allows you to specify how \I{depth of
474 contents}deep any contents section in a particular level of file
479 The \e{level} parameter indicates which level of contents section
480 you are dealing with. 0 denotes the main contents section in the
481 topmost file \c{Contents.html}; 1 denotes a contents section in a
482 chapter file; 2 is a contents section in a file containing a \c{\\H}
485 The \e{depth} parameter indicates the maximum depth of heading which
486 will be shown in this contents section. Again, 1 denotes a chapter,
487 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
489 So, for example: \cw{\\cfg\{html-contents-depth\}\{1\}\{3\}} instructs
490 Halibut to put contents links in chapter files for all sections down
491 to \c{\\S} level, but not to go into any more detail than that.
493 For backwards compatibility, the alternative syntax
494 \cw{\\cfg\{html-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
499 \dt \I{\cw{\\cfg\{html-leaf-contains-contents\}}}\cw{\\cfg\{html-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
501 \dd If you set this to \c{true}, then each leaf file will contain
502 its own contents section which summarises the text within it.
504 \dt \I{\cw{\\cfg\{html-leaf-smallest-contents\}}}\cw{\\cfg\{html-leaf-smallest-contents\}\{}\e{number}\cw{\}}
506 \dd Contents sections in leaf files are not output at all if they
507 contain very few entries (on the assumption that it just isn't worth
508 bothering). This directive configures the minimum number of entries
509 required in a leaf contents section to make Halibut bother
510 generating it at all.
512 \S{output-html-html} Including pieces of your own HTML
514 The directives in this section allow you to supply pieces of
515 \I{HTML}\i{verbatim HTML} code, which will be included in various
516 parts of the output files.
518 Note that none of Halibut's usual character set translation is applied
519 to this code; it is assumed to already be in a suitable encoding for
520 the target HTML files.
522 \dt \I{\cw{\\cfg\{html-head-end\}}}\cw{\\cfg\{html-head-end\}\{}\e{HTML text}\cw{\}}
524 \dd The text you provide in this directive is placed at the end of
525 the \i\cw{<HEAD>} section of each output HTML file. So this is a
526 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
528 \dt \I{\cw{\\cfg\{html-local-head\}}}\cw{\\cfg\{html-local-head\}\{}\e{HTML text}\cw{\}}
530 \dd This configuration directive is local: you specify it within a
531 document section, and it acts on that section only.
535 The text you provide in this directive is placed at the end of the
536 \i\cw{<HEAD>} section of whichever output HTML file contains the
537 section in which the directive was placed. You can specify this
538 directive multiple times in multiple sections if you like.
540 This directive is particularly useful for constructing \i{MacOS
541 on-line help}, which is mostly normal HTML but which requires a
542 special \i\cw{<META NAME="AppleTitle">} tag in the topmost source
543 file. You can arrange this by placing this configuration directive
544 in the preamble or the introduction section, something like this:
546 \c \cfg{html-local-head}{<meta name="AppleTitle"
547 \c content="MyApp Help">}
551 \dt \I{\cw{\\cfg\{html-body-tag\}}}\cw{\\cfg\{html-body-tag\}\{}\e{HTML text}\cw{\}}
553 \dd The text you provide in this directive is used in place of the
554 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
555 \i{background colour}, for example, you could write
556 \cw{\\cfg\{html-body-tag\}\{<body bg="#123456">\}}.
558 \dt \I{\cw{\\cfg\{html-body-start\}}}\cw{\\cfg\{html-body-start\}\{}\e{HTML text}\cw{\}}
560 \dd The text you provide in this directive is placed at the
561 beginning of the \i\cw{<BODY>} section of each output HTML file. So
562 if you intend your HTML files to be part of a web site with a
563 standard \i{house style}, and the style needs a \i{header} at the
564 top of every page, this is where you can add that header.
566 \dt \I{\cw{\\cfg\{html-body-end\}}}\cw{\\cfg\{html-body-end\}\{}\e{HTML text}\cw{\}}
568 \dd The text you provide in this directive is placed at the end of
569 the \i\cw{<BODY>} section of each output HTML file, before any address
570 section. So if you intend your HTML files to be part of a web site
571 with a standard \i{house style}, and the style needs a \i{footer} at
572 the bottom of every page, this is where you can add that footer.
574 \dt \I{\cw{\\cfg\{html-address-start\}}}\cw{\\cfg\{html-address-start\}\{}\e{HTML text}\cw{\}}
576 \dd The text you provide in this directive is placed at the
577 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
578 output HTML file. This might be a good place to put authors'
579 \i{contact details}, for example.
581 \dt \I{\cw{\\cfg\{html-address-end\}}}\cw{\\cfg\{html-address-end\}\{}\e{HTML text}\cw{\}}
583 \dd The text you provide in this directive is placed at the end of
584 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
585 after the version IDs (if present).
587 \dt \I{\cw{\\cfg\{html-navigation-attributes\}}}\cw{\\cfg\{html-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
589 \dd The text you provide in this directive is included inside the
590 \cw{<P>} tag containing the \i{navigation links} at the top of each
591 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
592 wanted the navigation links to have a particular CSS style, you
594 \cw{\\cfg\{html-navigation-attributes\}\{class="foo"\}}, and the
595 navigation-links paragraph would then begin with the tag \cw{<p
598 \S{output-html-headings} \ii{Configuring heading display}
600 \dt \I{\cw{\\cfg\{html-chapter-numeric\}}}\cw{\\cfg\{html-chapter-numeric\}\{}\e{boolean}\cw{\}}
602 \dd If this is set to \c{true}, then chapter headings will not
603 contain the word \q{Chapter} (or whatever other word you have
604 defined in its place - see \k{input-sections} and \k{input-config});
605 they will just contain the chapter \e{number}, followed by the
606 chapter title. If you set this to \c{false}, chapter headings will
607 be prefixed by \q{Chapter} or equivalent.
609 \dt \I{\cw{\\cfg\{html-chapter-shownumber\}}}\cw{\\cfg\{html-chapter-shownumber\}\{}\e{boolean}\cw{\}}
611 \dd If this is set to \c{false}, then chapter headings will \e{only}
612 contain the chapter title: they will not contain the word
613 \q{Chapter} (or whatever other word you have defined in its place),
614 and neither will they contain the chapter number. If set to
615 \c{false}, this overrides \cw{\\cfg\{html-chapter-numeric\}}.
617 \dt \I{\cw{\\cfg\{html-chapter-suffix\}}}\cw{\\cfg\{html-chapter-suffix\}\{}\e{text}\cw{\}}
619 \dd This specifies the suffix text to be appended to the chapter
620 number, before displaying the chapter title. For example, if you set
621 this to \cq{:\_}, then the chapter title might look something
622 like \q{Chapter 2: Doing Things}.
624 \dt \I{\cw{\\cfg\{html-section-numeric\}}}\cw{\\cfg\{html-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
626 \# {level} can be omitted (defaults to 0). Is this intentional?
628 \dd Specifies whether section headings at a particular level should
629 contain the word \q{Section} or equivalent (if \c{false}), or should
630 be numeric only (if \c{true}). The \e{level} parameter specifies
631 which level of section headings you want to affect: 0 means
632 first-level headings (\c{\\H}), 1 means second-level headings
633 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
635 \dt \I{\cw{\\cfg\{html-section-shownumber\}}}\cw{\\cfg\{html-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
637 \dd If this is set to \c{false}, then section headings at the
638 specified level will \e{only} contain the section title: they will
639 not contain the word \q{Section} (or whatever other word you have
640 defined in its place), and neither will they contain the section
641 number. If set to \c{false}, this overrides
642 \cw{\\cfg\{html-section-numeric\}}.
644 \dt \I{\cw{\\cfg\{html-section-suffix\}}}\cw{\\cfg\{html-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
646 \# {level} can be omitted (defaults to 0). Is this intentional?
648 \dd Specifies the suffix text to be appended to section numbers at a
649 particular level, before displaying the section title.
651 \S{output-html-names} Configuring standard text
653 These directives let you fine-tune the names Halibut uses in places
654 such as the navigation bar to refer to various parts of the document,
655 and other standard pieces of text, for instance to change them to a
658 \dt \I{\cw{\\cfg\{html-preamble-text\}}}\cw{\\cfg\{html-preamble-text\}\{}\e{text}\cw{\}}
660 \dt \I{\cw{\\cfg\{html-contents-text\}}}\cw{\\cfg\{html-contents-text\}\{}\e{text}\cw{\}}
662 \dt \I{\cw{\\cfg\{html-index-text\}}}\cw{\\cfg\{html-index-text\}\{}\e{text}\cw{\}}
664 \dd Text used to refer to the preamble (i.e., any paragraphs before
665 the first chapter heading), contents, and index respectively, in the
666 navigation bar, contents, and index.
670 (\c{html-contents-text} and \c{html-index-text} override the
671 cross-format configuration keywords \c{contents} and \c{index} (see
672 \k{input-config}, if both appear. They are legacy keywords preserved
673 for backwards compatibility; you should generally use \c{contents}
678 \dt \I{\cw{\\cfg\{html-title-separator\}}}\cw{\\cfg\{html-title-separator\}\{}\e{text}\cw{\}}
680 \dd If multiple headings are used in a file's \cw{<TITLE>} tag, this
681 text is used to separate them.
683 \# Under what circumstances can this occur?
685 \dt \I{\cw{\\cfg\{html-index-main-separator\}}}\cw{\\cfg\{html-index-main-separator\}\{}\e{text}\cw{\}}
687 \dd Separator between index term and references in the index.
689 \dt \I{\cw{\\cfg\{html-index-multiple-separator\}}}\cw{\\cfg\{html-index-multiple-separator\}\{}\e{text}\cw{\}}
691 \dd Separator between multiple references for a single index term in
694 \dt \I{\cw{\\cfg\{html-pre-versionid\}}}\cw{\\cfg\{html-pre-versionid\}\{}\e{text}\cw{\}}
696 \dt \I{\cw{\\cfg\{html-post-versionid\}}}\cw{\\cfg\{html-post-versionid\}\{}\e{text}\cw{\}}
698 \dd Text surrounding each output \i{version ID paragraph}.
700 \dt \I{\cw{\\cfg\{html-nav-prev-text\}}}\cw{\\cfg\{html-nav-prev-text\}\{}\e{text}\cw{\}}
702 \dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}}
704 \dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}}
706 \dd The text used for the \q{previous page}, \q{next page}, and \q{up}
707 links on the navigation bar.
709 \dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}}
711 \dd Separator between links in the navigation bar.
713 \S{output-html-characters} Configuring the characters used
715 Unlike the other backends, HTML does not have a single
716 \i\cw{\\cfg\{html-charset\}} directive, as there are several levels of
717 character encoding to consider.
719 The character set names are the same as for
720 \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
721 \cw{\\cfg\{input-charset\}}, these directives affect the \e{entire}
722 output; it's not possible to switch encodings halfway through.
724 \dt \I\cw{\\cfg\{html-output-charset\}}\cw{\\cfg\{html-output-charset\}\{}\e{character set name}\cw{\}}
726 \dd The character encoding of the HTML file to be output. Unicode
727 characters in this encoding's repertoire are included literally rather
728 than as \i{HTML entities}.
730 \dt \I\cw{\\cfg\{html-restrict-charset\}}\cw{\\cfg\{html-restrict-charset\}\{}\e{character set name}\cw{\}}
732 \dd Only Unicode characters representable in this character set will be
733 output; any others will be omitted and use their fallback text, if
734 any. Characters not in \q{html-output-charset} will be represented as
735 HTML numeric entities.
737 \dt \I{\cw{\\cfg\{html-quotes\}}}\cw{\\cfg\{html-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
739 \dd Specifies the quotation marks to use, overriding any
740 \cw{\\cfg\{quotes\}} directive. You can specify multiple
741 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
742 directive (see \k{output-text-characters}).
744 \S{output-html-misc} Miscellaneous options
746 \dt \I\cw{\\cfg\{html-version\}}\cw{\\cfg\{html-version\}\{}\e{version}\cw{\}}
748 \dd Identifies the precise version of HTML that is output. This
749 affects the declaration within the HTML, and also has minor effects on
750 the body of the HTML so that it is valid for the declared version. The
751 available variants are:
761 \dd W3C HTML 4.01 Strict
765 \dd ISO/IEC 15445:2000
767 \dt \cw{xhtml1.0transitional}
769 \dd W3C XHTML 1.0 Transitional
771 \dt \cw{xhtml1.0strict}
773 \dd W3C XHTML 1.0 Strict
777 \dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}]
779 \dd This directive lets you specify a \i{template}, with exactly the
780 same syntax used in \cw{\\cfg\{html-template-filename\}} (see
781 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
782 NAME="...">}) used to allow URLs to refer to specific sections
783 within a particular HTML file. So if you set this to \cq{%k},
784 for example, then each individual section in your document will be
785 addressable by means of a URL ending in a \c{#} followed by your
786 internal section keyword.
790 If more than one template is specified, anchors are generated in all
791 the specified formats; Halibut's own cross-references are generated
792 with the first template.
794 Characters that are not permitted in anchor names are stripped. If
795 there are no valid characters left, or a fragment is non-unique,
796 Halibut starts inventing fragment names and suffixes as appropriate.
798 Note that there are potentially fragment names that are not controlled
799 by this mechanism, such as index references.
803 \dt \I{\cw{\\cfg\{html-versionid\}}}\cw{\\cfg\{html-versionid\}\{}\e{boolean}\cw{\}}
805 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
806 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
807 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
808 file. If it is set to \c{false}, they will only be included as HTML
811 \dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}}
813 \dd If this is set to \c{true}, machine-readable relational links will
814 be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK
815 REL="next">} and so on within the \i\cw{<HEAD>} section)
816 providing links to related files. The same set of links are provided
817 as in the navigation bar (with which this should not be confused).
821 Some browsers make use of this semantic information, for instance to
822 allow easy navigation through related pages, and to prefetch the next
823 page. (Search engines can also make use of it.) However, many browsers
824 ignore this markup, so it would be unwise to rely on it for
827 The use and rendering of this information is entirely up to the
828 browser; none of the other Halibut options for the navigation bar will
833 \dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}}
835 \dd If this is set to \c{true}, the usual \i{navigation links} within
836 the \e{body} of each HTML file (near the top of the rendered page) will
839 \dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}}
841 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
842 bottom of each HTML file will be omitted completely. (This will
843 therefore also cause \i{version IDs} not to be included visibly.)
845 \dt \I{\cw{\\cfg\{html-author\}}}\cw{\\cfg\{html-author\}\{}\e{text}\cw{\}}
847 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
848 name="author">} tag in the output HTML files, so that browsers which
849 support this can automatically identify the \i{author} of the document.
851 \dt \I{\cw{\\cfg\{html-description\}}}\cw{\\cfg\{html-description\}\{}\e{text}\cw{\}}
853 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
854 name="description">} tag in the output HTML files, so that browsers
855 which support this can easily pick out a brief \I{description, of
856 document}description of the document.
858 \S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help}
860 The HTML files output from Halibut's HTML back end can be used as
861 input to the MS Windows HTML Help compiler. In order to do this, you
862 also need some auxiliary files: a project file, and (probably) a
863 contents file and an index file. Halibut can optionally generate
866 To enable the generation of MS HTML Help auxiliary files, use the
867 following configuration directives:
869 \dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}}
871 \dd Instructs Halibut to output an HTML Help project file with the
872 specified name. You will almost certainly want the filename to end
873 in the extension \c{.hhp} (although Halibut will not enforce this).
874 If you use this option, you must also use the
875 \cw{html-mshtmlhelp-chm} option to specify the desired name of the
878 \dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}}
880 \dd Specifies the desired name of the compiled HTML Help file. You
881 will almost certainly want this to have the extension \c{.chm}
882 (although Halibut will not enforce this). The name you specify here
883 will be written into the help project file. If you specify this
884 option, you must also use the \cw{html-mshtmlhelp-project} option to
885 request a help project file in the first place.
887 \dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}}
889 \dd Instructs Halibut to output an HTML Help contents file with the
890 specified name, and refer to it in the help project file. You will
891 almost certainly want the filename to end in the extension \c{.hhc}
892 (although Halibut will not enforce this). This option will be
893 ignored if you have not also specified a help project file.
897 Creating a contents file like this causes the HTML Help viewer to
898 display a contents tree in the pane to the left of the main text
899 window. You can choose to generate an HTML Help project without this
900 feature, in which case the user will still be able to navigate
901 around the document by using the ordinary internal links in the HTML
902 files themselves just as if it were a web page. However, using a
903 contents file is recommended.
907 \dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}}
909 \dd Instructs Halibut to output an HTML Help index file with the
910 specified name, and refer to it in the help project file. You will
911 almost certainly want the filename to end in the extension \c{.hhk}
912 (although Halibut will not enforce this). This option will be
913 ignored if you have not also specified a help project file.
917 Specifying this option suppresses the generation of an HTML-based
918 index file (see \cw{\\cfg\{html-index-filename\}} in
919 \k{output-html-file}).
921 Creating an index file like this causes the HTML Help viewer to
922 provide a list of index terms in a pane to the left of the main text
923 window. You can choose to generate an HTML Help project without this
924 feature, in which case a conventional HTML index will be generated
925 instead (assuming you have any index terms at all defined) and the
926 user will still be able to use that. However, using an index file is
929 Halibut will not output an index file at all, or link to one from
930 the help project file, if your document contains no index entries.
934 If you use the above options, Halibut will output a help project
935 file which you should be able to feed straight to the command-line
936 MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help
937 Workshop (\cw{HHW.EXE}).
939 You may also wish to alter other HTML configuration options to make
940 the resulting help file look more like a help file and less like a
941 web page. A suggested set of additional configuration options for
942 HTML Help is as follows:
944 \b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help
945 works best with lots of small files (\q{topics}) rather than a few
946 large ones. In particular, the contents and index mechanisms can
947 only reference files, not subsections within files.
949 \b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress
950 the contents list above the main text of each bottom-level file.
952 \b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help
953 has its own navigation facilities and it looks a bit strange to
956 \b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the
957 \cw{<ADDRESS>} section makes less sense in a help file than it does
960 \S{output-html-defaults} Default settings
962 The \i{default settings} for Halibut's HTML output format are:
964 \c \cfg{html-contents-filename}{Contents.html}
965 \c \cfg{html-index-filename}{IndexPage.html}
966 \c \cfg{html-template-filename}{%n.html}
967 \c \cfg{html-single-filename}{Manual.html}
969 \c \cfg{html-leaf-level}{2}
970 \c \cfg{html-leaf-contains-contents}{false}
971 \c \cfg{html-leaf-smallest-contents}{4}
972 \c \cfg{html-contents-depth}{0}{2}
973 \c \cfg{html-contents-depth}{1}{3}
974 \c ... and so on for all section levels below this ...
975 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
977 \c \cfg{html-head-end}{}
978 \c \cfg{html-body-tag}{<body>}
979 \c \cfg{html-body-start}{}
980 \c \cfg{html-body-end}{}
981 \c \cfg{html-address-start}{}
982 \c \cfg{html-address-end}{}
983 \c \cfg{html-navigation-attributes}{}
985 \c \cfg{html-chapter-numeric}{false}
986 \c \cfg{html-chapter-shownumber}{true}
987 \c \cfg{html-chapter-suffix}{: }
989 \c \cfg{html-section-numeric}{0}{true}
990 \c \cfg{html-section-shownumber}{0}{true}
991 \c \cfg{html-section-suffix}{0}{ }
993 \c \cfg{html-section-numeric}{1}{true}
994 \c \cfg{html-section-shownumber}{1}{true}
995 \c \cfg{html-section-suffix}{1}{ }
997 \c ... and so on for all section levels below this ...
998 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
1000 \c \cfg{html-preamble-text}{Preamble}
1001 \c \cfg{html-contents-text}{Contents}
1002 \c \cfg{html-index-text}{Index}
1003 \c \cfg{html-title-separator}{ - }
1004 \c \cfg{html-index-main-separator}{: }
1005 \c \cfg{html-index-multiple-separator}{, }
1006 \c \cfg{html-pre-versionid}{[}
1007 \c \cfg{html-post-versionid}{]}
1008 \c \cfg{html-nav-prev-text}{Previous}
1009 \c \cfg{html-nav-next-text}{Next}
1010 \c \cfg{html-nav-up-text}{Up}
1011 \c \cfg{html-nav-separator}{ | }
1013 \c \cfg{html-output-charset}{ASCII}
1014 \c \cfg{html-restrict-charset}{UTF-8}
1015 \c \cfg{html-quotes}{\u2018}{\u2019}{"}{"}
1017 \c \cfg{html-version}{html4}
1018 \c \cfg{html-template-fragment}{%b}
1019 \c \cfg{html-versionid}{true}
1020 \c \cfg{html-rellinks}{true}
1021 \c \cfg{html-suppress-navlinks{false}
1022 \c \cfg{html-suppress-address}{false}
1023 \c \cfg{html-author}{}
1024 \c \cfg{html-description}{}
1026 \H{output-whlp} Windows Help
1028 This output format generates data that can be used by the \i{Windows
1029 Help} program \cw{WINHLP32.EXE}. There are two actual files
1030 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
1032 Note that as of 2006, MS is discontinuing the Windows Help format in
1033 favour of the newer HTML Help format (\c{.chm} files). Halibut is
1034 not currently able to generate \c{.chm} files directly, but its HTML
1035 back end can write out project files suitable for use as input to
1036 the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more
1037 information on this.
1039 Currently, the Windows Help output is hardcoded to be in the
1040 \q{\i{Win1252}} character set. (If anyone knows how character sets
1041 are encoded in Windows Help files, we'd appreciate help.)
1043 The Windows Help output format supports the following configuration
1046 \S{output-whlp-file} Output file name
1048 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
1050 \dd Sets the \i{output file name} in which to store the man page.
1051 This directive is implicitly generated if you provide a file name
1052 parameter after the command-line option \i\c{--winhelp} (see
1053 \k{running-options}).
1057 Your output file name should end with \c{.hlp}; if it doesn't,
1058 Halibut will append it. Halibut will also generate a contents file
1059 (ending in \c{.cnt}) alongside the file name you specify.
1063 \S{output-whlp-characters} Configuring the characters used
1065 \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1067 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1068 You can specify multiple fallback options. Works exactly like the
1069 \cw{\\cfg\{text-bullet\}} directive (see
1070 \k{output-text-characters}).
1072 \dt \I{\cw{\\cfg\{winhelp-quotes\}}}\cw{\\cfg\{winhelp-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
1074 \dd Specifies the quotation marks to use, overriding any
1075 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1076 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1077 directive (see \k{output-text-characters}).
1079 \S{output-whlp-misc} Miscellaneous configuration options
1081 \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
1083 \dd Sets the text used to describe the help page containing the blurb
1084 (see \k{input-blurb}) and table of contents.
1087 \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
1089 \dd Specifies the \I{suffix text, in section titles}suffix text to
1090 be appended to section numbers, before displaying the section title.
1091 (Applies to all levels.)
1093 \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
1095 \dd This text is appended to the number on a \i{numbered list} item,
1096 in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
1097 \k{output-text-characters}).
1099 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
1101 \dd This directive defines a Windows \i{Help topic} name in the current
1102 section. Topic names can be used by the program invoking
1103 \cw{WINHELP.EXE} to jump straight to a particular section. So you
1104 can use this for \i{context-sensitive help}.
1108 For example, if you used this directive in a particular section:
1110 \c \cfg{winhelp-topic}{savingfiles}
1112 then a Windows application could invoke Windows Help to jump to that
1113 particular section in the help file like this:
1115 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
1116 \c (DWORD)"JI(`',`savingfiles')");
1118 You can use this configuration directive many times, in many
1119 different subsections of your document, in order to define a lot of
1120 different help contexts which you can use in this way.
1124 \S{output-whlp-defaults} Default settings
1126 The \i{default settings} for the Windows Help output format are:
1128 \c \cfg{winhelp-filename}{output.hlp}
1130 \c \cfg{winhelp-bullet}{\u2022}{-}
1131 \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
1133 \c \cfg{winhelp-contents-titlepage}{Title page}
1134 \c \cfg{winhelp-section-suffix}{: }
1135 \c \cfg{winhelp-list-suffix}{.}
1137 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
1139 \H{output-man} Unix \cw{man} pages
1141 This output format generates a Unix \i{\cw{man} page}. That is to say,
1142 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
1145 The available configuration options for this format are as follows:
1147 \S{output-man-file} Output file name
1149 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
1151 \dd Sets the \i{output file name} in which to store the man page.
1152 This directive is implicitly generated if you provide a file name
1153 parameter after the command-line option \i\c{--man} (see
1154 \k{running-options}).
1156 \S{output-man-identity} Configuring headers and footers
1158 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
1160 \dd This directive is used to generate the initial \i{\c{.TH}
1161 directive} that appears at the top of a \cw{man} page. It expects to
1162 be followed by some number of brace pairs containing text, which will
1163 be used in the \i{headers} and \i{footers} of the formatted output.
1167 A traditional order for the arguments appears to be:
1169 \n The name of the program.
1171 \n The (numeric) manual section.
1173 \n The date that the \cw{man} page was written.
1175 \n The name of any containing suite of which the program is a part.
1177 \n The name of the \i{author} of the \cw{man} page.
1179 For example, a typical \cw{man} page might contain
1181 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
1186 \S{output-man-headings} Configuring heading display
1188 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
1190 \dd If this is set to \c{true}, then \i{section headings} in the
1191 \cw{man} page will have their \i{section numbers} displayed as usual. If
1192 set to \c{false}, the section numbers will be omitted. (\cw{man}
1193 pages traditionally have section names such as \q{SYNOPSIS},
1194 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
1195 \c{false} is the setting which conforms most closely to normal
1198 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
1200 \dd If this is set to a number greater than 0, then section headings
1201 \e{higher} than the given depth will not be displayed. If it is set
1202 to zero, all section headings will be displayed as normal.
1206 The point of this is so that you can use the same Halibut input file
1207 to generate a quick-reference \cw{man} page for a program, \e{and} to
1208 include that \cw{man} page as an appendix in your program's full manual.
1209 If you are to include the \cw{man} page as an appendix, then the internal
1210 headings within the page will probably need to be at \c{\\H} or
1211 \c{\\S} level; therefore, when you format that input file on its own
1212 to create the \cw{man} page itself, you will need to have defined a
1213 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
1214 want to see displayed.
1216 Here's an example. You might have a file \c{appendix.but}, which
1219 \c \A{manpages} \cw{man} pages for the Foo tool suite
1221 \c \cfg{man-mindepth}{2}
1223 Then you have a file \c{make-foo.but}, and probably others like it
1224 as well, each of which looks something like this:
1226 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
1229 \c \H{man-foo} \cw{man} page for \c{make-foo}
1231 \c \S{man-foo-name} NAME
1233 \c \c{make-foo} - create Foo files for the Foo tool suite
1235 \c \S{man-foo-synopsis} SYNOPSIS
1237 \c ... and so on ...
1238 \e iiiiiiiiiiiiiiiii
1240 So when you're generating your main manual, you can include
1241 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
1242 pages you have, and your \cw{man} pages will be formatted neatly as
1243 part of an appendix. Then, in a separate run of Halibut, you can
1246 \c halibut appendix.but make-foo.but
1248 and this will generate a \cw{man} page \c{output.1}, in which the
1249 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
1250 page for \c{make-foo}} will not be displayed because of the
1251 \c{man-mindepth} directive. So the first visible heading in the
1252 output \cw{man} page will be \q{NAME}, exactly as a user would
1257 \S{output-man-characters} Configuring the characters used
1259 \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
1261 \dd Specifies what character set the output should be in, similarly to
1262 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1264 \# FIXME: you're probably on your own in making sure that it's
1265 sensible to output man pages in that charset.
1267 \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1269 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1270 You can specify multiple fallback options. Works exactly like the
1271 \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
1273 \dt \I{\cw{\\cfg\{man-rule\}}}\cw{\\cfg\{man-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
1275 \dd This specifies the text which should be used for drawing
1276 \i{horizontal rules} (generated by \i\c{\\rule}; see
1277 \k{input-rule}) when the manual page is rendered into text.
1278 It should only be one character long, but otherwise
1279 it works like the \cw{\\cfg\{text-rule\}} directive
1280 (see \k{output-text-characters}).
1282 \dt \I{\cw{\\cfg\{man-quotes\}}}\cw{\\cfg\{man-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
1284 \dd Specifies the quotation marks to use, overriding any
1285 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1286 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1287 directive (see \k{output-text-characters}).
1289 \S{output-man-defaults} Default settings
1291 The \i{default settings} for the \cw{man} page output format are:
1293 \c \cfg{man-filename}{output.1}
1295 \c \cfg{man-identity}{}
1297 \c \cfg{man-headnumbers}{false}
1298 \c \cfg{man-mindepth}{0}
1300 \c \cfg{man-charset}{ASCII}
1301 \c \cfg{man-bullet}{\u2022}{o}
1302 \c \cfg{man-rule}{\u2500}{-}
1303 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
1305 \H{output-info} GNU Info
1307 This output format generates files which can be used with the \i{GNU
1310 There are typically multiple output files: a primary file whose name
1311 usually ends in \c{.info}, and one or more subsidiary files whose
1312 names have numbers on the end, so that they end in \c{.info-1},
1313 \c{.info-2} and so on. Alternatively, this output format can be
1314 configured to output a single large file containing the whole
1317 The Info output format supports the following configuration
1320 \S{output-info-file} Controlling the output filenames
1322 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
1324 \dd Sets the output file name in which to store the Info file.
1325 This directive is implicitly generated if you provide a file name
1326 parameter after the command-line option \i\c{--info} (see
1327 \k{running-options}).
1331 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
1332 your output file name to produce any subsidiary files required.
1334 Note that Info files refer to their own names internally, so
1335 these files cannot be \I{renaming Info files}renamed after
1336 creation and remain useful.
1340 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
1342 \dd Sets the preferred \i{maximum file size} for each subsidiary
1343 file. As a special case, if you set this to zero, there will be no
1344 subsidiary files and the whole document will be placed in a single
1345 self-contained output file. (However, note that this file can still
1346 not be renamed usefully.)
1350 The preferred maximum file size is only a guideline. Halibut may be
1351 forced to exceed it if a single section of the document is larger
1352 than the maximum size (since individual Info nodes may not be
1353 split between files).
1357 \S{output-info-dimensions} Indentation and line width
1359 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
1361 \dd Sets the \I{text width}width of the main part of the document,
1362 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
1363 directive (see \k{output-text-dimensions}).
1365 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
1367 \dd Specifies the extra indentation for \I{code paragraphs,
1368 indentation} code paragraphs. Works exactly like the
1369 \cw{\\cfg\{text-indent-code\}} directive (see
1370 \k{output-text-dimensions}).
1372 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
1374 \dd Specifies how much horizontal space to leave in the index node
1375 for the text of \i{index terms}, before displaying the sections the
1378 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
1380 \dd Specifies the extra indentation before the bullet or number in a
1381 \I{bulletted list, indentation}\I{numbered list, indentation}list
1382 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
1383 directive (see \k{output-text-dimensions}).
1385 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
1387 \dd Specifies the additional indentation before the body of a list
1388 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
1389 directive (see \k{output-text-dimensions}).
1391 \S{output-info-headings} Configuring heading display
1393 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
1395 \dd Specifies the suffix text to be appended to each section number
1396 before displaying the section title. For example, if you set this to
1397 \cq{:\_}, then a typical section title might look something like
1398 \q{Section 3.1: Something Like This}.
1400 \dt \I{\cw{\\cfg\{info-title-underline\}}}\cw{\\cfg\{info-title-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1402 \dd Specifies the text to be used to \I{underlining}underline
1403 the overall document title. Works
1404 very much like the \cw{\\cfg\{text-title-underline\}} directive
1405 (see \k{output-text-headings}). You can specify more than one
1406 option, and Halibut will choose the first one supported by the
1409 \dt \I{\cw{\\cfg\{info-chapter-underline\}}}\cw{\\cfg\{info-chapter-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1411 \dd Specifies how chapter and appendix headings should be underlined.
1413 \dt \I{\cw{\\cfg\{info-section-underline\}}}\cw{\\cfg\{info-section-underline\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1415 \dd Specifies how to underline section headings at a particular level.
1416 The \e{level} parameter specifies which level of section
1417 headings you want to affect: 0 means first-level headings (\c{\\H}),
1418 1 means second-level headings (\c{\\S}), 2 means the level below
1419 that (\c{\\S2}), and so on.
1421 \S{output-info-characters} Controlling the characters used
1423 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
1425 \dd Specifies what character set the output should be in, similarly to
1426 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1428 \# FIXME: if you try sufficiently hard, you can probably find an
1429 output encoding that will break the info format by trampling on its
1430 special characters. So either don't do that, or tell us what we should
1433 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1435 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1436 You can specify multiple fallback options. Works exactly like the
1437 \cw{\\cfg\{text-bullet\}} directive (see
1438 \k{output-text-characters}).
1440 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1442 \dd Specifies the text used to draw \i{horizontal rules}. You can
1443 specify multiple fallback options. Works exactly like the
1444 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
1446 \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{\}}]
1448 \dd Specifies the quotation marks to use, overriding any
1449 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1450 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1451 directive (see \k{output-text-characters}).
1453 \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{\}}]
1455 \dd Specifies how to display emphasised text. You can specify
1456 multiple fallback options. Works exactly like the
1457 \cw{\\cfg\{text-emphasis\}} directive (see
1458 \k{output-text-characters}).
1460 \S{output-info-misc} Miscellaneous configuration options
1462 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
1464 \dd Specifies the text to append to the item numbers in a
1465 \i{numbered list}. Works exactly like the
1466 \cw{\\cfg\{text-list-suffix\}} directive (see
1467 \k{output-text-misc}).
1469 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
1470 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
1472 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
1473 header of the Info file. This mechanism is used to automatically
1474 generate the \i{\c{dir} file} at the root of a Unix system's
1479 The parameters to this directive are:
1483 \dd Specifies the section of the \c{dir} file in which you want your
1484 document referenced. For example, \q{Development}, or \q{Games}, or
1489 \dd Specifies a short name for the directory entry, which will
1490 appear at the start of the menu line.
1494 \dd Specifies a long name for the directory entry, which will appear
1495 at the end of the menu line.
1499 \dd This parameter is optional. If it is present, then the directory
1500 entry will cause a jump to a particular subsection of your document,
1501 rather than starting at the top. The subsection will be the one
1502 referred to by the given keyword (see \k{input-sections} for details
1503 about assigning keywords to document sections).
1505 For example, in a document describing many game programs, the
1506 configuration directive
1508 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1511 might produce text in the \c{dir} file looking something like this:
1514 \c * Chess: (mygames)Chapter 3. Electronic chess game
1516 if the output file were called \c{mygames.info} and the keyword
1517 \c{chess} had been used to define Chapter 3 of the document.
1521 \S{output-info-defaults} Default settings
1523 The \i{default settings} for the Info output format are:
1525 \c \cfg{info-filename}{output.info}
1526 \c \cfg{info-max-file-size}{65536}
1528 \c \cfg{info-width}{70}
1529 \c \cfg{info-indent-code}{2}
1530 \c \cfg{info-index-width}{40}
1531 \c \cfg{info-list-indent}{1}
1532 \c \cfg{info-listitem-indent}{3}
1534 \c \cfg{info-section-suffix}{: }
1535 \c \cfg{info-title-underline}{*}
1536 \c \cfg{info-chapter-underline}{=}
1537 \c \cfg{info-section-underline}{0}{-}
1538 \c \cfg{info-section-underline}{1}{.}
1539 \c \cfg{info-section-underline}{2}{.}
1540 \c ... and so on for all section levels below this ...
1541 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
1543 \c \cfg{info-charset}{ASCII}
1544 \c \cfg{info-bullet}{\u2022}{-}
1545 \c \cfg{info-rule}{\u2500}{-}
1546 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1547 \c \cfg{info-emphasis}{_}{_}
1549 \c \cfg{info-list-suffix}{.}
1551 and no \cw{\\cfg\{info-dir-entry\}} directives.
1553 \H{output-paper} Paper formats
1555 These output formats (currently PDF and PostScript) generate printable
1556 manuals. As such, they share a number of configuration directives.
1558 \S{output-pdf} \i{PDF}
1560 This output format generates a printable manual in PDF format. In
1561 addition, it uses some PDF interactive features to
1562 provide an outline of all the document's sections and clickable
1563 cross-references between sections.
1565 There is one configuration option specific to PDF:
1567 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1569 \dd Sets the \i{output file name} in which to store the PDF file.
1570 This directive is implicitly generated if you provide a file name
1571 parameter after the command-line option \i\c{--pdf} (see
1572 \k{running-options}).
1574 The \i{default settings} for the PDF output format are:
1576 \c \cfg{pdf-filename}{output.pdf}
1578 \S{output-ps} \i{PostScript}
1580 This output format generates a printable manual in PostScript format.
1581 This should look exactly identical to the PDF output (see
1582 \k{output-ps}), and uses \i\c{pdfmark} to arrange that if converted
1583 to PDF it will contain the same interactive features.
1585 There is one configuration option specific to PostScript:
1587 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1589 \dd Sets the \i{output file name} in which to store the PostScript
1590 file. This directive is implicitly generated if you provide a file
1591 name parameter after the command-line option \i\c{--ps} (see
1592 \k{running-options}).
1594 The \i{default settings} for the PostScript output format are:
1596 \c \cfg{ps-filename}{output.ps}
1598 \S{output-paper-dimensions} Configuring layout and \i{measurements}
1600 All measurements are in PostScript \i{points} (72 points to the inch).
1602 \S2{output-paper-pagesize} Page properties
1604 \dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
1606 \dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
1608 \dd Specify the absolute limits of the paper.
1610 \dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
1612 \dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
1614 \dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
1616 \dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
1618 \dd Specify the margins. Most text appears within these margins,
1623 \b Section numbers, which appear in the left margin.
1625 \b The footer (containing page numbers), which appears in the bottom
1630 \S2{output-paper-line} Vertical spacing
1632 \dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
1634 \dd Specifies the amount of space between lines of text within a
1635 paragraph. (So, if the font size is 12pt and there is 2pt of leading,
1636 there will be 14pt between successive baselines.)
1638 \dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
1640 \dd Specifies the amount of vertical space between paragraphs. (The
1641 vertical space between paragraphs does \e{not} include
1642 \c{paper-base-leading}.)
1644 \S2{output-paper-indentation} Indentation
1646 \dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
1648 \dd Specifies the indentation of the bullet or number in a
1649 \I{bulletted list, indentation}bulletted or \I{numbered list,
1650 indentation}numbered \I{list, indentation}list, similarly to
1651 \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
1653 \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
1655 \dd Specifies the \e{extra} indentation for the body of a list item,
1656 over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
1658 \# FIXME: doesn't actually work, AFAICT.
1660 \dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
1662 \dd Specifies the amount of indentation for a level of quoting. Used
1663 for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
1664 (see \k{input-code}).
1666 \S2{output-paper-headings} Headings
1668 \dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
1670 \dd Specifies the space between the top margin and the top of the
1671 chapter heading. (Each chapter begins on a new page.)
1673 \dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
1675 \dd Specifies the vertical thickness of the black rule under chapter
1678 \dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
1680 \dd Specifies the distance between the base of the chapter heading and
1681 the \e{base} of the underlying rule.
1683 \dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
1685 \dd Specifies the distance between the left margin and the \e{right}
1686 of section numbers (which are in the left margin).
1688 \S2{output-paper-index} Contents and index
1690 \dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}}
1692 \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
1694 \# FIXME: I do not know what dees one does. (I couldn't get either of
1695 them to do anything obvious, although the source indicates they should
1698 \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
1700 \dd Specifies the horizontal spacing between dots in \i\e{leaders}
1701 (the dotted lines that appear between section headings and page
1702 numbers in the table of contents).
1704 \dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
1706 \dd Specifies the distance between the bottom margin and the \e{base}
1707 of the footer (which contains page numbers).
1709 \dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
1711 \dd Specifies the number of columns the index should be divided into.
1713 \# FIXME: with this set to 1, the right-alignment of some index entry
1714 page numbers in the Halibut manual is decidedly wonky.
1716 \dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
1718 \dd Specifies the amount of \I{gutter} horizontal space between index
1721 \dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
1723 \dd Specifies the minimum allowable horizontal space between an index
1724 entry and its page number. If the gap is smaller, the page number is
1725 moved to the next line.
1727 \S2{output-paper-fonts} \ii{Fonts}
1729 The directives in this section control which fonts Halibut uses for
1730 various kinds of text. Directives for setting the font normally take
1731 three font names, the first of which is used for normal text, the
1732 second for emphasised text, and the third for code. Any fonts which
1733 aren't specified are left unchanged.
1735 Halibut intrinsically knows about some fonts, and these fonts are also
1736 built into all PDF and most PostScript implementations.
1737 These fonts can be used without further formality. Halibut can also use
1738 other fonts, and can \I{embedding fonts}embed them it its PDF and
1739 PostScript output. These other fonts are supplied to Halibut by
1740 simply adding them to the list of input files on its command line.
1742 To use a \i{Type 1 font} Halibut needs both the font file itself,
1743 in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB)
1744 format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file. The AFM
1745 file must be specified first on the command line. If Halibut gets an
1746 AFM file without a corresponding Type 1 font file, the PostScript and
1747 PDF output files will still use that font, but they won't contain it.
1749 Using a \i{TrueType font} is rather simpler, and simply requires you to
1750 pass the font file to Halibut. Halibut does place a few restrictions on
1751 TrueType fonts, notably that they must include a \i{Unicode} mapping
1752 table and a PostScript name.
1754 Fonts are specified using their PostScript names. Running Halibut with
1755 the \i\cw{\-\-list-fonts} option causes it to display the PostScript
1756 names of all the fonts it intrinsically knows about, along with any
1757 fonts the were supplied as input files.
1759 \ii{Font sizes} are specified in PostScript \i{points} (72 to the inch).
1761 \dt \I{\cw{\\cfg\{paper-title-fonts\}}}\cw{\\cfg\{paper-title-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
1763 \dd Specifies the fonts to use for text in the document title.
1765 \dt \I{\cw{\\cfg\{paper-title-font-size\}}}\cw{\\cfg\{paper-title-font-size\}\{}\e{points}\cw{\}}
1767 \dd Specifies the \i{font size} of the document title.
1769 \dt \I{\cw{\\cfg\{paper-chapter-fonts\}}}\cw{\\cfg\{paper-chapter-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
1771 \dd Specifies the fonts to use for text in chapter titles.
1773 \dt \I{\cw{\\cfg\{paper-chapter-font-size\}}}\cw{\\cfg\{paper-chapter-font-size\}\{}\e{points}\cw{\}}
1775 \dd Specifies the \i{font size} of chapter titles.
1777 \dt \I{\cw{\\cfg\{paper-section-fonts\}}}\cw{\\cfg\{paper-section-fonts\}\{}\e{level}\cw{\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
1779 \dd Specifies the fonts to use for text in section headings at the \e{level}
1782 \dt \I{\cw{\\cfg\{paper-section-font-size\}}}\cw{\\cfg\{paper-section-font-size\}\{}\e{level}\cw{\}\{}\e{points}\cw{\}}
1784 \dd Specifies the \i{font size} of section headings at the \e{level}
1787 \dt \I{\cw{\\cfg\{paper-base-fonts\}}}\cw{\\cfg\{paper-base-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]]
1789 \dd Specifies the fonts to use for text in the body text.
1791 \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
1793 \dd Specifies the \i{font size} of body text.
1795 \dt \I{\cw{\\cfg\{paper-code-fonts\}}}\cw{\\cfg\{paper-code-fonts\}\{}\e{bold-font}\cw{\}}[\cw{\{}\e{italic-font}\cw{\}}[\cw{\{}\e{normal-font}\cw{\}}]]
1797 \dd Specifies the fonts to use for text in code paragraphs. The
1798 \e{bold-font} is used for bold text, the \e{italic-font} for
1799 emphasised text, and the \e{normal-font} for normal code.
1801 \dt \I{\cw{\\cfg\{paper-code-font-size\}}}\cw{\\cfg\{paper-code-font-size\}\{}\e{points}\cw{\}}
1803 \dd Specifies the \i{font size} of text in code paragraphs.
1805 \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
1807 \dd Specifies the font size to use for \i{page numbers}.
1809 \S2{output-paper-misc} Miscellaneous
1811 \dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
1813 \dd Specifies the vertical thickness of the rule produced by the
1814 \cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
1815 reserved for thicker rules.)
1817 \S{output-paper-characters} Configuring the characters used
1819 \dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1821 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1822 You can specify multiple fallback options. Works exactly like the
1823 \cw{\\cfg\{text-bullet\}} directive (see
1824 \k{output-text-characters}).
1826 \dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}]
1828 \dd Specifies the quotation marks to use, overriding any
1829 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1830 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1831 directive (see \k{output-text-characters}).
1833 \S{output-paper-defaults} Default settings for paper formats
1835 The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
1838 \c \cfg{paper-page-width}{595}
1839 \c \cfg{paper-page-height}{842}
1841 \c \cfg{paper-left-margin}{72}
1842 \c \cfg{paper-top-margin}{72}
1843 \c \cfg{paper-right-margin}{72}
1844 \c \cfg{paper-bottom-margin}{108}
1846 \c \cfg{paper-base-leading}{1}
1847 \c \cfg{paper-base-para-spacing}{10}
1849 \c \cfg{paper-list-indent}{6}
1850 \c \cfg{paper-listitem-indent}{18}
1851 \c \cfg{paper-quote-indent}{18}
1853 \c \cfg{paper-chapter-top-space}{72}
1854 \c \cfg{paper-chapter-underline-thickness}{3}
1855 \c \cfg{paper-chapter-underline-depth}{14}
1856 \c \cfg{paper-sect-num-left-space}{12}
1858 \c \cfg{paper-contents-index-step}{24}
1859 \c \cfg{paper-contents-margin}{84}
1860 \c \cfg{paper-leader-separation}{12}
1861 \c \cfg{paper-footer-distance}{32}
1862 \c \cfg{paper-index-columns}{2}
1863 \c \cfg{paper-index-gutter}{36}
1864 \c \cfg{paper-index-minsep}{18}
1866 \c \cfg{paper-base-fonts}{Times-Roman}{Times-Italic}{Courier}
1867 \c \cfg{paper-base-font-size}{12}
1868 \c \cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier}
1869 \c \cfg{paper-code-font-size}{12}
1870 \c \cfg{paper-title-fonts}{Helvetica-Bold}
1871 \c {Helvetica-BoldOblique}{Courier-Bold}
1872 \c \cfg{paper-title-font-size}{24}
1873 \c \cfg{paper-chapter-fonts}{Helvetica-Bold}
1874 \c {Helvetica-BoldOblique}{Courier-Bold}
1875 \c \cfg{paper-chapter-font-size}{20}
1876 \c \cfg{paper-section-fonts}{0}{Helvetica-Bold}
1877 \c {Helvetica-BoldOblique}{Courier-Bold}
1878 \c \cfg{paper-section-font-size}{0}{16}
1879 \c \cfg{paper-section-fonts}{1}{Helvetica-Bold}
1880 \c {Helvetica-BoldOblique}{Courier-Bold}
1881 \c \cfg{paper-section-font-size}{1}{14}
1882 \c \cfg{paper-section-fonts}{2}{Helvetica-Bold}
1883 \c {Helvetica-BoldOblique}{Courier-Bold}
1884 \c \cfg{paper-section-font-size}{2}{13}
1885 \c ... and so on for all section levels below this ...
1886 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
1888 \c \cfg{paper-pagenum-font-size}{12}
1890 \c \cfg{paper-rule-thickness}{1}
1892 \c \cfg{paper-bullet}{\u2022}{-}
1893 \c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}