1 \C{output} Halibut output formats
3 This chapter describes each of Halibut's current \i{output formats}.
4 It gives some general information about the format, and also
5 describes all the \i{configuration directives} which are specific to
8 \H{output-text} Plain text
10 This output format generates the document as a single \i{plain text}
11 file. No table of contents or index is generated.
13 The precise formatting of the text file can be controlled by a
14 variety of configuration directives. They are listed in the
15 following subsections.
17 \S{output-text-file} Output file name
19 \dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}}
21 \dd Sets the \i{output file name} in which to store the text file.
22 This directive is implicitly generated if you provide a file name
23 parameter after the command-line option \i\c{--text} (see
26 \S{output-text-dimensions} Indentation and line width
28 This section describes the configuration directives which control
29 the \i{horizontal dimensions} of the output text file: how much
30 paragraphs are indented by and how long the lines are.
32 \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
34 \dd Sets the \I{text width}width of the main part of the document,
35 in characters. This width will be used for wrapping paragraphs and
36 for centring titles (if you have asked for titles to be centred -
37 see \k{output-text-headings}). This width does \e{not} include the
38 left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
39 indent of 8 and a width of 64, your maximum output line length will
42 \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
44 \dd Sets the left \i{indentation} for the document. If you set this
45 to zero, your document will look like an ordinary text file as
46 someone with a text editor might have written it; if you set it
47 above zero, the text file will have a \i{margin} down the left in
48 the style of some printed manuals, and you can then configure the
49 section numbers to appear in this margin (see
50 \k{output-text-headings}).
52 \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
54 \dd Specifies how many extra characters of indentation (on top of
55 the normal left indent) should be given to \I{code paragraphs,
56 indentation} code paragraphs.
58 \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
60 \dd Specifies how many extra spaces should be used to indent the
61 bullet or number in a \I{bulletted list, indentation}bulletted or
62 \I{numbered list, indentation}numbered \I{list, indentation}list.
63 The actual body of the list item will be indented by this much
64 \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}.
66 \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
68 \dd Specifies how many extra spaces should be used to indent the
69 body of a list item, over and above the number configured in
70 \cw{\\cfg\{text-list-indent\}}.
72 \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
74 \dd When this is set to \c{true}, the document \i{preamble} (i.e. any
75 paragraphs appearing before the first chapter heading) will be
76 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
77 this setting is \c{false}, the document preamble will not be
78 indented at all from the left margin.
80 \S{output-text-headings} \ii{Configuring heading display}
82 The directives in this section allow you to configure the appearance
83 of the title, chapter and section headings in your text file.
85 Several of the directives listed below specify the \i{alignment} of
86 a heading. These alignment options have three possible values:
90 \dd Align the heading to the very left of the text file (column zero).
94 \dd Align the section title to the left of the main display region
95 (in other words, indented to the level specified by
96 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
97 left of that (so that it goes in the margin if there is room).
101 \dd Centre the heading.
103 Also, several of the directives below specify how a title should be
104 \I{underlining}underlined. The parameter to one of these directives
105 should be either blank (\cw{\{\}}) or a piece of text which will be
106 repeated to produce the underline. So you might want to specify, for
107 example, \cw{\\text-title-underline\{=\}} but
108 \cw{\\text-chapter-underline\{\-\}}.
110 You can also specify more than one underline setting, and Halibut
111 will choose the first one that the output character set supports.
112 So, for example, you could write
113 \cw{\\text-chapter-underline\{\\u203e\}\{\-\}}, and Halibut would use
114 the Unicode \q{OVERLINE} character where possible and fall back to
115 the ASCII minus sign otherwise.
117 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
119 \dd Specifies the alignment of the overall document title: \c{left},
120 \c{leftplus} or \c{centre}.
122 \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}}
124 \dd Specifies how the overall document title should be underlined.
126 \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
128 \dd Specifies the alignment of chapter and appendix headings.
130 \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}}
132 \dd Specifies how chapter and appendix headings should be underlined.
134 \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
136 \dd If this is set to \c{true}, then chapter headings will not
137 contain the word \q{Chapter} (or whatever other word you have
138 defined in its place - see \k{input-sections} and \k{input-config});
139 they will just contain the chapter \e{number}, followed by the
140 chapter title. If you set this to \c{false}, chapter headings will
141 be prefixed by \q{Chapter} or equivalent.
143 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
145 \dd This specifies the suffix text to be appended to the chapter
146 number, before displaying the chapter title. For example, if you set
147 this to \q{\cw{:\_}}, then the chapter title might look something
148 like \q{Chapter 2: Doing Things}.
150 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
152 \dd Specifies the alignment of section headings at a particular
153 level. The \e{level} parameter specifies which level of section
154 headings you want to affect: 0 means first-level headings (\c{\\H}),
155 1 means second-level headings (\c{\\S}), 2 means the level below
156 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
157 just like the other alignment directives listed above.
159 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}}
161 \dd Specifies how to underline section headings at a particular level.
163 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
165 \dd Specifies whether section headings at a particular level should
166 contain the word \q{Section} or equivalent (if \c{false}), or should
167 be numeric only (if \c{true}).
169 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
171 \dd Specifies the \I{suffix text, in section titles}suffix text to
172 be appended to section numbers at a particular level, before
173 displaying the section title.
175 \S{output-text-characters} Configuring the characters used
177 \dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}}
179 \dd This tells Halibut what \i{character set} the output should be
180 in. Any Unicode characters representable in this set will be output
181 verbatim; any other characters will not be output and their
182 \i{fallback text} (if any) will be used instead.
186 The character set names are the same as for
187 \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike
188 \cw{\\cfg\{input-charset\}}, this directive affects the \e{entire}
189 output; it's not possible to switch encodings halfway through.
193 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
195 \dd This specifies the text which should be used as the \i{bullet}
196 in bulletted lists. It can be one character
197 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
198 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
202 Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple
203 possible options after this command, and Halibut will choose the first one
204 which the output character set supports. For example, you might write
205 \cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case
206 Halibut would use the Unicode \q{BULLET} character where possible,
207 fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available,
208 and resort to the ASCII asterisk if all else failed.
212 \dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}]
214 \dd This specifies the text which should be used for drawing
215 \i{horizontal rules} (generated by \i\c{\\rule}; see
216 \k{input-rule}). It can be one character, or more than one. The
217 string you specify will be repeated to reach the required width, so
218 you can specify something like \q{\cw{-=}} to get a rule that looks
223 Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback
224 options in this command.
228 \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{\}}]
230 \dd This specifies a set of quote characters for the text backend,
231 overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax
232 (see \k{input-config}).
236 In this backend, these quotes will also be used to mark text enclosed
237 in the \c{\\c} command (see \k{input-code}).
241 \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{\}}]
243 \dd This specifies the characters which should be used to surround
244 emphasised text (written using the \c{\\e} command; see
249 You should separately specify the start-emphasis and end-emphasis
250 text, each of which can be more than one character if you want.
251 Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs
252 of fallback options in this command, and Halibut will always use a
257 \S{output-text-misc} Miscellaneous configuration options
259 \dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}}
261 \dd This text is appended to the number on a \i{numbered list} item
262 (see \k{input-list-number}). So if you want to label your lists as
263 \q{1)}, \q{2)} and so on, then you would write
264 \cw{\\cfg\{text-list-suffix\}\{)\}}.
266 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
268 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
269 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
270 included at the bottom of the text file. If it is set to \c{false},
271 they will be omitted completely.
273 \# FIXME: code indentation is configurable, therefore \quote
274 \# indentation probably ought to be as well.
276 \# FIXME: text-indent-* should be consistently named.
278 \S{output-text-defaults} Default settings
280 The \i{default settings} for Halibut's plain text output format are:
282 \c \cfg{text-filename}{output.txt}
284 \c \cfg{text-width}{68}
285 \c \cfg{text-indent}{7}
286 \c \cfg{text-indent-code}{2}
287 \c \cfg{text-list-indent}{1}
288 \c \cfg{text-listitem-indent}{3}
289 \c \cfg{text-indent-preamble}{false}
291 \c \cfg{text-title-align}{centre}
292 \c \cfg{text-title-underline}{\u2550}{=}
294 \c \cfg{text-chapter-align}{left}
295 \c \cfg{text-chapter-underline}{\u203e}{-}
296 \c \cfg{text-chapter-numeric}{false}
297 \c \cfg{text-chapter-suffix}{: }
299 \c \cfg{text-section-align}{0}{leftplus}
300 \c \cfg{text-section-underline}{0}{}
301 \c \cfg{text-section-numeric}{0}{true}
302 \c \cfg{text-section-suffix}{0}{ }
304 \c \cfg{text-section-align}{1}{leftplus}
305 \c \cfg{text-section-underline}{1}{}
306 \c \cfg{text-section-numeric}{1}{true}
307 \c \cfg{text-section-suffix}{1}{ }
309 \c ... and so on for all section levels below this ...
310 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
312 \c \cfg{text-charset}{ASCII}
313 \c \cfg{text-bullet}{\u2022}{-}
314 \c \cfg{text-rule}{\u2500}{-}
315 \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'}
316 \c \cfg{text-emphasis}{_}{_}
318 \c \cfg{text-list-suffix}{.}
319 \c \cfg{text-versionid}{true}
323 \# FIXME: this probably needs major revision due to the new HTML
326 This output format generates an \i{HTML} version of the document. By
327 default, this will be in multiple files, starting with
328 \c{Contents.html} and splitting the document into files by chapter
329 and/or subsection. You can configure precisely how the text is split
330 between HTML files using the configuration commands described in
331 this section. In particular, you can configure Halibut to output one
332 single HTML file instead of multiple ones.
334 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
335 which is why all of the configuration directives start with the word
336 \c{xhtml} rather than \c{html}.
338 \S{output-html-file} Controlling the output file names
340 \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
342 \dd Sets the \i{output file name} in which to store the top-level
343 contents page. Since this is the first page a user ought to see when
344 beginning to read the document, a good choice in many cases might be
345 \c{index.html} (although this is not the default, for historical
348 \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
350 \dd Sets the file name in which to store the document's index.
352 \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
354 \dd Provides a \i{template} to be used when constructing the file
355 names of each chapter or section of the document. This template
356 should contain at least one \i\e{formatting command}, in the form of
357 a per cent sign followed by a letter. (If you need a literal per
358 cent sign, you can write \c{%%}.)
362 The formatting commands used in this template are:
364 \dt \I{%N-upper}\c{%N}
366 \dd Expands to the visible title of the section, with white space
367 removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
368 Fish}}, this formatting command would expand to
369 \q{\cw{CatchingFish}}.
373 \dd Expands to the type and number of the section, without white
374 space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
375 section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
376 If the section has no number (an unnumbered chapter created using
377 \c{\\U}), this directive falls back to doing the same thing as
382 \dd Expands to the bare number of the section. So in chapter 1 this
383 would expand to \q{\cw{1}}; in section A.4.3 it would expand to
384 \q{\cw{A.4.3}}, and so on. If the section has no number (an
385 unnumbered chapter created using \c{\\U}), this directive falls back
386 to doing the same thing as \c{%N}.
390 \dd Expands to the internal keyword specified in the section title.
391 So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
392 formatting command would expand to \q{\cw{fish}}. If the section has
393 no keyword (an unnumbered chapter created using \c{\\U}), this
394 directive falls back to doing the same thing as \c{%N}.
396 These formatting directives can also be used in the
397 \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
398 \k{output-html-misc}).
402 \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
404 \dd Sets the file name in which to store the entire document, if
405 Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
406 produce a single self-contained file. Both this directive \e{and}
407 \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
408 provide a file name parameter after the command-line option
409 \i\c{--html} (see \k{running-options}).
411 \S{output-html-split} Controlling the splitting into HTML files
413 By default, the HTML output from Halibut is split into multiple
414 files. Each file typically contains a single chapter or section and
415 everything below it, unless subsections of that chapter are
416 themselves split off into further files.
418 Most files also contain a contents section, giving hyperlinks to the
419 sections in the file and/or the sections below it.
421 The configuration directives listed below allow you to configure the
422 splitting into files, and the details of the contents sections.
424 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
426 \dd This setting indicates the depth of section which should be
427 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
428 you set it to 1, for example, then every chapter will be given its
429 own HTML file, plus a top-level \i{contents file}. If you set this
430 to 2, then each chapter \e{and} each \c{\\H} section will have a
431 file, and the chapter files will mostly just contain links to their
436 If you set this option to zero, then the whole document will appear
437 in a single file. If you do this, Halibut will call that file
438 \i\c{Manual.html} instead of \i\c{Contents.html}.
440 This option is automatically set to zero if you provide a file name
441 parameter after the command-line option \i\c{--html} (see
442 \k{running-options}), because you have specified a single file name
443 and so Halibut assumes you want the whole document to be placed in
448 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
450 \dd This directive allows you to specify how \I{depth of
451 contents}deep the contents section in a particular file should go.
455 The \e{level} parameter indicates which level of contents section
456 you are dealing with. 0 denotes the main contents section in the
457 topmost file \c{Contents.html}; 1 denotes a contents section in a
458 chapter file; 2 is a contents section in a file containing a \c{\\H}
459 heading, and so on. Currently you can't go below level 5 (which
460 corresponds to a \c{\\S3} heading).
462 The \e{depth} parameter indicates the maximum depth of heading which
463 will be shown in this contents section. Again, 1 denotes a chapter,
464 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
466 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
467 Halibut to put contents links in chapter files for all sections down
468 to \c{\\S} level, but not to go into any more detail than that.
472 \# FIXME: this is utterly ghastly. For a start, it should include
473 \# the level as a separate argument, like the text section config
474 \# directives. Secondly, it shouldn't be limited in depth!
476 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
478 \dd If you set this to \c{true}, then each leaf file will contain
479 its own contents section which summarises the text within it.
481 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
483 \dd Contents sections in leaf files are not output at all if they
484 contain very few entries (on the assumption that it just isn't worth
485 bothering). This directive configures the minimum number of entries
486 required in a leaf contents section to make Halibut bother
487 generating it at all.
489 \S{output-html-html} Including pieces of your own HTML
491 The directives in this section allow you to supply pieces of
492 \I{HTML}\i{verbatim HTML} code, which will be included in various
493 parts of the output files.
495 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
497 \dd The text you provide in this directive is placed at the end of
498 the \i\cw{<HEAD>} section of each output HTML file. So this is a
499 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
501 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
503 \dd The text you provide in this directive is used in place of the
504 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
505 \i{background colour}, for example, you could write
506 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
508 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
510 \dd The text you provide in this directive is placed at the
511 beginning of the \i\cw{<BODY>} section of each output HTML file. So
512 if you intend your HTML files to be part of a web site with a
513 standard \i{house style}, and the style needs a \i{header} at the
514 top of every page, this is where you can add that header.
516 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
518 \dd The text you provide in this directive is placed at the end of
519 the \i\cw{<BODY>} section of each output HTML file. So if you intend
520 your HTML files to be part of a web site with a standard \i{house
521 style}, and the style needs a \i{footer} at the bottom of every
522 page, this is where you can add that footer.
524 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
526 \dd The text you provide in this directive is placed at the
527 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
528 output HTML file. This might be a good place to put authors'
529 \i{contact details}, for example.
531 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
533 \dd The text you provide in this directive is placed at the end of
534 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
535 after the version IDs (if present).
537 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
539 \dd The text you provide in this directive is included inside the
540 \cw{<P>} tag containing the \i{navigation links} at the top of each
541 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
542 wanted the navigation links to have a particular CSS style, you
544 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
545 navigation-links paragraph would then begin with the tag \cw{<p
548 \S{output-html-headings} \ii{Configuring heading display}
550 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
552 \dd If this is set to \c{true}, then chapter headings will not
553 contain the word \q{Chapter} (or whatever other word you have
554 defined in its place - see \k{input-sections} and \k{input-config});
555 they will just contain the chapter \e{number}, followed by the
556 chapter title. If you set this to \c{false}, chapter headings will
557 be prefixed by \q{Chapter} or equivalent.
559 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
561 \dd This specifies the suffix text to be appended to the chapter
562 number, before displaying the chapter title. For example, if you set
563 this to \q{\cw{:\_}}, then the chapter title might look something
564 like \q{Chapter 2: Doing Things}.
566 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
568 \dd Specifies whether section headings at a particular level should
569 contain the word \q{Section} or equivalent (if \c{false}), or should
570 be numeric only (if \c{true}). The \e{level} parameter specifies
571 which level of section headings you want to affect: 0 means
572 first-level headings (\c{\\H}), 1 means second-level headings
573 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
575 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
577 \dd Specifies the suffix text to be appended to section numbers at a
578 particular level, before displaying the section title.
580 \S{output-html-misc} Miscellaneous options
582 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
584 \dd This directive lets you specify a \i{template}, with exactly the
585 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
586 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
587 NAME="...">}) used to allow URLs to refer to specific sections
588 within a particular HTML file. So if you set this to \q{\cw{%k}},
589 for example, then each individual section in your document will be
590 addressable by means of a URL ending in a \c{#} followed by your
591 internal section keyword.
593 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
595 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
596 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
597 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
598 file. If it is set to \c{false}, they will be omitted completely.
600 \# FIXME: surely it would be better to include them in HTML
601 \# comments? The only question is whether they should be _visible_.
603 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
605 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
606 bottom of each HTML file will be omitted completely. (This will
607 therefore also cause \i{version IDs} not to be included.)
609 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
611 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
612 name="author">} tag in the output HTML files, so that browsers which
613 support this can automatically identify the \i{author} of the document.
615 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
617 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
618 name="description">} tag in the output HTML files, so that browsers
619 which support this can easily pick out a brief \I{description, of
620 document}description of the document.
622 \S{output-html-defaults} Default settings
624 The \i{default settings} for Halibut's HTML output format are:
626 \c \cfg{xhtml-contents-filename}{Contents.html}
627 \c \cfg{xhtml-index-filename}{IndexPage.html}
628 \c \cfg{xhtml-template-filename}{%n.html}
629 \c \cfg{xhtml-single-filename}{Manual.html}
630 \c \cfg{xhtml-template-fragment}{%b}
632 \c \cfg{xhtml-leaf-level}{2}
633 \c \cfg{xhtml-leaf-contains-contents}{false}
634 \c \cfg{xhtml-leaf-smallest-contents}{4}
635 \c \cfg{xhtml-contents-depth-0}{2}
636 \c \cfg{xhtml-contents-depth-1}{3}
637 \c \cfg{xhtml-contents-depth-2}{4}
638 \c \cfg{xhtml-contents-depth-3}{5}
639 \c \cfg{xhtml-contents-depth-4}{6}
640 \c \cfg{xhtml-contents-depth-5}{7}
642 \c \cfg{xhtml-head-end}{}
643 \c \cfg{xhtml-body-tag}{<body>}
644 \c \cfg{xhtml-body-start}{}
645 \c \cfg{xhtml-body-end}{}
646 \c \cfg{xhtml-address-start}{}
647 \c \cfg{xhtml-address-end}{}
648 \c \cfg{xhtml-navigation-attributes}{}
650 \c \cfg{xhtml-versionid}{true}
651 \c \cfg{xhtml-suppress-address}{false}
652 \c \cfg{xhtml-author}{}
653 \c \cfg{xhtml-description}{}
655 \c \cfg{xhtml-chapter-numeric}{false}
656 \c \cfg{xhtml-chapter-suffix}{: }
658 \c \cfg{xhtml-section-numeric}{0}{true}
659 \c \cfg{xhtml-section-suffix}{0}{ }
661 \c \cfg{xhtml-section-numeric}{1}{true}
662 \c \cfg{xhtml-section-suffix}{1}{ }
664 \c ... and so on for all section levels below this ...
665 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
667 \H{output-whlp} Windows Help
669 This output format generates data that can be used by the \i{Windows
670 Help} program \cw{WINHELP.EXE}. There are two actual files
671 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
673 Currently, the output is harcoded to be in the \q{\i{Win1252}}
676 The Windows Help output format supports the following configuration
679 \S{output-whlp-file} Output file name
681 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
683 \dd Sets the \i{output file name} in which to store the man page.
684 This directive is implicitly generated if you provide a file name
685 parameter after the command-line option \i\c{--winhelp} (see
686 \k{running-options}).
690 Your output file name should end with \c{.hlp}; if it doesn't,
691 Halibut will append it. Halibut will also generate a contents file
692 (ending in \c{.cnt}) alongside the file name you specify.
696 \S{output-whlp-characters} Configuring the characters used
698 \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
700 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
701 You can specify multiple fallback options. Works exactly like the
702 \cw{\\cfg\{text-bullet\}} directive (see
703 \k{output-text-characters}).
705 \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{\}}]
707 \dd Specifies the quotation marks to use, overriding any
708 \cw{\\cfg\{quotes\}} directive. You can specify multiple
709 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
710 directive (see \k{output-text-characters}).
712 \S{output-whlp-misc} Miscellaneous configuration options
714 \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
716 \dd Sets the text used to describe the help page containing the blurb
717 (see \k{input-blurb}) and table of contents.
720 \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
722 \dd Specifies the \I{suffix text, in section titles}suffix text to
723 be appended to section numbers, before displaying the section title.
724 (Applies to all levels.)
726 \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
728 \dd This text is appended to the number on a \i{numbered list} item,
729 in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
730 \k{output-text-characters}).
732 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
734 \dd This directive defines a Windows \i{Help topic} name in the current
735 section. Topic names can be used by the program invoking
736 \cw{WINHELP.EXE} to jump straight to a particular section. So you
737 can use this for \i{context-sensitive help}.
741 For example, if you used this directive in a particular section:
743 \c \cfg{winhelp-topic}{savingfiles}
745 then a Windows application could invoke Windows Help to jump to that
746 particular section in the help file like this:
748 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
749 \c (DWORD)"JI(`',`savingfiles')");
751 You can use this configuration directive many times, in many
752 different subsections of your document, in order to define a lot of
753 different help contexts which you can use in this way.
757 \S{output-whlp-defaults} Default settings
759 The \i{default settings} for the Windows Help output format are:
761 \c \cfg{winhelp-filename}{output.hlp}
763 \c \cfg{winhelp-bullet}{\u2022}{-}
764 \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
766 \c \cfg{winhelp-contents-titlepage}{Title page}
767 \c \cfg{winhelp-section-suffix}{: }
768 \c \cfg{winhelp-list-suffix}{.}
770 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
772 \H{output-man} Unix \cw{man} pages
774 This output format generates a Unix \i{\cw{man} page}. That is to say,
775 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
778 The available configuration options for this format are as follows:
780 \S{output-man-file} Output file name
782 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
784 \dd Sets the \i{output file name} in which to store the man page.
785 This directive is implicitly generated if you provide a file name
786 parameter after the command-line option \i\c{--man} (see
787 \k{running-options}).
789 \S{output-man-identity} Configuring headers and footers
791 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
793 \dd This directive is used to generate the initial \i{\c{.TH}
794 directive} that appears at the top of a \cw{man} page. It expects to
795 be followed by some number of brace pairs containing text, which will
796 be used in the \i{headers} and \i{footers} of the formatted output.
800 A traditional order for the arguments appears to be:
802 \n The name of the program.
804 \n The (numeric) manual section.
806 \n The date that the \cw{man} page was written.
808 \n The name of any containing suite of which the program is a part.
810 \n The name of the \i{author} of the \cw{man} page.
812 For example, a typical \cw{man} page might contain
814 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
819 \S{output-man-headings} Configuring heading display
821 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
823 \dd If this is set to \c{true}, then \i{section headings} in the
824 \cw{man} page will have their \i{section numbers} displayed as usual. If
825 set to \c{false}, the section numbers will be omitted. (\cw{man}
826 pages traditionally have section names such as \q{SYNOPSIS},
827 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
828 \c{false} is the setting which conforms most closely to normal
831 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
833 \dd If this is set to a number greater than 0, then section headings
834 \e{higher} than the given depth will not be displayed. If it is set
835 to zero, all section headings will be displayed as normal.
839 The point of this is so that you can use the same Halibut input file
840 to generate a quick-reference \cw{man} page for a program, \e{and} to
841 include that \cw{man} page as an appendix in your program's full manual.
842 If you are to include the \cw{man} page as an appendix, then the internal
843 headings within the page will probably need to be at \c{\\H} or
844 \c{\\S} level; therefore, when you format that input file on its own
845 to create the \cw{man} page itself, you will need to have defined a
846 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
847 want to see displayed.
849 Here's an example. You might have a file \c{appendix.but}, which
852 \c \A{manpages} \cw{man} pages for the Foo tool suite
854 \c \cfg{man-mindepth}{2}
856 Then you have a file \c{make-foo.but}, and probably others like it
857 as well, each of which looks something like this:
859 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
862 \c \H{man-foo} \cw{man} page for \c{make-foo}
864 \c \S{man-foo-name} NAME
866 \c \c{make-foo} - create Foo files for the Foo tool suite
868 \c \S{man-foo-synopsis} SYNOPSIS
873 So when you're generating your main manual, you can include
874 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
875 pages you have, and your \cw{man} pages will be formatted neatly as
876 part of an appendix. Then, in a separate run of Halibut, you can
879 \c halibut appendix.but make-foo.but
881 and this will generate a \cw{man} page \c{output.1}, in which the
882 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
883 page for \c{make-foo}} will not be displayed because of the
884 \c{man-mindepth} directive. So the first visible heading in the
885 output \cw{man} page will be \q{NAME}, exactly as a user would
890 \S{output-man-characters} Configuring the characters used
892 \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
894 \dd Specifies what character set the output should be in, similarly to
895 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
897 \# FIXME: you're probably on your own in making sure that it's
898 sensible to output man pages in that charset.
900 \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
902 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
903 You can specify multiple fallback options. Works exactly like the
904 \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
906 \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{\}}]
908 \dd Specifies the quotation marks to use, overriding any
909 \cw{\\cfg\{quotes\}} directive. You can specify multiple
910 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
911 directive (see \k{output-text-characters}).
913 \S{output-man-defaults} Default settings
915 The \i{default settings} for the \cw{man} page output format are:
917 \c \cfg{man-filename}{output.1}
919 \c \cfg{man-identity}{}
921 \c \cfg{man-headnumbers}{false}
922 \c \cfg{man-mindepth}{0}
924 \c \cfg{man-charset}{ASCII}
925 \c \cfg{man-bullet}{\u2022}{o}
926 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
928 \H{output-info} GNU \c{info}
930 This output format generates files which can be used with the \i{GNU
933 There are typically multiple output files: a primary file whose name
934 usually ends in \c{.info}, and one or more subsidiary files whose
935 names have numbers on the end, so that they end in \c{.info-1},
936 \c{.info-2} and so on. Alternatively, this output format can be
937 configured to output a single large file containing the whole
940 The \c{info} output format supports the following configuration
943 \S{output-info-file} Controlling the output filenames
945 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
947 \dd Sets the output file name in which to store the \c{info} file.
948 This directive is implicitly generated if you provide a file name
949 parameter after the command-line option \i\c{--info} (see
950 \k{running-options}).
954 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
955 your output file name to produce any subsidiary files required.
957 Note that \c{info} files refer to their own names internally, so
958 these files cannot be \I{renaming \c{info} files}renamed after
959 creation and remain useful.
963 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
965 \dd Sets the preferred \i{maximum file size} for each subsidiary
966 file. As a special case, if you set this to zero, there will be no
967 subsidiary files and the whole document will be placed in a single
968 self-contained output file. (However, note that this file can still
969 not be renamed usefully.)
973 The preferred maximum file size is only a guideline. Halibut may be
974 forced to exceed it if a single section of the document is larger
975 than the maximum size (since individual \c{info} nodes may not be
976 split between files).
980 \S{output-info-dimensions} Indentation and line width
982 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
984 \dd Sets the \I{text width}width of the main part of the document,
985 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
986 directive (see \k{output-text-dimensions}).
988 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
990 \dd Specifies the extra indentation for \I{code paragraphs,
991 indentation} code paragraphs. Works exactly like the
992 \cw{\\cfg\{text-indent-code\}} directive (see
993 \k{output-text-dimensions}).
995 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
997 \dd Specifies how much horizontal space to leave in the index node
998 for the text of \i{index terms}, before displaying the sections the
1001 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
1003 \dd Specifies the extra indentation before the bullet or number in a
1004 \I{bulletted list, indentation}\I{numbered list, indentation}list
1005 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
1006 directive (see \k{output-text-dimensions}).
1008 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
1010 \dd Specifies the additional indentation before the body of a list
1011 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
1012 directive (see \k{output-text-dimensions}).
1014 \S{output-info-headings} Configuring heading display
1016 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
1018 \dd Specifies the suffix text to be appended to each section number
1019 before displaying the section title. For example, if you set this to
1020 \q{\cw{:\_}}, then a typical section title might look something like
1021 \q{Section 3.1: Something Like This}.
1023 \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1025 \dd Specifies the text to be used to underline section titles. Works
1026 very much like the \cw{\\cfg\{text-chapter-underline\}} directive
1027 (see \k{output-text-headings}). You can specify more than one
1028 option, and Halibut will choose the first one supported by the
1031 \S{output-info-characters} Controlling the characters used
1033 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
1035 \dd Specifies what character set the output should be in, similarly to
1036 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1038 \# FIXME: if you try sufficiently hard, you can probably find an
1039 output encoding that will break the info format by trampling on its
1040 special characters. So either don't do that, or tell us what we should
1043 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1045 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1046 You can specify multiple fallback options. Works exactly like the
1047 \cw{\\cfg\{text-bullet\}} directive (see
1048 \k{output-text-characters}).
1050 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1052 \dd Specifies the text used to draw \i{horizontal rules}. You can
1053 specify multiple fallback options. Works exactly like the
1054 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
1056 \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{\}}]
1058 \dd Specifies the quotation marks to use, overriding any
1059 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1060 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1061 directive (see \k{output-text-characters}).
1063 \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{\}}]
1065 \dd Specifies how to display emphasised text. You can specify
1066 multiple fallback options. Works exactly like the
1067 \cw{\\cfg\{text-emphasis\}} directive (see
1068 \k{output-text-characters}).
1070 \S{output-info-misc} Miscellaneous configuration options
1072 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
1074 \dd Specifies the text to append to the item numbers in a
1075 \i{numbered list}. Works exactly like the
1076 \cw{\\cfg\{text-list-suffix\}} directive (see
1077 \k{output-text-misc}).
1079 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
1080 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
1082 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
1083 header of the Info file. This mechanism is used to automatically
1084 generate the \i{\c{dir} file} at the root of a Unix system's
1085 \c{info} collection.
1089 The parameters to this directive are:
1093 \dd Specifies the section of the \c{dir} file in which you want your
1094 document referenced. For example, \q{Development}, or \q{Games}, or
1099 \dd Specifies a short name for the directory entry, which will
1100 appear at the start of the menu line.
1104 \dd Specifies a long name for the directory entry, which will appear
1105 at the end of the menu line.
1109 \dd This parameter is optional. If it is present, then the directory
1110 entry will cause a jump to a particular subsection of your document,
1111 rather than starting at the top. The subsection will be the one
1112 referred to by the given keyword (see \k{input-sections} for details
1113 about assigning keywords to document sections).
1115 For example, in a document describing many game programs, the
1116 configuration directive
1118 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1121 might produce text in the \c{dir} file looking something like this:
1124 \c * Chess: (mygames)Chapter 3. Electronic chess game
1126 if the output file were called \c{mygames.info} and the keyword
1127 \c{chess} had been used to define Chapter 3 of the document.
1131 \S{output-info-defaults} Default settings
1133 The \i{default settings} for the \c{info} output format are:
1135 \c \cfg{info-filename}{output.info}
1136 \c \cfg{info-max-file-size}{65536}
1138 \c \cfg{info-width}{70}
1139 \c \cfg{info-indent-code}{2}
1140 \c \cfg{info-index-width}{40}
1141 \c \cfg{info-list-indent}{1}
1142 \c \cfg{info-listitem-indent}{3}
1144 \c \cfg{info-section-suffix}{: }
1145 \c \cfg{info-underline}{\u203e}{-}
1147 \c \cfg{info-charset}{ASCII}
1148 \c \cfg{info-bullet}{\u2022}{-}
1149 \c \cfg{info-rule}{\u2500}{-}
1150 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1151 \c \cfg{info-emphasis}{_}{_}
1153 \c \cfg{info-list-suffix}{.}
1155 and no \cw{\\cfg\{info-dir-entry\}} directives.
1157 \H{output-paper} Paper formats
1159 These output formats (currently PostScript and PDF) generate printable
1160 manuals. As such, they share a number of configuration directives.
1162 \S{output-ps} \i{PostScript}
1164 This output format generates a printable manual in PostScript format.
1166 There is one configuration option specific to PostScript:
1168 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1170 \dd Sets the \i{output file name} in which to store the PostScript
1171 file. This directive is implicitly generated if you provide a file
1172 name parameter after the command-line option \i\c{--ps} (see
1173 \k{running-options}).
1175 The \i{default settings} for the PostScript output format are:
1177 \c \cfg{ps-filename}{output.ps}
1179 \S{output-pdf} \i{PDF}
1181 This output format generates a printable manual in PDF format. This
1182 should look exactly identical to the PostScript output (see
1183 \k{output-ps}), but also uses some PDF interactive features to
1184 provide an outline of all the document's sections and clickable
1185 cross-references between sections.
1187 There is one configuration option specific to PDF:
1189 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1191 \dd Sets the \i{output file name} in which to store the PDF file.
1192 This directive is implicitly generated if you provide a file name
1193 parameter after the command-line option \i\c{--pdf} (see
1194 \k{running-options}).
1196 The \i{default settings} for the PDF output format are:
1198 \c \cfg{pdf-filename}{output.pdf}
1200 \S{output-paper-dimensions} Configuring layout and \i{measurements}
1202 All measurements are in PostScript \i{points} (72 points to the inch).
1204 \S2{output-paper-pagesize} Page properties
1206 \dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
1208 \dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
1210 \dd Specify the absolute limits of the paper.
1212 \dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
1214 \dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
1216 \dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
1218 \dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
1220 \dd Specify the margins. Most text appears within these margins,
1225 \b Section numbers, which appear in the left margin.
1227 \b The footer (containing page numbers), which appears in the bottom
1232 \S2{output-paper-line} Vertical spacing
1234 \dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
1236 \dd Specifies the amount of space between lines of text within a
1237 paragraph. (So, if the font size is 12pt and there is 2pt of leading,
1238 there will be 14pt between successive baselines.)
1240 \dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
1242 \dd Specifies the amount of vertical space between paragraphs. (The
1243 vertical space between paragraphs does \e{not} include
1244 \c{paper-base-leading}.)
1246 \S2{output-paper-indentation} Indentation
1248 \dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
1250 \dd Specifies the indentation of the bullet or number in a
1251 \I{bulletted list, indentation}bulletted or \I{numbered list,
1252 indentation}numbers \I{list, indentation}list, similarly to
1253 \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
1255 \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
1257 \dd Specifies the \e{extra} indentation for the body of a list item,
1258 over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
1260 \# FIXME: doesn't actually work, AFAICT.
1262 \dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
1264 \dd Specifies the amount of indentation for a level of quoting. Used
1265 for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
1266 (see \k{input-code}).
1268 \S2{output-paper-headings} Headings
1270 \dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
1272 \dd Specifies the space between the top margin \#{XXX check} and the
1273 top of the chapter heading. (Each chapter begins on a new page.)
1275 \# FIXME: the first page of the Index gets mangled if this is
1278 \# FIXME: exact relationship to top-margin?
1280 \dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
1282 \dd Specifies the vertical thickness of the black rule under chapter
1285 \dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
1287 \dd Specifies the distance between the base of the chapter heading and
1288 the \e{base} of the underlying rule.
1290 \dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
1292 \dd Specifies the distance between the left margin and the \e{right}
1293 of section numbers (which are in the left margin).
1295 \S2{output-paper-index} Contents and index
1297 \dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}}
1299 \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
1301 \# FIXME: I do not know what dees one does. (I couldn't get either of
1302 them to do anything obvious, although the source indicates they should
1305 \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
1307 \dd Specifies the horizontal spacing between dots in \i\e{leaders}
1308 (the dotted lines that appear between section headings and page
1309 numbers in the table of contents).
1311 \dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
1313 \dd Specifies the distance between the bottom margin and the \e{base}
1314 of the footer (which contains page numbers).
1316 \dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
1318 \dd Specifies the number of columns the index should be divided into.
1320 \# FIXME: with this set to 1, the right-alignment of some index entry
1321 page numbers in the Halibut manual is decidedly wonky.
1323 \dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
1325 \dd Specifies the amount of \I{gutter} horizontal space between index
1328 \dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
1330 \dd Specifies the minimum allowable horizontal space between an index
1331 entry and its page number. If the gap is smaller, the page number is
1332 moved to the next line.
1334 \S2{output-paper-fonts} Fonts
1336 \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
1338 \dd Specifies the font size of body text.
1340 \# FIXME: actually, this doesn't appear to do anything at all - most
1341 font sizes are still hardcoded.
1343 \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
1345 \dd Specifies the font size to use for page numbers.
1347 \S2{output-paper-misc} Miscellaneous
1349 \dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
1351 \dd Specifies the vertical thickness of the rule produced by the
1352 \cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
1353 reserved for thicker rules.)
1355 \S{output-paper-characters} Configuring the characters used
1357 \dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1359 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1360 You can specify multiple fallback options. Works exactly like the
1361 \cw{\\cfg\{text-bullet\}} directive (see
1362 \k{output-text-characters}).
1364 \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{\}}]
1366 \dd Specifies the quotation marks to use, overriding any
1367 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1368 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1369 directive (see \k{output-text-characters}).
1371 \S{output-paper-defaults} Default settings for paper formats
1373 The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
1376 \c \cfg{paper-page-width}{595}
1377 \c \cfg{paper-page-height}{841}
1379 \c \cfg{paper-left-margin}{72}
1380 \c \cfg{paper-top-margin}{72}
1381 \c \cfg{paper-right-margin}{72}
1382 \c \cfg{paper-bottom-margin}{108}
1384 \c \cfg{paper-base-leading}{1}
1385 \c \cfg{paper-base-para-spacing}{10}
1387 \c \cfg{paper-list-indent}{6}
1388 \c \cfg{paper-listitem-indent}{18}
1389 \c \cfg{paper-quote-indent}{18}
1391 \c \cfg{paper-chapter-top-space}{72}
1392 \c \cfg{paper-chapter-underline-thickness}{3}
1393 \c \cfg{paper-chapter-underline-depth}{14}
1394 \c \cfg{paper-sect-num-left-space}{12}
1396 \c \cfg{paper-contents-index-step}{24}
1397 \c \cfg{paper-contents-margin}{84}
1398 \c \cfg{paper-leader-separation}{12}
1399 \c \cfg{paper-footer-distance}{32}
1400 \c \cfg{paper-index-columns}{2}
1401 \c \cfg{paper-index-gutter}{36}
1402 \c \cfg{paper-index-minsep}{18}
1404 \c \cfg{paper-base-font-size}{12}
1405 \c \cfg{paper-pagenum-font-size}{12}
1407 \c \cfg{paper-rule-thickness}{1}
1409 \c \cfg{paper-bullet}{\u2022}{-}
1410 \c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}