JUDE
USER'S
GUIDE
Thank you for participating in this beta test of Jude.
Please use the Report Bug and Request Enhancement features
in the Help menu of Jude to submit bug reports and enhancement
requests. Or, send your bugs, requests, and comments to:
Back to Top
Version 0.90 is a significant step forward from the Alpha 3 release.
New features include:
Back to Top
Back to Top
Back to Top
Back to Top
When you unpack jude.zip, it creates a directory
named jude090. This directory contains almost everything
you need to run Jude. The only other piece you will need is
the license file that is e-mailed to you when you register
to download jude. When you receive the e-mail message, save
it into this jude090 directory as a file with the
name jude.license. Jude will not run without this file!
Back to Top
There are three parts of the configuration file that must
be edited. Each is marked with the text "EDITME", and each
has comments explaining what must be edited.
The first line to be edited is the following:
The next edit you must make tells Jude where it can find
the class files for each of the versions of Java you have
installed. By default, the configuration file contains the
following lines:
The third line to be edited tells Jude where it can find
the source files for the most recent version of Java. This
line looks like this:
Note that it is possible to use Jude to document classes other than
those that comprise the standard Java API. Note the first line of the
jude.config file:
Back to Top
This program will read the class files for all versions of
Java listed in the jude.config file, and will read
the source files for the most recent version listed in that
file. It compresses the API information and javadoc
comments in those files into a single file named
java.jude. If you have Java 1.2
installed, the resulting file will be about 4 megabytes
long.
The data file generation program does a substantial
amount of work, and requires a substantial amount of time
and memory. You must have at least 128 megabytes of virtual
memory available. On a 400 Mhz Pentium system, you can
expect the program to run for five to fifteen minutes,
depending substantially on the speed of your Java VM. If
you have Sun's "hotspot" compiler available, I recommend its
use.
The data file generation program displays its progress as
it goes. It may also display errors and warnings (which it
also outputs to the file jude.log) as it progresses. If you
are using Java 1.3, you may see quite a few errors and
warnings. These result from the fact that Java 1.3 shipped
with some source files missing. The errors are benign: they
simply mean that for the methods of classes for which no
source code was available, argument names will not be available.
If you see any errors other than those described above,
you may not have properly configured the jude.config
file. If you find errors that you cannot fix by editing
this file, please let me know about them: judebug@davidflanagan.com.
Back to Top
It is important to understand that Jude.html must be a
file, not a HTTP URL on a web server, even a local web server. The
reason is that Jude requires random-access to its data file, which can
only be accomplished when the applet is run from the local hard disk (or
a local network drive) and cannot be done with the HTTP protocol. If
you are trying to install Jude for use by a workgroup, you should
install it on a networked fileserver that everyone has access to, or you
should allow everyone in the group to install a copy locally on their
hard drive. But you should not expect to be able to serve the
Jude.html file from your web server!
In addition to Jude.html, the Jude distribution also contains a
file named StartJude.html. This file contains a simple script
that opens a new window and starts Jude within that window. This new
window does not display all the Navigator chrome that is not necessary
when using Jude, and you may find that you prefer to run Jude in this
way. StartJude.html is particularly useful when bookmarked.
However, because of the way the StartJude.html script is written,
you must open the file in a fresh new browser window, or you will not
easily be able to create a bookmark to it.
Back to Top
Jude defines a number of navigation commands that allow you to move
among pages of documentation in ways other than by clicking links. The
commands are available from the Go menu, from buttons on the
toolbar, and as keyboard shortcuts. The Back and Forward
commands move backwards and forwards through the list of documentation
pages you've viewed. Note that you should not use Netscape's back and
forward buttons. The Top command makes Jude display the
top-level list of packages again. The Out command makes Jude
move from the current page "out" one level of abstraction to the next
outermost level of documentation. For example, if you are viewing the
documentation for String.indexOf(), the Out command will
take you to the documentation for String, and using it again will
take you to the list of classes in the java.lang package.
Finally, the Up command takes you up a level in the class
hierarchy to the documentation for the superclass of the currently
displayed class. For example, you are are viewing the documentation for
String, clicking Super will take you to the
documentation for Object.
Another way to navigate Jude is by searching. There are
several command for doing this; they are available from the
Search menu, from the toolbar, and as keyboard shortcuts. The
Go command allows you to jump directly to the documentation for
any named package, class, method, or field. This command is very useful
for those of us who prefer typing over clicking, clicking, clicking with
the mouse. The Search command allows you to enter a query and do
a full-text search on the documentation for all classes and members.
See the section on searching below for details.
Other commands allow you to do a "Find" and "Find again" on the text of
the currently displayed page. These two commands are simply a wrapper
around pre-existing browser functionality.
Finally, the menubar offers Sections, History,
Inheritance, and Containment menus that provide yet
another way to navigate. Sections allows you to jump among the
sections of the current page. The History menu allows you to
jump to pages you've previously visited. Inheritance and
Containment allow you to jump directly to related pages based on
the inheritance and containment hierarchies.
Back to Top
Introduction
Jude is a remarkable new Java documentation system. It
combines:
judebug@davidflanagan.com
Your comments and ideas will help to make Jude a better product!
New Features in version 0.90
There have been no incompatible changes to the Jude datafile generation
process or datafile format in this release. Thus, if you
already have a generated datafile, you can continue to use
it as is.
Requirements
In order to use Jude, you must:
Legal Matters
Jude was written by David Flanagan, and is Copyright ©
1996-2000 by David Flanagan. All rights reserved. Jude is
licensed software. Please read the file LICENSE.html.
Installation
Installing Jude is a three part process, explained in the
sections below.
Step 1: Unpack the distribution
Jude is distributed in a ZIP file named jude090.zip.
Since ZIP files and JAR files have the same format, you can
use the jar program to unpack it:
jar xf jude090.jar
Or, use any other program for manipulating JAR or ZIP files,
such as WinZIP.
Step 2: Edit the Configuration Files
One of the files in the jude090 directory is named
jude.config. You must edit this file to tell Jude
about the Java installation on your system. The information
you provide in this file will be used by Jude in the third
installation step below. If you have an earlier release of Jude, you
can usually copy the jude.config file from that release to this
one.
java.releases: 10, 11, 12
It specifies what versions of Java you have installed on
your system. You only need to have one version of Java
installed for Jude to work, but if you want it to accurately
tell you when every field, method, class, and package was
introduced into Java, it is best if you have the full set of
releases available. In any case, edit the line to specify
what versions you have. For example, if you had only Java
1.2 installed, you'd change the line to this:
java.releases: 12
Or, if you had both versions 1.1 and 1.2 installed:
java.releases: 11, 12
java.10.path: c:\\jdk1.0.2\\lib\\classes.zip
java.11.path: c:\\jdk1.1.8\\lib\\classes.zip
java.12.path: c:\\jdk1.2.2\\jre\\lib\\rt.jar
Note that the format of this configuration file requires
that you use double backslash characters as the directory
separator on Windows platforms. If you are running on a
Unix system, then you might edit the lines to look something
like this:
java.10.path: /usr/local/jdk1.0.2/lib/classes.zip
java.11.path: /usr/local/jdk1.1.7/lib/classes.zip
java.12.path: /usr/local/jdk1.2/jre/lib/rt.jar
java.sourcepath: c:\\jdk1.2.2\\src.jar
If you are running on Unix system, you might edit to
something like this:
java.sourcepath: /usr/local/jdk1.2/src.jar
If you've installed Sun's beta version of Java 1.3, you may also want to
include that release in your jude.config file.
apis: java
You can edit this line to list any number of apis other than the
standard Java api. For example:
apis: java, jini
For each API named on this line, you must define properties that are
analogous to the java.* properties described above. For
example, you might set these properties to tell Jude where to find
information about the Jini API:
jini.releases: 10
jini.10.path: ...jini classpath here...
jini.sourcepath: ...jini sourcepath here...
Step 3: Generate the Data File
Jude reads all the information and documentation it needs
from a single large data file. Because the data file
contains the (highly compressed) contents of Sun's javadoc
documentation, Sun does not allow me to distribute it with
Jude. This means that you must generate the data file for
your own system before you can run Jude.
The jude directory contains two scripts for
generating the data file. If you are on a Windows platform,
open a MS-DOS window and run the script extract.bat:
c:\jude> extract
If you are on a Unix system, use the script extract.sh:
% ./extract.sh
If neither of these scripts works for you, you can run the
data file generation program "manually" with a command
something like this:
cd jude
java -mx128m -classpath jude.jar com.davidflanagan.jude.Extract jude.config
Running Jude
Once you have installed Jude and generated the data file it
requires, you can start using it. Because Jude displays
Java documentation in HTML form, it runs as an applet inside
of a web browser. To use it, simply load the file
Jude.html into Netscape Navigator version 4.5 or
later (but not Netscape 6!). Jude does not (at least not
currently) work in Microsoft's Internet Explorer, or with Mozilla.
Navigating
When Jude starts up it spends some time reading information
from the data file, and then displays a list of hyperlinked
package names. If you click on the name of a package, you
will be shown a list of hyperlinked class names that are
part of that package. Click on a class name to see a list
of the methods and fields in that class, arranged in the
quick-reference style of Java in a Nutshell. Along
with this class synopsis, you will also see the javadoc
documentation for the class. Finally, If you click on the
name of a method or field, you will see details, and javadoc
documentation for the method or field.
Keyboard Shortcuts
One of the most important features of Jude, and the feature
that sets it apart from other documentation browser systems
is its keyboard shortcuts and searching capabilities. I
hate using the mouse and have tried to make Jude easy to
operate from the keyboard.
The following table lists the keyboard commands recognized
by Jude:
| Key | Function |
|---|---|
| F1 | Display Help |
| B | Back to previously viewed page |
| F | Forward; opposite of Back |
| T | Top: display the top-level package list |
| O | Out to Container: move out the containment hierarchy |
| U | Up to Superclass: move up the inheritance hierarchy |
| M | Show/Hide More information about the current link |
| G | Go: display named package, class, or member |
| S | Search: Full-text query (described below) |
| Alt-F, Ctrl-F | Find in current page |
| Alt-G, Ctrl-G | Find Again in current page |
| Y | Jump to Synopsis section |
| D | Jump to Description section |
| H | Jump to Hierarchy section |
| P | Jump to JavaBeans Properties section |
| X | Jump to Cross References (xrefs) section |
| Home | Jump to top of page |
| End | Jump to end of page |
| Alt-F4 | Close Window |
| Alt-W, Ctrl-W | Close Window |
| Alt-N, Ctrl-N | Open New Window |
| Alt-P, Ctrl-P | |
| Shift+Up | Scroll to previous section |
| Shift+Down | Scroll to next section |
| PageUp, PageDown | scroll |
| Up, Down | scroll |
Back to Top
The Go command is a kind of "index search". In addition to
this command, Jude also supports full-text searching with the
Search command, and the S keyboard shortcut. The Jude
data file contains a full-text index of all the javadoc documentation it
contains. If you have ever searched the internet with a search engine
like AltaVista, you know how to use a full-text index. Jude's full-text
query syntax is in fact inspired by the syntax used by AltaVista.
When you type one or more words to search for Jude finds
all documents that contain one or more of those words, and
arranges them in order according to how well they matched.
This means that documents that match more of your words will
typically be listed first. If a word is prefixed with the
'+' character, then it is required. All search results will
contain that word. If a word is prefixed with a '-'
character, then that word will not appear in any of the
returned search results. A word may be followed by a '*'
character to specify that they should match any word that
they are a prefix of.
Words in a full-text query may also be prefixed by
modifiers that specify where they may be matched. Use
"name:" to specify that a word must match the name of the
class, method or field. Use "description:" to specify that
the match must occur in the description. Use "arguments:"
to specify that the match must occur in description of a
method argument, and use "returns:" to specify that the
match must occur in the Returns section of a method
description.
Searching
Perhaps the most powerful feature of Jude is its interactive searching
capability. Type the G key (for the Go command), and Jude
prompts you to enter a string. If you enter the unique name of a
package, class, method, or field, Jude displays the documentation for it
immediately. If there is more than one match for your search string,
Jude displays a list of hyperlinked matches. Using this feature is
often the easiest way to navigate from class to class. It is often
easier to type the name of a class than it is to use the mouse to
navigate there.