<p>This is a paragraph.</p> <p/> is useless Gary
On Thu, May 1, 2014 at 10:20 PM, Paul Benedict <pbened...@apache.org> wrote: > 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 > -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org Java Persistence with Hibernate, Second Edition<http://www.manning.com/bauer3/> JUnit in Action, Second Edition <http://www.manning.com/tahchiev/> Spring Batch in Action <http://www.manning.com/templier/> Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
