On Thu, 01 May 2014 22:49:58 +0200, Thomas Neidhart wrote:
On 05/01/2014 10:31 PM, Gilles wrote:
Hi.
I don't like most of the changes performed on the Javadoc; most of
them
are going in the wrong direction IMHO, the most severe being the use
of
HTML "entities" rather than using MathJax.[1]
well, this does not really come as a surprise.
But seriously, about which changes are you talking?
There are 5 groups of changes which have been performed so far:
* replace <br/> with <p> tags
Trigerring an error on self-closing (and valid XML) tags seems
utterly stupid. [There might be some deeper reasons which I'm not
aware of at this point, since those "nice" Java 8 features are
totally new to me.]
* escape angle brackets (<, >) with the corresponding HTML entities
Does Java 8 refuse angle brackets enclosed in {@code ...} tags?
* remove unneeded </p> tags where java 8 javadoc complained
In XML, closing tags are never unneeded, they are required; so it
looks like Java 8 decided to be XML non-compliant.
If this is so, my opinion is to not use <p> anymore!
* add <code> tags within <pre> blocks as <sub> was not allowed
otherwise
* fix wrong/missing closing of tags (mostly ol, ul, code, li)
The only change being potentially controversial wrt readability are
the
angle brackets, but there are already many cases where the entities
are
used and this is only good practice and making it consistent in the
whole codebase.
I don't agree that reducing legibility is good practise.
Last time I checked W3C was trying to make HTML a valid XML
language;
now from what I read in this commit, Java 8 insists on being invalid
XML...
Since when was it decided to comply with Java 8 despite that it does
not
seem to be an obvious move?
Feel free to revert my change, I was only determined to avoid
potential
problems with the 3.3 vote as some people build with Java 8 and
report
errors with it.
As the build with Java 8 is broken anyway (due to findbugs), it was a
wasted effort for now, thus I stopped in the middle of it.
Until there is agreement on a way out, I think that we should have
followed the route proposed here:
http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
(i.e. disable the enforcement of the new rules).
Well, I tried that, but the setting did not seem to work with java 7,
thus I had to remove it again.
Then, as I indicated in the [vote] post, we should just not support
Java 8 for the time being, and ask people to open appropriate issues
for the things they wish to be fixed.
Why should we jump because Oracle made Java 8 non compatible with
Java 7?
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
