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
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/whatsnew-7.html
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
javadoc
tool to _produce_ HTML. Hence there is no advantage in creating a
Javadoc
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
a bad idea).
Do you mean that Javadoc 8 requires that
\( a <= 0 \)
be written
\( a ≤ 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-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
