From 7e330bca5bc45fa7feb6c31da5c3f1b6b44c208c Mon Sep 17 00:00:00 2001 From: Simon Tatham Date: Sat, 13 May 2017 18:33:51 +0100 Subject: New output mode to write CHM files directly. I became aware a few months ago that enough is known about CHM files that free software _can_ write them without benefit of the MS HTML Help compiler - in particular there's a thing called 'chmcmd' in the Free Pascal Compiler software distribution which is more or less a drop-in replacement for hhc.exe itself. But although depending on chmcmd would be a bit nicer than depending on hhc.exe, Halibut has always preferred to do the whole job itself if it can. So here's my own from-scratch code to generate CHM directly from Halibut source. The new output mode is presented as a completely separate top-level thing independent of HTML mode. Of course, in reality, the two back ends share all of the HTML-generation code, differing only in a few configuration defaults and the minor detail of what will be _done_ with each chunk of HTML as it's generated (this is what the recent refactoring in b3db1cce3 was in aid of). But even so, the output modes are properly independent from a user-visible-behaviour perspective: they use parallel sets of config directives rather than sharing the same ones (you can set \cfg{html-foo} and \cfg{chm-foo} independently, for a great many values of 'foo'), and you can run either or neither or both as you choose in a given run of Halibut. The old HTML Help support, in the form of some config directives for HTML mode to output the auxiliary files needed by hhc.exe, is still around and should still work the same as it always did. I have no real intention of removing it, partly for the reasons stated in the manual (someone might find it useful to have Halibut generate the .HHP file once and then make manual adjustments to it, so that they can change styling options that the direct CHM output doesn't permit), and mostly because it wouldn't save a great deal of code or complexity in any case - the big two of the three auxiliary files (the HHC and HHK) have to be generated _anyway_ to go inside the .CHM, so all the code would have to stay around regardless. --- doc/running.but | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'doc/running.but') 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 -- cgit v1.1