CODEWITHSUNDEEP
python-sphinxchmhtml-help
Adrien Laveau
Adrien Laveau

Reputation: 73

HTMLHELP file produced with Python3.11 Sphinx 7.2.6 cannot be compiled with hhc.exe

Our software uses Sphinx to produce documentation, website, chm etc... We are trying to switch from to python2.7 to python3.11 One of the blocking point is the following : We run sphinx -b htmlhelp and then we run hhc.exe on the output to produce the CHM.

Doing so provokes the following error and the chm is corrupted

HHC5013: Error:
runtime error R6002
- floating point not loaded

After investigation I realized that the produced files (.hhp,.hhc etc..) are different (with sphinx ran on the same input files and same configuration of course)

And especially some special characters in the hhc file "}" are encoded. Changing them back manually to their original value seems to fix the problem. Left : file created with python 2.7 --> works Right : file created with python 3.11 --> does not work

enter image description here

Indeed the correct file name is

src/functions/@f{lastprintdate}.html

Upvotes: 0

Views: 158

Answers (1)

help-info.de
help-info.de

Reputation: 7298

Please note that the proprietary CHM file format is about 25 years old und was first shipped with IE4 and Windows 98.

You know - the HTML Help 1.x compiler is not Unicode compatible and can fail when compiling a CHM that contains non-latin or special (e.g. @,{,},#,$,!,*,& etc) characters in the path and / or topic names. URL percent encoding replaces special ASCII characters with a "%" followed by two hexadecimal digits.

The error is reproducible using a simple topic file e.g. @f{lastprintdate}.rst and also occurs in an optional generated index file *.hhk in addition to the known problem with the file for the table of contents *.hhc (tested on Windows10 Pro, Python 3.11.4, Sphinx 7.2.6). The generated *.hhp project file using src\functions\@f{lastprintdate}.html in the [FILES] section is OK.

*.hhc sample:

<LI> <OBJECT type="text/sitemap">
    <param name="Name" value="Functions">
    <param name="Local" value="src/functions/%40f%7Blastprintdate%7D.html">
</OBJECT>

*.hhk sample:

<UL> <LI> <OBJECT type="text/sitemap">
    <param name="Keyword" value="LastPrintDate">
    <param name="Local" value="src/functions/%40f%7Blastprintdate%7D.html#index-0">
</OBJECT>

The suggested solution for HHC5013 in the HTMLHelp Error Message Reference does not help either, because Sphinx has already set Binary TOC=No by default!

HHC5013: TOC Error: URL reference cannot be resolved "filename" Problem: The compiler was unable to create a URL for an entry in the HHC file. This problem may occur if the compiler cannot locate a file referenced in the HHC. Result: The .chm file is corrupt and cannot be used.

BTW - sphinx-doc.org/en/master/changes.html#id1452 - support for Python 2.7 was dropped in Sphinx 2.0.0.

However, the problem is caused by Sphinx x.x.x (?, currently checked 7.2.6), because of the URL percent encoding replaces.

At this stage I only see to avoid filenames with special characters OR clean up your .hhc file as you already have done (e.g. using Notepad++ Macro, Script or RegEx).

Edit:

On Windows you'll find a __init__.py at

C:\Users\%USERNAME%\AppData\Local\Programs\Python\Python311\Lib\site-packages\sphinxcontrib\htmlhelp

To fix the behaviour for the HTMLHelp Table of Contents file .hhc above the class ToCTreeVisitor add

def chm_unquote(s: str) -> str:
    """
    Replace %xx escapes with their single-character equivalent.
    chm_unquote() is a temporal fix for CHM topic reference with %xx escapes 
    """
    s = urllib.parse.unquote(s)
    return s

and edit following lines in the class ToCTreeVisitor in this way:

    def visit_reference(self, node: Element) -> None:
        title = chm_htmlescape(node.astext(), True)
        node['refuri'] = chm_unquote(node['refuri'])
        self.append('    <param name="Name" value="%s">' % title)
        self.append('    <param name="Local" value="%s">' % node['refuri'])
        self.append('</OBJECT>')
        raise nodes.SkipNode

Upvotes: 0

Related Questions