On Thu, 29 Sep 2016 10:55:07 +0200, Emmanuel Bourg wrote:
Le 29/09/2016 à 01:37, Gilles a écrit :
The more so that the issue was encountered by several people
in different components, and IIRC now, the consensus (or
workaround) had been to indeed disable "doclint".
This is a wise workaround, fixing old Javadocs is a waste of time,
but
it isn't forbidden. If RNG had hundred of HTML errors I would have
just
disabled doclint when "mvn javadoc:javadoc" is used, but here it was
easy to fix.
when I raised the issue, and nobody gave a damn
Probably because Javadoc formatting issues aren't important enough
for
people to bother.
I've used <p></p> to create a _paragraph_:
"a distinct section of a piece of writing, usually dealing
with a single theme and indicated by a new line, indentation,
or numbering"
Your usage of <p>, even if compliant with the HTML spec, does
not comply with the above definition
Maybe you should bring your concerns to the HTML Working Group then.
You known that this is not a very useful suggestion.
I've always assumed that <p> is for paragraph; obviously I
was wrong (for HTML and thus Javadoc).
In "xdoc", it seems that <p> can be used as I want.
IMHO, the term "paragraph" in the HTML spec is confusing
since a <p> that cannot be (fully) used as such.
The standardization committee surely knows that for a long
time, and is not going to change it now.
<div> is indeed what I should have used instead.
and makes the Javadoc difficult to read.
The modification I made has no visual impact. These two snippets:
<p>TOTO list:
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
Have a nice day!</p>
and:
<p>TOTO list:</p>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
<p>Have a nice day!</p>
are rendered identically in modern browsers.
That's not the point.
I think that developers read much more often the source code than
the rendered HTML (which is mostly for users); that's obviously
why I put emphasis on well and consistently formatted Javadoc.
And the code readability
isn't that different.
OK.
I don't agree.
I prefer:
<div>
TOTO list:
<ul>
<li>
One (description is usually longer than one word)
</li>
<li>
Two:
</li>
<li>
Three
</li>
</ul>
Have a nice day!
</div>
Is there an HTML element which we can use to make a paragraph
(that would allow sample code or a list within it)?
You can use a <div> to mix inline text and lists, but you lose the
paragraph semantic and the top/bottom margins.
Thanks for the reminder.
Gilles
Emmanuel Bourg
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
