[List] notes on items, sigils and flattening

Author: moritz

lib/List.pod

@@ -8,6 +8,35 @@ C<List> stores items sequentially and potentially lazily.
 
 Indexes into lists and arrays start at 0 by default.
 
+You cannot assign to list elements. Use Arrays for that use
+case instead.
+
+
+=head2 Items, Flattening and Sigils
+
+In Perl 6, assigning a C<List> to a scalar variable does not lose
+information. The difference is that iteration generally treats a
+list (or any other list-like object, like a C<Parcel> or an C<Array>)
+inside a scalar as a single element.
+
+    my @a = 1, 2, 3;
+    for @a { }      # three iterations
+
+    my $s = @a;
+    for $s { }      # one iteration
+    for @a.item { } # one iteration
+    for $s.list { } # three iterations
+
+Combining lists or arrays that are not inclosed into an item container
+generally flattens.
+
+    my @a = 1, 2, 3;
+    my @flat   = @a, @a;           # six elements
+    my @nested = @a.item, @a.item; # two elemnts
+
+C<.item> can often be written as C<$( ... )>, and on an array variable
+even as C<$@a>.
+
 =head2 Methods
 
 =head3 elems