X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/blobdiff_plain/cb0b173da1f683d33d0d2329017cd918f7ccbccb..refs/heads/master:/doc/output.but diff --git a/doc/output.but b/doc/output.but index 35613ca..49a6b05 100644 --- a/doc/output.but +++ b/doc/output.but @@ -142,6 +142,14 @@ they will just contain the chapter \e{number}, followed by the chapter title. If you set this to \c{false}, chapter headings will be prefixed by \q{Chapter} or equivalent. +\dt \I{\cw{\\cfg\{text-chapter-shownumber\}}}\cw{\\cfg\{text-chapter-shownumber\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{false}, then chapter headings will \e{only} +contain the chapter title: they will not contain the word +\q{Chapter} (or whatever other word you have defined in its place), +and neither will they contain the chapter number. If set to +\c{false}, this overrides \cw{\\cfg\{text-chapter-numeric\}}. + \dt \I{\cw{\\cfg\{text-chapter-suffix\}}}\cw{\\cfg\{text-chapter-suffix\}\{}\e{text}\cw{\}} \dd This specifies the suffix text to be appended to the chapter @@ -168,6 +176,15 @@ just like the other alignment directives listed above. contain the word \q{Section} or equivalent (if \c{false}), or should be numeric only (if \c{true}). +\dt \I{\cw{\\cfg\{text-section-shownumber\}}}\cw{\\cfg\{text-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{false}, then section headings at the +specified level will \e{only} contain the section title: they will +not contain the word \q{Section} (or whatever other word you have +defined in its place), and neither will they contain the section +number. If set to \c{false}, this overrides +\cw{\\cfg\{text-section-numeric\}}. + \dt \I{\cw{\\cfg\{text-section-suffix\}}}\cw{\\cfg\{text-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} \dd Specifies the \I{suffix text, in section titles}suffix text to @@ -296,16 +313,19 @@ The \i{default settings} for Halibut's plain text output format are: \c \cfg{text-chapter-align}{left} \c \cfg{text-chapter-underline}{\u203e}{-} \c \cfg{text-chapter-numeric}{false} +\c \cfg{text-chapter-shownumber}{true} \c \cfg{text-chapter-suffix}{: } \c \c \cfg{text-section-align}{0}{leftplus} \c \cfg{text-section-underline}{0}{} \c \cfg{text-section-numeric}{0}{true} +\c \cfg{text-section-shownumber}{0}{true} \c \cfg{text-section-suffix}{0}{ } \c \c \cfg{text-section-align}{1}{leftplus} \c \cfg{text-section-underline}{1}{} \c \cfg{text-section-numeric}{1}{true} +\c \cfg{text-section-shownumber}{1}{true} \c \cfg{text-section-suffix}{1}{ } \c \c ... and so on for all section levels below this ... @@ -442,6 +462,10 @@ parameter after the command-line option \i\c{--html} (see and so Halibut assumes you want the whole document to be placed in that file. +You can also specify the special name \c{infinity} (or \c{infinite} +or \c{inf}) if you want to ensure that \e{every} section and +subsection ends up in a separate file no matter how deep you go. + } \dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}} @@ -582,6 +606,14 @@ they will just contain the chapter \e{number}, followed by the chapter title. If you set this to \c{false}, chapter headings will be prefixed by \q{Chapter} or equivalent. +\dt \I{\cw{\\cfg\{html-chapter-shownumber\}}}\cw{\\cfg\{html-chapter-shownumber\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{false}, then chapter headings will \e{only} +contain the chapter title: they will not contain the word +\q{Chapter} (or whatever other word you have defined in its place), +and neither will they contain the chapter number. If set to +\c{false}, this overrides \cw{\\cfg\{html-chapter-numeric\}}. + \dt \I{\cw{\\cfg\{html-chapter-suffix\}}}\cw{\\cfg\{html-chapter-suffix\}\{}\e{text}\cw{\}} \dd This specifies the suffix text to be appended to the chapter @@ -600,6 +632,15 @@ which level of section headings you want to affect: 0 means first-level headings (\c{\\H}), 1 means second-level headings (\c{\\S}), 2 means the level below that (\c{\\S2}), and so on. +\dt \I{\cw{\\cfg\{html-section-shownumber\}}}\cw{\\cfg\{html-section-shownumber\}\{}\e{level}\cw{\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{false}, then section headings at the +specified level will \e{only} contain the section title: they will +not contain the word \q{Section} (or whatever other word you have +defined in its place), and neither will they contain the section +number. If set to \c{false}, this overrides +\cw{\\cfg\{html-section-numeric\}}. + \dt \I{\cw{\\cfg\{html-section-suffix\}}}\cw{\\cfg\{html-section-suffix\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}} \# {level} can be omitted (defaults to 0). Is this intentional? @@ -624,6 +665,16 @@ different language. the first chapter heading), contents, and index respectively, in the navigation bar, contents, and index. +\lcont{ + +(\c{html-contents-text} and \c{html-index-text} override the +cross-format configuration keywords \c{contents} and \c{index} (see +\k{input-config}, if both appear. They are legacy keywords preserved +for backwards compatibility; you should generally use \c{contents} +and \c{index}.) + +} + \dt \I{\cw{\\cfg\{html-title-separator\}}}\cw{\\cfg\{html-title-separator\}\{}\e{text}\cw{\}} \dd If multiple headings are used in a file's \cw{} tag, this @@ -650,8 +701,10 @@ the index. \dt \I{\cw{\\cfg\{html-nav-next-text\}}}\cw{\\cfg\{html-nav-next-text\}\{}\e{text}\cw{\}} -\dd The text used for the \q{previous page} and \q{next page} links on -the navigation bar. +\dt \I{\cw{\\cfg\{html-nav-up-text\}}}\cw{\\cfg\{html-nav-up-text\}\{}\e{text}\cw{\}} + +\dd The text used for the \q{previous page}, \q{next page}, and \q{up} +links on the navigation bar. \dt \I{\cw{\\cfg\{html-nav-separator\}}}\cw{\\cfg\{html-nav-separator\}\{}\e{text}\cw{\}} @@ -694,24 +747,34 @@ directive (see \k{output-text-characters}). \dd Identifies the precise version of HTML that is output. This affects the declaration within the HTML, and also has minor effects on -the body of the HTML so that it is valid for the declare version. The +the body of the HTML so that it is valid for the declared version. The available variants are: \lcont{ -\b \cw{html3.2} +\dt \cw{html3.2} + +\dd W3C HTML 3.2 + +\dt \cw{html4} + +\dd W3C HTML 4.01 Strict -\b \cw{html4} +\dt \cw{iso-html} -\b \cw{iso-html} +\dd ISO/IEC 15445:2000 -\b \cw{xhtml1.0transitional} +\dt \cw{xhtml1.0transitional} -\b \cw{xhtml1.0strict} +\dd W3C XHTML 1.0 Transitional + +\dt \cw{xhtml1.0strict} + +\dd W3C XHTML 1.0 Strict } -\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}} +\dt \I{\cw{\\cfg\{html-template-fragment\}}}\cw{\\cfg\{html-template-fragment\}\{}\e{template}\cw{\}}[\cw{\{}\e{template}\cw{\}\{}...\cw{\}}] \dd This directive lets you specify a \i{template}, with exactly the same syntax used in \cw{\\cfg\{html-template-filename\}} (see @@ -724,9 +787,16 @@ internal section keyword. \lcont{ -Note that no checking is done that the anchor name is valid HTML. So -if you use \cq{%k}, for example, you may need to restrict your use of -keyword names. +If more than one template is specified, anchors are generated in all +the specified formats; Halibut's own cross-references are generated +with the first template. + +Characters that are not permitted in anchor names are stripped. If +there are no valid characters left, or a fragment is non-unique, +Halibut starts inventing fragment names and suffixes as appropriate. + +Note that there are potentially fragment names that are not controlled +by this mechanism, such as index references. } @@ -738,6 +808,34 @@ visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML file. If it is set to \c{false}, they will only be included as HTML comments. +\dt \I{\cw{\\cfg\{html-rellinks\}}}\cw{\\cfg\{html-rellinks\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{true}, machine-readable relational links will +be emitted in each HTML file (\I{\cw{<LINK>} tags}\cw{<LINK +REL="next">} and so on within the \i\cw{<HEAD>} section) +providing links to related files. The same set of links are provided +as in the navigation bar (with which this should not be confused). + +\lcont{ + +Some browsers make use of this semantic information, for instance to +allow easy navigation through related pages, and to prefetch the next +page. (Search engines can also make use of it.) However, many browsers +ignore this markup, so it would be unwise to rely on it for +navigation. + +The use and rendering of this information is entirely up to the +browser; none of the other Halibut options for the navigation bar will +have any effect. + +} + +\dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{true}, the usual \i{navigation links} within +the \e{body} of each HTML file (near the top of the rendered page) will +be suppressed. + \dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}} \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the @@ -757,6 +855,108 @@ name="description">} tag in the output HTML files, so that browsers which support this can easily pick out a brief \I{description, of document}description of the document. +\S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help} + +The HTML files output from Halibut's HTML back end can be used as +input to the MS Windows HTML Help compiler. In order to do this, you +also need some auxiliary files: a project file, and (probably) a +contents file and an index file. Halibut can optionally generate +those as well. + +To enable the generation of MS HTML Help auxiliary files, use the +following configuration directives: + +\dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help project file with the +specified name. You will almost certainly want the filename to end +in the extension \c{.hhp} (although Halibut will not enforce this). +If you use this option, you must also use the +\cw{html-mshtmlhelp-chm} option to specify the desired name of the +compiled help file. + +\dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}} + +\dd Specifies the desired name of the compiled HTML Help file. You +will almost certainly want this to have the extension \c{.chm} +(although Halibut will not enforce this). The name you specify here +will be written into the help project file. If you specify this +option, you must also use the \cw{html-mshtmlhelp-project} option to +request a help project file in the first place. + +\dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help contents file with the +specified name, and refer to it in the help project file. You will +almost certainly want the filename to end in the extension \c{.hhc} +(although Halibut will not enforce this). This option will be +ignored if you have not also specified a help project file. + +\lcont{ + +Creating a contents file like this causes the HTML Help viewer to +display a contents tree in the pane to the left of the main text +window. You can choose to generate an HTML Help project without this +feature, in which case the user will still be able to navigate +around the document by using the ordinary internal links in the HTML +files themselves just as if it were a web page. However, using a +contents file is recommended. + +} + +\dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help index file with the +specified name, and refer to it in the help project file. You will +almost certainly want the filename to end in the extension \c{.hhk} +(although Halibut will not enforce this). This option will be +ignored if you have not also specified a help project file. + +\lcont{ + +Specifying this option suppresses the generation of an HTML-based +index file (see \cw{\\cfg\{html-index-filename\}} in +\k{output-html-file}). + +Creating an index file like this causes the HTML Help viewer to +provide a list of index terms in a pane to the left of the main text +window. You can choose to generate an HTML Help project without this +feature, in which case a conventional HTML index will be generated +instead (assuming you have any index terms at all defined) and the +user will still be able to use that. However, using an index file is +recommended. + +Halibut will not output an index file at all, or link to one from +the help project file, if your document contains no index entries. + +} + +If you use the above options, Halibut will output a help project +file which you should be able to feed straight to the command-line +MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help +Workshop (\cw{HHW.EXE}). + +You may also wish to alter other HTML configuration options to make +the resulting help file look more like a help file and less like a +web page. A suggested set of additional configuration options for +HTML Help is as follows: + +\b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help +works best with lots of small files (\q{topics}) rather than a few +large ones. In particular, the contents and index mechanisms can +only reference files, not subsections within files. + +\b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress +the contents list above the main text of each bottom-level file. + +\b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help +has its own navigation facilities and it looks a bit strange to +duplicate them. + +\b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the +\cw{<ADDRESS>} section makes less sense in a help file than it does +on a web page. + \S{output-html-defaults} Default settings The \i{default settings} for Halibut's HTML output format are: @@ -783,12 +983,15 @@ The \i{default settings} for Halibut's HTML output format are: \c \cfg{html-navigation-attributes}{} \c \c \cfg{html-chapter-numeric}{false} +\c \cfg{html-chapter-shownumber}{true} \c \cfg{html-chapter-suffix}{: } \c \c \cfg{html-section-numeric}{0}{true} +\c \cfg{html-section-shownumber}{0}{true} \c \cfg{html-section-suffix}{0}{ } \c \c \cfg{html-section-numeric}{1}{true} +\c \cfg{html-section-shownumber}{1}{true} \c \cfg{html-section-suffix}{1}{ } \c \c ... and so on for all section levels below this ... @@ -804,6 +1007,7 @@ The \i{default settings} for Halibut's HTML output format are: \c \cfg{html-post-versionid}{]} \c \cfg{html-nav-prev-text}{Previous} \c \cfg{html-nav-next-text}{Next} +\c \cfg{html-nav-up-text}{Up} \c \cfg{html-nav-separator}{ | } \c \c \cfg{html-output-charset}{ASCII} @@ -813,6 +1017,8 @@ The \i{default settings} for Halibut's HTML output format are: \c \cfg{html-version}{html4} \c \cfg{html-template-fragment}{%b} \c \cfg{html-versionid}{true} +\c \cfg{html-rellinks}{true} +\c \cfg{html-suppress-navlinks{false} \c \cfg{html-suppress-address}{false} \c \cfg{html-author}{} \c \cfg{html-description}{} @@ -820,12 +1026,19 @@ The \i{default settings} for Halibut's HTML output format are: \H{output-whlp} Windows Help This output format generates data that can be used by the \i{Windows -Help} program \cw{WINHELP.EXE}. There are two actual files +Help} program \cw{WINHLP32.EXE}. There are two actual files generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. -Currently, the output is hardcoded to be in the \q{\i{Win1252}} -character set. (If anyone knows how character sets are encoded in -Windows Help, we'd appreciate help.) +Note that as of 2006, MS is discontinuing the Windows Help format in +favour of the newer HTML Help format (\c{.chm} files). Halibut is +not currently able to generate \c{.chm} files directly, but its HTML +back end can write out project files suitable for use as input to +the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more +information on this. + +Currently, the Windows Help output is hardcoded to be in the +\q{\i{Win1252}} character set. (If anyone knows how character sets +are encoded in Windows Help files, we'd appreciate help.) The Windows Help output format supports the following configuration directives: @@ -834,7 +1047,7 @@ directives: \dt \I{\cw{\\cfg\{winhelp-filename\}}}\cw{\\cfg\{winhelp-filename\}\{}\e{filename}\cw{\}} -\dd Sets the \i{output file name} in which to store the man page. +\dd Sets the \i{output file name} in which to store the help file. This directive is implicitly generated if you provide a file name parameter after the command-line option \i\c{--winhelp} (see \k{running-options}). @@ -1057,6 +1270,15 @@ sensible to output man pages in that charset. You can specify multiple fallback options. Works exactly like the \cw{\\cfg\{text-bullet\}} directive (see \k{output-text-characters}). +\dt \I{\cw{\\cfg\{man-rule\}}}\cw{\\cfg\{man-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] + +\dd This specifies the text which should be used for drawing +\i{horizontal rules} (generated by \i\c{\\rule}; see +\k{input-rule}) when the manual page is rendered into text. +It should only be one character long, but otherwise +it works like the \cw{\\cfg\{text-rule\}} directive +(see \k{output-text-characters}). + \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{\}}] \dd Specifies the quotation marks to use, overriding any @@ -1077,12 +1299,13 @@ The \i{default settings} for the \cw{man} page output format are: \c \c \cfg{man-charset}{ASCII} \c \cfg{man-bullet}{\u2022}{o} +\c \cfg{man-rule}{\u2500}{-} \c \cfg{man-quotes}{\u2018}{\u2019}{"}{"} -\H{output-info} GNU \c{info} +\H{output-info} GNU Info This output format generates files which can be used with the \i{GNU -\c{info}} program. +Info} program. There are typically multiple output files: a primary file whose name usually ends in \c{.info}, and one or more subsidiary files whose @@ -1091,14 +1314,14 @@ names have numbers on the end, so that they end in \c{.info-1}, configured to output a single large file containing the whole document. -The \c{info} output format supports the following configuration +The Info output format supports the following configuration directives: \S{output-info-file} Controlling the output filenames \dt \I{\cw{\\cfg\{info-filename\}}}\cw{\\cfg\{info-filename\}\{}\e{filename}\cw{\}} -\dd Sets the output file name in which to store the \c{info} file. +\dd Sets the output file name in which to store the Info file. This directive is implicitly generated if you provide a file name parameter after the command-line option \i\c{--info} (see \k{running-options}). @@ -1108,8 +1331,8 @@ parameter after the command-line option \i\c{--info} (see The suffixes \c{-1}, \c{-2}, \c{-3} and so on will be appended to your output file name to produce any subsidiary files required. -Note that \c{info} files refer to their own names internally, so -these files cannot be \I{renaming \c{info} files}renamed after +Note that Info files refer to their own names internally, so +these files cannot be \I{renaming Info files}renamed after creation and remain useful. } @@ -1126,7 +1349,7 @@ not be renamed usefully.) The preferred maximum file size is only a guideline. Halibut may be forced to exceed it if a single section of the document is larger -than the maximum size (since individual \c{info} nodes may not be +than the maximum size (since individual Info nodes may not be split between files). } @@ -1174,14 +1397,27 @@ before displaying the section title. For example, if you set this to \cq{:\_}, then a typical section title might look something like \q{Section 3.1: Something Like This}. -\dt \I{\cw{\\cfg\{info-underline\}}}\cw{\\cfg\{info-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] +\dt \I{\cw{\\cfg\{info-title-underline\}}}\cw{\\cfg\{info-title-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] -\dd Specifies the text to be used to underline section titles. Works -very much like the \cw{\\cfg\{text-chapter-underline\}} directive +\dd Specifies the text to be used to \I{underlining}underline +the overall document title. Works +very much like the \cw{\\cfg\{text-title-underline\}} directive (see \k{output-text-headings}). You can specify more than one option, and Halibut will choose the first one supported by the character set. +\dt \I{\cw{\\cfg\{info-chapter-underline\}}}\cw{\\cfg\{info-chapter-underline\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies how chapter and appendix headings should be underlined. + +\dt \I{\cw{\\cfg\{info-section-underline\}}}\cw{\\cfg\{info-section-underline\}\{}\e{level}\cw{\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies how to underline section headings at a particular level. +The \e{level} parameter specifies which level of section +headings you want to affect: 0 means first-level headings (\c{\\H}), +1 means second-level headings (\c{\\S}), 2 means the level below +that (\c{\\S2}), and so on. + \S{output-info-characters} Controlling the characters used \dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}} @@ -1236,7 +1472,7 @@ name}\cw{\}\{}\e{long name}\cw{\}}[\cw{\{}\e{keyword}\cw{\}}] \dd Constructs an \i\cw{INFO-DIR-ENTRY} section and places it in the header of the Info file. This mechanism is used to automatically generate the \i{\c{dir} file} at the root of a Unix system's -\c{info} collection. +Info collection. \lcont{ @@ -1284,7 +1520,7 @@ if the output file were called \c{mygames.info} and the keyword \S{output-info-defaults} Default settings -The \i{default settings} for the \c{info} output format are: +The \i{default settings} for the Info output format are: \c \cfg{info-filename}{output.info} \c \cfg{info-max-file-size}{65536} @@ -1296,7 +1532,13 @@ The \i{default settings} for the \c{info} output format are: \c \cfg{info-listitem-indent}{3} \c \c \cfg{info-section-suffix}{: } -\c \cfg{info-underline}{\u203e}{-} +\c \cfg{info-title-underline}{*} +\c \cfg{info-chapter-underline}{=} +\c \cfg{info-section-underline}{0}{-} +\c \cfg{info-section-underline}{1}{.} +\c \cfg{info-section-underline}{2}{.} +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii \c \c \cfg{info-charset}{ASCII} \c \cfg{info-bullet}{\u2022}{-} @@ -1310,31 +1552,13 @@ and no \cw{\\cfg\{info-dir-entry\}} directives. \H{output-paper} Paper formats -These output formats (currently PostScript and PDF) generate printable +These output formats (currently PDF and PostScript) generate printable manuals. As such, they share a number of configuration directives. -\S{output-ps} \i{PostScript} - -This output format generates a printable manual in PostScript format. - -There is one configuration option specific to PostScript: - -\dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} - -\dd Sets the \i{output file name} in which to store the PostScript -file. This directive is implicitly generated if you provide a file -name parameter after the command-line option \i\c{--ps} (see -\k{running-options}). - -The \i{default settings} for the PostScript output format are: - -\c \cfg{ps-filename}{output.ps} - \S{output-pdf} \i{PDF} -This output format generates a printable manual in PDF format. This -should look exactly identical to the PostScript output (see -\k{output-ps}), but also uses some PDF interactive features to +This output format generates a printable manual in PDF format. In +addition, it uses some PDF interactive features to provide an outline of all the document's sections and clickable cross-references between sections. @@ -1351,6 +1575,26 @@ The \i{default settings} for the PDF output format are: \c \cfg{pdf-filename}{output.pdf} +\S{output-ps} \i{PostScript} + +This output format generates a printable manual in PostScript format. +This should look exactly identical to the PDF output (see +\k{output-ps}), and uses \i\c{pdfmark} to arrange that if converted +to PDF it will contain the same interactive features. + +There is one configuration option specific to PostScript: + +\dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} + +\dd Sets the \i{output file name} in which to store the PostScript +file. This directive is implicitly generated if you provide a file +name parameter after the command-line option \i\c{--ps} (see +\k{running-options}). + +The \i{default settings} for the PostScript output format are: + +\c \cfg{ps-filename}{output.ps} + \S{output-paper-dimensions} Configuring layout and \i{measurements} All measurements are in PostScript \i{points} (72 points to the inch). @@ -1403,7 +1647,7 @@ vertical space between paragraphs does \e{not} include \dd Specifies the indentation of the bullet or number in a \I{bulletted list, indentation}bulletted or \I{numbered list, -indentation}numbers \I{list, indentation}list, similarly to +indentation}numbered \I{list, indentation}list, similarly to \cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}). \dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}} @@ -1443,13 +1687,19 @@ of section numbers (which are in the left margin). \S2{output-paper-index} Contents and index -\dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}} +\dt \I{\cw{\\cfg\{paper-contents-indent-step\}}}\cw{\\cfg\{paper-contents-indent-step\}\{}\e{points}\cw{\}} + +\dd Specifies by how much to indent each entry in the table of +contents per level of subdivision in the document. (In other words, +chapter titles appear at the left of the table of contents, headings +within the chapter are indented by the amount configured here, +subheadings by twice that, and so on.) \dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}} -\# FIXME: I do not know what dees one does. (I couldn't get either of -them to do anything obvious, although the source indicates they should -do something.) +\dd Specifies the amount of space on the right of the table of +contents which should be reserved for page numbers only. Headings in +the table of contents which extend into this space will be wrapped. \dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}} @@ -1480,18 +1730,87 @@ columns. entry and its page number. If the gap is smaller, the page number is moved to the next line. -\S2{output-paper-fonts} Fonts +\S2{output-paper-fonts} \ii{Fonts} + +The directives in this section control which fonts Halibut uses for +various kinds of text. Directives for setting the font normally take +three font names, the first of which is used for normal text, the +second for emphasised text, and the third for code. Any fonts which +aren't specified are left unchanged. + +Halibut intrinsically knows about some fonts, and these fonts are also +built into all PDF and most PostScript implementations. +These fonts can be used without further formality. Halibut can also use +other fonts, and can \I{embedding fonts}embed them it its PDF and +PostScript output. These other fonts are supplied to Halibut by +simply adding them to the list of input files on its command line. + +To use a \i{Type 1 font} Halibut needs both the font file itself, +in either hexadecimal (\I{PFA files}PFA) or IBM PC (\I{PFB files}PFB) +format, and an \i{Adobe Font Metrics} (\I{AFM files}AFM) file. The AFM +file must be specified first on the command line. If Halibut gets an +AFM file without a corresponding Type 1 font file, the PostScript and +PDF output files will still use that font, but they won't contain it. + +Using a \i{TrueType font} is rather simpler, and simply requires you to +pass the font file to Halibut. Halibut does place a few restrictions on +TrueType fonts, notably that they must include a \i{Unicode} mapping +table and a PostScript name. + +Fonts are specified using their PostScript names. Running Halibut with +the \i\cw{\-\-list-fonts} option causes it to display the PostScript +names of all the fonts it intrinsically knows about, along with any +fonts the were supplied as input files. + +\ii{Font sizes} are specified in PostScript \i{points} (72 to the inch). + +\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{\}}]] + +\dd Specifies the fonts to use for text in the document title. + +\dt \I{\cw{\\cfg\{paper-title-font-size\}}}\cw{\\cfg\{paper-title-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the \i{font size} of the document title. + +\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{\}}]] + +\dd Specifies the fonts to use for text in chapter titles. + +\dt \I{\cw{\\cfg\{paper-chapter-font-size\}}}\cw{\\cfg\{paper-chapter-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the \i{font size} of chapter titles. + +\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{\}}]] + +\dd Specifies the fonts to use for text in section headings at the \e{level} +specified. + +\dt \I{\cw{\\cfg\{paper-section-font-size\}}}\cw{\\cfg\{paper-section-font-size\}\{}\e{level}\cw{\}\{}\e{points}\cw{\}} + +\dd Specifies the \i{font size} of section headings at the \e{level} +specified. + +\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{\}}]] + +\dd Specifies the fonts to use for text in the body text. \dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}} -\dd Specifies the font size of body text. +\dd Specifies the \i{font size} of body text. + +\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{\}}]] + +\dd Specifies the fonts to use for text in code paragraphs. The +\e{bold-font} is used for bold text, the \e{italic-font} for +emphasised text, and the \e{normal-font} for normal code. -\# FIXME: actually, this doesn't appear to do anything at all - most -font sizes are still hardcoded. +\dt \I{\cw{\\cfg\{paper-code-font-size\}}}\cw{\\cfg\{paper-code-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the \i{font size} of text in code paragraphs. \dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}} -\dd Specifies the font size to use for page numbers. +\dd Specifies the font size to use for \i{page numbers}. \S2{output-paper-misc} Miscellaneous @@ -1523,7 +1842,7 @@ The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e., \i{A4 paper}. \c \cfg{paper-page-width}{595} -\c \cfg{paper-page-height}{841} +\c \cfg{paper-page-height}{842} \c \c \cfg{paper-left-margin}{72} \c \cfg{paper-top-margin}{72} @@ -1542,7 +1861,7 @@ The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e., \c \cfg{paper-chapter-underline-depth}{14} \c \cfg{paper-sect-num-left-space}{12} \c -\c \cfg{paper-contents-index-step}{24} +\c \cfg{paper-contents-indent-step}{24} \c \cfg{paper-contents-margin}{84} \c \cfg{paper-leader-separation}{12} \c \cfg{paper-footer-distance}{32} @@ -1550,7 +1869,28 @@ The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e., \c \cfg{paper-index-gutter}{36} \c \cfg{paper-index-minsep}{18} \c +\c \cfg{paper-base-fonts}{Times-Roman}{Times-Italic}{Courier} \c \cfg{paper-base-font-size}{12} +\c \cfg{paper-code-fonts}{Courier-Bold}{Courier-Oblique}{Courier} +\c \cfg{paper-code-font-size}{12} +\c \cfg{paper-title-fonts}{Helvetica-Bold} +\c {Helvetica-BoldOblique}{Courier-Bold} +\c \cfg{paper-title-font-size}{24} +\c \cfg{paper-chapter-fonts}{Helvetica-Bold} +\c {Helvetica-BoldOblique}{Courier-Bold} +\c \cfg{paper-chapter-font-size}{20} +\c \cfg{paper-section-fonts}{0}{Helvetica-Bold} +\c {Helvetica-BoldOblique}{Courier-Bold} +\c \cfg{paper-section-font-size}{0}{16} +\c \cfg{paper-section-fonts}{1}{Helvetica-Bold} +\c {Helvetica-BoldOblique}{Courier-Bold} +\c \cfg{paper-section-font-size}{1}{14} +\c \cfg{paper-section-fonts}{2}{Helvetica-Bold} +\c {Helvetica-BoldOblique}{Courier-Bold} +\c \cfg{paper-section-font-size}{2}{13} +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c \c \cfg{paper-pagenum-font-size}{12} \c \c \cfg{paper-rule-thickness}{1}