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