<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html;charset=UTF-8" http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
I can confirm the same behavior that Jon sees with Firefox 57 on
Windows 7.<br>
<br>
The link scrolls to the right place with the <a id="..."> link
and does not with the <h1 id="..."> link.<br>
<br>
-- Kevin<br>
<br>
<br>
Jonathan Gibbons wrote:
<blockquote cite="mid:5A1602AB.3060600@oracle.com" type="cite">
  <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
Semyon,<br>
  <br>
Using the files I previously posted, I confirm that I see the same
display problem on a Mac, using the latest OS (High Sierra) and Safari.
I also see the problem on the same Mac, with Firefox 55.0.2<br>
  <br>
-- Jon<br>
  <br>
  <div class="moz-cite-prefix">On 11/22/2017 02:53 PM, Jonathan Gibbons
wrote:<br>
  </div>
  <blockquote cite="mid:5A15FFF8.6070102@oracle.com" type="cite">
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
Semyon,<br>
    <br>
I have reconstructed a very simple, very artificial example to demo the
bug.   This example uses lots of filler text, but while that is
artificial, for sake of recreating a demo,  note that the problem first
appeared, for real, in real JDK 9 API documentation with extended doc
comments, and that as a result, we followed the advice I have been
trying to give you.<br>
    <br>
See the toy API bundle here: <br>
    <a moz-do-not-send="true" class="moz-txt-link-freetext"
 href="http://cr.openjdk.java.net/%7Ejjg/semyon/api/overview-summary.html">http://cr.openjdk.java.net/~jjg/semyon/api/overview-summary.html</a><br>
    <br>
There are two modules, modA and modB.  Both have huge long doc
comments, with a heading at the top and a link at the bottom.<br>
    <br>
In modA, the anchor is of the form <h1 id="head">.  In modB, the
anchor is of the form <a id="head">.<br>
    <br>
In each of these files, scroll to the end of the comment, and look for
a link, called "link", at the bottom of the page.  In both cases, the
page scrolls so that the heading is near the top of the browser window,
but in one case it is hidden under the javadoc navbar, and in the other
case, it is clearly visible, below the javadoc navbar.<br>
    <br>
This is the difference in behavior that I can been trying to describe
to you. I'm using Ubuntu 14.04 with Firefox 38, but I'm not the only
one to have seen this effect.  I don't know whether you will get the
same effect in your browser, but the fact that there is a reasonable
OS/browser combo that demonstrates the problem is enough of a reason to
avoid provoking the problem unnecessarily.   If you don't see the
problem on your browser, but want to see it in mine, I see you are in
SCA22, so drop by my office for a demo.<br>
    <br>
I'll leave it to the AWT team to decide what to do about this
bug/review. I still recommend updating what is necessary to fix issues,
and not otherwise changing the doc comments unnecessarily, and not
changing them in a way to provoke this bad behavior.<br>
    <br>
-- Jon<br>
    <br>
    <br>
    <br>
    <br>
    <div class="moz-cite-prefix">On 11/22/2017 12:10 PM, Semyon
Sadetsky wrote:<br>
    </div>
    <blockquote
 cite="mid:f583dfbf-08fc-15c3-b8f3-44370b3f6f34@oracle.com" type="cite">
      <meta http-equiv="Content-Type"
 content="text/html;
          charset=utf-8">
      <p>Hi Jon,</p>
      <p>This is not only about HTML5 spec, I also hardly can find
resources that follow your "<a id=" rule. And I doubt that
cross-browser compatibility is important for Javadoc only and others do
not care about their readers. So, I asked you for an examples of such
workaround or a reference to a bug filed against any browser. Fragment
identifiers is too important functionality to let this issue be
unnoticeable. <br>
      </p>
      <p>You are correct that there is no bug here. But a bug was
absent  before this fix as well. This bug is about following to the
HTML5 standards, so let's follow them in full and not to return to this
once again. We have a good chance to provide documentation in clean
HTML5 after the fix without any workarounds. <br>
      </p>
      <p>--Semyon<br>
      </p>
      <div class="moz-cite-prefix">On 11/14/2017 09:16 AM, Jonathan
