Better tag some skip-tests, and allow some to run

Author: coke

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/glossary.pod6

@@ -94,7 +94,7 @@ normally need to use some operator (e.g. C</> for L<Rat> or C<+> for
 L<Complex>). This allows you to use such literals in places where
 expressions are not allowed, for example, as literals in signatures:
 
-=for code :skip-test
+=for code :skip-test<syntax error>
 # Wrong, can't use an operator there:
 multi foo (1/3) { say "It's one third!" }
 =for code
@@ -131,7 +131,7 @@ that name:
 # anonymous, but knows its own name
 my $s = anon sub triple($x) { 3 * $x }
 say $s.name;        # OUTPUT: «triple␤»
-=for code :skip-test
+=for code :skip-test<error>
 say triple(42);     # OUTPUT: «Undeclared routine: triple␤»
 
 X<|API>
@@ -157,11 +157,11 @@ X<|Arity>
 The number of L<positional|/type/Positional> operands expected by an
 L<operator|#Operator>, subroutine, method or callable block.
 
-    =begin code :preamble<class Foo {};>
+    =begin code :preamble<class Foo {}>
     sub infix:<+>(Foo $a, Foo $b) { $a.Int + $b.Int }  # arity of "+" is 2
     sub frobnicate($x) { ... }                         # arity of 1
     sub the-answer() { 42 }                            # arity of 0
-    -> $key, $value { ... }                            # arity of 2
+    -> $key, $value { ... }                     # arity of 2
     =end code
 
 The arity of a C<Callable> is one of the main selectors in
@@ -279,12 +279,14 @@ Finally, if there is a variable with the same name as an intended adverbial
 pair, you don't have to specify the name twice, but just specify the adverb
 with the appropriate sigil:
 
-    =begin code :skip-test
-    :$foo          # same as foo => $foo
-    :@bar          # same as bar => @bar
-    :%mapper       # same as mapper => %mapper
-    :&test         # same as test => &test
-    =end code
+=begin table
+    variable only | same as
+  ================|==============
+    :$foo         | foo => $foo
+    :@bar         | bar => @bar
+    :%mapper      | mapper => %mapper
+    :&test        | test => &test
+=end table
 
 See also L<#Adverb>.
 

doc/Language/haskell-to-p6.pod6

@@ -80,7 +80,7 @@ and Undefined objects. Plain type objects are undefined while instantiated objec
 
 So in Perl 6 we have type constraints that indicate the definedness of a type. These are
 
-    =begin code :skip-test
+    =begin code
     Int:D; # This is a defined Int.
     Int:U; # This is an undefined Int, AKA a type object
     Int:_; # This is either defined or undefined.

doc/Language/ipc.pod6

@@ -70,7 +70,7 @@ you will want to make use of L<Proc::Async|/type/Proc::Async>. This class
 provides support for asynchronous communication with a program, as well as the
 ability to send signals to that program.
 
-    =begin code :skip-test
+    =begin code
     # Get ready to run the program
     my $log = Proc::Async.new('tail', '-f',  '/var/log/system.log');
     $log.stdout.tap(-> $buf { print $buf });

doc/Language/list.pod6

@@ -23,8 +23,9 @@ with parentheses, so:
 
 There is one exception, empty lists are created with just parenthesis:
 
-=for code :skip-test
+=for code
 ();          # This is an empty List
+=for code :skip-test<syntax error>
 (,);         # This is a syntax error
 
 Note that hanging commas are just fine as long as the beginning and
@@ -69,13 +70,14 @@ use a sigil before the parenthesis:
 Individual elements can be pulled out of a list using a subscript.  The
 first element of a list is at index number zero:
 
-    =begin code :skip-test
+    =for code
     say (1, 2)[0];  # says 1
     say (1, 2)[1];  # says 2
     say (1, 2)[2];  # says Nil
+    =for code :skip-test<syntax error>
     say (1, 2)[-1]; # Error
+    =for code
     say ((<a b>,<c d>),(<e f>,<g h>))[1;0;1]; # says "f"
-    =end code
 
 =head1 The @ sigil
 
@@ -544,7 +546,7 @@ Given the following sub declaration:
 
 Calls that pass an Array[Int] will be successful:
 
-    =begin code :skip-test
+    =begin code :preamble<sub mean(Int @a) {}>
     my Int @b = 1, 3, 5;
     say mean(@b);                       # @b is Array[Int]
     say mean(Array[Int].new(1, 3, 5));  # Anonymous Array[Int]
