| 1 | \versionid $Id$ |
| 2 | |
| 3 | \C{output} Halibut output formats |
| 4 | |
| 5 | This chapter describes each of Halibut's current \i{output formats}. |
| 6 | It gives some general information about the format, and also |
| 7 | describes all the \i{configuration directives} which are specific to |
| 8 | that format. |
| 9 | |
| 10 | \H{output-text} Plain text |
| 11 | |
| 12 | This output format generates the document as a single \i{plain text} |
| 13 | file. No table of contents or index is generated. |
| 14 | |
| 15 | The precise formatting of the text file can be controlled by a |
| 16 | variety of configuration directives. They are listed in the |
| 17 | following subsections. |
| 18 | |
| 19 | \S{output-text-file} Output file name |
| 20 | |
| 21 | \dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}} |
| 22 | |
| 23 | \dd Sets the \i{output file name} in which to store the text file. |
| 24 | This directive is implicitly generated if you provide a file name |
| 25 | parameter after the command-line option \i\c{--text} (see |
| 26 | \k{running-options}). |
| 27 | |
| 28 | \S{output-text-dimensions} Indentation and line width |
| 29 | |
| 30 | This section describes the configuration directives which control |
| 31 | the \i{horizontal dimensions} of the output text file: how much |
| 32 | paragraphs are indented by and how long the lines are. |
| 33 | |
| 34 | \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}} |
| 35 | |
| 36 | \dd Sets the \I{text width}width of the main part of the document, |
| 37 | in characters. This width will be used for wrapping paragraphs and |
| 38 | for centring titles (if you have asked for titles to be centred - |
| 39 | see \k{output-text-headings}). This width does \e{not} include the |
| 40 | left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an |
| 41 | indent of 8 and a width of 64, your maximum output line length will |
| 42 | be 72. |
| 43 | |
| 44 | \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}} |
| 45 | |
| 46 | \dd Sets the left \i{indentation} for the document. If you set this |
| 47 | to zero, your document will look like an ordinary text file as |
| 48 | someone with a text editor might have written it; if you set it |
| 49 | above zero, the text file will have a \i{margin} down the left in |
| 50 | the style of some printed manuals, and you can then configure the |
| 51 | section numbers to appear in this margin (see |
| 52 | \k{output-text-headings}). |
| 53 | |
| 54 | \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}} |
| 55 | |
| 56 | \dd Specifies how many extra characters of indentation (on top of |
| 57 | the normal left indent) should be given to \I{code paragraphs, |
| 58 | indentation} code paragraphs. |
| 59 | |
| 60 | \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}} |
| 61 | |
| 62 | \dd Specifies how many extra spaces should be used to indent the |
| 63 | bullet or number in a \I{bulletted list, indentation}bulletted or |
| 64 | \I{numbered list, indentation}numbered \I{list, indentation}list. |
| 65 | The actual body of the list item will be indented by this much |
| 66 | \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}. |
| 67 | |
| 68 | \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}} |
| 69 | |
| 70 | \dd Specifies how many extra spaces should be used to indent the |
| 71 | body of a list item, over and above the number configured in |
| 72 | \cw{\\cfg\{text-list-indent\}}. |
| 73 | |
| 74 | \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}} |
| 75 | |
| 76 | \dd When this is set to \c{true}, the document \i{preamble} (i.e. any |
| 77 | paragraphs appearing before the first chapter heading) will be |
| 78 | indented to the level specified by \cw{\\cfg\{text-indent\}}. If |
| 79 | this setting is \c{false}, the document preamble will not be |
| 80 | indented at all from the left margin. |
| 81 | |
| 82 | \S{output-text-headings} \ii{Configuring heading display} |
| 83 | |
| 84 | The directives in this section allow you to configure the appearance |
| 85 | of the title, chapter and section headings in your text file. |
| 86 | |
| 87 | Several of the directives listed below specify the \i{alignment} of |
| 88 | a heading. These alignment options have three possible values: |
| 89 | |
| 90 | \dt \i\c{left} |
| 91 | |
| 92 | \dd Align the heading to the very left of the text file (column zero). |
| 93 | |
| 94 | \dt \i\c{leftplus} |
| 95 | |
| 96 | \dd Align the section title to the left of the main display region |
| 97 | (in other words, indented to the level specified by |
| 98 | \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the |
| 99 | left of that (so that it goes in the margin if there is room). |
| 100 | |
| 101 | \dt \i\c{centre} |
| 102 | |
| 103 | \dd Centre the heading. |
| 104 | |
| 105 | Also, several of the directives below specify how a title should be |
| 106 | \I{underlining}underlined. The parameter to one of these directives |
| 107 | should be either blank (\cw{\{\}}) or a piece of text which will be |
| 108 | repeated to produce the underline. So you might want to specify, for |
| 109 | example, \cw{\\text-title-underline\{=\}} but |
| 110 | \cw{\\text-chapter-underline\{\-\}}. |
| 111 | |
| 112 | You can also specify more than one underline setting, and Halibut |
| 113 | will choose the first one that the output character set supports. |
| 114 | So, for example, you could write |
| 115 | \cw{\\text-chapter-underline\{\\u203e\}\{\-\}}, and Halibut would use |
| 116 | the Unicode \q{OVERLINE} character where possible and fall back to |
| 117 | the ASCII minus sign otherwise. |
| 118 | |
| 119 | \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}} |
| 120 | |
| 121 | \dd Specifies the alignment of the overall document title: \c{left}, |
| 122 | \c{leftplus} or \c{centre}. |
| 123 | |
| 124 | \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-text}\cw{\}} |
| 125 | |
| 126 | \dd Specifies how the overall document title should be underlined. |
| 127 | |
| 128 | \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}} |
| 129 | |
| 130 | \dd Specifies the alignment of chapter and appendix headings. |
| 131 | |
| 132 | \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-text}\cw{\}} |
| 133 | |
| 134 | \dd Specifies how chapter and appendix headings should be underlined. |
| 135 | |
| 136 | \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}} |
| 137 | |
| 138 | \dd If this is set to \c{true}, then chapter headings will not |
| 139 | contain the word \q{Chapter} (or whatever other word you have |
| 140 | defined in its place - see \k{input-sections} and \k{input-config}); |
| 141 | they will just contain the chapter \e{number}, followed by the |
| 142 | chapter title. If you set this to \c{false}, chapter headings will |
| 143 | be prefixed by \q{Chapter} or equivalent. |
| 144 | |
| 145 | \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}} |
| 146 | |
| 147 | \dd This specifies the suffix text to be appended to the chapter |
| 148 | number, before displaying the chapter title. For example, if you set |
| 149 | this to \cq{:\_}, then the chapter title might look something |
| 150 | like \q{Chapter 2: Doing Things}. |
| 151 | |
| 152 | \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}} |
| 153 | |
| 154 | \dd Specifies the alignment of section headings at a particular |
| 155 | level. The \e{level} parameter specifies which level of section |
| 156 | headings you want to affect: 0 means first-level headings (\c{\\H}), |
| 157 | 1 means second-level headings (\c{\\S}), 2 means the level below |
| 158 | that (\c{\\S2}), and so on. The \e{alignment} parameter is treated |
| 159 | just like the other alignment directives listed above. |
| 160 | |
| 161 | \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-text}\cw{\}} |
| 162 | |
| 163 | \dd Specifies how to underline section headings at a particular level. |
| 164 | |
| 165 | \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} |
| 166 | |
| 167 | \dd Specifies whether section headings at a particular level should |
| 168 | contain the word \q{Section} or equivalent (if \c{false}), or should |
| 169 | be numeric only (if \c{true}). |
| 170 | |
| 171 | \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} |
| 172 | |
| 173 | \dd Specifies the \I{suffix text, in section titles}suffix text to |
| 174 | be appended to section numbers at a particular level, before |
| 175 | displaying the section title. |
| 176 | |
| 177 | \S{output-text-characters} Configuring the characters used |
| 178 | |
| 179 | \dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}} |
| 180 | |
| 181 | \dd This tells Halibut what \i{character set} the output should be |
| 182 | in. Any Unicode characters representable in this set will be output |
| 183 | verbatim; any other characters will not be output and their |
| 184 | \i{fallback text} (if any) will be used instead. |
| 185 | |
| 186 | \lcont{ |
| 187 | |
| 188 | The character set names are the same as for |
| 189 | \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike |
| 190 | \cw{\\cfg\{input-charset\}}, this directive affects the \e{entire} |
| 191 | output; it's not possible to switch encodings halfway through. |
| 192 | |
| 193 | } |
| 194 | |
| 195 | \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] |
| 196 | |
| 197 | \dd This specifies the text which should be used as the \i{bullet} |
| 198 | in bulletted lists. It can be one character |
| 199 | (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one |
| 200 | (\cw{\\cfg\{text-bullet\}\{(*)\}}). |
| 201 | |
| 202 | \lcont{ |
| 203 | |
| 204 | Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple |
| 205 | possible options after this command, and Halibut will choose the first one |
| 206 | which the output character set supports. For example, you might write |
| 207 | \cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case |
| 208 | Halibut would use the Unicode \q{BULLET} character where possible, |
| 209 | fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available, |
| 210 | and resort to the ASCII asterisk if all else failed. |
| 211 | |
| 212 | } |
| 213 | |
| 214 | \dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] |
| 215 | |
| 216 | \dd This specifies the text which should be used for drawing |
| 217 | \i{horizontal rules} (generated by \i\c{\\rule}; see |
| 218 | \k{input-rule}). It can be one character, or more than one. The |
| 219 | string you specify will be repeated to reach the required width, so |
| 220 | you can specify something like \cq{-=} to get a rule that looks |
| 221 | like \cw{-=-=-=}. |
| 222 | |
| 223 | \lcont{ |
| 224 | |
| 225 | Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback |
| 226 | options in this command. |
| 227 | |
| 228 | } |
| 229 | |
| 230 | \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{\}}] |
| 231 | |
| 232 | \dd This specifies a set of quote characters for the text backend, |
| 233 | overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax |
| 234 | (see \k{input-config}). |
| 235 | |
| 236 | \lcont{ |
| 237 | |
| 238 | In this backend, these quotes will also be used to mark text enclosed |
| 239 | in the \c{\\c} command (see \k{input-code}). |
| 240 | |
| 241 | } |
| 242 | |
| 243 | \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{\}}] |
| 244 | |
| 245 | \dd This specifies the characters which should be used to surround |
| 246 | emphasised text (written using the \c{\\e} command; see |
| 247 | \k{input-emph}). |
| 248 | |
| 249 | \lcont{ |
| 250 | |
| 251 | You should separately specify the start-emphasis and end-emphasis |
| 252 | text, each of which can be more than one character if you want. |
| 253 | Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs |
| 254 | of fallback options in this command, and Halibut will always use a |
| 255 | matching pair. |
| 256 | |
| 257 | } |
| 258 | |
| 259 | \S{output-text-misc} Miscellaneous configuration options |
| 260 | |
| 261 | \dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}} |
| 262 | |
| 263 | \dd This text is appended to the number on a \i{numbered list} item |
| 264 | (see \k{input-list-number}). So if you want to label your lists as |
| 265 | \q{1)}, \q{2)} and so on, then you would write |
| 266 | \cw{\\cfg\{text-list-suffix\}\{)\}}. |
| 267 | |
| 268 | \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}} |
| 269 | |
| 270 | \dd If this is set to \c{true}, \i{version ID paragraphs} (defined |
| 271 | using the \i\c{\\versionid} command - see \k{input-blurb}) will be |
| 272 | included at the bottom of the text file. If it is set to \c{false}, |
| 273 | they will be omitted completely. |
| 274 | |
| 275 | \# FIXME: code indentation is configurable, therefore \quote |
| 276 | \# indentation probably ought to be as well. |
| 277 | |
| 278 | \# FIXME: text-indent-* should be consistently named. |
| 279 | |
| 280 | \S{output-text-defaults} Default settings |
| 281 | |
| 282 | The \i{default settings} for Halibut's plain text output format are: |
| 283 | |
| 284 | \c \cfg{text-filename}{output.txt} |
| 285 | \c |
| 286 | \c \cfg{text-width}{68} |
| 287 | \c \cfg{text-indent}{7} |
| 288 | \c \cfg{text-indent-code}{2} |
| 289 | \c \cfg{text-list-indent}{1} |
| 290 | \c \cfg{text-listitem-indent}{3} |
| 291 | \c \cfg{text-indent-preamble}{false} |
| 292 | \c |
| 293 | \c \cfg{text-title-align}{centre} |
| 294 | \c \cfg{text-title-underline}{\u2550}{=} |
| 295 | \c |
| 296 | \c \cfg{text-chapter-align}{left} |
| 297 | \c \cfg{text-chapter-underline}{\u203e}{-} |
| 298 | \c \cfg{text-chapter-numeric}{false} |
| 299 | \c \cfg{text-chapter-suffix}{: } |
| 300 | \c |
| 301 | \c \cfg{text-section-align}{0}{leftplus} |
| 302 | \c \cfg{text-section-underline}{0}{} |
| 303 | \c \cfg{text-section-numeric}{0}{true} |
| 304 | \c \cfg{text-section-suffix}{0}{ } |
| 305 | \c |
| 306 | \c \cfg{text-section-align}{1}{leftplus} |
| 307 | \c \cfg{text-section-underline}{1}{} |
| 308 | \c \cfg{text-section-numeric}{1}{true} |
| 309 | \c \cfg{text-section-suffix}{1}{ } |
| 310 | \c |
| 311 | \c ... and so on for all section levels below this ... |
| 312 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
| 313 | \c |
| 314 | \c \cfg{text-charset}{ASCII} |
| 315 | \c \cfg{text-bullet}{\u2022}{-} |
| 316 | \c \cfg{text-rule}{\u2500}{-} |
| 317 | \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'} |
| 318 | \c \cfg{text-emphasis}{_}{_} |
| 319 | \c |
| 320 | \c \cfg{text-list-suffix}{.} |
| 321 | \c \cfg{text-versionid}{true} |
| 322 | |
| 323 | \H{output-html} HTML |
| 324 | |
| 325 | This output format generates an \i{HTML} version of the document. By |
| 326 | default, this will be in multiple files, starting with |
| 327 | \c{Contents.html} and splitting the document into files by chapter |
| 328 | and/or subsection. You can configure precisely how the text is split |
| 329 | between HTML files using the configuration commands described in |
| 330 | this section. In particular, you can configure Halibut to output one |
| 331 | single HTML file instead of multiple ones. |
| 332 | |
| 333 | \I{\cw{\\cfg\{xhtml-anything\}}}Configuration directives with an |
| 334 | \c{xhtml-} prefix are synonyms for those with an \c{html-} prefix. |
| 335 | |
| 336 | \S{output-html-file} Controlling the output file names |
| 337 | |
| 338 | \dt \I{\cw{\\cfg\{html-contents-filename\}}}\cw{\\cfg\{html-contents-filename\}\{}\e{filename}\cw{\}} |
| 339 | |
| 340 | \dd Sets the \i{output file name} in which to store the top-level |
| 341 | contents page. Since this is the first page a user ought to see when |
| 342 | beginning to read the document, a good choice in many cases might be |
| 343 | \c{index.html} (although this is not the default, for historical |
| 344 | reasons). |
| 345 | |
| 346 | \dt \I{\cw{\\cfg\{html-index-filename\}}}\cw{\\cfg\{html-index-filename\}\{}\e{filename}\cw{\}} |
| 347 | |
| 348 | \dd Sets the file name in which to store the document's index. |
| 349 | |
| 350 | \dt \I{\cw{\\cfg\{html-template-filename\}}}\cw{\\cfg\{html-template-filename\}\{}\e{template}\cw{\}} |
| 351 | |
| 352 | \dd Provides a \i{template} to be used when constructing the file |
| 353 | names of each chapter or section of the document. This template |
| 354 | should contain at least one \i\e{formatting command}, in the form of |
| 355 | a per cent sign followed by a letter. (If you need a literal per |
| 356 | cent sign, you can write \c{%%}.) |
| 357 | |
| 358 | \lcont{ |
| 359 | |
| 360 | The formatting commands used in this template are: |
| 361 | |
| 362 | \dt \I{%N-upper}\c{%N} |
| 363 | |
| 364 | \dd Expands to the visible title of the section, with white space |
| 365 | removed. So in a chapter declared as \cq{\\C\{fish\} Catching |
| 366 | Fish}, this formatting command would expand to |
| 367 | \cq{CatchingFish}. |
| 368 | |
| 369 | \dt \i\c{%n} |
| 370 | |
| 371 | \dd Expands to the type and number of the section, without white |
| 372 | space. So in chapter 1 this would expand to \cq{Chapter1}; in |
| 373 | section A.4.3 it would expand to \cq{SectionA.4.3}, and so on. |
| 374 | If the section has no number (an unnumbered chapter created using |
| 375 | \c{\\U}), this directive falls back to doing the same thing as |
| 376 | \c{%N}. |
| 377 | |
| 378 | \dt \i\c{%b} |
| 379 | |
| 380 | \dd Expands to the number of the section, in a format suitable for an |
| 381 | HTML fragment name. The first character of the section type is |
| 382 | prepended to the section number. So in chapter 1 this would expand to |
| 383 | \cq{C1}; in section A.4.3 it would expand to \cq{SA.4.3}, and so on. |
| 384 | If the section has no number (an unnumbered chapter created using |
| 385 | \c{\\U}), this directive falls back to doing the same thing as \c{%N}. |
| 386 | |
| 387 | \dt \i\c{%k} |
| 388 | |
| 389 | \dd Expands to the internal keyword specified in the section title. |
| 390 | So in a chapter declared as \cq{\\C\{fish\} Catching Fish}, this |
| 391 | formatting command would expand to \cq{fish}. If the section has |
| 392 | no keyword (an unnumbered chapter created using \c{\\U}), this |
| 393 | directive falls back to doing the same thing as \c{%N}. |
| 394 | |
| 395 | These formatting directives can also be used in the |
| 396 | \cw{\\cfg\{html-template-fragment\}} configuration directive (see |
| 397 | \k{output-html-misc}). |
| 398 | |
| 399 | } |
| 400 | |
| 401 | \dt \I{\cw{\\cfg\{html-single-filename\}}}\cw{\\cfg\{html-single-filename\}\{}\e{filename}\cw{\}} |
| 402 | |
| 403 | \dd Sets the file name in which to store the entire document, if |
| 404 | Halibut is configured (using \c{\\cfg\{html-leaf-level\}\{0\}} to |
| 405 | produce a single self-contained file. Both this directive \e{and} |
| 406 | \c{\\cfg\{html-leaf-level\}\{0\}} are implicitly generated if you |
| 407 | provide a file name parameter after the command-line option |
| 408 | \i\c{--html} (see \k{running-options}). |
| 409 | |
| 410 | \S{output-html-split} Controlling the splitting into HTML files |
| 411 | |
| 412 | By default, the HTML output from Halibut is split into multiple |
| 413 | files. Each file typically contains a single chapter or section and |
| 414 | everything below it, unless subsections of that chapter are |
| 415 | themselves split off into further files. |
| 416 | |
| 417 | Most files also contain a contents section, giving hyperlinks to the |
| 418 | sections in the file and/or the sections below it. |
| 419 | |
| 420 | The configuration directives listed below allow you to configure the |
| 421 | splitting into files, and the details of the contents sections. |
| 422 | |
| 423 | \dt \I{\cw{\\cfg\{html-leaf-level\}}}\cw{\\cfg\{html-leaf-level\}\{}\e{depth}\cw{\}} |
| 424 | |
| 425 | \dd This setting indicates the depth of section which should be |
| 426 | given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if |
| 427 | you set it to 1, for example, then every chapter will be given its |
| 428 | own HTML file, plus a top-level \i{contents file}. If you set this |
| 429 | to 2, then each chapter \e{and} each \c{\\H} section will have a |
| 430 | file, and the chapter files will mostly just contain links to their |
| 431 | \i{sub-file}s. |
| 432 | |
| 433 | \lcont{ |
| 434 | |
| 435 | If you set this option to zero, then the whole document will appear |
| 436 | in a single file. If you do this, Halibut will call that file |
| 437 | \i\c{Manual.html} instead of \i\c{Contents.html} by default. |
| 438 | |
| 439 | This option is automatically set to zero if you provide a file name |
| 440 | parameter after the command-line option \i\c{--html} (see |
| 441 | \k{running-options}), because you have specified a single file name |
| 442 | and so Halibut assumes you want the whole document to be placed in |
| 443 | that file. |
| 444 | |
| 445 | You can also specify the special name \c{infinity} (or \c{infinite} |
| 446 | or \c{inf}) if you want to ensure that \e{every} section and |
| 447 | subsection ends up in a separate file no matter how deep you go. |
| 448 | |
| 449 | } |
| 450 | |
| 451 | \dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}} |
| 452 | |
| 453 | \dd This directive allows you to specify how \I{depth of |
| 454 | contents}deep any contents section in a particular level of file |
| 455 | should go. |
| 456 | |
| 457 | \lcont{ |
| 458 | |
| 459 | The \e{level} parameter indicates which level of contents section |
| 460 | you are dealing with. 0 denotes the main contents section in the |
| 461 | topmost file \c{Contents.html}; 1 denotes a contents section in a |
| 462 | chapter file; 2 is a contents section in a file containing a \c{\\H} |
| 463 | heading, and so on. |
| 464 | |
| 465 | The \e{depth} parameter indicates the maximum depth of heading which |
| 466 | will be shown in this contents section. Again, 1 denotes a chapter, |
| 467 | 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on. |
| 468 | |
| 469 | So, for example: \cw{\\cfg\{html-contents-depth\}\{1\}\{3\}} instructs |
| 470 | Halibut to put contents links in chapter files for all sections down |
| 471 | to \c{\\S} level, but not to go into any more detail than that. |
| 472 | |
| 473 | For backwards compatibility, the alternative syntax |
| 474 | \cw{\\cfg\{html-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}} |
| 475 | is also supported. |
| 476 | |
| 477 | } |
| 478 | |
| 479 | \dt \I{\cw{\\cfg\{html-leaf-contains-contents\}}}\cw{\\cfg\{html-leaf-contains-contents\}\{}\e{boolean}\cw{\}} |
| 480 | |
| 481 | \dd If you set this to \c{true}, then each leaf file will contain |
| 482 | its own contents section which summarises the text within it. |
| 483 | |
| 484 | \dt \I{\cw{\\cfg\{html-leaf-smallest-contents\}}}\cw{\\cfg\{html-leaf-smallest-contents\}\{}\e{number}\cw{\}} |
| 485 | |
| 486 | \dd Contents sections in leaf files are not output at all if they |
| 487 | contain very few entries (on the assumption that it just isn't worth |
| 488 | bothering). This directive configures the minimum number of entries |
| 489 | required in a leaf contents section to make Halibut bother |
| 490 | generating it at all. |
| 491 | |
| 492 | \S{output-html-html} Including pieces of your own HTML |
| 493 | |
| 494 | The directives in this section allow you to supply pieces of |
| 495 | \I{HTML}\i{verbatim HTML} code, which will be included in various |
| 496 | parts of the output files. |
| 497 | |
| 498 | Note that none of Halibut's usual character set translation is applied |
| 499 | to this code; it is assumed to already be in a suitable encoding for |
| 500 | the target HTML files. |
| 501 | |
| 502 | \dt \I{\cw{\\cfg\{html-head-end\}}}\cw{\\cfg\{html-head-end\}\{}\e{HTML text}\cw{\}} |
| 503 | |
| 504 | \dd The text you provide in this directive is placed at the end of |
| 505 | the \i\cw{<HEAD>} section of each output HTML file. So this is a |
| 506 | good place to put, for example, a link to a \i{CSS} \i{stylesheet}. |
| 507 | |
| 508 | \dt \I{\cw{\\cfg\{html-local-head\}}}\cw{\\cfg\{html-local-head\}\{}\e{HTML text}\cw{\}} |
| 509 | |
| 510 | \dd This configuration directive is local: you specify it within a |
| 511 | document section, and it acts on that section only. |
| 512 | |
| 513 | \lcont{ |
| 514 | |
| 515 | The text you provide in this directive is placed at the end of the |
| 516 | \i\cw{<HEAD>} section of whichever output HTML file contains the |
| 517 | section in which the directive was placed. You can specify this |
| 518 | directive multiple times in multiple sections if you like. |
| 519 | |
| 520 | This directive is particularly useful for constructing \i{MacOS |
| 521 | on-line help}, which is mostly normal HTML but which requires a |
| 522 | special \i\cw{<META NAME="AppleTitle">} tag in the topmost source |
| 523 | file. You can arrange this by placing this configuration directive |
| 524 | in the preamble or the introduction section, something like this: |
| 525 | |
| 526 | \c \cfg{html-local-head}{<meta name="AppleTitle" |
| 527 | \c content="MyApp Help">} |
| 528 | |
| 529 | } |
| 530 | |
| 531 | \dt \I{\cw{\\cfg\{html-body-tag\}}}\cw{\\cfg\{html-body-tag\}\{}\e{HTML text}\cw{\}} |
| 532 | |
| 533 | \dd The text you provide in this directive is used in place of the |
| 534 | \i\cw{<BODY>} tag in each output file. So if you wanted to define a |
| 535 | \i{background colour}, for example, you could write |
| 536 | \cw{\\cfg\{html-body-tag\}\{<body bg="#123456">\}}. |
| 537 | |
| 538 | \dt \I{\cw{\\cfg\{html-body-start\}}}\cw{\\cfg\{html-body-start\}\{}\e{HTML text}\cw{\}} |
| 539 | |
| 540 | \dd The text you provide in this directive is placed at the |
| 541 | beginning of the \i\cw{<BODY>} section of each output HTML file. So |
| 542 | if you intend your HTML files to be part of a web site with a |
| 543 | standard \i{house style}, and the style needs a \i{header} at the |
| 544 | top of every page, this is where you can add that header. |
| 545 | |
| 546 | \dt \I{\cw{\\cfg\{html-body-end\}}}\cw{\\cfg\{html-body-end\}\{}\e{HTML text}\cw{\}} |
| 547 | |
| 548 | \dd The text you provide in this directive is placed at the end of |
| 549 | the \i\cw{<BODY>} section of each output HTML file, before any address |
| 550 | section. So if you intend your HTML files to be part of a web site |
| 551 | with a standard \i{house style}, and the style needs a \i{footer} at |
| 552 | the bottom of every page, this is where you can add that footer. |
| 553 | |
| 554 | \dt \I{\cw{\\cfg\{html-address-start\}}}\cw{\\cfg\{html-address-start\}\{}\e{HTML text}\cw{\}} |
| 555 | |
| 556 | \dd The text you provide in this directive is placed at the |
| 557 | beginning of the \i\cw{<ADDRESS>} section at the bottom of each |
| 558 | output HTML file. This might be a good place to put authors' |
| 559 | \i{contact details}, for example. |
| 560 | |
| 561 | \dt \I{\cw{\\cfg\{html-address-end\}}}\cw{\\cfg\{html-address-end\}\{}\e{HTML text}\cw{\}} |
| 562 | |
| 563 | \dd The text you provide in this directive is placed at the end of |
| 564 | the \i\cw{<ADDRESS>} section at the bottom of each output HTML file, |
| 565 | after the version IDs (if present). |
| 566 | |
| 567 | \dt \I{\cw{\\cfg\{html-navigation-attributes\}}}\cw{\\cfg\{html-navigation-attributes\}\{}\e{HTML attributes}\cw{\}} |
| 568 | |
| 569 | \dd The text you provide in this directive is included inside the |
| 570 | \cw{<P>} tag containing the \i{navigation links} at the top of each |
| 571 | page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you |
| 572 | wanted the navigation links to have a particular CSS style, you |
| 573 | could write |
| 574 | \cw{\\cfg\{html-navigation-attributes\}\{class="foo"\}}, and the |
| 575 | navigation-links paragraph would then begin with the tag \cw{<p |
| 576 | class="foo">}. |
| 577 | |
| 578 | \S{output-html-headings} \ii{Configuring heading display} |
| 579 | |
| 580 | \dt \I{\cw{\\cfg\{html-chapter-numeric\}}}\cw{\\cfg\{html-chapter-numeric\}\{}\e{boolean}\cw{\}} |
| 581 | |
| 582 | \dd If this is set to \c{true}, then chapter headings will not |
| 583 | contain the word \q{Chapter} (or whatever other word you have |
| 584 | defined in its place - see \k{input-sections} and \k{input-config}); |
| 585 | they will just contain the chapter \e{number}, followed by the |
| 586 | chapter title. If you set this to \c{false}, chapter headings will |
| 587 | be prefixed by \q{Chapter} or equivalent. |
| 588 | |
| 589 | \dt \I{\cw{\\cfg\{html-chapter-suffix\}}}\cw{\\cfg\{html-chapter-suffix\}\{}\e{text}\cw{\}} |
| 590 | |
| 591 | \dd This specifies the suffix text to be appended to the chapter |
| 592 | number, before displaying the chapter title. For example, if you set |
| 593 | this to \cq{:\_}, then the chapter title might look something |
| 594 | like \q{Chapter 2: Doing Things}. |
| 595 | |
| 596 | \dt \I{\cw{\\cfg\{html-section-numeric\}}}\cw{\\cfg\{html-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} |
| 597 | |
| 598 | \# {level} can be omitted (defaults to 0). Is this intentional? |
| 599 | |
| 600 | \dd Specifies whether section headings at a particular level should |
| 601 | contain the word \q{Section} or equivalent (if \c{false}), or should |
| 602 | be numeric only (if \c{true}). The \e{level} parameter specifies |
| 603 | which level of section headings you want to affect: 0 means |
| 604 | first-level headings (\c{\\H}), 1 means second-level headings |
| 605 | (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on. |
| 606 | |
| 607 | \dt \I{\cw{\\cfg\{html-section-suffix\}}}\cw{\\cfg\{html-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} |
| 608 | |
| 609 | \# {level} can be omitted (defaults to 0). Is this intentional? |
| 610 | |
| 611 | \dd Specifies the suffix text to be appended to section numbers at a |
| 612 | particular level, before displaying the section title. |
| 613 | |
| 614 | \S{output-html-names} Configuring standard text |
| 615 | |
| 616 | These directives let you fine-tune the names Halibut uses in places |
| 617 | such as the navigation bar to refer to various parts of the document, |
| 618 | and other standard pieces of text, for instance to change them to a |
| 619 | different language. |
| 620 | |
| 621 | \dt \I{\cw{\\cfg\{html-preamble-text\}}}\cw{\\cfg\{html-preamble-text\}\{}\e{text}\cw{\}} |
| 622 | |
| 623 | \dt \I{\cw{\\cfg\{html-contents-text\}}}\cw{\\cfg\{html-contents-text\}\{}\e{text}\cw{\}} |
| 624 | |
| 625 | \dt \I{\cw{\\cfg\{html-index-text\}}}\cw{\\cfg\{html-index-text\}\{}\e{text}\cw{\}} |
| 626 | |
| 627 | \dd Text used to refer to the preamble (i.e., any paragraphs before |
| 628 | the first chapter heading), contents, and index respectively, in the |
| 629 | navigation bar, contents, and index. |
| 630 | |
| 631 | \lcont{ |
| 632 | |
| 633 | (\c{html-contents-text} and \c{html-index-text} override the |
| 634 | cross-format configuration keywords \c{contents} and \c{index} (see |
| 635 | \k{input-config}, if both appear. They are legacy keywords preserved |
| 636 | for backwards compatibility; you should generally use \c{contents} |
| 637 | and \c{index}.) |
| 638 | |
| 639 | } |
| 640 | |
| 641 | \dt \I{\cw{\\cfg\{html-title-separator\}}}\cw{\\cfg\{html-title-separator\}\{}\e{text}\cw{\}} |
| 642 | |
| 643 | \dd If multiple headings are used in a file's \cw{<TITLE>} tag, this |
| 644 | text is used to separate them. |
| 645 | |
| 646 | \# Under what circumstances can this occur? |
| 647 | |
| 648 | \dt \I{\cw{\\cfg\{html-index-main-separator\}}}\cw{\\cfg\{html-index-main-separator\}\{}\e{text}\cw{\}} |
| 649 | |
| 650 | \dd Separator between index term and references in the index. |
| 651 | |
| 652 | \dt \I{\cw{\\cfg\{html-index-multiple-separator\}}}\cw{\\cfg\{html-index-multiple-separator\}\{}\e{text}\cw{\}} |
| 653 | |
| 654 | \dd Separator between multiple references for a single index term in |
| 655 | the index. |
| 656 | |
| 657 | \dt \I{\cw{\\cfg\{html-pre-versionid\}}}\cw{\\cfg\{html-pre-versionid\}\{}\e{text}\cw{\}} |
| 658 | |
| 659 | \dt \I{\cw{\\cfg\{html-post-versionid\}}}\cw{\\cfg\{html-post-versionid\}\{}\e{text}\cw{\}} |
| 660 | |
| 661 | \dd Text surrounding each output \i{version ID paragraph}. |
| 662 | |
| 663 | \dt \I{\cw{\\cfg\{html-nav-prev-text\}}}\cw{\\cfg\{html-nav-prev-text\}\{}\e{text}\cw{\}} |
| 664 | |
| 665 | \dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}} |
| 666 | |
| 667 | \dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}} |
| 668 | |
| 669 | \dd The text used for the \q{previous page}, \q{next page}, and \q{up} |
| 670 | links on the navigation bar. |
| 671 | |
| 672 | \dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}} |
| 673 | |
| 674 | \dd Separator between links in the navigation bar. |
| 675 | |
| 676 | \S{output-html-characters} Configuring the characters used |
| 677 | |
| 678 | Unlike the other backends, HTML does not have a single |
| 679 | \i\cw{\\cfg\{html-charset\}} directive, as there are several levels of |
| 680 | character encoding to consider. |
| 681 | |
| 682 | The character set names are the same as for |
| 683 | \cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike |
| 684 | \cw{\\cfg\{input-charset\}}, these directives affect the \e{entire} |
| 685 | output; it's not possible to switch encodings halfway through. |
| 686 | |
| 687 | \dt \I\cw{\\cfg\{html-output-charset\}}\cw{\\cfg\{html-output-charset\}\{}\e{character set name}\cw{\}} |
| 688 | |
| 689 | \dd The character encoding of the HTML file to be output. Unicode |
| 690 | characters in this encoding's repertoire are included literally rather |
| 691 | than as \i{HTML entities}. |
| 692 | |
| 693 | \dt \I\cw{\\cfg\{html-restrict-charset\}}\cw{\\cfg\{html-restrict-charset\}\{}\e{character set name}\cw{\}} |
| 694 | |
| 695 | \dd Only Unicode characters representable in this character set will be |
| 696 | output; any others will be omitted and use their fallback text, if |
| 697 | any. Characters not in \q{html-output-charset} will be represented as |
| 698 | HTML numeric entities. |
| 699 | |
| 700 | \dt \I{\cw{\\cfg\{html-quotes\}}}\cw{\\cfg\{html-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}] |
| 701 | |
| 702 | \dd Specifies the quotation marks to use, overriding any |
| 703 | \cw{\\cfg\{quotes\}} directive. You can specify multiple |
| 704 | fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} |
| 705 | directive (see \k{output-text-characters}). |
| 706 | |
| 707 | \S{output-html-misc} Miscellaneous options |
| 708 | |
| 709 | \dt \I\cw{\\cfg\{html-version\}}\cw{\\cfg\{html-version\}\{}\e{version}\cw{\}} |
| 710 | |
| 711 | \dd Identifies the precise version of HTML that is output. This |
| 712 | affects the declaration within the HTML, and also has minor effects on |
| 713 | the body of the HTML so that it is valid for the declared version. The |
| 714 | available variants are: |
| 715 | |
| 716 | \lcont{ |
| 717 | |
| 718 | \dt \cw{html3.2} |
| 719 | |
| 720 | \dd W3C HTML 3.2 |
| 721 | |
| 722 | \dt \cw{html4} |
| 723 | |
| 724 | \dd W3C HTML 4.01 Strict |
| 725 | |
| 726 | \dt \cw{iso-html} |
| 727 | |
| 728 | \dd ISO/IEC 15445:2000 |
| 729 | |
| 730 | \dt \cw{xhtml1.0transitional} |
| 731 | |
| 732 | \dd W3C XHTML 1.0 Transitional |
| 733 | |
| 734 | \dt \cw{xhtml1.0strict} |
| 735 | |
| 736 | \dd W3C XHTML 1.0 Strict |
| 737 | |
| 738 | } |
| 739 | |
| 740 | \dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}] |
| 741 | |
| 742 | \dd This directive lets you specify a \i{template}, with exactly the |
| 743 | same syntax used in \cw{\\cfg\{html-template-filename\}} (see |
| 744 | \k{output-html-file}), to be used for the anchor names (\i\cw{<A |
| 745 | NAME="...">}) used to allow URLs to refer to specific sections |
| 746 | within a particular HTML file. So if you set this to \cq{%k}, |
| 747 | for example, then each individual section in your document will be |
| 748 | addressable by means of a URL ending in a \c{#} followed by your |
| 749 | internal section keyword. |
| 750 | |
| 751 | \lcont{ |
| 752 | |
| 753 | If more than one template is specified, anchors are generated in all |
| 754 | the specified formats; Halibut's own cross-references are generated |
| 755 | with the first template. |
| 756 | |
| 757 | Characters that are not permitted in anchor names are stripped. If |
| 758 | there are no valid characters left, or a fragment is non-unique, |
| 759 | Halibut starts inventing fragment names and suffixes as appropriate. |
| 760 | |
| 761 | Note that there are potentially fragment names that are not controlled |
| 762 | by this mechanism, such as index references. |
| 763 | |
| 764 | } |
| 765 | |
| 766 | \dt \I{\cw{\\cfg\{html-versionid\}}}\cw{\\cfg\{html-versionid\}\{}\e{boolean}\cw{\}} |
| 767 | |
| 768 | \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using |
| 769 | the \i\c{\\versionid} command - see \k{input-blurb}) will be included |
| 770 | visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML |
| 771 | file. If it is set to \c{false}, they will only be included as HTML |
| 772 | comments. |
| 773 | |
| 774 | \dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}} |
| 775 | |
| 776 | \dd If this is set to \c{true}, machine-readable relational links will |
| 777 | be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK |
| 778 | REL="next">} and so on within the \i\cw{<HEAD>} section) |
| 779 | providing links to related files. The same set of links are provided |
| 780 | as in the navigation bar (with which this should not be confused). |
| 781 | |
| 782 | \lcont{ |
| 783 | |
| 784 | Some browsers make use of this semantic information, for instance to |
| 785 | allow easy navigation through related pages, and to prefetch the next |
| 786 | page. (Search engines can also make use of it.) However, many browsers |
| 787 | ignore this markup, so it would be unwise to rely on it for |
| 788 | navigation. |
| 789 | |
| 790 | The use and rendering of this information is entirely up to the |
| 791 | browser; none of the other Halibut options for the navigation bar will |
| 792 | have any effect. |
| 793 | |
| 794 | } |
| 795 | |
| 796 | \dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}} |
| 797 | |
| 798 | \dd If this is set to \c{true}, the usual \i{navigation links} within |
| 799 | the \e{body} of each HTML file (near the top of the rendered page) will |
| 800 | be suppressed. |
| 801 | |
| 802 | \dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}} |
| 803 | |
| 804 | \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the |
| 805 | bottom of each HTML file will be omitted completely. (This will |
| 806 | therefore also cause \i{version IDs} not to be included visibly.) |
| 807 | |
| 808 | \dt \I{\cw{\\cfg\{html-author\}}}\cw{\\cfg\{html-author\}\{}\e{text}\cw{\}} |
| 809 | |
| 810 | \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META |
| 811 | name="author">} tag in the output HTML files, so that browsers which |
| 812 | support this can automatically identify the \i{author} of the document. |
| 813 | |
| 814 | \dt \I{\cw{\\cfg\{html-description\}}}\cw{\\cfg\{html-description\}\{}\e{text}\cw{\}} |
| 815 | |
| 816 | \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META |
| 817 | name="description">} tag in the output HTML files, so that browsers |
| 818 | which support this can easily pick out a brief \I{description, of |
| 819 | document}description of the document. |
| 820 | |
| 821 | \S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help} |
| 822 | |
| 823 | The HTML files output from Halibut's HTML back end can be used as |
| 824 | input to the MS Windows HTML Help compiler. In order to do this, you |
| 825 | also need some auxiliary files: a project file, and (probably) a |
| 826 | contents file and an index file. Halibut can optionally generate |
| 827 | those as well. |
| 828 | |
| 829 | To enable the generation of MS HTML Help auxiliary files, use the |
| 830 | following configuration directives: |
| 831 | |
| 832 | \dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}} |
| 833 | |
| 834 | \dd Instructs Halibut to output an HTML Help project file with the |
| 835 | specified name. You will almost certainly want the filename to end |
| 836 | in the extension \c{.hhp} (although Halibut will not enforce this). |
| 837 | If you use this option, you must also use the |
| 838 | \cw{html-mshtmlhelp-chm} option to specify the desired name of the |
| 839 | compiled help file. |
| 840 | |
| 841 | \dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}} |
| 842 | |
| 843 | \dd Specifies the desired name of the compiled HTML Help file. You |
| 844 | will almost certainly want this to have the extension \c{.chm} |
| 845 | (although Halibut will not enforce this). The name you specify here |
| 846 | will be written into the help project file. If you specify this |
| 847 | option, you must also use the \cw{html-mshtmlhelp-project} option to |
| 848 | request a help project file in the first place. |
| 849 | |
| 850 | \dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}} |
| 851 | |
| 852 | \dd Instructs Halibut to output an HTML Help contents file with the |
| 853 | specified name, and refer to it in the help project file. You will |
| 854 | almost certainly want the filename to end in the extension \c{.hhc} |
| 855 | (although Halibut will not enforce this). This option will be |
| 856 | ignored if you have not also specified a help project file. |
| 857 | |
| 858 | \lcont{ |
| 859 | |
| 860 | Creating a contents file like this causes the HTML Help viewer to |
| 861 | display a contents tree in the pane to the left of the main text |
| 862 | window. You can choose to generate an HTML Help project without this |
| 863 | feature, in which case the user will still be able to navigate |
| 864 | around the document by using the ordinary internal links in the HTML |
| 865 | files themselves just as if it were a web page. However, using a |
| 866 | contents file is recommended. |
| 867 | |
| 868 | } |
| 869 | |
| 870 | \dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}} |
| 871 | |
| 872 | \dd Instructs Halibut to output an HTML Help index file with the |
| 873 | specified name, and refer to it in the help project file. You will |
| 874 | almost certainly want the filename to end in the extension \c{.hhk} |
| 875 | (although Halibut will not enforce this). This option will be |
| 876 | ignored if you have not also specified a help project file. |
| 877 | |
| 878 | \lcont{ |
| 879 | |
| 880 | Specifying this option suppresses the generation of an HTML-based |
| 881 | index file (see \cw{\\cfg\{html-index-filename\}} in |
| 882 | \k{output-html-file}). |
| 883 | |
| 884 | Creating an index file like this causes the HTML Help viewer to |
| 885 | provide a list of index terms in a pane to the left of the main text |
| 886 | window. You can choose to generate an HTML Help project without this |
| 887 | feature, in which case a conventional HTML index will be generated |
| 888 | instead (assuming you have any index terms at all defined) and the |
| 889 | user will still be able to use that. However, using an index file is |
| 890 | recommended. |
| 891 | |
| 892 | Halibut will not output an index file at all, or link to one from |
| 893 | the help project file, if your document contains no index entries. |
| 894 | |
| 895 | } |
| 896 | |
| 897 | If you use the above options, Halibut will output a help project |
| 898 | file which you should be able to feed straight to the command-line |
| 899 | MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help |
| 900 | Workshop (\cw{HHW.EXE}). |
| 901 | |
| 902 | You may also wish to alter other HTML configuration options to make |
| 903 | the resulting help file look more like a help file and less like a |
| 904 | web page. A suggested set of additional configuration options for |
| 905 | HTML Help is as follows: |
| 906 | |
| 907 | \b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help |
| 908 | works best with lots of small files (\q{topics}) rather than a few |
| 909 | large ones. In particular, the contents and index mechanisms can |
| 910 | only reference files, not subsections within files. |
| 911 | |
| 912 | \b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress |
| 913 | the contents list above the main text of each bottom-level file. |
| 914 | |
| 915 | \b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help |
| 916 | has its own navigation facilities and it looks a bit strange to |
| 917 | duplicate them. |
| 918 | |
| 919 | \b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the |
| 920 | \cw{<ADDRESS>} section makes less sense in a help file than it does |
| 921 | on a web page. |
| 922 | |
| 923 | \S{output-html-defaults} Default settings |
| 924 | |
| 925 | The \i{default settings} for Halibut's HTML output format are: |
| 926 | |
| 927 | \c \cfg{html-contents-filename}{Contents.html} |
| 928 | \c \cfg{html-index-filename}{IndexPage.html} |
| 929 | \c \cfg{html-template-filename}{%n.html} |
| 930 | \c \cfg{html-single-filename}{Manual.html} |
| 931 | \c |
| 932 | \c \cfg{html-leaf-level}{2} |
| 933 | \c \cfg{html-leaf-contains-contents}{false} |
| 934 | \c \cfg{html-leaf-smallest-contents}{4} |
| 935 | \c \cfg{html-contents-depth}{0}{2} |
| 936 | \c \cfg{html-contents-depth}{1}{3} |
| 937 | \c ... and so on for all section levels below this ... |
| 938 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
| 939 | \c |
| 940 | \c \cfg{html-head-end}{} |
| 941 | \c \cfg{html-body-tag}{<body>} |
| 942 | \c \cfg{html-body-start}{} |
| 943 | \c \cfg{html-body-end}{} |
| 944 | \c \cfg{html-address-start}{} |
| 945 | \c \cfg{html-address-end}{} |
| 946 | \c \cfg{html-navigation-attributes}{} |
| 947 | \c |
| 948 | \c \cfg{html-chapter-numeric}{false} |
| 949 | \c \cfg{html-chapter-suffix}{: } |
| 950 | \c |
| 951 | \c \cfg{html-section-numeric}{0}{true} |
| 952 | \c \cfg{html-section-suffix}{0}{ } |
| 953 | \c |
| 954 | \c \cfg{html-section-numeric}{1}{true} |
| 955 | \c \cfg{html-section-suffix}{1}{ } |
| 956 | \c |
| 957 | \c ... and so on for all section levels below this ... |
| 958 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
| 959 | \c |
| 960 | \c \cfg{html-preamble-text}{Preamble} |
| 961 | \c \cfg{html-contents-text}{Contents} |
| 962 | \c \cfg{html-index-text}{Index} |
| 963 | \c \cfg{html-title-separator}{ - } |
| 964 | \c \cfg{html-index-main-separator}{: } |
| 965 | \c \cfg{html-index-multiple-separator}{, } |
| 966 | \c \cfg{html-pre-versionid}{[} |
| 967 | \c \cfg{html-post-versionid}{]} |
| 968 | \c \cfg{html-nav-prev-text}{Previous} |
| 969 | \c \cfg{html-nav-next-text}{Next} |
| 970 | \c \cfg{html-nav-up-text}{Up} |
| 971 | \c \cfg{html-nav-separator}{ | } |
| 972 | \c |
| 973 | \c \cfg{html-output-charset}{ASCII} |
| 974 | \c \cfg{html-restrict-charset}{UTF-8} |
| 975 | \c \cfg{html-quotes}{\u2018}{\u2019}{"}{"} |
| 976 | \c |
| 977 | \c \cfg{html-version}{html4} |
| 978 | \c \cfg{html-template-fragment}{%b} |
| 979 | \c \cfg{html-versionid}{true} |
| 980 | \c \cfg{html-rellinks}{true} |
| 981 | \c \cfg{html-suppress-navlinks{false} |
| 982 | \c \cfg{html-suppress-address}{false} |
| 983 | \c \cfg{html-author}{} |
| 984 | \c \cfg{html-description}{} |
| 985 | |
| 986 | \H{output-whlp} Windows Help |
| 987 | |
| 988 | This output format generates data that can be used by the \i{Windows |
| 989 | Help} program \cw{WINHLP32.EXE}. There are two actual files |
| 990 | generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. |
| 991 | |
| 992 | Note that as of 2006, MS is discontinuing the Windows Help format in |
| 993 | favour of the newer HTML Help format (\c{.chm} files). Halibut is |
| 994 | not currently able to generate \c{.chm} files directly, but its HTML |
| 995 | back end can write out project files suitable for use as input to |
| 996 | the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more |
| 997 | information on this. |
| 998 | |
| 999 | Currently, the Windows Help output is hardcoded to be in the |
| 1000 | \q{\i{Win1252}} character set. (If anyone knows how character sets |
| 1001 | are encoded in Windows Help files, we'd appreciate help.) |
| 1002 | |
| 1003 | The Windows Help output format supports the following configuration |
| 1004 | directives: |
| 1005 | |
| 1006 | \S{output-whlp-file} Output file name |
| 1007 | |
| 1008 | \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}} |
| 1009 | |
| 1010 | \dd Sets the \i{output file name} in which to store the man page. |
| 1011 | This directive is implicitly generated if you provide a file name |
| 1012 | parameter after the command-line option \i\c{--winhelp} (see |
| 1013 | \k{running-options}). |
| 1014 | |
| 1015 | \lcont{ |
| 1016 | |
| 1017 | Your output file name should end with \c{.hlp}; if it doesn't, |
| 1018 | Halibut will append it. Halibut will also generate a contents file |
| 1019 | (ending in \c{.cnt}) alongside the file name you specify. |
| 1020 | |
| 1021 | } |
| 1022 | |
| 1023 | \S{output-whlp-characters} Configuring the characters used |
| 1024 | |
| 1025 | \dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1026 | |
| 1027 | \dd Specifies the text to use as the \i{bullet} in bulletted lists. |
| 1028 | You can specify multiple fallback options. Works exactly like the |
| 1029 | \cw{\\cfg\{text-bullet\}} directive (see |
| 1030 | \k{output-text-characters}). |
| 1031 | |
| 1032 | \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{\}}] |
| 1033 | |
| 1034 | \dd Specifies the quotation marks to use, overriding any |
| 1035 | \cw{\\cfg\{quotes\}} directive. You can specify multiple |
| 1036 | fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} |
| 1037 | directive (see \k{output-text-characters}). |
| 1038 | |
| 1039 | \S{output-whlp-misc} Miscellaneous configuration options |
| 1040 | |
| 1041 | \dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}} |
| 1042 | |
| 1043 | \dd Sets the text used to describe the help page containing the blurb |
| 1044 | (see \k{input-blurb}) and table of contents. |
| 1045 | |
| 1046 | \dt |
| 1047 | \I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}} |
| 1048 | |
| 1049 | \dd Specifies the \I{suffix text, in section titles}suffix text to |
| 1050 | be appended to section numbers, before displaying the section title. |
| 1051 | (Applies to all levels.) |
| 1052 | |
| 1053 | \dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}} |
| 1054 | |
| 1055 | \dd This text is appended to the number on a \i{numbered list} item, |
| 1056 | in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see |
| 1057 | \k{output-text-characters}). |
| 1058 | |
| 1059 | \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}} |
| 1060 | |
| 1061 | \dd This directive defines a Windows \i{Help topic} name in the current |
| 1062 | section. Topic names can be used by the program invoking |
| 1063 | \cw{WINHELP.EXE} to jump straight to a particular section. So you |
| 1064 | can use this for \i{context-sensitive help}. |
| 1065 | |
| 1066 | \lcont{ |
| 1067 | |
| 1068 | For example, if you used this directive in a particular section: |
| 1069 | |
| 1070 | \c \cfg{winhelp-topic}{savingfiles} |
| 1071 | |
| 1072 | then a Windows application could invoke Windows Help to jump to that |
| 1073 | particular section in the help file like this: |
| 1074 | |
| 1075 | \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND, |
| 1076 | \c (DWORD)"JI(`',`savingfiles')"); |
| 1077 | |
| 1078 | You can use this configuration directive many times, in many |
| 1079 | different subsections of your document, in order to define a lot of |
| 1080 | different help contexts which you can use in this way. |
| 1081 | |
| 1082 | } |
| 1083 | |
| 1084 | \S{output-whlp-defaults} Default settings |
| 1085 | |
| 1086 | The \i{default settings} for the Windows Help output format are: |
| 1087 | |
| 1088 | \c \cfg{winhelp-filename}{output.hlp} |
| 1089 | \c |
| 1090 | \c \cfg{winhelp-bullet}{\u2022}{-} |
| 1091 | \c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"} |
| 1092 | \c |
| 1093 | \c \cfg{winhelp-contents-titlepage}{Title page} |
| 1094 | \c \cfg{winhelp-section-suffix}{: } |
| 1095 | \c \cfg{winhelp-list-suffix}{.} |
| 1096 | |
| 1097 | and no \c{\\cfg\{winhelp-topic\}} directives anywhere. |
| 1098 | |
| 1099 | \H{output-man} Unix \cw{man} pages |
| 1100 | |
| 1101 | This output format generates a Unix \i{\cw{man} page}. That is to say, |
| 1102 | it generates \i\c{nroff} input designed to work with the \c{-mandoc} |
| 1103 | macro package. |
| 1104 | |
| 1105 | The available configuration options for this format are as follows: |
| 1106 | |
| 1107 | \S{output-man-file} Output file name |
| 1108 | |
| 1109 | \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}} |
| 1110 | |
| 1111 | \dd Sets the \i{output file name} in which to store the man page. |
| 1112 | This directive is implicitly generated if you provide a file name |
| 1113 | parameter after the command-line option \i\c{--man} (see |
| 1114 | \k{running-options}). |
| 1115 | |
| 1116 | \S{output-man-identity} Configuring headers and footers |
| 1117 | |
| 1118 | \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}} |
| 1119 | |
| 1120 | \dd This directive is used to generate the initial \i{\c{.TH} |
| 1121 | directive} that appears at the top of a \cw{man} page. It expects to |
| 1122 | be followed by some number of brace pairs containing text, which will |
| 1123 | be used in the \i{headers} and \i{footers} of the formatted output. |
| 1124 | |
| 1125 | \lcont{ |
| 1126 | |
| 1127 | A traditional order for the arguments appears to be: |
| 1128 | |
| 1129 | \n The name of the program. |
| 1130 | |
| 1131 | \n The (numeric) manual section. |
| 1132 | |
| 1133 | \n The date that the \cw{man} page was written. |
| 1134 | |
| 1135 | \n The name of any containing suite of which the program is a part. |
| 1136 | |
| 1137 | \n The name of the \i{author} of the \cw{man} page. |
| 1138 | |
| 1139 | For example, a typical \cw{man} page might contain |
| 1140 | |
| 1141 | \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred |
| 1142 | \c Bloggs} |
| 1143 | |
| 1144 | } |
| 1145 | |
| 1146 | \S{output-man-headings} Configuring heading display |
| 1147 | |
| 1148 | \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}} |
| 1149 | |
| 1150 | \dd If this is set to \c{true}, then \i{section headings} in the |
| 1151 | \cw{man} page will have their \i{section numbers} displayed as usual. If |
| 1152 | set to \c{false}, the section numbers will be omitted. (\cw{man} |
| 1153 | pages traditionally have section names such as \q{SYNOPSIS}, |
| 1154 | \q{OPTIONS} and \q{BUGS}, and do not typically number them, so |
| 1155 | \c{false} is the setting which conforms most closely to normal |
| 1156 | \cw{man} style.) |
| 1157 | |
| 1158 | \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}} |
| 1159 | |
| 1160 | \dd If this is set to a number greater than 0, then section headings |
| 1161 | \e{higher} than the given depth will not be displayed. If it is set |
| 1162 | to zero, all section headings will be displayed as normal. |
| 1163 | |
| 1164 | \lcont{ |
| 1165 | |
| 1166 | The point of this is so that you can use the same Halibut input file |
| 1167 | to generate a quick-reference \cw{man} page for a program, \e{and} to |
| 1168 | include that \cw{man} page as an appendix in your program's full manual. |
| 1169 | If you are to include the \cw{man} page as an appendix, then the internal |
| 1170 | headings within the page will probably need to be at \c{\\H} or |
| 1171 | \c{\\S} level; therefore, when you format that input file on its own |
| 1172 | to create the \cw{man} page itself, you will need to have defined a |
| 1173 | \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't |
| 1174 | want to see displayed. |
| 1175 | |
| 1176 | Here's an example. You might have a file \c{appendix.but}, which |
| 1177 | simply says |
| 1178 | |
| 1179 | \c \A{manpages} \cw{man} pages for the Foo tool suite |
| 1180 | \c |
| 1181 | \c \cfg{man-mindepth}{2} |
| 1182 | |
| 1183 | Then you have a file \c{make-foo.but}, and probably others like it |
| 1184 | as well, each of which looks something like this: |
| 1185 | |
| 1186 | \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred |
| 1187 | \c Bloggs} |
| 1188 | \c |
| 1189 | \c \H{man-foo} \cw{man} page for \c{make-foo} |
| 1190 | \c |
| 1191 | \c \S{man-foo-name} NAME |
| 1192 | \c |
| 1193 | \c \c{make-foo} - create Foo files for the Foo tool suite |
| 1194 | \c |
| 1195 | \c \S{man-foo-synopsis} SYNOPSIS |
| 1196 | \c |
| 1197 | \c ... and so on ... |
| 1198 | \e iiiiiiiiiiiiiiiii |
| 1199 | |
| 1200 | So when you're generating your main manual, you can include |
| 1201 | \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man} |
| 1202 | pages you have, and your \cw{man} pages will be formatted neatly as |
| 1203 | part of an appendix. Then, in a separate run of Halibut, you can |
| 1204 | just do |
| 1205 | |
| 1206 | \c halibut appendix.but make-foo.but |
| 1207 | |
| 1208 | and this will generate a \cw{man} page \c{output.1}, in which the |
| 1209 | headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man} |
| 1210 | page for \c{make-foo}} will not be displayed because of the |
| 1211 | \c{man-mindepth} directive. So the first visible heading in the |
| 1212 | output \cw{man} page will be \q{NAME}, exactly as a user would |
| 1213 | expect. |
| 1214 | |
| 1215 | } |
| 1216 | |
| 1217 | \S{output-man-characters} Configuring the characters used |
| 1218 | |
| 1219 | \dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}} |
| 1220 | |
| 1221 | \dd Specifies what character set the output should be in, similarly to |
| 1222 | \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}). |
| 1223 | |
| 1224 | \# FIXME: you're probably on your own in making sure that it's |
| 1225 | sensible to output man pages in that charset. |
| 1226 | |
| 1227 | \dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1228 | |
| 1229 | \dd Specifies the text to use as the \i{bullet} in bulletted lists. |
| 1230 | You can specify multiple fallback options. Works exactly like the |
| 1231 | \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}). |
| 1232 | |
| 1233 | \dt \I{\cw{\\cfg\{man-rule\}}}\cw{\\cfg\{man-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] |
| 1234 | |
| 1235 | \dd This specifies the text which should be used for drawing |
| 1236 | \i{horizontal rules} (generated by \i\c{\\rule}; see |
| 1237 | \k{input-rule}) when the manual page is rendered into text. |
| 1238 | It should only be one character long, but otherwise |
| 1239 | it works like the \cw{\\cfg\{text-rule\}} directive |
| 1240 | (see \k{output-text-characters}). |
| 1241 | |
| 1242 | \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{\}}] |
| 1243 | |
| 1244 | \dd Specifies the quotation marks to use, overriding any |
| 1245 | \cw{\\cfg\{quotes\}} directive. You can specify multiple |
| 1246 | fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} |
| 1247 | directive (see \k{output-text-characters}). |
| 1248 | |
| 1249 | \S{output-man-defaults} Default settings |
| 1250 | |
| 1251 | The \i{default settings} for the \cw{man} page output format are: |
| 1252 | |
| 1253 | \c \cfg{man-filename}{output.1} |
| 1254 | \c |
| 1255 | \c \cfg{man-identity}{} |
| 1256 | \c |
| 1257 | \c \cfg{man-headnumbers}{false} |
| 1258 | \c \cfg{man-mindepth}{0} |
| 1259 | \c |
| 1260 | \c \cfg{man-charset}{ASCII} |
| 1261 | \c \cfg{man-bullet}{\u2022}{o} |
| 1262 | \c \cfg{man-rule}{\u2500}{-} |
| 1263 | \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"} |
| 1264 | |
| 1265 | \H{output-info} GNU \c{info} |
| 1266 | |
| 1267 | This output format generates files which can be used with the \i{GNU |
| 1268 | \c{info}} program. |
| 1269 | |
| 1270 | There are typically multiple output files: a primary file whose name |
| 1271 | usually ends in \c{.info}, and one or more subsidiary files whose |
| 1272 | names have numbers on the end, so that they end in \c{.info-1}, |
| 1273 | \c{.info-2} and so on. Alternatively, this output format can be |
| 1274 | configured to output a single large file containing the whole |
| 1275 | document. |
| 1276 | |
| 1277 | The \c{info} output format supports the following configuration |
| 1278 | directives: |
| 1279 | |
| 1280 | \S{output-info-file} Controlling the output filenames |
| 1281 | |
| 1282 | \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}} |
| 1283 | |
| 1284 | \dd Sets the output file name in which to store the \c{info} file. |
| 1285 | This directive is implicitly generated if you provide a file name |
| 1286 | parameter after the command-line option \i\c{--info} (see |
| 1287 | \k{running-options}). |
| 1288 | |
| 1289 | \lcont{ |
| 1290 | |
| 1291 | The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to |
| 1292 | your output file name to produce any subsidiary files required. |
| 1293 | |
| 1294 | Note that \c{info} files refer to their own names internally, so |
| 1295 | these files cannot be \I{renaming \c{info} files}renamed after |
| 1296 | creation and remain useful. |
| 1297 | |
| 1298 | } |
| 1299 | |
| 1300 | \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}} |
| 1301 | |
| 1302 | \dd Sets the preferred \i{maximum file size} for each subsidiary |
| 1303 | file. As a special case, if you set this to zero, there will be no |
| 1304 | subsidiary files and the whole document will be placed in a single |
| 1305 | self-contained output file. (However, note that this file can still |
| 1306 | not be renamed usefully.) |
| 1307 | |
| 1308 | \lcont{ |
| 1309 | |
| 1310 | The preferred maximum file size is only a guideline. Halibut may be |
| 1311 | forced to exceed it if a single section of the document is larger |
| 1312 | than the maximum size (since individual \c{info} nodes may not be |
| 1313 | split between files). |
| 1314 | |
| 1315 | } |
| 1316 | |
| 1317 | \S{output-info-dimensions} Indentation and line width |
| 1318 | |
| 1319 | \dt \I{\cw{\\cfg\{info-width\}}}\cw{\\cfg\{info-width\}\{}\e{width}\cw{\}} |
| 1320 | |
| 1321 | \dd Sets the \I{text width}width of the main part of the document, |
| 1322 | in characters. Works exactly like the \cw{\\cfg\{text-width\}} |
| 1323 | directive (see \k{output-text-dimensions}). |
| 1324 | |
| 1325 | \dt \I{\cw{\\cfg\{info-indent-code\}}}\cw{\\cfg\{info-indent-code\}\{}\e{indent}\cw{\}} |
| 1326 | |
| 1327 | \dd Specifies the extra indentation for \I{code paragraphs, |
| 1328 | indentation} code paragraphs. Works exactly like the |
| 1329 | \cw{\\cfg\{text-indent-code\}} directive (see |
| 1330 | \k{output-text-dimensions}). |
| 1331 | |
| 1332 | \dt \I{\cw{\\cfg\{info-index-width\}}}\cw{\\cfg\{info-index-width\}\{}\e{width}\cw{\}} |
| 1333 | |
| 1334 | \dd Specifies how much horizontal space to leave in the index node |
| 1335 | for the text of \i{index terms}, before displaying the sections the |
| 1336 | terms occur in. |
| 1337 | |
| 1338 | \dt \I{\cw{\\cfg\{info-list-indent\}}}\cw{\\cfg\{info-list-indent\}\{}\e{indent}\cw{\}} |
| 1339 | |
| 1340 | \dd Specifies the extra indentation before the bullet or number in a |
| 1341 | \I{bulletted list, indentation}\I{numbered list, indentation}list |
| 1342 | item. Works exactly like the \cw{\\cfg\{text-list-indent\}} |
| 1343 | directive (see \k{output-text-dimensions}). |
| 1344 | |
| 1345 | \dt \I{\cw{\\cfg\{info-listitem-indent\}}}\cw{\\cfg\{info-listitem-indent\}\{}\e{indent}\cw{\}} |
| 1346 | |
| 1347 | \dd Specifies the additional indentation before the body of a list |
| 1348 | item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}} |
| 1349 | directive (see \k{output-text-dimensions}). |
| 1350 | |
| 1351 | \S{output-info-headings} Configuring heading display |
| 1352 | |
| 1353 | \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}} |
| 1354 | |
| 1355 | \dd Specifies the suffix text to be appended to each section number |
| 1356 | before displaying the section title. For example, if you set this to |
| 1357 | \cq{:\_}, then a typical section title might look something like |
| 1358 | \q{Section 3.1: Something Like This}. |
| 1359 | |
| 1360 | \dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1361 | |
| 1362 | \dd Specifies the text to be used to underline section titles. Works |
| 1363 | very much like the \cw{\\cfg\{text-chapter-underline\}} directive |
| 1364 | (see \k{output-text-headings}). You can specify more than one |
| 1365 | option, and Halibut will choose the first one supported by the |
| 1366 | character set. |
| 1367 | |
| 1368 | \S{output-info-characters} Controlling the characters used |
| 1369 | |
| 1370 | \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}} |
| 1371 | |
| 1372 | \dd Specifies what character set the output should be in, similarly to |
| 1373 | \cw{\\cfg\{text-charset\}} (see \k{output-text-characters}). |
| 1374 | |
| 1375 | \# FIXME: if you try sufficiently hard, you can probably find an |
| 1376 | output encoding that will break the info format by trampling on its |
| 1377 | special characters. So either don't do that, or tell us what we should |
| 1378 | do about it. |
| 1379 | |
| 1380 | \dt \I{\cw{\\cfg\{info-bullet\}}}\cw{\\cfg\{info-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1381 | |
| 1382 | \dd Specifies the text to use as the \i{bullet} in bulletted lists. |
| 1383 | You can specify multiple fallback options. Works exactly like the |
| 1384 | \cw{\\cfg\{text-bullet\}} directive (see |
| 1385 | \k{output-text-characters}). |
| 1386 | |
| 1387 | \dt \I{\cw{\\cfg\{info-rule\}}}\cw{\\cfg\{info-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1388 | |
| 1389 | \dd Specifies the text used to draw \i{horizontal rules}. You can |
| 1390 | specify multiple fallback options. Works exactly like the |
| 1391 | \cw{\\cfg\{text-rule\}} directive (see \k{output-text-characters}). |
| 1392 | |
| 1393 | \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{\}}] |
| 1394 | |
| 1395 | \dd Specifies the quotation marks to use, overriding any |
| 1396 | \cw{\\cfg\{quotes\}} directive. You can specify multiple |
| 1397 | fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} |
| 1398 | directive (see \k{output-text-characters}). |
| 1399 | |
| 1400 | \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{\}}] |
| 1401 | |
| 1402 | \dd Specifies how to display emphasised text. You can specify |
| 1403 | multiple fallback options. Works exactly like the |
| 1404 | \cw{\\cfg\{text-emphasis\}} directive (see |
| 1405 | \k{output-text-characters}). |
| 1406 | |
| 1407 | \S{output-info-misc} Miscellaneous configuration options |
| 1408 | |
| 1409 | \dt \I{\cw{\\cfg\{info-list-suffix\}}}\cw{\\cfg\{info-list-suffix\}\{}\e{text}\cw{\}} |
| 1410 | |
| 1411 | \dd Specifies the text to append to the item numbers in a |
| 1412 | \i{numbered list}. Works exactly like the |
| 1413 | \cw{\\cfg\{text-list-suffix\}} directive (see |
| 1414 | \k{output-text-misc}). |
| 1415 | |
| 1416 | \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short |
| 1417 | name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}] |
| 1418 | |
| 1419 | \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the |
| 1420 | header of the Info file. This mechanism is used to automatically |
| 1421 | generate the \i{\c{dir} file} at the root of a Unix system's |
| 1422 | \c{info} collection. |
| 1423 | |
| 1424 | \lcont{ |
| 1425 | |
| 1426 | The parameters to this directive are: |
| 1427 | |
| 1428 | \dt \e{section} |
| 1429 | |
| 1430 | \dd Specifies the section of the \c{dir} file in which you want your |
| 1431 | document referenced. For example, \q{Development}, or \q{Games}, or |
| 1432 | \q{Miscellaneous}. |
| 1433 | |
| 1434 | \dt \e{short name} |
| 1435 | |
| 1436 | \dd Specifies a short name for the directory entry, which will |
| 1437 | appear at the start of the menu line. |
| 1438 | |
| 1439 | \dt \e{long name} |
| 1440 | |
| 1441 | \dd Specifies a long name for the directory entry, which will appear |
| 1442 | at the end of the menu line. |
| 1443 | |
| 1444 | \dt \e{keyword} |
| 1445 | |
| 1446 | \dd This parameter is optional. If it is present, then the directory |
| 1447 | entry will cause a jump to a particular subsection of your document, |
| 1448 | rather than starting at the top. The subsection will be the one |
| 1449 | referred to by the given keyword (see \k{input-sections} for details |
| 1450 | about assigning keywords to document sections). |
| 1451 | |
| 1452 | For example, in a document describing many game programs, the |
| 1453 | configuration directive |
| 1454 | |
| 1455 | \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess |
| 1456 | \c game}{chess} |
| 1457 | |
| 1458 | might produce text in the \c{dir} file looking something like this: |
| 1459 | |
| 1460 | \c Games |
| 1461 | \c * Chess: (mygames)Chapter 3. Electronic chess game |
| 1462 | |
| 1463 | if the output file were called \c{mygames.info} and the keyword |
| 1464 | \c{chess} had been used to define Chapter 3 of the document. |
| 1465 | |
| 1466 | } |
| 1467 | |
| 1468 | \S{output-info-defaults} Default settings |
| 1469 | |
| 1470 | The \i{default settings} for the \c{info} output format are: |
| 1471 | |
| 1472 | \c \cfg{info-filename}{output.info} |
| 1473 | \c \cfg{info-max-file-size}{65536} |
| 1474 | \c |
| 1475 | \c \cfg{info-width}{70} |
| 1476 | \c \cfg{info-indent-code}{2} |
| 1477 | \c \cfg{info-index-width}{40} |
| 1478 | \c \cfg{info-list-indent}{1} |
| 1479 | \c \cfg{info-listitem-indent}{3} |
| 1480 | \c |
| 1481 | \c \cfg{info-section-suffix}{: } |
| 1482 | \c \cfg{info-underline}{\u203e}{-} |
| 1483 | \c |
| 1484 | \c \cfg{info-charset}{ASCII} |
| 1485 | \c \cfg{info-bullet}{\u2022}{-} |
| 1486 | \c \cfg{info-rule}{\u2500}{-} |
| 1487 | \c \cfg{info-quotes}{\u2018}{\u2019}{`}{'} |
| 1488 | \c \cfg{info-emphasis}{_}{_} |
| 1489 | \c |
| 1490 | \c \cfg{info-list-suffix}{.} |
| 1491 | |
| 1492 | and no \cw{\\cfg\{info-dir-entry\}} directives. |
| 1493 | |
| 1494 | \H{output-paper} Paper formats |
| 1495 | |
| 1496 | These output formats (currently PDF and PostScript) generate printable |
| 1497 | manuals. As such, they share a number of configuration directives. |
| 1498 | |
| 1499 | \S{output-pdf} \i{PDF} |
| 1500 | |
| 1501 | This output format generates a printable manual in PDF format. In |
| 1502 | addition, it uses some PDF interactive features to |
| 1503 | provide an outline of all the document's sections and clickable |
| 1504 | cross-references between sections. |
| 1505 | |
| 1506 | There is one configuration option specific to PDF: |
| 1507 | |
| 1508 | \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}} |
| 1509 | |
| 1510 | \dd Sets the \i{output file name} in which to store the PDF file. |
| 1511 | This directive is implicitly generated if you provide a file name |
| 1512 | parameter after the command-line option \i\c{--pdf} (see |
| 1513 | \k{running-options}). |
| 1514 | |
| 1515 | The \i{default settings} for the PDF output format are: |
| 1516 | |
| 1517 | \c \cfg{pdf-filename}{output.pdf} |
| 1518 | |
| 1519 | \S{output-ps} \i{PostScript} |
| 1520 | |
| 1521 | This output format generates a printable manual in PostScript format. |
| 1522 | This should look exactly identical to the PDF output (see |
| 1523 | \k{output-ps}), and uses \i\c{pdfmark} to arrange that if converted |
| 1524 | to PDF it will contain the same interactive features. |
| 1525 | |
| 1526 | There is one configuration option specific to PostScript: |
| 1527 | |
| 1528 | \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} |
| 1529 | |
| 1530 | \dd Sets the \i{output file name} in which to store the PostScript |
| 1531 | file. This directive is implicitly generated if you provide a file |
| 1532 | name parameter after the command-line option \i\c{--ps} (see |
| 1533 | \k{running-options}). |
| 1534 | |
| 1535 | The \i{default settings} for the PostScript output format are: |
| 1536 | |
| 1537 | \c \cfg{ps-filename}{output.ps} |
| 1538 | |
| 1539 | \S{output-paper-dimensions} Configuring layout and \i{measurements} |
| 1540 | |
| 1541 | All measurements are in PostScript \i{points} (72 points to the inch). |
| 1542 | |
| 1543 | \S2{output-paper-pagesize} Page properties |
| 1544 | |
| 1545 | \dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}} |
| 1546 | |
| 1547 | \dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}} |
| 1548 | |
| 1549 | \dd Specify the absolute limits of the paper. |
| 1550 | |
| 1551 | \dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}} |
| 1552 | |
| 1553 | \dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}} |
| 1554 | |
| 1555 | \dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}} |
| 1556 | |
| 1557 | \dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}} |
| 1558 | |
| 1559 | \dd Specify the margins. Most text appears within these margins, |
| 1560 | except: |
| 1561 | |
| 1562 | \lcont{ |
| 1563 | |
| 1564 | \b Section numbers, which appear in the left margin. |
| 1565 | |
| 1566 | \b The footer (containing page numbers), which appears in the bottom |
| 1567 | margin. |
| 1568 | |
| 1569 | } |
| 1570 | |
| 1571 | \S2{output-paper-line} Vertical spacing |
| 1572 | |
| 1573 | \dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}} |
| 1574 | |
| 1575 | \dd Specifies the amount of space between lines of text within a |
| 1576 | paragraph. (So, if the font size is 12pt and there is 2pt of leading, |
| 1577 | there will be 14pt between successive baselines.) |
| 1578 | |
| 1579 | \dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}} |
| 1580 | |
| 1581 | \dd Specifies the amount of vertical space between paragraphs. (The |
| 1582 | vertical space between paragraphs does \e{not} include |
| 1583 | \c{paper-base-leading}.) |
| 1584 | |
| 1585 | \S2{output-paper-indentation} Indentation |
| 1586 | |
| 1587 | \dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}} |
| 1588 | |
| 1589 | \dd Specifies the indentation of the bullet or number in a |
| 1590 | \I{bulletted list, indentation}bulletted or \I{numbered list, |
| 1591 | indentation}numbered \I{list, indentation}list, similarly to |
| 1592 | \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}). |
| 1593 | |
| 1594 | \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}} |
| 1595 | |
| 1596 | \dd Specifies the \e{extra} indentation for the body of a list item, |
| 1597 | over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}. |
| 1598 | |
| 1599 | \# FIXME: doesn't actually work, AFAICT. |
| 1600 | |
| 1601 | \dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}} |
| 1602 | |
| 1603 | \dd Specifies the amount of indentation for a level of quoting. Used |
| 1604 | for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c} |
| 1605 | (see \k{input-code}). |
| 1606 | |
| 1607 | \S2{output-paper-headings} Headings |
| 1608 | |
| 1609 | \dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}} |
| 1610 | |
| 1611 | \dd Specifies the space between the top margin and the top of the |
| 1612 | chapter heading. (Each chapter begins on a new page.) |
| 1613 | |
| 1614 | \dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}} |
| 1615 | |
| 1616 | \dd Specifies the vertical thickness of the black rule under chapter |
| 1617 | headings. |
| 1618 | |
| 1619 | \dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}} |
| 1620 | |
| 1621 | \dd Specifies the distance between the base of the chapter heading and |
| 1622 | the \e{base} of the underlying rule. |
| 1623 | |
| 1624 | \dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}} |
| 1625 | |
| 1626 | \dd Specifies the distance between the left margin and the \e{right} |
| 1627 | of section numbers (which are in the left margin). |
| 1628 | |
| 1629 | \S2{output-paper-index} Contents and index |
| 1630 | |
| 1631 | \dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}} |
| 1632 | |
| 1633 | \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}} |
| 1634 | |
| 1635 | \# FIXME: I do not know what dees one does. (I couldn't get either of |
| 1636 | them to do anything obvious, although the source indicates they should |
| 1637 | do something.) |
| 1638 | |
| 1639 | \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}} |
| 1640 | |
| 1641 | \dd Specifies the horizontal spacing between dots in \i\e{leaders} |
| 1642 | (the dotted lines that appear between section headings and page |
| 1643 | numbers in the table of contents). |
| 1644 | |
| 1645 | \dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}} |
| 1646 | |
| 1647 | \dd Specifies the distance between the bottom margin and the \e{base} |
| 1648 | of the footer (which contains page numbers). |
| 1649 | |
| 1650 | \dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}} |
| 1651 | |
| 1652 | \dd Specifies the number of columns the index should be divided into. |
| 1653 | |
| 1654 | \# FIXME: with this set to 1, the right-alignment of some index entry |
| 1655 | page numbers in the Halibut manual is decidedly wonky. |
| 1656 | |
| 1657 | \dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}} |
| 1658 | |
| 1659 | \dd Specifies the amount of \I{gutter} horizontal space between index |
| 1660 | columns. |
| 1661 | |
| 1662 | \dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}} |
| 1663 | |
| 1664 | \dd Specifies the minimum allowable horizontal space between an index |
| 1665 | entry and its page number. If the gap is smaller, the page number is |
| 1666 | moved to the next line. |
| 1667 | |
| 1668 | \S2{output-paper-fonts} \ii{Fonts} |
| 1669 | |
| 1670 | The directives in this section control which fonts Halibut uses for |
| 1671 | various kinds of text. Directives for setting the font normally take |
| 1672 | three font names, the first of which is used for normal text, the |
| 1673 | second for emphasised text, and the third for code. Any fonts which |
| 1674 | aren't specified are left unchanged. |
| 1675 | |
| 1676 | Halibut intrinsically knows about some fonts, and these fonts are also |
| 1677 | built into all PDF and most PostScript implementations. |
| 1678 | These fonts can be used without further formality. Halibut can also use |
| 1679 | other fonts, and can \I{embedding fonts}embed them it its PDF and |
| 1680 | PostScript output. These other fonts are supplied to Halibut by |
| 1681 | simply adding them to the list of input files on its command line. |
| 1682 | |
| 1683 | To use a \i{Type 1 font} Halibut needs both the font file itself, |
| 1684 | in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB) |
| 1685 | format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file. The AFM |
| 1686 | file must be specified first on the command line. If Halibut gets an |
| 1687 | AFM file without a corresponding Type 1 font file, the PostScript and |
| 1688 | PDF output files will still use that font, but they won't contain it. |
| 1689 | |
| 1690 | Using a \i{TrueType font} is rather simpler, and simply requires you to |
| 1691 | pass the font file to Halibut. Halibut does place a few restrictions on |
| 1692 | TrueType fonts, notably that they must include a \i{Unicode} mapping |
| 1693 | table and a PostScript name. |
| 1694 | |
| 1695 | Fonts are specified using their PostScript names. Running Halibut with |
| 1696 | the \i\cw{\-\-list-fonts} option causes it to display the PostScript |
| 1697 | names of all the fonts it intrinsically knows about, along with any |
| 1698 | fonts the were supplied as input files. |
| 1699 | |
| 1700 | \ii{Font sizes} are specified in PostScript \i{points} (72 to the inch). |
| 1701 | |
| 1702 | \dt \I{\cw{\\cfg\{paper-title-fonts\}}}\cw{\\cfg\{paper-title-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]] |
| 1703 | |
| 1704 | \dd Specifies the fonts to use for text in the document title. |
| 1705 | |
| 1706 | \dt \I{\cw{\\cfg\{paper-title-font-size\}}}\cw{\\cfg\{paper-title-font-size\}\{}\e{points}\cw{\}} |
| 1707 | |
| 1708 | \dd Specifies the \i{font size} of the document title. |
| 1709 | |
| 1710 | \dt \I{\cw{\\cfg\{paper-chapter-fonts\}}}\cw{\\cfg\{paper-chapter-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]] |
| 1711 | |
| 1712 | \dd Specifies the fonts to use for text in chapter titles. |
| 1713 | |
| 1714 | \dt \I{\cw{\\cfg\{paper-chapter-font-size\}}}\cw{\\cfg\{paper-chapter-font-size\}\{}\e{points}\cw{\}} |
| 1715 | |
| 1716 | \dd Specifies the \i{font size} of chapter titles. |
| 1717 | |
| 1718 | \dt \I{\cw{\\cfg\{paper-section-fonts\}}}\cw{\\cfg\{paper-section-fonts\}\{}\e{level}\cw{\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]] |
| 1719 | |
| 1720 | \dd Specifies the fonts to use for text in section headings at the \e{level} |
| 1721 | specified. |
| 1722 | |
| 1723 | \dt \I{\cw{\\cfg\{paper-section-font-size\}}}\cw{\\cfg\{paper-section-font-size\}\{}\e{level}\cw{\}\{}\e{points}\cw{\}} |
| 1724 | |
| 1725 | \dd Specifies the \i{font size} of section headings at the \e{level} |
| 1726 | specified. |
| 1727 | |
| 1728 | \dt \I{\cw{\\cfg\{paper-base-fonts\}}}\cw{\\cfg\{paper-base-fonts\}\{}\e{normal-font}\cw{\}}[\cw{\{}\e{emph-font}\cw{\}}[\cw{\{}\e{code-font}\cw{\}}]] |
| 1729 | |
| 1730 | \dd Specifies the fonts to use for text in the body text. |
| 1731 | |
| 1732 | \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}} |
| 1733 | |
| 1734 | \dd Specifies the \i{font size} of body text. |
| 1735 | |
| 1736 | \dt \I{\cw{\\cfg\{paper-code-fonts\}}}\cw{\\cfg\{paper-code-fonts\}\{}\e{bold-font}\cw{\}}[\cw{\{}\e{italic-font}\cw{\}}[\cw{\{}\e{normal-font}\cw{\}}]] |
| 1737 | |
| 1738 | \dd Specifies the fonts to use for text in code paragraps. The |
| 1739 | \e{bold-font} is used for bold text, the \e{italic-font} for |
| 1740 | emphasised text, and the \e{normal-font} for normal code. |
| 1741 | |
| 1742 | \dt \I{\cw{\\cfg\{paper-code-font-size\}}}\cw{\\cfg\{paper-code-font-size\}\{}\e{points}\cw{\}} |
| 1743 | |
| 1744 | \dd Specifies the \i{font size} of text in code paragraphs. |
| 1745 | |
| 1746 | \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}} |
| 1747 | |
| 1748 | \dd Specifies the font size to use for \i{page numbers}. |
| 1749 | |
| 1750 | \S2{output-paper-misc} Miscellaneous |
| 1751 | |
| 1752 | \dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}} |
| 1753 | |
| 1754 | \dd Specifies the vertical thickness of the rule produced by the |
| 1755 | \cw{\\rule} command (see \k{input-rule}). (Note that no extra space is |
| 1756 | reserved for thicker rules.) |
| 1757 | |
| 1758 | \S{output-paper-characters} Configuring the characters used |
| 1759 | |
| 1760 | \dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] |
| 1761 | |
| 1762 | \dd Specifies the text to use as the \i{bullet} in bulletted lists. |
| 1763 | You can specify multiple fallback options. Works exactly like the |
| 1764 | \cw{\\cfg\{text-bullet\}} directive (see |
| 1765 | \k{output-text-characters}). |
| 1766 | |
| 1767 | \dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}] |
| 1768 | |
| 1769 | \dd Specifies the quotation marks to use, overriding any |
| 1770 | \cw{\\cfg\{quotes\}} directive. You can specify multiple |
| 1771 | fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} |
| 1772 | directive (see \k{output-text-characters}). |
| 1773 | |
| 1774 | \S{output-paper-defaults} Default settings for paper formats |
| 1775 | |
| 1776 | The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e., |
| 1777 | \i{A4 paper}. |
| 1778 | |
| 1779 | \c \cfg{paper-page-width}{595} |
| 1780 | \c \cfg{paper-page-height}{842} |
| 1781 | \c |
| 1782 | \c \cfg{paper-left-margin}{72} |
| 1783 | \c \cfg{paper-top-margin}{72} |
| 1784 | \c \cfg{paper-right-margin}{72} |
| 1785 | \c \cfg{paper-bottom-margin}{108} |
| 1786 | \c |
| 1787 | \c \cfg{paper-base-leading}{1} |
| 1788 | \c \cfg{paper-base-para-spacing}{10} |
| 1789 | \c |
| 1790 | \c \cfg{paper-list-indent}{6} |
| 1791 | \c \cfg{paper-listitem-indent}{18} |
| 1792 | \c \cfg{paper-quote-indent}{18} |
| 1793 | \c |
| 1794 | \c \cfg{paper-chapter-top-space}{72} |
| 1795 | \c \cfg{paper-chapter-underline-thickness}{3} |
| 1796 | \c \cfg{paper-chapter-underline-depth}{14} |
| 1797 | \c \cfg{paper-sect-num-left-space}{12} |
| 1798 | \c |
| 1799 | \c \cfg{paper-contents-index-step}{24} |
| 1800 | \c \cfg{paper-contents-margin}{84} |
| 1801 | \c \cfg{paper-leader-separation}{12} |
| 1802 | \c \cfg{paper-footer-distance}{32} |
| 1803 | \c \cfg{paper-index-columns}{2} |
| 1804 | \c \cfg{paper-index-gutter}{36} |
| 1805 | \c \cfg{paper-index-minsep}{18} |
| 1806 | \c |
| 1807 | \c \cfg{paper-base-fonts}{Times-Roman}{Times-Italic}{Courier} |
| 1808 | \c \cfg{paper-base-font-size}{12} |
| 1809 | \c \cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier} |
| 1810 | \c \cfg{paper-code-font-size}{12} |
| 1811 | \c \cfg{paper-title-fonts}{Helvetica-Bold} |
| 1812 | \c {Helvetica-BoldOblique}{Courier-Bold} |
| 1813 | \c \cfg{paper-title-font-size}{24} |
| 1814 | \c \cfg{paper-chapter-fonts}{Helvetica-Bold} |
| 1815 | \c {Helvetica-BoldOblique}{Courier-Bold} |
| 1816 | \c \cfg{paper-chapter-font-size}{20} |
| 1817 | \c \cfg{paper-section-fonts}{0}{Helvetica-Bold} |
| 1818 | \c {Helvetica-BoldOblique}{Courier-Bold} |
| 1819 | \c \cfg{paper-section-font-size}{0}{16} |
| 1820 | \c \cfg{paper-section-fonts}{1}{Helvetica-Bold} |
| 1821 | \c {Helvetica-BoldOblique}{Courier-Bold} |
| 1822 | \c \cfg{paper-section-font-size}{1}{14} |
| 1823 | \c \cfg{paper-section-fonts}{2}{Helvetica-Bold} |
| 1824 | \c {Helvetica-BoldOblique}{Courier-Bold} |
| 1825 | \c \cfg{paper-section-font-size}{2}{13} |
| 1826 | \c ... and so on for all section levels below this ... |
| 1827 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
| 1828 | \c |
| 1829 | \c \cfg{paper-pagenum-font-size}{12} |
| 1830 | \c |
| 1831 | \c \cfg{paper-rule-thickness}{1} |
| 1832 | \c |
| 1833 | \c \cfg{paper-bullet}{\u2022}{-} |
| 1834 | \c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'} |