# commons-dev mailing list archives

##### Site index · List index
Message view
Top
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Fri, 02 May 2014 13:13:44 GMT
On Fri, 02 May 2014 01:48:28 -0700, Phil Steitz wrote:
> On 5/1/14, 7:20 PM, Paul Benedict wrote:
>> Phil, I don't know who was telling people Javadoc is XML. I never
>> heard of
>> that.
>
> Well, could be just be personal ignorance, but the practice of
> closing tags in commons javadoc goes back to at least 2002.  You can
> see it in the [lang] Developer Guide (closing <p/>'s are referenced
> there) and throughout Commons components.  I could not find much in
> the archives actually discussing it.  I vaguely recall some argument
> that valid XML would be easier to process with tools other than the
> javadoc tool itself.  Personally, I find it a little more readable.
> I honestly don't care, but do find it irritating that we are being
> forced to fiddle with this stuff to keep the tool happy / producing
> "good" warnings.

According to

the javadoc tool produces HTML 4.01 "Transitional" (and thus assumes,
but does not check, that the Javadoc fragments are compliant with that
specification).

It seems that Java 8 goes some way to check for SGML compliance while
not enforcing HTML 4.01 "Strict": According to the the W3C validator
service, every paragraph (including the first sentence in Javadoc!),
should be preceded by a <p>.

SGML compliance requires supporting "null end tags"[1]:
http://www.webdevout.net/tidings/2006/04/16/the-problem-with-the-net/
which makes _all_ self-closing tags invalid, a.o. <p/> and <br/>.
XML being ubiquitous in the programming world (and somewhat beyond),
it was an understandable mistake that its syntax would be picked up
in preference to this obscure feature of (somewhat obsoleted) SGML.
[Who is using NET in Javadoc?  Actually, who has ever used NET?]

In HTML5, the situation becomes more consistent[2]:
1. <p/> is still invalid, because a "paragraph" cannot be empty (i.e.
it must logically contain the sentence that make up the
paragraph).[3]
2. <br/> is accepted. But it is recommended only in specific
situations[4]:

http://www.w3.org/TR/2011/WD-html5-author-20110705/the-br-element.html#the-br-element

Unless I'm mistaken, the javadoc tool of Java 8 thus forbids a syntax
that will be valid in HTML5 for the sake of supporting a feature that
will disappear in HTML5!

I'd tentatively conclude that we should use the following syntax:
<p>
Some documentation. Further details.
</p>
<p>
Some more documentation.
</p>

That would make the fragment valid as HTML 4.01 and 5, as well as XML.

> I agree with Gilles though that entities damage readability and
> using *more* of them is a step in the wrong direction.

This is what really started me.
Javadoc in itself is not valid HTML: it must be processed by the
tool to _produce_ HTML. Hence there is no advantage in creating a
content that is as close as possible to HTML compliance when more
legible
alternatives exist such as {@code a <= 0}.

> I will -1
> commits that rip out MathJax or mangle the embedded TeX (unless and
> until someone explains for legitimate reasons why MathJax itself is

Do you mean that Javadoc 8 requires that
$$a <= 0$$
be written
$$a &le; 0$$
?

Regards,
Gilles

[1] It looks like the existence of this SGML feature is a remnant from
an epoch where every byte of storage mattered.
And dropping it in XML seemed quite sensible; thus increasing the
consistency and legibility of the notation, and allowing an obvious
shortcut (the self-closing tag) for empty elements.
[2] Do we agree that HTML5 _is_ the future of HTML? Is Javadoc going
to stick with SGML/HTML4.01?
[3] <p> is routinely, but wrongly, used (in CM's Javadoc) as a
_separator_.
[4] The way I used <br> in CM's Javadoc would probably fall in the "not
recommended" category.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org