document corner case of \l and \u, and simplify the code handling it

2011-05-27  Paolo Bonzini  <bonzini@gnu.org>

	* doc/sed-in.texi: Explain behavior of \l and \u at the end
	of the replacement text.
	* doc/sed.texi: Regenerate.
	* sed/execute.c (append_replacement, do_subst): Further
	simplification.

3 files changed, 60 insertions, 0 deletions

diff --git a/ChangeLog b/ChangeLog
index 6616302..ac294f2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,13 @@
 2011-05-27  Paolo Bonzini  <bonzini@gnu.org>
 
+	* doc/sed-in.texi: Explain behavior of \l and \u at the end
+	of the replacement text.
+	* doc/sed.texi: Regenerate.
+	* sed/execute.c (append_replacement, do_subst): Further
+	simplification.
+
+2011-05-27  Paolo Bonzini  <bonzini@gnu.org>
+
 	* doc/sed-in.texi: Fix incorrect comment in the "Increment a
 	number" example.  Reported by Wu Liang and Micah Cowan.
 	* doc/sed.texi: Regenerate.
diff --git a/doc/sed-in.texi b/doc/sed-in.texi
index e659a10..f058f03 100644
--- a/doc/sed-in.texi
+++ b/doc/sed-in.texi
@@ -1015,6 +1015,32 @@ to uppercase,
 Stop case conversion started by @code{\L} or @code{\U}.
 @end table
 
+When the @code{g} flag is being used, case conversion does not
+propagate from one occurrence of the regular expression to
+another.  For example, when the following command is executed
+with @samp{a-b-} in pattern space:
+@example
+s/\(b\?\)-/x\u\1/g
+@end example
+
+@noindent
+the output is @samp{axxB}.  When replacing the first @samp{-},
+the @samp{\u} sequence only affects the empty replacement of
+@samp{\1}.  It does not affect the @code{x} character that is
+added to pattern space when replacing @code{b-} with @code{xB}.
+
+On the other hand, @code{\l} and @code{\u} do affect the remainder
+of the replacement text if they are followed by an empty substitution.
+With @samp{a-b-} in pattern space, the following command:
+@example
+s/\(b\?\)-/\u\1x/g
+@end example
+
+@noindent
+will replace @samp{-} with @samp{X} (uppercase) and @samp{b-} with
+@samp{Bx}.  If this behavior is undesirable, you can prevent it by
+adding a @samp{\E} sequence---after @samp{\1} in this case.
+
 To include a literal @code{\}, @code{&}, or newline in the final
 replacement, be sure to precede the desired @code{\}, @code{&},
 or newline in the @var{replacement} with a @code{\}.
diff --git a/doc/sed.texi b/doc/sed.texi
index 8feeaa2..6f22872 100644
--- a/doc/sed.texi
+++ b/doc/sed.texi
@@ -1016,6 +1016,32 @@ to uppercase,
 Stop case conversion started by @code{\L} or @code{\U}.
 @end table
 
+When the @code{g} flag is being used, case conversion does not
+propagate from one occurrence of the regular expression to
+another.  For example, when the following command is executed
+with @samp{a-b-} in pattern space:
+@example
+s/\(b\?\)-/x\u\1/g
+@end example
+
+@noindent
+the output is @samp{axxB}.  When replacing the first @samp{-},
+the @samp{\u} sequence only affects the empty replacement of
+@samp{\1}.  It does not affect the @code{x} character that is
+added to pattern space when replacing @code{b-} with @code{xB}.
+
+On the other hand, @code{\l} and @code{\u} do affect the remainder
+of the replacement text if they are followed by an empty substitution.
+With @samp{a-b-} in pattern space, the following command:
+@example
+s/\(b\?\)-/\u\1x/g
+@end example
+
+@noindent
+will replace @samp{-} with @samp{X} (uppercase) and @samp{b-} with
+@samp{Bx}.  If this behavior is undesirable, you can prevent it by
+adding a @samp{\E} sequence---after @samp{\1} in this case.
+
 To include a literal @code{\}, @code{&}, or newline in the final
 replacement, be sure to precede the desired @code{\}, @code{&},
 or newline in the @var{replacement} with a @code{\}.