The {@docRoot} tag mistakenly interprets to a value with a trailing 
slash (/).  In previous releases it included no trailing slash.  This 
extra slash causes the URL to be broken if there was already a slash
following {@docRoot}.  The workaround is for you to remove
any slash immediately following {@docRoot} from the doc comment.
This bug will be fixed in a future release.

The Javadoc spec for java.lang.Thread contains several links to 
the threadPrimitiveDeprecation.html file at 
j2se/1.4/docs/guide/misc/threadPrimitive.html.
An example of such a link is the one in the spec for the resume method:

http://java.sun.com/j2se/1.4/docs/api/java/lang/Thread.html#resume()

However, these links are broken in 1.4, though they aren't broken in 
the 1.3.1 spec.  In both 1.4 and 1.3.1, the HTML in the Javadoc comment 
looks like this:

<a href="{@docRoot}/../guide/misc/threadPrimitiveDeprecation.html">Why 
are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.

In 1.3 the output looks like:
<a href="../../../guide/misc/threadPrimitiveDeprecation.html">Why 
are Thread.stop, Thread.suspend and Thread.resume Deprecated?</a>.

But in 1.4 the output looks like:

<A href="../..//../guide/misc/threadPrimitiveDeprecation.html">Why 
are Thread.stop, Thread.suspend and Thread.resume Deprecated?</A>.

I'm wondering if the fact that the same tag produces broken links in 
1.4 but not in 1.3.1 means that there's a bug in the 1.4 Javadoc?  Or 
can you see some other reason that's causing the broken links?


======================================================================

We have two workarounds -- programs that you run on the HTML files to correct for the extra slash.  One program uses Perl, the other uses a Sun internal utility called LinkFix (a Java program for fixing links).

The Perl program:
--------------------------------------------------------------------
#!/bin/ksh

# This script deletes all extra slashes inserted into the HTML files due to 
# a bug in {@docRoot}.  It is designed to correct only the errors found in 
# Merlin 1.4.0 API docs.  (There were found to be no errors in the API docs
# saved under the guide directory.)

# To run, execute:
#
# % /home/dkramer/javadoc/1.4/fixdocroot-perl.sh

# Duplicate scripts below that do nothing extra are commented out with '# DUPE'

# Start in the api directory
cd /java/pubs/ws/dkramer-merlin-tl/build/solaris-sparc/doc/api

perl -pi.bak -e 's|../../..//../guide/imf/spec.html|../../../../guide/imf/spec.html|' java/awt/im/package-summary.html
perl -pi.bak -e 's|../../..//../guide/imf/api-reference.html|../../../../guide/imf/api-reference.html|' java/awt/im/package-summary.html
perl -pi.bak -e 's|../../..//../guide/imf/overview.html|../../../../guide/imf/overview.html|' java/awt/im/package-summary.html
perl -pi.bak -e 's|../../..//../guide/imf/api-tutorial.html|../../../../guide/imf/api-tutorial.html|' java/awt/im/package-summary.html
\rm -rf java/awt/im/package-summary.html.bak

perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' java/io/class-use/IOException.html
# DUPE perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' java/io/class-use/IOException.html
\rm -rf java/io/IOException.html.bak

perl -pi.bak -e 's|../..//java/util/regex/Pattern.html|../../java/util/regex/Pattern.html|' java/lang/String.html
# DUPE perl -pi.bak -e 's|../..//java/util/regex/Pattern.html|../../java/util/regex/Pattern.html|' java/lang/String.html
# DUPE perl -pi.bak -e 's|../..//java/util/regex/Pattern.html|../../java/util/regex/Pattern.html|' java/lang/String.html
# DUPE perl -pi.bak -e 's|../..//java/util/regex/Pattern.html|../../java/util/regex/Pattern.html|' java/lang/String.html
\rm -rf java/lang/String.html.bak

perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 
# DUPE perl -pi.bak -e 's|../..//../guide/misc/threadPrimitiveDeprecation.html|../../../guide/misc/threadPrimitiveDeprecation.html|' java/lang/Thread.html 

perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|'  java/lang/class-use/ClassNotFoundException.html
\rm -rf java/lang/class-use/ClassNotFoundException.html.bak

perl -pi.bak -e 's|../..//../guide/jdbc/getstart/GettingStartedTOC.fm.html|../../../guide/jdbc/getstart/GettingStartedTOC.fm.html|' java/sql/package-summary.html
\rm -rf java/sql/package-summary.html.bak

perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' javax/rmi/CORBA/StubDelegate.html
# DUPE perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' javax/rmi/CORBA/StubDelegate.html
# DUPE perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' javax/rmi/CORBA/StubDelegate.html
# DUPE perl -pi.bak -e 's|../../..//serialized-form.html|../../../serialized-form.html|' javax/rmi/CORBA/StubDelegate.html
\rm -rf javax/rmi/CORBA/StubDelegate.html.bak

perl -pi.bak -e 's|../../..//../guide/idl/GShome.html|../../../../guide/idl/GShome.html|' org/omg/CORBA/package-summary.html
perl -pi.bak -e 's|../../..//../guide/idl/jidlExceptions.html|../../../../guide/idl/jidlExceptions.html|' org/omg/CORBA/package-summary.html
perl -pi.bak -e 's|../../..//../guide/idl/jidlExample.html|../../../../guide/idl/jidlExample.html|' org/omg/CORBA/package-summary.html
perl -pi.bak -e 's|../../..//../guide/idl/index.html|../../../../guide/idl/index.html|' org/omg/CORBA/package-summary.html
\rm -rf org/omg/CORBA/package-summary.html.bak

perl -pi.bak -e 's|..//serialized-form.html|../serialized-form.html|' index-files/index-18.html
perl -pi.bak -e 's|..//../guide/misc/threadPrimitiveDeprecation.html|../../guide/misc/threadPrimitiveDeprecation.html|' index-files/index-18.html
\rm -rf index-files/index-18.html.bak

perl -pi.bak -e 's|..//java/util/regex/Pattern.html|../java/util/regex/Pattern.html|' index-files/index-19.html
# DUPE perl -pi.bak -e 's|..//java/util/regex/Pattern.html|../java/util/regex/Pattern.html|' index-files/index-19.html
perl -pi.bak -e 's|..//../guide/misc/threadPrimitiveDeprecation.html|../../guide/misc/threadPrimitiveDeprecation.html|' index-files/index-19.html
# DUPE perl -pi.bak -e 's|..//../guide/misc/threadPrimitiveDeprecation.html|../../guide/misc/threadPrimitiveDeprecation.html|' index-files/index-19.html
# DUPE perl -pi.bak -e 's|..//../guide/misc/threadPrimitiveDeprecation.html|../../guide/misc/threadPrimitiveDeprecation.html|' index-files/index-19.html
\rm -rf index-files/index-19.html.bak

perl -pi.bak -e 's|..//serialized-form.html|../serialized-form.html|' index-files/index-23.html
\rm -rf index-files/index-23.html.bak
--------------------------------------------------------------------

The LinkFix program:
--------------------------------------------------------------------
/java/re/jdk/1.4.0/nightly/binaries/solsparc/latest/bin/java   -classpath /java/pubs/lib/linkfix/classes LinkFix   -path /java/pubs/ws/dkramer-merlin-tl/build/solaris-sparc/doc/api/   -changeTarget '([^:])//' '$1/'    -ignore SCCS   -recurse 
--------------------------------------------------------------------

Yep, this is indeed a bug in Javadoc.
  xxxxx@xxxxx   2001-11-19

Because this bug was not approved to be fixed for Merlin, I will try 
to fix the generated HTML for Merlin by post-processing the HTML
with linkfix (in /java/pubs/lib/).
  xxxxx@xxxxx   2001-12-05

I wrote a perl script to fix the broken links present in the 1.4.0 API docs.
This script is located in "workaround".
  xxxxx@xxxxx   2001-12-19

I notice that while all links from {@docRoot} have an extra slash,
both Netscape and Internet Explorer are forgiving (goes to the
correct page) when the extra slash is followed by a directory or 
file name:

   <a href="../../..//serialized-form.html#javax.rmi.CORBA.Stub">

but not forgiving when followed by dots:

   <a href="../..//../guide/misc/threadPrimitiveDeprecation.html">

The former occurs when linking to pages under the 
doc root (the root of the api docs), while the latter 
occurs when linking to pages outside the api doc hierarchy.
Therefore, broken links are noticed only when linking outside
the api doc hierarchy.
  xxxxx@xxxxx   2001-12-19

Fixed for hopper.  Regression test is at 
<ws>/test/com/sun/javadoc/DocRootSlash/DocRootSlash.java
  xxxxx@xxxxx   2002-04-20