commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Fri, 02 May 2014 19:10:05 GMT
On 5/2/14, 6:13 AM, Gilles wrote:
> 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]:
> 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]:
> 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 &le; 0 \)
> ?

I don't know.  I just don't want to have to mangle or rip out the TeX.
> 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.

Not sure I get [3] and [4].  I agree with you that
<p>Beautiful prose </p>
makes sense as the generic paragraph format.  Most browsers render
<p>Beautiful <br/>
 prose </p>
with less of a break than
<p>Beautiful </p>
and there are places where our generated javadoc is clearer (IMO)
due to having used the former [5].  Maybe what I am missing is that
the right usage is <br> instead of <br/>.  The latter, I vaguely
recall starting to use around the same time we started adding </p>'s
everywhere to make valid XML.


[5]  Here is an example:

> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message