JDK-4460354 : stddoclet: Broken link due to relative link <a href> in first sentence
  • Type: Bug
  • Status: Closed
  • Resolution: Fixed
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Affected Version: 1.3.0
  • OS: solaris_2.6
  • CPU: sparc
  • Submit Date: 2001-05-18
  • Updated Date: 2014-05-05
  • Resolved Date: 2005-01-11
Description
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.

Comments
CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: merlin-beta2 tiger FIXED IN: merlin-beta2 tiger INTEGRATED IN: tiger tiger-b22
2004-06-14

EVALUATION Will investigate and fix for 1.4 beta. jamie.ho@Eng 2001-05-23 This bug has now been fixed. I assume that if the link does not start with http: or file:, it is a relative link. Please correct me if I am wrong. Location of fix: HtmlStandardWriter.java jamie.ho@Eng 2001-05-30 This bug had to be fixed again in tiger. It broke during refactoring. ###@###.### 2003-09-23
2001-05-30

PUBLIC COMMENTS This bug has been fixed. The doclet now checks for broken relative links and fixes them by making them absolute links. jamie.ho@Eng 2001-05-30
2001-05-30