The best way to convert from Javadoc to .chm

Pre-processing:

由于chm是微软公司发布的一种帮助文档格式,所有要使用下面的方法转换,请先安装HTML Help Workshop(HHW)。还有一个很重要的问题,就是如何从项目生成Javadoc,可以使用Eclipse中的Export功能,但是这里有几个小点需要注意:

1. Java代码的格式问题

Java代码编写的使用有的使用GBK,有的使用UTF-8,这个时候就会有区别。使用GBK编码的时候生成Javadoc文档时没有太大问题的,但是,要是整个项目的默认编码格式是UTF-8的话,就会报警告:编码 GBK 的不可映射字符

根本没有成功生成Javadoc文档,如何解决?解决方案就是在生成Javadoc的时候对VM options进行编码设置-encoding UTF-8 -charset UTF-8,设置如下:

2.如何把生成的Javadoc文档生成英语版本

这个问题有的时候为了解决中文乱码是很重要的,我们生成英文版本的Javadoc(仅对生成的Javadoc框架的语言做限制,并没有对注释内容的格式做限制,也就是说这个时候注释还是可以是中文的)。 解决方案也是在VM options中加入-locale en_US,但是此时注意的是,如果把-locale en_US设置在后面的话,会报一个错误,大致是-locale en_US在javadoc命令必须是在最前面,所有,正确的写法就是-locale en_US -encoding UTF-8 -charset UTF-8(整合上面),默认如果不写-locale的话,安装locale语言来进行设置,当然我们中国人就是中文的了。(当然如果你工程默认编码是GBK而且您想生成中文的帮助文档的话,这写都可以不要,使用默认即可) 设置截图如下:

Generate .chm Document:

关于 Javadoc To CHM 的介绍,这里摘自原作者的网站:http://www.burgaud.com/jd2chm/

Javadoc To CHM is a software that generates Microsoft HTML Help projects files from a Javadoc documentation. It generates the project file (.HHP), the contents file (.HHC) and the index file (.HHK). After having generated the HTML project files, Jd2chm invokes the Microsoft HTML Help Compiler (hhc.exe) with the project file (.HHP) as parameter in order to build the Compiled HTML file (.CHM).

Summary

Screenshot

Notes About Jd2chm Version 0.3

Jd2chm 0.3 does not have a documentation other than the following sections. You can also access the slightly outdated jd2chm 2.0 documentation, jd2chm_doc.htm or jd2chm.pdf (138kB). Feel free to contact the author if you have any question.

Features

Jd2chm 0.3 includes many improvements. Here is a brief list of the new Jd2chm features and improvements:

  • Distributed in two formats: Python script, jd2chm_py_03.zip (10kB), for those who already have Python installed on their computer and Win32 executable version, jd2chm_exe_03.zip (1MB), for the others.
  • The executable version was prepared with the McMillan Installer. See section Resources for related resources.
  • Script compatible with Python 2.2 and 2.3.
  • Performance improvement: the parsing does not use any more the HTML parser but only regular expressions.
  • The Microsoft HTML Help Compiler is required (see Javadoc To CHM Resources).
  • Detection of the Microsoft HTML compiler.
  • Starts automatically the CHM compilation.
  • Moving the full JDK Javadoc API to a temporary directory is not needed any more.
  • Tested successfully against the Javadoc APIs from both J2SE 1.4.2 and J2SE 1.5.0 Beta 2.
  • The CHM Table of Contents is generated as binary for performance purpose, but the icons used can only be the default one.
  • The CHM Table of Contents includes the methods (was limited to the Java classes until version 0.2).
  • Addition of the non public inner classes in the Table of Contents.
  • Light logging implementation.
  • The CHM files generated may be open on Linux with xCHM.

Installation

  1. Download either the python script package jd2chm_py_03.zip (10kB) or the executable package jd2chm_exe_03.zip (1MB).
  2. To install the script package, extract the 2 files from jd2chm_py_03.zip (10kB) and copy them into a directory included in your PATH.
  3. To install the script package, extract the executable file from jd2chm_exe_03.zip (1MB) and copy this file into a directory included in your PATH.

Usage

  • Open a command line in a Javadoc API directory.
  • Type jd2chm followed by ENTER.
  • Enter prompted informations, as in the following example:
C:\javadoc\beanshell>jd2chm
jd2chm Version 0.3
Copyright (c) 2000-2004 Andre Burgaud

http://www.burgaud.com

The project name will be given to:
- The HTML Help project files (.HHP, .HHK, .HHC)
- To the final CHM file
Enter the project name: bsh
The project title will be assign to the CHM window
Enter the project title: "Beanshell API"
[11-08-2005 14:21:44] INFO      Starts building the project
[11-08-2005 14:21:44] INFO      Project: bsh
[11-08-2005 14:21:44] INFO      Title: "Beanshell API"
...

Running the script with the option -h will display the usage.

Download

jd2chm_py_03.zip (10kB) Python script Jd2chm (requires Python 2.2 or greater).
jd2chm_exe_03.zip (1MB) Jd2chm in binary format (does not require Python to be installed on your machine).
jd2chm_doc.htm (12kB) Jd2chm 0.2 documentation (HTML format).
jd2chm.pdf (138kB) Jd2chm 0.2 documentation (PDF format).
jd2chm02.zip (125kB) Jd2chm Version 0.2
jd2chm01.zip (115kB) Jd2chm Version 0.1

Resources

如果读者喜欢原版的话可以参照上面的说明制作,不过另外xxli79将原版作了少少修改,修正了原版的一些bugs,该版本发布在csdn上,连接地址为:http://download.csdn.net/source/1024968

下面再度摘抄修改版作者的说明如下:

改造自jd2chm 0.3,这个软件好像从04年后就一直没有更新了,但是0.3版存在一些问题,从06年第一次出j2se1.5 api spec中文版的时候,俺自己动手改了改代码编译了一份chm,编译的chm和工具后来也就小范围流转,自己查阅的各方面javadoc我都会编译成 chm,比htm来得方便很多。

最近编译1.6的api spec,又更新了一下,感觉这东东还是挺不错的,因此干脆发布出来大家同乐乐吧。希望对搞java的兄弟有点用。
已知问题:对于UTF-8编码的中文javadoc,编译成chm后无法搜索中文。

纳米盘下载(1.4M):http://www.namipan.com/d/e2392071317bb45ecdcfc31b5de493248d68909ea4dc1600

另外编译好的1.6的api spec也可以从纳米盘下载,自己编译一次还是比较耗时间的。
中文(08年5月的,比官方发布的、网上流传的中文chm新):http://www.namipan.com/d/0afe8c540ce8ca604515779941c051d1003043910b667602
英文:http://www.namipan.com/d/88535dc749ee0b9319f9dab59ada0c2691fb7f0269925402

我改的内容:
============================================
v0.34
1、英文版的保持原始jd2chm版本带的CSS
2、中文版本的javadoc可选择使用雅黑

============================================

v0.33
1、可以不拷贝到临时目录
2、可以选择Language为中文:对于中文的javadoc,如果不能搜索中文,可以启用该参数试试
3、替换hhc文件的“<A[^>]+>([^<]+)</A>”为“\1”
4、替换hhc文件的“&nbsp;”为“ ”
5、默认doc字体设置为雅黑(css)
6、修正语言为非英文时,目录树字体难看的问题(-->Microsoft Sans Serif)
7、Interface节点换个书的图标,看得清楚些

============================================

v0.32
1、兼容性问题:有些Javadoc没有index-all.html

============================================

v0.31
1、增加启动参数 start_dir
2、增加选项,完成后删除临时文件
3、绿化hhc