diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 8 | ||||
| -rw-r--r-- | doc/chm.but | 17 | ||||
| -rw-r--r-- | doc/intro.but | 5 | ||||
| -rw-r--r-- | doc/manpage.but | 18 | ||||
| -rw-r--r-- | doc/output.but | 291 | ||||
| -rw-r--r-- | doc/running.but | 24 |
6 files changed, 236 insertions, 127 deletions
diff --git a/doc/Makefile b/doc/Makefile index 81a1fd8..e0cc27a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,7 +11,7 @@ all: index.html halibut.1 index.html: $(INPUTS) $(HALIBUT) $(HALIBUT) --text=halibut.txt --html --info=halibut.info \ - --ps=halibut.ps --pdf=halibut.pdf $(INPUTS) + --ps=halibut.ps --pdf=halibut.pdf --chm=halibut.chm $(INPUTS) halibut.1: manpage.but $(HALIBUT) --man=halibut.1 manpage.but @@ -21,8 +21,4 @@ install: $(INSTALL) -m 644 halibut.1 $(man1dir)/halibut.1 clean: - 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 + rm -f *.html *.txt *.hlp *.cnt *.1 *.info* *.ps *.pdf *.chm diff --git a/doc/chm.but b/doc/chm.but deleted file mode 100644 index ef21ecc..0000000 --- a/doc/chm.but +++ /dev/null @@ -1,17 +0,0 @@ -\# 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} diff --git a/doc/intro.but b/doc/intro.but index 2e5ada1..ce1668c 100644 --- a/doc/intro.but +++ b/doc/intro.but @@ -25,10 +25,9 @@ Currently Halibut supports the following output formats: \b PostScript. -\b Old-style Windows Help (\cw{.HLP}). +\b Windows HTML Help (\cw{.CHM}). -(By setting suitable options, the HTML output can also be made -suitable for feeding to the newer-style Windows HTML Help compiler.) +\b Old-style Windows Help (\cw{.HLP}). \H{intro-features} Features supported by Halibut diff --git a/doc/manpage.but b/doc/manpage.but index 56048f6..a13b195 100644 --- a/doc/manpage.but +++ b/doc/manpage.but @@ -43,13 +43,21 @@ produced as output; this, and the file names, will be as specified in the input files, or given a set of default names starting with \c{Contents.html} if none is specified at all. +\dt \cw{--chm}[\cw{=}\e{filename}] + +\dd Makes Halibut generate an output file in Windows HTML Help +format. If the optional \e{filename} parameter is supplied, the output +help file will be given that name. Otherwise, the name of the output +help file will be as specified in the input files, or \c{output.chm} +if none is specified at all. + \dt \cw{--winhelp}[\cw{=}\e{filename}] -\dd Makes Halibut generate an output file in Windows Help format. If -the optional \e{filename} parameter is supplied, the output help -file will be given that name. Otherwise, the name of the output help -file will be as specified in the input files, or \c{output.hlp} if -none is specified at all. +\dd Makes Halibut generate an output file in old-style Windows Help +format. If the optional \e{filename} parameter is supplied, the output +help file will be given that name. Otherwise, the name of the output +help file will be as specified in the input files, or \c{output.hlp} +if none is specified at all. \lcont{ The output help file must have a name ending in \c{.hlp}; if it does diff --git a/doc/output.but b/doc/output.but index 9309b82..ccb99df 100644 --- a/doc/output.but +++ b/doc/output.but @@ -858,13 +858,202 @@ 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} +\S{output-html-defaults} Default settings + +The \i{default settings} for Halibut's HTML output format are: + +\c \cfg{html-contents-filename}{Contents.html} +\c \cfg{html-index-filename}{IndexPage.html} +\c \cfg{html-template-filename}{%n.html} +\c \cfg{html-single-filename}{Manual.html} +\c +\c \cfg{html-leaf-level}{2} +\c \cfg{html-leaf-contains-contents}{false} +\c \cfg{html-leaf-smallest-contents}{4} +\c \cfg{html-contents-depth}{0}{2} +\c \cfg{html-contents-depth}{1}{3} +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{html-head-end}{} +\c \cfg{html-body-tag}{<body>} +\c \cfg{html-body-start}{} +\c \cfg{html-body-end}{} +\c \cfg{html-address-start}{} +\c \cfg{html-address-end}{} +\c \cfg{html-navigation-attributes}{} +\c +\c \cfg{html-chapter-numeric}{false} +\c \cfg{html-chapter-shownumber}{true} +\c \cfg{html-chapter-suffix}{: } +\c +\c \cfg{html-section-numeric}{0}{true} +\c \cfg{html-section-shownumber}{0}{true} +\c \cfg{html-section-suffix}{0}{ } +\c +\c \cfg{html-section-numeric}{1}{true} +\c \cfg{html-section-shownumber}{1}{true} +\c \cfg{html-section-suffix}{1}{ } +\c +\c ... and so on for all section levels below this ... +\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{html-preamble-text}{Preamble} +\c \cfg{html-contents-text}{Contents} +\c \cfg{html-index-text}{Index} +\c \cfg{html-title-separator}{ - } +\c \cfg{html-index-main-separator}{: } +\c \cfg{html-index-multiple-separator}{, } +\c \cfg{html-pre-versionid}{[} +\c \cfg{html-post-versionid}{]} +\c \cfg{html-nav-prev-text}{Previous} +\c \cfg{html-nav-next-text}{Next} +\c \cfg{html-nav-up-text}{Up} +\c \cfg{html-nav-separator}{ | } +\c +\c \cfg{html-output-charset}{ASCII} +\c \cfg{html-restrict-charset}{UTF-8} +\c \cfg{html-quotes}{\u2018}{\u2019}{"}{"} +\c +\c \cfg{html-version}{html4} +\c \cfg{html-template-fragment}{%b} +\c \cfg{html-versionid}{true} +\c \cfg{html-rellinks}{true} +\c \cfg{html-suppress-navlinks{false} +\c \cfg{html-suppress-address}{false} +\c \cfg{html-author}{} +\c \cfg{html-description}{} + +\H{output-chm} Windows \i{HTML Help} + +This output format generates a \c{.chm} file suitable for use with the +Windows HTML Help system. + +Older versions of Halibut could only generate HTML Help by writing out +a set of source files acceptable to the MS help compiler. Nowadays +Halibut can generate CHM directly, so that's no longer necessary. +However, the legacy method is still available if you need it; see +\k{output-html-mshtmlhelp} for details. + +\S{output-chm-file} Output file name + +\dt \I{\cw{\\cfg\{chm-filename\}}}\cw{\\cfg\{chm-filename\}\{}\e{filename}\cw{\}} + +\dd Sets the \i{output file name} in which to store the HTML Help +file. This directive is implicitly generated if you provide a file +name parameter after the command-line option \i\c{--chm} (see +\k{running-options}). + +\S{output-chm-mostconfig} Configuration shared with the HTML back end + +As the name suggests, an HTML Help file is mostly a compressed +container for HTML files. So the CHM back end shares a great deal of +its code with the HTML back end, and as a result, it supports the same +range of format configuration options. + +(One exception to this general rule is that the configuration options +relating to generating \e{HTML Help compiler input} are not supported +in CHM mode, because they wouldn't make any sense! The +\cw{html-mshtmlhelp-*} options described in \k{output-html-mshtmlhelp} +have no analogue starting \cw{chm-}.) + +However, because HTML and CHM are used in different ways, you may need +to configure the two back ends differently. So in CHM mode, Halibut +supports all the same configuration directives described in +\k{output-html}, but with their names changed so that they begin with +\cq{chm-} in place of \cq{html-}. This lets you maintain two sets of +configuration independently; for example, you could specify +\c{\\cfg\{html-chapter-numeric\}\{true\}} and +\c{\\cfg\{chm-chapter-numeric\}\{false\}} in the same source file, and +then when you ran Halibut with both the \c{--html} and \c{--chm} +options, it would produce purely numeric chapter titles in the HTML +output but not in the CHM file. + +If you do decide to apply a piece of configuration across both these +back ends, you can prefix it with \cq{htmlall-} instead of \cq{html-} +or \cq{chm-}. For example, +\c{\\cfg\{htmlall-chapter-numeric\}\{true\}} will enable purely +numeric chapter titles in \e{both} the HTML and CHM output. + +\S{output-chm-extra} Including extra files in the CHM + +CHM files are mostly a container for HTML, and the HTML files inside +them are allowed to cross-refer to all the usual other kinds of file +that HTML might refer to, such as images, stylesheets and even +Javascript. If you want to make use of this capability, you need to +tell Halibut what extra files it needs to incorporate into the CHM +container. + +\dt \I{\cw{\\cfg\{chm-extra-file\}}}\cw{\\cfg\{chm-extra-file\}\{}\e{filename}\cw{\}} + +\dt \I{\cw{\\cfg\{chm-extra-file\}}}\cw{\\cfg\{chm-extra-file\}\{}\e{filename}\cw{\}\{}\e{name inside CHM}\cw{\}} + +\dd Tells Halibut to read an additional input file from \e{filename} +and incorporate it into the CHM. + +\lcont{ + +In the first form of the directive, the file will be given the same +name within the CHM's internal namespace (i.e. for the purposes of +linking to it from HTML files) as Halibut used to load it from disk. +If you need to include the file with a different internal name, you +can use the second form of the directive, which separately specifies +the name under which Halibut should look for the input file and the +name it should give it inside the CHM. + +You can specify this directive multiple times, to include more than +one file. + +} + +\S{output-chm-internalnames} Renaming the CHM internal support files + +As well as ordinary HTML, there are also two special files inside a +CHM, containing the table of contents and the index. Halibut generates +these automatically, and you normally don't have to worry about them. +However, it is \e{just} possible (though very unlikely!) that you +might find they conflict with the name of some file you wanted to +include in the CHM yourself, and hence, Halibut provides configuration +options to change them if you need to. + +\dt \I{\cw{\\cfg\{chm-contents-name\}}}\cw{\\cfg\{chm-contents-name\}\{}\e{filename}\cw{\}} + +\dd Controls the name of the internal contents file in the CHM. + +\dt \I{\cw{\\cfg\{chm-index-name\}}}\cw{\\cfg\{chm-index-name\}\{}\e{filename}\cw{\}} + +\dd Controls the name of the internal index file in the CHM. + +\S{output-chm-defaults} Default settings + +The \i{default settings} for Halibut's CHM output format are mostly +the same as for the standard HTML output. However, a few defaults are +changed to be more in line with the way CHM wants to do things. + +\c \cfg{chm-filename}{output.chm} +\c \cfg{chm-contents-name}{contents.hhc} +\c \cfg{chm-index-name}{index.hhk} +\c \cfg{chm-leaf-level}{infinite} +\c \cfg{chm-suppress-navlinks{true} +\c \cfg{chm-suppress-address}{true} -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. +\S{output-html-mshtmlhelp} Generating input to the MS Windows \i{HTML +Help compiler} + +Before Halibut gained the ability to write out CHM files directly, it +used a more cumbersome system in which you could run it in HTML mode +and enable some extra options that would write out supporting files +needed by the official Windows HTML Help compiler, so that you could +still generate a CHM file from your Halibut source in multiple build +steps. + +This legacy system for HTML Help generation is still supported, partly +to avoid backwards-compatibility breakage for anyone already using it, +and also because it permits more flexibility in the resulting CHM +files: Halibut's own CHM file generation makes some fixed decisions +about window layout and styling, whereas if you use the official help +compiler you can start from Halibut's default project file and make +whatever manual changes you like to that sort of thing. To enable the generation of MS HTML Help auxiliary files, use the following configuration directives: @@ -940,18 +1129,16 @@ 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: +the resulting help file look more like a help file and less like a web +page. If you use Halibut's direct CHM output, this is done for you +automatically (see \k{output-chm-defaults}); but if you're using the +HTML output mode then I recommend the following changes. \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. @@ -960,83 +1147,15 @@ duplicate them. \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: - -\c \cfg{html-contents-filename}{Contents.html} -\c \cfg{html-index-filename}{IndexPage.html} -\c \cfg{html-template-filename}{%n.html} -\c \cfg{html-single-filename}{Manual.html} -\c -\c \cfg{html-leaf-level}{2} -\c \cfg{html-leaf-contains-contents}{false} -\c \cfg{html-leaf-smallest-contents}{4} -\c \cfg{html-contents-depth}{0}{2} -\c \cfg{html-contents-depth}{1}{3} -\c ... and so on for all section levels below this ... -\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii -\c -\c \cfg{html-head-end}{} -\c \cfg{html-body-tag}{<body>} -\c \cfg{html-body-start}{} -\c \cfg{html-body-end}{} -\c \cfg{html-address-start}{} -\c \cfg{html-address-end}{} -\c \cfg{html-navigation-attributes}{} -\c -\c \cfg{html-chapter-numeric}{false} -\c \cfg{html-chapter-shownumber}{true} -\c \cfg{html-chapter-suffix}{: } -\c -\c \cfg{html-section-numeric}{0}{true} -\c \cfg{html-section-shownumber}{0}{true} -\c \cfg{html-section-suffix}{0}{ } -\c -\c \cfg{html-section-numeric}{1}{true} -\c \cfg{html-section-shownumber}{1}{true} -\c \cfg{html-section-suffix}{1}{ } -\c -\c ... and so on for all section levels below this ... -\e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii -\c -\c \cfg{html-preamble-text}{Preamble} -\c \cfg{html-contents-text}{Contents} -\c \cfg{html-index-text}{Index} -\c \cfg{html-title-separator}{ - } -\c \cfg{html-index-main-separator}{: } -\c \cfg{html-index-multiple-separator}{, } -\c \cfg{html-pre-versionid}{[} -\c \cfg{html-post-versionid}{]} -\c \cfg{html-nav-prev-text}{Previous} -\c \cfg{html-nav-next-text}{Next} -\c \cfg{html-nav-up-text}{Up} -\c \cfg{html-nav-separator}{ | } -\c -\c \cfg{html-output-charset}{ASCII} -\c \cfg{html-restrict-charset}{UTF-8} -\c \cfg{html-quotes}{\u2018}{\u2019}{"}{"} -\c -\c \cfg{html-version}{html4} -\c \cfg{html-template-fragment}{%b} -\c \cfg{html-versionid}{true} -\c \cfg{html-rellinks}{true} -\c \cfg{html-suppress-navlinks{false} -\c \cfg{html-suppress-address}{false} -\c \cfg{html-author}{} -\c \cfg{html-description}{} - -\H{output-whlp} Windows Help +\H{output-whlp} Legacy Windows Help -This output format generates data that can be used by the \i{Windows -Help} program \cw{WINHLP32.EXE}. There are two actual files +This output format generates data that can be used by the legacy +\i{Windows Help} program \cw{WINHLP32.EXE}. There are two actual files generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. -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 +This legacy Windows Help format was discontinued in 2006 in favour of +HTML Help, which Halibut can also generate. You probably want to use +that instead for any new project. See \k{output-chm} for more information on this. Currently, the Windows Help output is hardcoded to be in the diff --git a/doc/running.but b/doc/running.but index 39e1715..6c2b6c6 100644 --- a/doc/running.but +++ b/doc/running.but @@ -12,22 +12,19 @@ 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.chm} will be a Windows \i{HTML Help} version of the +same thing. (Note that to do this Halibut does not require any +external software such as a \i{Help compiler}. It \e{directly} +generates Windows HTML 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 \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 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}. \b The set of files \c{*.html} will contain an \i{HTML} version of @@ -79,6 +76,13 @@ line, using the \c{-C} option). \dd Synonym for \c{--html}. +\dt \i\cw{--chm}[\cw{=}\e{filename}] + +\dd Specifies that you want to generate Windows HTML Help +output. You can optionally specify a file name (e.g. +\c{\-\-chm=myfile.chm}), in which case Halibut will change the +name of the output file as well. + \dt \i\cw{--winhelp}[\cw{=}\e{filename}] \dd Specifies that you want to generate old-style Windows Help |