<p> I agree that paragraphs should be written like this. </p>
Gary On Wed, Sep 28, 2016 at 4:37 PM, Gilles <[email protected]> wrote: > > Thanks for the non-trivial details that make the change > understandable. > > It would have been nice to post this information on the ML, > before applying the changes. > 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". > > With this new specification (where laziness is not forgiven), > it is even more important than it was (when I raised the > issue, and nobody gave a damn) to decide together how to > layout Javadoc comments (so that they are both readable in > code and compliant). > > 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, and makes the Javadoc > difficult to read. > > Is there an HTML element which we can use to make a paragraph > (that would allow sample code or a list within it)? > > > Gilles > > > On Thu, 29 Sep 2016 00:59:48 +0200, Emmanuel Bourg wrote: > >> Le 28/09/2016 à 16:40, Gilles a écrit : >> >> They are not trivial issues, because they are not seen by everyone. >>> >> >> I'm not sure I have the same definition of "trivial" in my dictionary :) >> >> >> Below, you refer to HTML 5. >>> >>> Is the "javadoc" tool assuming that its input is valid HTML 5? >>> >> >> Javadoc in Java 8 is HTML 4 compliant, it'll switch to HTML 5 in Java 9 >> (see JEP 224 [1]). >> >> But the rule I mentioned isn't new in HTML 5, it existed before: >> >> https://www.w3.org/TR/html401/struct/text.html#edef-P >> >> "The P element represents a paragraph. It cannot contain block-level >> elements (including P itself)." >> >> >> Several years ago, I raise the issue of writing "valid" HTML/XHTML. >>> >>> At the time, the answer had been that the Javadoc specification >>> referred to an older HTML version, and that it was not going to >>> change, and thus not worth updating the docs in any consistent >>> way with the recommendation of W3C. >>> >>> Has that changed? >>> >> >> It changed with Java 8 enforcing the correctness of the HTML output. >> >> >> No, I purposefully removed that option before rerunning "mvn clean site"! >>> >> >> Perhaps you've run into >>> https://issues.apache.org/jira/browse/RNG-1 >>> >>> All I'm saying is that change must be clarified because it is definitely >>> not "Java 8" as such that causes the trouble. >>> >> >> Are you using OpenJDK 8 on Debian/Ubuntu? doclint is disabled by default >> on these systems [2]. >> >> Emmanuel Bourg >> >> [1] http://openjdk.java.net/jeps/224 >> [2] >> >> https://sources.debian.net/src/openjdk-8/8u102-b14.1-2/debia >> n/patches/disable-doclint-by-default.diff/ >> >> >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > > -- E-Mail: [email protected] | [email protected] Java Persistence with Hibernate, Second Edition <http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
