Hi Jon,
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.
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.
--Semyon
On 11/14/2017 09:16 AM, Jonathan Gibbons wrote:
Semyon,
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.
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.
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.
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.
-- Jon
On 10/25/17 6:31 PM, Semyon Sadetsky wrote:
Hi Jonathan,
On 10/24/2017 03:20 PM, Jonathan Gibbons wrote:
Semyon,
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.
You probably meant 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 fragment identifiers except for <a> element there must be
bugs reported that which will be fixed soon.
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.
--Semyon
[1] https://www.w3schools.com/html/html_links.asp
[2] http://www.html5-tutorials.org/html-basics/links/
[3] https://www.w3.org/TR/html5/browsers.html#scroll-to-fragid
-- Jon
On 10/23/2017 10:08 PM, Semyon Sadetsky wrote:
Hi Sergey,
I see no reason to have an extra empty anchor tag to set a
bookmark. The id attribute works with any element.
For example:
<a id="Definitions"></a>
<h3>Definitions</h3>
should be
<h3 id="Definitions">Definitions</h3>
--Semyon
On 10/23/2017 02:42 PM, Sergey Bylokhov wrote:
Hello,
Please review the fix for.
8182410: missing 'title' in
api/javax/swing/plaf/synth/doc-files/componentProperties.html
8183508: multi_tsc.html should be updated
8181289: Invalid HTML 5 in AWT/Swing docs
Description:
- Illegal characters were removed.
- Unsupported tags/properties were removed -like <tt>, <center>,
font, etc.(except the tags related to tables which I'll fix later).
- HTML5 doctype is set for all files.
- The <title> is set for all files.
- <a name="" is replaced by <a id=""
Why you replace
- Copyrights were added to some files.
Note that I placed a <head> tag before copyright to solve errors
like:
"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"
specdiff:
http://cr.openjdk.java.net/~serb/8181289/specdiff/overview-summary.html
Bugs:
https://bugs.openjdk.java.net/browse/JDK-8182410
https://bugs.openjdk.java.net/browse/JDK-8183508
https://bugs.openjdk.java.net/browse/JDK-8181289
Webrev can be found at:
http://cr.openjdk.java.net/~serb/8181289/webrev.00