On 5/1/14, 7:20 PM, Paul Benedict wrote: > Phil, I don't know who was telling people Javadoc is XML. I never heard of > that.
Well, could be just be personal ignorance, but the practice of closing tags in commons javadoc goes back to at least 2002. You can see it in the [lang] Developer Guide (closing <p/>'s are referenced there) and throughout Commons components. I could not find much in the archives actually discussing it. I vaguely recall some argument that valid XML would be easier to process with tools other than the javadoc tool itself. Personally, I find it a little more readable. I honestly don't care, but do find it irritating that we are being forced to fiddle with this stuff to keep the tool happy / producing "good" warnings. I agree with Gilles though that entities damage readability and using *more* of them is a step in the wrong direction. I will -1 commits that rip out MathJax or mangle the embedded TeX (unless and until someone explains for legitimate reasons why MathJax itself is a bad idea). Phil > 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 >> >> > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
