Name: nt126004 Date: 03/12/2002


FULL PRODUCT VERSION :
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 :
SunOS dakota 5.8 Generic_108528-11 sun4u sparc SUNW,Ultra-5_10

ADDITIONAL OPERATING SYSTEMS :
Should be OS-independent


A DESCRIPTION OF THE PROBLEM :
The -breakiterator semantics don't work properly when a
relative path is used in an HTML anchor that appears in the
first sentence of a package-level comment. If the relative
path contains a leading '.' or '..' directory qualifier,
then the first '.' gets treated as a sentence-ending
character by the BreakIterator. The result is an unclosed
<a>nchor, which causes formatting problems in the overview
summary table and in the package summary brief description.

The problem does not exist if absolute links are used, but
that's not an option when you're trying to link to some
other document in the Javadoc tree.

REGRESSION. Last worked in version 1.3.1

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Create a "package.html" file in an existing package
directory, if necessary.
2. In the first sentence, include a raw HTML link to, say,
the package class tree (<a
href="./package-tree.html">package tree</a>).
3. Run javadoc v. 1.4 with the -breakiterator switch. (Note:
if you turn off the -breakiterator switch, and don't have
-quiet on, then you'll see the breakiterator warning that
tells you how the first sentence would have been different
if -breakiterator had been used. It's easy to see that the
-breakiterator version is quite wrong.)
4. Look at the generated Javadocs. On the overview summary
page, the table of package names and first sentences will be
malformed (in Communicator 4.x, at least) because the
particular package's first sentence contains an unclosed
<a>nchor.
5. Look at the package summary page for the particular
package. The first sentence of the package comment will
contain all of the text that came before the first '.' in
the Javadoc comment, followed abruptly on the same line by
the "Description" anchor, which is a broken link.

EXPECTED VERSUS ACTUAL BEHAVIOR :
The BreakIterator should understand the '.' and '..'
directory semantics when used in <a>nchors, at the very
least. Right now, it correctly handles absolute paths (so it
-does- understand that the '.' before a file extension isn't
a sentence-ender). Better still would be to have
BreakIterator ignore HTML anchor paths altogether.

This bug can be reproduced always.

---------- BEGIN SOURCE ----------
(see "Description" and "Steps to Reproduce", above)
---------- END SOURCE ----------

CUSTOMER WORKAROUND :
Don't use the -breakiterator switch until it's fixed. I
can't use absolute paths in my package-level comments,
because I can't know in advance where the files will be
installed.
(Review ID: 143467)
======================================================================
From duplicate 4623506:

/**
 * Class for <a href="../bar/baz.html#bingo">bar</a>.
 */
public class Foo {
}

The new sentence mistakenly stops at the dots denoting parent directory ".."
From an HTML perspective, it should be clear that the periods
in question are embedded inside an HTML tag, and therefore cannot
reasonably be considered to mark the end of a sentence. The
assertion that the next major release will consider them to
mark the end of a sentence implies, to me, that the next major
release will not understand what constitutes an HTML tag, that
is, will not understand how to parse HTML correctly.