Gibbons wrote:<br>
      </div>
      <blockquote type="cite"
 cite="mid:827bf9b6-d57b-bf1f-d7b1-f6d0afa7456d@oracle.com">
        <meta http-equiv="Content-Type"
 content="text/html;
            charset=utf-8">
        <p>Semyon,</p>
        <p>I read the HTML 5 spec the same as you, and we (on the
Javadoc team) started using id on other elements, as well as <a>
to provide a target that could be linked to.</p>
        <p>However, the pragmatic experience was that the scrolling in
some browsers did not completely reveal the element when there was a
layered z component involved: the target element sometimes ended up
under that layered component. Our experience was that the behavior was
fixed when the target identifier was in an <a> element.<br>
        </p>
        <p>So, yes, you can follow the rules, and suggest that it is OK
to put id on any element, and use it as a fragment identifier in a
link, as given in the spec. Or you can be nice to your readers, and
workaround what is probably a display bug in some browsers.</p>
        <p>In the case of this review, you were suggesting additional
"cleanup" on code that worked. Since there was no bug involved, and
thus no inherent need to fix the code, my review feedback is to leave
the code alone.  You may choose to insist differently, and I cannot say
that what you are suggesting is against the spec; I can just say that
we can seen cases where such changes leads to bad visual effects.</p>
        <p>-- Jon<br>
        </p>
        <br>
        <div class="moz-cite-prefix">On 10/25/17 6:31 PM, Semyon
Sadetsky wrote:<br>
        </div>
        <blockquote type="cite"
 cite="mid:fa57e431-e6a6-8f32-d7c9-517df18725ab@oracle.com">
          <meta http-equiv="Content-Type"
 content="text/html;
              charset=utf-8">
          <p>Hi Jonathan,</p>
          <br>
          <div class="moz-cite-prefix">On 10/24/2017 03:20 PM, Jonathan
Gibbons wrote:<br>
          </div>
          <blockquote type="cite" cite="mid:59EFBCA5.3090402@oracle.com">
            <br>
Semyon, <br>
            <br>
Although id is a global attribute and can be used to identify any node,
some browsers do better navigation/scrolling when the id is in an
<a> tag.  We have seen poor autoscrolling behavior when the id is
an a header tag, such that the header ends up obscured under the
navigation bar at the top of the page. <br>
          </blockquote>
You probably meant <span
 style="color: rgb(0, 0, 0); font-family: Verdana,sans-serif; font-size: 15px; font-style: normal; font-weight: normal; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; background-color: rgb(255, 255, 255); display: inline ! important; float: none;">heading
elements, because "header tag" is something different. Do you have any
references those issues reports? Because in html5 the fragment
identifiers are the only correct way to have internal document
bookmarks [1] [2]. If some browsers do not navigate to </span><span
 style="color: rgb(0, 0, 0); font-family: Verdana,sans-serif; font-size: 15px; font-style: normal; font-weight: normal; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; background-color: rgb(255, 255, 255); display: inline ! important; float: none;"><span
 style="color: rgb(0, 0, 0); font-family: Verdana,sans-serif; font-size: 15px; font-style: normal; font-weight: normal; letter-spacing: normal; orphans: 2; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; background-color: rgb(255, 255, 255); display: inline ! important; float: none;">fragment
identifiers</span> except for <a> element there must be bugs
reported that  which will be fixed soon.<br>
The html5 specification is very specific about navigating to the
fragment identifier [3]. So, there should no be difference between
navigating to "<a id=" or to any other element having id attribute.
If you just need an extra vertical space above header you could use css
style or <p>, but usage of <a> as an upper margin seems odd
since it is a special tag. <br>
          <br>
--Semyon<br>
          <br>
[1] <a class="moz-txt-link-freetext"
 href="https://www.w3schools.com/html/html_links.asp"
 moz-do-not-send="true">https://www.w3schools.com/html/html_links.asp</a><br>
