JDK-4662945 : Broken link due to {@docroot} not processed in package pages
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 1.4.0
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • OS: windows_2000
  • CPU: x86
  • Submitted: 2002-04-04
  • Updated: 2014-05-05
  • Resolved: 2002-04-25
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
1.4.1 hopperFixed
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
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: hopper FIXED IN: hopper INTEGRATED IN: hopper
14-06-2004

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
04-04-2002