P.S.: RFR [9] 8133651: automated replacing of old-style tags in docs

Alexander Stepanov alexander.v.stepanov at oracle.com
Mon Oct 5 11:12:27 UTC 2015


Hello,

Could you please review the fix for
https://bugs.openjdk.java.net/browse/JDK-8138838

Patch + webrev zipped + specdiff report:
http://cr.openjdk.java.net/~avstepan/8138838

Just some cosmetic changes for docs (<code>...</code> -> {@code ...} 
replacement) + some misprints fixed.

Not sure if these changes are desired at all for now.

Thanks,
Alexander

(Just in case, adding the prehistory and sending a copy to core-libs-dev).



On 10/1/2015 2:31 PM, Alexander Stepanov wrote:
> Hello Martin, Stuart,
>
> Thank you for the notes,
>
> Yes, the initial utility is quite ugly, I just tried to prepare it as 
> quickly as possible hoping that it covers the majority of "trivial" 
> replace cases. Yes, it does not process multi-line <code> inclusions.
>
> >  s = s.replace( "<CODE>", tag1);
> >  s = s.replace( "<Code>", tag1);
> >  s = s.replace("</CODE>", tag2);
> >  s = s.replace("</Code>", tag2);
>
> - replaced with "s = ln.replaceAll("(?i)<code>", 
> "<code>").replaceAll("(?i)</code>", "</code>");"
>
> Unfortunately my Perl/lisp knowledge are zero :)
>
> > Should you publish your specdiff?  I guess not - it would be empty!
> For now it contains a single fixed misprint diff, but there are a few 
> another misprints at the moment which I'd like to include in the patch 
> as well.
>
> So if you don't have objections, I'll delay for a several days and 
> then publish a final RFR (probably containing changes in some other 
> repos like jaxws, corba or jaxp) which would be more formal 
> (containing bug # and the final specdiff report).
>
> Thanks again,
> Alexander
>
>
> On 10/1/2015 9:54 AM, Martin Buchholz wrote:
>> Hi s'marks,
>> You probably don't need to absolutify paths.
>> And you can easily handle multiple args.
>>
>> (just for fun!)
>> Checks for javadoc comment; handles popular html entities; handles 
>> multiple lines; handles both tt and code:
>>
>> #!/bin/bash
>> find "$@" -name '*.java' | \
>>   xargs -r perl -p0777i -e \
>>   'do {} while s~^ 
>> *\*.*\K<(tt|code)>((?:[^<>{}\&\@]|&(?:lt|gt|amp);)*)</\1>~$_=$2; 
>> s/</</g; s/>/>/g; s/&/&/g; "{\@code $_}"~mgie'
>>
>>
>> On Wed, Sep 30, 2015 at 6:16 PM, Stuart Marks 
>> <stuart.marks at oracle.com <mailto:stuart.marks at oracle.com>> wrote:
>>
>>     Hi Alexander, Martin,
>>
>>     The challenge of Perl file slurping and Emacs one-liners was too
>>     much to bear.
>>
>>     This is Java, so one-liners are hardly possible. Still, there are
>>     a bunch of improvements that can be made to the Java version. (OK,
>>     and I'm showing off a bit.)
>>
>>     Take a look at this:
>>
>> http://cr.openjdk.java.net/~smarks/misc/SimpleTagEditorSmarks1.java 
>> <http://cr.openjdk.java.net/%7Esmarks/misc/SimpleTagEditorSmarks1.java>
>>
>>     I haven't studied the output exhaustively, but it seems to do a
>>     reasonably good job for the common cases. I ran it over java.lang
>>     and I noticed a few cases where there is markup embedded within
>>     <code></code> text, which should be looked at more closely.
>>
>>     I don't particularly care if you use my version, but there are
>>     some techniques that I'd strongly recommend that you consider
>>     using in any such tool. In particular:
>>
>>      - Pattern.DOTALL to do multi-line matches
>>      - Pattern.CASE_INSENSITIVE
>>      - try-with-resources to ensure that files are closed properly
>>      - NIO instead of old java.io <http://java.io> APIs, particularly
>>     Files.walk() and streams
>>      - use Scanner to deal with input file buffering
>>      - Scanner's stream support (I recently added this to JDK 9)
>>
>>     Enjoy,
>>
>>     s'marks
>>
>>
>>
>>     On 9/29/15 2:23 PM, Martin Buchholz wrote:
>>
>>         Hi Alexander,
>>
>>         your change looks good.  It's OK to have manual corrections
>>         for automated
>>         mega-changes like this, as long as they all revert changes.
>>
>>         Random comments:
>>
>>         Should you publish your specdiff?  I guess not - it would be
>>         empty!
>>
>>                      while((s = br.readLine()) != null) {
>>
>>         by matching only one line at a time, you lose the ability to 
>> make
>>         replacements that span lines.  Perlers like to "slurp" in the
>>         entire file
>>         as a single string.
>>
>>                  s = s.replace( "<CODE>", tag1);
>>                  s = s.replace( "<Code>", tag1);
>>                  s = s.replace("</CODE>", tag2);
>>                  s = s.replace("</Code>", tag2);
>>
>>         Why not use case-insensitive regex?
>>
>>         Here's an emacs-lisp one-liner I've been known to use:
>>
>>         (defun tt-code ()
>>            (interactive)
>>            (query-replace-regexp
>> "<\\(tt\\|code\\)>\\([^&<>\\\\]+\\)</\\1>" "{@code
>>         \\2}"))
>>
>>         With more work, one can automate transformation of embedded
>>         things like <
>>
>>         But of course, it's not even possible to transform ALL uses of
>>         <code> to
>>         {@code, if there was imaginative use of nested html tags.
>>
>>
>>         On Tue, Sep 29, 2015 at 3:21 AM, Alexander Stepanov <
>>         alexander.v.stepanov at oracle.com
>>         <mailto:alexander.v.stepanov at oracle.com>> wrote:
>>
>>             Updated: a few manual corrections were made (as @linkplain
>>             tags displays
>>             nested {@code } literally):
>> http://cr.openjdk.java.net/~avstepan/tmp/codeTags/jdk.patch 
>> <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/jdk.patch>
>>             -checked with specdiff (which of course does not cover
>>             documentation for
>>             internal packages), no unexpected diffs detected.
>>
>>             Regards,
>>             Alexander
>>
>>
>>             On 9/27/2015 4:52 PM, Alexander Stepanov wrote:
>>
>>                 Hello Martin,
>>
>>                 Here is some simple app. to replace <code></code> tags
>>                 with a new-style
>>                 {@code } one (which is definitely not so elegant as
>>                 the Perl one-liners):
>> http://cr.openjdk.java.net/~avstepan/tmp/codeTags/SimpleTagEditor.java
>> <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/SimpleTagEditor.java>
>>
>>                 Corresponding patch for jdk and replacement log (~62k
>>                 of the tag changes):
>> http://cr.openjdk.java.net/~avstepan/tmp/codeTags/jdk.patch
>> <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/jdk.patch>
>> http://cr.openjdk.java.net/~avstepan/tmp/codeTags/replace.log
>> <http://cr.openjdk.java.net/%7Eavstepan/tmp/codeTags/replace.log>
>>                 (sorry, I have to check the correctness of the patch
>>                 with specdiff yet,
>>                 so this is rather demo at the moment).
>>
>>                 Don't know if these changes (cosmetic by nature) are
>>                 desired for now or
>>                 not. Moreover, probably some part of them should go to
>>                 another repos (e.g.,
>>                 awt, swing -> "client" instead of "dev").
>>
>>                 Regards,
>>                 Alexander
>>
>




More information about the core-libs-dev mailing list