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
