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 \cq{:\_}, 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 \cq{-=} 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 \cq{\\C\{fish\} Catching
368 Fish}, this formatting command would expand to
373 \dd Expands to the type and number of the section, without white
374 space. So in chapter 1 this would expand to \cq{Chapter1}; in
375 section A.4.3 it would expand to \cq{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 \cq{1}; in section A.4.3 it would expand to
384 \cq{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 \cq{\\C\{fish\} Catching Fish}, this
392 formatting command would expand to \cq{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-local-head\}}}\cw{\\cfg\{xhtml-local-head\}\{}\e{HTML text}\cw{\}}
503 \dd This configuration directive is local: you specify it within a
504 document section, and it acts on that section only.
508 The text you provide in this directive is placed at the end of the
509 \i\cw{<HEAD>} section of whichever output HTML file contains the
510 section in which the directive was placed. You can specify this
511 directive multiple times in multiple sections if you like.
513 This directive is particularly useful for constructing \i{MacOS
514 on-line help}, which is mostly normal HTML but which requires a
515 special \i\cw{<META NAME="AppleTitle">} tag in the topmost source
516 file. You can arrange this by placing this configuration directive
517 in the preamble or the introduction section, something like this:
519 \c \cfg{html-local-head}{<meta name="AppleTitle"
520 \c content="MyApp Help">}
524 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
526 \dd The text you provide in this directive is used in place of the
527 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
528 \i{background colour}, for example, you could write
529 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
531 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
533 \dd The text you provide in this directive is placed at the
534 beginning of the \i\cw{<BODY>} section of each output HTML file. So
535 if you intend your HTML files to be part of a web site with a
536 standard \i{house style}, and the style needs a \i{header} at the
537 top of every page, this is where you can add that header.
539 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
541 \dd The text you provide in this directive is placed at the end of
542 the \i\cw{<BODY>} section of each output HTML file. So if you intend
543 your HTML files to be part of a web site with a standard \i{house
544 style}, and the style needs a \i{footer} at the bottom of every
545 page, this is where you can add that footer.
547 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
549 \dd The text you provide in this directive is placed at the
550 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
551 output HTML file. This might be a good place to put authors'
552 \i{contact details}, for example.
554 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
556 \dd The text you provide in this directive is placed at the end of
557 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
558 after the version IDs (if present).
560 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
562 \dd The text you provide in this directive is included inside the
563 \cw{<P>} tag containing the \i{navigation links} at the top of each
564 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
565 wanted the navigation links to have a particular CSS style, you
567 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
568 navigation-links paragraph would then begin with the tag \cw{<p
571 \S{output-html-headings} \ii{Configuring heading display}
573 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
575 \dd If this is set to \c{true}, then chapter headings will not
576 contain the word \q{Chapter} (or whatever other word you have
577 defined in its place - see \k{input-sections} and \k{input-config});
578 they will just contain the chapter \e{number}, followed by the
579 chapter title. If you set this to \c{false}, chapter headings will
580 be prefixed by \q{Chapter} or equivalent.
582 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
584 \dd This specifies the suffix text to be appended to the chapter
585 number, before displaying the chapter title. For example, if you set
586 this to \cq{:\_}, then the chapter title might look something
587 like \q{Chapter 2: Doing Things}.
589 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
591 \dd Specifies whether section headings at a particular level should
592 contain the word \q{Section} or equivalent (if \c{false}), or should
593 be numeric only (if \c{true}). The \e{level} parameter specifies
594 which level of section headings you want to affect: 0 means
595 first-level headings (\c{\\H}), 1 means second-level headings
596 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
598 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
600 \dd Specifies the suffix text to be appended to section numbers at a
601 particular level, before displaying the section title.
603 \S{output-html-misc} Miscellaneous options
605 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
607 \dd This directive lets you specify a \i{template}, with exactly the
608 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
609 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
610 NAME="...">}) used to allow URLs to refer to specific sections
611 within a particular HTML file. So if you set this to \cq{%k},
612 for example, then each individual section in your document will be
613 addressable by means of a URL ending in a \c{#} followed by your
614 internal section keyword.
616 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
618 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
619 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
620 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
621 file. If it is set to \c{false}, they will be omitted completely.
623 \# FIXME: surely it would be better to include them in HTML
624 \# comments? The only question is whether they should be _visible_.
626 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
628 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
629 bottom of each HTML file will be omitted completely. (This will
630 therefore also cause \i{version IDs} not to be included.)
632 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
634 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
635 name="author">} tag in the output HTML files, so that browsers which
636 support this can automatically identify the \i{author} of the document.
638 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
640 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
641 name="description">} tag in the output HTML files, so that browsers
642 which support this can easily pick out a brief \I{description, of
643 document}description of the document.
645 \S{output-html-defaults} Default settings
647 The \i{default settings} for Halibut's HTML output format are:
649 \c \cfg{xhtml-contents-filename}{Contents.html}
650 \c \cfg{xhtml-index-filename}{IndexPage.html}
651 \c \cfg{xhtml-template-filename}{%n.html}
652 \c \cfg{xhtml-single-filename}{Manual.html}
653 \c \cfg{xhtml-template-fragment}{%b}
655 \c \cfg{xhtml-leaf-level}{2}
656 \c \cfg{xhtml-leaf-contains-contents}{false}
657 \c \cfg{xhtml-leaf-smallest-contents}{4}
658 \c \cfg{xhtml-contents-depth-0}{2}
659 \c \cfg{xhtml-contents-depth-1}{3}
660 \c \cfg{xhtml-contents-depth-2}{4}
661 \c \cfg{xhtml-contents-depth-3}{5}
662 \c \cfg{xhtml-contents-depth-4}{6}
663 \c \cfg{xhtml-contents-depth-5}{7}
665 \c \cfg{xhtml-head-end}{}
666 \c \cfg{xhtml-body-tag}{<body>}
667 \c \cfg{xhtml-body-start}{}
668 \c \cfg{xhtml-body-end}{}
669 \c \cfg{xhtml-address-start}{}
670 \c \cfg{xhtml-address-end}{}
671 \c \cfg{xhtml-navigation-attributes}{}
673 \c \cfg{xhtml-versionid}{true}
674 \c \cfg{xhtml-suppress-address}{false}
675 \c \cfg{xhtml-author}{}
676 \c \cfg{xhtml-description}{}
678 \c \cfg{xhtml-chapter-numeric}{false}
679 \c \cfg{xhtml-chapter-suffix}{: }
681 \c \cfg{xhtml-section-numeric}{0}{true}
682 \c \cfg{xhtml-section-suffix}{0}{ }
684 \c \cfg{xhtml-section-numeric}{1}{true}
685 \c \cfg{xhtml-section-suffix}{1}{ }
687 \c ... and so on for all section levels below this ...
688 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
690 \H{output-whlp} Windows Help
692 This output format generates data that can be used by the \i{Windows
693 Help} program \cw{WINHELP.EXE}. There are two actual files
694 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
696 Currently, the output is harcoded to be in the \q{\i{Win1252}}
699 The Windows Help output format supports the following configuration
702 \S{output-whlp-file} Output file name
704 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
706 \dd Sets the \i{output file name} in which to store the man page.
707 This directive is implicitly generated if you provide a file name
708 parameter after the command-line option \i\c{--winhelp} (see
709 \k{running-options}).
713 Your output file name should end with \c{.hlp}; if it doesn't,
714 Halibut will append it. Halibut will also generate a contents file
715 (ending in \c{.cnt}) alongside the file name you specify.
719 \S{output-whlp-characters} Configuring the characters used
721 \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
723 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
724 You can specify multiple fallback options. Works exactly like the
725 \cw{\\cfg\{text-bullet\}} directive (see
726 \k{output-text-characters}).
728 \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{\}}]
730 \dd Specifies the quotation marks to use, overriding any
731 \cw{\\cfg\{quotes\}} directive. You can specify multiple
732 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
733 directive (see \k{output-text-characters}).
735 \S{output-whlp-misc} Miscellaneous configuration options
737 \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
739 \dd Sets the text used to describe the help page containing the blurb
740 (see \k{input-blurb}) and table of contents.
743 \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
745 \dd Specifies the \I{suffix text, in section titles}suffix text to
746 be appended to section numbers, before displaying the section title.
747 (Applies to all levels.)
749 \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
751 \dd This text is appended to the number on a \i{numbered list} item,
752 in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
753 \k{output-text-characters}).
755 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
757 \dd This directive defines a Windows \i{Help topic} name in the current
758 section. Topic names can be used by the program invoking
759 \cw{WINHELP.EXE} to jump straight to a particular section. So you
760 can use this for \i{context-sensitive help}.
764 For example, if you used this directive in a particular section:
766 \c \cfg{winhelp-topic}{savingfiles}
768 then a Windows application could invoke Windows Help to jump to that
769 particular section in the help file like this:
771 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
772 \c (DWORD)"JI(`',`savingfiles')");
774 You can use this configuration directive many times, in many
775 different subsections of your document, in order to define a lot of
776 different help contexts which you can use in this way.
780 \S{output-whlp-defaults} Default settings
782 The \i{default settings} for the Windows Help output format are:
784 \c \cfg{winhelp-filename}{output.hlp}
786 \c \cfg{winhelp-bullet}{\u2022}{-}
787 \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
789 \c \cfg{winhelp-contents-titlepage}{Title page}
790 \c \cfg{winhelp-section-suffix}{: }
791 \c \cfg{winhelp-list-suffix}{.}
793 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
795 \H{output-man} Unix \cw{man} pages
797 This output format generates a Unix \i{\cw{man} page}. That is to say,
798 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
801 The available configuration options for this format are as follows:
803 \S{output-man-file} Output file name
805 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
807 \dd Sets the \i{output file name} in which to store the man page.
808 This directive is implicitly generated if you provide a file name
809 parameter after the command-line option \i\c{--man} (see
810 \k{running-options}).
812 \S{output-man-identity} Configuring headers and footers
814 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
816 \dd This directive is used to generate the initial \i{\c{.TH}
817 directive} that appears at the top of a \cw{man} page. It expects to
818 be followed by some number of brace pairs containing text, which will
819 be used in the \i{headers} and \i{footers} of the formatted output.
823 A traditional order for the arguments appears to be:
825 \n The name of the program.
827 \n The (numeric) manual section.
829 \n The date that the \cw{man} page was written.
831 \n The name of any containing suite of which the program is a part.
833 \n The name of the \i{author} of the \cw{man} page.
835 For example, a typical \cw{man} page might contain
837 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
842 \S{output-man-headings} Configuring heading display
844 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
846 \dd If this is set to \c{true}, then \i{section headings} in the
847 \cw{man} page will have their \i{section numbers} displayed as usual. If
848 set to \c{false}, the section numbers will be omitted. (\cw{man}
849 pages traditionally have section names such as \q{SYNOPSIS},
850 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
851 \c{false} is the setting which conforms most closely to normal
854 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
856 \dd If this is set to a number greater than 0, then section headings
857 \e{higher} than the given depth will not be displayed. If it is set
858 to zero, all section headings will be displayed as normal.
862 The point of this is so that you can use the same Halibut input file
863 to generate a quick-reference \cw{man} page for a program, \e{and} to
864 include that \cw{man} page as an appendix in your program's full manual.
865 If you are to include the \cw{man} page as an appendix, then the internal
866 headings within the page will probably need to be at \c{\\H} or
867 \c{\\S} level; therefore, when you format that input file on its own
868 to create the \cw{man} page itself, you will need to have defined a
869 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
870 want to see displayed.
872 Here's an example. You might have a file \c{appendix.but}, which
875 \c \A{manpages} \cw{man} pages for the Foo tool suite
877 \c \cfg{man-mindepth}{2}
879 Then you have a file \c{make-foo.but}, and probably others like it
880 as well, each of which looks something like this:
882 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
885 \c \H{man-foo} \cw{man} page for \c{make-foo}
887 \c \S{man-foo-name} NAME
889 \c \c{make-foo} - create Foo files for the Foo tool suite
891 \c \S{man-foo-synopsis} SYNOPSIS
896 So when you're generating your main manual, you can include
897 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
898 pages you have, and your \cw{man} pages will be formatted neatly as
899 part of an appendix. Then, in a separate run of Halibut, you can
902 \c halibut appendix.but make-foo.but
904 and this will generate a \cw{man} page \c{output.1}, in which the
905 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
906 page for \c{make-foo}} will not be displayed because of the
907 \c{man-mindepth} directive. So the first visible heading in the
908 output \cw{man} page will be \q{NAME}, exactly as a user would
913 \S{output-man-characters} Configuring the characters used
915 \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
917 \dd Specifies what character set the output should be in, similarly to
918 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
920 \# FIXME: you're probably on your own in making sure that it's
921 sensible to output man pages in that charset.
923 \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
925 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
926 You can specify multiple fallback options. Works exactly like the
927 \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
929 \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{\}}]
931 \dd Specifies the quotation marks to use, overriding any
932 \cw{\\cfg\{quotes\}} directive. You can specify multiple
933 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
934 directive (see \k{output-text-characters}).
936 \S{output-man-defaults} Default settings
938 The \i{default settings} for the \cw{man} page output format are:
940 \c \cfg{man-filename}{output.1}
942 \c \cfg{man-identity}{}
944 \c \cfg{man-headnumbers}{false}
945 \c \cfg{man-mindepth}{0}
947 \c \cfg{man-charset}{ASCII}
948 \c \cfg{man-bullet}{\u2022}{o}
949 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
951 \H{output-info} GNU \c{info}
953 This output format generates files which can be used with the \i{GNU
956 There are typically multiple output files: a primary file whose name
957 usually ends in \c{.info}, and one or more subsidiary files whose
958 names have numbers on the end, so that they end in \c{.info-1},
959 \c{.info-2} and so on. Alternatively, this output format can be
960 configured to output a single large file containing the whole
963 The \c{info} output format supports the following configuration
966 \S{output-info-file} Controlling the output filenames
968 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
970 \dd Sets the output file name in which to store the \c{info} file.
971 This directive is implicitly generated if you provide a file name
972 parameter after the command-line option \i\c{--info} (see
973 \k{running-options}).
977 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
978 your output file name to produce any subsidiary files required.
980 Note that \c{info} files refer to their own names internally, so
981 these files cannot be \I{renaming \c{info} files}renamed after
982 creation and remain useful.
986 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
988 \dd Sets the preferred \i{maximum file size} for each subsidiary
989 file. As a special case, if you set this to zero, there will be no
990 subsidiary files and the whole document will be placed in a single
991 self-contained output file. (However, note that this file can still
992 not be renamed usefully.)
996 The preferred maximum file size is only a guideline. Halibut may be
997 forced to exceed it if a single section of the document is larger
998 than the maximum size (since individual \c{info} nodes may not be
999 split between files).
1003 \S{output-info-dimensions} Indentation and line width
1005 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
1007 \dd Sets the \I{text width}width of the main part of the document,
1008 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
1009 directive (see \k{output-text-dimensions}).
1011 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
1013 \dd Specifies the extra indentation for \I{code paragraphs,
1014 indentation} code paragraphs. Works exactly like the
1015 \cw{\\cfg\{text-indent-code\}} directive (see
1016 \k{output-text-dimensions}).
1018 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
1020 \dd Specifies how much horizontal space to leave in the index node
1021 for the text of \i{index terms}, before displaying the sections the
1024 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
1026 \dd Specifies the extra indentation before the bullet or number in a
1027 \I{bulletted list, indentation}\I{numbered list, indentation}list
1028 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
1029 directive (see \k{output-text-dimensions}).
1031 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
1033 \dd Specifies the additional indentation before the body of a list
1034 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
1035 directive (see \k{output-text-dimensions}).
1037 \S{output-info-headings} Configuring heading display
1039 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
1041 \dd Specifies the suffix text to be appended to each section number
1042 before displaying the section title. For example, if you set this to
1043 \cq{:\_}, then a typical section title might look something like
1044 \q{Section 3.1: Something Like This}.
1046 \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1048 \dd Specifies the text to be used to underline section titles. Works
1049 very much like the \cw{\\cfg\{text-chapter-underline\}} directive
1050 (see \k{output-text-headings}). You can specify more than one
1051 option, and Halibut will choose the first one supported by the
1054 \S{output-info-characters} Controlling the characters used
1056 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
1058 \dd Specifies what character set the output should be in, similarly to
1059 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1061 \# FIXME: if you try sufficiently hard, you can probably find an
1062 output encoding that will break the info format by trampling on its
1063 special characters. So either don't do that, or tell us what we should
1066 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1068 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1069 You can specify multiple fallback options. Works exactly like the
1070 \cw{\\cfg\{text-bullet\}} directive (see
1071 \k{output-text-characters}).
1073 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1075 \dd Specifies the text used to draw \i{horizontal rules}. You can
1076 specify multiple fallback options. Works exactly like the
1077 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
1079 \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{\}}]
1081 \dd Specifies the quotation marks to use, overriding any
1082 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1083 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1084 directive (see \k{output-text-characters}).
1086 \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{\}}]
1088 \dd Specifies how to display emphasised text. You can specify
1089 multiple fallback options. Works exactly like the
1090 \cw{\\cfg\{text-emphasis\}} directive (see
1091 \k{output-text-characters}).
1093 \S{output-info-misc} Miscellaneous configuration options
1095 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
1097 \dd Specifies the text to append to the item numbers in a
1098 \i{numbered list}. Works exactly like the
1099 \cw{\\cfg\{text-list-suffix\}} directive (see
1100 \k{output-text-misc}).
1102 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
1103 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
1105 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
1106 header of the Info file. This mechanism is used to automatically
1107 generate the \i{\c{dir} file} at the root of a Unix system's
1108 \c{info} collection.
1112 The parameters to this directive are:
1116 \dd Specifies the section of the \c{dir} file in which you want your
1117 document referenced. For example, \q{Development}, or \q{Games}, or
1122 \dd Specifies a short name for the directory entry, which will
1123 appear at the start of the menu line.
1127 \dd Specifies a long name for the directory entry, which will appear
1128 at the end of the menu line.
1132 \dd This parameter is optional. If it is present, then the directory
1133 entry will cause a jump to a particular subsection of your document,
1134 rather than starting at the top. The subsection will be the one
1135 referred to by the given keyword (see \k{input-sections} for details
1136 about assigning keywords to document sections).
1138 For example, in a document describing many game programs, the
1139 configuration directive
1141 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1144 might produce text in the \c{dir} file looking something like this:
1147 \c * Chess: (mygames)Chapter 3. Electronic chess game
1149 if the output file were called \c{mygames.info} and the keyword
1150 \c{chess} had been used to define Chapter 3 of the document.
1154 \S{output-info-defaults} Default settings
1156 The \i{default settings} for the \c{info} output format are:
1158 \c \cfg{info-filename}{output.info}
1159 \c \cfg{info-max-file-size}{65536}
1161 \c \cfg{info-width}{70}
1162 \c \cfg{info-indent-code}{2}
1163 \c \cfg{info-index-width}{40}
1164 \c \cfg{info-list-indent}{1}
1165 \c \cfg{info-listitem-indent}{3}
1167 \c \cfg{info-section-suffix}{: }
1168 \c \cfg{info-underline}{\u203e}{-}
1170 \c \cfg{info-charset}{ASCII}
1171 \c \cfg{info-bullet}{\u2022}{-}
1172 \c \cfg{info-rule}{\u2500}{-}
1173 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1174 \c \cfg{info-emphasis}{_}{_}
1176 \c \cfg{info-list-suffix}{.}
1178 and no \cw{\\cfg\{info-dir-entry\}} directives.
1180 \H{output-paper} Paper formats
1182 These output formats (currently PostScript and PDF) generate printable
1183 manuals. As such, they share a number of configuration directives.
1185 \S{output-ps} \i{PostScript}
1187 This output format generates a printable manual in PostScript format.
1189 There is one configuration option specific to PostScript:
1191 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1193 \dd Sets the \i{output file name} in which to store the PostScript
1194 file. This directive is implicitly generated if you provide a file
1195 name parameter after the command-line option \i\c{--ps} (see
1196 \k{running-options}).
1198 The \i{default settings} for the PostScript output format are:
1200 \c \cfg{ps-filename}{output.ps}
1202 \S{output-pdf} \i{PDF}
1204 This output format generates a printable manual in PDF format. This
1205 should look exactly identical to the PostScript output (see
1206 \k{output-ps}), but also uses some PDF interactive features to
1207 provide an outline of all the document's sections and clickable
1208 cross-references between sections.
1210 There is one configuration option specific to PDF:
1212 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1214 \dd Sets the \i{output file name} in which to store the PDF file.
1215 This directive is implicitly generated if you provide a file name
1216 parameter after the command-line option \i\c{--pdf} (see
1217 \k{running-options}).
1219 The \i{default settings} for the PDF output format are:
1221 \c \cfg{pdf-filename}{output.pdf}
1223 \S{output-paper-dimensions} Configuring layout and \i{measurements}
1225 All measurements are in PostScript \i{points} (72 points to the inch).
1227 \S2{output-paper-pagesize} Page properties
1229 \dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}}
1231 \dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}}
1233 \dd Specify the absolute limits of the paper.
1235 \dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}}
1237 \dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}}
1239 \dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}}
1241 \dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}}
1243 \dd Specify the margins. Most text appears within these margins,
1248 \b Section numbers, which appear in the left margin.
1250 \b The footer (containing page numbers), which appears in the bottom
1255 \S2{output-paper-line} Vertical spacing
1257 \dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}}
1259 \dd Specifies the amount of space between lines of text within a
1260 paragraph. (So, if the font size is 12pt and there is 2pt of leading,
1261 there will be 14pt between successive baselines.)
1263 \dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}}
1265 \dd Specifies the amount of vertical space between paragraphs. (The
1266 vertical space between paragraphs does \e{not} include
1267 \c{paper-base-leading}.)
1269 \S2{output-paper-indentation} Indentation
1271 \dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}}
1273 \dd Specifies the indentation of the bullet or number in a
1274 \I{bulletted list, indentation}bulletted or \I{numbered list,
1275 indentation}numbers \I{list, indentation}list, similarly to
1276 \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}).
1278 \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}}
1280 \dd Specifies the \e{extra} indentation for the body of a list item,
1281 over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}.
1283 \# FIXME: doesn't actually work, AFAICT.
1285 \dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}}
1287 \dd Specifies the amount of indentation for a level of quoting. Used
1288 for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c}
1289 (see \k{input-code}).
1291 \S2{output-paper-headings} Headings
1293 \dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}}
1295 \dd Specifies the space between the top margin and the top of the
1296 chapter heading. (Each chapter begins on a new page.)
1298 \dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}}
1300 \dd Specifies the vertical thickness of the black rule under chapter
1303 \dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}}
1305 \dd Specifies the distance between the base of the chapter heading and
1306 the \e{base} of the underlying rule.
1308 \dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}}
1310 \dd Specifies the distance between the left margin and the \e{right}
1311 of section numbers (which are in the left margin).
1313 \S2{output-paper-index} Contents and index
1315 \dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}}
1317 \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}}
1319 \# FIXME: I do not know what dees one does. (I couldn't get either of
1320 them to do anything obvious, although the source indicates they should
1323 \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}}
1325 \dd Specifies the horizontal spacing between dots in \i\e{leaders}
1326 (the dotted lines that appear between section headings and page
1327 numbers in the table of contents).
1329 \dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}}
1331 \dd Specifies the distance between the bottom margin and the \e{base}
1332 of the footer (which contains page numbers).
1334 \dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}}
1336 \dd Specifies the number of columns the index should be divided into.
1338 \# FIXME: with this set to 1, the right-alignment of some index entry
1339 page numbers in the Halibut manual is decidedly wonky.
1341 \dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}}
1343 \dd Specifies the amount of \I{gutter} horizontal space between index
1346 \dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}}
1348 \dd Specifies the minimum allowable horizontal space between an index
1349 entry and its page number. If the gap is smaller, the page number is
1350 moved to the next line.
1352 \S2{output-paper-fonts} Fonts
1354 \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}}
1356 \dd Specifies the font size of body text.
1358 \# FIXME: actually, this doesn't appear to do anything at all - most
1359 font sizes are still hardcoded.
1361 \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}}
1363 \dd Specifies the font size to use for page numbers.
1365 \S2{output-paper-misc} Miscellaneous
1367 \dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}}
1369 \dd Specifies the vertical thickness of the rule produced by the
1370 \cw{\\rule} command (see \k{input-rule}). (Note that no extra space is
1371 reserved for thicker rules.)
1373 \S{output-paper-characters} Configuring the characters used
1375 \dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1377 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1378 You can specify multiple fallback options. Works exactly like the
1379 \cw{\\cfg\{text-bullet\}} directive (see
1380 \k{output-text-characters}).
1382 \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{\}}]
1384 \dd Specifies the quotation marks to use, overriding any
1385 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1386 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1387 directive (see \k{output-text-characters}).
1389 \S{output-paper-defaults} Default settings for paper formats
1391 The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e.,
1394 \c \cfg{paper-page-width}{595}
1395 \c \cfg{paper-page-height}{841}
1397 \c \cfg{paper-left-margin}{72}
1398 \c \cfg{paper-top-margin}{72}
1399 \c \cfg{paper-right-margin}{72}
1400 \c \cfg{paper-bottom-margin}{108}
1402 \c \cfg{paper-base-leading}{1}
1403 \c \cfg{paper-base-para-spacing}{10}
1405 \c \cfg{paper-list-indent}{6}
1406 \c \cfg{paper-listitem-indent}{18}
1407 \c \cfg{paper-quote-indent}{18}
1409 \c \cfg{paper-chapter-top-space}{72}
1410 \c \cfg{paper-chapter-underline-thickness}{3}
1411 \c \cfg{paper-chapter-underline-depth}{14}
1412 \c \cfg{paper-sect-num-left-space}{12}
1414 \c \cfg{paper-contents-index-step}{24}
1415 \c \cfg{paper-contents-margin}{84}
1416 \c \cfg{paper-leader-separation}{12}
1417 \c \cfg{paper-footer-distance}{32}
1418 \c \cfg{paper-index-columns}{2}
1419 \c \cfg{paper-index-gutter}{36}
1420 \c \cfg{paper-index-minsep}{18}
1422 \c \cfg{paper-base-font-size}{12}
1423 \c \cfg{paper-pagenum-font-size}{12}
1425 \c \cfg{paper-rule-thickness}{1}
1427 \c \cfg{paper-bullet}{\u2022}{-}
1428 \c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'}