more 5to6 tweaks (and moved the two method call sections together)

lib/Language/5to6.pod

@@ -44,18 +44,6 @@ promising.
 
 =head2 Syntax
 
-=head3 Method call syntax
-
-If you've read any Perl 6 code at all, it's immediately obvious that
-method call syntax now uses a dot instead of an arrow:
-
-    $person->name  # Perl 5
-    $person.name   # Perl 6
-
-The dot notation is both easier to type and more of an industry standard.
-But we also wanted to steal the arrow for something else.  (Concatenation
-is now done with the C<~> operator, if you were wondering.)
-
 =head3 Whitespace
 
 Perl 5 allows a surprising amount of flexibility in the use of whitespace,
@@ -67,8 +55,8 @@ even with strict mode and warnings turned on:
         ->
         name)."!"if$greeted[$i]<1;
 
-Perl 6 also endorses programmer freedom and creativity, but balances
-syntactic flexibility against the goal of having a consistent,
+Perl 6 also endorses programmer freedom and creativity, but balanced
+syntactic flexibility against its design goal of having a consistent,
 deterministic, extensible grammar that supports single-pass parsing and
 helpful error messages, integrates features like custom operators cleanly,
 and doesn't lead programmers to accidentally misstate their intent.
@@ -93,21 +81,18 @@ I<No space allowed before the opening parenthesis of an argument list.>
 =end item
 
 =begin item
-I<No space allowed before the opening bracket of a postcircumfix (such as an array/hash subscript), or around the method call operator.>
-
-    $people [0] -> name; # Perl 5
-    @people[0].name      # Perl 6
-    @people.[0].name      # Perl 6, alternative pseudo-method style
+I<No space allowed after a prefix operator, or before a
+postfix/postcircumfix operator (including array/hash subscripts).>
 
+    $seen {$_} ++; # Perl 5
+    $seen{$_}++;   # Perl 6
 =end item
 
 =begin item
-I<No space allowed before a postfix operator.>
-
-    $i ++; # Perl 5
-    $i++;  # Perl 6
-    $i.++; # Perl 6, alternative pseudo-method style
+I<No space allowed around the method call operator.>
 
+    $customer -> name; # Perl 5
+    $customer.name;    # Perl 6
 =end item
 
 =begin item
@@ -136,9 +121,12 @@ See also L<S03#Minimal whitespace DWIMmery|http://design.perl6.org/S03.html#Mini
 
 =head3 Sigils
 
-In Perl 5, arrays and hashes use changing sigils depending on how they are being accessed. In Perl 6 the sigils are invariant, no matter how the variable is being used - you can think of them as part of the variable's name.
+In Perl 5, arrays and hashes use changing sigils depending on how they are
+being accessed. In Perl 6 the sigils are invariant, no matter how the
+variable is being used - you can think of them as part of the variable's
+name.
 
-See also L<Dereferencing>.
+(See also L<#Dereferencing>).
 
 =head4 C<$> Scalar
 
@@ -254,6 +242,9 @@ C<&foo;> I<and> C<goto &foo;> I<for re-using the caller's argument list / replac
 
 =head4 C<*> Glob
 
+=comment TODO: Research what exact use-cases still need typeglobs in Perl 5
+         today, and refactor this section to list them (with translations).
+
 In Perl 5, the C<*> sigil referred to the GLOB structure that Perl uses to
 store non-lexical variables, file handles, subs, and formats.
 
@@ -292,8 +283,33 @@ And here's just one possible Perl 6 translation:
     my $in-file = open $path or die;
     my ($line1, $line2) = read-n($in-file, 2);
 
+=head3 C«->» Method calls
+
+If you've read any Perl 6 code at all, it's immediately obvious that
+method call syntax now uses a dot instead of an arrow:
+
+    $person->name  # Perl 5
+    $person.name   # Perl 6
+
+The dot notation is both easier to type and more of an industry standard.
+But we also wanted to steal the arrow for something else.  (Concatenation
+is now done with the C<~> operator, if you were wondering.)
+
+To call a method whose name is not known until runtime:
+
+    $object->$methodname(@args);  # Perl 5
+    $object."$methodname"(@args); # Perl 6
+
+If you leave out the quotes, then Perl 6 expects C<$methodname> to contain
+a C<Method> object, rather than the simple string name of the method.
+
 =head3 Reference creation
 
+=comment TODO: Rewrite this section to make it clear that the "referencing/
+         dereferencing" metaphor does not map cleanly to the actual Perl 6
+         container system, and focus more on how one would translate or
+         replace actual code that uses references in Perl 5.
+
 In Perl 5, references to anonymous arrays and hashes and subs are returned
 during their creation. References to existing named variables and subs were
 generated with the C<\> operator.
@@ -366,17 +382,6 @@ That new feature corresponds Perl 6 C<.list> and C<.hash> methods:
 
 See S32/Containers
 
-=head3 C«$object->$methodname»
-
-To call a method whose name is not known until runtime:
-
-    $object->$methodname(@args);  # Perl 5
-    $object."$methodname"(@args); # Perl 6
-
-If you leave out the quotes, then Perl 6 expects C<$methodname> to contain
-a reference to the method itself (which is a Method object), instead of the
-simple string name of the method.
-
 =head2 Operators
 
 See S03-operators for full details on all operators.