From: simon Date: Sat, 10 Apr 2004 09:48:28 +0000 (+0000) Subject: Add documentation for the info backend. X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/commitdiff_plain/43f61c25ffd4b1e5403c4ae6d49e6a0a39fd4444 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 --- 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 --- 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 --- 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 --- 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.