Merge pull request #1 from perl6/master

update

Author: finanalyst

assets/sass/style.scss

@@ -512,6 +512,17 @@ table#TOC {
         }
     }
 
+    tr.toc-level-4 {
+        td {
+            padding-top: 2pt;
+            font-size: 0.8em;
+        }
+
+        td.toc-text {
+            padding-left: 16px;
+        }
+    }
+
     td.toc-number {
         display: none;
     }
@@ -612,4 +623,4 @@ a[href*="//"]:not([href*="perl6.org"])::after,
   position: relative;
   overflow: hidden;
   width: 100%;
-}
+}

doc/Language/5to6-nutshell.pod6

@@ -7,7 +7,7 @@
 This page attempts to provide a fast-path to the changes in syntax and
 semantics from Perl 5 to Perl 6. Whatever worked in Perl 5 and must be
 written differently in Perl 6, should be listed here (whereas many
-I<new> Perl 6 features and idioms are not).
+I<new> Perl 6 features and idioms need not).
 
 Hence this should not be mistaken for a beginner tutorial or a
 promotional overview of Perl 6; it is intended as a technical reference
@@ -284,12 +284,13 @@ first $coderef, @values, :k;
 =end item
 
 =begin item
-C<&foo;> I<and> C<goto &foo;> I<for re-using the caller's argument list /
-replacing the caller in the call stack>. Perl 6 can use either L<C<callsame>|/language/functions#index-entry-dispatch_callsame> for re-dispatching or L<C<nextsame>|/language/functions#index-entry-dispatch_nextsame> and L<C<nextwith>|/language/functions#index-entry-dispatch_nextwith>, which have no exact equivalent in Perl 5.
-
-=begin comment
-    # TODO: Suggest .nextsame and .nextwith once they've been implemented in Rakudo.
-=end comment
+C<&foo;> I<and> C<goto &foo;> I<for re-using the caller's argument
+list / replacing the caller in the call stack>. Perl 6 can use either
+L<C<callsame>|/language/functions#index-entry-dispatch_callsame> for
+re-dispatching or
+L<C<nextsame>|/language/functions#index-entry-dispatch_nextsame> and
+L<C<nextwith>|/language/functions#index-entry-dispatch_nextwith>, which have no
+exact equivalent in Perl 5.
 
 =for code :lang<perl5>
 sub foo { say "before"; &bar;     say "after" } # Perl 5
@@ -320,8 +321,8 @@ foo(3); # /language/functions#index-entry-dispatch_callsame
 In Perl 5, the C<*> sigil referred to the GLOB structure that Perl uses to
 store non-lexical variables, filehandles, subs, and formats.
 
-(This should not be confused with the Perl 5 built-in C<glob()> function,
-which reads filenames from a directory).
+N<This should not be confused with the Perl 5 built-in C<glob()> function,
+which reads filenames from a directory.>
 
 You are most likely to encounter a GLOB in code written on a early Perl
 version that does not support lexical filehandles, when a filehandle needed
@@ -1126,6 +1127,43 @@ As with Perl 5, comments work as usual in regexes.
 
     / word #`(match lexical "word") /
 