@@ -555,7 +557,7 @@ However, the following calls will all fail, due to passing an untyped array,
 even if the array just happens to contain Int values at the point it is
 passed:
 
-    =begin code :skip-test
+    =begin code :skip-test<compilation errors>
     my @c = 1, 3, 5;
     say mean(@c);                       # Fails, passing untyped Array
     say mean([1, 3, 5]);                # Same
@@ -566,7 +568,7 @@ Note that in any given compiler, there may be fancy, under-the-hood, ways to
 bypass the type check on arrays, so when handling untrusted input, it can be
 good practice to perform additional type checks, where it matters:
 
-    =begin code :skip-test
+    =begin code :preamble<my @a;my $i>
     for @a -> Int $i { $_++.say };
     =end code
 

doc/Language/operators.pod6

@@ -724,7 +724,7 @@ L<common mistake|/language/traps#Using_»_and_map_interchangeably> of expecting
 side-effects to occur in order. The following C<say> is B<not>
 guaranteed to produce the output in order:
 
-    =begin code :skip-test
+    =begin code :preamble<my @a>
     @a».say;  # WRONG! Could produce a␤b␤c␤ or c␤b␤a␤ or any other order
     =end code
 
@@ -1016,11 +1016,12 @@ replacing the resulting value in the left-side container.
 In most cases, this behaves identically to the postfix mutator, but the
 precedence is lower:
 
-=for code :skip-test
-my $a = -5
-say ++$a.=abs
+=for code
+my $a = -5;
+say ++$a.=abs;
 # OUTPUT: «6␤»
-say ++$a .= abs
+=for code :skip-test<error>
+say ++$a .= abs;
 # OUTPUT: «Cannot modify an immutable Int␤
 #           in block <unit> at <tmp> line 1␤␤»
 
@@ -1360,7 +1361,7 @@ restored to its original value.
 
 You can also assign immediately as part of the call to temp:
 
-=begin code :skip-test
+=begin code :preamble<my $a>
 temp $a = "five";
 =end code
 
