commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
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
>  
> 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 &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>
<p>Prose</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.

Phil

[5]  Here is an example:
http://s.apache.org/z9Q

>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message