RFR [9] 8132468: docs: replace <tt> tags (obsolete in html5) for java.io, java.lang, java.math

[Stuart Marks]

Hi Alexander,

The changes to File.java look good. Thanks for doing the specdiffs as well; it's 
a good way to verify that even with all these markup changes, specdiff didn't 
detect any changes to java.io.File at all.

(I didn't look at other files; I'm presuming that others have.)

s'marks

On 8/5/15 5:01 AM, Alexander Stepanov wrote:
> Hello Stuart,
>
> Please see the final version of File.java (please update the page) - just
> replacing <tt> with <code> in the mentioned places:
> http://cr.openjdk.java.net/~avstepan/8132468/webrev.01/src/java.base/share/classes/java/io/File.java.udiff.html
>
> The specdiff reports for lang and io:
> http://cr.openjdk.java.net/~avstepan/8132468/specdiff.io/overview-summary.html
> http://cr.openjdk.java.net/~avstepan/8132468/specdiff.lang/overview-summary.html
>
> Regards,
> Alexander
>
> On 8/4/2015 12:47 AM, Stuart Marks wrote:
>> Hi Alexander,
>>
>> I think Pavel's advice to run specdiff is useful. It's not too difficult to
>> run and in this case it provides a useful cross-check for making a large
>> number of markup changes. Contact me directly if you need help with specdiff.
>> I've run specdiff over your webrev.01 and I've posted the results here:
>>
>> http://cr.openjdk.java.net/~smarks/reviews/8132468/specdiff.01/overview-summary.html
>>
>>
>> They show that of all the changes you made, only four are considered
>> significant from specdiff's point of view. Of these, two appear to be merely
>> whitespace issues, but there are two changes that do appear significant:
>>
>>     File(URI)     // constructor
>>     File.toURI()
>>
>> In both cases the italic 'f' is intended to be a metasyntactic variable, not
>> an actual variable that's part of the code. The italic 'f' should be restored.
>> In the case of File.toURI() it appears that the resulting code is now
>> malformed, so there's clearly an error here.
>>
>> You and Daniel Fuchs had an exchange about this a bit earlier. I suspect the
>> reason for the   that appears between the opening parenthesis and the
>> italic 'f' is so that the tail of the 'f' doesn't crash into parenthesis. In
>> other words, the   is there merely for typographical purposes. I suspect
>> that after you restore the italic 'f' it'll look bad, so you'll want to
>> restore the   as well.
>>
>> s'marks
>>
>> On 8/3/15 9:03 AM, Alexander Stepanov wrote:
>>> Hello Pavel
>>>
>>>  > Hi Alexander, if I were you I would run specdiff
>>> Thanks; but sorry, I'm afraid I haven't enough time for the extra experiments
>>> just now...
>>>
>>>  > It's very easy to go the all the way and lose oneself in there :)
>>> please accept my condolences :)
>>>
>>> Regards,
>>> Alexander
>>>
>>> On 8/3/2015 6:33 PM, Pavel Rappo wrote:
>>>>> On 3 Aug 2015, at 16:07, Alexander Stepanov <alexander.v.stepanov at oracle.com>
>>>>> wrote:
>>>>>
>>>>> Please see the updated webrev:
>>>>> http://cr.openjdk.java.net/~avstepan/8132468/webrev.01/
>>>>>
>>>>> removed wrapping <code></code> around the links (mostly PrintStream.java,
>>>>> PrintWriter.java, File.java), plus other changes in File.java
>>>>>
>>>>> Thanks,
>>>>> Alexander
>>>> Hi Alexander, if I were you I would run specdiff against the changes and
>>>> upload it along with the RFR.
>>>>
>>>> P.S. "I've tried it once, it was awful." [1] It's very easy to go the all the
>>>> way and lose oneself in there :)
>>>>
>>>> ------------------------------------------------------------------------------
>>>> [1]
>>>> http://mail.openjdk.java.net/pipermail/core-libs-dev/2014-December/030262.html
>>>>
>>>> -Pavel
>>>>
>>>
>