Re: RFR: Update tables in java.base to be HTML5-friendly.

[Jonathan Gibbons]

On 5/3/17 7:49 PM, Martin Buchholz wrote:


---

Yes, "striped" is a much better name than "altrows".  "striped-tables" 
as you suggest may be better. Choose your names carefully - we can't 
change them in the future.


---


Well, we can, ... but ...

A goal of creating specification(s) for the stylesheet(s) provided by 
javadoc, for the doclet-generated output, and for the doc-comment 
content, is that the specification(s) should be subject to specification 
review[1], and not just an impl detail of the javadool tool and/or build 
system.


-- Jon

[1] 
http://mail.openjdk.java.net/pipermail/csr-discuss/2017-April/thread.html

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Jonathan Gibbons]

On 5/3/17 7:49 PM, Martin Buchholz wrote:


w3.org  doc seems to suggest we should only be defining 
table styles with borders.


https://www.w3.org/TR/html5/tabular-data.html#attr-table-border

"""Tables should not be used as layout aids. """

"""User agents, especially those that do table analysis on arbitrary 
content, are encouraged to find heuristics to determine which tables 
actually contain data and which are merely being used for layout. """


Understood.  The patch as provided already changes some tables with 
`summary="layout"` into definition lists.  There are additional 
candidates that would be candidates for such a change at some point.


-- Jon

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Martin Buchholz]

Jonathan Gibbons for  "css style czar"!

---

I checked the tables at
http://cr.openjdk.java.net/~jjg/8179479-8179592/api/java/util/concurrent/BlockingDeque.html
They look perfectly fine, although I feel a twinge of
non-collapsed-border-nostalgia.

---

Yes, "striped" is a much better name than "altrows".  "striped-tables" as
you suggest may be better.  Choose your names carefully - we can't change
them in the future.

---

w3.org doc seems to suggest we should only be defining table styles with
borders.

https://www.w3.org/TR/html5/tabular-data.html#attr-table-border

"""Tables should not be used as layout aids. """

"""User agents, especially those that do table analysis on arbitrary
content, are encouraged to find heuristics to determine which tables
actually contain data and which are merely being used for layout. """

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Jonathan Gibbons]

With my javadoc-tool-developer hat on, I'd like to get out of the 
business of jdk-style-owner, or at least identify that as a distinct 
hat. :-)


Kumar has identified a problem with the styles as currently defined ... 
you cannot easily embed a table with a default style inside a table with 
an explicit style ... which suggests the need for a third named style 
for "no borders".  (And yes, we have nested tables in some places.).


Although we disagree with your comment "THIS IS JAVA" (no it's not, it's 
HTML and CSS) the point is noted. How about the following names, with 
appropriate comments to come in the style sheet:


1. 
it does what it says, but long term, I see this being 
deprecated in favor of other styles ... there are places where a style 
with no borders is in use now, but when you add in captions, some amount 
of bordering would be better.


2. 
simple collapsed borders around each cell

3. 
previously called altrows.

How about longer names, specific to tables, like "borderless-table", 
"plain-table", "striped-table"? That would make it easier to have named 
styles for other constructs, although we will need to keep a balance 
between a proliferation of named styles and too much inline style.


All of this would be so much better with sufficient definitions for all 
the styles used by javadoc to allow adventurous and creative folk to use 
modified stylesheets for their own API. But not this week.


By the way, I forgot to mention in my original email, there is a copy of 
the API docs showing the proposed changes, available here:


http://cr.openjdk.java.net/~jjg/8179479-8179592/api/java.base-summary.html

-- Jon




On 05/03/2017 05:46 PM, Martin Buchholz wrote:
Jon, I am happy for you to own the html5 style for the entire javadoc; 
consistency wins; my comments are only suggestions and I'm no html or 
css expert.


On Wed, May 3, 2017 at 5:03 PM, Jonathan Gibbons 
mailto:jonathan.gibb...@oracle.com>> wrote:




On 05/03/2017 04:39 PM, Martin Buchholz wrote:

Thanks, Jon.

For the Deque/Queue tables
- * 
+ * 
I expected that we would modify these to

which rendered alright and is compliant (although "border" is a
weird boolean) and makes the "border intent" clear to humans and
to browsers.

THIS IS JAVA, so I'd prefer more verbose meaningful names for
these style classes ... hmmm ... class="contrasting_rows" ?  To
me, "plain" is suggestive of no borders at all.

Can we have some guidance comments in stylesheet.css explaining
when to use the different classes?



Martin,

If you are specifically requesting that the tables in Deque/Queue
use "" then I will do as you request, but I note
that the "plain" style does more than just  `border="1"`. It
adjusts the caption font and the margins above and below the
table. Given that the JSR166 doc comments actually use the
 tag reasonably, the presentation with the non-default
font seemed "better".

