From: simon Date: Mon, 11 Dec 2006 19:43:10 +0000 (+0000) Subject: Support for the MS HTML Help system in the HTML back end. As yet I X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/halibut/commitdiff_plain/f2ef00b5e1a2a46947aab9e47119aff3e43c9326 Support for the MS HTML Help system in the HTML back end. As yet I don't know how to write out a .CHM directly, but I am at least able to have the HTML back end write out the three auxiliary files which enable a .CHM to be generated using the MS HTML Help compiler. git-svn-id: svn://svn.tartarus.org/sgt/halibut@6991 cda61777-01e9-0310-a592-d414129be87e --- diff --git a/bk_html.c b/bk_html.c index a1b46f6..11d37d3 100644 --- a/bk_html.c +++ b/bk_html.c @@ -10,6 +10,13 @@ * sensible. Perhaps for the topmost section in the file, no * fragment should be used? (Though it should probably still be * _there_ even if unused.) + * + * - In HHK index mode: subsidiary hhk entries (as in replacing + * `foo, bar' with `foo\n\tbar') can be done by embedding + * sub-

@@ -41,10 +48,12 @@ typedef struct { int ncdepths; int address_section, visible_version_id; int leaf_contains_contents, leaf_smallest_contents; + int navlinks; char *contents_filename; char *index_filename; char *template_filename; char *single_filename; + char *chm_filename, *hhp_filename, *hhc_filename, *hhk_filename; char **template_fragments; int ntfragments; char *head_end, *body_start, *body_end, *addr_start, *addr_end; @@ -77,6 +86,13 @@ struct htmlfile { int last_fragment_number; int min_heading_depth; htmlsect *first, *last; /* first/last highest-level sections */ + /* + * The `temp' field is available for use in individual passes + * over the file list. For example, the HHK index generation + * uses it to ensure no index term references the same file + * more than once. + */ + int temp; }; struct htmlsect { @@ -92,6 +108,7 @@ typedef struct { htmlfile *head, *tail; htmlfile *single, *index; tree234 *frags; + tree234 *files; } htmlfilelist; typedef struct { @@ -127,6 +144,8 @@ typedef struct { enum { HO_NEUTRAL, HO_IN_TAG, HO_IN_EMPTY_TAG, HO_IN_TEXT } state; + int hackflags; /* used for icky .HH* stuff */ + int hacklimit; /* text size limit, again for .HH* */ /* * Stuff beyond here deals with the higher syntactic level: it * tracks how many levels of

\n"); + currdepth++; + } + while (currdepth > depth) { + fprintf(ho.fp, "

\n", + f->filename, leaf ? 11 : 1); + } + + while (currdepth > 0) { + fprintf(ho.fp, "

\n"); + + cleanup(&ho); + } + if (hhk_filename) { + htmlfile *f; + htmloutput ho; + indexentry *entry; + int i; + + /* + * First make a pass over all HTML files and set their + * `temp' fields to zero, because we're about to use them. + */ + for (f = files.head; f; f = f->next) + f->temp = 0; + + ho.fp = fopen(hhk_filename, "w"); + if (!ho.fp) + error(err_cantopenw, hhk_filename); + + ho.charset = CS_CP1252; /* as far as I know, HHK files are */ + ho.restrict_charset = CS_CP1252; /* hardwired to this charset */ + ho.cstate = charset_init_state; + ho.ver = HTML_4; /* *shrug* */ + ho.state = HO_NEUTRAL; + ho.contents_level = 0; + ho.hackflags = HO_HACK_QUOTEQUOTES; + + /* + * Magic DOCTYPE which seems to work for .HHK files. I'm + * wary of trying to change it! + */ + fprintf(ho.fp, "\n" + "\n" + "\n" + "

\n"); + + /* + * Now go through those files and re-clear the temp + * fields ready for the _next_ index term. + */ + for (j = 0; j < hi->nrefs; j++) { + htmlindexref *hr = + (htmlindexref *)hi->refs[j]->private_data; + hr->section->file->temp = 0; + } + } + } + + fprintf(ho.fp, "

