From 8acf99e3293c45fbaef69ba9cee3e790f1ff45bd Mon Sep 17 00:00:00 2001
From: "Arnold D. Robbins" <arnold@skeeve.com>
Date: Wed, 31 Mar 2021 21:08:58 +0300
Subject: Add some doc on the empty regexp.

---
 doc/gawk.texi | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

(limited to 'doc/gawk.texi')

diff --git a/doc/gawk.texi b/doc/gawk.texi
index c208ecac..7a746e1b 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -5965,6 +5965,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
 
-- 
cgit v1.2.3