Merge pull request #3457 from uzluisf/master

Revise 'Raku by example 101' page

Author: JJ

doc/Language/101-basics.pod6

@@ -1,6 +1,6 @@
 =begin pod :kind("Language") :subkind("Language") :category("beginning")
 
-=TITLE  Raku by example P6-101
+=TITLE  Raku by example 101
 
 =SUBTITLE A basic introductory example of a Raku program
 
@@ -29,20 +29,15 @@ Here's one way to solve that problem in Raku:
 =begin code :solo
 use v6;
 
-# Single line comments like this one start with '#'.
-my $file  = open 'scores.txt'; # Comments can also follow code on a line.
-my @names = $file.get.words;
+# start by printing out the header.
+say "Tournament Results:\n";
+
+my $file  = open 'scores.txt'; # get filehandle and...
+my @names = $file.get.words;   # ... get players.
 
 my %matches;
 my %sets;
 
-#`(  Multiple line comments
-     are denoted by a #, then `, then one of {,[, or (
-     and closed by the corresponding },], and ).
-     Nested pairs of square brackets, curly braces and
-     parentheses are matched, so
-     something like this () will not end the comment.
-     In this case, closed by: )
 for $file.lines -> $line {
     next unless $line; # ignore any empty lines
 
@@ -60,9 +55,6 @@ for $file.lines -> $line {
     }
 }
 
