Previous | Contents | Index | Next
This chapter describes each of Halibut's current output formats. It gives some general information about the format, and also describes all the configuration directives which are specific to that format.
This output format generates the document as a single plain text file.
The output file is currently assumed to be in the ISO 8859-1 character set. Any Unicode characters representable in this set will be output verbatim; any other characters will not be output and their fallback text (if any) will be used instead.
The precise formatting of the text file can be controlled by a variety of configuration directives. They are listed in the following subsections.
\cfg{text-filename}{
filename}
--text
(see section 2.1).This section describes the configuration directives which control the horizontal dimensions of the output text file: how much paragraphs are indented by and how long the lines are.
\cfg{text-width}{
width}
\cfg{text-indent}
; if you specify an indent of 8 and a width of 64, your maximum output line length will be 72.\cfg{text-indent}{
indent}
\cfg{text-indent-code}{
indent}
\cfg{text-list-indent}{
indent}
\cfg{text-listitem-indent}
.\cfg{text-listitem-indent}{
indent}
\cfg{text-list-indent}
.\cfg{text-indent-preamble}{
boolean}
true
, the document preamble (i.e. any paragraphs appearing before the first chapter heading) will be indented to the level specified by \cfg{text-indent}
. If this setting is false
, the document preamble will not be indented at all from the left margin.The directives in this section allow you to configure the appearance of the title, chapter and section headings in your text file.
Several of the directives listed below specify the alignment of a heading. These alignment options have three possible values:
left
leftplus
\cfg{text-indent}
). The section number is placed to the left of that (so that it goes in the margin if there is room).centre
Also, several of the directives below specify how a title should be underlined. The parameter to one of these directives should be either blank ({}
) or a single character. In the latter case, that character will be used to underline the title. So you might want to specify, for example, \text-title-underline{=}
but \text-chapter-underline{-}
.
\cfg{text-title-align}{
alignment}
left
, leftplus
or centre
.\cfg{text-title-underline}{
underline-character}
\cfg{text-chapter-align}{
alignment}
\cfg{text-chapter-underline}{
underline-character}
\cfg{text-chapter-numeric}{
boolean}
true
, then chapter headings will not contain the word "Chapter" (or whatever other word you have defined in its place - see section 3.3.5 and section 3.6); they will just contain the chapter number, followed by the chapter title. If you set this to false
, chapter headings will be prefixed by "Chapter" or equivalent.\cfg{text-chapter-suffix}{
text}
:
", then the chapter title might look something like "Chapter 2: Doing Things".\cfg{text-section-align}{
level}{
alignment}
\H
), 1 means second-level headings (\S
), 2 means the level below that (\S2
), and so on. The alignment parameter is treated just like the other alignment directives listed above.\cfg{text-section-underline}{
level}{
underline-character}
\cfg{text-section-numeric}{
level}{
boolean}
false
), or should be numeric only (if true
).\cfg{text-section-suffix}{
level}{
text}
\cfg{text-versionid}{
boolean}
true
, version ID paragraphs (defined using the \versionid
command - see section 3.3.6) will be included at the bottom of the text file. If it is set to false
, they will be omitted completely.\cfg{text-bullet}{
text}
\cfg{text-bullet}{-}
), or more than one (\cfg{text-bullet}{(*)}
).The default settings for Halibut's plain text output format are:
\cfg{text-filename}{output.txt} \cfg{text-width}{68} \cfg{text-indent}{7} \cfg{text-indent-code}{2} \cfg{text-list-indent}{1} \cfg{text-listitem-indent}{3} \cfg{text-indent-preamble}{false} \cfg{text-title-align}{centre} \cfg{text-title-underline}{=} \cfg{text-chapter-align}{left} \cfg{text-chapter-underline}{-} \cfg{text-chapter-numeric}{false} \cfg{text-chapter-suffix}{: } \cfg{text-section-align}{0}{leftplus} \cfg{text-section-underline}{0}{} \cfg{text-section-numeric}{0}{true} \cfg{text-section-suffix}{0}{ } \cfg{text-section-align}{1}{leftplus} \cfg{text-section-underline}{1}{} \cfg{text-section-numeric}{1}{true} \cfg{text-section-suffix}{1}{ } ... and so on for all section levels below this ...
This output format generates an HTML version of the document. By default, this will be in multiple files, starting with Contents.html
and splitting the document into files by chapter and/or subsection. You can configure precisely how the text is split between HTML files using the configuration commands described in this section. In particular, you can configure Halibut to output one single HTML file instead of multiple ones.
Strictly speaking, the output format is XHTML 1.0 Transitional, which is why all of the configuration directives start with the word xhtml
rather than html
.
\cfg{xhtml-contents-filename}{
filename}
index.html
(but this is not the default, for historical reasons).\cfg{xhtml-index-filename}{
filename}
\cfg{xhtml-template-filename}{
template}
%%
.)
The formatting commands used in this template are:
%N
\C{fish} Catching Fish
", this formatting command would expand to "CatchingFish
".%n
Chapter1
"; in section A.4.3 it would expand to "SectionA.4.3
", and so on. If the section has no number (an unnumbered chapter created using \U
), this directive falls back to doing the same thing as %N
.%b
1
"; in section A.4.3 it would expand to "A.4.3
", and so on. If the section has no number (an unnumbered chapter created using \U
), this directive falls back to doing the same thing as %N
.%k
\C{fish} Catching Fish
", this formatting command would expand to "fish
". If the section has no keyword (an unnumbered chapter created using \U
), this directive falls back to doing the same thing as %N
.These formatting directives can also be used in the \cfg{xhtml-template-fragment}
configuration directive (see section 4.2.5).
\cfg{xhtml-single-filename}{
filename}
\cfg{xhtml-leaf-level}{0}
to produce a single self-contained file. Both this directive and \cfg{xhtml-leaf-level}{0}
are implicitly generated if you provide a file name parameter after the command-line option --html
(see section 2.1).By default, the HTML output from Halibut is split into multiple files. Each file typically contains a single chapter or section and everything below it, unless subsections of that chapter are themselves split off into further files.
Most files also contain a contents section, giving hyperlinks to the sections in the file and/or the sections below it.
The configuration directives listed below allow you to configure the splitting into files, and the details of the contents sections.
\cfg{xhtml-leaf-level}{
depth}
\H
section will have a file, and the chapter files will mostly just contain links to their sub-files.
If you set this option to zero, then the whole document will appear in a single file. If you do this, Halibut will call that file Manual.html
instead of Contents.html
.
This option is automatically set to zero if you provide a file name parameter after the command-line option --html
(see section 2.1), because you have specified a single file name and so Halibut assumes you want the whole document to be placed in that file.
\cfg{xhtml-contents-depth-
level}{
depth}
The level parameter indicates which level of contents section you are dealing with. 0 denotes the main contents section in the topmost file Contents.html
; 1 denotes a contents section in a chapter file; 2 is a contents section in a file containing a \H
heading, and so on. Currently you can't go below level 5 (which corresponds to a \S3
heading).
The depth parameter indicates the maximum depth of heading which will be shown in this contents section. Again, 1 denotes a chapter, 2 is a \H
heading, 3 is a \S
heading, and so on.
So, for example: \cfg{xhtml-contents-depth-1}{3}
instructs Halibut to put contents links in chapter files for all sections down to \S
level, but not to go into any more detail than that.
\cfg{xhtml-leaf-contains-contents}{
boolean}
true
, then each leaf file will contain its own contents section which summarises the text within it.\cfg{xhtml-leaf-smallest-contents}{
number}
The directives in this section allow you to supply pieces of verbatim HTML code, which will be included in various parts of the output files.
\cfg{xhtml-head-end}{
HTML text}
<HEAD>
section of each output HTML file. So this is a good place to put, for example, a link to a CSS stylesheet.\cfg{xhtml-body-tag}{
HTML text}
<BODY>
tag in each output file. So if you wanted to define a background colour, for example, you could write \cfg{xhtml-body-tag}{<body bg="#123456">}
.\cfg{xhtml-body-start}{
HTML text}
<BODY>
section of each output HTML file. So if you intend your HTML files to be part of a web site with a standard house style, and the style needs a header at the top of every page, this is where you can add that header.\cfg{xhtml-body-end}{
HTML text}
<BODY>
section of each output HTML file. So if you intend your HTML files to be part of a web site with a standard house style, and the style needs a footer at the bottom of every page, this is where you can add that footer.\cfg{xhtml-address-start}{
HTML text}
<ADDRESS>
section at the bottom of each output HTML file. This might be a good place to put authors' contact details, for example.\cfg{xhtml-address-end}{
HTML text}
<ADDRESS>
section at the bottom of each output HTML file, after the version IDs (if present).\cfg{xhtml-navigation-attributes}{
HTML attributes}
<P>
tag containing the navigation links at the top of each page ("Previous" / "Contents" / "Next"). So if you wanted the navigation links to have a particular CSS style, you could write \cfg{xhtml-navigation-attributes}{class="foo"}
, and the navigation-links paragraph would then begin with the tag <p class="foo">
.\cfg{xhtml-chapter-numeric}{
boolean}
true
, then chapter headings will not contain the word "Chapter" (or whatever other word you have defined in its place - see section 3.3.5 and section 3.6); they will just contain the chapter number, followed by the chapter title. If you set this to false
, chapter headings will be prefixed by "Chapter" or equivalent.\cfg{xhtml-chapter-suffix}{
text}
:
", then the chapter title might look something like "Chapter 2: Doing Things".\cfg{xhtml-section-numeric}{
boolean}
false
), or should be numeric only (if true
). The level parameter specifies which level of section headings you want to affect: 0 means first-level headings (\H
), 1 means second-level headings (\S
), 2 means the level below that (\S2
), and so on.\cfg{xhtml-section-suffix}{
text}
\cfg{xhtml-template-fragment}{
template}
\cfg{xhtml-template-filename}
(see section 4.2.1), to be used for the anchor names (A NAME="..."
) used to allow URLs to refer to specific sections within a particular HTML file. So if you set this to "%k
", for example, then each individual section in your document will be addressable by means of a URL ending in a #
followed by your internal section keyword.\cfg{xhtml-versionid}{
boolean}
true
, version ID paragraphs (defined using the \versionid
command - see section 3.3.6) will be included visibly in the <ADDRESS>
section at the bottom of each HTML file. If it is set to false
, they will be omitted completely.\cfg{xhtml-suppress-address}{
boolean}
true
, the <ADDRESS>
section at the bottom of each HTML file will be omitted completely. (This will therefore also cause version IDs not to be included.)\cfg{xhtml-author}{
text}
<META name="author">
tag in the output HTML files, so that browsers which support this can automatically identify the author of the document.\cfg{xhtml-description}{
text}
<META name="description">
tag in the output HTML files, so that browsers which support this can easily pick out a brief description of the document.The default settings for Halibut's HTML output format are:
\cfg{xhtml-contents-filename}{Contents.html} \cfg{xhtml-index-filename}{IndexPage.html} \cfg{xhtml-template-filename}{%n.html} \cfg{xhtml-single-filename}{Manual.html} \cfg{xhtml-template-fragment}{%b} \cfg{xhtml-leaf-level}{2} \cfg{xhtml-leaf-contains-contents}{false} \cfg{xhtml-leaf-smallest-contents}{4} \cfg{xhtml-contents-depth-0}{2} \cfg{xhtml-contents-depth-1}{3} \cfg{xhtml-contents-depth-2}{4} \cfg{xhtml-contents-depth-3}{5} \cfg{xhtml-contents-depth-4}{6} \cfg{xhtml-contents-depth-5}{7} \cfg{xhtml-head-end}{} \cfg{xhtml-body-tag}{<body>} \cfg{xhtml-body-start}{} \cfg{xhtml-body-end}{} \cfg{xhtml-address-start}{} \cfg{xhtml-address-end}{} \cfg{xhtml-navigation-attributes}{} \cfg{xhtml-versionid}{true} \cfg{xhtml-suppress-address}{false} \cfg{xhtml-author}{} \cfg{xhtml-description}{} \cfg{xhtml-chapter-numeric}{false} \cfg{xhtml-chapter-suffix}{: } \cfg{xhtml-section-numeric}{0}{true} \cfg{xhtml-section-suffix}{0}{ } \cfg{xhtml-section-numeric}{1}{true} \cfg{xhtml-section-suffix}{1}{ } ... and so on for all section levels below this ...
This output format generates data that can be used by the Windows Help program WINHELP.EXE
. There are two actual files generated, one ending in .hlp
and the other ending in .cnt
.
The Windows Help output format supports the following configuration directives:
\cfg{winhelp-filename}{
filename}
--winhelp
(see section 2.1).
Your output file name should end with .hlp
; if it doesn't, Halibut will append it. Halibut will also generate a contents file (ending in .cnt
) alongside the file name you specify.
\cfg{winhelp-topic}{
topic-name}
WINHELP.EXE
to jump straight to a particular section. So you can use this for context-sensitive help.
For example, if you used this directive in a particular section:
\cfg{winhelp-topic}{savingfiles}
then a Windows application could invoke Windows Help to jump to that particular section in the help file like this:
WinHelp(hwnd, "mydoc.hlp", HELP_COMMAND, (DWORD)"JI(`',`savingfiles')");
You can use this configuration directive many times, in many different subsections of your document, in order to define a lot of different help contexts which you can use in this way.
The default settings for the Windows Help output format are:
\cfg{winhelp-filename}{output.hlp}
and no \cfg{winhelp-topic}
directives anywhere.
man
pagesThis output format generates a Unix man
page. That is to say, it generates nroff
input designed to work with the -mandoc
macro package.
The available configuration options for this format are as follows:
\cfg{man-filename}{
filename}
--man
(see section 2.1).\cfg{man-identity}{
text}{
text...}
.TH
directive that appears at the top of a man
page. It expects to be followed by some number of brace pairs containing text, which will be used in the headers and footers of the formatted output.
A traditional order for the arguments appears to be:
man
page was written.man
page.For example, a typical man
page might contain
\cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs}
\cfg{man-headnumbers}{
boolean}
true
, then section headings in the man
page will have their section numbers displayed as usual. If set to false
, the section numbers will be omitted. (man
pages traditionally have section names such as "SYNOPSIS", "OPTIONS" and "BUGS", and do not typically number them, so false
is the setting which conforms most closely to normal man
style.)\cfg{man-mindepth}{
depth}
The point of this is so that you can use the same Halibut input file to generate a quick-reference man
page for a program, and to include that man
page as an appendix in your program's full manual. If you are to include the man
page as an appendix, then the internal headings within the page will probably need to be at \H
or \S
level; therefore, when you format that input file on its own to create the man
page itself, you will need to have defined a \C
and possibly a \H
heading beforehand, which you don't want to see displayed.
Here's an example. You might have a file appendix.but
, which simply says
\A{manpages} \cw{man} pages for the Foo tool suite \cfg{man-mindepth}{2}
Then you have a file make-foo.but
, and probably others like it as well, each of which looks something like this:
\cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs} \H{man-foo} \cw{man} page for \c{make-foo} \S{man-foo-name} NAME \c{make-foo} - create Foo files for the Foo tool suite \S{man-foo-synopsis} SYNOPSIS ... and so on ...
So when you're generating your main manual, you can include appendix.but
followed by make-foo.but
and any other man
pages you have, and your man
pages will be formatted neatly as part of an appendix. Then, in a separate run of Halibut, you can just do
halibut appendix.but make-foo.but
and this will generate a man
page output.1
, in which the headings "man
pages for the Foo tool suite" and "man
page for make-foo
" will not be displayed because of the man-mindepth
directive. So the first visible heading in the output man
page will be "NAME", exactly as a user would expect.
The default settings for the man
page output format are:
\cfg{man-filename}{output.1} \cfg{man-identity}{} \cfg{man-headnumbers}{false} \cfg{man-mindepth}{0}
Previous | Contents | Index | Next