[1.8] htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files (#5853)

* htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files

.hhc/.hhk files don't recognize hex escaping, we need convert hex escaping to decimal escaping. for example: `'` -> `'`.

CHANGES

@@ -37,6 +37,7 @@ Bugs fixed
   possibility to use original meaning in place of Sphinx custom one
 * #5834: apidoc: wrong help for ``--tocfile``
 * #5800: todo: crashed if todo is defined in TextElement
+* #5846: htmlhelp: convert hex escaping to decimal escaping in .hhc/.hhk files
 
 Testing
 --------

sphinx/builders/htmlhelp.py

@@ -13,6 +13,7 @@ from __future__ import print_function
 
 import codecs
 import os
+import re
 from os import path
 
 from docutils import nodes
@@ -27,7 +28,7 @@ from sphinx.util.pycompat import htmlescape
 
 if False:
     # For type annotation
-    from typing import Any, Dict, IO, List, Tuple  # NOQA
+    from typing import Any, Dict, IO, List, Match, Tuple  # NOQA
     from sphinx.application import Sphinx  # NOQA
 
 
@@ -169,6 +170,24 @@ chm_locales = {
 }
 
 
+def chm_htmlescape(*args, **kwargs):
+    # type: (*Any, **Any) -> unicode
+    """
+    chm_htmlescape() is a wrapper of htmlescape().
+    .hhc/.hhk files don't recognize hex escaping, we need convert
+    hex escaping to decimal escaping. for example: `'` -> `'`
+    htmlescape() may generates a hex escaping `'` for single
+    quote `'`, this wrapper fixes this.
+    """
+    def convert(matchobj):
+        # type: (Match[unicode]) -> unicode
+        codepoint = int(matchobj.group(1), 16)
+        return '&#%d;' % codepoint
+    return re.sub(r'&#[xX]([0-9a-fA-F]+);',
+                  convert,
+                  htmlescape(*args, **kwargs))
+
+
 class HTMLHelpBuilder(StandaloneHTMLBuilder):
     """
     Builder that also outputs Windows HTML help project, contents and
@@ -278,7 +297,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
                         write_toc(subnode, ullevel)
                 elif isinstance(node, nodes.reference):
                     link = node['refuri']
-                    title = htmlescape(node.astext()).replace('"', '"')
+                    title = chm_htmlescape(node.astext()).replace('"', '"')
                     f.write(object_sitemap % (title, link))
                 elif isinstance(node, nodes.bullet_list):
                     if ullevel != 0:
@@ -311,7 +330,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder):
                     item = '    <param name="%s" value="%s">\n' % \
                         (name, value)
                     f.write(item)
-                title = htmlescape(title)
+                title = chm_htmlescape(title)
                 f.write('<LI> <OBJECT type="text/sitemap">\n')
                 write_param('Keyword', title)
                 if len(refs) == 0:

tests/roots/test-build-htmlhelp/conf.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+
+project = 'test'
+master_doc = 'index'

tests/roots/test-build-htmlhelp/index.rst

@@ -0,0 +1,19 @@
+Index markup
+------------
+
+.. index::
+   single: entry
+   pair: entry; pair
+   double: entry; double
+   triple: index; entry; triple
+   keyword: with
+   see: from; to
+   seealso: fromalso; toalso
+
+.. index::
+   !Main, !Other
+   !single: entry; pair
+
+.. index:: triple-quoted string, Unicode Consortium, raw string
+   single: """; string literal
+   single: '''; string literal

tests/roots/test-build-htmlhelp/make.bat

@@ -0,0 +1,64 @@
+@echo off
+setlocal
+
+pushd %~dp0
+
+set this=%~n0
+
+if not defined PYTHON set PYTHON=py
+
+if not defined SPHINXBUILD (
+    %PYTHON% -c "import sphinx" > nul 2> nul
+    if errorlevel 1 (
+        echo Installing sphinx with %PYTHON%
+        %PYTHON% -m pip install sphinx
+        if errorlevel 1 exit /B
+    )
+    set SPHINXBUILD=%PYTHON% -c "import sphinx.cmd.build, sys; sys.exit(sphinx.cmd.build.main())"
+)
+
+rem Search for HHC in likely places
+set HTMLHELP=
+where hhc /q && set HTMLHELP=hhc && goto :skiphhcsearch
+where /R ..\externals hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" where /R "%ProgramFiles(x86)%" hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" where /R "%ProgramFiles%" hhc > "%TEMP%\hhc.loc" 2> nul && set /P HTMLHELP= < "%TEMP%\hhc.loc" & del "%TEMP%\hhc.loc"
+if not exist "%HTMLHELP%" (
+    echo.
+    echo.The HTML Help Workshop was not found.  Set the HTMLHELP variable
+    echo.to the path to hhc.exe or download and install it from
+    echo.http://msdn.microsoft.com/en-us/library/ms669985
+    exit /B 1
+)
+echo hhc.exe path: %HTMLHELP%
+
+if "%BUILDDIR%" EQU "" set BUILDDIR=build
+
+%SPHINXBUILD% >nul 2> nul
+if errorlevel 9009 (
+    echo.
+    echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+    echo.installed, then set the SPHINXBUILD environment variable to point
+    echo.to the full path of the 'sphinx-build' executable. Alternatively you
+    echo.may add the Sphinx directory to PATH.
+    popd
+    exit /B 1
+)
+
+set SPHINXOPTS=-D html_theme_options.body_max_width=none %SPHINXOPTS%
+
+cmd /S /C "%SPHINXBUILD% %SPHINXOPTS% -bhtmlhelp -dbuild\doctrees . "%BUILDDIR%\htmlhelp"
+
+"%HTMLHELP%" "%BUILDDIR%\htmlhelp\test.hhp"
+rem hhc.exe seems to always exit with code 1, reset to 0 for less than 2
+if not errorlevel 2 cmd /C exit /b 0
+
+echo.
+if errorlevel 1 (
+    echo.Build failed (exit code %ERRORLEVEL%^), check for error messages
+    echo.above.  Any output will be found in %BUILDDIR%\%1
+) else (
+    echo.Build succeeded. All output should be in %BUILDDIR%\%1
+)
+
+popd

tests/test_build_htmlhelp.py

@@ -0,0 +1,45 @@
+"""
+    test_build_htmlhelp
+    ~~~~~~~~~~~~~~~~~~~
+    Test the HTML Help builder and check output against XPath.
+    :copyright: Copyright 2007-2018 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import os.path
+import re
+import sys
+from subprocess import Popen, PIPE
+
+import pytest
+
+from sphinx.util.osutil import cd
+
+
+@pytest.mark.skipif(sys.platform != "win32",
+                    reason="hhc.exe only available on Windows.")
+@pytest.mark.sphinx('htmlhelp', testroot='build-htmlhelp')
+def test_chm():
+    # run make.bat
+    with cd(r".\roots\test-build-htmlhelp"):
+        try:
+            p = Popen(['make.bat'],
+                      stdout=PIPE, stderr=PIPE)
+        except:
+            raise
+        else:
+            p.communicate()
+
+    # check .hhk file
+    this_path = os.path.dirname(os.path.abspath(__file__))
+    hhk_file = os.path.join(this_path, 'roots', 'test-build-htmlhelp',
+                            'build', 'htmlhelp', 'test.hhk')
+    if not os.path.isfile(hhk_file):
+        print(".chm build failed, please install HTML Help Workshop.")
+        return
+
+    with open(hhk_file, 'rb') as f:
+        data = f.read()
+    m = re.search(br'&#[xX][0-9a-fA-F]+;', data)
+    assert m == None, 'Hex escaping exists in .hhk file: ' + str(m.group(0))
+