From 0a6347b45815f2ef02120d42a3b3dbf79d289b1d Mon Sep 17 00:00:00 2001 From: simon Date: Thu, 1 Apr 2004 17:54:54 +0000 Subject: [PATCH] Having done all these command-line options and new \cfg directives, I'd better document them... git-svn-id: svn://svn.tartarus.org/sgt/halibut@4024 cda61777-01e9-0310-a592-d414129be87e --- doc/Makefile | 6 +-- doc/blurb.but | 9 ++-- doc/index.but | 42 +++++++++++++++ doc/output.but | 157 +++++++++++++++++++++++++++++++++++++++++++++++++++----- doc/running.but | 138 +++++++++++++++++++++++++++++++++++++++++++------ 5 files changed, 313 insertions(+), 39 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index e660d41..0e8737a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -7,11 +7,7 @@ HALIBUT = ../build/halibut 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 diff --git a/doc/blurb.but b/doc/blurb.but index b644681..e7f8e4c 100644 --- a/doc/blurb.but +++ b/doc/blurb.but @@ -1,13 +1,14 @@ \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 anakin@pobox.com} +\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. @@ -16,4 +17,4 @@ 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 $ diff --git a/doc/index.but b/doc/index.but index 04ae667..4d5ef5b 100644 --- a/doc/index.but +++ b/doc/index.but @@ -11,6 +11,33 @@ \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\}} @@ -304,3 +331,18 @@ directive \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 diff --git a/doc/output.but b/doc/output.but index 5c70e72..89eca4e 100644 --- a/doc/output.but +++ b/doc/output.but @@ -8,7 +8,7 @@ that format. \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 @@ -19,6 +19,15 @@ The precise formatting of the text file can be controlled by a 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 @@ -187,6 +196,8 @@ in bulletted lists. It can be one character 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} @@ -223,13 +234,85 @@ default, this will be in multiple files, starting with 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 @@ -259,6 +342,12 @@ 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 \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{\}} @@ -395,6 +484,17 @@ particular level, before displaying the section title. \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 @@ -428,6 +528,12 @@ document}description of the document. 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} @@ -466,17 +572,26 @@ 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 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{\}} @@ -503,6 +618,12 @@ different help contexts which you can use in this way. } +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, @@ -511,6 +632,13 @@ macro package. 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} @@ -608,6 +736,7 @@ expect. 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} diff --git a/doc/running.but b/doc/running.but index 5666e30..2e3a2a0 100644 --- a/doc/running.but +++ b/doc/running.but @@ -1,8 +1,8 @@ \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 @@ -35,16 +35,122 @@ the topmost one that users should be directed to initially. If you 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. -- 2.11.0