Split out EXAMPLES.md

Part of #1302

Author: coke

CONTRIBUTING.md

@@ -15,8 +15,7 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).
 # TABLE OF CONTENTS
 - [General principles](#general-principles)
 - [Documenting types](#documenting-types)
-- [Testing examples](#testing-examples)
-    - [Skipping tests](#skipping-tests)
+- [Writing and Testing examples](#writing-and-testing-examples)
 - [Debug mode](#debug-mode)
     - [Invisible index anchors](#invisible-index-anchors)
     - [Viewport size](#viewport-size)
@@ -113,70 +112,9 @@ tests about whitespace and spelling that might be difficult to get right
 on an initial commit, and shouldn't be considered to break the build. If
 you're contributing a patch or pull request, please make sure this passes.
 
-## Testing examples
+## Writing and testing examples
 
-To export examples from all .pod6-files use `make extract-examples`. To run
-individual tests pick the right .p6-file from `examples/` as a parameter to
-`perl6`.
-
-### Skipping tests
-
-Some examples fail with compile time exceptions and would interrupt the test
-for a file. Use the pod-config option `skip-test` to skip them.
-
-    =begin code :skip-test
-        your-example-here();
-    =end code
-
-In other cases, the snippet of code isn't Perl 6; in that case, mark the
-language, which will also skip the test.
-
-    =begin code :lang<tcl>
-        puts "this is not Perl"
-    =end code
-
-When writing examples, it's often helpful to refer to things that aren't
-defined in that snippet; you don't want to have to have a full working
-example in the code.
-
-    =begin code :preamble<no strict;>
-        $x = pi;
-    =end code
-
-    =begin code :preamble<my $x; sub frob {...};>
-        $x = frob();
-    =end code
-
-You can disable certain checks with :ok-test, allowing us to
-generally fail certain styles, but allow them when it is explicitly the
-point of the code.
-
-    =begin code :ok-test<WHAT>
-        say 42.WHAT;
-    =end
-
-If a code snippet looks like a method declaration, it's automatically
-wrapped in additional code so you don't have to specify a body in the docs.
-Multi-line method signatures are much harder to detect, so if you have a
-method body that spans likes, use the :method tag:
-
-    =begin code :method
-        method arg (
-            Bool $one,
-            Bool $two
-        )
-    =end code
-
-
-### Catching expected exception
-
-Some tests will throw exceptions that would stop the execution of the extracted
-test file. Use the pod-option `catch-all` to have a default handler installed
-for a single example.
-
-    =begin code :catch-all
-        exception-generator-here();
-    =end code
+See [EXAMPLES].
 
 ## Testing method completeness
 

EXAMPLES.md

@@ -0,0 +1,81 @@
+## Writing Examples
+
+Please use code blocks to highlight example code; any indented blocks
+are considered to be code, but you can use the `=for code` directive, or a
+combination of `=begin code` and `=end code` to better control which
+blocks are considered.
+
+## Testing Examples
+
+The file `xt/examples-compilation.t` will test code. This file is run
+as part of `make xtest`. Each sample 
+
+Note that method signatures are also compiled. They have an implied block
+added to insure valid compilation.
+
+Care is taken to wrap the sample code in enough boilerplate so that no
+runtime code is executed, and that a class is available if needed.
+
+## Skipping or finessing tests
+
+While our goal is to test every example of Perl 6 in the repository, some
+blocks are not easy to test. Here are some ways you can skip the test or
+finesse it. 
+
+### Other languages
+
+We're just testing Perl 6 here: to skip another language, use `:lang`
+
+    =begin code :lang<tcl>
+        puts "this is not Perl"
+    =end code
+
+### Allow .WHAT
+
+One of the checks is to dissaude using `.WHAT` in tests; However, rarely
+that is the explicit point of the test. You can whitelist it:
+
+    =begin code :ok-test<WHAT>
+        say 42.WHAT;
+    =end
+
+### Methods
+
+If a code snippet looks like a method declaration, it's automatically
+wrapped in additional code so you don't have to specify a body in the docs.
+Multi-line method signatures are much harder to detect, so if you have a
+method body that spans likes, use the :method tag:
+
+    =begin code :method
+        method arg (
+            Bool $one,
+            Bool $two
+        )
+    =end code
+
+This helps keep the method detection logic in the test code simple.
+
+### Preambles
+
+When writing examples, it's often helpful to refer to things that aren't
+defined in that snippet; you don't want to have to have a full working
+example in the code.
+
+    =begin code :preamble<no strict;>
+        $x = pi;
+    =end code
+
+    =begin code :preamble<my $x; sub frob {...};>
+        $x = frob();
+    =end code
+
+### Failures
+
+Some examples fail with compile time exceptions and would interrupt the test
+for a file. Use the pod-config option `skip-test` to skip them. When possible,
+specify a reason why you have to use this; it should be considered a last
+resort, and many examples might be amenable to using one of the previous annotations.
+
+    =begin code :skip-test<compile time error>
+        if 1 "missing a block";
+    =end code