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.
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 Paul On Thu, May 1, 2014 at 4:22 PM, Gilles <gil...@harfang.homelinux.org> wrote: > 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 > > -- Cheers, Paul
