United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4662945 : Broken link due to {@docroot} not processed in package pages

Details
Type:
Bug
Submit Date:
2002-04-04
Status:
Resolved
Updated Date:
2002-04-25
Project Name:
JDK
Resolved Date:
2002-04-25
Component:
docs
OS:
windows_2000
Sub-Component:
doclet
CPU:
x86
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.1 (hopper)

Related Reports

Sub Tasks

Description

Name: nt126004			Date: 04/04/2002


FULL PRODUCT VERSION :
java version "1.4.0"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.4.0-b92)
Java HotSpot(TM) Client VM (build 1.4.0-b92, mixed mode)

FULL OPERATING SYSTEM VERSION :
Microsoft Windows 2000 [Version 5.00.2195]

A DESCRIPTION OF THE PROBLEM :
This is not fixed by Bug Id 4460354.

Cannot use standard approaches to create a link to the
#package_description bookmark in the first sentence of a
package-summary.html ("package") page, such that the link
works both from the package page and the overview-
summary.html ("overview") page.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. In the first sentence of a package.html page, try the
syntax described in the Source Code section below.
2.
3.

EXPECTED VERSUS ACTUAL BEHAVIOR :
Expected: Relative link to bookmark on package page should
work both from that package page and from the overview page.

Actual: Depending on which syntax you use, one or the other
ends up broken.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
I have tried a few approaches:
-----------
(1) Works on package-summary.html page, but tries to point to a local bookmark
when it appears on the overview-summary.html page:

<a href="#package_description">complete description</a>
This is not fixed by Bug Id 4460354.

-----------
(2) Works on package-summary.html page, but not when link appears on overview-
summary.html page:

<a href="package-summary.html#package_description">complete description</a>
This is not fixed by Bug Id 4460354.

-----------
(3) Works on package-summary.html page, but not when link appears on overview-
summary.html page:

<a href="{@docroot}package-summary.html#package_description">complete
description</a> of this package.

-----------
(4) OPPOSITE: Works when link appears on overview-summary.html page, but not on
package-summary.html page:

Click the <a href="{@docroot}com/mydomain/mypackage/package-
summary.html#package_description">complete description</a> of this package.

-----------
(5) This syntax does not work at all:
{@link com.mydomain.mypackage#package_description}
---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Write the URL so it will be relative when it appears on the
overview page, and then use JavaScript to rewrite it on the
package page:
<a href="{@docroot}com/mydomain/mypackage/package-
summary.html#package_description"
onclick="this.href=adjustPath()">complete description</a>

<script language="JavaScript"><!--
/* Rewrites bookmark to be relative to this package page.
   Do not put this script into the HEAD element,
   as anything we put in there seems to be ignored by
   javadoc.
*/
   function adjustPath() {
      return "#package_description";
   }
// --></script>
(Review ID: 144814) 
======================================================================

                                    

Comments
EVALUATION

Case 3 is nearly the proper way to do this.  Here's the corrected example:

<A HREF="{@docroot}p/package-summary.html#package_description">complete description</A>

However, when I run 1.4.0, I get this warning

./p/package.html: warning - @docroot is an unknown tag.

and {@docroot} is replaced with a slash "/".

The bug is that {@docroot} is not processed properly in package pages.

BTW, even if you get this to work, the first sentence is copied to the 
description (ahead of the rest of the description), so it would appear a bit confusing.  

We have a request in to add an option to put the description ahead of 
the list of packages.  Perhaps that would help you.

Changed synopsis from:
  Broken link due to relative link to bookmark in first sentence of package
to:
  Broken link due to {@docroot} not processed in package pages

###@###.### 2002-04-04

Fixed for hopper by adding a warning that this tag is unknown but
another tag exists that differs only by case.
###@###.### 2002-04-21
                                     
2002-04-04
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