[basics] rw review

Lots of minor improvements throughout.

src/basics.pod

@@ -59,7 +59,7 @@ The =begin/=end tags here add a bit of semantic markup we can exploit later.
     my @sorted = @names.sort({ %sets{$_} }).sort({ %games{$_} }).reverse;
 
     for @sorted -> $n {
-        say "$n has won { %games{$n} } games and { %sets{$n} } sets";
+        say "$n has won %games{$n} games and %sets{$n} sets";
     }
 
 =end programlisting
@@ -72,10 +72,10 @@ This produces the output:
     Beth has won 1 games and 4 sets
 
 Every Perl 6 program should begin with C<use v6;>. This line tells the compiler
-which version of Perl it is written in.  If you accidentally run the file with
-Perl 5, you'll get a helpful error message.
+which version of Perl the program expects. Should you accidentally run the file
+with Perl 5, you'd get a helpful error message.
 
-A Perl 6 program consists of one or more statements.  A statement ends with a
+A Perl 6 program consists of zero or more statements. A statement ends with a
 semicolon or a curly bracket at the end of a line.
 
 =begin programlisting
@@ -95,32 +95,16 @@ X<sigil>
 X<identifier>
 
 A variable name begins with a I<sigil>, which is a non-word character such as
-C<$>, C<@>, C<%>, or C<&> -- or occasionally the double colon C<::>. After the
+C<$>, C<@>, C<%>, or C<&> -- or occasionally the double colon C<::>. The
+sigils usually restrict the variable to some particular type. After the
 sigil comes an identifier, which may consist of letters, digits and the
 underscore. Between letters you can also use a dash C<-> or a hyphen C<'>, so
-C<isn't> and C<very-cool> are valid identifiers.
-
-=for author
-
-I'm not clear about the intent of the following paragraph.  It starts to
-explain scalars, but then veers off into "arbitrary values", which could mean a
-lot of things.
-
-Scalar variables B<can> hold anything you can store in variables, including
-Arrays and Hashes. How should I write that instead? Would "Variables starting
-with a dollar are the most permissive, and can hold an arbitrary object" be
-better? --moritz
-
-I personally would rather use the symbol than the name of the symbol, because
-the array and hash entries later on do so. --eternaleye
-
-=end for
+C<isn't> and C<double-click> are valid identifiers.
 
 X<files; handle>
 X<file handle>
 
-Each sigil carries a meaning. Variables with the C<$> sigil can hold
-arbitrary values. The built-in function C<open> opens a file, here named
+The built-in function C<open> opens a file, here named
 F<scores>, and returns an object describing that file, a I<file handle>. The
 equality sign C<=> I<assigns> that file handle to the variable on the left,
 which means that C<$file> now stores the file handle.
@@ -129,8 +113,9 @@ X<strings; literal>
 X<string literal>
 X<string>
 
-C<'scores'> is a I<string literal>. A string is a piece of text, or sequence
-of characters. In this line, it's an argument provided to C<open>.  If you prefer C-style notation, you could also write C<open('scores')>.
+C<'scores'> is a I<string literal>. A string is a piece of text, a sequence
+of characters. In this line, it's an argument provided to C<open>.  If you
+prefer C-style notation, you could also write C<open('scores')>.
 
 =begin programlisting
 
@@ -166,6 +151,12 @@ value that corresponds to a certain C<$key> with C<%hash{$key}>.
 Here in the score counting program, C<%games> stores the number of games each
 player has won and C<%sets> the number of sets each player has won.
 
