Hello Daniel, Thank you for the notes;

The <code></code> is not needed around {@link } - as that should be the default formatting for {@link } Sorry, didn't know; I have to fix that.

Would that be easier to read as: Yes, probably that's better. Some old-style <code></code> tags were saved just because of some extra code formatting (like italic letters, <strong> or <sup> tags etc.) inside of them (which should be displayed literally in case of {@code })

if the goal is to replace <code></code> and <tt></tt> everywhere Sorry, I didn't replace *all* of <code></code>, just some of them. The main intention was to replace just <tt></tt> (as the tag is deprecated for HTML5, in contrast to the <code>). So the touched packages (and even files) still have a lot of <code> tags.

Thanks, Alexander On 8/3/2015 3:17 PM, Daniel Fuchs wrote:

On 03/08/15 11:31, Alexander Stepanov wrote:

...

Hello,

Could you please review the following fix: http://cr.openjdk.java.net/~avstepan/8132468/webrev.00/ for https://bugs.openjdk.java.net/browse/JDK-8132468

Just some cleanup for docs (replacing obsolete "<tt></tt>").

Thanks, Alexander

Hi Alexander,

mostly looks good to me - with afew remarks though.

In some files, such as src/java.base/share/classes/java/io/Console.java and src/java.base/share/classes/java/lang/ClassLoader.java (possibly others) - you're using formatting like:

+ * <code>{@link #readLine}</code>.

The <code></code> is not needed around {@link } - as that should be the default formatting for {@link } (we use {@linkplain } when we don't want the code formatting for @link).

src/java.base/share/classes/java/io/File.java

+ * <blockquote><code> + * new File(</code><i> f</i><code>.{@link + * #toURI() toURI}()).equals(</code><i> f</i><code>.{@link + * #getAbsoluteFile() getAbsoluteFile}()) + * </code></blockquote>

Would that be easier to read as:

* <blockquote>{@code new File(f.}{@link * #toURI() toURI()}{@code .equals(f.}{@link * #getAbsoluteFile() getAbsoluteFile()}{@code )} * </blockquote>

(not sure why the original text has hard spaces   - as we usually don't put any space after an open parenthesis)

Same remark for this a few lines below:

+ * <blockquote><code> + * new {@link #File(java.net.URI) File}(</code><i> f</i>{@code + * .toURI()).equals(}<i> f</i><code>.{@link #getAbsoluteFile() getAbsoluteFile}()) + * </code></blockquote>

I mean - I don't particularly object but if the goal is to replace <code></code> and <tt></tt> everywhere - then why not go the full way down?

The other question is whether <pre></pre> would be a better fit than <blockquote><code></code></blockquote>.

Otherwise looks good!

-- daniel

On 3 Aug 2015, at 16:07, Alexander Stepanov <alexander.v.stepanov@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.ht... -Pavel

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-summ... 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@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.ht...

-Pavel

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/c...

The specdiff reports for lang and io: http://cr.openjdk.java.net/~avstepan/8132468/specdiff.io/overview-summary.ht... http://cr.openjdk.java.net/~avstepan/8132468/specdiff.lang/overview-summary....

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

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@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.ht...

-Pavel

Hi Alexander, On 8/5/15 2:01 PM, 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/c...

The specdiff reports for lang and io: http://cr.openjdk.java.net/~avstepan/8132468/specdiff.io/overview-summary.ht...

http://cr.openjdk.java.net/~avstepan/8132468/specdiff.lang/overview-summary....

This looks good to me as well. best regards, -- daniel

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

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@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.ht...

-Pavel