It appears that when a classpath contains two paths that begin with a tilde (~),
only the first path is recognized -- the second path is ignored and therefore a
"Package xxx not found in import" error is thrown

Tildes should be allowed in the classpath argument.

This bug is described in length at the Javadoc forum, "Package not found in import" at:
http://forum.java.sun.com/thread.jsp?forum=41&thread=241106

Here is the basic problem -- the jar files are under the home directory,
so the user naturally wants to use tildes to reach them:

% ls ~/cvs/pipeline/java/classes/xerces.jar ~/cvs/pipeline/java/classes/jh.jar
/nethome/users/qwang/cvs/pipeline/java/classes/jh.jar /nethome/users/qwang/cvs/pipeline/java/classes/xerces.jar

When using tildes, with JavaHelp jar file (jh.jar) as the second path in
classpath, it cannot be found:

% javadoc -d ~/cvs/pipeline/java/src/doc3 -classpath ~/cvs/pipeline/java/classes/xerces.jar:~/cvs/pipeline/java/classes/jh.jar -sourcepath ~/cvs/pipeline/java/src pipe pipe.adapter pipe.dialog pipe.form pipe.server
    Loading source files for package pipe...
    Loading source files for package pipe.adapter...
    Loading source files for package pipe.dialog...
    Loading source files for package pipe.form...
    Loading source files for package pipe.server...
    Constructing Javadoc information... /nethome/users/qwang/cvs/pipeline/java/src/pipe/form/PipeMenu.java:14: Package javax.help not found in import.
                        import javax.help.*;
                        ^

With Xerces jar file (xerces.jar) second, it likewise cannot be found,
but the first path can be found.

However, it works when "/nethome/users/qwang" is used instead of tilde:

% javadoc -d ~/cvs/pipeline/java/src/doc3 -classpath /nethome/users/qwang/cvs/pipeline/java/classes/jh.jar:/nethome/users/qwang/cvs/pipeline/java/classes/xerces.jar -sourcepath ~/cvs/pipeline/java/src pipe pipe.adapter pipe.dialog pipe.form pipe.server
     Loading source files for package pipe...
     Loading source files for package pipe.adapter...
     Loading source files for package pipe.dialog...
     Loading source files for package pipe.form...
     Loading source files for package pipe.server...
     Constructing Javadoc information...
     Building tree for all the packages and classes...
     Building index for all the packages and classes...
     Generating /nethome/users/qwang/cvs/pipeline/java/src/doc3/overview-tree.html...