\n"); + cleanup(&ho); + } + + /* * Go through and check that no index fragments were referenced * without being generated, or indeed vice versa. * @@ -1491,6 +1875,11 @@ void html_backend(paragraph *sourceform, keywordlist *keywords, } freetree234(files.frags); } + /* + * The strings in files.files are all owned by their containing + * htmlfile structures, so there's no need to free them here. + */ + freetree234(files.files); { htmlsect *sect, *tmp; sect = sects.head; @@ -1584,8 +1973,12 @@ static void html_file_section(htmlconfig *cfg, htmlfilelist *files, * we invent a fresh file and put this section at its head. * Otherwise, we put it in the same file as its parent * section. + * + * Another special value of cfg->leaf_level is -1, which + * means infinity (i.e. it's considered to always be + * greater than depth). */ - if (ldepth > cfg->leaf_level) { + if (cfg->leaf_level > 0 && ldepth > cfg->leaf_level) { /* * We know that sect->parent cannot be NULL. The only * circumstance in which it can be is if sect is at @@ -1641,7 +2034,8 @@ static htmlfile *html_new_file(htmlfilelist *list, char *filename) list->head = ret; list->tail = ret; - ret->filename = dupstr(filename); + ret->filename = html_sanitise_filename(list, dupstr(filename)); + add234(list->files, ret->filename); ret->last_fragment_number = 0; ret->min_heading_depth = INT_MAX; ret->first = ret->last = NULL; @@ -1943,8 +2337,16 @@ static void html_text_limit_internal(htmloutput *ho, wchar_t const *text, char outbuf[256]; int bytes, err; + if (ho->hackflags & (HO_HACK_QUOTEQUOTES | HO_HACK_OMITQUOTES)) + quote_quotes = TRUE; /* override the input value */ + if (maxlen > 0 && textlen > maxlen) textlen = maxlen; + if (ho->hacklimit >= 0) { + if (textlen > ho->hacklimit) + textlen = ho->hacklimit; + ho->hacklimit -= textlen; + } while (textlen > 0) { /* Scan ahead for characters we really can't display in HTML. */ @@ -1978,19 +2380,25 @@ static void html_text_limit_internal(htmloutput *ho, wchar_t const *text, * HTML. */ if (ho->fp) { - if (*text == L'<') - fprintf(ho->fp, "<"); - else if (*text == L'>') - fprintf(ho->fp, ">"); - else if (*text == L'&') - fprintf(ho->fp, "&"); - else if (*text == L'"') - fprintf(ho->fp, """); - else if (*text == L' ') { - assert(nbsp); - fprintf(ho->fp, " "); - } else - assert(!"Can't happen"); + if (*text == L'"' && (ho->hackflags & HO_HACK_OMITQUOTES)) { + fputc('\'', ho->fp); + } else if (ho->hackflags & HO_HACK_QUOTENOTHING) { + fputc(*text, ho->fp); + } else { + if (*text == L'<') + fprintf(ho->fp, "<"); + else if (*text == L'>') + fprintf(ho->fp, ">"); + else if (*text == L'&') + fprintf(ho->fp, "&"); + else if (*text == L'"') + fprintf(ho->fp, """); + else if (*text == L' ') { + assert(nbsp); + fprintf(ho->fp, " "); + } else + assert(!"Can't happen"); + } } text++, textlen--; } @@ -2162,6 +2570,69 @@ static char *html_sanitise_fragment(htmlfilelist *files, htmlfile *file, return text; } +static char *html_sanitise_filename(htmlfilelist *files, char *text) +{ + /* + * Unceremoniously rip out any character that might cause + * difficulty in some filesystem or another, or be otherwise + * inconvenient. + * + * That doesn't leave much punctuation. I permit alphanumerics + * and +-.=_ only. + */ + char *p = text, *q = text; + + while (*p) { + if ((*p>='A' && *p<='Z') || + (*p>='a' && *p<='z') || + (*p>='0' && *p<='9') || + *p=='-' || *p=='_' || *p=='+' || *p=='.' || *p=='=') + *q++ = *p; + p++; + } + *q = '\0'; + + /* If there's nothing left, make something valid up */ + if (!*text) { + static const char anonfrag[] = "anon.html"; + text = sresize(text, lenof(anonfrag), char); + strcpy(text, anonfrag); + } + + /* + * Now we check for clashes with other filenames, and adjust + * this one if necessary by appending a hyphen followed by a + * number just before the file extension (if any). + */ + { + int len, extpos; + int suffix = 1; + + p = NULL; + + while (find234(files->files, text, NULL)) { + if (!p) { + len = strlen(text); + p = text; + text = snewn(len+20, char); + + for (extpos = len; extpos > 0 && p[extpos-1] != '.'; extpos--); + if (extpos > 0) + extpos--; + else + extpos = len; + } + + sprintf(text, "%.*s-%d%s", extpos, p, ++suffix, p+extpos); + } + + if (p) + sfree(p); + } + + return text; +} + static void html_contents_entry(htmloutput *ho, int depth, htmlsect *s, htmlfile *thisfile, keywordlist *keywords, htmlconfig *cfg) 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{

} 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{

} 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{

} 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{ diff --git a/error.c b/error.c index 2dae220..7fe97ec 100644 --- a/error.c +++ b/error.c @@ -333,9 +333,14 @@ static void do_error(int code, va_list ap) { case err_pfnoafm: fpos = *va_arg(ap, filepos *); sp = va_arg(ap, char *); - sprintf(error, "No metrics available for Type 1 font '%.200s'", sp); + sprintf(error, "no metrics available for Type 1 font '%.200s'", sp); flags = FILEPOS; break; + case err_chmnames: + sprintf(error, "only one of html-mshtmlhelp-chm and " + "html-mshtmlhelp-hhp found"); + flags = PREFIX; + break; case err_whatever: sp = va_arg(ap, char *); vsprintf(error, sp, ap); diff --git a/halibut.h b/halibut.h index 3cb1ed7..1ff014e 100644 --- a/halibut.h +++ b/halibut.h @@ -252,6 +252,7 @@ enum { err_pfhead, /* bad Type 1 header line */ err_pfbad, /* otherwise invalide Type 1 font */ err_pfnoafm, /* Type 1 font but no AFM */ + err_chmnames, /* need both or neither of hhp+chm */ err_whatever /* random error of another type */ }; diff --git a/inputs/test.but b/inputs/test.but index f52d4b8..ecd5a2d 100644 --- a/inputs/test.but +++ b/inputs/test.but @@ -279,6 +279,11 @@ Umm. Ahh. +\H{app-\\two} Section with inconvenient keyword + +If you apply this file together with \cw{doc/chm.but}, this section +should test \cw{html_sanitise_filename()}. + \U Bibliography \B{book} Some text describing a book.