commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <gil...@harfang.homelinux.org>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Thu, 01 May 2014 22:02:46 GMT
On Thu, 1 May 2014 16:31:13 -0500, Paul Benedict wrote:
> Gilles,
>
> Javadoc is not XHTML but HTML... and not just HTML, but an HTML 
> fragment.
> Documentation writers need to remember that their content is being 
> placed
> within a bigger document so correct tag usage is important to get
> predictable results.

The issue here is: what is correct tag usage?
IIRC, some years ago, W3C indicated that lenient HTML syntax was a 
design
mistake, and transitional syntax was intended to make future versions 
of
(X)HTML be strictly XML-compliant (a.o. to simplify processing and 
enhance
the chance of "predictable results").
 From the partial information gotten here due to the issue with the 
release
of CM, I get the impression that for some obscure reason, Java tries to
distance itself from the path set by the W3C.

Until we know all the consequences of upgrading to Java8, I think that 
we
should not rush to make unnecessary changes.

>
> I think all Math committers will find this thread about the Javadoc 
> changes
> for Java 8 to be informative (switching to thread view can help):
> 
> http://mail.openjdk.java.net/pipermail/core-libs-dev/2013-July/019269.html

If that means that Javadoc will become tied to legacy HTML, it's a 
reason
for not using it more than necessary; in particular using entities 
should
be avoided wherever possible.

IMO, it makes little sense that Oracle now _requires_ than developers 
write
less legible documentation. This is turning back the clock...


Gilles


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


Mime
View raw message