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) 
======================================================================

N/A

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

  Broken link due to {@docroot} not processed in package pages

 xxxxx@xxxxx  2002-04-04

Fixed for hopper by adding a warning that this tag is unknown but
another tag exists that differs only by case.
 xxxxx@xxxxx  2002-04-21