-#`[
-  This is another multi-line comment. ]
-#`{ So is this, though it's not actually multi-line. }
 my @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;
 
 for @sorted -> $n {
@@ -74,37 +66,55 @@ for @sorted -> $n {
 
 This produces the output:
 
-=for code :lang<text>
+=begin code :lang<text>
+Tournament Results:
+
 Ana has won 2 matches and 8 sets
 Dave has won 2 matches and 6 sets
 Charlie has won 1 match and 4 sets
 Beth has won 1 match and 4 sets
+=end code
 
-=head3 X<C<v6>|v6 (Basics)>
+=head1 Pragma X<C<v6>|v6 (Basics)>
+
+=begin code
+use v6;
+=end code
 
 Every Raku program should begin with a line similar to C<use v6;>. This line
 tells the compiler which version of Raku the program expects. For instance,
 6.c is an example of a Raku version. Should you accidentally run the file
 with Perl, you'll get a helpful error message.
 
-=head3 X<C<statement>|statement (Basics)>
+=head1 X<Statements|statement (Basics)>
+
+=begin code
+# start by printing out the header.
+say "Tournament Results:\n";
+=end code
 
 A Raku program consists of zero or more statements. A I<statement> ends with
-a semicolon or a curly brace at the end of a line:
+a semicolon or a curly brace at the end of a line.
+
+In Raku, single line comments start with a single hash character C<#> and
+extend until the end of the line. Raku also supports
+L<multi-line/embedded comments|/language/syntax#Multi-line_/_embedded_comments>.
+The compiler doesn't evaluate comments as program text and they're only intended
+for human readers.
+
+=head1 X<Lexical scope|my (Basics)> and X<block>
 
 =begin code
 my $file = open 'scores.txt';
 =end code
 
-=head3 X<C<lexical>> and X<C<block>>
-
 C<my> declares a lexical variable, which are visible only in the current block
 from the point of declaration to the end of the block. If there's no enclosing
 block, it's visible throughout the remainder of the file (which would
 effectively be the enclosing block). A block is any part of the code enclosed
 between curly braces C<{ }>.
 
-=head3 X<C<sigil>> and X<C<identifier>|identifier (Basics)>
+=head2 X<Sigils|sigils (Basics)> and X<identifiers|identifiers (Basics)>
 
 A variable name begins with a I<sigil>, which is a non-alpha-numeric
 symbol such as C<$>, C<@>, C<%>, or C<&> E<mdash> or occasionally the double
@@ -115,7 +125,7 @@ consist of letters, digits and the underscore. Between letters you can
 also use a dash C<-> or an apostrophe C<'>, so C<isn't> and
 C<double-click> are valid identifiers.
 
-=head3 X<C<scalar>>
+=head2 X<Scalar|scalar (Basics)>
 
 Sigils indicate the default access method for a variable. Variables
 with the C<@> sigil are accessed positionally; variables with the C<%>
@@ -126,25 +136,25 @@ C<Array> or a C<Hash>; the C<$> sigil signifies that it should be
 treated as a single value, even in a context that expects multiple
 values (as with an C<Array> or C<Hash>).
 
-=head3 X<C<filehandle>> and X<C<assignment>>
+=head2 X<Filehandle|filehandle (Basics)> and X<assignment|assignment (Basics)>
 
 The built-in function C<open> opens a file, here named C<scores.txt>,
 and returns a I<filehandle> E<mdash> an object representing that file. The
-equality sign C<=> I<assigns> that filehandle to the variable on the left,
+assignment operator C<=> I<assigns> that filehandle to the variable on the left,
 which means that C<$file> now stores the filehandle.
 
-=head3 X<C<string literal>>
+=head2 X<String literals|string literal (Basics)>
 
 C<'scores.txt'> is a I<string literal>. A string is a piece of text, and a
 string literal is a string which appears directly in the program. In this line,
 it's the argument provided to C<open>.
 
-=begin code :preamble<my $file>
+=head1 X<Arrays|array (Basics)>, X<methods|method (Basics)> and X<invocants|invocant (Basics)>
+
+=begin code :preamble<my @names>
 my @names = $file.get.words;
 =end code
 
-=head3 X<C<array>>, X<C<method>|method (Basics)> and X<C<invocant>|invocant (Basics)>
-
 The right-hand side calls a I<method> E<mdash> a named group of
 behavior E<mdash> named C<get> on the filehandle stored in C<$file>. The C<get>
 method reads and returns one line from the file, removing the line ending. If
@@ -159,13 +169,13 @@ Finally, this list gets stored in the L<Array|/type/Array> C<@names>.
 The C<@> sigil marks the declared variable as an C<Array>.
 Arrays store ordered lists.
 
+=head1 X<Hashes|hash (Basics)>
+
 =begin code
 my %matches;
 my %sets;
 =end code
 
-=head3 X<C<hash>>
-
 These two lines of code declare two hashes. The C<%> sigil marks each variable
 as a C<Hash>. A C<Hash> is an unordered collection of key-value pairs. Other
 programming languages call that a I<hash table>, I<dictionary>, or I<map>.
@@ -176,14 +186,14 @@ In the score counting program, C<%matches> stores the number of matches each
 player has won. C<%sets> stores the number of sets each player has won. Both
 of these hashes are indexed by the player's name.
 
+=head1 X<C<for>|for (Basics)> and X<blocks|block (Basics)>
+
 =begin code :preamble<my $file>
 for $file.lines -> $line {
     ...
 }
 =end code
 
-=head3 X<C<for>|for (Basics)> and X<C<block>>
-
 C<for> produces a loop that runs the I<block> delimited by curly braces
 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
@@ -259,24 +269,30 @@ there is no need to include a separate statement like C<%sets{$p1} = 0> before
 you can meaningfully add C<$r1> to it. We'll look at this is behavior in a bit
 more detail below.
 
+=head2 X<C<Any>|Any (Basics)> and X<C<+=>|+= (Basics)>
 
-=head3 X<C<Any>| Any (Basics)> and X<C<+=>>
+=begin code :preamble<my %sets;my $p1;my $p2;my $r1;my $r2>
+%sets{$p1} += $r1;
+%sets{$p2} += $r2;
+=end code
 
-C<+= $r1> means I<increase the value in the variable on the left by $r1>. In the
-first iteration C<%sets{$p1}> is not yet defined, so it defaults to a special
+C<%sets{$p1} += $r1> means I<increase the value in the variable on the left by $r1>.
+In the first iteration C<%sets{$p1}> is not yet defined, so it defaults to a special
 value called C<Any>. The C<+=> operator conveniently treats the undefined value
 C<Any> as a number with the value C<0>, allowing it to sensibly add some other
 value to it. To perform the addition, the strings C<$r1>, C<$r2>, etc. are
 automatically converted to numbers, as addition is a numeric operation.
 
-=head3 X<C<fat arrow>>,  X<C<pair>> and X<C<autovivification>>
+=head2 X<Fat arrow|fat arrow (Basics)>, X<pairs|pair (Basics)> and X<autovivification|autovivification (Basics)>
 
 Before these two lines execute, C<%sets> is empty. Adding to an entry that is
 not in the hash yet will cause that entry to spring into existence
-just-in-time, with a value starting at zero. (This is 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 the key and the value
-in a C<Pair>.)
+just-in-time, with a value starting at zero. This behavior is known as
+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 the
+key and the value in a C<Pair>.)
+
+=head2 X<Postincrement|postincrement (Basics)> and X<preincrement|preincrement (Basics)>
 
 =begin code :preamble<my $r1;my $r2;my $p1;my $p2;my %matches;>
 if $r1 > $r2 {
@@ -291,20 +307,18 @@ If C<$r1> is not larger than C<$r2>, C<%matches{$p2}> increments. Just as in
 the case of C<+=>, if either hash value did not exist previously, it is
 autovivified by the increment operation.
 
-=head3 X<C<postincrement>> and X<C<preincrement>>
-
 C<$thing++> is a variant of C<$thing += 1>; it differs from the latter in that
 the return value of the expression is C<$thing> I<before> the increment, and not
 the incremented value. As in many other programming languages, you can use C<++>
 as a prefix. Then it returns the incremented value: C<my $x = 1; say ++$x>
 prints C<2>.
 
+=head1 X<Topic variable|topic variable (Basics)>
+
 =begin code :preamble<my @names;my %sets;my %matches>
 my @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;
 =end code
 
-=head3 X<C<variables, $_>>
-
 This line consists of three individually simple steps. An array's C<sort>
 method returns a sorted version of the array's contents. However, the default
 sort on an array sorts by its contents. To print player names in winner-first
@@ -313,7 +327,7 @@ names. The C<sort> method's argument is a I<block> used to transform the array
 elements (the names of players) to the data by which to sort. The array items
 are passed in through the I<topic variable> C<$_>.
 
-=head3 X<C<block>|block (Basics)>
+=head2 Blocks
 
 You have seen blocks before: both the C<for> loop C<< -> $line { ... } >> and
 the C<if> statement worked on blocks. A block is a self-contained piece of
@@ -325,13 +339,13 @@ have both won two matches. That simple sort doesn't account for the number of
 sets won, which is the secondary criterion to decide who has won the
 tournament.
 
-=head3 X<C<stable sort>>
+=head2 Stable sort
 
 When two array items have the same value, C<sort> leaves them in the same order
 as it found them. Computer scientists call this a I<stable sort>. The program
 takes advantage of this property of Raku'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 matches won.
+sorting twice: first by the number of sets won (the primary criterion), then
+by the number of matches won (the secondary criterion).
 
 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 no one has
@@ -342,6 +356,8 @@ C<sort> sorts in ascending order, from smallest to largest. This is the
 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>.
 
+=head1 Standard output
+
 =begin code :preamble<my @sorted;my %matches;my %sets>
 for @sorted -> $n {
     my $match-noun = %matches{$n} == 1 ?? 'match' !! 'matches';
@@ -350,8 +366,6 @@ for @sorted -> $n {
 }
 =end code
 
-=head3 X<C<say>| say (Basics)>, X<C<print>| say (Basics)> and X<C<put>|put (Basics)>
-
 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. Read this code as "For each
 element of sorted, set C<$n> to the element, then execute the contents of the
@@ -370,16 +384,16 @@ want the newline at the end.)
 Note that C<say> will truncate certain data structures by calling the C<.gist>
 method so C<put> is safer if you want exact output.
 
-=head3 X<C<interpolation>>
+=head2 X<Variable interpolation|variable interpolation (Basics)>
 
 When you run the program, you'll see that C<say> doesn't print the contents of
 that string verbatim. In place of C<$n> it prints the contents of the variable
-C<$n> E<mdash> the names of players stored in C<$n>. This automatic substitution
-of code with its contents is I<interpolation>. This interpolation happens only
-in strings delimited by double quotes C<"...">. Single quoted strings C<'...'>
-do not interpolate:
+C<$n> E<mdash> a player's name stored in C<$n>. This automatic substitution
+of code with its contents is called I<interpolation>. This interpolation happens
+only in strings delimited by double quotes C<"...">. Single quoted strings
+C<'...'> do not interpolate:
 
-=head3 X<C<double-quoted strings>> and X<C<single-quoted strings>>
+=head2 X<Double-quoted strings|double-quoted strings (Basics)> and X<single-quoted strings|single-quoted strings (Basics)>
 
 =begin code
 my $names = 'things';
@@ -389,7 +403,7 @@ say "Do not call me $names"; # OUTPUT: «Do not call me things␤»
 
 Double quoted strings in Raku can interpolate variables with the C<$>
 sigil as well as blocks of code in curly braces. Since any arbitrary
-Perl code can appear within curly braces, C<Array>s and C<Hash>es may be
+Raku code can appear within curly braces, C<Array>s and C<Hash>es may be
 interpolated by placing them within curly braces.
 
 Arrays within curly braces are interpolated with a single space character
@@ -429,7 +443,7 @@ followed by a postcircumfix E<mdash> a bracketing pair that follows a
 statement. It's also ok to have a method call between the variable name and
 the postcircumfix.
 
-=head3 X<C<Zen slice>| Zen slice (Basics)>
+=head1 Zen slices
 
 =begin code
 my @flavors = <vanilla peach>;
@@ -447,7 +461,6 @@ say "we have @flavors.sort.join(', ')";
                                   # OUTPUT: «we have peach, vanilla␤»
 =end code
 
-
 =head1 Exercises
 
 B<1.> The input format of the example program is redundant: the first line