On Jul 25, 2013, at 7:16 PM, Jonathan Gibbons wrote: > On 07/25/2013 02:01 PM, Nick Williams wrote: >> 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. > > The (implicit) prohibition on self-closing elements is that they are not > mentioned/allowed in the spec we are trying to follow, which is HTML 4.01, as > defined in the DOCTYPE declarations in the generated files. > >> >> - HTML5 does allow self-closing elements ... but ONLY for void elements (not >> empty elements that allow content). > > When we convert javadoc to be able to generate HTML 5, we would obviously > update doclint accordingly. > >> >> - 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. > > -Xdoclint (intentionally) generates both warnings and errors. There have > been some cases where seemingly minor issues have caused incorrect > documentation to be generated, which is why we generate errors as well as > warnings.
So why is "self-closing element not allowed" considered an error when it's only a warning when validated with a W3 validator? Seems to me like a reasonable compromise to make this a warning instead of an error. Thoughts? > > >> >> - 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). > > Yes, we know about that one. We just haven't gotten around to fixing it yet. > The goal is that it should be possible to generate docs that are > validator-clean. There are other big boo-boos, such as invalid characters in > the anchors for method documentation, and duplicate names for overloaded > methods. But we'll get there. If you find other cases of javadoc output > failing a validator that you think is javadoc's fault, please let us know on > javadoc-...@openjdk.java.net. > > -- Jon > > >> >> 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 >
