<html>
  <head>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    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 class="moz-txt-link-freetext" href="http://cr.openjdk.java.net/~jjg/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-variant-ligatures: normal;
            font-variant-caps: 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; -webkit-text-stroke-width:
            0px; background-color: rgb(255, 255, 255);
            text-decoration-style: initial; text-decoration-color:
            initial; 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-variant-ligatures: normal;
            font-variant-caps: 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; -webkit-text-stroke-width:
            0px; background-color: rgb(255, 255, 255);
            text-decoration-style: initial; text-decoration-color:
            initial; display: inline !important; float: none;"><span
              style="color: rgb(0, 0, 0); font-family: Verdana,
              sans-serif; font-size: 15px; font-style: normal;
              font-variant-ligatures: normal; font-variant-caps: 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;
              -webkit-text-stroke-width: 0px; background-color: rgb(255,
              255, 255); text-decoration-style: initial;
              text-decoration-color: initial; 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>
  </body>
</html>