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
> - * <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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/compiler-dev/attachments/20170503/d9b51034/attachment.html>