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. <table class="no-borders">
         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. <table class="plain">
         simple collapsed borders around each cell

3. <table class="striped">
         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 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>
>
>     On 05/03/2017 04:39 PM, Martin Buchholz wrote:
>>     Thanks, Jon.
>>
>>     For the Deque/Queue tables
>>     - * <table BORDER CELLPADDING=3 CELLSPACING=1>
>>     + * <table class="plain">
>>     I expected that we would modify these to
>>     <table border=1>
>>     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 "<table border=1>" 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
>     <caption> 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 <tables>
>     with 70 different variants of the opening <table> 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
>
>