<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  </head>
  <body text="#000000" bgcolor="#FFFFFF">
    > The current changes get my "+1" as comformant HTML5.<br>
    <br>
    This is not true.  The empty <a> tags produce warnings in
    HTML5 validator:<br>
    <br>
<a class="moz-txt-link-freetext" href="https://validator.w3.org/nu/?doc=http%3A%2F%2Fcr.openjdk.java.net%2F~ssadetsky%2F8181289%2Fjdoc%2FmodB-summary.html">https://validator.w3.org/nu/?doc=http%3A%2F%2Fcr.openjdk.java.net%2F~ssadetsky%2F8181289%2Fjdoc%2FmodB-summary.html</a><br>
    <br>
    <br>
    <blockquote type="cite"
      cite="mid:113a7a2e-fcf3-e609-6ddf-576aa4118fa4@oracle.com"> <br>
      -phil.<br>
      <br>
      <div class="moz-cite-prefix">On 11/22/2017 07:58 PM, Jonathan
        Gibbons wrote:<br>
      </div>
      <blockquote type="cite"
        cite="mid:05fd5d7d-2a07-5446-2386-2b4800075ad0@oracle.com">
        <meta http-equiv="Content-Type" content="text/html;
          charset=utf-8">
        <p>Semyon,</p>
        <p>You may indeed have explained why the behavior as it is, but
          we cannot and should not link this review with changes to the
          javadoc stylesheets, when the specific changes in the review
          are gratuitous and not necessary in the first place.</p>
        <p>Yes, we may separately, and later, look at how the javadoc
          manages the header. Until then, I recommend that we stay
          within guidelines that are fully conformant HTML5, and without
          visual issues with the existing stylesheet. </p>
        <p>So, I want to end this back and forth. I've spent enough time
          on this. I've given my review feedback, which remains to not
          introduce changes which may cause visual issues. If you and
          the  AWT team want to proceed with those changes, I'm done.</p>
        -- Jon<br>
        <br>
        <div class="moz-cite-prefix">On 11/22/17 7:46 PM, Semyon
          Sadetsky wrote:<br>
        </div>
        <blockquote type="cite"
          cite="mid:12d20f64-a74c-0771-3cee-2be7b1406af1@oracle.com">
          <meta http-equiv="Content-Type" content="text/html;
            charset=utf-8">
          <p>Jon,</p>
          <p>This is because you have fixed page header. For me it works
            equally in all browsers. I see no discrepancy between Chrome
            and Firefox on my Linux platform. I believe that the
            stylesheet.css you have in those examples does the magic :</p>
          <p>a[name]:before, a[name]:target, a[id]:before, a[id]:target
            {<br>
                content: "";<br>
                display: inline-block;<br>
                position: relative;<br>
                padding-top: 129px;<br>
                margin-top: -129px;<br>
            }</p>
          <p>so nothing specific comes from browser or "<a id=" it is
            just a special margin/padding is set for a[id] as I suspect
            at the beginning. This css rule is well known solution for
            the problem.<br>
          </p>
          <p>I think the next link may help you</p>
          <p><a class="moz-txt-link-freetext"
href="http://nicolasgallagher.com/jump-links-and-viewport-positioning/demo/"
              moz-do-not-send="true">http://nicolasgallagher.com/jump-links-and-viewport-positioning/demo/</a></p>
          <p>--Semyon<br>
          </p>
          <br>
          <div class="moz-cite-prefix">On 11/22/2017 02:53 PM, Jonathan
            Gibbons wrote:<br>
          </div>
          <blockquote type="cite" cite="mid:5A15FFF8.6070102@oracle.com">
            <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 class="moz-txt-link-freetext"
href="http://cr.openjdk.java.net/%7Ejjg/semyon/api/overview-summary.html"
              moz-do-not-send="true">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>
          </blockquote>
          <br>
        </blockquote>
        <br>
      </blockquote>
      <br>
    </blockquote>
    <br>
  </body>
</html>