当前位置：物联沃-IOTWORD物联网 > 技术教程 > Python 从零到一，制作.chm文件全攻略
代码收藏家代码收藏家 技术教程

Python 从零到一，制作.chm文件全攻略

文章目录

  • CHM文件简介
  • CHM文件的特点
  • CHM文件的应用场景
  • 生成CHM文件所需的微软工具
  • HTML Help Workshop
  • Microsoft HTML Help Compiler (hhc.exe)
  • Microsoft Help Viewer
  • CHM工程所需的关键文件
  • .hhp文件（HTML Help Project）
  • .hhk文件（HTML Help Index）
  • .hhc文件（HTML Help Table of Contents）
  • 其他资源文件
  • 关键文件说明
  • 项目配置文件（`.hhp`）
  • 目录文件（`.hhc`）
  • 索引文件（`.hhk`）
  • 总结
  • 示例
  • hhp
  • hhc
  • hhk
  • hhc更多规则
  • 注意事项
  • 示例代码
  • 参考

    • CHM文件简介

    在软件开发领域，为用户提供详尽的帮助文档是至关重要的。微软的CHM文件格式，即编译的HTML帮助文件，提供了一种高效的方式来组织和分发这些文档。CHM文件以其独特的优势，如易于导航、搜索功能强大、占用空间小等，成为了许多软件开发者和文档编写者的首选格式。

    CHM文件的特点

    压缩性：CHM文件将多个HTML文件和相关资源（如图片、CSS样式表等）压缩成一个单一的文件，减少了存储空间的需求，同时也方便了文件的传输和分发。

    导航性：CHM文件支持目录树和索引，使得用户可以快速地找到所需信息。

    搜索功能：内置的全文搜索功能允许用户快速定位关键词，提高了文档的可用性。

    兼容性：CHM文件格式广泛支持Windows操作系统，确保了广泛的用户基础。

    可定制性：开发者可以自定义CHM文件的布局、样式和功能，以匹配软件的品牌形象。

    CHM文件的应用场景

    软件开发：作为软件的帮助文档，提供用户操作指南、API参考等。
    技术文档：为技术手册、产品手册等提供易于访问的格式。
    在线帮助系统：作为在线帮助系统的离线版本，供用户在没有网络的情况下使用。
    随着技术的发展，尽管有新的文档格式和帮助系统不断涌现，CHM文件依然以其实用性和便利性在某些领域保持着其地位。在本文中，我们将深入探讨如何使用Python生成CHM文件，为读者提供一份全面的指南。

    生成CHM文件所需的微软工具

    HTML Help Workshop

    这是微软提供的一个免费工具，用于将HTML文件和相关资源编译成CHM格式。它提供了一个简单的图形界面，允许用户添加文件、设置项目属性，并生成CHM文件。

    Microsoft HTML Help Compiler (hhc.exe)

    这是一个命令行工具，用于编译HTML帮助文件。它比HTML Help Workshop更为灵活，可以通过脚本自动化编译过程。

    Microsoft Help Viewer

    这是一个应用程序，用于查看和搜索CHM文件。它支持多种语言，并且可以与Visual Studio等开发工具集成。

    CHM工程所需的关键文件

    .hhp文件（HTML Help Project）

    这是项目文件，包含了创建CHM文件所需的所有信息。它定义了项目的标题、目录结构、索引、搜索关键字、编译选项等。.hhp文件是编译过程中的核心，因为它指导HTML Help Compiler如何将HTML内容和其他资源编译成CHM文件。
    .hhc文件（HTML Help Contents）
    这是目录文件，定义了CHM文件中的目录树结构。用户可以通过目录树来浏览文档的不同部分。.hhc文件通常由HTML Help Workshop自动生成，但也可以手动编辑，以定制目录的显示方式。

    .hhk文件（HTML Help Index）

    这是索引文件，包含了CHM文件中的关键词索引。用户可以通过索引快速找到文档中特定的主题或词汇。.hhk文件同样可以由HTML Help Workshop生成，也可以根据需要进行手动编辑。

    .hhc文件（HTML Help Table of Contents）

    这是目录文件的另一种形式，定义了CHM文件的目录结构，但与.hhc文件不同，.hhc文件通常用于定义更复杂的目录结构，如多级目录。

    其他资源文件

    除了上述文件外，CHM工程还可能包括图像、CSS样式表、JavaScript脚本等资源文件，这些都是构成CHM文件内容和样式的必需品。

    关键文件说明

    您提供的示例文件分别对应了CHM文件创建过程中的三个关键组件：项目配置文件（.hhp）、目录文件（.hhc）和索引文件（.hhk）。下面我将逐一解释每个文件的内容和作用：

    项目配置文件（.hhp）

    这个文件是一个文本文件，包含了创建CHM文件所需的编译选项。以下是您提供的.hhp文件内容的解释：

  • Compatibility=1.1 or later：指定了CHM文件的兼容性版本，这里是1.1或更高版本。
  • Compiled file=HALCON_Operator_Reference.chm：指定了生成的CHM文件的名称。
  • Default topic=index.html：定义了CHM文件的默认打开页面。
  • Display compile progress=Yes：在编译过程中是否显示进度。
  • Full-text search=Yes：是否启用全文搜索功能。
  • Contents file=HALCON_Operator_Reference.hhc：指定了目录文件的名称。
  • Index file=HALCON_Operator_Reference.hhk：指定了索引文件的名称。
  • Language=0x804 中文(简体，中国)：设置了CHM文件的语言代码和语言描述。
  • Default Font=微软雅黑,12,0：定义了CHM文件中默认使用的字体、大小和样式。
  • Title=HALCON_Operator_Reference：设置了CHM文件的标题。

    • 目录文件（.hhc）

    这个文件是一个HTML文件，定义了CHM文件中的目录结构。以下是您提供的.hhc文件内容的解释：

  • <!DOCTYPE HTML ...>：声明了这是一个HTML文档。
  • <meta name="GENERATOR" content="Python HTML Help Generator">：指定了生成这个文件的工具。
  • <OBJECT type="text/site properties">：定义了CHM文件的一些属性，如窗口样式和字体。
  • <UL> 和 <LI>：定义了一个无序列表，每个列表项代表目录中的一个条目。
  • <OBJECT type="text/sitemap"> 和 <param name="Name" value="...">：定义了目录项的名称。
  • <param name="Local" value="...">：指定了每个目录项对应的本地HTML文件。

    • 索引文件（.hhk）

    这个文件也是一个HTML文件，定义了CHM文件中的索引结构。它的结构与.hhc文件类似，但用于索引而不是目录。以下是您提供的.hhk文件内容的解释：

  • 结构与.hhc文件类似，但通常用于定义索引项而不是目录项。
  • 索引项允许用户通过关键词快速查找文档中的相关内容。

    • 总结

    这些文件共同工作，使得CHM文件能够具有目录导航、索引查找和全文搜索等功能。.hhp文件作为项目配置的核心，指导编译过程；.hhc和.hhk文件则分别定义了目录和索引结构，使用户能够方便地浏览和搜索帮助文档。在Python中，您可以编写脚本来生成和编辑这些文件，以自动化CHM文件的创建过程。

    示例

    hhp

    [OPTIONS]