[2] <a class="moz-txt-link-freetext"
 href="http://www.html5-tutorials.org/html-basics/links/"
 moz-do-not-send="true">http://www.html5-tutorials.org/html-basics/links/</a><br>
[3] <a class="moz-txt-link-freetext"
 href="https://www.w3.org/TR/html5/browsers.html#scroll-to-fragid"
 moz-do-not-send="true">https://www.w3.org/TR/html5/browsers.html#scroll-to-fragid</a><br>
          <br>
          </span>
          <blockquote type="cite" cite="mid:59EFBCA5.3090402@oracle.com">
            <br>
-- Jon <br>
            <br>
            <br>
On 10/23/2017 10:08 PM, Semyon Sadetsky wrote: <br>
            <blockquote type="cite">Hi Sergey, <br>
              <br>
I see no reason to have an extra empty anchor tag to set a bookmark.
The id attribute works with any element. <br>
              <br>
For example: <br>
              <br>
    <a id="Definitions"></a> <br>
    <h3>Definitions</h3> <br>
              <br>
should be <br>
              <br>
    <h3 id="Definitions">Definitions</h3> <br>
              <br>
--Semyon <br>
              <br>
On 10/23/2017 02:42 PM, Sergey Bylokhov wrote: <br>
              <blockquote type="cite"> <br>
Hello, <br>
Please review the fix for. <br>
8182410: missing 'title' in
api/javax/swing/plaf/synth/doc-files/componentProperties.html <br>
8183508: multi_tsc.html should be updated <br>
8181289: Invalid HTML 5 in AWT/Swing docs <br>
                <br>
Description: <br>
 - Illegal characters were removed. <br>
 - Unsupported tags/properties were removed -like <tt>,
<center>, font, etc.(except the tags related to tables which I'll
fix later). <br>
 - HTML5 doctype is set for all files. <br>
 - The <title> is set for all files. <br>
 - <a name="" is replaced by <a id="" <br>
              </blockquote>
Why you replace <br>
              <br>
              <blockquote type="cite"> - Copyrights were added to some
files. <br>
                <br>
Note that I placed a <head> tag before copyright to solve errors
like: <br>
"A charset attribute on a meta element found after the first 1024
bytes. Fatal Error: Changing encoding at this point would need
non-streamable behavior" <br>
                <br>
specdiff: <a class="moz-txt-link-freetext"
 href="http://cr.openjdk.java.net/%7Eserb/8181289/specdiff/overview-summary.html"
 moz-do-not-send="true">http://cr.openjdk.java.net/~serb/8181289/specdiff/overview-summary.html</a>
                <br>
                <br>
Bugs: <br>
    <a class="moz-txt-link-freetext"
 href="https://bugs.openjdk.java.net/browse/JDK-8182410"
 moz-do-not-send="true">https://bugs.openjdk.java.net/browse/JDK-8182410</a>
                <br>
    <a class="moz-txt-link-freetext"
 href="https://bugs.openjdk.java.net/browse/JDK-8183508"
 moz-do-not-send="true">https://bugs.openjdk.java.net/browse/JDK-8183508</a>
                <br>
    <a class="moz-txt-link-freetext"
 href="https://bugs.openjdk.java.net/browse/JDK-8181289"
 moz-do-not-send="true">https://bugs.openjdk.java.net/browse/JDK-8181289</a>
                <br>
                <br>
Webrev can be found at: <a class="moz-txt-link-freetext"
 href="http://cr.openjdk.java.net/%7Eserb/8181289/webrev.00"
 moz-do-not-send="true">http://cr.openjdk.java.net/~serb/8181289/webrev.00</a>
                <br>
                <br>
              </blockquote>
              <br>
            </blockquote>
            <br>
          </blockquote>
          <br>
        </blockquote>
        <br>
      </blockquote>
      <br>
    </blockquote>
    <br>
  </blockquote>
  <br>
</blockquote>
</body>
</html>