On 5/2/14, 6:13 AM, Gilles wrote: > On Fri, 02 May 2014 01:48:28 -0700, Phil Steitz wrote: >> 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. > > According to > > http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/whatsnew-7.html > the javadoc tool produces HTML 4.01 "Transitional" (and thus assumes, > but does not check, that the Javadoc fragments are compliant with > that > specification). > > It seems that Java 8 goes some way to check for SGML compliance while > not enforcing HTML 4.01 "Strict": According to the the W3C validator > service, every paragraph (including the first sentence in Javadoc!), > should be preceded by a <p>. > > SGML compliance requires supporting "null end tags"[1]: > > http://www.webdevout.net/tidings/2006/04/16/the-problem-with-the-net/ > which makes _all_ self-closing tags invalid, a.o. <p/> and <br/>. > XML being ubiquitous in the programming world (and somewhat beyond), > it was an understandable mistake that its syntax would be picked up > in preference to this obscure feature of (somewhat obsoleted) SGML. > [Who is using NET in Javadoc? Actually, who has ever used NET?] > > In HTML5, the situation becomes more consistent[2]: > 1. <p/> is still invalid, because a "paragraph" cannot be empty (i.e. > it must logically contain the sentence that make up the > paragraph).[3] > 2. <br/> is accepted. But it is recommended only in specific > situations[4]: > > http://www.w3.org/TR/2011/WD-html5-author-20110705/the-br-element.html#the-br-element > > Unless I'm mistaken, the javadoc tool of Java 8 thus forbids a syntax > that will be valid in HTML5 for the sake of supporting a feature that > will disappear in HTML5! > > I'd tentatively conclude that we should use the following syntax: > <p> > Some documentation. Further details. > </p> > <p> > Some more documentation. > </p> > > That would make the fragment valid as HTML 4.01 and 5, as well as > XML. > >> I agree with Gilles though that entities damage readability and >> using *more* of them is a step in the wrong direction. > > This is what really started me. > Javadoc in itself is not valid HTML: it must be processed by the > javadoc > tool to _produce_ HTML. Hence there is no advantage in creating a > Javadoc > content that is as close as possible to HTML compliance when more > legible > alternatives exist such as {@code a <= 0}. > >> 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). > > Do you mean that Javadoc 8 requires that > \( a <= 0 \) > be written > \( a ≤ 0 \) > ?
I don't know. I just don't want to have to mangle or rip out the TeX. > > > Regards, > Gilles > > [1] It looks like the existence of this SGML feature is a remnant > from > an epoch where every byte of storage mattered. > And dropping it in XML seemed quite sensible; thus increasing the > consistency and legibility of the notation, and allowing an > obvious > shortcut (the self-closing tag) for empty elements. > [2] Do we agree that HTML5 _is_ the future of HTML? Is Javadoc going > to stick with SGML/HTML4.01? > [3] <p> is routinely, but wrongly, used (in CM's Javadoc) as a > _separator_. > [4] The way I used <br> in CM's Javadoc would probably fall in the > "not > recommended" category. Not sure I get [3] and [4]. I agree with you that <p>Beautiful prose </p> makes sense as the generic paragraph format. Most browsers render <p>Beautiful <br/> prose </p> with less of a break than <p>Beautiful </p> <p>Prose</p> and there are places where our generated javadoc is clearer (IMO) due to having used the former [5]. Maybe what I am missing is that the right usage is <br> instead of <br/>. The latter, I vaguely recall starting to use around the same time we started adding </p>'s everywhere to make valid XML. Phil [5] Here is an example: http://s.apache.org/z9Q > > > --------------------------------------------------------------------- > 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
