HtmlDoc - A HTML Text-processor for Java Elements
PACKAGE:charite.christo.
PACKAGE:javax.swing.
PACKAGE:java.lang.
Note that the project is still in a very early state.!
Motivation:
The documentation of complex
applications contains references of GUI elements which need to be
kept up to date.
Problems evolve when the program source is changed and for example the label of a button is altered.
With every change in the source text the corresponding parts of the documentation need to be changed as well.
Tis is also true for screen-hardcopies within the documentation.
For smaller projects all citations of a GUI button can be changed
manually when the respective label text or the button functionality changes.
However, for more complex programs this is performed more effectively using HtmlDoc.
The HtmlDoc can also be used for HTML files describing Java code.
Implementation:
Special HTML expressions are inserted by the user.
These HTML expressions are replaced by this program and a
modified HTML file is generated.
The HTML expressions are enclosed in the tags for italics <i>.
Thus, the HTML code is syntactically valid before as well as after
processing.
The HTML expressions can refer to public variables and methods in Java
classes. Therefore these classes must be public and their
class files must be in the class path.
Parameters:
Four types of input parameters are allowed
- Class names:
This works only if class files and java files reside at the same place.
Each class is initiated using reflection.
and the program obtains the documentation of each class.
The documentation can be a file formed by replacing the file suffix ".class" by "Help.html".
Alternatively, the documentation can be enclosed in a /**HELP...*/ block in the java WIKI:Source_code.
- Java source files:
The program determines the class name, initiates the class and poceeds with the class as in the item before.
- HTML files:
The program will process the file and store the processed file in the destination directory.
Command line switches:
- -h or -help: Show help text.
- -log: Show log pane..
- -images=URL of images:
URL base where PNG images are stored. If set then images will be referenced by an absolute URL.
Otherwise images are referenced relatively.
Examples:
The following example command line processes this document.
java charite.christo.HtmlDocMain charite.christo.HtmlDocMain
Description of the special HTML expressions:
Note that the syntax for methods and fields is similar to the JDK javadoc tool.
After the class name a "#" sign preceedes the name of the method or variable.
A frequent mistake is to use a dot instead of "#".
- <i>STRING:a Java class#a field or method</i>:
The contents of the static field is inserted
into the HTML code:
<i>STRING:javax.swing.JFileChooser#APPROVE_SELECTION</i>
yields STRING:javax.swing.JFileChooser#APPROVE_SELECTION
<i>STRING:System#currentTimeMillis()</i>
yields STRING:System#currentTimeMillis()
- <i>INCLUDE_FILE:a text file</i>:The file
contents is inserted. The file name can be given as a variable or method. Example:
<i>INCLUDE_FILE:~/myDocument.txt</i>
The WIKI:Tilde designates the home path. WIKI:Slash and WIKI:Backslash are separators in file paths.
-
- <i>JCOMPONENT:a Java class#a field or method</i>:
This inserts a JComponent. It can be used for figures or a screen-shot.
The exclamation mark allows the user to interact with the GUI component.
<i>JCOMPONENT:new JFileChooser()!></i>
yields
JCOMPONENT:new JFileChooser()!
Without this exclamation mark one gets a still image:
JCOMPONENT:new JFileChooser()
- <i>CB:a Java class#a field or method</i>:
This creates a check-box.
<i>CB:System#currentTimeMillis()></i>
yields
CB:System#currentTimeMillis()
- <i>LABEL:a Java class#a field or method</i>:
This creates a JLabel with the specified String or Icon.
<i>LABEL:System#currentTimeMillis()></i>
yields
LABEL:System#currentTimeMillis()
- <i>PACKAGE:javax.swing.</i>:
Importing packages allows to use short class names. E.g JButton instead of javax.swing.JButton.
Currently the following tags are understood:
STRING_ARRAY:HtmlDoc#SPECIAL_HTML_TAG