If someone hard-codes a relative link <a href> in the
first sentence of a package, class or member description,
that link will be broken when that sentence is copied
to a page that resides in any other directory.

The first sentence can be copied to files in two different
directories: a class-use directory and to the index-files
directory. The first sentence of a package can also
be copied to the overview-summary.html file.
(However, the first sentence of a class or member
description is copied to the class or member summary,
respectively, but those files reside in the same directory,
so do not cause broken links.)

For example, the first sentence of a class description
is copied to a class-use page. If it contained a relative
hyperlink, it would be a broken link in the class-use page.

Specifically, here's an example sentence in Charset.html
(where link is not broken):

   Unchecked exception thrown when a string that is not a
   <a href="Charset.html#names">legal charset name</a> is used as such.

This link is broken where it appears in this file:

file://localhost/java/pubs/linkCheckDocSet/jdk1.4/docs/api/java/lang/class-use/RuntimeException.html#java.nio.charset
 

One workaround would be to use {@docroot} so that the link is
not relative to the current directory:

   Unchecked exception thrown when a string that is not a
   <a href="{@docroot}/java/nio/charset/Charset.html#names">legal
   charset name</a> is used as such.

A better solution would be to fix this in the doclet so it uses
a different relative path depending in which directory the
sentence appears. So in this case, it would generate (I believe):

   Unchecked exception thrown when a string that is not a
   <a href="../../../java/nio/charset/Charset.html#names">legal
   charset name</a> is used as such.

when this sentence appears in the java/lang/class-use directory.