Okay. To address some of your points (not in order): - I do not interpret "no end tags" as a strict prohibition on self-closing elements. I think many people agree with me. I think the fact that browsers barf at <br></br> but not <br /> reinforces this interpretation.
- HTML5 does allow self-closing elements ... but ONLY for void elements (not empty elements that allow content). - So you say -Xdoclint for JavaDoc was meant to be the analog to -Xlint for JavaC, and I buy that ... except that it wasn't implemented that way. -Xlint produces /warnings/. -Xdoclint produces /errors/ and causes JavaDoc to fail. If -Xlint produces warnings and -Werror makes those warnings errors, then IMO -Xdoclint should also produce warnings and -Werror (or possibly something like -Wdocerror) should make those warnings errors. After all, the <br /> problem that the W3 validator points out is a WARNING, not an ERROR. - Somewhat off topic, every JavaDoc page produced by Java 8 right now has at least one W3 validator warning, because they're all missing a character encoding declaration (assumed to be UTF-8 for validation, but that's not portable). Nick On Jul 25, 2013, at 3:46 PM, Jonathan Gibbons wrote: > First, as was pointed out earlier[1] in the original thread, the HTML 4 spec > does not mention the existence of self-closing elements, and in that message, > David makes a good point that <br> is defined to not have an end tag, > making the <br/> syntax doubly questionable. > > So what does "doclint" stand for? Read it as "doc lint" meaning it is to > javadoc comments what -Xlint is to javac and lint is to C code. In other > words, it is intended to be used to point out questionable (or erroneous) > input. The ";" in "for (Item i: list);" is totally legal, the cast in > "String s = > (String) "abc"; are both legal, but we do not think it unreasonable to > highlight them in code, along with all the other -X lint warnings. So > too with -Xdoclint messages regarding javadoc comments. > > Yes, you can say that all the browsers (now) accept this syntax -- but > the design intent of -Xdoclint was to highlight issues that might cause > a validator to give comments. For far too long, the javadoc tool itself > has generated bad code, and so the general goal in the ongoing javadoc > TLC has been that given valid input, javadoc should generate valid output, > where "valid" means "conforms to the published DOCTYPE" and accepted > by a standard recognized validator, such as the one I cited at w3c.org. > > I would /strongly/ prefer that we not revert back to "is the output from > javadoc > accepted by all browsers?". > > Should -Xdoclint be opt-in or opt-out? For what its worth, this was > always a controversial decision, because of the potential for discussions like > this. We've ended up with a compromise. It is opt-in at javac time, which is > when I'd expect most interested developers to want to use it -- as a > developer, > I want to see the doclint feedback at the time I'm writing my doc comments, > when I'm in the compile-edit-test cycle. But it is not enabled by default > for > javac. But it is enabled by default in javadoc at doc-generation time. > When you're generating docs, it is good for folk to know that the docs do > not conform to the declared standard (i.e. HTML 4.01) If you're not > interested > in the feedback, you can disable it easily enough. If you are interested, > a global replace of <br/> to <br> should not be an onerous task in any > modern IDE. > > Finally, another message [2] in the thread mentioned HTML 5. That is > definitely > on the upcoming radar. I would also like to see javadoc more forgiving in > its input while still generating conformant output. Yes, that might mean > fixing > up minor transgressions. But not today. > > -- Jon > > > [1] http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019262.html > [2] http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019264.html > > On 07/25/2013 01:22 PM, Nick Williams wrote: >> Jonathan, I don't see the "confirmation that this is not legal HTML" that >> you reference. I see a warning that some browsers may not interpret it >> correctly. But IE 5+ and all Firefox, Chrome, Netscape, Opera, etc. versions >> interpret it correctly. >> >> I understand your point about the spec not specifically allowing it. >> HOWEVER, I promise you there are TENS OF THOUSANDS of existing JavaDoc'd >> classes that will break JavaDoc generation as a result of this change. >> >> Maybe doclint (what does that stand for, by the way?) could be a default-off >> feature instead of a default-on feature? >> >> Nick >> >> On Jul 25, 2013, at 1:59 PM, Jonathan Gibbons wrote: >> >>> The message about "self-closing element not allowed" is because >>> self-closing elements are not allowed in HTML 4. The message is generated >>> by the new "doclint" feature available in javac and javadoc, which is >>> specifically intended to detect issues in javadoc comments. If you do not >>> wish to use the new doclint feature, you can disable it with -Xdoclint:none. >>> >>> >>> As confirmation that this is not legal HTML, try typing a code fragment >>> such as the following into the W3c validator at >>> http://validator.w3.org/check >>> >>>> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" >>>> "http://www.w3.org/TR/html4/loose.dtd";> >>>> <head> >>>> <title>test</title> >>>> </head> >>>> <body> >>>> <br/> >>>> </body> >>>> </html> >>> You will get the following warning: >>> >>>> 1. /Line 6 <http://validator.w3.org/check#line-6>, Column 4/: >>>> NET-enabling start-tag requires SHORTTAG YES >>>> |<br*/*>| >>>> >>>> For the current document, the validator interprets strings like >>>> |<FOO />| according to legacy rules that break the expectations of >>>> most authors and thus cause confusing warnings and error messages >>>> from the validator. This interpretation is triggered by HTML 4 >>>> documents or other SGML-based HTML documents. To avoid the >>>> messages, simply remove the "/" character in such contexts. NB: If >>>> you expect |<FOO />| to be interpreted as an XML-compatible >>>> "self-closing" tag, then you need to use XHTML or HTML5. >>>> >>>> This warning and related errors may also be caused by an unquoted >>>> attribute value containing one or more "/". Example: |<a >>>> href=http://w3c.org>W3C</a>|. In such cases, the solution is to >>>> put quotation marks around the value. >>>> >>> -- Jon >>> >>> >>> >>> On 07/25/2013 11:14 AM, Alan Bateman wrote: >>>> Re: Invalid "self-closing element not allowed" JavaDoc error.eml >>>> >>>> Subject: >>>> Re: Invalid "self-closing element not allowed" JavaDoc error >>>> From: >>>> "David M. Lloyd" <david.ll...@redhat.com> >>>> Date: >>>> 07/25/2013 10:41 AM >>>> >>>> To: >>>> core-libs-dev@openjdk.java.net >>>> >>>> >>>> On 07/25/2013 12:27 PM, Nick Williams wrote: >>>>> My apologies if this is not the right place to address this. If so, >>>>> please forgive and direct me to the correct list. >>>>> >>>>> There are a lot of people/projects complaining about Java 8's new >>>>> "self-closing element not allowed" error when compiling JavaDoc that has >>>>> legal <br /> tags in it (just google "self-closing element not allowed" >>>>> in quotes). Some (including myself) are asking, "Why should we fix this? >>>>> The problem is not in the JavaDoc, it's in the JavDoc compiler." However, >>>>> I haven't been able to find anyone who has actually broached the subject >>>>> on any mailing lists. >>>>> >>>>> <br /> is completely legal. While it is not strictly required by the HTML >>>>> standard (unless you're using XHTML), using self-closing tags is >>>>> /preferred/ because it's more obvious what the intention is. Perhaps most >>>>> importantly, <br /> is supported on 100% of browsers and is used >>>>> throughout JavaDoc all over the place. I have a feeling that once more >>>>> projects start compiling on a released Java 8, this is going to make a >>>>> fair number of people angry that hey have to "fix" (read: needlessly >>>>> change) potentially thousands of classes' worth of JavaDoc. >>>>> >>>>> What was the motivation behind the new "self-closing element not allowed" >>>>> check and how can we make it go away? >>>> Not really having a stake in this, I just want to observe a couple things. >>>> First, from what I can see, the HTML 4.x specifications make no reference >>>> to self-closing elements or their syntactical realization. As far as I >>>> can tell (not being any kind of SGML expert), self-closing elements are >>>> not valid or meaningful HTML according to its SGML definition. >>>> >>>> Finally, even if they were allowed, the BR tag is explicitly defined to >>>> forbid an end tag; self-closing elements imply an end tag (at least they >>>> do in XML, which appears to be the next-nearest concrete specification >>>> that has anything to say on the matter). >>>> >>>> See http://www.w3.org/TR/html401/struct/text.html#edef-BR for more info. >>>> >>>> So I'm curious when you say "using self-closing tags is /preferred/", do >>>> you have any sources to cite? >>>> -- >>>> - DML >>>> >>>> Re: Invalid "self-closing element not allowed" JavaDoc error.eml >>>> >>>> Subject: >>>> Re: Invalid "self-closing element not allowed" JavaDoc error >>>> From: >>>> Stephen Colebourne <scolebou...@joda.org> >>>> Date: >>>> 07/25/2013 10:59 AM >>>> >>>> To: >>>> core-libs-dev@openjdk.java.net >>>> >>>> >>>> Its complicated, see for example: >>>> http://stackoverflow.com/questions/3558119/are-self-closing-tags-valid-in-html5 >>>> >>>> The key point here is not whether its in the standard or not, but what >>>> people actually*do*. >>>> >>>> There is no doubt in my mind that <br /> br space slash is very common >>>> indeed. Its certainly my default. The javadoc validator should be as >>>> lenient as browsers are in this case. >>>> >>>> Stephen >>>> >>>> >>>> On 25 July 2013 18:41, David M. Lloyd<david.ll...@redhat.com> wrote: >>>>>> On 07/25/2013 12:27 PM, Nick Williams wrote: >>>>>>>> My apologies if this is not the right place to address this. If so, >>>>>>>> please >>>>>>>> forgive and direct me to the correct list. >>>>>>>> >>>>>>>> There are a lot of people/projects complaining about Java 8's new >>>>>>>> "self-closing element not allowed" error when compiling JavaDoc that >>>>>>>> has >>>>>>>> legal <br /> tags in it (just google "self-closing element not >>>>>>>> allowed" in >>>>>>>> quotes). Some (including myself) are asking, "Why should we fix this? >>>>>>>> The >>>>>>>> problem is not in the JavaDoc, it's in the JavDoc compiler." However, I >>>>>>>> haven't been able to find anyone who has actually broached the subject >>>>>>>> on >>>>>>>> any mailing lists. >>>>>>>> >>>>>>>> <br /> is completely legal. While it is not strictly required by the >>>>>>>> HTML >>>>>>>> standard (unless you're using XHTML), using self-closing tags >>>>>>>> is/preferred/ >>>>>>>> because it's more obvious what the intention is. Perhaps most >>>>>>>> importantly, >>>>>>>> <br /> is supported on 100% of browsers and is used throughout JavaDoc >>>>>>>> all >>>>>>>> over the place. I have a feeling that once more projects start >>>>>>>> compiling on >>>>>>>> a released Java 8, this is going to make a fair number of people angry >>>>>>>> that >>>>>>>> hey have to "fix" (read: needlessly change) potentially thousands of >>>>>>>> classes' worth of JavaDoc. >>>>>>>> >>>>>>>> What was the motivation behind the new "self-closing element not >>>>>>>> allowed" >>>>>>>> check and how can we make it go away? >>>>>> >>>>>> Not really having a stake in this, I just want to observe a couple >>>>>> things. >>>>>> First, from what I can see, the HTML 4.x specifications make no >>>>>> reference to >>>>>> self-closing elements or their syntactical realization. As far as I can >>>>>> tell (not being any kind of SGML expert), self-closing elements are not >>>>>> valid or meaningful HTML according to its SGML definition. >>>>>> >>>>>> Finally, even if they were allowed, the BR tag is explicitly defined to >>>>>> forbid an end tag; self-closing elements imply an end tag (at least they >>>>>> do >>>>>> in XML, which appears to be the next-nearest concrete specification that >>>>>> has >>>>>> anything to say on the matter). >>>>>> >>>>>> Seehttp://www.w3.org/TR/html401/struct/text.html#edef-BR for more info. >>>>>> >>>>>> So I'm curious when you say "using self-closing tags is/preferred/", do >>>>>> you >>>>>> have any sources to cite? >>>>>> -- >>>>>> - DML >
