RFR: Update tables in java.base to be HTML5-friendly.
martinrb at google.com
Thu May 4 00:46:23 UTC 2017
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
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?
> 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
More information about the core-libs-dev