16ea3abe |
1 | \C{output} Halibut output formats |
2 | |
339cbe09 |
3 | This chapter describes each of Halibut's current \i{output formats}. |
4 | It gives some general information about the format, and also |
5 | describes all the \i{configuration directives} which are specific to |
6 | that format. |
16ea3abe |
7 | |
8 | \H{output-text} Plain text |
9 | |
339cbe09 |
10 | This output format generates the document as a single \i{plain text} |
0a6347b4 |
11 | file. |
16ea3abe |
12 | |
339cbe09 |
13 | The output file is currently assumed to be in the \i{ISO 8859-1} |
16ea3abe |
14 | character set. Any Unicode characters representable in this set will |
15 | be output verbatim; any other characters will not be output and |
339cbe09 |
16 | their \i{fallback text} (if any) will be used instead. |
16ea3abe |
17 | |
18 | The precise formatting of the text file can be controlled by a |
19 | variety of configuration directives. They are listed in the |
20 | following subsections. |
21 | |
0a6347b4 |
22 | \S{output-text-file} Output file name |
23 | |
24 | \dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}} |
25 | |
26 | \dd Sets the \i{output file name} in which to store the text file. |
27 | This directive is implicitly generated if you provide a file name |
28 | parameter after the command-line option \i\c{--text} (see |
29 | \k{running-options}). |
30 | |
16ea3abe |
31 | \S{output-text-dimensions} Indentation and line width |
32 | |
33 | This section describes the configuration directives which control |
339cbe09 |
34 | the \i{horizontal dimensions} of the output text file: how much |
16ea3abe |
35 | paragraphs are indented by and how long the lines are. |
36 | |
339cbe09 |
37 | \dt \I{\cw{\\cfg\{text-width\}}}\cw{\\cfg\{text-width\}\{}\e{width}\cw{\}} |
16ea3abe |
38 | |
339cbe09 |
39 | \dd Sets the \I{text width}width of the main part of the document, |
40 | in characters. This width will be used for wrapping paragraphs and |
41 | for centring titles (if you have asked for titles to be centred - |
42 | see \k{output-text-headings}). This width does \e{not} include the |
43 | left indentation set by \cw{\\cfg\{text-indent\}}; if you specify an |
16ea3abe |
44 | indent of 8 and a width of 64, your maximum output line length will |
45 | be 72. |
46 | |
339cbe09 |
47 | \dt \I{\cw{\\cfg\{text-indent\}}}\cw{\\cfg\{text-indent\}\{}\e{indent}\cw{\}} |
16ea3abe |
48 | |
339cbe09 |
49 | \dd Sets the left \i{indentation} for the document. If you set this |
50 | to zero, your document will look like an ordinary text file as |
51 | someone with a text editor might have written it; if you set it |
52 | above zero, the text file will have a \i{margin} down the left in |
53 | the style of some printed manuals, and you can then configure the |
54 | section numbers to appear in this margin (see |
55 | \k{output-text-headings}). |
16ea3abe |
56 | |
339cbe09 |
57 | \dt \I{\cw{\\cfg\{text-indent-code\}}}\cw{\\cfg\{text-indent-code\}\{}\e{indent}\cw{\}} |
16ea3abe |
58 | |
59 | \dd Specifies how many extra characters of indentation (on top of |
339cbe09 |
60 | the normal left indent) should be given to \I{code paragraphs, |
61 | indentation} code paragraphs. |
16ea3abe |
62 | |
339cbe09 |
63 | \dt \I{\cw{\\cfg\{text-list-indent\}}}\cw{\\cfg\{text-list-indent\}\{}\e{indent}\cw{\}} |
16ea3abe |
64 | |
65 | \dd Specifies how many extra spaces should be used to indent the |
339cbe09 |
66 | bullet or number in a \I{bulletted list, indentation}bulletted or |
67 | \I{numbered list, indentation}numbered \I{list, indentation}list. |
68 | The actual body of the list item will be indented by this much |
69 | \e{plus} the value configured by \cw{\\cfg\{text-listitem-indent\}}. |
16ea3abe |
70 | |
339cbe09 |
71 | \dt \I{\cw{\\cfg\{text-listitem-indent\}}}\cw{\\cfg\{text-listitem-indent\}\{}\e{indent}\cw{\}} |
16ea3abe |
72 | |
73 | \dd Specifies how many extra spaces should be used to indent the |
74 | body of a list item, over and above the number configured in |
75 | \cw{\\cfg\{text-list-indent\}}. |
76 | |
339cbe09 |
77 | \dt \I{\cw{\\cfg\{text-indent-preamble\}}}\cw{\\cfg\{text-indent-preamble\}\{}\e{boolean}\cw{\}} |
16ea3abe |
78 | |
339cbe09 |
79 | \dd When this is set to \c{true}, the document \i{preamble} (i.e. any |
16ea3abe |
80 | paragraphs appearing before the first chapter heading) will be |
81 | indented to the level specified by \cw{\\cfg\{text-indent\}}. If |
82 | this setting is \c{false}, the document preamble will not be |
83 | indented at all from the left margin. |
84 | |
339cbe09 |
85 | \S{output-text-headings} \ii{Configuring heading display} |
16ea3abe |
86 | |
87 | The directives in this section allow you to configure the appearance |
88 | of the title, chapter and section headings in your text file. |
89 | |
339cbe09 |
90 | Several of the directives listed below specify the \i{alignment} of |
91 | a heading. These alignment options have three possible values: |
16ea3abe |
92 | |
339cbe09 |
93 | \dt \i\c{left} |
16ea3abe |
94 | |
95 | \dd Align the heading to the very left of the text file (column zero). |
96 | |
339cbe09 |
97 | \dt \i\c{leftplus} |
16ea3abe |
98 | |
99 | \dd Align the section title to the left of the main display region |
100 | (in other words, indented to the level specified by |
101 | \cw{\\cfg\{text-indent\}}). The section \e{number} is placed to the |
102 | left of that (so that it goes in the margin if there is room). |
103 | |
339cbe09 |
104 | \dt \i\c{centre} |
16ea3abe |
105 | |
106 | \dd Centre the heading. |
107 | |
108 | Also, several of the directives below specify how a title should be |
339cbe09 |
109 | \I{underlining}underlined. The parameter to one of these directives |
110 | should be either blank (\cw{\{\}}) or a single character. In the |
111 | latter case, that character will be used to underline the title. So |
112 | you might want to specify, for example, |
113 | \cw{\\text-title-underline\{=\}} but |
16ea3abe |
114 | \cw{\\text-chapter-underline\{-\}}. |
115 | |
339cbe09 |
116 | \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}} |
16ea3abe |
117 | |
118 | \dd Specifies the alignment of the overall document title: \c{left}, |
119 | \c{leftplus} or \c{centre}. |
120 | |
339cbe09 |
121 | \dt \I{\cw{\\cfg\{text-title-underline\}}}\cw{\\cfg\{text-title-underline\}\{}\e{underline-character}\cw{\}} |
16ea3abe |
122 | |
123 | \dd Specifies how the overall document title should be underlined. |
124 | |
339cbe09 |
125 | \dt \I{\cw{\\cfg\{text-chapter-align\}}}\cw{\\cfg\{text-chapter-align\}\{}\e{alignment}\cw{\}} |
16ea3abe |
126 | |
127 | \dd Specifies the alignment of chapter and appendix headings. |
128 | |
339cbe09 |
129 | \dt \I{\cw{\\cfg\{text-chapter-underline\}}}\cw{\\cfg\{text-chapter-underline\}\{}\e{underline-character}\cw{\}} |
16ea3abe |
130 | |
131 | \dd Specifies how chapter and appendix headings should be underlined. |
132 | |
339cbe09 |
133 | \dt \I{\cw{\\cfg\{text-chapter-numeric\}}}\cw{\\cfg\{text-chapter-numeric\}\{}\e{boolean}\cw{\}} |
16ea3abe |
134 | |
135 | \dd If this is set to \c{true}, then chapter headings will not |
136 | contain the word \q{Chapter} (or whatever other word you have |
137 | defined in its place - see \k{input-sections} and \k{input-config}); |
138 | they will just contain the chapter \e{number}, followed by the |
139 | chapter title. If you set this to \c{false}, chapter headings will |
140 | be prefixed by \q{Chapter} or equivalent. |
141 | |
339cbe09 |
142 | \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}} |
16ea3abe |
143 | |
144 | \dd This specifies the suffix text to be appended to the chapter |
145 | number, before displaying the chapter title. For example, if you set |
146 | this to \q{\cw{:\_}}, then the chapter title might look something |
147 | like \q{Chapter 2: Doing Things}. |
148 | |
339cbe09 |
149 | \dt \I{\cw{\\cfg\{text-section-align\}}}\cw{\\cfg\{text-section-align\}\{}\e{level}\cw{\}\{}\e{alignment}\cw{\}} |
16ea3abe |
150 | |
151 | \dd Specifies the alignment of section headings at a particular |
152 | level. The \e{level} parameter specifies which level of section |
153 | headings you want to affect: 0 means first-level headings (\c{\\H}), |
154 | 1 means second-level headings (\c{\\S}), 2 means the level below |
155 | that (\c{\\S2}), and so on. The \e{alignment} parameter is treated |
156 | just like the other alignment directives listed above. |
157 | |
339cbe09 |
158 | \dt \I{\cw{\\cfg\{text-section-underline\}}}\cw{\\cfg\{text-section-underline\}\{}\e{level}\cw{\}\{}\e{underline-character}\cw{\}} |
16ea3abe |
159 | |
160 | \dd Specifies how to underline section headings at a particular level. |
161 | |
339cbe09 |
162 | \dt \I{\cw{\\cfg\{text-section-numeric\}}}\cw{\\cfg\{text-section-numeric\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} |
16ea3abe |
163 | |
164 | \dd Specifies whether section headings at a particular level should |
165 | contain the word \q{Section} or equivalent (if \c{false}), or should |
166 | be numeric only (if \c{true}). |
167 | |
339cbe09 |
168 | \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} |
16ea3abe |
169 | |
339cbe09 |
170 | \dd Specifies the \I{suffix text, in section titles}suffix text to |
171 | be appended to section numbers at a particular level, before |
172 | displaying the section title. |
16ea3abe |
173 | |
174 | \S{output-text-misc} Miscellaneous configuration options |
175 | |
339cbe09 |
176 | \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}} |
16ea3abe |
177 | |
339cbe09 |
178 | \dd If this is set to \c{true}, \i{version ID paragraphs} (defined |
179 | using the \i\c{\\versionid} command - see \k{input-blurb}) will be |
180 | included at the bottom of the text file. If it is set to \c{false}, |
181 | they will be omitted completely. |
16ea3abe |
182 | |
339cbe09 |
183 | \dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}} |
16ea3abe |
184 | |
339cbe09 |
185 | \dd This specifies the text which should be used as the \i{bullet} |
186 | in bulletted lists. It can be one character |
16ea3abe |
187 | (\cw{\\cfg\{text-bullet\}\{-\}}), or more than one |
188 | (\cw{\\cfg\{text-bullet\}\{(*)\}}). |
189 | |
190 | \# FIXME: code indentation is configurable, therefore \quote |
191 | \# indentation probably ought to be as well. |
192 | |
193 | \# FIXME: text-indent-* should be consistently named. |
194 | |
195 | \S{output-text-defaults} Default settings |
196 | |
339cbe09 |
197 | The \i{default settings} for Halibut's plain text output format are: |
16ea3abe |
198 | |
0a6347b4 |
199 | \c \cfg{text-filename}{output.txt} |
200 | \c |
16ea3abe |
201 | \c \cfg{text-width}{68} |
202 | \c \cfg{text-indent}{7} |
203 | \c \cfg{text-indent-code}{2} |
204 | \c \cfg{text-list-indent}{1} |
205 | \c \cfg{text-listitem-indent}{3} |
206 | \c \cfg{text-indent-preamble}{false} |
207 | \c |
208 | \c \cfg{text-title-align}{centre} |
209 | \c \cfg{text-title-underline}{=} |
210 | \c |
211 | \c \cfg{text-chapter-align}{left} |
212 | \c \cfg{text-chapter-underline}{-} |
213 | \c \cfg{text-chapter-numeric}{false} |
214 | \c \cfg{text-chapter-suffix}{: } |
215 | \c |
216 | \c \cfg{text-section-align}{0}{leftplus} |
217 | \c \cfg{text-section-underline}{0}{} |
218 | \c \cfg{text-section-numeric}{0}{true} |
219 | \c \cfg{text-section-suffix}{0}{ } |
220 | \c |
221 | \c \cfg{text-section-align}{1}{leftplus} |
222 | \c \cfg{text-section-underline}{1}{} |
223 | \c \cfg{text-section-numeric}{1}{true} |
224 | \c \cfg{text-section-suffix}{1}{ } |
225 | \c |
226 | \c ... and so on for all section levels below this ... |
227 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
228 | |
229 | \H{output-html} HTML |
230 | |
339cbe09 |
231 | This output format generates an \i{HTML} version of the document. By |
16ea3abe |
232 | default, this will be in multiple files, starting with |
233 | \c{Contents.html} and splitting the document into files by chapter |
234 | and/or subsection. You can configure precisely how the text is split |
235 | between HTML files using the configuration commands described in |
236 | this section. In particular, you can configure Halibut to output one |
0a6347b4 |
237 | single HTML file instead of multiple ones. |
16ea3abe |
238 | |
339cbe09 |
239 | Strictly speaking, the output format is \i{XHTML} 1.0 Transitional, |
16ea3abe |
240 | which is why all of the configuration directives start with the word |
241 | \c{xhtml} rather than \c{html}. |
242 | |
0a6347b4 |
243 | \S{output-html-file} Controlling the output file names |
244 | |
245 | \dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}} |
246 | |
247 | \dd Sets the \i{output file name} in which to store the top-level |
248 | contents page. Since this is the first page a user ought to see when |
249 | beginning to read the document, a good choice in many cases might be |
fc8e7adb |
250 | \c{index.html} (although this is not the default, for historical |
0a6347b4 |
251 | reasons). |
252 | |
253 | \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}} |
254 | |
255 | \dd Sets the file name in which to store the document's index. |
256 | |
257 | \dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}} |
258 | |
259 | \dd Provides a \i{template} to be used when constructing the file |
260 | names of each chapter or section of the document. This template |
261 | should contain at least one \i\e{formatting command}, in the form of |
262 | a per cent sign followed by a letter. (If you need a literal per |
263 | cent sign, you can write \c{%%}.) |
264 | |
265 | \lcont{ |
266 | |
267 | The formatting commands used in this template are: |
268 | |
269 | \dt \i\c{%N} |
270 | |
271 | \dd Expands to the visible title of the section, with white space |
272 | removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching |
273 | Fish}}, this formatting command would expand to |
274 | \q{\cw{CatchingFish}}. |
275 | |
276 | \dt \i\c{%n} |
277 | |
278 | \dd Expands to the type and number of the section, without white |
279 | space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in |
280 | section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on. |
281 | If the section has no number (an unnumbered chapter created using |
282 | \c{\\U}), this directive falls back to doing the same thing as |
283 | \c{%N}. |
284 | |
285 | \dt \i\c{%b} |
286 | |
287 | \dd Expands to the bare number of the section. So in chapter 1 this |
288 | would expand to \q{\cw{1}}; in section A.4.3 it would expand to |
289 | \q{\cw{A.4.3}}, and so on. If the section has no number (an |
290 | unnumbered chapter created using \c{\\U}), this directive falls back |
291 | to doing the same thing as \c{%N}. |
292 | |
293 | \dt \i\c{%k} |
294 | |
295 | \dd Expands to the internal keyword specified in the section title. |
296 | So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this |
297 | formatting command would expand to \q{\cw{fish}}. If the section has |
298 | no keyword (an unnumbered chapter created using \c{\\U}), this |
299 | directive falls back to doing the same thing as \c{%N}. |
300 | |
301 | These formatting directives can also be used in the |
302 | \cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see |
303 | \k{output-html-misc}). |
304 | |
305 | } |
306 | |
307 | \dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}} |
308 | |
309 | \dd Sets the file name in which to store the entire document, if |
310 | Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to |
311 | produce a single self-contained file. Both this directive \e{and} |
312 | \c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you |
313 | provide a file name parameter after the command-line option |
314 | \i\c{--html} (see \k{running-options}). |
315 | |
16ea3abe |
316 | \S{output-html-split} Controlling the splitting into HTML files |
317 | |
318 | By default, the HTML output from Halibut is split into multiple |
319 | files. Each file typically contains a single chapter or section and |
320 | everything below it, unless subsections of that chapter are |
321 | themselves split off into further files. |
322 | |
323 | Most files also contain a contents section, giving hyperlinks to the |
324 | sections in the file and/or the sections below it. |
325 | |
326 | The configuration directives listed below allow you to configure the |
327 | splitting into files, and the details of the contents sections. |
328 | |
339cbe09 |
329 | \dt \I{\cw{\\cfg\{xhtml-leaf-level\}}}\cw{\\cfg\{xhtml-leaf-level\}\{}\e{depth}\cw{\}} |
16ea3abe |
330 | |
331 | \dd This setting indicates the depth of section which should be |
339cbe09 |
332 | given a \I{leaf file}\q{leaf} file (a file with no sub-files). So if |
333 | you set it to 1, for example, then every chapter will be given its |
334 | own HTML file, plus a top-level \i{contents file}. If you set this |
335 | to 2, then each chapter \e{and} each \c{\\H} section will have a |
336 | file, and the chapter files will mostly just contain links to their |
337 | \i{sub-file}s. |
16ea3abe |
338 | |
339 | \lcont{ |
340 | |
341 | If you set this option to zero, then the whole document will appear |
342 | in a single file. If you do this, Halibut will call that file |
339cbe09 |
343 | \i\c{Manual.html} instead of \i\c{Contents.html}. |
16ea3abe |
344 | |
0a6347b4 |
345 | This option is automatically set to zero if you provide a file name |
346 | parameter after the command-line option \i\c{--html} (see |
347 | \k{running-options}), because you have specified a single file name |
348 | and so Halibut assumes you want the whole document to be placed in |
349 | that file. |
350 | |
16ea3abe |
351 | } |
352 | |
339cbe09 |
353 | \dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}} |
16ea3abe |
354 | |
339cbe09 |
355 | \dd This directive allows you to specify how \I{depth of |
356 | contents}deep the contents section in a particular file should go. |
16ea3abe |
357 | |
358 | \lcont{ |
359 | |
360 | The \e{level} parameter indicates which level of contents section |
361 | you are dealing with. 0 denotes the main contents section in the |
362 | topmost file \c{Contents.html}; 1 denotes a contents section in a |
363 | chapter file; 2 is a contents section in a file containing a \c{\\H} |
364 | heading, and so on. Currently you can't go below level 5 (which |
365 | corresponds to a \c{\\S3} heading). |
366 | |
367 | The \e{depth} parameter indicates the maximum depth of heading which |
368 | will be shown in this contents section. Again, 1 denotes a chapter, |
369 | 2 is a \c{\\H} heading, 3 is a \c{\\S} heading, and so on. |
370 | |
371 | So, for example: \cw{\\cfg\{xhtml-contents-depth-1\}\{3\}} instructs |
372 | Halibut to put contents links in chapter files for all sections down |
373 | to \c{\\S} level, but not to go into any more detail than that. |
374 | |
375 | } |
376 | |
377 | \# FIXME: this is utterly ghastly. For a start, it should include |
378 | \# the level as a separate argument, like the text section config |
379 | \# directives. Secondly, it shouldn't be limited in depth! |
380 | |
339cbe09 |
381 | \dt \I{\cw{\\cfg\{xhtml-leaf-contains-contents\}}}\cw{\\cfg\{xhtml-leaf-contains-contents\}\{}\e{boolean}\cw{\}} |
16ea3abe |
382 | |
383 | \dd If you set this to \c{true}, then each leaf file will contain |
384 | its own contents section which summarises the text within it. |
385 | |
339cbe09 |
386 | \dt \I{\cw{\\cfg\{xhtml-leaf-smallest-contents\}}}\cw{\\cfg\{xhtml-leaf-smallest-contents\}\{}\e{number}\cw{\}} |
16ea3abe |
387 | |
388 | \dd Contents sections in leaf files are not output at all if they |
389 | contain very few entries (on the assumption that it just isn't worth |
390 | bothering). This directive configures the minimum number of entries |
391 | required in a leaf contents section to make Halibut bother |
392 | generating it at all. |
393 | |
394 | \S{output-html-html} Including pieces of your own HTML |
395 | |
396 | The directives in this section allow you to supply pieces of |
339cbe09 |
397 | \I{HTML}\i{verbatim HTML} code, which will be included in various |
398 | parts of the output files. |
16ea3abe |
399 | |
339cbe09 |
400 | \dt \I{\cw{\\cfg\{xhtml-head-end\}}}\cw{\\cfg\{xhtml-head-end\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
401 | |
402 | \dd The text you provide in this directive is placed at the end of |
339cbe09 |
403 | the \i\cw{<HEAD>} section of each output HTML file. So this is a |
404 | good place to put, for example, a link to a \i{CSS} \i{stylesheet}. |
16ea3abe |
405 | |
339cbe09 |
406 | \dt \I{\cw{\\cfg\{xhtml-body-tag\}}}\cw{\\cfg\{xhtml-body-tag\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
407 | |
408 | \dd The text you provide in this directive is used in place of the |
339cbe09 |
409 | \i\cw{<BODY>} tag in each output file. So if you wanted to define a |
410 | \i{background colour}, for example, you could write |
16ea3abe |
411 | \cw{\\cfg\{xhtml-body-tag\}\{<body bg="#123456">\}}. |
412 | |
339cbe09 |
413 | \dt \I{\cw{\\cfg\{xhtml-body-start\}}}\cw{\\cfg\{xhtml-body-start\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
414 | |
415 | \dd The text you provide in this directive is placed at the |
339cbe09 |
416 | beginning of the \i\cw{<BODY>} section of each output HTML file. So |
417 | if you intend your HTML files to be part of a web site with a |
418 | standard \i{house style}, and the style needs a \i{header} at the |
419 | top of every page, this is where you can add that header. |
16ea3abe |
420 | |
339cbe09 |
421 | \dt \I{\cw{\\cfg\{xhtml-body-end\}}}\cw{\\cfg\{xhtml-body-end\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
422 | |
339cbe09 |
423 | \dd The text you provide in this directive is placed at the end of |
424 | the \i\cw{<BODY>} section of each output HTML file. So if you intend |
425 | your HTML files to be part of a web site with a standard \i{house |
426 | style}, and the style needs a \i{footer} at the bottom of every |
427 | page, this is where you can add that footer. |
16ea3abe |
428 | |
339cbe09 |
429 | \dt \I{\cw{\\cfg\{xhtml-address-start\}}}\cw{\\cfg\{xhtml-address-start\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
430 | |
431 | \dd The text you provide in this directive is placed at the |
339cbe09 |
432 | beginning of the \i\cw{<ADDRESS>} section at the bottom of each |
433 | output HTML file. This might be a good place to put authors' |
434 | \i{contact details}, for example. |
16ea3abe |
435 | |
339cbe09 |
436 | \dt \I{\cw{\\cfg\{xhtml-address-end\}}}\cw{\\cfg\{xhtml-address-end\}\{}\e{HTML text}\cw{\}} |
16ea3abe |
437 | |
339cbe09 |
438 | \dd The text you provide in this directive is placed at the end of |
439 | the \i\cw{<ADDRESS>} section at the bottom of each output HTML file, |
440 | after the version IDs (if present). |
16ea3abe |
441 | |
339cbe09 |
442 | \dt \I{\cw{\\cfg\{xhtml-navigation-attributes\}}}\cw{\\cfg\{xhtml-navigation-attributes\}\{}\e{HTML attributes}\cw{\}} |
16ea3abe |
443 | |
444 | \dd The text you provide in this directive is included inside the |
339cbe09 |
445 | \cw{<P>} tag containing the \i{navigation links} at the top of each |
446 | page (\i{\q{Previous}} / \i{\q{Contents}} / \i{\q{Next}}). So if you |
447 | wanted the navigation links to have a particular CSS style, you |
448 | could write |
16ea3abe |
449 | \cw{\\cfg\{xhtml-navigation-attributes\}\{class="foo"\}}, and the |
450 | navigation-links paragraph would then begin with the tag \cw{<p |
451 | class="foo">}. |
452 | |
339cbe09 |
453 | \S{output-html-headings} \ii{Configuring heading display} |
16ea3abe |
454 | |
339cbe09 |
455 | \dt \I{\cw{\\cfg\{xhtml-chapter-numeric\}}}\cw{\\cfg\{xhtml-chapter-numeric\}\{}\e{boolean}\cw{\}} |
16ea3abe |
456 | |
457 | \dd If this is set to \c{true}, then chapter headings will not |
458 | contain the word \q{Chapter} (or whatever other word you have |
459 | defined in its place - see \k{input-sections} and \k{input-config}); |
460 | they will just contain the chapter \e{number}, followed by the |
461 | chapter title. If you set this to \c{false}, chapter headings will |
462 | be prefixed by \q{Chapter} or equivalent. |
463 | |
339cbe09 |
464 | \dt \I{\cw{\\cfg\{xhtml-chapter-suffix\}}}\cw{\\cfg\{xhtml-chapter-suffix\}\{}\e{text}\cw{\}} |
16ea3abe |
465 | |
466 | \dd This specifies the suffix text to be appended to the chapter |
467 | number, before displaying the chapter title. For example, if you set |
468 | this to \q{\cw{:\_}}, then the chapter title might look something |
469 | like \q{Chapter 2: Doing Things}. |
470 | |
339cbe09 |
471 | \dt \I{\cw{\\cfg\{xhtml-section-numeric\}}}\cw{\\cfg\{xhtml-section-numeric\}\{}\e{boolean}\cw{\}} |
16ea3abe |
472 | |
473 | \dd Specifies whether section headings at a particular level should |
474 | contain the word \q{Section} or equivalent (if \c{false}), or should |
475 | be numeric only (if \c{true}). The \e{level} parameter specifies |
476 | which level of section headings you want to affect: 0 means |
477 | first-level headings (\c{\\H}), 1 means second-level headings |
478 | (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on. |
479 | |
339cbe09 |
480 | \dt \I{\cw{\\cfg\{xhtml-section-suffix\}}}\cw{\\cfg\{xhtml-section-suffix\}\{}\e{text}\cw{\}} |
16ea3abe |
481 | |
482 | \dd Specifies the suffix text to be appended to section numbers at a |
483 | particular level, before displaying the section title. |
484 | |
485 | \S{output-html-misc} Miscellaneous options |
486 | |
0a6347b4 |
487 | \dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}} |
488 | |
489 | \dd This directive lets you specify a \i{template}, with exactly the |
490 | same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see |
fc8e7adb |
491 | \k{output-html-file}), to be used for the anchor names (\i\cw{<A |
492 | NAME="...">}) used to allow URLs to refer to specific sections |
493 | within a particular HTML file. So if you set this to \q{\cw{%k}}, |
494 | for example, then each individual section in your document will be |
0a6347b4 |
495 | addressable by means of a URL ending in a \c{#} followed by your |
496 | internal section keyword. |
497 | |
339cbe09 |
498 | \dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}} |
16ea3abe |
499 | |
339cbe09 |
500 | \dd If this is set to \c{true}, \i{version ID paragraphs} (defined using |
501 | the \i\c{\\versionid} command - see \k{input-blurb}) will be included |
502 | visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML |
16ea3abe |
503 | file. If it is set to \c{false}, they will be omitted completely. |
504 | |
505 | \# FIXME: surely it would be better to include them in HTML |
506 | \# comments? The only question is whether they should be _visible_. |
507 | |
339cbe09 |
508 | \dt \I{\cw{\\cfg\{xhtml-suppress-address\}}}\cw{\\cfg\{xhtml-suppress-address\}\{}\e{boolean}\cw{\}} |
16ea3abe |
509 | |
339cbe09 |
510 | \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the |
16ea3abe |
511 | bottom of each HTML file will be omitted completely. (This will |
339cbe09 |
512 | therefore also cause \i{version IDs} not to be included.) |
16ea3abe |
513 | |
339cbe09 |
514 | \dt \I{\cw{\\cfg\{xhtml-author\}}}\cw{\\cfg\{xhtml-author\}\{}\e{text}\cw{\}} |
16ea3abe |
515 | |
339cbe09 |
516 | \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META |
517 | name="author">} tag in the output HTML files, so that browsers which |
518 | support this can automatically identify the \i{author} of the document. |
16ea3abe |
519 | |
339cbe09 |
520 | \dt \I{\cw{\\cfg\{xhtml-description\}}}\cw{\\cfg\{xhtml-description\}\{}\e{text}\cw{\}} |
16ea3abe |
521 | |
339cbe09 |
522 | \dd The text supplied here goes in a \I{\cw{<META>} tags}\cw{<META |
523 | name="description">} tag in the output HTML files, so that browsers |
524 | which support this can easily pick out a brief \I{description, of |
525 | document}description of the document. |
16ea3abe |
526 | |
527 | \S{output-html-defaults} Default settings |
528 | |
339cbe09 |
529 | The \i{default settings} for Halibut's HTML output format are: |
16ea3abe |
530 | |
0a6347b4 |
531 | \c \cfg{xhtml-contents-filename}{Contents.html} |
532 | \c \cfg{xhtml-index-filename}{IndexPage.html} |
533 | \c \cfg{xhtml-template-filename}{%n.html} |
534 | \c \cfg{xhtml-single-filename}{Manual.html} |
535 | \c \cfg{xhtml-template-fragment}{%b} |
536 | \c |
16ea3abe |
537 | \c \cfg{xhtml-leaf-level}{2} |
538 | \c \cfg{xhtml-leaf-contains-contents}{false} |
539 | \c \cfg{xhtml-leaf-smallest-contents}{4} |
540 | \c \cfg{xhtml-contents-depth-0}{2} |
541 | \c \cfg{xhtml-contents-depth-1}{3} |
542 | \c \cfg{xhtml-contents-depth-2}{4} |
543 | \c \cfg{xhtml-contents-depth-3}{5} |
544 | \c \cfg{xhtml-contents-depth-4}{6} |
545 | \c \cfg{xhtml-contents-depth-5}{7} |
546 | \c |
547 | \c \cfg{xhtml-head-end}{} |
548 | \c \cfg{xhtml-body-tag}{<body>} |
549 | \c \cfg{xhtml-body-start}{} |
550 | \c \cfg{xhtml-body-end}{} |
551 | \c \cfg{xhtml-address-start}{} |
552 | \c \cfg{xhtml-address-end}{} |
553 | \c \cfg{xhtml-navigation-attributes}{} |
554 | \c |
555 | \c \cfg{xhtml-versionid}{true} |
556 | \c \cfg{xhtml-suppress-address}{false} |
557 | \c \cfg{xhtml-author}{} |
558 | \c \cfg{xhtml-description}{} |
559 | \c |
560 | \c \cfg{xhtml-chapter-numeric}{false} |
561 | \c \cfg{xhtml-chapter-suffix}{: } |
562 | \c |
563 | \c \cfg{xhtml-section-numeric}{0}{true} |
564 | \c \cfg{xhtml-section-suffix}{0}{ } |
565 | \c |
566 | \c \cfg{xhtml-section-numeric}{1}{true} |
567 | \c \cfg{xhtml-section-suffix}{1}{ } |
568 | \c |
569 | \c ... and so on for all section levels below this ... |
570 | \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii |
571 | |
572 | \H{output-whlp} Windows Help |
573 | |
339cbe09 |
574 | This output format generates data that can be used by the \i{Windows |
0a6347b4 |
575 | Help} program \cw{WINHELP.EXE}. There are two actual files |
576 | generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. |
577 | |
578 | The Windows Help output format supports the following configuration |
579 | directives: |
580 | |
581 | \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}} |
582 | |
583 | \dd Sets the \i{output file name} in which to store the man page. |
584 | This directive is implicitly generated if you provide a file name |
585 | parameter after the command-line option \i\c{--winhelp} (see |
586 | \k{running-options}). |
587 | |
588 | \lcont{ |
589 | |
590 | Your output file name should end with \c{.hlp}; if it doesn't, |
591 | Halibut will append it. Halibut will also generate a contents file |
592 | (ending in \c{.cnt}) alongside the file name you specify. |
593 | |
594 | } |
16ea3abe |
595 | |
339cbe09 |
596 | \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}} |
16ea3abe |
597 | |
339cbe09 |
598 | \dd This directive defines a Windows \i{Help topic} name in the current |
16ea3abe |
599 | section. Topic names can be used by the program invoking |
600 | \cw{WINHELP.EXE} to jump straight to a particular section. So you |
339cbe09 |
601 | can use this for \i{context-sensitive help}. |
16ea3abe |
602 | |
603 | \lcont{ |
604 | |
605 | For example, if you used this directive in a particular section: |
606 | |
607 | \c \cfg{winhelp-topic}{savingfiles} |
608 | |
609 | then a Windows application could invoke Windows Help to jump to that |
610 | particular section in the help file like this: |
611 | |
612 | \c WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND, |
613 | \c (DWORD)"JI(`',`savingfiles')"); |
614 | |
615 | You can use this configuration directive many times, in many |
616 | different subsections of your document, in order to define a lot of |
617 | different help contexts which you can use in this way. |
618 | |
619 | } |
620 | |
0a6347b4 |
621 | The \i{default settings} for the Windows Help output format are: |
622 | |
623 | \c \cfg{winhelp-filename}{output.hlp} |
624 | |
625 | and no \c{\\cfg\{winhelp-topic\}} directives anywhere. |
626 | |
16ea3abe |
627 | \H{output-man} Unix \cw{man} pages |
628 | |
339cbe09 |
629 | This output format generates a Unix \i{\cw{man} page}. That is to say, |
630 | it generates \i\c{nroff} input designed to work with the \c{-mandoc} |
16ea3abe |
631 | macro package. |
632 | |
633 | The available configuration options for this format are as follows: |
634 | |
0a6347b4 |
635 | \dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}} |
636 | |
637 | \dd Sets the \i{output file name} in which to store the man page. |
638 | This directive is implicitly generated if you provide a file name |
639 | parameter after the command-line option \i\c{--man} (see |
640 | \k{running-options}). |
641 | |
339cbe09 |
642 | \dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}} |
16ea3abe |
643 | |
339cbe09 |
644 | \dd This directive is used to generate the initial \i{\c{.TH} |
645 | directive} that appears at the top of a \cw{man} page. It expects to |
646 | be followed by some number of brace pairs containing text, which will |
647 | be used in the \i{headers} and \i{footers} of the formatted output. |
16ea3abe |
648 | |
649 | \lcont{ |
650 | |
651 | A traditional order for the arguments appears to be: |
652 | |
653 | \n The name of the program. |
654 | |
655 | \n The (numeric) manual section. |
656 | |
657 | \n The date that the \cw{man} page was written. |
658 | |
659 | \n The name of any containing suite of which the program is a part. |
660 | |
339cbe09 |
661 | \n The name of the \i{author} of the \cw{man} page. |
16ea3abe |
662 | |
663 | For example, a typical \cw{man} page might contain |
664 | |
fc8e7adb |
665 | \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred |
666 | \c Bloggs} |
16ea3abe |
667 | |
668 | } |
669 | |
339cbe09 |
670 | \dt \I{\cw{\\cfg\{man-headnumbers\}}}\cw{\\cfg\{man-headnumbers\}\{}\e{boolean}\cw{\}} |
16ea3abe |
671 | |
339cbe09 |
672 | \dd If this is set to \c{true}, then \i{section headings} in the |
673 | \cw{man} page will have their \i{section numbers} displayed as usual. If |
16ea3abe |
674 | set to \c{false}, the section numbers will be omitted. (\cw{man} |
675 | pages traditionally have section names such as \q{SYNOPSIS}, |
676 | \q{OPTIONS} and \q{BUGS}, and do not typically number them, so |
677 | \c{false} is the setting which conforms most closely to normal |
678 | \cw{man} style.) |
679 | |
339cbe09 |
680 | \dt \I{\cw{\\cfg\{man-mindepth\}}}\cw{\\cfg\{man-mindepth\}\{}\e{depth}\cw{\}} |
16ea3abe |
681 | |
682 | \dd If this is set to a number greater than 0, then section headings |
683 | \e{higher} than the given depth will not be displayed. If it is set |
684 | to zero, all section headings will be displayed as normal. |
685 | |
686 | \lcont{ |
687 | |
688 | The point of this is so that you can use the same Halibut input file |
689 | to generate a quick-reference \cw{man} page for a program, \e{and} to |
690 | include that \cw{man} page as an appendix in your program's full manual. |
691 | If you are to include the \cw{man} page as an appendix, then the internal |
692 | headings within the page will probably need to be at \c{\\H} or |
693 | \c{\\S} level; therefore, when you format that input file on its own |
694 | to create the \cw{man} page itself, you will need to have defined a |
695 | \c{\\C} and possibly a \c{\\H} heading beforehand, which you don't |
696 | want to see displayed. |
697 | |
698 | Here's an example. You might have a file \c{appendix.but}, which |
699 | simply says |
700 | |
701 | \c \A{manpages} \cw{man} pages for the Foo tool suite |
702 | \c |
703 | \c \cfg{man-mindepth}{2} |
704 | |
705 | Then you have a file \c{make-foo.but}, and probably others like it |
706 | as well, each of which looks something like this: |
707 | |
fc8e7adb |
708 | \c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred |
709 | \c Bloggs} |
16ea3abe |
710 | \c |
711 | \c \H{man-foo} \cw{man} page for \c{make-foo} |
712 | \c |
713 | \c \S{man-foo-name} NAME |
714 | \c |
715 | \c \c{make-foo} - create Foo files for the Foo tool suite |
716 | \c |
717 | \c \S{man-foo-synopsis} SYNOPSIS |
718 | \c |
719 | \c ... and so on ... |
720 | \e iiiiiiiiiiiiiiiii |
721 | |
722 | So when you're generating your main manual, you can include |
723 | \c{appendix.but} followed by \c{make-foo.but} and any other \cw{man} |
724 | pages you have, and your \cw{man} pages will be formatted neatly as |
725 | part of an appendix. Then, in a separate run of Halibut, you can |
726 | just do |
727 | |
728 | \c halibut appendix.but make-foo.but |
729 | |
730 | and this will generate a \cw{man} page \c{output.1}, in which the |
731 | headings \q{\cw{man} pages for the Foo tool suite} and \q{\cw{man} |
732 | page for \c{make-foo}} will not be displayed because of the |
733 | \c{man-mindepth} directive. So the first visible heading in the |
734 | output \cw{man} page will be \q{NAME}, exactly as a user would |
735 | expect. |
736 | |
737 | } |
738 | |
339cbe09 |
739 | The \i{default settings} for the \cw{man} page output format are: |
16ea3abe |
740 | |
0a6347b4 |
741 | \c \cfg{man-filename}{output.1} |
16ea3abe |
742 | \c \cfg{man-identity}{} |
743 | \c \cfg{man-headnumbers}{false} |
744 | \c \cfg{man-mindepth}{0} |
43f61c25 |
745 | |
746 | \H{output-info} GNU \c{info} |
747 | |
748 | This output format generates files which can be used with the \i{GNU |
749 | \c{info}} program. |
750 | |
751 | There are typically multiple output files: a primary file whose name |
752 | usually ends in \c{.info}, and one or more subsidiary files whose |
753 | names have numbers on the end, so that they end in \c{.info-1}, |
754 | \c{.info-2} and so on. Alternatively, this output format can be |
755 | configured to output a single large file containing the whole |
756 | document. |
757 | |
758 | The \c{info} output format supports the following configuration |
759 | directives: |
760 | |
761 | \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}} |
762 | |
763 | \dd Sets the output file name in which to store the \c{info} file. |
764 | This directive is implicitly generated if you provide a file name |
765 | parameter after the command-line option \i\c{--info} (see |
766 | \k{running-options}). |
767 | |
768 | \lcont{ |
769 | |
770 | The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to |
771 | your output file name to produce any subsidiary files required. |
772 | |
773 | Note that \c{info} files refer to their own names internally, so |
774 | these files cannot be \I{renaming \c{info} files}renamed after |
775 | creation and remain useful. |
776 | |
777 | } |
778 | |
779 | \dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}} |
780 | |
781 | \dd Sets the preferred \i{maximum file size} for each subsidiary |
782 | file. As a special case, if you set this to zero, there will be no |
783 | subsidiary files and the whole document will be placed in a single |
784 | self-contained output file. (However, note that this file can still |
785 | not be renamed usefully.) |
786 | |
787 | \lcont{ |
788 | |
789 | The preferred maximum file size is only a guideline. Halibut may be |
790 | forced to exceed it if a single section of the document is larger |
791 | than the maximum size (since individual \c{info} nodes may not be |
792 | split between files). |
793 | |
794 | } |
795 | |
796 | \dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short |
797 | name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}] |
798 | |
799 | \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the |
800 | header of the Info file. This mechanism is used to automatically |
801 | generate the \i{\c{dir} file} at the root of a Unix system's |
802 | \c{info} collection. |
803 | |
804 | \lcont{ |
805 | |
806 | The parameters to this directive are: |
807 | |
808 | \dt \e{section} |
809 | |
810 | \dd Specifies the section of the \c{dir} file in which you want your |
811 | document referenced. For example, \q{Development}, or \q{Games}, or |
812 | \q{Miscellaneous}. |
813 | |
814 | \dt \e{short name} |
815 | |
816 | \dd Specifies a short name for the directory entry, which will |
817 | appear at the start of the menu line. |
818 | |
819 | \dt \e{long name} |
820 | |
821 | \dd Specifies a long name for the directory entry, which will appear |
822 | at the end of the menu line. |
823 | |
824 | \dt \e{keyword} |
825 | |
826 | \dd This parameter is optional. If it is present, then the directory |
827 | entry will cause a jump to a particular subsection of your document, |
828 | rather than starting at the top. The subsection will be the one |
829 | referred to by the given keyword (see \k{input-sections} for details |
830 | about assigning keywords to document sections). |
831 | |
832 | For example, in a document describing many game programs, the |
833 | configuration directive |
834 | |
fc8e7adb |
835 | \c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess |
836 | \c game}{chess} |
43f61c25 |
837 | |
838 | might produce text in the \c{dir} file looking something like this: |
839 | |
840 | \c Games |
841 | \c * Chess: (mygames)Chapter 3. Electronic chess game |
842 | |
843 | if the output file were called \c{mygames.info} and the keyword |
844 | \c{chess} had been used to define Chapter 3 of the document. |
845 | |
846 | } |
0287083a |
847 | |
848 | \H{output-ps} \i{PostScript} |
849 | |
850 | This output format generates a printable manual in PostScript format. |
851 | |
852 | This format is currently very new and is not yet configurable. There |
853 | is only one available configuration option: |
854 | |
855 | \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} |
856 | |
857 | \dd Sets the \i{output file name} in which to store the PostScript |
858 | file. This directive is implicitly generated if you provide a file |
859 | name parameter after the command-line option \i\c{--ps} (see |
860 | \k{running-options}). |
861 | |
862 | The \i{default settings} for the PostScript output format are: |
863 | |
864 | \c \cfg{ps-filename}{output.ps} |
865 | |
866 | \H{output-pdf} \i{PDF} |
867 | |
868 | This output format generates a printable manual in PDF format. This |
869 | should look exactly identical to the PostScript output (see |
870 | \k{output-ps}), but also uses some PDF interactive features to |
871 | provide an outline of all the document's sections and clickable |
872 | cross-references between sections. |
873 | |
874 | This format is currently very new and is not yet configurable. There |
875 | is only one available configuration option: |
876 | |
877 | \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}} |
878 | |
879 | \dd Sets the \i{output file name} in which to store the PDF file. |
880 | This directive is implicitly generated if you provide a file name |
881 | parameter after the command-line option \i\c{--pdf} (see |
882 | \k{running-options}). |
883 | |
884 | The \i{default settings} for the PDF output format are: |
885 | |
886 | \c \cfg{pdf-filename}{output.pdf} |