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