Javadoc To HTML Help
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
ANDRE BURGAUD OPEN SOURCE LICENSE, VERSION 1.0
Copyright © 2000 Andre Burgaud. All rights reserved.
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL ANDRE BURGAUD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by André Burgaud http://www.burgaud.com."
Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
"Javadoc To CHM" (jd2chm.py) is a Python script that generates Microsoft HTML Help projects files from a Javadoc documentation.
2 Jd2chm Package
The Jd2chm package contains 3 files:
jd2chm.py "Javadoc To CHM" Python script.
- jd2chm.pdf Current documentation.
- compile.bat Windows batch file that calls the Jd2chm script and the Hhc compiler (modify the variables to fit your project).
3.1 Version 0.2 - 07-18-2001
Handles single package Javadoc
- An Interface icon allows distinction between a Class and an Interface in the table of content
- The overview documentation is available when the All Classes node is selected
- The package documentation is available when the node corresponding to a package is selected (no more viewed as a distinct individual topic)
- File compile.cmd changed to compile.bat
- Minor bugs correction
3.2 Version 0.1 - 10-22-2000
In order to use jd2chm.py you will need to install the following software 1:
If you have already installed the required products (Python, Java 2 SDK and Microsoft HTML Help),
copy jd2chm.py into a directory in your PATH. To test jd2chm.py, type jd2chm.py at the command line:
Javadoc To Compiled HTML Help (jd2chm) v0.2
Copyright (c) 2000 Andre Burgaud
jd2chm.py [-h] [-p project_name -t doc_title]
-h : displays usage
-p project_name : builds a CHM project_name
-p doc_title : title of the final documentation
6.1 Javadoc Documentation
Generate the Javadoc Documentation from your Java source code (refer to the Java 2 SDK Documentation for more details).
- In the Javadoc directory, run jd2chm.py with the -p and -t options. The -p option is followed by the name of the project.
The -t will have the title as argument (don't forget to enclose the string with quotes especially if there are whitespaces). Example:
C:\>jd2chm.py -p myProject -t "Title of myProject v 1.0"
This will generate 3 files:
The project file (myProject.hhp)
- The contents file (myProject.hhc)
- The index file (myProject.hhk)
- Run the HTML Help compiler. To run it from the command line, the compiler should be in the PATH:
Microsoft HTML Help Compiler 4.74.8702
Compile time: 0 minutes, 11 seconds
4,304 Local links
106 Internet links
Created e:\myProject\docs\api\myProject.chm, 198,396 bytes
Compression decreased file by 1,184,565 bytes.
6.2 Java API Documentation
You will be able to compile almost any standard generated Javadoc documentations, including the Java API Documentation.
In order to compile the JDK API documentation successfully, you should perform the following additional step before generating the compiled HTML project files:
You will generate the project files and compile the project from this temporary directory.
Due to the size of the JDK API Javadoc (about 100 Mb), and the number of files (more than 4600), you have to be patient during the compilation.
It takes about 10 mn to generate the project files and about 15 mn to compile on a Celeron 466 with 128Mb of RAM.
The result CHM file is about 16Mb.
Copy the entire api directory and subdirectories in a temporary directory to isolate the files from the other JDK documents.
The api directory is located under the docs directory in your JDK_HOME.
Example: if your JDK_HOME is c:\jdk1.3, the API Javadoc is c:\jdk1.3\docs\api.
During the compilation you will have many warnings due to the tags that hhc.exe can't process.
The jd2chm script saves the default CSS file (stylesheet.css) and replaces it by a custom one.
If you want to prevent the style sheet file to be changed, set the variable CUSTOM_CSS to 0.
Except for the cascading style sheet file that may be replaced, no other file is modified.
The result file gives you a fastest access to the whole Java API Specification, including a complete index and an advanced search system.
Furthermore, as a companion of SciTE you may have a Java context sensitive help (see SciTE section).
6.3 Quick Build
To speed up the process of generating project files and compiling with hhc.exe, you can directly use the command file (compile.bat) provided in the package and modify the variables.
Copy this file in your Javadoc directory, then run it from the command line. It will call respectively jd2chm and hhc.exe.
To download the source editor SciTE, visit http://www.scintilla.org.
SciTE is a powerful and flexible source editor that lets you customizing many commands.
Below is an example to associate a context sensitive help for Java files.
After building your personal copy of the compiled Java help file (described above), add these three lines in the cpp.properties file located in your SciTE direcory.
(Considering that the CHM file you generated is located in e:\doc\jdk13.chm)
With this customization, when you edit a Java file, the Java Help pops up if you press the F1 key. It also displays the help index with the word selected in your Java source file.
Here is a list of the links you may access to download products described in this document:
- Microsoft MSDN
9 Java Documentation Redistribution
To know more about the Java Documentation Redistribution Policy, visit
- Refer to the "Links" section to get alternative web sites
- Optional: if you want to use the Java context sensitive help with SciTE
This document was translated from LATEX by