Merge branch 'gawk-5.1-stable'

1 files changed, 94 insertions, 0 deletions

diff --git a/doc/gawk.texi b/doc/gawk.texi
index b472316b..591246c0 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -5970,6 +5970,100 @@ regexp that precedes them.  For example, @code{/+/} matches a literal
 plus sign.  However, many other versions of @command{awk} treat such a
 usage as a syntax error.
 
+@cindex sidebar @subentry What About The Empty Regexp?
+@ifdocbook
+@docbook
+<sidebar><title>What About The Empty Regexp?</title>
+@end docbook
+
+@cindex empty regexps
+@cindex regexps, empty
+We describe here an advanced regexp usage. Feel free to skip it
+upon first reading.
+
+You can supply an empty regexp constant (@samp{//}) in all places
+where a regexp is expected. Is this useful?  What does it match?
+
+It is useful. It matches the (invisible) empty string at the start
+and end of a string of characters, as well as the empty string
+between characters. This is best illustrated with the @code{gsub()}
+function, which makes global substitutions in a string
+(@pxref{String Functions}).  Normal usage of @code{gsub()} is like
+so:
+
+@example
+$ @kbd{awk '}
+> @kbd{BEGIN @{}
+> @kbd{    x = "ABC_CBA"}
+> @kbd{    gsub(/B/, "bb", x)}
+> @kbd{    print x}
+> @kbd{@}'}
+@print{} AbbC_CbbA
+@end example
+
+We can use @code{gsub()} to see where the empty strings
+are that match the empty regexp:
+
+@example
+$ @kbd{awk '}
+> @kbd{BEGIN @{}
+> @kbd{    x = "ABC"}
+> @kbd{    gsub(//, "x", x)}
+> @kbd{    print x}
+> @kbd{@}'}
+@print{} xAxBxCx
+@end example
+
+@docbook
+</sidebar>
+@end docbook
+@end ifdocbook
+
+@ifnotdocbook
+@cartouche
+@center @b{What About The Empty Regexp?}
+
+
+@cindex empty regexps
+@cindex regexps, empty
+We describe here an advanced regexp usage. Feel free to skip it
+upon first reading.
+
+You can supply an empty regexp constant (@samp{//}) in all places
+where a regexp is expected. Is this useful?  What does it match?
+
+It is useful. It matches the (invisible) empty string at the start
+and end of a string of characters, as well as the empty string
+between characters. This is best illustrated with the @code{gsub()}
+function, which makes global substitutions in a string
+(@pxref{String Functions}).  Normal usage of @code{gsub()} is like
+so:
+
+@example
+$ @kbd{awk '}
+> @kbd{BEGIN @{}
+> @kbd{    x = "ABC_CBA"}
+> @kbd{    gsub(/B/, "bb", x)}
+> @kbd{    print x}
+> @kbd{@}'}
+@print{} AbbC_CbbA
+@end example
+
+We can use @code{gsub()} to see where the empty strings
+are that match the empty regexp:
+
+@example
+$ @kbd{awk '}
+> @kbd{BEGIN @{}
+> @kbd{    x = "ABC"}
+> @kbd{    gsub(//, "x", x)}
+> @kbd{    print x}
+> @kbd{@}'}
+@print{} xAxBxCx
+@end example
+@end cartouche
+@end ifnotdocbook
+
 @node Interval Expressions
 @subsection Some Notes On Interval Expressions