RFR [9] 8133651: replace some <tt> tags (obsolete in html5) in core-libs docs

[Alexander Stepanov]

Hello Martin,

Thank you for review and for the notes!

 > I'm biased of course, but I like the approach I took with 
blessed-modifier-order:
 > - make the change completely automated
 > - leave "human editing" for a separate change
 > - publish the code used to make the automated change (in my case, 
typically a perl one-liner)

Automated replacement has an obvious advantage: it is fast and massive. 
But there are some disadvantages at the same time (just IMHO).

Using script it is quite easy to miss some not very trivial cases, e.g.:
- remove unnecessary linebreaks, like
  * <tt>someCode
  * </tt>
(which would be better to replace with single-line {@code someCode};
- joining of successive terms, like "<tt>ONE</tt>, <tt>TWO</tt>, 
<tt>THREE</tt>" -> "{@code ONE, TWO, THREE}";
- errors like extra or missing "<" or ">": * <tt>Collection 
<T></tt>", - there were a lot of them;
- some cases when <tt></tt> should be replaced with <code></code>, not 
{@code } (e.g. because of unicode characters inside of code etc.);
- extra tags inside of <tt> or <code> which should be moved outside of 
{@code }, like <tt><i>someCode</i></tt> or <tt><b>someCode</b></tt>;
- simple removing of needless tags, like "<tt>{@link ...}</tt>" -> 
"{@link ...}";
- replace HTML codes with symbols ('<', '>', '@', ...)
- etc.
- plus some other formatting changes and fixes for misprints which would 
be omitted during the automated replacement (and wouldn't be done in 
future manually because there is no motivation for repeated processing).

So sometimes it may be difficult to say where is the border between 
"trivial" and "human-editing" cases (and the portion of "non-trivial 
cases" is definitely not minor); moreover, even the automated 
replacement requires the subsequent careful review before publishing of 
webrev (as well as by reviewers who probably wouldn't be happy to review 
hundreds of files at the same time) and iterative checks/corrections. 
specdiff is very useful for this task but also cannot fully cover the 
diffs (as some changes are situated in the internal com/... sun/... 
packages).

Moreover, I'm sure that some reviewers would be annoyed with the fact 
that some (quite simple) changes were postponed because they are "not 
too trivial to be fixed just now" (because they will suspect they would 
be postponed forever). So the patch creator would (probably) receive 
some advices during the review like "please fix also fix this and that" 
(which is normal, of course).

So my preference was to make the changes package by package (in some 
reasonable amount of files) not postponing part of the changes for the 
future (sorry for these boring repeating review requests). Please note 
that all the above mentioned is *rather explanation of my motivation 
than objection* :) (and of course I used some text editor replace 
automation which is surely not so advanced as Perl).

 > It's probably correct, but I would have left it out of this change
Yes, I see. Reverted (please update the web page):
http://cr.openjdk.java.net/~avstepan/8133651/jdk.00/index.html

Thanks,
Alexander

P.S. The <tt> replacement job is mostly (I guess, ~80%) complete. But 
probably this approach should be used if some similar replacement task 
for, e.g., <code></code> tags would be planned in future (there are 
thousands of them).


On 9/24/2015 6:10 AM, Martin Buchholz wrote:
>
>
> On Sat, Sep 19, 2015 at 6:58 AM, Alexander Stepanov 
> <alexander.v.stepanov at oracle.com 
> <mailto:alexander.v.stepanov at oracle.com>> wrote:
>
>     Hello,
>
>     Could you please review the following fix
>     http://cr.openjdk.java.net/~avstepan/8133651/jdk.00/
>     <http://cr.openjdk.java.net/%7Eavstepan/8133651/jdk.00/>
>     http://cr.openjdk.java.net/~avstepan/8133651/jaxws.00/index.html
>     <http://cr.openjdk.java.net/%7Eavstepan/8133651/jaxws.00/index.html>
>     for
>     https://bugs.openjdk.java.net/browse/JDK-8133651
>
>     Just another portion of deprecated <tt> (and <xmp>) tags replaced
>     with {@code }. Some misprints were also fixed.
>
>
> I'm biased of course, but I like the approach I took with 
> blessed-modifier-order:
> - make the change completely automated
> - leave "human editing" for a separate change
> - publish the code used to make the automated change (in my case, 
> typically a perl one-liner)
>
>
>     The following (expected) changes were detected by specdiff:
>     - removed needless dashes in java.util.Locale,
>     - removed needless curly brace in xml.bind.annotation.XmlElementRef
>
>
> I would do a separate automated "removed needless dashes" changeset.
>
>
>     Please let me know if the following changes are desirable or not:
>     http://cr.openjdk.java.net/~avstepan/8133651/jdk.00/src/jdk.jconsole/share/classes/sun/tools/jconsole/Formatter.java.udiff.html
>     <http://cr.openjdk.java.net/%7Eavstepan/8133651/jdk.00/src/jdk.jconsole/share/classes/sun/tools/jconsole/Formatter.java.udiff.html>
>
>
> This is an actual change to the behavior of this code - the 
> maintainers of jconsole need to approve it.  It's probably correct, 
> but I would have left it out of this change. If you remove it, then I 
> approve this change.