+=head1 BEGIN, UNITCHECK, CHECK, INIT and END
+
+Except for C<UNITCHECK>, all of these special blocks exist in Perl 6 as well.
+In Perl 6, these are called L<Phasers|/language/phasers>.   But there are some
+differences!
+
+=head2 UNITCHECK becomes CHECK
+
+There is currently B<no> direct equivalent of C<CHECK> blocks in Perl 6.
+The C<CHECK> phaser in Perl 6 has the same semantics as the C<UNITCHECK>
+block in Perl 5: it gets run whenever the compilation unit in which it
+occurs, has finished parsing.  This is considered a much saner semantic
+than the current semantics of C<CHECK> blocks in Perl 5.  But for
+compatibility reasons, it was impossible to change the semantics of C<CHECK>
+blocks in Perl 5, so a C<UNITCHECK> block was introduced in 5.10.  So it
+was decided that the Perl 6 C<CHECK> phaser would follow the saner Perl 5
+C<UNITCHECK> semantics.
+
+=head2 No block necessary
+
+In Perl 5, these special blocks B<must> have curly braces, which implies a
+separate scope.  In Perl 6 this is not necessary, allowing these special
+blocks to share their scope with the surrounding lexical scope.
+
+=for code :lang<perl5>
+my $foo;             # Perl 5
+BEGIN { $foo = 42 }
+=for code
+BEGIN my $foo = 42;  # Perl 6
+
+=head2 Changed semantics with regards to precompilation
+
+If you put C<BEGIN> and C<CHECK> phasers in a module that is being
+precompiled, then these phasers will B<only> be executed during precompilation
+and B<not> when a precompiled module is being loaded.  So when porting module
+code from Perl 5, you may need to change C<BEGIN> and C<CHECK> blocks to
+C<INIT> blocks to ensure that they're run when loading that module.
 
 =head1 Pragmas
 
@@ -1218,7 +1256,8 @@ tau, pi, e, i; # built-in constants in Perl 6
 
 =head3 C<encoding>
 
-TODO Allows you to write your script in non-ascii or non-utf8.
+Allows you to write your script in non-ascii or non-utf8. Perl 6 uses, for the
+time being, only utf8 for its scripts.
 
 =head3 C<integer>
 
@@ -1233,9 +1272,9 @@ say $foo * $bar;    # uses native integer multiplication
 
 =head3 C<lib>
 
-Manipulate where modules are looked up at compile time.  The underlying logic
-is B<very> different from Perl 5, but in most cases, C<use lib> in Perl 6
-works the same as in Perl 5.
+Manipulate where modules are looked up at compile time.  The underlying logic is
+B<very> different from Perl 5, but in the case you are using a equivalent
+syntax, C<use lib> in Perl 6 works the same as in Perl 5.
 
 =head3 C<mro>
 
@@ -1332,7 +1371,8 @@ This is now the default behavior.
 
 =item C<-S>, C<-T>.
 
-This has been eliminated. Several ways to L<replicate "taint" mode are discussed in Reddit|https://www.reddit.com/r/perl6/comments/718z4o/taint_mode_for_perl_6/>.
+This has been eliminated. Several ways to
+L<replicate "taint" mode are discussed in Reddit|https://www.reddit.com/r/perl6/comments/718z4o/taint_mode_for_perl_6/>.
 
 =head1 File-related operations
 
@@ -1370,7 +1410,7 @@ the C<lines> method on the result of C<slurp> instead:
 
     my @lines = "test-file".IO.slurp.lines;  # also auto-chomps
 
-=head2 Trapping the standard output of executables.
+=head2 Capturing the standard output of executables.
 
 Whereas in Perl 5 you would do:
 
@@ -1489,7 +1529,7 @@ C<is export> role on the relevant subs and I<all> subs with this role are
 then exported.  Hence, the following module C<Bar> exports the subs C<foo>
 and C<bar> but not C<baz>:
 
-=begin code :skip-test
+=begin code :skip-test<unit>
 unit module Bar;
 
 sub foo($a) is export { say "foo $a" }

doc/Language/5to6-perlfunc.pod6

@@ -1337,7 +1337,7 @@ much as possible.
 
 These survive the transition to Perl 6. Some notes:
 
-=for code :skip-test
+=for code :lang<perl5>
 q/.../;  # is still equivalent to using single quotes.
 qq/.../; # is still equivalent to using double quotes.
 qw/.../; # is more commonly rendered as C<< <...> >> in Perl 6.

doc/Language/classtut.pod6

@@ -316,7 +316,7 @@ possible to predict the moment when attribute initialization will be executed,
 because it can take place during compilation, runtime or both, especially when
 importing the class using the L<use|/syntax/use> keyword.
 
