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