diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 6 | ||||
| -rw-r--r-- | doc/chm.but | 19 | ||||
| -rw-r--r-- | doc/index.but | 27 | ||||
| -rw-r--r-- | doc/intro.but | 7 | ||||
| -rw-r--r-- | doc/output.but | 126 | ||||
| -rw-r--r-- | doc/running.but | 29 |
6 files changed, 194 insertions, 20 deletions
diff --git a/doc/Makefile b/doc/Makefile index cfdd943..63299ad 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -20,4 +20,8 @@ install: $(INSTALL) -m 644 halibut.1 $(man1dir)/halibut.1 clean: - rm -f *.html *.txt *.hlp *.cnt *.1 *.info* *.ps *.pdf + rm -f *.html *.txt *.hlp *.cnt *.1 *.info* *.ps *.pdf *.hh* *.chm + +chm: halibut.hhp +halibut.hhp: $(INPUTS) $(HALIBUT) chm.but + $(HALIBUT) --html $(INPUTS) chm.but diff --git a/doc/chm.but b/doc/chm.but new file mode 100644 index 0000000..510baf8 --- /dev/null +++ b/doc/chm.but @@ -0,0 +1,19 @@ +\# File containing the magic HTML configuration directives to create +\# an MS HTML Help project. We put this on the end of the Halibut +\# docs build command line to build the HHP and friends. + +\cfg{html-leaf-level}{infinite} +\cfg{html-leaf-contains-contents}{false} +\cfg{html-suppress-navlinks}{true} +\cfg{html-suppress-address}{true} + +\cfg{html-contents-filename}{index.html} +\cfg{html-template-filename}{%k.html} +\cfg{html-template-fragment}{%k} + +\cfg{html-mshtmlhelp-chm}{halibut.chm} +\cfg{html-mshtmlhelp-project}{halibut.hhp} +\cfg{html-mshtmlhelp-contents}{halibut.hhc} +\cfg{html-mshtmlhelp-index}{halibut.hhk} + +\versionid $Id$ diff --git a/doc/index.but b/doc/index.but index b059b47..b8587c7 100644 --- a/doc/index.but +++ b/doc/index.but @@ -3,6 +3,12 @@ \IM{Windows Help} Windows Help \IM{Windows Help} Help, Windows +\IM{HTML Help} HTML Help +\IM{HTML Help} Windows HTML Help +\IM{HTML Help} MS HTML Help +\IM{HTML Help} Microsoft HTML Help +\IM{HTML Help} \cw{.chm} files + \IM{Help compiler} Help compiler, lack of need for \IM{plain text} plain text @@ -326,6 +332,11 @@ configuration directive \IM{\\cfg\{html-suppress-address\}} \cw{\\cfg\{html-suppress-address\}} +\IM{\\cfg\{html-suppress-navlinks\}} \c{html-suppress-navlinks} +configuration directive +\IM{\\cfg\{html-suppress-navlinks\}} +\cw{\\cfg\{html-suppress-navlinks\}} + \IM{\\cfg\{html-author\}} \c{html-author} configuration directive \IM{\\cfg\{html-author\}} \cw{\\cfg\{html-author\}} @@ -333,6 +344,22 @@ configuration directive directive \IM{\\cfg\{html-description\}} \cw{\\cfg\{html-description\}} +\IM{\\cfg\{html-mshtmlhelp-project\}} \c{html-mshtmlhelp-project} +configuration directive +\IM{\\cfg\{html-mshtmlhelp-project\}} \cw{\\cfg\{html-mshtmlhelp-project\}} + +\IM{\\cfg\{html-mshtmlhelp-chm\}} \c{html-mshtmlhelp-chm} +configuration directive +\IM{\\cfg\{html-mshtmlhelp-chm\}} \cw{\\cfg\{html-mshtmlhelp-chm\}} + +\IM{\\cfg\{html-mshtmlhelp-contents\}} \c{html-mshtmlhelp-contents} +configuration directive +\IM{\\cfg\{html-mshtmlhelp-contents\}} \cw{\\cfg\{html-mshtmlhelp-contents\}} + +\IM{\\cfg\{html-mshtmlhelp-index\}} \c{html-mshtmlhelp-index} +configuration directive +\IM{\\cfg\{html-mshtmlhelp-index\}} \cw{\\cfg\{html-mshtmlhelp-index\}} + \IM{\\cfg\{winhelp-topic\}} \c{winhelp-topic} configuration directive \IM{\\cfg\{winhelp-topic\}} \cw{\\cfg\{winhelp-topic\}} diff --git a/doc/intro.but b/doc/intro.but index 2898d17..ae63dd3 100644 --- a/doc/intro.but +++ b/doc/intro.but @@ -19,8 +19,6 @@ Currently Halibut supports the following output formats: \b HTML. -\b Windows Help. - \b Unix \cw{man} page format. \b GNU \c{info} format. @@ -29,6 +27,11 @@ Currently Halibut supports the following output formats: \b PostScript. +\b Old-style Windows Help (\cw{.HLP}). + +(By setting suitable options, the HTML output can also be made +suitable for feeding to the newer-style Windows HTML Help compiler.) + \H{intro-features} Features supported by Halibut Here's a list of Halibut's notable features. diff --git a/doc/output.but b/doc/output.but index 1145fbe..df4580e 100644 --- a/doc/output.but +++ b/doc/output.but @@ -442,6 +442,10 @@ parameter after the command-line option \i\c{--html} (see and so Halibut assumes you want the whole document to be placed in that file. +You can also specify the special name \c{infinity} (or \c{infinite} +or \c{inf}) if you want to ensure that \e{every} section and +subsection ends up in a separate file no matter how deep you go. + } \dt \I{\cw{\\cfg\{html-contents-depth\}}}\cw{\\cfg\{html-contents-depth\}\{}\e{level}\cw{\}\{}\e{depth}\cw{\}} @@ -765,6 +769,11 @@ visibly in the \i\cw{<ADDRESS>} section at the bottom of each HTML file. If it is set to \c{false}, they will only be included as HTML comments. +\dt \I{\cw{\\cfg\{html-suppress-navlinks\}}}\cw{\\cfg\{html-suppress-navlinks\}\{}\e{boolean}\cw{\}} + +\dd If this is set to \c{true}, the usual \i{navigation links} at the +top of each HTML file will be suppressed. + \dt \I{\cw{\\cfg\{html-suppress-address\}}}\cw{\\cfg\{html-suppress-address\}\{}\e{boolean}\cw{\}} \dd If this is set to \c{true}, the \i\cw{<ADDRESS>} section at the @@ -784,6 +793,108 @@ name="description">} tag in the output HTML files, so that browsers which support this can easily pick out a brief \I{description, of document}description of the document. +\S{output-html-mshtmlhelp} Generating MS Windows \i{HTML Help} + +The HTML files output from Halibut's HTML back end can be used as +input to the MS Windows HTML Help compiler. In order to do this, you +also need some auxiliary files: a project file, and (probably) a +contents file and an index file. Halibut can optionally generate +those as well. + +To enable the generation of MS HTML Help auxiliary files, use the +following configuration directives: + +\dt \I\cw{\\cfg\{html-mshtmlhelp-project\}}\cw{\\cfg\{html-mshtmlhelp-project\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help project file with the +specified name. You will almost certainly want the filename to end +in the extension \c{.hhp} (although Halibut will not enforce this). +If you use this option, you must also use the +\cw{html-mshtmlhelp-chm} option to specify the desired name of the +compiled help file. + +\dt \I\cw{\\cfg\{html-mshtmlhelp-chm\}}\cw{\\cfg\{html-mshtmlhelp-chm\}\{}\e{filename}\cw{\}} + +\dd Specifies the desired name of the compiled HTML Help file. You +will almost certainly want this to have the extension \c{.chm} +(although Halibut will not enforce this). The name you specify here +will be written into the help project file. If you specify this +option, you must also use the \cw{html-mshtmlhelp-project} option to +request a help project file in the first place. + +\dt \I\cw{\\cfg\{html-mshtmlhelp-contents\}}\cw{\\cfg\{html-mshtmlhelp-contents\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help contents file with the +specified name, and refer to it in the help project file. You will +almost certainly want the filename to end in the extension \c{.hhc} +(although Halibut will not enforce this). This option will be +ignored if you have not also specified a help project file. + +\lcont{ + +Creating a contents file like this causes the HTML Help viewer to +display a contents tree in the pane to the left of the main text +window. You can choose to generate an HTML Help project without this +feature, in which case the user will still be able to navigate +around the document by using the ordinary internal links in the HTML +files themselves just as if it were a web page. However, using a +contents file is recommended. + +} + +\dt \I\cw{\\cfg\{html-mshtmlhelp-index\}}\cw{\\cfg\{html-mshtmlhelp-index\}\{}\e{filename}\cw{\}} + +\dd Instructs Halibut to output an HTML Help index file with the +specified name, and refer to it in the help project file. You will +almost certainly want the filename to end in the extension \c{.hhk} +(although Halibut will not enforce this). This option will be +ignored if you have not also specified a help project file. + +\lcont{ + +Specifying this option suppresses the generation of an HTML-based +index file (see \cw{\\cfg\{html-index-filename\}} in +\k{output-html-file}). + +Creating an index file like this causes the HTML Help viewer to +provide a list of index terms in a pane to the left of the main text +window. You can choose to generate an HTML Help project without this +feature, in which case a conventional HTML index will be generated +instead (assuming you have any index terms at all defined) and the +user will still be able to use that. However, using an index file is +recommended. + +Halibut will not output an index file at all, or link to one from +the help project file, if your document contains no index entries. + +} + +If you use the above options, Halibut will output a help project +file which you should be able to feed straight to the command-line +MS HTML Help compiler (\cw{HHC.EXE}), or load into the MS HTML Help +Workshop (\cw{HHW.EXE}). + +You may also wish to alter other HTML configuration options to make +the resulting help file look more like a help file and less like a +web page. A suggested set of additional configuration options for +HTML Help is as follows: + +\b \cw{\\cfg\{html-leaf-level\}\{infinite\}}, because HTML Help +works best with lots of small files (\q{topics}) rather than a few +large ones. In particular, the contents and index mechanisms can +only reference files, not subsections within files. + +\b \cw{\\cfg\{html-leaf-contains-contents\}\{false\}}, to suppress +the contents list above the main text of each bottom-level file. + +\b \cw{\\cfg\{html-suppress-navlinks\}\{true\}}, because HTML Help +has its own navigation facilities and it looks a bit strange to +duplicate them. + +\b \cw{\\cfg\{html-suppress-address\}\{true\}}, because the +\cw{<address>} section makes less sense in a help file than it does +on a web page. + \S{output-html-defaults} Default settings The \i{default settings} for Halibut's HTML output format are: @@ -847,12 +958,19 @@ 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 +Help} program \cw{WINHLP32.EXE}. There are two actual files generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. -Currently, the output is hardcoded to be in the \q{\i{Win1252}} -character set. (If anyone knows how character sets are encoded in -Windows Help, we'd appreciate help.) +Note that as of 2006, MS is discontinuing the Windows Help format in +favour of the newer HTML Help format (\c{.chm} files). Halibut is +not currently able to generate \c{.chm} files directly, but its HTML +back end can write out project files suitable for use as input to +the MS HTML Help compiler. See \k{output-html-mshtmlhelp} for more +information on this. + +Currently, the Windows Help output is hardcoded to be in the +\q{\i{Win1252}} character set. (If anyone knows how character sets +are encoded in Windows Help files, we'd appreciate help.) The Windows Help output format supports the following configuration directives: diff --git a/doc/running.but b/doc/running.but index 884c33f..8574708 100644 --- a/doc/running.but +++ b/doc/running.but @@ -14,18 +14,20 @@ This will generate a large set of \i{output files}: \b \i\c{output.txt} will be a \i{plain text} version of the input document. -\b \i\c{output.hlp} and \i\c{output.cnt} will be a \i{Windows Help} -version of the same thing. (Most of the text is in \c{output.hlp}; -\c{output.cnt} contains additional contents data used by the Windows -help topic selector. If you lose the latter, the former should still -be usable, but it will look less modern.) +\b \i\c{output.hlp} and \i\c{output.cnt} will be an old-style +\i{Windows Help} version of the same thing. (Most of the text is in +\c{output.hlp}; \c{output.cnt} contains additional contents data +used by the Windows help topic selector. If you lose the latter, the +former should still be usable, but it will look less modern.) \lcont{ -Note that Halibut does not require any external software such as a -\i{Help compiler}. It \e{directly} generates Windows Help files, and -therefore it doesn't need to be run on Windows to do so: it can -generate them even when run from an automated script on a Unix -machine. + +Note that to do this Halibut does not require any external software +such as a \i{Help compiler}. It \e{directly} generates old-style +Windows Help files, and therefore it doesn't need to be run on +Windows to do so: it can generate them even when run from an +automated script on a Unix machine. + } \b \c{output.1} will be a Unix \i{\cw{man} page}. @@ -81,9 +83,10 @@ line, using the \c{-C} option). \dt \i\cw{--winhelp}[\cw{=}\e{filename}] -\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. +\dd Specifies that you want to generate old-style 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. \lcont{ |