+C<Array>s and C<Hash>es are central enough to each have their own sigil in
+Perl. The C<$> sigil, however, confers no restriction on the type of the
+value it contains. You can store numbers, strings or more complex objects
+in C<$>-sigil variables. (You can even put an C<Array> or a C<Hash> in there,
+should you wish.)
+
 =begin programlisting
 
     for $file.lines -> $line {
@@ -176,9 +167,10 @@ player has won and C<%sets> the number of sets each player has won.
 
 X<for>
 
-C<for> introduces a loop that runs the block indicated by C<...> once for each
-item of the list, setting the variable C<$line> to the current value.
-C<$file.lines> produces a list of the lines read from the file C<scores>.
+C<for> produces a loop that runs the block indicated by C<...> once for each
+item of the list, setting the variable C<$line> to the current value of each
+iteration. C<$file.lines> produces a list of the lines read from the file
+C<scores>.
 
 During the first iteration, C<$line> contains the string C<Ana vs Dave | 3:0>.
 During the second, C<Charlie vs Beth | 3:1>, and so on.
@@ -189,10 +181,10 @@ During the second, C<Charlie vs Beth | 3:1>, and so on.
 
 =end programlisting
 
-Again C<my> declares variables, this time a list of two at once. The right-hand
+Again, C<my> declares variables, this time a list of two at once. The right-hand
 side of the assignment is again a call to C<split>, this time splitting on a
 vertical bar surrounded by spaces. C<$pairing> gets the first item of the
-returned list and C<$result> the second.
+returned list, and C<$result> the second.
 
 While processing the first line, C<$pairing> holds the string C<Ana vs Dave>
 and C<$result> is set to C<3:0>.
@@ -268,7 +260,7 @@ After processing the first line of the file, the variables contain the values:
 
 =end table
 
-The program then counts the number of won sets:
+The program then counts the number of sets won:
 
 =begin programlisting
 
@@ -299,10 +291,11 @@ X<fat arrow>
 X<< => >>
 X<pair>
 
-Before these two lines execute, C<%sets> is empty. The assignment automatically
-populates the hash; after these two lines have run for the first time, C<%sets>
-contains C<< 'Ana' => 3, 'Dave' => 0 >>.  (The fat arrow C<< => >> separates
-key and value in a C<Pair>.)
+Before these two lines execute, C<%sets> is empty. Adding to an entry not in
+the hash will cause that entry to spring into existence just-in-time, with a
+value starting at zero. (This is called I<autovivification>). After these two
+lines have run for the first time, C<%sets> contains C<< 'Ana' => 3, 'Dave' =>
+0 >>.  (The fat arrow C<< => >> separates key and value in a C<Pair>.)
 
 =begin programlisting
 
@@ -315,9 +308,9 @@ key and value in a C<Pair>.)
 =end programlisting
 
 If C<$r1> has a larger value than C<$r2>, C<%games{$p1}> increments by one.  If
-C<$r1> is not larger than C<$r2>, C<%games{$p2}> increments.  If either hash
-value did not exist previously, it springs into existence from the increment
-operation. This is called I<autovivification>.
+C<$r1> is not larger than C<$r2>, C<%games{$p2}> increments. Just as in the
+case of C<+=> above, if either hash value did not exist previously, it is
+autovivified by the increment operation.
 
 X<postincrement>
 X<operators; postincrement>
@@ -327,8 +320,8 @@ X<operators; preincrement>
 C<$thing++> is short for C<$thing += 1> or
 C<$thing = $thing + 1>, with the small exception that the return value of the
 expression is C<$thing>, not the incremented value. Just like in the C
-programming language you can also use C<++> as a prefix, in which case it
-returns the increment value; C<my $x = 1; say ++$x> prints C<2>.
+programming language, you can also use C<++> as a prefix, in which case it
+returns the incremented value; C<my $x = 1; say ++$x> prints C<2>.
 
 =begin programlisting
 
@@ -340,14 +333,14 @@ X<topic variable>
 X<topic>
 X<variables; $_>
 
