Invalid "self-closing element not allowed" JavaDoc error
nicholas+openjdk at nicholaswilliams.net
Thu Jul 25 20:20:09 UTC 2013
Correction: I see now that we're using Frameset doctype for the parent page and Transitional for the pages within frames. I misunderstood that. My bad.
On Jul 25, 2013, at 3:19 PM, Nick Williams wrote:
> Point of interest: JavaDoc uses the HTML 4 "Loose" specification, not the HTML 4 "Strict" specification. By using frames, JavaDoc is in violation of the HTML 4.01 Loose specification (see below).
> There are void elements and there are empty elements.
> Void elements are elements that ARE NOT ALLOWED to have content. They are: area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track, wbr, and some foreign/extension elements.
> Empty elements are elements that ARE ALLOWED to have content but don't, for whatever reason. This is any element not listed above.
> In HTML (all versions), empty elements CANNOT be self-closing, they MUST have start and end tags (like <script scr="foo"></script>) because they MAY have content. Void elements MUST NOT have start and end tags because they MAY NOT have content. Browsers MAY permit self-closing void tags, and all browsers do. There is no syntax difference between Strict, Transitional (Loose), and Frameset. Strict prohibits frame sets, presentational elements (like <font>), and deprecated elements. Transitional (Loose) allows presentational elements and deprecated elements but prohibits frame sets. Frameset allows presentational elements, deprecated elements, and frame sets. /If/ the motivation behind "self-closing element not allowed" is abiding by the spec, then we should get rid of frames, too.
> In XHTML (all versions), both empty elements and void elements MUST EITHER have a start and an end tag OR be self-closing (http://www.w3.org/TR/xhtml1/#h-4.6). Furthermore, the spec recommends for compatibility reasons that you always put a space before the forward slash in a self-closing element (http://www.w3.org/TR/xhtml1/#C_2).
> Special Note: In HTML5, the SVG and MathML elements MUST EITHER have a start and an end tag OR be self-closing.
> On Jul 25, 2013, at 1:13 PM, David M. Lloyd wrote:
>> It all hinges on whether the tool is generating HTML 4 or HTML 5. If 4, then the output should be HTML 4 "strict" and this kind of input should either be translated or forced to be valid.
>> If the output is going to be HTML 5 - which I suspect is going to be considered "premature" given the usual glacial pace of these kinds of changes - then perhaps it's time to revisit some other crustiness, like the use of frames.
>> On 07/25/2013 12:59 PM, Stephen Colebourne wrote:
>>> Its complicated, see for example:
>>> 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.
>>> On 25 July 2013 18:41, David M. Lloyd <david.lloyd at 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).
>>>> 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
>> - DML
More information about the core-libs-dev