Compatibility=1.1 or later
Compiled file=HALCON_Operator_Reference.chm
Default topic=index.html
Display compile progress=Yes
Full-text search=Yes
Contents file=HALCON_Operator_Reference.hhc
Index file=HALCON_Operator_Reference.hhk
Language=0x804 中文(简体，中国)
Default Font=微软雅黑,12,0
Title=HALCON_Operator_Reference

    hhc

    <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Python HTML Help Generator">
<!-- Sitemap 1.0 -->
</HEAD>
<BODY>
<OBJECT type="text/site properties">
    <param name="Window Styles" value="0x800025">
    <param name="Font" value="微软雅黑,12,0">
</OBJECT>
<UL>

  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_diff_image "><param name="Local" value="abs_diff_image.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_funct_1d "><param name="Local" value="abs_funct_1d.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_image "><param name="Local" value="abs_image.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_matrix "><param name="Local" value="abs_matrix.html"></OBJECT>
...
</UL>
</BODY>
</HTML>

    hhk

    <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Python HTML Help Generator">
<!-- Index file for HHW -->
</HEAD>
<BODY>
<UL>

  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_diff_image "><param name="Local" value="abs_diff_image.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_funct_1d "><param name="Local" value="abs_funct_1d.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_image "><param name="Local" value="abs_image.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_matrix "><param name="Local" value="abs_matrix.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="abs_matrix_mod "><param name="Local" value="abs_matrix_mod.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="access_channel "><param name="Local" value="access_channel.html"></OBJECT>
  <LI> <OBJECT type="text/sitemap"><param name="Name" value="acos_image "><param name="Local" value="acos_image.html"></OBJECT>
....
</UL>
</BODY>
</HTML>

    hhc更多规则

  • UL表达为一个目录（称为heading），多个UL嵌套就是多目录嵌套，叶子节点就是LI（称为page）
  • UL和LI可以变更图标：<param name="Image" value="path/to/icon2.png">
  • Local和Topic区别：<param name="Local" value="introduction.html"> <param name="Topic" value="introduction.html#section1">
  • Local=“introduction.html”：指定了目录项链接到的HTML文件的相对路径。
  • Topic=“introduction.html#section1”：定义了点击目录项时打开的HTML文件的确切位置
  • UL和LI可以使用内置图标：编号从1到42，<param name="ImageNumber" value="10">
  • 采集网络上的html文件，可以采用Teleport Ultra完成

    • 注意事项

  • 在 hhp/hhc/hhk 中涉及路径的地方都要采用相对路径，以.hhp作为参考点
  • hhp/hhc/hhk 不能采用utf-8格式存储，可以是默认编码，也可以是gb2312
  • 路径不要包含中文

    • 示例代码

    import os
