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.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
>