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 bullshit. 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
