Merge branch 'gawk-5.1-stable'

1 files changed, 23 insertions, 0 deletions

diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index 110e090c..abe5a236 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -19964,6 +19964,29 @@ function causes it to become a scalar variable (unassigned).
 However, @code{isarray()} and @code{typeof()} are different; they do
 not change their arguments from untyped to unassigned.
 
+@cindex dark corner @subentry array elements created by reference
+By ``variable'' we mean one denoted by a simple identifier.  Array elements
+that come into existence simply by referencing them
+are different, they are automatically forced to be scalars. Consider:
+
+@example
+$ @kbd{gawk 'BEGIN @{ print typeof(x) @}'}
+@print{} untyped
+$ @kbd{gawk 'BEGIN @{ print typeof(x["foo"]) @}'}
+@print{} unassigned
+@end example
+
+@noindent
+@code{x[0]} comes into existence before it is passed to @code{typeof()};
+@code{typeof()} cannot tell that it didn't exist prior to being called.
+@value{DARKCORNER}
+
+@c FIXME: For 5.2, this will change, update this bit of doc.
+This may change in a future release, whereby @command{gawk}
+would allow such an unassigned array element to be used for
+a multidimensional array, and not remain a scalar forever
+(or until deleted).
+
 @node I18N Functions
 @subsection String-Translation Functions
 @cindex @command{gawk} @subentry string-translation functions