Phil, I don't know who was telling people Javadoc is XML. I never heard of that. AFAIK, it has always been HTML but the Javadoc parser didn't care to enforce it. Now it's enforcing it so the only "good" Javadoc is HTML as it always was. If anyone wants to show me Sun saying Javadoc was XML, I'll gladly eat my words and enjoy learning something new. But why fight the technology? Javadoc isn't ever going to be XML so why continue going down that path?
On Thu, May 1, 2014 at 9:15 PM, Phil Steitz <phil.ste...@gmail.com> wrote: > On 5/1/14, 2:31 PM, 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. > > > > 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 > > Thanks for sharing. Basically, I would say "what Stephen said" > which is that the J8 ridiculouslness should be roundly ignored. > > it is truly comical that roughly 10 years ago, we started > assiduously adding </p>'s so we would have "valid XML." Now the > "best minds" are telling us that we need to rip all of that out. I > am calling ########. Lets focus on getting good, complete Javadoc. > Turn off whatever warning crap is being emitted. I agree with > Gilles on this. > > Phil > > > > 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 > >> > >> > > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > -- Cheers, Paul