That being said, prior to doing this work, I did some analysis on
the tables coming from doc comments.  There are about 484 
with 70 different variants of the opening  tag.  Therefore,
there was a secondary goal to simplify the many different visual
appearances created using inline styles.

How strongly do you feel about the names?  As I said at the end of
the email, I would like to do a more complete cleanup of javadoc
support for stylesheets in a subsequent release. This would
involve separating the stylesheet for the HTML generated by the
doclet from a stylesheet provided to accompany the doc comments,
and would clean up the name space and write a moderately formal
specification of the styles in those stylesheets.

I can put some comments in the default stylesheet for the time being.

-- Jon

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Martin Buchholz]

Jon, I am happy for you to own the html5 style for the entire javadoc;
consistency wins; my comments are only suggestions and I'm no html or css
expert.

On Wed, May 3, 2017 at 5:03 PM, Jonathan Gibbons <
jonathan.gibb...@oracle.com> wrote:

>
>
> On 05/03/2017 04:39 PM, Martin Buchholz wrote:
>
> Thanks, Jon.
>
> For the Deque/Queue tables
>
> - * 
> + * 
>
> I expected that we would modify these to
> 
> which rendered alright and is compliant (although "border" is a weird
> boolean) and makes the "border intent" clear to humans and to browsers.
>
> THIS IS JAVA, so I'd prefer more verbose meaningful names for these style
> classes ... hmmm ... class="contrasting_rows" ?  To me, "plain" is
> suggestive of no borders at all.
>
> Can we have some guidance comments in stylesheet.css explaining when to
> use the different classes?
>
>
> Martin,
>
> If you are specifically requesting that the tables in Deque/Queue use
> "" then I will do as you request, but I note that the
> "plain" style does more than just  `border="1"`. It adjusts the caption
> font and the margins above and below the table. Given that the JSR166 doc
> comments actually use the  tag reasonably, the presentation with
> the non-default font seemed "better".
>
> That being said, prior to doing this work, I did some analysis on the
> tables coming from doc comments.  There are about 484  with 70
> different variants of the opening  tag.  Therefore, there was a
> secondary goal to simplify the many different visual appearances created
> using inline styles.
>
> How strongly do you feel about the names?  As I said at the end of the
> email, I would like to do a more complete cleanup of javadoc support for
> stylesheets in a subsequent release. This would involve separating the
> stylesheet for the HTML generated by the doclet from a stylesheet provided
> to accompany the doc comments, and would clean up the name space and write
> a moderately formal specification of the styles in those stylesheets.
>
> I can put some comments in the default stylesheet for the time being.
>
> -- Jon
>

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Jonathan Gibbons]

On 05/03/2017 04:39 PM, Martin Buchholz wrote:

Thanks, Jon.

For the Deque/Queue tables
- * 
+ * 
I expected that we would modify these to

which rendered alright and is compliant (although "border" is a weird 
boolean) and makes the "border intent" clear to humans and to browsers.


THIS IS JAVA, so I'd prefer more verbose meaningful names for these 
style classes ... hmmm ... class="contrasting_rows" ?  To me, "plain" 
is suggestive of no borders at all.


Can we have some guidance comments in stylesheet.css explaining when 
to use the different classes?




Martin,

If you are specifically requesting that the tables in Deque/Queue use 
"" then I will do as you request, but I note that the 
"plain" style does more than just  `border="1"`. It adjusts the caption 
font and the margins above and below the table. Given that the JSR166 
doc comments actually use the  tag reasonably, the presentation 
with the non-default font seemed "better".


That being said, prior to doing this work, I did some analysis on the 
tables coming from doc comments.  There are about 484  with 70 
different variants of the opening  tag.  Therefore, there was a 
secondary goal to simplify the many different visual appearances created 
using inline styles.


How strongly do you feel about the names?  As I said at the end of the 
email, I would like to do a more complete cleanup of javadoc support for 
stylesheets in a subsequent release. This would involve separating the 
stylesheet for the HTML generated by the doclet from a stylesheet 
provided to accompany the doc comments, and would clean up the name 
space and write a moderately formal specification of the styles in those 
stylesheets.


I can put some comments in the default stylesheet for the time being.

-- Jon

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Martin Buchholz]

Thanks, Jon.

For the Deque/Queue tables

- * 
+ * 

I expected that we would modify these to

which rendered alright and is compliant (although "border" is a weird
boolean) and makes the "border intent" clear to humans and to browsers.

THIS IS JAVA, so I'd prefer more verbose meaningful names for these style
classes ... hmmm ... class="contrasting_rows" ?  To me, "plain" is
suggestive of no borders at all.

Can we have some guidance comments in stylesheet.css explaining when to use
the different classes?

Re: RFR: Update tables in java.base to be HTML5-friendly.

[Joseph D. Darcy]

Hi Jon,

The changes in the java.lang and java.math packages look fine.

Cheers,

-Joe

On 5/3/2017 3: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