-    =begin code :skip-test
+    =begin code :preamble<class Foo {}; sub some_complicated_subroutine {}>
     class HaveStaticAttr {
           my Foo $.foo = some_complicated_subroutine;
     }
@@ -493,7 +493,7 @@ After creating a class, you can create instances of the class.  Declaring a
 custom constructor provides a simple way of declaring tasks along with their
 dependencies. To create a single task with no dependencies, write:
 
-=for code :skip-test
+=for code :preamble<class Task {}>
 my $eat = Task.new({ say 'eating dinner. NOM!' });
 
 An earlier section explained that declaring the class C<Task> installed a
@@ -505,7 +505,7 @@ modifying or accessing an existing object.
 
 Unfortunately, dinner never magically happens.  It has dependent tasks:
 
-    =begin code :skip-test
+    =begin code :preamble<class Task {}>
     my $eat =
         Task.new({ say 'eating dinner. NOM!' },
             Task.new({ say 'making dinner' },
@@ -523,7 +523,7 @@ Notice how the custom constructor and sensible use of whitespace makes task depe
 Finally, the C<perform> method call recursively calls the C<perform> method
 on the various other dependencies in order, giving the output:
 
-    =begin code :skip-test
+    =begin code :lang<output>
     making some money
     going to the store
     buying food
@@ -563,7 +563,7 @@ other means, such as attribute accessors.
 Now, any object of type Programmer can make use of the methods and accessors
 defined in the Employee class as though they were from the Programmer class.
 
-    =begin code :skip-test
+    =begin code :preamble<class Programmer {}>
     my $programmer = Programmer.new(
         salary => 100_000,
         known_languages => <Perl5 Perl6 Erlang C++>,
@@ -580,7 +580,7 @@ Of course, classes can override methods and attributes defined by parent
 classes by defining their own.  The example below demonstrates the C<Baker>
 class overriding the C<Cook>'s C<cook> method.
 
-    =begin code :skip-test
+    =begin code :preamble<class Employee {}>
     class Cook is Employee {
         has @.utensils  is rw;
         has @.cookbooks is rw;
@@ -636,7 +636,7 @@ classes when looking up a method to search for.  Perl 6 uses the L<C3 algorithm
 multiple inheritance hierarchies, which is better than depth-first search
 for handling multiple inheritance.
 
-    =begin code :skip-test
+    =begin code :preamble<class Programmer {}; class Cook {}>
     class GeekCook is Programmer is Cook {
         method new( *%params ) {
             push( %params<cookbooks>, "Cooking for Geeks" );
@@ -671,7 +671,7 @@ Classes to be inherited from can be listed in the class declaration body by
 prefixing the C<is> trait with C<also>. This also works for the role
 composition trait C<does>.
 
-    =begin code :skip-test
+    =begin code :preamble<class Programmer {}; class Cook {}>
     class GeekCook {
         also is Programmer;
         also is Cook;
@@ -692,18 +692,17 @@ a controlling object) for some properties, such as its type.
 Given an object C<$o> and the class definitions from the previous sections,
 we can ask it a few questions:
 
-    =begin code :skip-test
+    =begin code :preamble<my $o; class Employee {}; class GeekCook {}>
     if $o ~~ Employee { say "It's an employee" };
     if $o ~~ GeekCook { say "It's a geeky cook" };
-    say $o.WHAT;
     say $o.perl;
     say $o.^methods(:local)».name.join(', ');
     say $o.^name;
     =end code
 
 The output can look like this:
 
-    =begin code :skip-test
+    =begin code :lang<output>
     It's an employee
     (Programmer)
     Programmer.new(known_languages => ["Perl", "Python", "Pascal"],
@@ -737,7 +736,7 @@ it is actually a method call on its I<meta class>, which is a class managing
 the properties of the C<Programmer> class – or any other class you are
 interested in. This meta class enables other ways of introspection too:
 
-=for code :skip-test
+=for code :preamble<my $o>
 say $o.^attributes.join(', ');
 say $o.^parents.map({ $_.^name }).join(', ');