all: Contents.html
Contents.html: $(INPUTS) $(HALIBUT)
- $(HALIBUT) $(INPUTS)
- rm -f index.html
- ln -s Contents.html index.html
- mv output.txt halibut.txt
- rm -f output.hlp output.cnt output.1
+ $(HALIBUT) --text=halibut.txt --html $(INPUTS)
clean:
rm -f *.html *.txt *.hlp *.cnt *.1
\title Halibut User Manual
\cfg{xhtml-leaf-level}{1}
-
\cfg{xhtml-leaf-smallest-contents}{2}
-
\cfg{xhtml-leaf-contains-contents}{true}
-
\cfg{xhtml-body-end}{Comments to <a href='mailto:anakin@pobox.com'>anakin@pobox.com</a>}
+\cfg{xhtml-contents-filename}{index.html}
+\cfg{xhtml-template-filename}{%k.html}
+\cfg{xhtml-template-fragment}{%k}
+
Halibut is a free (MIT-licensed) documentation production system,
able to generate multiple output formats from the same input data.
This document is its user manual.
rights reserved. You may distribute this documentation under the MIT
licence. See \k{licence} for the licence text in full.
-\versionid $Id: blurb.but,v 1.2 2004/03/25 19:16:28 simon Exp $
+\versionid $Id: blurb.but,v 1.3 2004/04/01 17:54:53 simon Exp $
\IM{text width} line length
\IM{text width} length of lines
+\IM{output file name} output file name
+\IM{output file name} file name, output
+
+\IM{\\cfg\{text-filename\}} \c{text-filename} configuration directive
+\IM{\\cfg\{text-filename\}} \cw{\\cfg\{text-filename\}}
+
+\IM{\\cfg\{man-filename\}} \c{man-filename} configuration directive
+\IM{\\cfg\{man-filename\}} \cw{\\cfg\{man-filename\}}
+
+\IM{\\cfg\{winhelp-filename\}} \c{winhelp-filename} configuration directive
+\IM{\\cfg\{winhelp-filename\}} \cw{\\cfg\{winhelp-filename\}}
+
+\IM{\\cfg\{xhtml-contents-filename\}} \c{xhtml-contents-filename} configuration directive
+\IM{\\cfg\{xhtml-contents-filename\}} \cw{\\cfg\{xhtml-contents-filename\}}
+
+\IM{\\cfg\{xhtml-index-filename\}} \c{xhtml-index-filename} configuration directive
+\IM{\\cfg\{xhtml-index-filename\}} \cw{\\cfg\{xhtml-index-filename\}}
+
+\IM{\\cfg\{xhtml-template-filename\}} \c{xhtml-template-filename} configuration directive
+\IM{\\cfg\{xhtml-template-filename\}} \cw{\\cfg\{xhtml-template-filename\}}
+
+\IM{\\cfg\{xhtml-single-filename\}} \c{xhtml-single-filename} configuration directive
+\IM{\\cfg\{xhtml-single-filename\}} \cw{\\cfg\{xhtml-single-filename\}}
+
+\IM{\\cfg\{xhtml-template-fragment\}} \c{xhtml-template-fragment} configuration directive
+\IM{\\cfg\{xhtml-template-fragment\}} \cw{\\cfg\{xhtml-template-fragment\}}
+
\IM{\\cfg\{text-width\}} \c{text-width} configuration directive
\IM{\\cfg\{text-width\}} \cw{\\cfg\{text-width\}}
\IM{renaming sections} sections, renaming
\IM{renaming sections} appendices, renaming
+\IM{command-line options} command-line options
+\IM{command-line options} options, command-line
+
+\IM{--text} \c{--text} command-line option
+\IM{--html} \c{--html} command-line option
+\IM{--xhtml} \c{--xhtml} command-line option
+\IM{--winhelp} \c{--winhelp} command-line option
+\IM{--whlp} \c{--whlp} command-line option
+\IM{--hlp} \c{--hlp} command-line option
+\IM{--man} \c{--man} command-line option
+\IM{-C} \c{-C} command-line option
+\IM{--help} \c{--help} command-line option
+\IM{--version} \c{--version} command-line option
+\IM{--licence} \c{--licence} command-line option
+\IM{--precise} \c{--precise} command-line option
\H{output-text} Plain text
This output format generates the document as a single \i{plain text}
-file, under the name \i\c{output.txt}.
+file.
The output file is currently assumed to be in the \i{ISO 8859-1}
character set. Any Unicode characters representable in this set will
variety of configuration directives. They are listed in the
following subsections.
+\S{output-text-file} Output file name
+
+\dt \I{\cw{\\cfg\{text-filename\}}}\cw{\\cfg\{text-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the text file.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--text} (see
+\k{running-options}).
+
\S{output-text-dimensions} Indentation and line width
This section describes the configuration directives which control
The \i{default settings} for Halibut's plain text output format are:
+\c \cfg{text-filename}{output.txt}
+\c
\c \cfg{text-width}{68}
\c \cfg{text-indent}{7}
\c \cfg{text-indent-code}{2}
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, in which case it will be
-called \c{Manual.html} (but you can rename it easily enough).
+single HTML file instead of multiple ones.
Strictly speaking, the output format is \i{XHTML} 1.0 Transitional,
which is why all of the configuration directives start with the word
\c{xhtml} rather than \c{html}.
+\S{output-html-file} Controlling the output file names
+
+\dt \I{\cw{\\cfg\{xhtml-contents-filename\}}}\cw{\\cfg\{xhtml-contents-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the top-level
+contents page. Since this is the first page a user ought to see when
+beginning to read the document, a good choice in many cases might be
+\c{index.html} (but this is not the default, for historical
+reasons).
+
+\dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the file name in which to store the document's index.
+
+\dt \I{\cw{\\cfg\{xhtml-template-filename\}}}\cw{\\cfg\{xhtml-template-filename\}\{}\e{template}\cw{\}}
+
+\dd Provides a \i{template} to be used when constructing the file
+names of each chapter or section of the document. This template
+should contain at least one \i\e{formatting command}, in the form of
+a per cent sign followed by a letter. (If you need a literal per
+cent sign, you can write \c{%%}.)
+
+\lcont{
+
+The formatting commands used in this template are:
+
+\dt \i\c{%N}
+
+\dd Expands to the visible title of the section, with white space
+removed. So in a chapter declared as \q{\cw{\\C\{fish\} Catching
+Fish}}, this formatting command would expand to
+\q{\cw{CatchingFish}}.
+
+\dt \i\c{%n}
+
+\dd Expands to the type and number of the section, without white
+space. So in chapter 1 this would expand to \q{\cw{Chapter1}}; in
+section A.4.3 it would expand to \q{\cw{SectionA.4.3}}, and so on.
+If the section has no number (an unnumbered chapter created using
+\c{\\U}), this directive falls back to doing the same thing as
+\c{%N}.
+
+\dt \i\c{%b}
+
+\dd Expands to the bare number of the section. So in chapter 1 this
+would expand to \q{\cw{1}}; in section A.4.3 it would expand to
+\q{\cw{A.4.3}}, and so on. If the section has no number (an
+unnumbered chapter created using \c{\\U}), this directive falls back
+to doing the same thing as \c{%N}.
+
+\dt \i\c{%k}
+
+\dd Expands to the internal keyword specified in the section title.
+So in a chapter declared as \q{\cw{\\C\{fish\} Catching Fish}}, this
+formatting command would expand to \q{\cw{fish}}. If the section has
+no keyword (an unnumbered chapter created using \c{\\U}), this
+directive falls back to doing the same thing as \c{%N}.
+
+These formatting directives can also be used in the
+\cw{\\cfg\{xhtml-template-fragment\}} configuration directive (see
+\k{output-html-misc}).
+
+}
+
+\dt \I{\cw{\\cfg\{xhtml-single-filename\}}}\cw{\\cfg\{xhtml-single-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the file name in which to store the entire document, if
+Halibut is configured (using \c{\\cfg\{xhtml-leaf-level\}\{0\}} to
+produce a single self-contained file. Both this directive \e{and}
+\c{\\cfg\{xhtml-leaf-level\}\{0\}} are implicitly generated if you
+provide a file name parameter after the command-line option
+\i\c{--html} (see \k{running-options}).
+
\S{output-html-split} Controlling the splitting into HTML files
By default, the HTML output from Halibut is split into multiple
in a single file. If you do this, Halibut will call that file
\i\c{Manual.html} instead of \i\c{Contents.html}.
+This option is automatically set to zero if you provide a file name
+parameter after the command-line option \i\c{--html} (see
+\k{running-options}), because you have specified a single file name
+and so Halibut assumes you want the whole document to be placed in
+that file.
+
}
\dt \I{\cw{\\cfg\{xhtml-contents-depth\}}}\cw{\\cfg\{xhtml-contents-depth-}\e{level}\cw{\}\{}\e{depth}\cw{\}}
\S{output-html-misc} Miscellaneous options
+\dt \I{\cw{\\cfg\{xhtml-template-fragment\}}}\cw{\\cfg\{xhtml-template-fragment\}\{}\e{template}\cw{\}}
+
+\dd This directive lets you specify a \i{template}, with exactly the
+same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see
+\k{output-html-file}), to be used for the anchor names (\i\cw{A
+NAME="..."}) used to allow URLs to refer to specific sections within
+a particular HTML file. So if you set this to \q{\cw{%k}}, for
+example, then each individual section in your document will be
+addressable by means of a URL ending in a \c{#} followed by your
+internal section keyword.
+
\dt \I{\cw{\\cfg\{xhtml-versionid\}}}\cw{\\cfg\{xhtml-versionid\}\{}\e{boolean}\cw{\}}
\dd If this is set to \c{true}, \i{version ID paragraphs} (defined using
The \i{default settings} for Halibut's HTML output format are:
+\c \cfg{xhtml-contents-filename}{Contents.html}
+\c \cfg{xhtml-index-filename}{IndexPage.html}
+\c \cfg{xhtml-template-filename}{%n.html}
+\c \cfg{xhtml-single-filename}{Manual.html}
+\c \cfg{xhtml-template-fragment}{%b}
+\c
\c \cfg{xhtml-leaf-level}{2}
\c \cfg{xhtml-leaf-contains-contents}{false}
\c \cfg{xhtml-leaf-smallest-contents}{4}
\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 generated,
-called \c{output.hlp} and \c{output.cnt}. (You can rename them both
-with no problems; they don't depend on keeping those filenames. You
-just have to make sure that the two names are related in this way,
-so that \c{.hlp} on the end of one name is replaced by \c{.cnt} on
-the end of the other.)
-
-The Windows Help output format is currently not configurable at all;
-all formatting decisions are fixed. However, there is one
-configuration directive you can use, which is not so much
-\e{configuration} as extra functionality:
+Help} program \cw{WINHELP.EXE}. There are two actual files
+generated, one ending in \c{.hlp} and the other ending in \c{.cnt}.
+
+The Windows Help output format supports the following configuration
+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.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--winhelp} (see
+\k{running-options}).
+
+\lcont{
+
+Your output file name should end with \c{.hlp}; if it doesn't,
+Halibut will append it. Halibut will also generate a contents file
+(ending in \c{.cnt}) alongside the file name you specify.
+
+}
\dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}}
}
+The \i{default settings} for the Windows Help output format are:
+
+\c \cfg{winhelp-filename}{output.hlp}
+
+and no \c{\\cfg\{winhelp-topic\}} directives anywhere.
+
\H{output-man} Unix \cw{man} pages
This output format generates a Unix \i{\cw{man} page}. That is to say,
The available configuration options for this format are as follows:
+\dt \I{\cw{\\cfg\{man-filename\}}}\cw{\\cfg\{man-filename\}\{}\e{filename}\cw{\}}
+
+\dd Sets the \i{output file name} in which to store the man page.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--man} (see
+\k{running-options}).
+
\dt \I{\cw{\\cfg\{man-identity\}}}\cw{\\cfg\{man-identity\}\{}\e{text}\cw{\}\{}\e{text...}\cw{\}}
\dd This directive is used to generate the initial \i{\c{.TH}
The \i{default settings} for the \cw{man} page output format are:
+\c \cfg{man-filename}{output.1}
\c \cfg{man-identity}{}
\c \cfg{man-headnumbers}{false}
\c \cfg{man-mindepth}{0}
\C{running} Running Halibut
-\I{running Halibut}Running Halibut is very simple. You provide a set
-of input files on its \i{command line}, and it produces a set of
-output files.
+\I{running Halibut}In the simplest case, running Halibut is very
+simple. You provide a set of input files on its \i{command line},
+and it produces a set of output files.
\c $ halibut intro.but getting-started.but reference.but index.but
\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
have configured Halibut to generate a single file, it will be called
\c{Manual.html}.
-Unfortunately, in the current version, it is not possible to tell
-Halibut to generate these files under different names; so you will
-need to \I{renaming files}rename them manually after they are
-generated. (Even this won't work for the multiple-file HTML
-document, because there will be lots of internal hyperlinks between
-the various files which use their names.) Neither is it possible to
-tell Halibut not to bother generating some of the output formats, so
-you will need to delete any that you don't want.
-
-I regret this inconvenience; it arose because I was more interested
-in getting the difficult document-formatting code to work than I was
-in sorting out details like this which should be easy. At some point
-I plan to add some command-line options to configure all this.
+\H{running-options} \ii{Command-line options}
+
+Halibut supports command-line options in case you don't want to use
+all of Halibut's \i{output formats}, or you want to configure the
+names of your \i{output files}, or you want to supply additional
+configuration on the command line. The supported options are listed
+here.
+
+Firstly, there are options which indicate which of the output
+formats you want Halibut to generate:
+
+\dt \i\cw{--text}[\cw{=}\e{filename}]
+
+\dd Specifies that you want to generate plain text output. You can
+optionally specify a file name (e.g. \c{--text=myfile.txt}), in
+which case Halibut will change the name of the output file as well.
+
+\dt \i\cw{--html}[\cw{=}\e{filename}]
+
+\dd Specifies that you want to generate HTML output. You can
+optionally specify a file name (e.g. \c{--html=myfile.html}), in
+which case Halibut will change the name of the output file as well.
+Specifying a file name here will also cause the HTML to be output in
+\e{only} one file, instead of the usual behaviour of producing
+multiple files with links between them. If you want to produce
+multiple files and configure their names, you will need to use the
+more complete file name configuration directives given in
+\k{output-html-file} (although you may want to do so on the command
+line, using the \c{-C} option).
+
+\dt \i\cw{--xhtml}[\cw{=}\e{filename}]
+
+\dd Synonym for \c{--html}.
+
+\dt \i\cw{--winhelp}[\cw{=}\e{filename}]
+
+\dd Specifies that you want to generate plain text output. You can
+optionally specify a file name (e.g. \c{--winhelp=myfile.hlp}), in
+which case Halibut will change the name of the output file as well.
+
+\lcont{
+
+Your output file name should end with \c{.hlp}; if it doesn't,
+Halibut will append it. Halibut will also generate a contents file
+(ending in \c{.cnt}) alongside the file name you specify.
+
+}
+
+\dt \i\cw{--whlp}[\cw{=}\e{filename}]
+
+\dd Synonym for \c{--winhelp}.
+
+\dt \i\cw{--hlp}[\cw{=}\e{filename}]
+
+\dd Synonym for \c{--winhelp}.
+
+\dt \i\cw{--man}[\cw{=}\e{filename}]
+
+\dd Specifies that you want to generate plain text output. You can
+optionally specify a file name (e.g. \c{--man=myfile.5}), in which
+case Halibut will change the name of the output file as well.
+
+Also, there is an option which allows you to specify an arbitrary
+\i\c{\\cfg} configuration directive (see \k{input-config}):
+
+\dt \i\cw{-C}\e{config-directive}\cw{:}\e{value}[\cw{:}\e{value}...]
+
+\dd The text following \c{-C} is expected to be a colon-separated
+list of strings. (If you need a literal colon, you can escape it
+with a backslash: \c{\\:}. If you need a literal \e{backslash}, you
+can do the same: \c{\\\\}.) These strings are used as the parts of a
+\c{\\cfg} directive. So, for example, the option
+
+\lcont{
+
+\c -Ctext-section-align:2:leftplus
+
+will translate into the configuration directive
+
+\c \cfg{text-section-align}{2}{leftplus}
+
+}
+
+The options which set the output file names actually work by
+implicitly generating these configuration directives. When you
+specify \c{--text=myfile.txt}, for example, Halibut treats it
+identically to \c{--text -Ctext-filename:myfile.txt}. The Windows
+Help and man page formats work similarly. HTML is slightly
+different, since it also arranges for single-file output if you pass
+a filename to \c{--html}; so \c{--html=myfile.html} is equivalent to
+\c{--html -Cxhtml-single-filename:myfile.html -Cxhtml-leaf-level:0}.
+(See \k{output} for explanations of all these configuration
+directives.)
+
+In addition to these, there are also a few other options:
+
+\dt \i\cw{--help}
+
+\dd Print a brief help message and exit immediately. (Don't confuse
+this with \c{--winhelp}!)
+
+\dt \i\cw{--version}
+
+\dd Print information about Halibut's version number and exit
+immediately.
+
+\dt \i\cw{--licence}
+
+\dd Display Halibut's licence (see also \k{licence}) and exit
+immediately.
+
+\dt \cw{--license}
+
+\dd US English alternative spelling of \c{--licence}.
+
+\dt \i\cw{--precise}
+
+\dd Report column numbers as well as line numbers when reporting
+errors in the Halibut input files.
~mdw / sgt / halibut / commitdiff