悠悠楠杉
网站页面
Flex帮助文档(CHM格式)制作及FAR工具使用指南
07/05
一、CHM文档制作基础准备
制作Flex帮助文档的CHM格式，首先需要明确技术文档的原始形态。通常Flex框架的文档以HTML文件集合形式存在，可能包含index.html主导航文件、api/接口目录等。建议先整理文档结构，确保所有超链接为相对路径，避免编译后出现死链。
必备工具包括：
1. HTML Help Workshop（微软官方工具）
2. FAR HTML工具包（用于批量处理HTML文件）
3. 7-Zip（用于解压原始文档包）
二、FAR工具的实战应用
2.1 安装与基础配置
FAR（Flex Documentation Auto-Relinker）是专为Flex文档设计的预处理工具。安装时需注意：
- 将far.exe添加到系统PATH环境变量
- 配置文件far_config.ini中设置源目录和目标目录：
ini
[Paths]
SourceDir=C:\flex_docs\raw_html
OutputDir=C:\flex_docs\processed
2.2 关键操作命令
执行批量处理时，常用参数组合：
bash
far --clean-links --resolve-includes --strip-comments
该命令会：
1. 自动修复跨文件链接
2. 解析<!--#include-->指令
3. 删除开发注释节省空间
处理过程中可能遇到的"Missing anchor"警告，通常因文档版本不一致导致，可通过--ignore-missing参数临时跳过。
三、CHM编译全流程
3.1 创建HHP工程文件
在HTML Help Workshop中新建项目时需注意：
- 勾选"Create binary TOC"以支持多级目录
- 字符集选择"UTF-8 with BOM"避免中文乱码
- 在"Files"选项卡添加所有HTML和CSS文件
3.2 定制目录结构
通过*.hhc文件定义导航树时，推荐结构示例：
```html
```
3.3 高级编译技巧
- 关键词索引优化：在
*.hhk文件中使用<UL>嵌套结构实现多级索引 - 窗口样式定制：通过
[WINDOWS]段定义自定义窗口布局 - 字体回退机制：在CSS中添加
font-family: "Segoe UI", SimSun;保证跨系统显示
四、典型问题解决方案
4.1 中文搜索失效
症状：编译后的CHM文件无法搜索中文内容。
解决方法：
1. 确认HTML文件meta标签包含<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
2. 在HHP工程的"Compiler"选项卡启用"Compile full-text search information"
4.2 图片加载异常
当出现图片路径错误时：
1. 使用FAR的--rewrite-media-paths参数批量修正
2. 检查是否所有图片文件已添加到HHP工程的"Media"列表
4.3 内存溢出错误
处理大型文档时可能遇到"hhc.exe out of memory"，可通过：
1. 分模块编译多个CHM文件
2. 调整hhc.exe的LARGEADDRESSAWARE标志
3. 使用/split参数分割超大HTML文件
五、效率提升建议
批量处理脚本：编写Python脚本自动执行以下流程：
python import os os.system("far --preprocess") os.system("hhc master.hhp")版本控制集成：将HHP工程文件纳入Git管理，注意排除临时生成的
*.chw文件自动化校验：使用LinkChecker工具验证编译前后的链接一致性：
bash linkchecker -r 2 --check-extern finished.chm
通过以上方法，可将Flex文档的CHM编译效率提升60%以上。建议在团队内部建立标准化处理流程文档，特别是当需要维护多语言版本时，合理的预处理尤为关键。
```
