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, under the name \i\c{output.txt}.
13 The output file is currently assumed to be in the \i{ISO 8859-1}
14 character set. Any Unicode characters representable in this set will
15 be output verbatim; any other characters will not be output and
16 their \i{fallback text} (if any) will be used instead.
18 The precise formatting of the text file can be controlled by a
19 variety of configuration directives. They are listed in the
20 following subsections.
22 \S{output-text-dimensions} Indentation and line width
24 This section describes the configuration directives which control
25 the \i{horizontal dimensions} of the output text file: how much
26 paragraphs are indented by and how long the lines are.
28 \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}}
30 \dd Sets the \I{text width}width of the main part of the document,
31 in characters. This width will be used for wrapping paragraphs and
32 for centring titles (if you have asked for titles to be centred -
33 see \k{output-text-headings}). This width does \e{not} include the
34 left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an
35 indent of 8 and a width of 64, your maximum output line length will
38 \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}}
40 \dd Sets the left \i{indentation} for the document. If you set this
41 to zero, your document will look like an ordinary text file as
42 someone with a text editor might have written it; if you set it
43 above zero, the text file will have a \i{margin} down the left in
44 the style of some printed manuals, and you can then configure the
45 section numbers to appear in this margin (see
46 \k{output-text-headings}).
48 \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}}
50 \dd Specifies how many extra characters of indentation (on top of
51 the normal left indent) should be given to \I{code paragraphs,
52 indentation} code paragraphs.
54 \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}}
56 \dd Specifies how many extra spaces should be used to indent the
57 bullet or number in a \I{bulletted list, indentation}bulletted or
58 \I{numbered list, indentation}numbered \I{list, indentation}list.
59 The actual body of the list item will be indented by this much
60 \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}.
62 \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}}
64 \dd Specifies how many extra spaces should be used to indent the
65 body of a list item, over and above the number configured in
66 \cw{\\cfg\{text-list-indent\}}.
68 \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}}
70 \dd When this is set to \c{true}, the document \i{preamble} (i.e. any
71 paragraphs appearing before the first chapter heading) will be
72 indented to the level specified by \cw{\\cfg\{text-indent\}}. If
73 this setting is \c{false}, the document preamble will not be
74 indented at all from the left margin.
76 \S{output-text-headings} \ii{Configuring heading display}
78 The directives in this section allow you to configure the appearance
79 of the title, chapter and section headings in your text file.
81 Several of the directives listed below specify the \i{alignment} of
82 a heading. These alignment options have three possible values:
86 \dd Align the heading to the very left of the text file (column zero).
90 \dd Align the section title to the left of the main display region
91 (in other words, indented to the level specified by
92 \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the
93 left of that (so that it goes in the margin if there is room).
97 \dd Centre the heading.
99 Also, several of the directives below specify how a title should be
100 \I{underlining}underlined. The parameter to one of these directives
101 should be either blank (\cw{\{\}}) or a single character. In the
102 latter case, that character will be used to underline the title. So
103 you might want to specify, for example,
104 \cw{\\text-title-underline\{=\}} but
105 \cw{\\text-chapter-underline\{-\}}.
107 \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}}
109 \dd Specifies the alignment of the overall document title: \c{left},
110 \c{leftplus} or \c{centre}.
112 \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}}
114 \dd Specifies how the overall document title should be underlined.
116 \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}}
118 \dd Specifies the alignment of chapter and appendix headings.
120 \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}}
122 \dd Specifies how chapter and appendix headings should be underlined.
124 \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}}
126 \dd If this is set to \c{true}, then chapter headings will not
127 contain the word \q{Chapter} (or whatever other word you have
128 defined in its place - see \k{input-sections} and \k{input-config});
129 they will just contain the chapter \e{number}, followed by the
130 chapter title. If you set this to \c{false}, chapter headings will
131 be prefixed by \q{Chapter} or equivalent.
133 \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}}
135 \dd This specifies the suffix text to be appended to the chapter
136 number, before displaying the chapter title. For example, if you set
137 this to \q{\cw{:\_}}, then the chapter title might look something
138 like \q{Chapter 2: Doing Things}.
140 \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}}
142 \dd Specifies the alignment of section headings at a particular
143 level. The \e{level} parameter specifies which level of section
144 headings you want to affect: 0 means first-level headings (\c{\\H}),
145 1 means second-level headings (\c{\\S}), 2 means the level below
146 that (\c{\\S2}), and so on. The \e{alignment} parameter is treated
147 just like the other alignment directives listed above.
149 \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}}
151 \dd Specifies how to underline section headings at a particular level.
153 \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}}
155 \dd Specifies whether section headings at a particular level should
156 contain the word \q{Section} or equivalent (if \c{false}), or should
157 be numeric only (if \c{true}).
159 \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}
161 \dd Specifies the \I{suffix text, in section titles}suffix text to
162 be appended to section numbers at a particular level, before
163 displaying the section title.
165 \S{output-text-misc} Miscellaneous configuration options
167 \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}}
169 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined
170 using the \i\c{\\versionid} command - see \k{input-blurb}) will be
171 included at the bottom of the text file. If it is set to \c{false},
172 they will be omitted completely.
174 \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}
176 \dd This specifies the text which should be used as the \i{bullet}
177 in bulletted lists. It can be one character
178 (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one
179 (\cw{\\cfg\{text-bullet\}\{(*)\}}).
181 \# FIXME: code indentation is configurable, therefore \quote
182 \# indentation probably ought to be as well.
184 \# FIXME: text-indent-* should be consistently named.
186 \S{output-text-defaults} Default settings
188 The \i{default settings} for Halibut's plain text output format are:
190 \c \cfg{text-width}{68}
191 \c \cfg{text-indent}{7}
192 \c \cfg{text-indent-code}{2}
193 \c \cfg{text-list-indent}{1}
194 \c \cfg{text-listitem-indent}{3}
195 \c \cfg{text-indent-preamble}{false}
197 \c \cfg{text-title-align}{centre}
198 \c \cfg{text-title-underline}{=}
200 \c \cfg{text-chapter-align}{left}
201 \c \cfg{text-chapter-underline}{-}
202 \c \cfg{text-chapter-numeric}{false}
203 \c \cfg{text-chapter-suffix}{: }
205 \c \cfg{text-section-align}{0}{leftplus}
206 \c \cfg{text-section-underline}{0}{}
207 \c \cfg{text-section-numeric}{0}{true}
208 \c \cfg{text-section-suffix}{0}{ }
210 \c \cfg{text-section-align}{1}{leftplus}
211 \c \cfg{text-section-underline}{1}{}
212 \c \cfg{text-section-numeric}{1}{true}
213 \c \cfg{text-section-suffix}{1}{ }
215 \c ... and so on for all section levels below this ...
216 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
220 This output format generates an \i{HTML} version of the document. By
221 default, this will be in multiple files, starting with
222 \c{Contents.html} and splitting the document into files by chapter
223 and/or subsection. You can configure precisely how the text is split
224 between HTML files using the configuration commands described in
225 this section. In particular, you can configure Halibut to output one
226 single HTML file instead of multiple ones, in which case it will be
227 called \c{Manual.html} (but you can rename it easily enough).
229 Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
230 which is why all of the configuration directives start with the word
231 \c{xhtml} rather than \c{html}.
233 \S{output-html-split} Controlling the splitting into HTML files
235 By default, the HTML output from Halibut is split into multiple
236 files. Each file typically contains a single chapter or section and
237 everything below it, unless subsections of that chapter are
238 themselves split off into further files.
240 Most files also contain a contents section, giving hyperlinks to the
241 sections in the file and/or the sections below it.
243 The configuration directives listed below allow you to configure the
244 splitting into files, and the details of the contents sections.
246 \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}}
248 \dd This setting indicates the depth of section which should be
249 given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if
250 you set it to 1, for example, then every chapter will be given its
251 own HTML file, plus a top-level \i{contents file}. If you set this
252 to 2, then each chapter \e{and} each \c{\\H} section will have a
253 file, and the chapter files will mostly just contain links to their
258 If you set this option to zero, then the whole document will appear
259 in a single file. If you do this, Halibut will call that file
260 \i\c{Manual.html} instead of \i\c{Contents.html}.
264 \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
266 \dd This directive allows you to specify how \I{depth of
267 contents}deep the contents section in a particular file should go.
271 The \e{level} parameter indicates which level of contents section
272 you are dealing with. 0 denotes the main contents section in the
273 topmost file \c{Contents.html}; 1 denotes a contents section in a
274 chapter file; 2 is a contents section in a file containing a \c{\\H}
275 heading, and so on. Currently you can't go below level 5 (which
276 corresponds to a \c{\\S3} heading).
278 The \e{depth} parameter indicates the maximum depth of heading which
279 will be shown in this contents section. Again, 1 denotes a chapter,
280 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on.
282 So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs
283 Halibut to put contents links in chapter files for all sections down
284 to \c{\\S} level, but not to go into any more detail than that.
288 \# FIXME: this is utterly ghastly. For a start, it should include
289 \# the level as a separate argument, like the text section config
290 \# directives. Secondly, it shouldn't be limited in depth!
292 \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}}
294 \dd If you set this to \c{true}, then each leaf file will contain
295 its own contents section which summarises the text within it.
297 \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}}
299 \dd Contents sections in leaf files are not output at all if they
300 contain very few entries (on the assumption that it just isn't worth
301 bothering). This directive configures the minimum number of entries
302 required in a leaf contents section to make Halibut bother
303 generating it at all.
305 \S{output-html-html} Including pieces of your own HTML
307 The directives in this section allow you to supply pieces of
308 \I{HTML}\i{verbatim HTML} code, which will be included in various
309 parts of the output files.
311 \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}}
313 \dd The text you provide in this directive is placed at the end of
314 the \i\cw{<HEAD>} section of each output HTML file. So this is a
315 good place to put, for example, a link to a \i{CSS} \i{stylesheet}.
317 \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}}
319 \dd The text you provide in this directive is used in place of the
320 \i\cw{<BODY>} tag in each output file. So if you wanted to define a
321 \i{background colour}, for example, you could write
322 \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}.
324 \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}}
326 \dd The text you provide in this directive is placed at the
327 beginning of the \i\cw{<BODY>} section of each output HTML file. So
328 if you intend your HTML files to be part of a web site with a
329 standard \i{house style}, and the style needs a \i{header} at the
330 top of every page, this is where you can add that header.
332 \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}}
334 \dd The text you provide in this directive is placed at the end of
335 the \i\cw{<BODY>} section of each output HTML file. So if you intend
336 your HTML files to be part of a web site with a standard \i{house
337 style}, and the style needs a \i{footer} at the bottom of every
338 page, this is where you can add that footer.
340 \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}}
342 \dd The text you provide in this directive is placed at the
343 beginning of the \i\cw{<ADDRESS>} section at the bottom of each
344 output HTML file. This might be a good place to put authors'
345 \i{contact details}, for example.
347 \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}}
349 \dd The text you provide in this directive is placed at the end of
350 the \i\cw{<ADDRESS>} section at the bottom of each output HTML file,
351 after the version IDs (if present).
353 \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}}
355 \dd The text you provide in this directive is included inside the
356 \cw{<P>} tag containing the \i{navigation links} at the top of each
357 page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you
358 wanted the navigation links to have a particular CSS style, you
360 \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the
361 navigation-links paragraph would then begin with the tag \cw{<p
364 \S{output-html-headings} \ii{Configuring heading display}
366 \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}}
368 \dd If this is set to \c{true}, then chapter headings will not
369 contain the word \q{Chapter} (or whatever other word you have
370 defined in its place - see \k{input-sections} and \k{input-config});
371 they will just contain the chapter \e{number}, followed by the
372 chapter title. If you set this to \c{false}, chapter headings will
373 be prefixed by \q{Chapter} or equivalent.
375 \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}}
377 \dd This specifies the suffix text to be appended to the chapter
378 number, before displaying the chapter title. For example, if you set
379 this to \q{\cw{:\_}}, then the chapter title might look something
380 like \q{Chapter 2: Doing Things}.
382 \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{boolean}\cw{\}}
384 \dd Specifies whether section headings at a particular level should
385 contain the word \q{Section} or equivalent (if \c{false}), or should
386 be numeric only (if \c{true}). The \e{level} parameter specifies
387 which level of section headings you want to affect: 0 means
388 first-level headings (\c{\\H}), 1 means second-level headings
389 (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on.
391 \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{text}\cw{\}}
393 \dd Specifies the suffix text to be appended to section numbers at a
394 particular level, before displaying the section title.
396 \S{output-html-misc} Miscellaneous options
398 \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
400 \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
401 the \i\c{\\versionid} command - see \k{input-blurb}) will be included
402 visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML
403 file. If it is set to \c{false}, they will be omitted completely.
405 \# FIXME: surely it would be better to include them in HTML
406 \# comments? The only question is whether they should be _visible_.
408 \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}}
410 \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the
411 bottom of each HTML file will be omitted completely. (This will
412 therefore also cause \i{version IDs} not to be included.)
414 \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}}
416 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
417 name="author">} tag in the output HTML files, so that browsers which
418 support this can automatically identify the \i{author} of the document.
420 \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}}
422 \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META
423 name="description">} tag in the output HTML files, so that browsers
424 which support this can easily pick out a brief \I{description, of
425 document}description of the document.
427 \S{output-html-defaults} Default settings
429 The \i{default settings} for Halibut's HTML output format are:
431 \c \cfg{xhtml-leaf-level}{2}
432 \c \cfg{xhtml-leaf-contains-contents}{false}
433 \c \cfg{xhtml-leaf-smallest-contents}{4}
434 \c \cfg{xhtml-contents-depth-0}{2}
435 \c \cfg{xhtml-contents-depth-1}{3}
436 \c \cfg{xhtml-contents-depth-2}{4}
437 \c \cfg{xhtml-contents-depth-3}{5}
438 \c \cfg{xhtml-contents-depth-4}{6}
439 \c \cfg{xhtml-contents-depth-5}{7}
441 \c \cfg{xhtml-head-end}{}
442 \c \cfg{xhtml-body-tag}{<body>}
443 \c \cfg{xhtml-body-start}{}
444 \c \cfg{xhtml-body-end}{}
445 \c \cfg{xhtml-address-start}{}
446 \c \cfg{xhtml-address-end}{}
447 \c \cfg{xhtml-navigation-attributes}{}
449 \c \cfg{xhtml-versionid}{true}
450 \c \cfg{xhtml-suppress-address}{false}
451 \c \cfg{xhtml-author}{}
452 \c \cfg{xhtml-description}{}
454 \c \cfg{xhtml-chapter-numeric}{false}
455 \c \cfg{xhtml-chapter-suffix}{: }
457 \c \cfg{xhtml-section-numeric}{0}{true}
458 \c \cfg{xhtml-section-suffix}{0}{ }
460 \c \cfg{xhtml-section-numeric}{1}{true}
461 \c \cfg{xhtml-section-suffix}{1}{ }
463 \c ... and so on for all section levels below this ...
464 \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
466 \H{output-whlp} Windows Help
468 This output format generates data that can be used by the \i{Windows
469 Help} program \cw{WINHELP.EXE}. There are two actual files generated,
470 called \c{output.hlp} and \c{output.cnt}. (You can rename them both
471 with no problems; they don't depend on keeping those filenames. You
472 just have to make sure that the two names are related in this way,
473 so that \c{.hlp} on the end of one name is replaced by \c{.cnt} on
474 the end of the other.)
476 The Windows Help output format is currently not configurable at all;
477 all formatting decisions are fixed. However, there is one
478 configuration directive you can use, which is not so much
479 \e{configuration} as extra functionality:
481 \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
483 \dd This directive defines a Windows \i{Help topic} name in the current
484 section. Topic names can be used by the program invoking
485 \cw{WINHELP.EXE} to jump straight to a particular section. So you
486 can use this for \i{context-sensitive help}.
490 For example, if you used this directive in a particular section:
492 \c \cfg{winhelp-topic}{savingfiles}
494 then a Windows application could invoke Windows Help to jump to that
495 particular section in the help file like this:
497 \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND,
498 \c (DWORD)"JI(`',`savingfiles')");
500 You can use this configuration directive many times, in many
501 different subsections of your document, in order to define a lot of
502 different help contexts which you can use in this way.
506 \H{output-man} Unix \cw{man} pages
508 This output format generates a Unix \i{\cw{man} page}. That is to say,
509 it generates \i\c{nroff} input designed to work with the \c{-mandoc}
512 The available configuration options for this format are as follows:
514 \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
516 \dd This directive is used to generate the initial \i{\c{.TH}
517 directive} that appears at the top of a \cw{man} page. It expects to
518 be followed by some number of brace pairs containing text, which will
519 be used in the \i{headers} and \i{footers} of the formatted output.
523 A traditional order for the arguments appears to be:
525 \n The name of the program.
527 \n The (numeric) manual section.
529 \n The date that the \cw{man} page was written.
531 \n The name of any containing suite of which the program is a part.
533 \n The name of the \i{author} of the \cw{man} page.
535 For example, a typical \cw{man} page might contain
537 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs}
541 \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}}
543 \dd If this is set to \c{true}, then \i{section headings} in the
544 \cw{man} page will have their \i{section numbers} displayed as usual. If
545 set to \c{false}, the section numbers will be omitted. (\cw{man}
546 pages traditionally have section names such as \q{SYNOPSIS},
547 \q{OPTIONS} and \q{BUGS}, and do not typically number them, so
548 \c{false} is the setting which conforms most closely to normal
551 \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}}
553 \dd If this is set to a number greater than 0, then section headings
554 \e{higher} than the given depth will not be displayed. If it is set
555 to zero, all section headings will be displayed as normal.
559 The point of this is so that you can use the same Halibut input file
560 to generate a quick-reference \cw{man} page for a program, \e{and} to
561 include that \cw{man} page as an appendix in your program's full manual.
562 If you are to include the \cw{man} page as an appendix, then the internal
563 headings within the page will probably need to be at \c{\\H} or
564 \c{\\S} level; therefore, when you format that input file on its own
565 to create the \cw{man} page itself, you will need to have defined a
566 \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't
567 want to see displayed.
569 Here's an example. You might have a file \c{appendix.but}, which
572 \c \A{manpages} \cw{man} pages for the Foo tool suite
574 \c \cfg{man-mindepth}{2}
576 Then you have a file \c{make-foo.but}, and probably others like it
577 as well, each of which looks something like this:
579 \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs}
581 \c \H{man-foo} \cw{man} page for \c{make-foo}
583 \c \S{man-foo-name} NAME
585 \c \c{make-foo} - create Foo files for the Foo tool suite
587 \c \S{man-foo-synopsis} SYNOPSIS
592 So when you're generating your main manual, you can include
593 \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man}
594 pages you have, and your \cw{man} pages will be formatted neatly as
595 part of an appendix. Then, in a separate run of Halibut, you can
598 \c halibut appendix.but make-foo.but
600 and this will generate a \cw{man} page \c{output.1}, in which the
601 headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man}
602 page for \c{make-foo}} will not be displayed because of the
603 \c{man-mindepth} directive. So the first visible heading in the
604 output \cw{man} page will be \q{NAME}, exactly as a user would
609 The \i{default settings} for the \cw{man} page output format are:
611 \c \cfg{man-identity}{}
612 \c \cfg{man-headnumbers}{false}
613 \c \cfg{man-mindepth}{0}