Java HotSpot(TM) Client VM (build 1.4.0-beta2-b77, mixed mode)

To summarize the problem:
    A  hard-coded anchor tag <A HREF="xx">ABC</A> located in the 
    first sentence of a class comment may be truncated when it appears
    on the package-summary.html page.  Because the truncation occurs
    before the trailing quote ("), it can swallow the following text.
      xxxxx@xxxxx   2002-01-03

Original description:

Javadoc generates a bad package-summary.html

Package-summary.html contains html errors. To reproduce the problem, you should: 
- create a JbcDateTimeChooser.java file in the current directory (source code
below)
- create the following subdirectories : md .\docs\api\jbc\beans
- execute the javadoc program.

---------------------------Command line
md .\docs\api\jbc\beans

del .\docs\api\*.html
del .\docs\api\jbc\beans\*.html

javadoc -public -author -version -d .\docs\api -footer "<b><a
Href="http://www.JBCSolutions.com/">JBCSolutions</a> - JbcBeans</b> v1.0"
-bottom "<b><a Href="http://www.JBCSolutions.com/">JBCSolutions</a> -
JbcBeans</b> v1.0" -windowtitle "JBCSolutions - JbcBeans v1.0 - API
specification" -doctitle "<b>JbcBeans</b> v1.0" -header "<b><a
Href="http://www.JBCSolutions.com/">JBCSolutions</a> - JbcBeans</b> v1.0<p>This
document is the API specification for the JbcBeans, version 1.0. "
.\JbcDateTimeChooser.java
-----------------------------Output

////////////////////////////////////////////////////////////////////////////////
//////////////
Java HotSpot(TM) Client VM (build 1.4.0-beta2-b77, mixed mode)

Loading source file .\JbcDateTimeChooser.java...
Constructing Javadoc information...
Standard Doclet version 1.4 beta (04 Aug 2001)

Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating .\docs\api\overview-tree.html...
Generating .\docs\api\index-all.html...
Generating .\docs\api\deprecated-list.html...
Building index for all classes...
Generating .\docs\api\allclasses-frame.html...
Generating .\docs\api\allclasses-noframe.html...
Generating .\docs\api\index.html...
Generating .\docs\api\packages.html...
Generating .\docs\api\jbc\beans\package-frame.html...
Generating .\docs\api\jbc\beans\package-summary.html...
Generating .\docs\api\jbc\beans\package-tree.html...
Generating .\docs\api\jbc\beans\JbcDateTimeChooser.html...
Generating .\docs\api\serialized-form.html...
Generating .\docs\api\package-list...
Generating .\docs\api\help-doc.html...
Generating .\docs\api\stylesheet.css...
////////////////////////////////////////////////////////////////////////////////
//////////////

Generated html code\docs\api\jbc\beans\package-summary.html
The ?????????????? show the wrong html code, where a leading 
quote (") appears in "Src" but a trailing quote never appears.

Best regards,
Jean-Bernard

<!-- =========== END OF NAVBAR =========== -->
<HR>
<H2>
Package jbc.beans
</H2>

<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=2><FONT SIZE="+2">
<B>Class Summary</B></FONT></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A
HREF="JbcDateTimeChooser.html">JbcDateTimeChooser</A></B></TD>
<TD><Img Border=1 Src="../../..</TD>
??????????????????????????????????????????????????
</TR>
</TABLE>
?

<P>
<HR>
<!-- ========== START OF NAVBAR ========== -->



********************************************************************************
*
************************    JbcDateTimeChooser.java
***************************
********************************************************************************
*
package jbc.beans;

import java.awt.*;

/*
 *
 * Copyright 1999-2001 JBC. All Rights Reserved.
 * Author Jean-Bernard Clerin
 *
 * This software is the proprietary information of JBC.
 * Use is subject to license terms.
 *
 */

/**
 * <p><center><Img Border=1 Src="../../../JbcDateTimeChooser.jpg"></Center><p>
 *
 * With this bean, the user may choose a date and hours, minutes,
 * seconds, in a user-friendly environment.<Br>
 *
 * @author Copyright ? 1999-2001, JBC. All Rights Reserved.<br>
 * <a href="../../../license.html">Licensed Materials - Property of JBC</a>.
 * @version 1.0
 */
public class JbcDateTimeChooser extends JComponent
   {
    /**
     * Default JbcDateTimeChooser constructor. <B>BlaBlaBla</B>.
     * <p>Creates a <code>JbcDateTimeChooser</code> instance.
     */
    public JbcDateTimeChooser()
       {
       }

    /**
     * <B>BlaBlaBla</B>.
     */
    public void BlaBlaBla(String title)
       {
       }
   }
(Review ID: 134833) 
======================================================================

N/A

Could be user error due to nesting double-quotes in -header.  I'll write
him to find out.
  xxxxx@xxxxx   2001-11-13



It appears to me the following bug is due to using nested
quotes (") in the javadoc command.

Please try putting single quotes around all arguments that contain
double quotes, such as the -footer argument and let me know if 
that fixes it.

-Doug

..............

The problem is not with the quotes.  See the attachment mentioned 
in the comment -- it clarifies the problem.  It boils down to the
following.  

If a hard-coded, relative <A HREF> anchor appears in the first sentence 
of a doc comment, javadoc must adjust its path to work when that sentence
appears on the package-summary.html page (and index page).
The routine to do this appears to work (somewhat) for a target file 
named "18.doc.html" but not for "doc.html".

This doc comment with "18.doc.html" produces good results:

/**
   * This is "Summary Sentence", respects the "Documentation Comments",
   * for more information :
   * <a href="../../18.doc.html#25979">see CHAPTER 18</a>.
   */

Good results in package-summary.html page:
  
   <TD>This is "Summary Sentence", respects the "Documentation Comments",
   for more information :
   <a href="../../\jbc\beans\../../18.doc.html#25979">see CHAPTER 18</a>.</TD>

(Notice the backslashes should be forward slashes)

................

This doc comment with "doc.html" produces bad results:

  /**
   * This is "Summary Sentence", respects the "Documentation Comments",
   * for more information :
   * <a href="../../doc.html#25979">see CHAPTER 18</a>.
   */

Bad results:

   <TD>This is "Summary Sentence", respects the "Documentation Comments",
   for more information :
   <a href="../..</TD>

In these examples, a source filename is passed into javadoc:

 C:> javadoc JbcDateTimeChooser.java

  xxxxx@xxxxx   2002-01-03

Changing synopsis from:
   Generates package-summary.html with a missing end-quote

   1st sentence <A HREF> truncated in package-summary.html

Am re-opening this until the submitter can no longer reproduce the bug.
Notice this bug might be a problem only on Windows, which the submitter
is using.

  xxxxx@xxxxx   2002-04-13

................................
Jean-Bernard replied:

I am pleased to hear from you. Attached the copy I sent to
CAP-feedback. By the way, Ingrid Yao just sent me an output
with warning messages. I do not get this type of output. I have
checked again and again with 1.4.0 and 1.4.1-B6, I still get the
same error. I cannot understand, it is too for me, I just give up.
Thanks for your help anyway.

Bug Description:
Re: 4523891 Javadoc generates a bad package-summary.html

Note: While controlling the tracking of bugs I posted for 1.4., I saw that
one of the bugs (4523891) I posted had been closed because
"not reproducible". It's quite crazy : I spent a lot of time and energy
to this issue with the Sun staff to focus and demonstrate this bug
(see the last email I got from Doug Kramer). Consequently I post it
for the last time. Up to you now!

Javadoc 1.4 implements a new feature, i.e. generation of a
package-summary.html file. Sometime, the code generated in this file
is in error (a tag is started but not ended). Consequently, it depends on
the browser you are using to read the documentation : if you are using
Netscape 4.x, the page is empty ; if you are using Internet Explorer,
the page is messed up, more the documentation is trunked.

To highlight the wrong code I have used a html page, emphasizing in
red what is wrong, in green what is right. Please unzip the file
(doc4523891.zip) attached and look at the index.html using your browser.

Steps to Reproduce (be specific):
- Run javadoc JbcDateTimeChooser2.java
- Edit and look with a text editor  jbc\beans\package-summary.html
at the line 78 you will see the wrong tag   <a href="../..</TD>

- In the source code, change the sixth line for
 * <a href="../../18.doc.html#25979">see CHAPTER 18</a>.
- Run javadoc JbcDateTimeChooser2.java
- Edit and look with a text editor  jbc\beans\package-summary.html
- Then, you will see a right tag.
If you want more information, have a look to file attached
(doc4523891.zip).

----------------- JbcDateTimeChooser2.java----------------------
package jbc.beans;
import java.lang.*;
 /**
  * This is "Summary Sentence", respects the "Documentation Comments",
  * for more information :
  * <a href="../../doc.html#25979">see CHAPTER 18</a>.
  */
 public class JbcDateTimeChooser2 extends Object
    {
    }

Best regards,
Jean-Bernard Clerin <  xxxxx@xxxxx  >

When I try this test that fails for Jean-Bernard, it succeeds for
me using Windows 2000, JDK 1.4.0 (which is build b92)

<TD>This is "Summary Sentence", respects the "Documentation Comments",
 for more information :
 <a href="../../\jbc\beans\../../doc.html#25979">see CHAPTER 18</a>.</TD>

I can click on the link shown in my results and it goes to that document 
and anchor.  The link is not broken, despite the double slash "/\". 
We should fix this "/\" anyway.

I am puzzled why we get different results.
  xxxxx@xxxxx   2002-04-13

I just noticed the results are different with uppercase or lowercase
"a href".

/**
 * Here is a link from C1 to the 
 *
 * <a href="../package-list">(a href) package-list</A>
 *
 * Here is a link from C1 to the 
 * <A HREF="../package-list">(A HREF) package-list</A>  
 */
public class C1 {
}

I get this result, which makes no changes for uppercase HREF
but introduces an error for lowercase href:

 Here is a link from C1 to the 
 <a href="../p1/t">(a href) pac">(a href) package-list</A>
             ^^^^   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
               |         |
       wrong path    should be: (a href) package-list

 Here is a link from C1 to the 
 <A HREF="../package-list">(A HREF) package-list</A>  

  xxxxx@xxxxx   2002-04-13

NOTE: I re-tested this same source files with both 1.4.0
and 1.4.1-beta-b13, and they tested fine -- I could not 
reproduce those results.
........................

New information on how relative links are handled internally:

This developer is not using {@docRoot}, yet the first sentence
is modified by the doclet.  This undocumented behavior should 
be documented once this bug is fixed.  The doclet is designed so that
when it encounters a hard-coded reference WITHOUT {@docRoot} 
(in any sentence?), it inserts {@docRoot} ahead of the relative
link.  Therefore, this link:

  <a href="../../18.doc.html#25979">see CHAPTER 18</a>.

becomes this internally:
  <a href="{@docRoot}/../../18.doc.html#25979">see CHAPTER 18</a>.

before being expanded to:
  <a href="../../jbc/beans/../../18.doc.html#25979">see CHAPTER 18</a>.

This works fine for me with 1.4.0.  

However, upon further investigation, if I put two of these links
into the first sentence, then the second one is corrupted:

  <a href="../p1/tml#25979">see CHAPTER ">see CHAPTER 18 (18.doc.html)</a>.

This is still not the result the submitter sees, but it similar.

  xxxxx@xxxxx   2002-04-22

This might be fixed in 1.4.1 in the TL workspace as of April 22, 2002
for build b11, as it might be related to this bug which has been fixed:
4638015: javadoc terminates with StringIndexOutOfBoundsException
I've asked Jean-Bernard to test it and report back.
  xxxxx@xxxxx   2002-04-22

...........................

Date: Fri, 24 May 2002 19:22:30 +0200

Subject: Re: CAP Bug Submission Form (4) - javadoc problem

Hello,

As Doug Kramer asked me, I tested the problem again with
(build 1.4.1-beta-b12, mixed mode). As for me, the problem
is still there. I want to be precise that it is not a serious problem
for me anymore as I have removed what was causing trouble
from my documentation.

Best regards,
Jean-Bernard

  xxxxx@xxxxx   2002-05-24

............................
After spending vast amounts of time on this bug, I could never
reproduce it, either, in any version, although the submitter
still can.  It may be a language-dependent bug that we cannot
pinpoint without the submitter's further help.
I concur with Jamie's closing it out.

  xxxxx@xxxxx   2002-05-26