Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Martin, I've worked with Bhavesh to sort out these issues. The inconsistency in the syntax has been fixed. The CSS could be more compact ... if we did not have to deal with nested tables. It was also a goal to simplify the use for the doc comment author, such that it was possible to put just one class definition on the tag, and not have to make additional declarations on the tags within the table. Our experiments showed that when we did not fully specify the structure, it was possible for the details of one style to "leak" into another when a table of one style was nested in another table of a different style. At this point, the goal is to introduce the class names, and to have CSS that works well enough across the major browsers. If someone wants to suggest more concise CSS that works well in all our uses cases, that would be a fine RFE for a future release. -- Jon On 5/10/17 7:10 PM, Martin Buchholz wrote: Looks good. --- I suspect there's some way to specify the styles more compactly, but I don't know enough css to say. --- +table.borderless thead tr th, table.borderless tbody tr th, table.borderless tr th, +table.plain > thead > tr > th, table.plain > tbody > tr > th, table.plain > tr > th, I was surprised at the difference in syntax; why the ">" in one but not the other?
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Looks good. --- I suspect there's some way to specify the styles more compactly, but I don't know enough css to say. --- +table.borderless thead tr th, table.borderless tbody tr th, table.borderless tr th, +table.plain > thead > tr > th, table.plain > tbody > tr > th, table.plain > tr > th, I was surprised at the difference in syntax; why the ">" in one but not the other?
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Looks good. Mandy > On May 10, 2017, at 5:36 PM, Jonathan Gibbons > wrote: > > Mandy, > > I have fixed the tables you noted. > > jdk (changes to java.base): > http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.02/ > > API showing the effect of these changes: > http://cr.openjdk.java.net/~jjg/8179479-8179592/api.02/java.base-summary.html > > -- Jon
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Mandy, I have fixed the tables you noted. jdk (changes to java.base): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.02/ API showing the effect of these changes: http://cr.openjdk.java.net/~jjg/8179479-8179592/api.02/java.base-summary.html -- Jon On 05/10/2017 03:50 PM, Mandy Chung wrote: On May 5, 2017, at 3:52 PM, Jonathan Gibbons wrote: This is an updated review for the changes to improve tables in java.base. : Webrevs: langtools (the stylesheet): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/ jdk (changes to java.base): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/ API showing the combined effect of these cahnges: http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html The new style class names are better. I reviewed the javadoc changes in java.base. Mostly looks good. A few table without an explicit class and FileSystemProvider should use striped class table. src/java.base/share/classes/java/nio/file/spi/FileSystemProvider.java - * + * src/java.base/share/classes/java/nio/charset/Charset.java + * + * + * + * + *
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
> On May 5, 2017, at 3:52 PM, Jonathan Gibbons > wrote: > > This is an updated review for the changes to improve tables in java.base. > : > Webrevs: > > langtools (the stylesheet): > http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/ > > jdk (changes to java.base): > http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/ > > API showing the combined effect of these cahnges: > http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html > The new style class names are better. I reviewed the javadoc changes in java.base. Mostly looks good. A few table without an explicit class and FileSystemProvider should use striped class table. src/java.base/share/classes/java/nio/file/spi/FileSystemProvider.java - * + * src/java.base/share/classes/java/nio/charset/Charset.java + * + * + * + * + *
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Kumar, The nature of CSS is such that there is generally no one single definition. The descriptive comments are just before the shared/common parts of the definitions. If I grouped the comment and class definition, someone else would point out that I could be sharing common properties. The better long term solution is a separate document, with examples. -- Jon On 05/08/2017 03:12 PM, Kumar Srinivasan wrote: Hi Jon, I looked at the stylesheet can the descriptive comments for each of the classes be moved closer to the class itself, ie. just before the definition ? Kumar This is an updated review for the changes to improve tables in java.base. The changes incorporate earlier review feedback, and also address a problem that was discovered with nested tables. The summary of the set of changes since the previous round is: * A new style class is added for borderless tables, to be used in preference to a table tag with no class. * The style classes are now named: borderless plain striped The longer form using a suffix `-table` was considered, but generally, there should not be so many style classes that such a level of discrimination is needed. The names `borderless` and `striped` are most likely to only apply to tables anyway, and `plain` could reasonably be used for other elements without conflict. * Comments are added to the stylesheet regarding these new classes, as a placeholder until a better specification for the styles in these stylesheets is created. * Within java.base, all uses of the `altrows` class have been updated to use `striped`, and tables with no class attribute have been changed to explicitly use `borderless`. Webrevs: langtools (the stylesheet): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/ jdk (changes to java.base): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/ API showing the combined effect of these cahnges: http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html -- Jon On 05/03/2017 03:06 PM, Jonathan Gibbons wrote: This is a review request for two co-dependent fixes. JDK-8179592: Update tables in java.base to be HTML 5-friendly. JDK-8179479: Add new styles to enable HTML 5 tables In doc comments, some of the HTML 4.01 attributes for tables are no longer available in HTML 5, and CSS should be used instead. To this end, some updates have been made to the main/default stylesheet used by javadoc, to define two new CSS classes for tables. The new classes are: Just puts plain borders around each cell, with no background coloring. Horizontal borders are not used between cells in the table body; instead, alternating backgrounds are used to help distinguish the separate rows. In addition, there is still the default No borders. These styles are in the langtools webrev, here: http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev/ The changes to the doc comments in java.base are in the jdk webrev, here: http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev/ summary vs. The ARIA recommendations are to use the summary attribute or tag ... but the summary attribute is no longer allowed in HTML 5. In general, the text that has been provided for a summary is not suitable for direct use as a caption. The temporary workaround is to use a caption that is not displayed. In time, the appropriate API owners should update the use of these undisplayed table captions, to modify the text of the caption and make the caption displayed (by removing style="display:none"). Doc comments were changed in files in the following packages: java.io java.lang java.lang.invoke java.lang.reflect java.math java.net java.nio.channels java.nio.charset java.nio.file java.nio.file.attribute java.nio.file.spi java.security java.security.cert java.text java.time.chrono java.time.format java.time.temporal java.util java.util.concurrent java.util.regex java.util.spi javax.net.ssl The intent is that the only changes in this webrev are to the HTML 5 markup. There should be no significant changes to the text in any doc comment. The decision to add the styles to the default stylesheet at this late stage in the release is not taken lightly, and is seen as a temporary measure. JDK-8177283 is a wishlist enhancement for updates to javadoc support of stylesheets, which includes the desire to move JDK-specific styles to a JDK-specific stylesheet. This review is primarily about continuing the ongoing effort to make our docs be HTML 5 compliant. I would prefer not to get into extended discussions about which style class to use for each table, and what the exact definition of the styleclasses should be at this time. But appropriate review feedback is obviously welcome. -- Jon
Re: RFR: [Updated] Update tables in java.base to be HTML5-friendly.
Hi Jon, I looked at the stylesheet can the descriptive comments for each of the classes be moved closer to the class itself, ie. just before the definition ? Kumar This is an updated review for the changes to improve tables in java.base. The changes incorporate earlier review feedback, and also address a problem that was discovered with nested tables. The summary of the set of changes since the previous round is: * A new style class is added for borderless tables, to be used in preference to a table tag with no class. * The style classes are now named: borderless plain striped The longer form using a suffix `-table` was considered, but generally, there should not be so many style classes that such a level of discrimination is needed. The names `borderless` and `striped` are most likely to only apply to tables anyway, and `plain` could reasonably be used for other elements without conflict. * Comments are added to the stylesheet regarding these new classes, as a placeholder until a better specification for the styles in these stylesheets is created. * Within java.base, all uses of the `altrows` class have been updated to use `striped`, and tables with no class attribute have been changed to explicitly use `borderless`. Webrevs: langtools (the stylesheet): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev.01/ jdk (changes to java.base): http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev.01/ API showing the combined effect of these cahnges: http://cr.openjdk.java.net/~jjg/8179479-8179592/api.01/java.base-summary.html -- Jon On 05/03/2017 03:06 PM, Jonathan Gibbons wrote: This is a review request for two co-dependent fixes. JDK-8179592: Update tables in java.base to be HTML 5-friendly. JDK-8179479: Add new styles to enable HTML 5 tables In doc comments, some of the HTML 4.01 attributes for tables are no longer available in HTML 5, and CSS should be used instead. To this end, some updates have been made to the main/default stylesheet used by javadoc, to define two new CSS classes for tables. The new classes are: Just puts plain borders around each cell, with no background coloring. Horizontal borders are not used between cells in the table body; instead, alternating backgrounds are used to help distinguish the separate rows. In addition, there is still the default No borders. These styles are in the langtools webrev, here: http://cr.openjdk.java.net/~jjg/8179479-8179592/8179479/webrev/ The changes to the doc comments in java.base are in the jdk webrev, here: http://cr.openjdk.java.net/~jjg/8179479-8179592/8179592/webrev/ summary vs. The ARIA recommendations are to use the summary attribute or tag ... but the summary attribute is no longer allowed in HTML 5. In general, the text that has been provided for a summary is not suitable for direct use as a caption. The temporary workaround is to use a caption that is not displayed. In time, the appropriate API owners should update the use of these undisplayed table captions, to modify the text of the caption and make the caption displayed (by removing style="display:none"). Doc comments were changed in files in the following packages: java.io java.lang java.lang.invoke java.lang.reflect java.math java.net java.nio.channels java.nio.charset java.nio.file java.nio.file.attribute java.nio.file.spi java.security java.security.cert java.text java.time.chrono java.time.format java.time.temporal java.util java.util.concurrent java.util.regex java.util.spi javax.net.ssl The intent is that the only changes in this webrev are to the HTML 5 markup. There should be no significant changes to the text in any doc comment. The decision to add the styles to the default stylesheet at this late stage in the release is not taken lightly, and is seen as a temporary measure. JDK-8177283 is a wishlist enhancement for updates to javadoc support of stylesheets, which includes the desire to move JDK-specific styles to a JDK-specific stylesheet. This review is primarily about continuing the ongoing effort to make our docs be HTML 5 compliant. I would prefer not to get into extended discussions about which style class to use for each table, and what the exact definition of the styleclasses should be at this time. But appropriate review feedback is obviously welcome. -- Jon
