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-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org

Reply via email to