-This might look a bit scary at first, but it consists of three relatively
-simple steps. An array knows how to sort itself with the C<sort> method.
-However, the default sort on an array sorts by its contents.  To print the
-players names in winner-first order, the code must sort the array by the scores
-of the players, not their names.  The C<sort> method can take an argument, a
-I<block> used to transform the array elements (the names of players) to the
-thing you want to sort by. The array items are passed in through the I<topic
-variable> C<$_>.
+This might look a bit scary at first, but it consists of three individually
+simple steps. An array knows how to return a sorted version of itself with the
+C<sort> method. However, the default sort on an array sorts by its contents.
+To print the players names in winner-first order, the code must sort the array
+by the scores of the players, not their names.  The C<sort> method can take an
+argument, a I<block> used to transform the array elements (the names of
+players) to the thing you want to sort by. The array items are passed in
+through the I<topic variable> C<$_>.
 
 X<block>
 
@@ -365,25 +358,26 @@ won, which is the secondary criterion to decide who has won the tournament.
 X<stable sort>
 X<sort; stable>
 
-When two array items have the same value, C<sort> leaves their relative
-order unchanged. Computer scientists call that a I<stable> sort.  The program
-uses this property of Perl 6's C<sort> to achieve the goal by sorting twice:
-first by the number of sets won (the secondary criterion), then by the number
-of games won.
+When two array items have the same value, C<sort> leaves them in the same order
+as they came in. Computer scientists call this a I<stable> sort.  The program
+takes advantage of this property of Perl 6's C<sort> to achieve the goal by
+sorting twice: first by the number of sets won (the secondary criterion), then
+by the number of games won.
 
-After the first sorting step the names are in the order C<Beth Charlie Dave
+After the first sorting step, the names are in the order C<Beth Charlie Dave
 Ana>.  After the second sorting step, it's still the same, because nobody has
 won fewer games but more sets than somebody else.  Such a situation is
 entirely possible, especially at larger tournaments.
 
 C<sort> sorts in ascending order, from smallest to largest.  This is the
-opposite of the desired order.  Thus, the code calls the C<.reverse> method on
-the result of the second sort, and stores the final list in C<@sorted>.
+opposite of the desired order.  Therefore, the code calls the C<.reverse>
+method on the result of the second sort, and stores the final list in
+C<@sorted>.
 
 =begin programlisting
 
     for @sorted -> $n {
-        say "$n has won { %games{$n} } games and { %sets{$n} } sets";
+        say "$n has won %games{$n} games and %sets{$n} sets";
     }
 
 =end programlisting
@@ -396,14 +390,14 @@ X<operators; say>
 To print out the players and their scores, the code loops over C<@sorted>,
 setting C<$n> to the name of each player in turn. C<say> prints its arguments
 to the standard output (the screen, normally), followed by a newline.  (Use
-C<print> instead if you don't want the newline at the end).
+C<print> if you don't want the newline at the end.)
 
 X<interpolation>
 
-When you try out the program, you'll find that it doesn't print the literal
-text C<$n> each time, but the name that is stored in C<$n>. This automatic
-substitution is called M<interpolation>.  Perl 6 can interpolate variables with
-the dollar sigil as well as blocks of code in curly braces.
+When you try out the program, you'll find that it doesn't literally print
+C<$n> each time, but the name that is stored in C<$n>. This automatic
+substitution is called M<interpolation>.  Perl 6 quotes can interpolate
+variables with the dollar sigil as well as blocks of code in curly braces.
 
 X<double-quoted strings>
 X<strings; double-quoted>
@@ -416,16 +410,10 @@ C<"...">.  Single quoted strings C<'...'> do not interpolate:
 =begin programlisting
 
     my $names = 'things';
-    say 'Do not call me $names';
-    say "Do not call me $names";
-    say 'Math: { 1 + 2 }'
-    say "Math: { 1 + 2 }"
-
-    # prints
-    # Do not call me $names
-    # Do not call me things
-    # Math: { 1 + 2 }
-    # Math: 3
+    say 'Do not call me $names'; # Do not call me $names
+    say "Do not call me $names"; # Do not call me things
+    say 'Math: { 1 + 2 }'        # Math: { 1 + 2 }
+    say "Math: { 1 + 2 }"        # Math: 3
 
 =end programlisting