<html>
<head>
<meta content="text/html; charset=utf-8" http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
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. :-)<br>
<br>
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.).<br>
<br>
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:<br>
<br>
1. <table class="no-borders"><br>
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.<br>
<br>
2. <table class="plain"><br>
simple collapsed borders around each cell<br>
<br>
3. <table class="striped"><br>
previously called altrows.<br>
<br>
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.<br>
<br>
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.<br>
<br>
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:<br>
<br>
<a class="moz-txt-link-freetext" href="http://cr.openjdk.java.net/~jjg/8179479-8179592/api/java.base-summary.html">http://cr.openjdk.java.net/~jjg/8179479-8179592/api/java.base-summary.html</a><br>
<br>
-- Jon<br>
<br>
<br>
<br>
<br>
<div class="moz-cite-prefix">On 05/03/2017 05:46 PM, Martin Buchholz
wrote:<br>
</div>
<blockquote
cite="mid:CA+kOe0_ZTTOP0+EgSX7XCuzeGTK9wq7XjNBcEfD0dDYTvS9tfw@mail.gmail.com"
type="cite">
<div dir="ltr">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.<br>
<div class="gmail_extra"><br>
<div class="gmail_quote">On Wed, May 3, 2017 at 5:03 PM,
Jonathan Gibbons <span dir="ltr"><<a
moz-do-not-send="true"
href="mailto:jonathan.gibbons@oracle.com"
target="_blank">jonathan.gibbons@oracle.com</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div bgcolor="#FFFFFF" text="#000000">
<div>
<div class="h5"> <br>
<br>
<div class="m_-8664344701494488802moz-cite-prefix">On
05/03/2017 04:39 PM, Martin Buchholz wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">Thanks, Jon.
<div><br>
</div>
<div>For the Deque/Queue tables</div>
<div>
<pre style="color:rgb(0,0,0);word-wrap:break-word;white-space:pre-wrap">- * <table BORDER CELLPADDING=3 CELLSPACING=1>
+ * <table class="plain">
</pre>
<div>I expected that we would modify these to</div>
<div><table border=1></div>
<div>which rendered alright and is compliant
(although "border" is a weird boolean) and
makes the "border intent" clear to humans
and to browsers.</div>
<div class="gmail_extra"><br>
</div>
<div class="gmail_extra">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.</div>
<div class="gmail_extra"><br>
</div>
<div class="gmail_extra">Can we have some
guidance comments in <span
style="color:rgb(0,0,0);white-space:pre-wrap">stylesheet.css
explaining when to use the different
classes?</span></div>
<div class="gmail_extra"><br>
</div>
</div>
</div>
</blockquote>
<br>
</div>
</div>
Martin,<br>
<br>
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".<br>
<br>
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.<br>
<br>
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.<br>
<br>
I can put some comments in the default stylesheet for
the time being. <br>
<br>
-- Jon<br>
</div>
</blockquote>
</div>
<br>
</div>
</div>
</blockquote>
<br>
</body>
</html>