Javadoc To HTML Help
Version 0.2
(jd2chm.py)

André Burgaud
andre@burgaud.com


ANDRE BURGAUD OPEN SOURCE LICENSE, VERSION 1.0
For jd2chm.py

Copyright © 2000 Andre Burgaud. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. 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.
  3. 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.
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.


1   Overview

"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:

3   Changes

3.1   Version 0.2 - 07-18-2001

3.2   Version 0.1 - 10-22-2000

4   Requirements

In order to use jd2chm.py you will need to install the following software 1:

5   Installation

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:

C:\>jd2chm.py
===========================================================
      Javadoc To Compiled HTML Help (jd2chm) v0.2
          Copyright (c) 2000 Andre Burgaud
===========================================================

===========================================================
Usage:
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   Usage

6.1   Javadoc Documentation

  1. Generate the Javadoc Documentation from your Java source code (refer to the Java 2 SDK Documentation for more details).
  2. 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:
  3. Run the HTML Help compiler. To run it from the command line, the compiler should be in the PATH:

    C:\>hhc myProject.hhp
    Microsoft HTML Help Compiler 4.74.8702
    
    Compiling e:\myProject\docs\api\myProject.chm
    
    Compile time: 0 minutes, 11 seconds
    352     Topics
    4,304   Local links
    106     Internet links
    0       Graphics
    
    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.

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.

7   SciTE

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.
if PLAT_WIN
  command.help.*.java=$(CurrentWord)!e:\doc\jdk13.chm
  command.help.subsystem.*.java=4
(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.

8   Links

Here is a list of the links you may access to download products described in this document:

9   Java Documentation Redistribution

To know more about the Java Documentation Redistribution Policy, visit
http://www.javasoft.com/docs/redist.html.

1
Refer to the "Links" section to get alternative web sites
2
Optional: if you want to use the Java context sensitive help with SciTE

This document was translated from LATEX by HEVEA.