Add documentation for the info backend.

git-svn-id: svn://svn.tartarus.org/sgt/halibut@4052 cda61777-01e9-0310-a592-d414129be87e

diff --git a/doc/index.but b/doc/index.but
index 75aadba..7b87c13 100644 (file)
--- a/doc/index.but
+++ b/doc/index.but
@@ -20,6 +20,15 @@
 \IM{\\cfg\{man-filename\}} \c{man-filename} configuration directive
 \IM{\\cfg\{man-filename\}} \cw{\\cfg\{man-filename\}}
 
+\IM{\\cfg\{info-filename\}} \c{info-filename} configuration directive
+\IM{\\cfg\{info-filename\}} \cw{\\cfg\{info-filename\}}
+
+\IM{\\cfg\{info-dir-entry\}} \c{info-dir-entry} configuration directive
+\IM{\\cfg\{info-dir-entry\}} \cw{\\cfg\{info-dir-entry\}}
+
+\IM{\\cfg\{info-max-file-size\}} \c{info-max-file-size} configuration directive
+\IM{\\cfg\{info-max-file-size\}} \cw{\\cfg\{info-max-file-size\}}
+
 \IM{\\cfg\{winhelp-filename\}} \c{winhelp-filename} configuration directive
 \IM{\\cfg\{winhelp-filename\}} \cw{\\cfg\{winhelp-filename\}}
 
@@ -357,3 +366,10 @@ directive
 \IM{keyword syntax} chapter keywords, syntax of
 \IM{keyword syntax} heading keywords, syntax of
 \IM{keyword syntax} syntax of keywords
+
+\IM{GNU info} GNU \c{info}
+\IM{GNU info} \c{info}
+
+\IM{INFO-DIR-ENTRY} \cw{INFO-DIR-ENTRY}
+\IM{INFO-DIR-ENTRY} \cw{START-INFO-DIR-ENTRY}
+\IM{INFO-DIR-ENTRY} \cw{END-INFO-DIR-ENTRY}

diff --git a/doc/intro.but b/doc/intro.but
index 5abbf98..1312021 100644 (file)
--- a/doc/intro.but
+++ b/doc/intro.but
@@ -19,10 +19,12 @@ Currently Halibut supports the following output formats:
 
 \b Windows Help.
 
-\b Unix man page format.
+\b Unix \cw{man} page format.
 
-Several other formats have been planned (notably PostScript, PDF and
-Unix \c{info}), but the need for them has not yet been urgent.
+\b GNU \c{info} format.
+
+Several other formats have been planned (notably PostScript and
+PDF), but the need for them has not yet been urgent.
 
 \H{intro-features} Features supported by Halibut
 

diff --git a/doc/output.but b/doc/output.but
index 89eca4e..74f4c2c 100644 (file)
--- a/doc/output.but
+++ b/doc/output.but
@@ -740,3 +740,104 @@ The \i{default settings} for the \cw{man} page output format are:
 \c \cfg{man-identity}{}
 \c \cfg{man-headnumbers}{false}
 \c \cfg{man-mindepth}{0}
+
+\H{output-info} GNU \c{info}
+
+This output format generates files which can be used with the \i{GNU
+\c{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
+names have numbers on the end, so that they end in \c{.info-1},
+\c{.info-2} and so on. Alternatively, this output format can be
+configured to output a single large file containing the whole
+document.
+
+The \c{info} output format supports the following configuration
+directives:
+
+\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.
+This directive is implicitly generated if you provide a file name
+parameter after the command-line option \i\c{--info} (see
+\k{running-options}).
+
+\lcont{
+
+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
+creation and remain useful.
+
+}
+
+\dt \I{\cw{\\cfg\{info-max-file-size\}}}\cw{\\cfg\{info-max-file-size\}\{}\e{bytes}\cw{\}}
+
+\dd Sets the preferred \i{maximum file size} for each subsidiary
+file. As a special case, if you set this to zero, there will be no
+subsidiary files and the whole document will be placed in a single
+self-contained output file. (However, note that this file can still
+not be renamed usefully.)
+
+\lcont{
+
+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
+split between files).
+
+}
+
+\dt \I{\cw{\\cfg\{info-dir-entry\}}}\cw{\\cfg\{info-dir-entry\}\{}\e{section}\cw{\}\{}\e{short
+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.
+
+\lcont{
+
+The parameters to this directive are:
+
+\dt \e{section}
+
+\dd Specifies the section of the \c{dir} file in which you want your
+document referenced. For example, \q{Development}, or \q{Games}, or
+\q{Miscellaneous}.
+
+\dt \e{short name}
+
+\dd Specifies a short name for the directory entry, which will
+appear at the start of the menu line.
+
+\dt \e{long name}
+
+\dd Specifies a long name for the directory entry, which will appear
+at the end of the menu line.
+
+\dt \e{keyword}
+
+\dd This parameter is optional. If it is present, then the directory
+entry will cause a jump to a particular subsection of your document,
+rather than starting at the top. The subsection will be the one
+referred to by the given keyword (see \k{input-sections} for details
+about assigning keywords to document sections).
+
+For example, in a document describing many game programs, the
+configuration directive
+
+\c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess game}{chess}
+
+might produce text in the \c{dir} file looking something like this:
+
+\c Games
+\c * Chess: (mygames)Chapter 3.   Electronic chess game
+
+if the output file were called \c{mygames.info} and the keyword
+\c{chess} had been used to define Chapter 3 of the document.
+
+}

diff --git a/doc/running.but b/doc/running.but
index e79400d..d8c0d4c 100644 (file)
--- a/doc/running.but
+++ b/doc/running.but
@@ -35,6 +35,10 @@ 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}.
 
+\b \c{output.info}, and some additional files \c{output.info-1},
+\c{output.info-2} etc., will be files suitable for use with GNU
+\c{info}.
+
 \H{running-options} \ii{Command-line options}
 
 Halibut supports command-line options in case you don't want to use
@@ -71,7 +75,7 @@ line, using the \c{-C} option).
 
 \dt \i\cw{--winhelp}[\cw{=}\e{filename}]
 
-\dd Specifies that you want to generate plain text output. You can
+\dd Specifies that you want to generate Windows Help 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.
 
@@ -93,9 +97,25 @@ Halibut will append it. Halibut will also generate a contents file
 
 \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.
+\dd Specifies that you want to generate \cw{man} page 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.
+
+\dt \i\cw{--info}[\cw{=}\e{filename}]
+
+\dd Specifies that you want to generate GNU \c{info} output. You can
+optionally specify a file name (e.g. \c{--info=myfile.info}), in
+which case Halibut will change the name of the output file as well.
+
+\lcont{
+
+Unless the \c{info} output format is configured not to (see
+\k{output-info}), Halibut will divide the \c{info} output into many
+small files. The extra files will have numeric suffixes on their
+names; so, for example, \c{output.info} might be accompanied by
+additional files \c{output.info-1}, \c{output.info-2} and so on.
+
+}
 
 If you do not specify any of the above options, Halibut will simply
 produce \e{all} of its output formats.