import re
import subprocess
import chardet
'''
CHM 文件生成器。
目前没有考虑子目录概念，按理子目录应该是一个UL标签。现在都按照LI来处理。
且hhc和hhk都采用了同样的结构，而实际应用程序的chm文件可能hhc要复杂些。
也没有为hhc提供图标。
'''

name = "HALCON_Operator_Reference"

title_remove = "[HALCON Operator Reference / Version 13.0.4]"
'''
hhp/hhc/hhk都必须与.html在同一个目录或上级目录，但是需要保障的是
在hhp/hhc/hhk中采用的是相对路径，而不能是绝对路径。不然生成的.chm里面的页面打不开。
目前采用的方法是chm/hhp/hhc/hhk与html在同一个目录下。
'''

# 指定HTML文件所在的目录
html_directory = r'D:\mvtecDOC\mvtec2\mvtec'
# 输出的CHM文件名和HHP文件名
home_filename = 'index.html'
chm_filename = f'{name}.chm'
project_filename = f'{name}.hhp'
content_filename = f'{name}.hhc'
index_filename = f'{name}.hhk'

# 定义hhp文件的默认值
hhp_template = f"""[OPTIONS]
Compatibility=1.1 or later
Compiled file={chm_filename}
Default topic={home_filename}
Display compile progress=Yes
Full-text search=Yes
Contents file={content_filename}
Index file={index_filename}
Language=0x804 中文(简体，中国)
Default Font=微软雅黑,12,0
Title={name}
"""

# 用于存储目录和索引的字符串
contents_str = """<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Python HTML Help Generator">
<!-- Sitemap 1.0 -->
</HEAD>
<BODY>
<OBJECT type="text/site properties">
    <param name="Window Styles" value="0x800025">
    <param name="Font" value="微软雅黑,12,0">
</OBJECT>
<UL>
"""

index_str = """<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<meta name="GENERATOR" content="Python HTML Help Generator">
<!-- Index file for HHW -->
</HEAD>
<BODY>
<UL>
"""

# 遍历目录下的所有HTML文件
html_files = [f for f in os.listdir(html_directory) if f.endswith('.html') and os.path.isfile(os.path.join(html_directory, f))]

for html_file in html_files:
    # hhp_template += os.path.join(html_directory, html_file) + '\n'

    print(html_file)
    file_path = os.path.join(html_directory, html_file)

    # 探测编码格式
    with open(file_path, 'rb') as file:
        bytes_data = file.read(32000)  # 读取32KB数据
        encoding = chardet.detect(bytes_data)['encoding']
        # print(encoding)

    with open(file_path, 'r', encoding=encoding, errors='replace') as file:
        content = file.read()
        title_match = re.search(r'<title>(.*?)</title>', content, re.IGNORECASE)
        title = title_match.group(1) if title_match else os.path.splitext(html_file)[0]
        title = title.replace(title_remove, '')
        contents_str += f'\n  <LI> <OBJECT type="text/sitemap"><param name="Name" value="{title}"><param name="Local" value="{html_file}"></OBJECT>'
        index_str += f'\n  <LI> <OBJECT type="text/sitemap"><param name="Name" value="{title}"><param name="Local" value="{html_file}"></OBJECT>'

contents_str += """
</UL>
</BODY>
</HTML>
"""
index_str += """
</UL>
</BODY>
</HTML>
"""

# hhc.exe 不支持utf-8

# 写入 .hhc 文件
with open(os.path.join(html_directory, content_filename), 'w', encoding='gb2312') as f:
    f.write(contents_str)

# 写入 .hhk 文件
with open(os.path.join(html_directory, index_filename), 'w', encoding='gb2312') as f:
    f.write(index_str)

# 写入hhp文件
with open(os.path.join(html_directory, project_filename), 'w', encoding='gb2312') as f:
    f.write(hhp_template)

# 调用hhc命令生成chm文件
# 需要确保hhc.exe在系统PATH中，或者提供完整路径
# "C:\Program Files (x86)\HTML Help Workshop\hhc.exe" D:\mvtecDOC\mvtec2\mvtec\HALCON_Operator_Reference.hhp
# hhc_path = r'"C:\Program Files (x86)\HTML Help Workshop\hhc.exe"'
# subprocess.run([hhc_path, project_filename], check=True)

    参考

  • XCHM-简单易用的chm制作器

    • 作者：西疆先生

    物联沃分享整理
    物联沃-IOTWORD物联网 » Python 从零到一，制作.chm文件全攻略

    代码收藏家 普通

    分享到：

    相关推荐

    发表回复