More clarifications on hash definition

Author: JJ

doc/Language/hashmap.pod6

@@ -156,6 +156,25 @@ binding:
     my %h := { a => 'b', c => 'd', e => 'f'};
     say %h; # OUTPUT: «{a => b, c => d, e => f}␤»
 
+Nested hashes can also be defined using the same syntax:
+
+     my %h =  e => f => 'g';
+     say %h<e><f>; # OUTPUT: «g␤»
+
+However, what you are defining here is a key pointing to a L<Pair>, which is
+fine if that is what you want, and if your nested hash has got a single key. But
+C<%h<e>> will point to a C<Pair> which will have these consequences:
+
+=begin code :skip-test<Illustrates an error>
+my %h =  e => f => 'g';
+%h<e><q> = 'k';
+# OUTPUT: «(exit code 1) Pair␤Cannot modify an immutable Str (Nil)␤  in block <unit>»
+
+This, however, will effectively define a nested hash:
+
+     m: my %h =  e => { f => 'g'};
+     say %h<e>.^name;  # OUTPUT: «Hash␤»
+     say %h<e><f>;     # OUTPUT: «g␤»
 
 If a L<Pair> is encountered where a value is expected, it is used as a
 hash value: