1 files changed, 30 insertions, 0 deletions
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index b584181d..e733c4ec 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -4442,6 +4442,36 @@ Given the variable assignment feature, the @option{-F} option for setting
 the value of @code{FS} is not
 strictly necessary.  It remains for historical compatibility.
 
+@sidebar Quoting Shell Variables On The @command{awk} Command Line
+@cindex quoting @subentry in @command{gawk} command lines
+@cindex shell quoting, rules for
+@cindex null strings @subentry in @command{gawk} arguments, quoting and
+
+Small @command{awk} programs are often embedded in larger shell scripts,
+so it's worthwhile to understand some shell basics. Consider the following:
+
+@example
+f=""
+awk '@{ print("hi") @}' $f
+@end example
+
+In this case, @command{awk} reads from standard input instead of trying
+to open any command line files. To the unwary, this looks like @command{awk}
+is hanging.
+
+However @command{awk} doesn't see an explicit empty string. When a
+variable expansion is the null string, @emph{and} it's not quoted,
+the shell simply removes it from the command line. To demonstrate:
+
+@example
+$ @kbd{f=""}
+$ @kbd{awk 'BEGIN @{ print ARGC @}' $f}
+@print{} 1
+$ @kbd{awk 'BEGIN @{ print ARGC @}' "$f"}
+@print{} 2
+@end example
+@end sidebar
+
 @node Naming Standard Input
 @section Naming Standard Input