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-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
147 \dd This specifies the suffix text to be appended to the chapter
148 number, before displaying the chapter title. For example, if you set
149 this to \cq{:\_}, then the chapter title might look something
150 like \q{Chapter 2: Doing Things}.
152 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
154 \dd Specifies the alignment of section headings at a particular
155 level. The \e{level} parameter specifies which level of section
156 headings you want to affect: 0 means first-level headings (\c{\\H}),
157 1 means second-level headings (\c{\\S}), 2 means the level below
158 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
159 just like the other alignment directives listed above.
161 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}}
163 \dd Specifies how to underline section headings at a particular level.
165 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
167 \dd Specifies whether section headings at a particular level should
168 contain the word \q{Section} or equivalent (if \c{false}), or should
169 be numeric only (if \c{true}).
171 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
173 \dd Specifies the \I{suffix text, in section titles}suffix text to
174 be appended to section numbers at a particular level, before
175 displaying the section title.
177 \S{output-text-characters} Configuring the characters used
179 \dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}}
181 \dd This tells Halibut what \i{character set} the output should be
182 in. Any Unicode characters representable in this set will be output
183 verbatim; any other characters will not be output and their
184 \i{fallback text} (if any) will be used instead.
188 The character set names are the same as for
189 \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
190 \cw{\\cfg\{input-charset\}}, this directive affects the \e{entire}
191 output; it's not possible to switch encodings halfway through.
195 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
197 \dd This specifies the text which should be used as the \i{bullet}
198 in bulletted lists. It can be one character
199 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
200 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
204 Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple
205 possible options after this command, and Halibut will choose the first one
206 which the output character set supports. For example, you might write
207 \cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case
208 Halibut would use the Unicode \q{BULLET} character where possible,
209 fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available,
210 and resort to the ASCII asterisk if all else failed.
214 \dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
216 \dd This specifies the text which should be used for drawing
217 \i{horizontal rules} (generated by \i\c{\\rule}; see
218 \k{input-rule}). It can be one character, or more than one. The
219 string you specify will be repeated to reach the required width, so
220 you can specify something like \cq{-=} to get a rule that looks
225 Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback
226 options in this command.
230 \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{\}}]
232 \dd This specifies a set of quote characters for the text backend,
233 overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax
234 (see \k{input-config}).
238 In this backend, these quotes will also be used to mark text enclosed
239 in the \c{\\c} command (see \k{input-code}).
243 \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{\}}]
245 \dd This specifies the characters which should be used to surround
246 emphasised text (written using the \c{\\e} command; see
251 You should separately specify the start-emphasis and end-emphasis
252 text, each of which can be more than one character if you want.
253 Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs
254 of fallback options in this command, and Halibut will always use a
259 \S{output-text-misc} Miscellaneous configuration options
261 \dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}}
263 \dd This text is appended to the number on a \i{numbered list} item
264 (see \k{input-list-number}). So if you want to label your lists as
265 \q{1)}, \q{2)} and so on, then you would write
266 \cw{\\cfg\{text-list-suffix\}\{)\}}.
268 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
270 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
271 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
272 included at the bottom of the text file. If it is set to \c{false},
273 they will be omitted completely.
275 \# FIXME: code indentation is configurable, therefore \quote
276 \# indentation probably ought to be as well.
278 \# FIXME: text-indent-* should be consistently named.
280 \S{output-text-defaults} Default settings
282 The \i{default settings} for Halibut's plain text output format are:
284 \c \cfg{text-filename}{output.txt}
286 \c \cfg{text-width}{68}
287 \c \cfg{text-indent}{7}
288 \c \cfg{text-indent-code}{2}
289 \c \cfg{text-list-indent}{1}
290 \c \cfg{text-listitem-indent}{3}
291 \c \cfg{text-indent-preamble}{false}
293 \c \cfg{text-title-align}{centre}
294 \c \cfg{text-title-underline}{\u2550}{=}
296 \c \cfg{text-chapter-align}{left}
297 \c \cfg{text-chapter-underline}{\u203e}{-}
298 \c \cfg{text-chapter-numeric}{false}
299 \c \cfg{text-chapter-suffix}{: }
301 \c \cfg{text-section-align}{0}{leftplus}
302 \c \cfg{text-section-underline}{0}{}
303 \c \cfg{text-section-numeric}{0}{true}
304 \c \cfg{text-section-suffix}{0}{ }
306 \c \cfg{text-section-align}{1}{leftplus}
307 \c \cfg{text-section-underline}{1}{}
308 \c \cfg{text-section-numeric}{1}{true}
309 \c \cfg{text-section-suffix}{1}{ }
311 \c ... and so on for all section levels below this ...
312 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
314 \c \cfg{text-charset}{ASCII}
315 \c \cfg{text-bullet}{\u2022}{-}
316 \c \cfg{text-rule}{\u2500}{-}
317 \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
318 \c \cfg{text-emphasis}{_}{_}
320 \c \cfg{text-list-suffix}{.}
321 \c \cfg{text-versionid}{true}
325 \e{NOTE:} This documentation is out of date with respect to the
326 current HTML backend, and needs rewriting.
328 This output format generates an \i{HTML} version of the document. By
329 default, this will be in multiple files, starting with
330 \c{Contents.html} and splitting the document into files by chapter
331 and/or subsection. You can configure precisely how the text is split
332 between HTML files using the configuration commands described in
333 this section. In particular, you can configure Halibut to output one
334 single HTML file instead of multiple ones.
336 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
337 which is why all of the configuration directives start with the word
338 \c{xhtml} rather than \c{html}.
340 \S{output-html-file} Controlling the output file names
342 \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
344 \dd Sets the \i{output file name} in which to store the top-level
345 contents page. Since this is the first page a user ought to see when
346 beginning to read the document, a good choice in many cases might be
347 \c{index.html} (although this is not the default, for historical
350 \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
352 \dd Sets the file name in which to store the document's index.
354 \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
356 \dd Provides a \i{template} to be used when constructing the file
357 names of each chapter or section of the document. This template
358 should contain at least one \i\e{formatting command}, in the form of
359 a per cent sign followed by a letter. (If you need a literal per
360 cent sign, you can write \c{%%}.)
364 The formatting commands used in this template are:
366 \dt \I{%N-upper}\c{%N}
368 \dd Expands to the visible title of the section, with white space
369 removed. So in a chapter declared as \cq{\\C\{fish\} Catching
370 Fish}, this formatting command would expand to
375 \dd Expands to the type and number of the section, without white
376 space. So in chapter 1 this would expand to \cq{Chapter1}; in
377 section A.4.3 it would expand to \cq{SectionA.4.3}, and so on.
378 If the section has no number (an unnumbered chapter created using
379 \c{\\U}), this directive falls back to doing the same thing as
384 \dd Expands to the bare number of the section. So in chapter 1 this
385 would expand to \cq{1}; in section A.4.3 it would expand to
386 \cq{A.4.3}, and so on. If the section has no number (an
387 unnumbered chapter created using \c{\\U}), this directive falls back
388 to doing the same thing as \c{%N}.
392 \dd Expands to the internal keyword specified in the section title.
393 So in a chapter declared as \cq{\\C\{fish\} Catching Fish}, this
394 formatting command would expand to \cq{fish}. If the section has
395 no keyword (an unnumbered chapter created using \c{\\U}), this
396 directive falls back to doing the same thing as \c{%N}.
398 These formatting directives can also be used in the
399 \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
400 \k{output-html-misc}).
404 \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
406 \dd Sets the file name in which to store the entire document, if
407 Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
408 produce a single self-contained file. Both this directive \e{and}
409 \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
410 provide a file name parameter after the command-line option
411 \i\c{--html} (see \k{running-options}).
413 \S{output-html-split} Controlling the splitting into HTML files
415 By default, the HTML output from Halibut is split into multiple
416 files. Each file typically contains a single chapter or section and
417 everything below it, unless subsections of that chapter are
418 themselves split off into further files.
420 Most files also contain a contents section, giving hyperlinks to the
421 sections in the file and/or the sections below it.
423 The configuration directives listed below allow you to configure the
424 splitting into files, and the details of the contents sections.
426 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
428 \dd This setting indicates the depth of section which should be
429 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
430 you set it to 1, for example, then every chapter will be given its
431 own HTML file, plus a top-level \i{contents file}. If you set this
432 to 2, then each chapter \e{and} each \c{\\H} section will have a
433 file, and the chapter files will mostly just contain links to their
438 If you set this option to zero, then the whole document will appear
439 in a single file. If you do this, Halibut will call that file
440 \i\c{Manual.html} instead of \i\c{Contents.html}.
442 This option is automatically set to zero if you provide a file name
443 parameter after the command-line option \i\c{--html} (see
444 \k{running-options}), because you have specified a single file name
445 and so Halibut assumes you want the whole document to be placed in
450 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
452 \dd This directive allows you to specify how \I{depth of
453 contents}deep the contents section in a particular file should go.
457 The \e{level} parameter indicates which level of contents section
458 you are dealing with. 0 denotes the main contents section in the
459 topmost file \c{Contents.html}; 1 denotes a contents section in a
460 chapter file; 2 is a contents section in a file containing a \c{\\H}
461 heading, and so on. Currently you can't go below level 5 (which
462 corresponds to a \c{\\S3} heading).
464 The \e{depth} parameter indicates the maximum depth of heading which
465 will be shown in this contents section. Again, 1 denotes a chapter,
466 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
468 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
469 Halibut to put contents links in chapter files for all sections down
470 to \c{\\S} level, but not to go into any more detail than that.
474 \# FIXME: this is utterly ghastly. For a start, it should include
475 \# the level as a separate argument, like the text section config
476 \# directives. Secondly, it shouldn't be limited in depth!
478 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
480 \dd If you set this to \c{true}, then each leaf file will contain
481 its own contents section which summarises the text within it.
483 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
485 \dd Contents sections in leaf files are not output at all if they
486 contain very few entries (on the assumption that it just isn't worth
487 bothering). This directive configures the minimum number of entries
488 required in a leaf contents section to make Halibut bother
489 generating it at all.
491 \S{output-html-html} Including pieces of your own HTML
493 The directives in this section allow you to supply pieces of
494 \I{HTML}\i{verbatim HTML} code, which will be included in various
495 parts of the output files.
497 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
499 \dd The text you provide in this directive is placed at the end of
500 the \i\cw{<HEAD>} section of each output HTML file. So this is a
501 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
503 \dt \I{\cw{\\cfg\{xhtml-local-head\}}}\cw{\\cfg\{xhtml-local-head\}\{}\e{HTML text}\cw{\}}
505 \dd This configuration directive is local: you specify it within a
506 document section, and it acts on that section only.
510 The text you provide in this directive is placed at the end of the
511 \i\cw{<HEAD>} section of whichever output HTML file contains the
512 section in which the directive was placed. You can specify this
513 directive multiple times in multiple sections if you like.
515 This directive is particularly useful for constructing \i{MacOS
516 on-line help}, which is mostly normal HTML but which requires a
517 special \i\cw{<META NAME="AppleTitle">} tag in the topmost source
518 file. You can arrange this by placing this configuration directive
519 in the preamble or the introduction section, something like this:
521 \c \cfg{html-local-head}{<meta name="AppleTitle"
522 \c content="MyApp Help">}
526 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
528 \dd The text you provide in this directive is used in place of the
529 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
530 \i{background colour}, for example, you could write
531 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
533 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
535 \dd The text you provide in this directive is placed at the
536 beginning of the \i\cw{<BODY>} section of each output HTML file. So
537 if you intend your HTML files to be part of a web site with a
538 standard \i{house style}, and the style needs a \i{header} at the
539 top of every page, this is where you can add that header.
541 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
543 \dd The text you provide in this directive is placed at the end of
544 the \i\cw{<BODY>} section of each output HTML file. So if you intend
545 your HTML files to be part of a web site with a standard \i{house
546 style}, and the style needs a \i{footer} at the bottom of every
547 page, this is where you can add that footer.
549 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
551 \dd The text you provide in this directive is placed at the
552 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
553 output HTML file. This might be a good place to put authors'
554 \i{contact details}, for example.
556 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
558 \dd The text you provide in this directive is placed at the end of
559 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
560 after the version IDs (if present).
562 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
564 \dd The text you provide in this directive is included inside the
565 \cw{<P>} tag containing the \i{navigation links} at the top of each
566 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
567 wanted the navigation links to have a particular CSS style, you
569 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
570 navigation-links paragraph would then begin with the tag \cw{<p
573 \S{output-html-headings} \ii{Configuring heading display}
575 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
577 \dd If this is set to \c{true}, then chapter headings will not
578 contain the word \q{Chapter} (or whatever other word you have
579 defined in its place - see \k{input-sections} and \k{input-config});
580 they will just contain the chapter \e{number}, followed by the
581 chapter title. If you set this to \c{false}, chapter headings will
582 be prefixed by \q{Chapter} or equivalent.
584 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
586 \dd This specifies the suffix text to be appended to the chapter
587 number, before displaying the chapter title. For example, if you set
588 this to \cq{:\_}, then the chapter title might look something
589 like \q{Chapter 2: Doing Things}.
591 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
593 \dd Specifies whether section headings at a particular level should
594 contain the word \q{Section} or equivalent (if \c{false}), or should
595 be numeric only (if \c{true}). The \e{level} parameter specifies
596 which level of section headings you want to affect: 0 means
597 first-level headings (\c{\\H}), 1 means second-level headings
598 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
600 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
602 \dd Specifies the suffix text to be appended to section numbers at a
603 particular level, before displaying the section title.
605 \S{output-html-misc} Miscellaneous options
607 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
609 \dd This directive lets you specify a \i{template}, with exactly the
610 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
611 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
612 NAME="...">}) used to allow URLs to refer to specific sections
613 within a particular HTML file. So if you set this to \cq{%k},
614 for example, then each individual section in your document will be
615 addressable by means of a URL ending in a \c{#} followed by your
616 internal section keyword.
618 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
620 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
621 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
622 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
623 file. If it is set to \c{false}, they will be omitted completely.
625 \# FIXME: surely it would be better to include them in HTML
626 \# comments? The only question is whether they should be _visible_.
628 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
630 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
631 bottom of each HTML file will be omitted completely. (This will
632 therefore also cause \i{version IDs} not to be included.)
634 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
636 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
637 name="author">} tag in the output HTML files, so that browsers which
638 support this can automatically identify the \i{author} of the document.
640 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
642 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
643 name="description">} tag in the output HTML files, so that browsers
644 which support this can easily pick out a brief \I{description, of
645 document}description of the document.
647 \S{output-html-defaults} Default settings
649 The \i{default settings} for Halibut's HTML output format are:
651 \c \cfg{xhtml-contents-filename}{Contents.html}
652 \c \cfg{xhtml-index-filename}{IndexPage.html}
653 \c \cfg{xhtml-template-filename}{%n.html}
654 \c \cfg{xhtml-single-filename}{Manual.html}
655 \c \cfg{xhtml-template-fragment}{%b}
657 \c \cfg{xhtml-leaf-level}{2}
658 \c \cfg{xhtml-leaf-contains-contents}{false}
659 \c \cfg{xhtml-leaf-smallest-contents}{4}
660 \c \cfg{xhtml-contents-depth-0}{2}
661 \c \cfg{xhtml-contents-depth-1}{3}
662 \c \cfg{xhtml-contents-depth-2}{4}
663 \c \cfg{xhtml-contents-depth-3}{5}
664 \c \cfg{xhtml-contents-depth-4}{6}
665 \c \cfg{xhtml-contents-depth-5}{7}
667 \c \cfg{xhtml-head-end}{}
668 \c \cfg{xhtml-body-tag}{<body>}
669 \c \cfg{xhtml-body-start}{}
670 \c \cfg{xhtml-body-end}{}
671 \c \cfg{xhtml-address-start}{}
672 \c \cfg{xhtml-address-end}{}
673 \c \cfg{xhtml-navigation-attributes}{}
675 \c \cfg{xhtml-versionid}{true}
676 \c \cfg{xhtml-suppress-address}{false}
677 \c \cfg{xhtml-author}{}
678 \c \cfg{xhtml-description}{}
680 \c \cfg{xhtml-chapter-numeric}{false}
681 \c \cfg{xhtml-chapter-suffix}{: }
683 \c \cfg{xhtml-section-numeric}{0}{true}
684 \c \cfg{xhtml-section-suffix}{0}{ }
686 \c \cfg{xhtml-section-numeric}{1}{true}
687 \c \cfg{xhtml-section-suffix}{1}{ }
689 \c ... and so on for all section levels below this ...
690 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
692 \H{output-whlp} Windows Help
694 This output format generates data that can be used by the \i{Windows
695 Help} program \cw{WINHELP.EXE}. There are two actual files
696 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
698 Currently, the output is hardcoded to be in the \q{\i{Win1252}}
699 character set. (If anyone knows how character sets are encoded in
700 Windows Help, we'd appreciate help.)
702 The Windows Help output format supports the following configuration
705 \S{output-whlp-file} Output file name
707 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
709 \dd Sets the \i{output file name} in which to store the man page.
710 This directive is implicitly generated if you provide a file name
711 parameter after the command-line option \i\c{--winhelp} (see
712 \k{running-options}).
716 Your output file name should end with \c{.hlp}; if it doesn't,
717 Halibut will append it. Halibut will also generate a contents file
718 (ending in \c{.cnt}) alongside the file name you specify.
722 \S{output-whlp-characters} Configuring the characters used
724 \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
726 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
727 You can specify multiple fallback options. Works exactly like the
728 \cw{\\cfg\{text-bullet\}} directive (see
729 \k{output-text-characters}).
731 \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{\}}]
733 \dd Specifies the quotation marks to use, overriding any
734 \cw{\\cfg\{quotes\}} directive. You can specify multiple
735 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
736 directive (see \k{output-text-characters}).
738 \S{output-whlp-misc} Miscellaneous configuration options
740 \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
742 \dd Sets the text used to describe the help page containing the blurb
743 (see \k{input-blurb}) and table of contents.
746 \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
748 \dd Specifies the \I{suffix text, in section titles}suffix text to
749 be appended to section numbers, before displaying the section title.
750 (Applies to all levels.)
752 \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
754 \dd This text is appended to the number on a \i{numbered list} item,
755 in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
756 \k{output-text-characters}).
758 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
760 \dd This directive defines a Windows \i{Help topic} name in the current
761 section. Topic names can be used by the program invoking
762 \cw{WINHELP.EXE} to jump straight to a particular section. So you
763 can use this for \i{context-sensitive help}.
767 For example, if you used this directive in a particular section:
769 \c \cfg{winhelp-topic}{savingfiles}
771 then a Windows application could invoke Windows Help to jump to that
772 particular section in the help file like this:
774 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
775 \c (DWORD)"JI(`',`savingfiles')");
777 You can use this configuration directive many times, in many
778 different subsections of your document, in order to define a lot of
779 different help contexts which you can use in this way.
783 \S{output-whlp-defaults} Default settings
785 The \i{default settings} for the Windows Help output format are:
787 \c \cfg{winhelp-filename}{output.hlp}
789 \c \cfg{winhelp-bullet}{\u2022}{-}
790 \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
792 \c \cfg{winhelp-contents-titlepage}{Title page}
793 \c \cfg{winhelp-section-suffix}{: }
794 \c \cfg{winhelp-list-suffix}{.}
796 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
798 \H{output-man} Unix \cw{man} pages
800 This output format generates a Unix \i{\cw{man} page}. That is to say,
801 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
804 The available configuration options for this format are as follows:
806 \S{output-man-file} Output file name
808 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
810 \dd Sets the \i{output file name} in which to store the man page.
811 This directive is implicitly generated if you provide a file name
812 parameter after the command-line option \i\c{--man} (see
813 \k{running-options}).
815 \S{output-man-identity} Configuring headers and footers
817 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
819 \dd This directive is used to generate the initial \i{\c{.TH}
820 directive} that appears at the top of a \cw{man} page. It expects to
821 be followed by some number of brace pairs containing text, which will
822 be used in the \i{headers} and \i{footers} of the formatted output.
826 A traditional order for the arguments appears to be:
828 \n The name of the program.
830 \n The (numeric) manual section.
832 \n The date that the \cw{man} page was written.
834 \n The name of any containing suite of which the program is a part.
836 \n The name of the \i{author} of the \cw{man} page.
838 For example, a typical \cw{man} page might contain
840 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
845 \S{output-man-headings} Configuring heading display
847 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
849 \dd If this is set to \c{true}, then \i{section headings} in the
850 \cw{man} page will have their \i{section numbers} displayed as usual. If
851 set to \c{false}, the section numbers will be omitted. (\cw{man}
852 pages traditionally have section names such as \q{SYNOPSIS},
853 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
854 \c{false} is the setting which conforms most closely to normal
857 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
859 \dd If this is set to a number greater than 0, then section headings
860 \e{higher} than the given depth will not be displayed. If it is set
861 to zero, all section headings will be displayed as normal.
865 The point of this is so that you can use the same Halibut input file
866 to generate a quick-reference \cw{man} page for a program, \e{and} to
867 include that \cw{man} page as an appendix in your program's full manual.
868 If you are to include the \cw{man} page as an appendix, then the internal
869 headings within the page will probably need to be at \c{\\H} or
870 \c{\\S} level; therefore, when you format that input file on its own
871 to create the \cw{man} page itself, you will need to have defined a
872 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
873 want to see displayed.
875 Here's an example. You might have a file \c{appendix.but}, which
878 \c \A{manpages} \cw{man} pages for the Foo tool suite
880 \c \cfg{man-mindepth}{2}
882 Then you have a file \c{make-foo.but}, and probably others like it
883 as well, each of which looks something like this:
885 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
888 \c \H{man-foo} \cw{man} page for \c{make-foo}
890 \c \S{man-foo-name} NAME
892 \c \c{make-foo} - create Foo files for the Foo tool suite
894 \c \S{man-foo-synopsis} SYNOPSIS
899 So when you're generating your main manual, you can include
900 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
901 pages you have, and your \cw{man} pages will be formatted neatly as
902 part of an appendix. Then, in a separate run of Halibut, you can
905 \c halibut appendix.but make-foo.but
907 and this will generate a \cw{man} page \c{output.1}, in which the
908 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
909 page for \c{make-foo}} will not be displayed because of the
910 \c{man-mindepth} directive. So the first visible heading in the
911 output \cw{man} page will be \q{NAME}, exactly as a user would
916 \S{output-man-characters} Configuring the characters used
918 \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
920 \dd Specifies what character set the output should be in, similarly to
921 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
923 \# FIXME: you're probably on your own in making sure that it's
924 sensible to output man pages in that charset.
926 \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
928 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
929 You can specify multiple fallback options. Works exactly like the
930 \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
932 \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{\}}]
934 \dd Specifies the quotation marks to use, overriding any
935 \cw{\\cfg\{quotes\}} directive. You can specify multiple
936 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
937 directive (see \k{output-text-characters}).
939 \S{output-man-defaults} Default settings
941 The \i{default settings} for the \cw{man} page output format are:
943 \c \cfg{man-filename}{output.1}
945 \c \cfg{man-identity}{}
947 \c \cfg{man-headnumbers}{false}
948 \c \cfg{man-mindepth}{0}
950 \c \cfg{man-charset}{ASCII}
951 \c \cfg{man-bullet}{\u2022}{o}
952 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
954 \H{output-info} GNU \c{info}
956 This output format generates files which can be used with the \i{GNU
959 There are typically multiple output files: a primary file whose name
960 usually ends in \c{.info}, and one or more subsidiary files whose
961 names have numbers on the end, so that they end in \c{.info-1},
962 \c{.info-2} and so on. Alternatively, this output format can be
963 configured to output a single large file containing the whole
966 The \c{info} output format supports the following configuration
969 \S{output-info-file} Controlling the output filenames
971 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
973 \dd Sets the output file name in which to store the \c{info} file.
974 This directive is implicitly generated if you provide a file name
975 parameter after the command-line option \i\c{--info} (see
976 \k{running-options}).
980 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
981 your output file name to produce any subsidiary files required.
983 Note that \c{info} files refer to their own names internally, so
984 these files cannot be \I{renaming \c{info} files}renamed after
985 creation and remain useful.
989 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
991 \dd Sets the preferred \i{maximum file size} for each subsidiary
992 file. As a special case, if you set this to zero, there will be no
993 subsidiary files and the whole document will be placed in a single
994 self-contained output file. (However, note that this file can still
995 not be renamed usefully.)
999 The preferred maximum file size is only a guideline. Halibut may be
1000 forced to exceed it if a single section of the document is larger
1001 than the maximum size (since individual \c{info} nodes may not be
1002 split between files).
1006 \S{output-info-dimensions} Indentation and line width
1008 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
1010 \dd Sets the \I{text width}width of the main part of the document,
1011 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
1012 directive (see \k{output-text-dimensions}).
1014 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
1016 \dd Specifies the extra indentation for \I{code paragraphs,
1017 indentation} code paragraphs. Works exactly like the
1018 \cw{\\cfg\{text-indent-code\}} directive (see
1019 \k{output-text-dimensions}).
1021 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
1023 \dd Specifies how much horizontal space to leave in the index node
1024 for the text of \i{index terms}, before displaying the sections the
1027 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
1029 \dd Specifies the extra indentation before the bullet or number in a
1030 \I{bulletted list, indentation}\I{numbered list, indentation}list
1031 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
1032 directive (see \k{output-text-dimensions}).
1034 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
1036 \dd Specifies the additional indentation before the body of a list
1037 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
1038 directive (see \k{output-text-dimensions}).
1040 \S{output-info-headings} Configuring heading display
1042 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
1044 \dd Specifies the suffix text to be appended to each section number
1045 before displaying the section title. For example, if you set this to
1046 \cq{:\_}, then a typical section title might look something like
1047 \q{Section 3.1: Something Like This}.
1049 \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1051 \dd Specifies the text to be used to underline section titles. Works
1052 very much like the \cw{\\cfg\{text-chapter-underline\}} directive
1053 (see \k{output-text-headings}). You can specify more than one
1054 option, and Halibut will choose the first one supported by the
1057 \S{output-info-characters} Controlling the characters used
1059 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
1061 \dd Specifies what character set the output should be in, similarly to
1062 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1064 \# FIXME: if you try sufficiently hard, you can probably find an
1065 output encoding that will break the info format by trampling on its
1066 special characters. So either don't do that, or tell us what we should
1069 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1071 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1072 You can specify multiple fallback options. Works exactly like the
1073 \cw{\\cfg\{text-bullet\}} directive (see
1074 \k{output-text-characters}).
1076 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1078 \dd Specifies the text used to draw \i{horizontal rules}. You can
1079 specify multiple fallback options. Works exactly like the
1080 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
1082 \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{\}}]
1084 \dd Specifies the quotation marks to use, overriding any
1085 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1086 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1087 directive (see \k{output-text-characters}).
1089 \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{\}}]
1091 \dd Specifies how to display emphasised text. You can specify
1092 multiple fallback options. Works exactly like the
1093 \cw{\\cfg\{text-emphasis\}} directive (see
1094 \k{output-text-characters}).
1096 \S{output-info-misc} Miscellaneous configuration options
1098 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
1100 \dd Specifies the text to append to the item numbers in a
1101 \i{numbered list}. Works exactly like the
1102 \cw{\\cfg\{text-list-suffix\}} directive (see
1103 \k{output-text-misc}).
1105 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
1106 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
1108 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
1109 header of the Info file. This mechanism is used to automatically
1110 generate the \i{\c{dir} file} at the root of a Unix system's
1111 \c{info} collection.
1115 The parameters to this directive are:
1119 \dd Specifies the section of the \c{dir} file in which you want your
1120 document referenced. For example, \q{Development}, or \q{Games}, or
1125 \dd Specifies a short name for the directory entry, which will
1126 appear at the start of the menu line.
1130 \dd Specifies a long name for the directory entry, which will appear
1131 at the end of the menu line.
1135 \dd This parameter is optional. If it is present, then the directory
1136 entry will cause a jump to a particular subsection of your document,
1137 rather than starting at the top. The subsection will be the one
1138 referred to by the given keyword (see \k{input-sections} for details
1139 about assigning keywords to document sections).
1141 For example, in a document describing many game programs, the
1142 configuration directive
1144 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1147 might produce text in the \c{dir} file looking something like this:
1150 \c * Chess: (mygames)Chapter 3. Electronic chess game
1152 if the output file were called \c{mygames.info} and the keyword
1153 \c{chess} had been used to define Chapter 3 of the document.
1157 \S{output-info-defaults} Default settings
1159 The \i{default settings} for the \c{info} output format are:
1161 \c \cfg{info-filename}{output.info}
1162 \c \cfg{info-max-file-size}{65536}
1164 \c \cfg{info-width}{70}
1165 \c \cfg{info-indent-code}{2}
1166 \c \cfg{info-index-width}{40}
1167 \c \cfg{info-list-indent}{1}
1168 \c \cfg{info-listitem-indent}{3}
1170 \c \cfg{info-section-suffix}{: }
1171 \c \cfg{info-underline}{\u203e}{-}
1173 \c \cfg{info-charset}{ASCII}
1174 \c \cfg{info-bullet}{\u2022}{-}
1175 \c \cfg{info-rule}{\u2500}{-}
1176 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1177 \c \cfg{info-emphasis}{_}{_}
1179 \c \cfg{info-list-suffix}{.}
1181 and no \cw{\\cfg\{info-dir-entry\}} directives.
1183 \H{output-paper} Paper formats
1185 These output formats (currently PostScript and PDF) generate printable
1186 manuals. As such, they share a number of configuration directives.
1188 \S{output-ps} \i{PostScript}
1190 This output format generates a printable manual in PostScript format.
1192 There is one configuration option specific to PostScript:
1194 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1196 \dd Sets the \i{output file name} in which to store the PostScript
1197 file. This directive is implicitly generated if you provide a file
1198 name parameter after the command-line option \i\c{--ps} (see
1199 \k{running-options}).
1201 The \i{default settings} for the PostScript output format are:
1203 \c \cfg{ps-filename}{output.ps}
1205 \S{output-pdf} \i{PDF}
1207 This output format generates a printable manual in PDF format. This
1208 should look exactly identical to the PostScript output (see
1209 \k{output-ps}), but also uses some PDF interactive features to
1210 provide an outline of all the document's sections and clickable
1211 cross-references between sections.
1213 There is one configuration option specific to PDF:
1215 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1217 \dd Sets the \i{output file name} in which to store the PDF file.
1218 This directive is implicitly generated if you provide a file name
1219 parameter after the command-line option \i\c{--pdf} (see
1220 \k{running-options}).
1222 The \i{default settings} for the PDF output format are:
1224 \c \cfg{pdf-filename}{output.pdf}
1226 \S{output-paper-dimensions} Configuring layout and \i{measurements}
1228 All measurements are in PostScript \i{points} (72 points to the inch).
1230 \S2{output-paper-pagesize} Page properties
1232 \dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
1234 \dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
1236 \dd Specify the absolute limits of the paper.
1238 \dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
1240 \dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
1242 \dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
1244 \dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
1246 \dd Specify the margins. Most text appears within these margins,
1251 \b Section numbers, which appear in the left margin.
1253 \b The footer (containing page numbers), which appears in the bottom
1258 \S2{output-paper-line} Vertical spacing
1260 \dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
1262 \dd Specifies the amount of space between lines of text within a
1263 paragraph. (So, if the font size is 12pt and there is 2pt of leading,
1264 there will be 14pt between successive baselines.)
1266 \dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
1268 \dd Specifies the amount of vertical space between paragraphs. (The
1269 vertical space between paragraphs does \e{not} include
1270 \c{paper-base-leading}.)
1272 \S2{output-paper-indentation} Indentation
1274 \dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
1276 \dd Specifies the indentation of the bullet or number in a
1277 \I{bulletted list, indentation}bulletted or \I{numbered list,
1278 indentation}numbers \I{list, indentation}list, similarly to
1279 \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
1281 \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
1283 \dd Specifies the \e{extra} indentation for the body of a list item,
1284 over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
1286 \# FIXME: doesn't actually work, AFAICT.
1288 \dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
1290 \dd Specifies the amount of indentation for a level of quoting. Used
1291 for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
1292 (see \k{input-code}).
1294 \S2{output-paper-headings} Headings
1296 \dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
1298 \dd Specifies the space between the top margin and the top of the
1299 chapter heading. (Each chapter begins on a new page.)
1301 \dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
1303 \dd Specifies the vertical thickness of the black rule under chapter
1306 \dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
1308 \dd Specifies the distance between the base of the chapter heading and
1309 the \e{base} of the underlying rule.
1311 \dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
1313 \dd Specifies the distance between the left margin and the \e{right}
1314 of section numbers (which are in the left margin).
1316 \S2{output-paper-index} Contents and index
1318 \dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}}
1320 \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
1322 \# FIXME: I do not know what dees one does. (I couldn't get either of
1323 them to do anything obvious, although the source indicates they should
1326 \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
1328 \dd Specifies the horizontal spacing between dots in \i\e{leaders}
1329 (the dotted lines that appear between section headings and page
1330 numbers in the table of contents).
1332 \dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
1334 \dd Specifies the distance between the bottom margin and the \e{base}
1335 of the footer (which contains page numbers).
1337 \dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
1339 \dd Specifies the number of columns the index should be divided into.
1341 \# FIXME: with this set to 1, the right-alignment of some index entry
1342 page numbers in the Halibut manual is decidedly wonky.
1344 \dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
1346 \dd Specifies the amount of \I{gutter} horizontal space between index
1349 \dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
1351 \dd Specifies the minimum allowable horizontal space between an index
1352 entry and its page number. If the gap is smaller, the page number is
1353 moved to the next line.
1355 \S2{output-paper-fonts} Fonts
1357 \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
1359 \dd Specifies the font size of body text.
1361 \# FIXME: actually, this doesn't appear to do anything at all - most
1362 font sizes are still hardcoded.
1364 \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
1366 \dd Specifies the font size to use for page numbers.
1368 \S2{output-paper-misc} Miscellaneous
1370 \dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
1372 \dd Specifies the vertical thickness of the rule produced by the
1373 \cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
1374 reserved for thicker rules.)
1376 \S{output-paper-characters} Configuring the characters used
1378 \dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1380 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1381 You can specify multiple fallback options. Works exactly like the
1382 \cw{\\cfg\{text-bullet\}} directive (see
1383 \k{output-text-characters}).
1385 \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{\}}]
1387 \dd Specifies the quotation marks to use, overriding any
1388 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1389 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1390 directive (see \k{output-text-characters}).
1392 \S{output-paper-defaults} Default settings for paper formats
1394 The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
1397 \c \cfg{paper-page-width}{595}
1398 \c \cfg{paper-page-height}{841}
1400 \c \cfg{paper-left-margin}{72}
1401 \c \cfg{paper-top-margin}{72}
1402 \c \cfg{paper-right-margin}{72}
1403 \c \cfg{paper-bottom-margin}{108}
1405 \c \cfg{paper-base-leading}{1}
1406 \c \cfg{paper-base-para-spacing}{10}
1408 \c \cfg{paper-list-indent}{6}
1409 \c \cfg{paper-listitem-indent}{18}
1410 \c \cfg{paper-quote-indent}{18}
1412 \c \cfg{paper-chapter-top-space}{72}
1413 \c \cfg{paper-chapter-underline-thickness}{3}
1414 \c \cfg{paper-chapter-underline-depth}{14}
1415 \c \cfg{paper-sect-num-left-space}{12}
1417 \c \cfg{paper-contents-index-step}{24}
1418 \c \cfg{paper-contents-margin}{84}
1419 \c \cfg{paper-leader-separation}{12}
1420 \c \cfg{paper-footer-distance}{32}
1421 \c \cfg{paper-index-columns}{2}
1422 \c \cfg{paper-index-gutter}{36}
1423 \c \cfg{paper-index-minsep}{18}
1425 \c \cfg{paper-base-font-size}{12}
1426 \c \cfg{paper-pagenum-font-size}{12}
1428 \c \cfg{paper-rule-thickness}{1}
1430 \c \cfg{paper-bullet}{\u2022}{-}
1431 \c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}