<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

Reply via email to