Merge branch 'master' of https://github.com/perl6/doc

doc/Language/5to6-perlfunc.pod

@@ -408,7 +408,7 @@ Same as in Perl 5, but can also be used as a method: C<5.exp>;
 
 =item fc EXPR
 
-Looks like it would do the same thing as in Perl 5... if it were implemented.
+Looks like it does the same thing as in Perl 5.
 
 =head2 fcntl
 

doc/Language/functions.pod

@@ -597,7 +597,7 @@ Here C<a 1> calls the most specific C<Int> candidate first, and C<callwith>
 re-dispatches to the less specific C<Any> candidate.
 
 Very often, a re-dispatch passes the same argument along that the caller
-received, so there is a special routine for that: C<callsame>.G
+received, so there is a special routine for that: C<callsame>.
 
 =begin code
 multi a(Any $x) {

doc/Language/testing.pod

@@ -212,13 +212,17 @@ strings, such as C<'=='> or C<'~~'>.
 
 =item like($obtained, $expected-regex, $description?)
 
+    like 'foo', /fo/, 'foo looks like fo';
+
 Marks a test as passed if the C<$obtained> C<Str> matches the
 C<$expected-regex>.  The function accepts an optional C<$description> of the
 test.  The regex to match can be either a pre-declared C<Regex> object or
 defined directly in the argument to C<like>.
 
 =item unlike($obtained, $expected-regex, $description?)
 
+    unlike 'foo', /bar/, 'foo does not look like bar';
+
 Marks a test as failed if the C<$obtained> C<Str> matches the
 C<$expected-regex>.  The function accepts an optional C<$description> of the
 test.  The regex to match can be either a pre-declared C<Regex> object or
@@ -265,6 +269,14 @@ C<$description> of the test.
     my $eulers-constant-approx = 2.71828;
     is-approx($eulers-constant-approx, e, "approximate Euler's constant");
 
+=head2 Module loading testing
+
+=item use-ok($module)
+
+Marks a test as passed if the given C<$module> is correctly loaded.
+
+    use-ok('Full::Qualified::ModuleName');
+
 =head2 Class membership testing
 
 =item isa-ok($object, $type, $description?)

doc/Language/variables.pod

@@ -552,20 +552,22 @@ called. So it will output
 
 =end code
 
-As seen in this example, C<$> can be used as an anonymous state variable
-without an explicit C<state> declaration.
-
 As with C<my>, declaring multiple C<state> variables must be placed
 in parentheses and for declaring a single variable, parentheses may
 be omitted.
 
+=head3 The C<$> Variable
+
+As well as explicitly declared named state variables C<$> can be used
+as an anonymous state variable without an explicit C<state> declaration:
+
 =begin code
 
 perl6 -e 'sub foo() { say ++$  }; foo() for ^3'
 
 =end code
 
-produces
+produces:
 
 =begin code
 
@@ -575,26 +577,28 @@ produces
 
 =end code
 
-Furthermore, state variables are not required to exist in
-subroutines. You could, for example, use C<$> in a one-liner to
-number the lines in a file.
+There is no L<Positional> (C<@>) or L<Associative> (C<%>) equivalent, so a
+named state variable must be used for those cases.
+
+Furthermore, state variables are not required to exist in subroutines. You
+could, for example, use C<$> in a one-liner to number the lines in a file:
 
 =begin code
 
 perl6 -ne 'say ++$ ~ " $_"' example.txt
 
 =end code
 
-Finally, if you were to use multiple anonymous state variables, they would
-fuction independently.
+Each reference to C<$> within a lexical scope in effect is a separate
+variable, as illustrated by:
 
 =begin code
 
 perl6 -e '{ say ++$; say $++  } for ^5'
 
 =end code
 
-would produce
+which produces:
 
 =begin code
 
@@ -611,6 +615,38 @@ would produce
 
 =end code
 
+If you need to refer to the value of C<$> more than once within the
+scope it should be copied to a new variable, for example:
+
+=begin code
+sub foo() {
+    given ++$ {
+        when 1 {
+            say "one";
+        }
+        when 2 {
+            say "two";
+        }
+        when 3 {
+            say "three";
+        }
+        default {
+            say "many";
+        }
+    }
+}
+
+foo() for ^3;
+=end code
+
+produces:
+
+=begin code
+one
+two
+three
+=end code
+
 =head2 The C<augment> Declarator
 
 With C<augment>, you can add attributes and methods to existing classes and