Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (athena.apache.org: domain of paulus.benedictus@gmail.com
 designates 209.85.192.52 as permitted sender)
MIME-Version: 1.0
Sender: paulus.benedictus@gmail.com
In-Reply-To: <136892395bc1a02297ff123956442319@scarlet.be>
References: <20140501134806.17C0A238896F@eris.apache.org>
	<3a0939d1692f6a188f3abe71d7903510@scarlet.be>
	<5362B376.1070001@gmail.com>
	<136892395bc1a02297ff123956442319@scarlet.be>
Date: Thu, 1 May 2014 16:31:13 -0500
Message-ID: 
 <CABLGb9wB1KREg5Rex7b5rRXaF81-H9qOyEvP32LPbQiLjEpJDw@mail.gmail.com>
Subject: Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] -
 ...)
From: Paul Benedict <pbenedict@apache.org>
To: Commons Developers List <dev@commons.apache.org>
Content-Type: multipart/alternative; boundary=001a1134effc6eaf1e04f85d621a

--001a1134effc6eaf1e04f85d621a
Content-Type: text/plain; charset=UTF-8

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

Paul


On Thu, May 1, 2014 at 4:22 PM, Gilles <gilles@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
Cheers,
Paul

--001a1134effc6eaf1e04f85d621a--