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