Title: Index search in CHM help crashes viewer
Type: behavior Stage:
Components: Documentation, Windows Versions: Python 3.10, Python 3.9, Python 3.8, Python 3.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Keelung Yang, Václav Dvořák, chrullrich, cito, docs@python, malin, methane, paul.moore, steve.dower, tim.golden, zach.ware
Priority: normal Keywords:

Created on 2018-11-13 11:06 by chrullrich, last changed 2020-09-04 21:06 by steve.dower.

File name Uploaded Description Edit
binary_index.png malin, 2018-12-02 05:37
Messages (15)
msg329824 - (view) Author: Christian Ullrich (chrullrich) * Date: 2018-11-13 11:06
Typing into the index keyword field frequently crashes the CHM viewer with the first or second character. The Python CHMs are the only ones that I see this crash with; it started around 3.6 or so.

From event log:

Faulting application name: hh.exe, version: 10.0.17134.1, time stamp: 0xa0eff942
Faulting module name: hhctrl.ocx, version: 10.0.17134.48, time stamp: 0x412ce02a
Exception code: 0xc0000005
Fault offset: 0x00000000000387b2
Faulting process ID: 0x3558
Faulting application start time: 0x01d47b3f8db53eef
Faulting application path: C:\Windows\hh.exe
Faulting module path: C:\Windows\System32\hhctrl.ocx
Report ID: 53f84d38-adb4-4c0b-bd45-9bce02406e6f
Faulting package full name: 
Faulting package-relative application ID: 

This particular crash involved the file from 3.7.1:

sha1(doc\python371.chm) = 1c0e2d861cadc759436bfac0a767c5bb633423f9
msg330867 - (view) Author: Ma Lin (malin) * Date: 2018-12-02 05:37
I suffered this problem more than one years.
Here is a solution, before compiling the chm, modify like this:

--- D:\Python-3.7.1\Doc\build\htmlhelp\python371.hhp	Sun Dec 02 13:12:37 2018
+++ D:\fix_crash\python371.hhp	Sun Dec 02 13:05:57 2018
@@ -1,6 +1,6 @@
 Binary TOC=No
-Binary Index=No
+Binary Index=Yes
 Compiled file=python371.chm
 Contents file=python371.hhc
 Default Window=python371
The chm will generate a binary file python371.chw in the same folder when first opened.
No longer crash, but duplicated entries don't show Title anymore, see the attached picture.
msg330871 - (view) Author: Christian Ullrich (chrullrich) * Date: 2018-12-02 09:23
Ma Lin, thanks for the suggestion!

Yes, it looks like this option fixes the problem. I can reproduce the crash at will with a .chm built without this option, and not at all with one that has it on.

If the .chm's directory is not writable, the .chw will be created, and later reused from, %APPDATA%\Microsoft\HTML Help.

Unfortunately, sphinx apparently has no facility for setting this option to Yes in the generated .hhp file, so it will have to be modified before compilation.
msg332525 - (view) Author: Ma Lin (malin) * Date: 2018-12-26 02:10
I solved this thoroughly: Format disk C: and install a clean Windows 10.

Don't forget to backup important files in C:\Users\<user name>\ folder.
msg370448 - (view) Author: Keelung Yang (Keelung Yang) Date: 2020-05-31 13:29
It's reoccurable in Python 3.8.3 (tags/v3.8.3:6f8c832, May 13 2020, 22:37:02) [MSC v.1924 64 bit (AMD64)] on windows version 10.0.19041.264

Just need to open "Python 3.8 Manuals (64-bit)" --> index --> input 'p' on keyboard.
msg370581 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2020-06-01 21:16
Can anyone confirm that you've got an active code page of something other than 1252 ("standard" US English)? I'm not able to reproduce this easily, and I wonder if it's because of that setting.

Easiest way to check is in Python:
>>> import locale
>>> locale.getpreferredencoding()
msg370586 - (view) Author: Inada Naoki (methane) * (Python committer) Date: 2020-06-02 01:13
I think it's time to abandon chm file.  It is too old.  MS doesn't maintain it anymore.
Let's promote ePub and PDF instead.
msg370605 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2020-06-02 12:02
> Let's promote ePub and PDF instead.

Find a good viewer we can bundle with the installer with equivalent search/index functionality and we can consider it.

More realistically, including the docs as unbundled HTML files and relying on the default browser is probably an all-around better idea.
msg370919 - (view) Author: Václav Dvořák (Václav Dvořák) Date: 2020-06-07 22:58
@steve.dower: I have cp1250 and I've had this issue for years now, on several Windows versions. Hoping Microsoft will fix it is obviously futile; can I ask for the Python community to apply the workaround suggested by Ma Lin please? Thanks.
msg371012 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2020-06-08 16:48
We either need someone to contribute a fix to sphinxcontrib\htmlhelp\templates\project.hhp (bearing in mind that this *must* be optional, as it breaks search), or write code to patch the generated file between generation and use (which is probably hard).

