<AWT Dev> 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 awt-dev
mailing list