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 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 This output format generates an \i{HTML} version of the document. By
324 default, this will be in multiple files, starting with
325 \c{Contents.html} and splitting the document into files by chapter
326 and/or subsection. You can configure precisely how the text is split
327 between HTML files using the configuration commands described in
328 this section. In particular, you can configure Halibut to output one
329 single HTML file instead of multiple ones.
331 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
332 which is why all of the configuration directives start with the word
333 \c{xhtml} rather than \c{html}.
335 \S{output-html-file} Controlling the output file names
337 \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
339 \dd Sets the \i{output file name} in which to store the top-level
340 contents page. Since this is the first page a user ought to see when
341 beginning to read the document, a good choice in many cases might be
342 \c{index.html} (although this is not the default, for historical
345 \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
347 \dd Sets the file name in which to store the document's index.
349 \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
351 \dd Provides a \i{template} to be used when constructing the file
352 names of each chapter or section of the document. This template
353 should contain at least one \i\e{formatting command}, in the form of
354 a per cent sign followed by a letter. (If you need a literal per
355 cent sign, you can write \c{%%}.)
359 The formatting commands used in this template are:
361 \dt \I{%N-upper}\c{%N}
363 \dd Expands to the visible title of the section, with white space
364 removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
365 Fish}}, this formatting command would expand to
366 \q{\cw{CatchingFish}}.
370 \dd Expands to the type and number of the section, without white
371 space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
372 section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
373 If the section has no number (an unnumbered chapter created using
374 \c{\\U}), this directive falls back to doing the same thing as
379 \dd Expands to the bare number of the section. So in chapter 1 this
380 would expand to \q{\cw{1}}; in section A.4.3 it would expand to
381 \q{\cw{A.4.3}}, and so on. If the section has no number (an
382 unnumbered chapter created using \c{\\U}), this directive falls back
383 to doing the same thing as \c{%N}.
387 \dd Expands to the internal keyword specified in the section title.
388 So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
389 formatting command would expand to \q{\cw{fish}}. If the section has
390 no keyword (an unnumbered chapter created using \c{\\U}), this
391 directive falls back to doing the same thing as \c{%N}.
393 These formatting directives can also be used in the
394 \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
395 \k{output-html-misc}).
399 \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
401 \dd Sets the file name in which to store the entire document, if
402 Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
403 produce a single self-contained file. Both this directive \e{and}
404 \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
405 provide a file name parameter after the command-line option
406 \i\c{--html} (see \k{running-options}).
408 \S{output-html-split} Controlling the splitting into HTML files
410 By default, the HTML output from Halibut is split into multiple
411 files. Each file typically contains a single chapter or section and
412 everything below it, unless subsections of that chapter are
413 themselves split off into further files.
415 Most files also contain a contents section, giving hyperlinks to the
416 sections in the file and/or the sections below it.
418 The configuration directives listed below allow you to configure the
419 splitting into files, and the details of the contents sections.
421 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
423 \dd This setting indicates the depth of section which should be
424 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
425 you set it to 1, for example, then every chapter will be given its
426 own HTML file, plus a top-level \i{contents file}. If you set this
427 to 2, then each chapter \e{and} each \c{\\H} section will have a
428 file, and the chapter files will mostly just contain links to their
433 If you set this option to zero, then the whole document will appear
434 in a single file. If you do this, Halibut will call that file
435 \i\c{Manual.html} instead of \i\c{Contents.html}.
437 This option is automatically set to zero if you provide a file name
438 parameter after the command-line option \i\c{--html} (see
439 \k{running-options}), because you have specified a single file name
440 and so Halibut assumes you want the whole document to be placed in
445 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
447 \dd This directive allows you to specify how \I{depth of
448 contents}deep the contents section in a particular file should go.
452 The \e{level} parameter indicates which level of contents section
453 you are dealing with. 0 denotes the main contents section in the
454 topmost file \c{Contents.html}; 1 denotes a contents section in a
455 chapter file; 2 is a contents section in a file containing a \c{\\H}
456 heading, and so on. Currently you can't go below level 5 (which
457 corresponds to a \c{\\S3} heading).
459 The \e{depth} parameter indicates the maximum depth of heading which
460 will be shown in this contents section. Again, 1 denotes a chapter,
461 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
463 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
464 Halibut to put contents links in chapter files for all sections down
465 to \c{\\S} level, but not to go into any more detail than that.
469 \# FIXME: this is utterly ghastly. For a start, it should include
470 \# the level as a separate argument, like the text section config
471 \# directives. Secondly, it shouldn't be limited in depth!
473 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
475 \dd If you set this to \c{true}, then each leaf file will contain
476 its own contents section which summarises the text within it.
478 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
480 \dd Contents sections in leaf files are not output at all if they
481 contain very few entries (on the assumption that it just isn't worth
482 bothering). This directive configures the minimum number of entries
483 required in a leaf contents section to make Halibut bother
484 generating it at all.
486 \S{output-html-html} Including pieces of your own HTML
488 The directives in this section allow you to supply pieces of
489 \I{HTML}\i{verbatim HTML} code, which will be included in various
490 parts of the output files.
492 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
494 \dd The text you provide in this directive is placed at the end of
495 the \i\cw{<HEAD>} section of each output HTML file. So this is a
496 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
498 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
500 \dd The text you provide in this directive is used in place of the
501 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
502 \i{background colour}, for example, you could write
503 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
505 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
507 \dd The text you provide in this directive is placed at the
508 beginning of the \i\cw{<BODY>} section of each output HTML file. So
509 if you intend your HTML files to be part of a web site with a
510 standard \i{house style}, and the style needs a \i{header} at the
511 top of every page, this is where you can add that header.
513 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
515 \dd The text you provide in this directive is placed at the end of
516 the \i\cw{<BODY>} section of each output HTML file. So if you intend
517 your HTML files to be part of a web site with a standard \i{house
518 style}, and the style needs a \i{footer} at the bottom of every
519 page, this is where you can add that footer.
521 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
523 \dd The text you provide in this directive is placed at the
524 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
525 output HTML file. This might be a good place to put authors'
526 \i{contact details}, for example.
528 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
530 \dd The text you provide in this directive is placed at the end of
531 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
532 after the version IDs (if present).
534 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
536 \dd The text you provide in this directive is included inside the
537 \cw{<P>} tag containing the \i{navigation links} at the top of each
538 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
539 wanted the navigation links to have a particular CSS style, you
541 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
542 navigation-links paragraph would then begin with the tag \cw{<p
545 \S{output-html-headings} \ii{Configuring heading display}
547 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
549 \dd If this is set to \c{true}, then chapter headings will not
550 contain the word \q{Chapter} (or whatever other word you have
551 defined in its place - see \k{input-sections} and \k{input-config});
552 they will just contain the chapter \e{number}, followed by the
553 chapter title. If you set this to \c{false}, chapter headings will
554 be prefixed by \q{Chapter} or equivalent.
556 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
558 \dd This specifies the suffix text to be appended to the chapter
559 number, before displaying the chapter title. For example, if you set
560 this to \q{\cw{:\_}}, then the chapter title might look something
561 like \q{Chapter 2: Doing Things}.
563 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
565 \dd Specifies whether section headings at a particular level should
566 contain the word \q{Section} or equivalent (if \c{false}), or should
567 be numeric only (if \c{true}). The \e{level} parameter specifies
568 which level of section headings you want to affect: 0 means
569 first-level headings (\c{\\H}), 1 means second-level headings
570 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
572 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
574 \dd Specifies the suffix text to be appended to section numbers at a
575 particular level, before displaying the section title.
577 \S{output-html-misc} Miscellaneous options
579 \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
581 \dd This directive lets you specify a \i{template}, with exactly the
582 same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
583 \k{output-html-file}), to be used for the anchor names (\i\cw{<A
584 NAME="...">}) used to allow URLs to refer to specific sections
585 within a particular HTML file. So if you set this to \q{\cw{%k}},
586 for example, then each individual section in your document will be
587 addressable by means of a URL ending in a \c{#} followed by your
588 internal section keyword.
590 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
592 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
593 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
594 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
595 file. If it is set to \c{false}, they will be omitted completely.
597 \# FIXME: surely it would be better to include them in HTML
598 \# comments? The only question is whether they should be _visible_.
600 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
602 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
603 bottom of each HTML file will be omitted completely. (This will
604 therefore also cause \i{version IDs} not to be included.)
606 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
608 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
609 name="author">} tag in the output HTML files, so that browsers which
610 support this can automatically identify the \i{author} of the document.
612 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
614 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
615 name="description">} tag in the output HTML files, so that browsers
616 which support this can easily pick out a brief \I{description, of
617 document}description of the document.
619 \S{output-html-defaults} Default settings
621 The \i{default settings} for Halibut's HTML output format are:
623 \c \cfg{xhtml-contents-filename}{Contents.html}
624 \c \cfg{xhtml-index-filename}{IndexPage.html}
625 \c \cfg{xhtml-template-filename}{%n.html}
626 \c \cfg{xhtml-single-filename}{Manual.html}
627 \c \cfg{xhtml-template-fragment}{%b}
629 \c \cfg{xhtml-leaf-level}{2}
630 \c \cfg{xhtml-leaf-contains-contents}{false}
631 \c \cfg{xhtml-leaf-smallest-contents}{4}
632 \c \cfg{xhtml-contents-depth-0}{2}
633 \c \cfg{xhtml-contents-depth-1}{3}
634 \c \cfg{xhtml-contents-depth-2}{4}
635 \c \cfg{xhtml-contents-depth-3}{5}
636 \c \cfg{xhtml-contents-depth-4}{6}
637 \c \cfg{xhtml-contents-depth-5}{7}
639 \c \cfg{xhtml-head-end}{}
640 \c \cfg{xhtml-body-tag}{<body>}
641 \c \cfg{xhtml-body-start}{}
642 \c \cfg{xhtml-body-end}{}
643 \c \cfg{xhtml-address-start}{}
644 \c \cfg{xhtml-address-end}{}
645 \c \cfg{xhtml-navigation-attributes}{}
647 \c \cfg{xhtml-versionid}{true}
648 \c \cfg{xhtml-suppress-address}{false}
649 \c \cfg{xhtml-author}{}
650 \c \cfg{xhtml-description}{}
652 \c \cfg{xhtml-chapter-numeric}{false}
653 \c \cfg{xhtml-chapter-suffix}{: }
655 \c \cfg{xhtml-section-numeric}{0}{true}
656 \c \cfg{xhtml-section-suffix}{0}{ }
658 \c \cfg{xhtml-section-numeric}{1}{true}
659 \c \cfg{xhtml-section-suffix}{1}{ }
661 \c ... and so on for all section levels below this ...
662 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
664 \H{output-whlp} Windows Help
666 This output format generates data that can be used by the \i{Windows
667 Help} program \cw{WINHELP.EXE}. There are two actual files
668 generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
670 Currently, the output is harcoded to be in the \q{\i{Win1252}}
673 The Windows Help output format supports the following configuration
676 \S{output-whlp-file} Output file name
678 \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}}
680 \dd Sets the \i{output file name} in which to store the man page.
681 This directive is implicitly generated if you provide a file name
682 parameter after the command-line option \i\c{--winhelp} (see
683 \k{running-options}).
687 Your output file name should end with \c{.hlp}; if it doesn't,
688 Halibut will append it. Halibut will also generate a contents file
689 (ending in \c{.cnt}) alongside the file name you specify.
693 \S{output-whlp-characters} Configuring the characters used
695 \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
697 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
698 You can specify multiple fallback options. Works exactly like the
699 \cw{\\cfg\{text-bullet\}} directive (see
700 \k{output-text-characters}).
702 \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{\}}]
704 \dd Specifies the quotation marks to use, overriding any
705 \cw{\\cfg\{quotes\}} directive. You can specify multiple
706 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
707 directive (see \k{output-text-characters}).
709 \S{output-whlp-misc} Miscellaneous configuration options
711 \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}}
713 \dd Sets the text used to describe the help page containing the blurb
714 (see \k{input-blurb}) and table of contents.
717 \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}}
719 \dd Specifies the \I{suffix text, in section titles}suffix text to
720 be appended to section numbers, before displaying the section title.
721 (Applies to all levels.)
723 \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}}
725 \dd This text is appended to the number on a \i{numbered list} item,
726 in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see
727 \k{output-text-characters}).
729 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
731 \dd This directive defines a Windows \i{Help topic} name in the current
732 section. Topic names can be used by the program invoking
733 \cw{WINHELP.EXE} to jump straight to a particular section. So you
734 can use this for \i{context-sensitive help}.
738 For example, if you used this directive in a particular section:
740 \c \cfg{winhelp-topic}{savingfiles}
742 then a Windows application could invoke Windows Help to jump to that
743 particular section in the help file like this:
745 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
746 \c (DWORD)"JI(`',`savingfiles')");
748 You can use this configuration directive many times, in many
749 different subsections of your document, in order to define a lot of
750 different help contexts which you can use in this way.
754 \S{output-whlp-defaults} Default settings
756 The \i{default settings} for the Windows Help output format are:
758 \c \cfg{winhelp-filename}{output.hlp}
760 \c \cfg{winhelp-bullet}{\u2022}{-}
761 \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"}
763 \c \cfg{winhelp-contents-titlepage}{Title page}
764 \c \cfg{winhelp-section-suffix}{: }
765 \c \cfg{winhelp-list-suffix}{.}
767 and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
769 \H{output-man} Unix \cw{man} pages
771 This output format generates a Unix \i{\cw{man} page}. That is to say,
772 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
775 The available configuration options for this format are as follows:
777 \S{output-man-file} Output file name
779 \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
781 \dd Sets the \i{output file name} in which to store the man page.
782 This directive is implicitly generated if you provide a file name
783 parameter after the command-line option \i\c{--man} (see
784 \k{running-options}).
786 \S{output-man-identity} Configuring headers and footers
788 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
790 \dd This directive is used to generate the initial \i{\c{.TH}
791 directive} that appears at the top of a \cw{man} page. It expects to
792 be followed by some number of brace pairs containing text, which will
793 be used in the \i{headers} and \i{footers} of the formatted output.
797 A traditional order for the arguments appears to be:
799 \n The name of the program.
801 \n The (numeric) manual section.
803 \n The date that the \cw{man} page was written.
805 \n The name of any containing suite of which the program is a part.
807 \n The name of the \i{author} of the \cw{man} page.
809 For example, a typical \cw{man} page might contain
811 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
816 \S{output-man-headings} Configuring heading display
818 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
820 \dd If this is set to \c{true}, then \i{section headings} in the
821 \cw{man} page will have their \i{section numbers} displayed as usual. If
822 set to \c{false}, the section numbers will be omitted. (\cw{man}
823 pages traditionally have section names such as \q{SYNOPSIS},
824 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
825 \c{false} is the setting which conforms most closely to normal
828 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
830 \dd If this is set to a number greater than 0, then section headings
831 \e{higher} than the given depth will not be displayed. If it is set
832 to zero, all section headings will be displayed as normal.
836 The point of this is so that you can use the same Halibut input file
837 to generate a quick-reference \cw{man} page for a program, \e{and} to
838 include that \cw{man} page as an appendix in your program's full manual.
839 If you are to include the \cw{man} page as an appendix, then the internal
840 headings within the page will probably need to be at \c{\\H} or
841 \c{\\S} level; therefore, when you format that input file on its own
842 to create the \cw{man} page itself, you will need to have defined a
843 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
844 want to see displayed.
846 Here's an example. You might have a file \c{appendix.but}, which
849 \c \A{manpages} \cw{man} pages for the Foo tool suite
851 \c \cfg{man-mindepth}{2}
853 Then you have a file \c{make-foo.but}, and probably others like it
854 as well, each of which looks something like this:
856 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred
859 \c \H{man-foo} \cw{man} page for \c{make-foo}
861 \c \S{man-foo-name} NAME
863 \c \c{make-foo} - create Foo files for the Foo tool suite
865 \c \S{man-foo-synopsis} SYNOPSIS
870 So when you're generating your main manual, you can include
871 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
872 pages you have, and your \cw{man} pages will be formatted neatly as
873 part of an appendix. Then, in a separate run of Halibut, you can
876 \c halibut appendix.but make-foo.but
878 and this will generate a \cw{man} page \c{output.1}, in which the
879 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
880 page for \c{make-foo}} will not be displayed because of the
881 \c{man-mindepth} directive. So the first visible heading in the
882 output \cw{man} page will be \q{NAME}, exactly as a user would
887 \S{output-man-characters} Configuring the characters used
889 \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}}
891 \dd Specifies what character set the output should be in, similarly to
892 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
894 \# FIXME: you're probably on your own in making sure that it's
895 sensible to output man pages in that charset.
897 \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
899 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
900 You can specify multiple fallback options. Works exactly like the
901 \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}).
903 \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{\}}]
905 \dd Specifies the quotation marks to use, overriding any
906 \cw{\\cfg\{quotes\}} directive. You can specify multiple
907 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
908 directive (see \k{output-text-characters}).
910 \S{output-man-defaults} Default settings
912 The \i{default settings} for the \cw{man} page output format are:
914 \c \cfg{man-filename}{output.1}
916 \c \cfg{man-identity}{}
918 \c \cfg{man-headnumbers}{false}
919 \c \cfg{man-mindepth}{0}
921 \c \cfg{man-charset}{ASCII}
922 \c \cfg{man-bullet}{\u2022}{o}
923 \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"}
925 \H{output-info} GNU \c{info}
927 This output format generates files which can be used with the \i{GNU
930 There are typically multiple output files: a primary file whose name
931 usually ends in \c{.info}, and one or more subsidiary files whose
932 names have numbers on the end, so that they end in \c{.info-1},
933 \c{.info-2} and so on. Alternatively, this output format can be
934 configured to output a single large file containing the whole
937 The \c{info} output format supports the following configuration
940 \S{output-info-file} Controlling the output filenames
942 \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}}
944 \dd Sets the output file name in which to store the \c{info} file.
945 This directive is implicitly generated if you provide a file name
946 parameter after the command-line option \i\c{--info} (see
947 \k{running-options}).
951 The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to
952 your output file name to produce any subsidiary files required.
954 Note that \c{info} files refer to their own names internally, so
955 these files cannot be \I{renaming \c{info} files}renamed after
956 creation and remain useful.
960 \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
962 \dd Sets the preferred \i{maximum file size} for each subsidiary
963 file. As a special case, if you set this to zero, there will be no
964 subsidiary files and the whole document will be placed in a single
965 self-contained output file. (However, note that this file can still
966 not be renamed usefully.)
970 The preferred maximum file size is only a guideline. Halibut may be
971 forced to exceed it if a single section of the document is larger
972 than the maximum size (since individual \c{info} nodes may not be
973 split between files).
977 \S{output-info-dimensions} Indentation and line width
979 \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}}
981 \dd Sets the \I{text width}width of the main part of the document,
982 in characters. Works exactly like the \cw{\\cfg\{text-width\}}
983 directive (see \k{output-text-dimensions}).
985 \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}}
987 \dd Specifies the extra indentation for \I{code paragraphs,
988 indentation} code paragraphs. Works exactly like the
989 \cw{\\cfg\{text-indent-code\}} directive (see
990 \k{output-text-dimensions}).
992 \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}}
994 \dd Specifies how much horizontal space to leave in the index node
995 for the text of \i{index terms}, before displaying the sections the
998 \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}}
1000 \dd Specifies the extra indentation before the bullet or number in a
1001 \I{bulletted list, indentation}\I{numbered list, indentation}list
1002 item. Works exactly like the \cw{\\cfg\{text-list-indent\}}
1003 directive (see \k{output-text-dimensions}).
1005 \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}}
1007 \dd Specifies the additional indentation before the body of a list
1008 item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}}
1009 directive (see \k{output-text-dimensions}).
1011 \S{output-info-headings} Configuring heading display
1013 \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}}
1015 \dd Specifies the suffix text to be appended to each section number
1016 before displaying the section title. For example, if you set this to
1017 \q{\cw{:\_}}, then a typical section title might look something like
1018 \q{Section 3.1: Something Like This}.
1020 \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1022 \dd Specifies the text to be used to underline section titles. Works
1023 very much like the \cw{\\cfg\{text-chapter-underline\}} directive
1024 (see \k{output-text-headings}). You can specify more than one
1025 option, and Halibut will choose the first one supported by the
1028 \S{output-info-characters} Controlling the characters used
1030 \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}}
1032 \dd Specifies what character set the output should be in, similarly to
1033 \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}).
1035 \# FIXME: if you try sufficiently hard, you can probably find an
1036 output encoding that will break the info format by trampling on its
1037 special characters. So either don't do that, or tell us what we should
1040 \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1042 \dd Specifies the text to use as the \i{bullet} in bulletted lists.
1043 You can specify multiple fallback options. Works exactly like the
1044 \cw{\\cfg\{text-bullet\}} directive (see
1045 \k{output-text-characters}).
1047 \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...]
1049 \dd Specifies the text used to draw \i{horizontal rules}. You can
1050 specify multiple fallback options. Works exactly like the
1051 \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}).
1053 \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{\}}]
1055 \dd Specifies the quotation marks to use, overriding any
1056 \cw{\\cfg\{quotes\}} directive. You can specify multiple
1057 fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}}
1058 directive (see \k{output-text-characters}).
1060 \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{\}}]
1062 \dd Specifies how to display emphasised text. You can specify
1063 multiple fallback options. Works exactly like the
1064 \cw{\\cfg\{text-emphasis\}} directive (see
1065 \k{output-text-characters}).
1067 \S{output-info-misc} Miscellaneous configuration options
1069 \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}}
1071 \dd Specifies the text to append to the item numbers in a
1072 \i{numbered list}. Works exactly like the
1073 \cw{\\cfg\{text-list-suffix\}} directive (see
1074 \k{output-text-misc}).
1076 \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
1077 name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}]
1079 \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the
1080 header of the Info file. This mechanism is used to automatically
1081 generate the \i{\c{dir} file} at the root of a Unix system's
1082 \c{info} collection.
1086 The parameters to this directive are:
1090 \dd Specifies the section of the \c{dir} file in which you want your
1091 document referenced. For example, \q{Development}, or \q{Games}, or
1096 \dd Specifies a short name for the directory entry, which will
1097 appear at the start of the menu line.
1101 \dd Specifies a long name for the directory entry, which will appear
1102 at the end of the menu line.
1106 \dd This parameter is optional. If it is present, then the directory
1107 entry will cause a jump to a particular subsection of your document,
1108 rather than starting at the top. The subsection will be the one
1109 referred to by the given keyword (see \k{input-sections} for details
1110 about assigning keywords to document sections).
1112 For example, in a document describing many game programs, the
1113 configuration directive
1115 \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess
1118 might produce text in the \c{dir} file looking something like this:
1121 \c * Chess: (mygames)Chapter 3. Electronic chess game
1123 if the output file were called \c{mygames.info} and the keyword
1124 \c{chess} had been used to define Chapter 3 of the document.
1128 \S{output-info-defaults} Default settings
1130 The \i{default settings} for the \c{info} output format are:
1132 \c \cfg{info-filename}{output.info}
1133 \c \cfg{info-max-file-size}{65536}
1135 \c \cfg{info-width}{70}
1136 \c \cfg{info-indent-code}{2}
1137 \c \cfg{info-index-width}{40}
1138 \c \cfg{info-list-indent}{1}
1139 \c \cfg{info-listitem-indent}{3}
1141 \c \cfg{info-section-suffix}{: }
1142 \c \cfg{info-underline}{\u203e}{-}
1144 \c \cfg{info-charset}{ASCII}
1145 \c \cfg{info-bullet}{\u2022}{-}
1146 \c \cfg{info-rule}{\u2500}{-}
1147 \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'}
1148 \c \cfg{info-emphasis}{_}{_}
1150 \c \cfg{info-list-suffix}{.}
1152 and no \cw{\\cfg\{info-dir-entry\}} directives.
1154 \H{output-ps} \i{PostScript}
1156 This output format generates a printable manual in PostScript format.
1158 This format is currently very new and is not yet configurable. There
1159 is only one available configuration option:
1161 \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}}
1163 \dd Sets the \i{output file name} in which to store the PostScript
1164 file. This directive is implicitly generated if you provide a file
1165 name parameter after the command-line option \i\c{--ps} (see
1166 \k{running-options}).
1168 The \i{default settings} for the PostScript output format are:
1170 \c \cfg{ps-filename}{output.ps}
1172 \H{output-pdf} \i{PDF}
1174 This output format generates a printable manual in PDF format. This
1175 should look exactly identical to the PostScript output (see
1176 \k{output-ps}), but also uses some PDF interactive features to
1177 provide an outline of all the document's sections and clickable
1178 cross-references between sections.
1180 This format is currently very new and is not yet configurable. There
1181 is only one available configuration option:
1183 \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}}
1185 \dd Sets the \i{output file name} in which to store the PDF file.
1186 This directive is implicitly generated if you provide a file name
1187 parameter after the command-line option \i\c{--pdf} (see
1188 \k{running-options}).
1190 The \i{default settings} for the PDF output format are:
1192 \c \cfg{pdf-filename}{output.pdf}