Stub Variable Declarator section

Though perhaps declarators and/or scope deserve their own document(s)? At
the very least, though, they should be mentioned in variables.pod.

lib/Language/variables.pod

@@ -97,7 +97,7 @@ depends on the $.
 Dynamic variables are looked up through the caller, not through the outer
 scope. For example:
 
-=begin code
+    =begin code
     my $lexical   = 1;
     my $*dynamic1 = 10;
     my $*dynamic2 = 100;
@@ -120,7 +120,7 @@ scope. For example:
 
     # prints 1, 10, 101
     say-all();
-=end code
+    =end code
 
 The first time C<&say-all> is called, it prints "1, 10, 100" just as one would
 expect. The second time though, it prints "1, 11, 101". This is because
@@ -136,7 +136,7 @@ did not assign to the old variable as we did with C<$*dynamic2>.
 Attributes are variables that exists per instance of a class. They may be
 directly accessed from within the class via C<!>:
 
-=begin code
+    =begin code
     class Point {
         has $.x;
         has $.y;
@@ -145,7 +145,7 @@ directly accessed from within the class via C<!>:
             "($!x, $!y)"
         }
     }
-=end code
+    =end code
 
 Note how the attributes are declared as C<$.x> and C<$.y> but are still
 accessed via C<$!x> and C<$!y>. This is because in Perl 6 all attributes are
@@ -175,7 +175,7 @@ For a list of those special variables see L<Compile-time "constants">.
 The C<.> twigil isn't really for variables at all. In fact, something along the
 lines of
 
-=begin code
+    =begin code
     class Point {
         has $.x;
         has $.y;
@@ -184,7 +184,7 @@ lines of
             "($.x, $.y)" # note that we use the . instead of ! this time
         }
     }
-=end code
+    =end code
 
 just calls the methods C<x> and C<y> on C<self>, which are automatically
 generated for you because you used the C<.> twigil as you declared your
@@ -194,14 +194,14 @@ don't want this to happen, use C<$!x> and C<$!y> instead.
 The fact that the C<.> twigil just does a method call also implies that the
 following is possible too.
 
-=begin code
+    =begin code
     class SaySomething {
         method a() { say "a"; }
         method b() { $.a; }
     }
 
     SaySomething.a; # prints "a"
-=end code
+    =end code
 
 For more details on objects, classes and their attributes and methods see
 L<objects>.
@@ -218,7 +218,7 @@ Variables of the form C<$^variable> are a type of placeholder variables. They
 may be used in bare blocks to declare formal parameters to that block. So the
 block in the code
 
-    =code allow<B>
+    =for code :allow<B>
     for ^4 {
         say "B<$^seconds> follows B<$^first>";
     }
@@ -254,7 +254,7 @@ Therefore the same things that apply to variables declared using the C<^> twigil
 apply also to them (with the exception that they are not positional and
 therefore not ordered using Unicode order, of course). So this:
 
-    =code :allow<B>
+    =for code :allow<B>
     say { B<$:add> ?? $^a + $^b !! $^a - $^b }( 4, 5 ) :!add
 
 Will print "-1".
@@ -309,11 +309,43 @@ or
         ...
     }
 
+=head1 Variable Declarators and Scope
+
+Most of the time, it's enough to create a new variable using the C<my>
+keyword:
+
+    =for code :allow<B>
+    B<my> $amazing-variable = "World";
+    say "Hello $amazing-variable!"; # Hello World!
+
+However, there are many declarators that change the details of scoping
+beyond what L<#Twigils> can do.
+
+=for table
+    Declarator    Effect
+    ==========    ======
+    my            Introduces lexically scoped names
+    our           Introduces package-scoped names
+    has           Introduces attribute names
+    anon          Introduces names that are private to the construct
+    state         Introduces lexically scoped but persistent names
+    augment       Adds definitions to an existing name
+    supersede     Replaces definitions of an existing name
+
+There are also two listops that resemble declarators, but act on
+predefined variables:
+
+=for table
+    Listop
+    ======
+    temp    Restores a variable's value at the end of scope
+    let     Restores a variable's value at the end of scope if the block exists unsuccessfully
+
 =head1 Special Variables
 
 =head2 Often-Used Variables
 
-# TODO: find a better heading
+=comment TODO: find a better heading
 
 There are three special variables that are available in every block: