United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
Bug ID: JDK-4524350 REGRESSION: stddoclet: {@docRoot} inserts an extra "/"
JDK-4524350 : REGRESSION: stddoclet: {@docRoot} inserts an extra "/"

Details
Type:
Bug
Submit Date:
2001-11-07
Status:
Resolved
Updated Date:
2002-04-25
Project Name:
JDK
Resolved Date:
2002-04-25
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P2
Resolution:
Fixed
Affected Versions:
1.2.0,1.4.0
Fixed Versions:
1.4.1 (hopper)

Related Reports
Duplicate:

Sub Tasks

Description
Name: dk30142			Date: 11/07/2001

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?


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

                                    

Comments
EVALUATION

Yep, this is indeed a bug in Javadoc.
###@###.### 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/).
###@###.### 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".
###@###.### 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.
###@###.### 2001-12-19

Fixed for hopper.  Regression test is at 
<ws>/test/com/sun/javadoc/DocRootSlash/DocRootSlash.java
###@###.### 2002-04-20
                                     
2001-12-19
PUBLIC COMMENTS

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.
                                     
2004-06-10
WORK AROUND

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 
--------------------------------------------------------------------
                                     
2004-06-11
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
hopper

FIXED IN:
hopper

INTEGRATED IN:
hopper


                                     
2004-06-14



Hardware and Software, Engineered to Work Together