@@ -1887,8 +1888,7 @@ this operator is not arithmetically symmetrical (doesn't do ± Δ):
 
 The tolerance is supposed to be modifiable via an adverb:
 
-=comment RT #128210
-=begin code :skip-test
+=begin code :skip-test<RT #128210>
 my ($x, $y) = 42, 42.1;
 say $x =~= $y :tolerance(.1);
 =end code

doc/Language/rb-nutshell.pod6

@@ -71,7 +71,7 @@ coding styles:
 =begin item
 I<No space allowed before the opening parenthesis of an argument list.>
 
-=begin code :skip-test
+=begin code :skip-test<error>
 foo (3, 4, 1); # Not right in Ruby or Perl 6 (in Perl 6 this would
                # try to pass a single argument of type List to foo)
 =end code
@@ -362,17 +362,19 @@ L<Captures|/type/Capture>.
 Perl 6 additionally uses "twigils", which are further indicators about the
 variable and go between the sigil and the rest of the variable name. Examples:
 
-=begin code :skip-test
-$foo     # Scalar with no twigil
-$!foo    # Private instance variable
-$.foo    # Instance variable accessor
-$*foo    # Dynamically scoped variable
-$^foo    # A positional (placeholder) parameter to a block
-$:foo    # A named (placeholder) parameter to a block
-$=foo    # POD (documentation) variables
-$?FILE   # Current source filename. The ? twigil indicates a compile-time value
-$~foo    # Sublanguage seen by parser, uncommon
-=end code
+=begin table
+Variable | Description
+=========|============
+$foo     | Scalar with no twigil
+$!foo    | Private instance variable
+$.foo    | Instance variable accessor
+$*foo    | Dynamically scoped variable
+$^foo    | A positional (placeholder) parameter to a block
+$:foo    | A named (placeholder) parameter to a block
+$=foo    | POD (documentation) variables
+$?FILE   | Current source filename. The ? twigil indicates a compile-time value
+$~foo    | Sublanguage seen by parser, uncommon
+=end table
 
 Though each of these examples use the C<$> sigil, most could use C<@>
 (Positional) or C<%> (Associative).
@@ -393,7 +395,7 @@ Perl 6 has I<colon-pair> syntax, which can sometimes look like Ruby symbols.
 =for code :lang<ruby>
 :age            # Ruby symbol
 
-=begin code :skip-test
+=begin code
 # All of these are equivalent for Perl 6
 :age            ;# Perl 6 pair with implicit True value
 :age(True)      ;# Perl 6 pair with explicit True value
@@ -480,7 +482,7 @@ See L<S03/Smartmatching|https://design.perl6.org/S03.html#Smart_matching> for mo
 In Perl 6, these single-character ops have been removed, and replaced by
 two-character ops which coerce their arguments to the needed context.
 
-=begin code :skip-test
+=begin code :lang<text>
 # Infix ops (two arguments; one on each side of the op)
 +&  +|  +^  And Or Xor: Numeric
 ~&  ~|  ~^  And Or Xor: String
@@ -1046,7 +1048,7 @@ $ PERL6LIB="/some/module/lib" perl6 program.p6
 As with Ruby, if you don't specify C<PERL6LIB>, you need to specify the
 library path within the program via the C<use lib> pragma:
 
-=for code :skip-test
+=for code :skip-test<can't use lib here>
 # Ruby and Perl 6
 use lib '/some/module/lib';
 
@@ -1062,18 +1064,18 @@ 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>:
 
-=for code :skip-test
+=for code :skip-test<can't unit here>
 unit module Bar; # remainder of the file is in module Bar { ... }
 
-=for code :skip-test
+=for code
 sub foo($a) is export { say "foo $a" }
 sub bar($b) is export { say "bar $b" }
 sub baz($z) { say "baz $z" }
 
 To use this module, simply C<use Bar> and the functions C<foo> and C<bar>
 will be available:
 
-=for code :skip-test
+=for code :skip-test<can't use>
 use Bar;
 foo(1);    #=> "foo 1"
 bar(2);    #=> "bar 2"
@@ -1082,7 +1084,7 @@ If you try to use C<baz> an "Undeclared routine" error is raised at compile time
 
 Some modules allow for selectively importing functions, which would look like:
 
-=begin code :skip-test
+=begin code :skip-test<can't use>
 use Bar <foo>; # Import only foo
 foo(1);        #=> "foo 1"
 bar(2);        # Error!

doc/Programs/02-reading-docs.pod6

@@ -26,7 +26,7 @@ p6doc [switches] [arguments]
 
 With no switches or arguments, C<p6doc> lists its help to C<$*OUT> (C<stdout>):
 
-=begin code :skip-test
+=begin code :lang<output>
 You want to maintain the index?
 To build an index for 'p6doc -f'
           p6doc build

doc/Type/Buf.pod6

@@ -118,7 +118,7 @@ Adds elements at the end of the buffer
 
 Extracts the last element of the buffer
 
-    =for code :skip-test
+    =for code :preamble<my $bú>
     say $bú.pop(); # OUTPUT: «8»
     say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5)»
 
@@ -128,7 +128,7 @@ Extracts the last element of the buffer
 
 Appends at the end of the buffer
 
-    =for code :skip-test
+    =for code :preamble<my $bú; my @φ>
     $bú.append( @φ[5..10] );
     say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»
 
@@ -138,7 +138,7 @@ Appends at the end of the buffer
 
 Adds elements at the beginning of the buffer
 
-    =for code :skip-test
+    =for code :preamble<my $bú>
     $bú.prepend( 0 );
     say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»
 
@@ -148,7 +148,7 @@ Adds elements at the beginning of the buffer
 
 Takes out the first element of the buffer
 
-    =for code :skip-test
+    =for code :preamble<my $bú>
     $bú.shift();
     say $bú.perl; # OUTPUT: «Buf.new(1,1,2,3,5,8,13,21,34,55,89)»
 
@@ -158,7 +158,7 @@ Takes out the first element of the buffer
 
 Adds elements at the beginning of the buffer
 
-    =for code :skip-test
+    =for code :preamble<my $bú>
     $bú.unshift( 0 );
     say $bú.perl; # OUTPUT: «Buf.new(0,1,1,2,3,5,8,13,21,34,55,89)»
 
@@ -168,7 +168,7 @@ Adds elements at the beginning of the buffer
 
 Substitutes elements of the buffer by other elements
 
-    =for code :skip-test
+    =for code :preamble<my $bú>
     $bú.splice:  0, 3, <3 2 1>;
     say $bú.perl; # OUTPUT: «Buf.new(3,2,1,2,3,5,8,13,21,34,55,89)»