And I'm not yet comfortable breaking search for it (as shown in the screenshot). I'd rather switch to distributing regular HTML files if there isn't a way to have both.
msg375994 - (view) Author: Ma Lin (malin) * Date: 2020-08-27 14:37
> More realistically, including the docs as unbundled HTML files
> and relying on the default browser is probably an all-around better idea.

CHM's index function is very convenient, I almost always use this feature when I use CHM.

How about use tkinter to write a doc indexing tool, it reads the indexes in this page:

Its behavior is the same as CHM's index, except that the link is opened in browser.

This indexing tool can be packaged with Python installer, just like IDLE, then MacOS/Linux users can also use the index.
msg375997 - (view) Author: Václav Dvořák (Václav Dvořák) Date: 2020-08-27 15:38
I have just apparently discovered a workaround! (Thanks to @chrullrich whose comment gave me the hint.) Maybe it's been obvious to everybody this whole time but I have only now found out that when I delete the file %APPDATA%\Microsoft\HTML Help\hh.dat (in my case c:\Users\dvorak\AppData\Roaming\Microsoft\HTML Help\hh.dat), the problem seems to go away. I'm so happy I just had to share. :)

I also have another, possibly naive idea. While Microsoft has ignored this issue for years, they have recently "helped the community release their distribution of Python to the Microsoft Store" (, and by "they", apparently I mean the very same Steve Dower who comments here, as I just realized. :-D (So... thanks, Steve.) So I'm thinking, as we actually have a Microsoft insider here, wouldn't it be possible to make Microsoft fix the viewer so that it, I don't know, possibly DOESN'T CRASH? I assume that Microsoft has plenty of those crash reports in some database?
msg376033 - (view) Author: Ma Lin (malin) * Date: 2020-08-28 12:01
> when I delete the file %APPDATA%\Microsoft\HTML Help\hh.dat,
> the problem seems to go away.

It doesn't work for me.
Moreover, `Binary Index=Yes` no longer works on my PC.

A few days ago, I installed a clean Windows 10 2004, then CHM's index cannot be used.
msg376112 - (view) Author: Christoph Zwerschke (cito) * Date: 2020-08-30 16:33
Had the same problem for years and wondered why nobody else complained.

Still reproducable with Win 10 Pro 2004, Python 3.8, cp1252 locale.

Deleting hh.dat did not solve the problem for me.
msg376405 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2020-09-04 21:06
So I found the "owner" of the HTML Help component in Windows (I put owner in quotes because this tool is _very_ maintenance mode, so nothing short of a critical vulnerability is going to be touched) and he helped me do some debugging.

In short, the index file is either corrupt, or it is not parsed correctly. I can reliably reproduce the crash with the following steps:

1. Open the Python docs
2. Switch to the Index tab
3. Double-click on any second-level (indented) entry
4. Modify the text in the Index search box

We haven't yet gone deep enough to be able to tell whether the help compiler is at fault, or the loader.

If anyone has the time and inclination, testing with older versions (if you can find them) of the HTML Help compiler may find a version that works. Unfortunately, the older copies we used to use were on the Subversion server, which is long gone now.

Alternatively, if anyone knows of a similar tool that we can redistribute easily with CPython (i.e. it's not as big as Zeal) and is significantly better than just using the user's default browser, I'd be interested to hear about it (as would the rest of the developer world, I'm sure - this is a fairly popular format!).
Date User Action Args
2020-09-04 21:06:02steve.dowersetmessages: + msg376405
2020-08-30 16:33:00citosetnosy: + cito
messages: + msg376112
2020-08-28 12:01:35malinsetmessages: + msg376033
2020-08-27 15:38:18Václav Dvořáksetmessages: + msg375997
2020-08-27 14:37:46malinsetmessages: + msg375994
2020-06-08 16:48:31steve.dowersetmessages: + msg371012
2020-06-07 22:58:08Václav Dvořáksetnosy: + Václav Dvořák
messages: + msg370919
2020-06-02 12:02:06steve.dowersetmessages: + msg370605
2020-06-02 01:14:00methanesetnosy: + methane
messages: + msg370586
2020-06-01 21:16:41steve.dowersetmessages: + msg370581
versions: + Python 3.8, Python 3.9, Python 3.10
2020-05-31 13:29:11Keelung Yangsetnosy: + Keelung Yang
messages: + msg370448
2018-12-26 02:10:30malinsetmessages: + msg332525
2018-12-02 09:23:30chrullrichsetmessages: + msg330871
2018-12-02 05:37:15malinsetfiles: + binary_index.png
nosy: + malin
messages: + msg330867

2018-11-13 11:06:57chrullrichcreate