From 970a2c472209b1b70bc6efca68b6567a51a876ad Mon Sep 17 00:00:00 2001
From: Cale <cale.short@gmail.com>
Date: Sat, 28 Jan 2017 16:11:48 -0500
Subject: [PATCH] Update Preface and Operators (#86)

* Add file extension to open('scores')

Did not compile without this.

* Update basics.pod

Not sure if I formatted the text correctly. I just put in new lines when the line was getting too long.

* Add links to docs

* Change Parcel to List

* Mention docs.perl6

* Add example links from docs, change heading

* Add loop explanation and link to docs on pair

* put loop explanation in a sidebar
---
 src/operators.pod | 27 ++++++++++++++++++++++++---
 src/preface.pod   |  8 +++++++-
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/src/operators.pod b/src/operators.pod
index ff8adc0..5c48eac 100644
--- a/src/operators.pod
+++ b/src/operators.pod
@@ -86,8 +86,8 @@ string.  You could also write the example line as:
 
 =end programlisting
 
-Finally, the C<,> operator constructs a C<Parcel>, which is a sequence
-of objects. In this case the objects are pairs.
+Finally, the C<,> operator constructs a C<List> from its arguments.
+In this case, the C<,> is constructing a List of L<Pairs|https://docs.perl6.org/type/Pair>.
 
 X<infix>
 X<operator, infix operators>
@@ -219,8 +219,29 @@ Now all the necessary information is in place, and the chart can print:
 
 X<printf>
 
+=begin sidebar
+
 These lines loop over the items in C<@scores>, binding them to the special
-variable C<$_> one at a time. For each item, the program uses the C<printf>
+variable C<$_> one at a time. You can think of C<$_> as the English "it".
+For example, the three loops below are all functionally the same:
+
+=begin programlisting
+
+    for @scores -> $pair {
+        printf $format, $pair.key, 'X' x ($unit * $pair.value);
+    }
+    for @scores {
+        printf $format,    $_.key, 'X' x ($unit *    $_.value);
+    }
+    for @scores {
+        printf $format,      .key, 'X' x ($unit *      .value);
+    }
+
+=end programlisting
+
+=end sidebar
+
+Now, for each item, the program uses the C<printf>
 built-in function to print both the name of the player and a bar.  This
 function is similar to C<printf> in C and Perl 5.  It takes a format string,
 which specifies how to print the following parameters. If C<$label-area-width>
diff --git a/src/preface.pod b/src/preface.pod
index 98b5d8b..7f8a931 100644
--- a/src/preface.pod
+++ b/src/preface.pod
@@ -100,7 +100,7 @@ If you invoke the Rakudo compiler without an explicit script to run, it enters
 an interactive mode that allows the execution of Perl 6 statements from
 the command line. A so-called "read eval print loop" (a.k.a. REPL).
 
-=head1 Getting involved
+=head1 Getting involved / Seeking assistance
 
 If you are inspired by the contents of this book and want to contribute
 to the Perl 6 community, there are some resources available to you:
@@ -111,6 +111,12 @@ to the Perl 6 community, there are some resources available to you:
 
 The Perl 6 homepage at C<http://perl6.org/> links to many useful resources.
 
+You will occassionally see links to the L<perl6 documentation|https://docs.perl6.org/>. We suggest that
+you use this as a first resource whenever you have questions. You can type anything
+into the search bar, including unicode characters.
+
+eg. L<open|https://docs.perl6.org/routine/open> or L<<=|https://docs.perl6.org/routine/$LESS-THAN_SIGN$EQUALS_SIGN> or L<∈|https://docs.perl6.org/routine/(elem)>.
+
 =item IRC
 
 The channel C<#perl6> on C<irc.freenode.net> discusses all things Perl 6.