Add test to avoid extra code indentation

Fix all instances found with new test.
Add note about code formatting to writing-docs

doc/Language/hashmap.pod6

@@ -147,7 +147,7 @@ the string values into integers for the sort. There are several ways that can be
 method may present the least "line noise" to novices or non-Raku viewers:
 
 =for code :preamble<my %csv>
-    say %csv.keys.map(+*).sort.raku;   # OUTPUT: «(2, 10).Seq␤»
+say %csv.keys.map(+*).sort.raku;   # OUTPUT: «(2, 10).Seq␤»
 
 In a hash constructor list the C<Pair> syntax doesn't have to be used, or it may be intermixed
 with ordinary list values as long as the list has an even number of elements in total as well

doc/Language/js-nutshell.pod6

@@ -86,14 +86,14 @@ than the outer scope. This is what the equivalent variable declarations look
 like in Raku:
 
 =for code
-my           $foo = 1; # Lexically scoped
-our          $foo = 1; # Package scoped
+my $foo = 1; # Lexically scoped
+our $foo = 1; # Package scoped
 
 =for code
-my  constant  foo = 1; # Lexically scoped; constant
+my constant foo = 1; # Lexically scoped; constant
 
 =for code
-    constant  foo = 1; # Package scoped; constant
+constant foo = 1; # Package scoped; constant
 
 =for code
 my  $*foo = 1; # Dynamic variable; lexically scoped

doc/Language/list.pod6

@@ -526,11 +526,12 @@ normal behavior of the L<..|/type/Range> operator. The subscript operator
 L<[]|/language/subscripts#Slices> evaluates the WhateverCode providing the
 list's C<.elems> as an argument and uses the resulting range to slice:
 
-    =for code :preamble<my @a = 1..5>
+    =begin code :preamble<my @a = 1..5>
     say @a[0..*-1];   # OUTPUT: «(1 2 3 4 5)␤»
     say @a[0..^*-1];  # OUTPUT: «(1 2 3 4)␤»
     # Produces 0..^2.5 as the slice range
     say @a[0..^*/2];  # OUTPUT: «(1 2 3)␤»
+    =end code
 
 Notice that C<0..^*> and C<0..^*+0> behave consistently in subscripts despite
 one being an infinite range and the other a WhateverCode producing ranges,

doc/Language/operators.pod6

@@ -301,9 +301,10 @@ judging the while loop condition.
 In dealing with simple and compound assignment operators, it is tempting to
 think that for instance the following two statements are (always) equivalent:
 
-    =for code :skip-test<pseudo code>
+    =begin code :skip-test<pseudo code>
     expression1 += expression2;                     # compound assignment
     expression1  = expression1 + expression2;       # simple assignment
+    =end code
 
 They are not, however, for two reasons. Firstly, C<expression1> in the compound
 assignment statement is evaluated only once, whereas C<expression1> in the
@@ -1549,27 +1550,27 @@ Both C<.count> and C<.arity> of the right-hand side will be maintained, as
 well as the C<.of> of the left hand side.
 
 =begin code
-    sub f($p){ say 'f'; $p / 2 }
-    sub g($p){ say 'g'; $p * 2 }
-
-    my &composed = &f ∘ &g;
-    say composed 2; # OUTPUT: «g␤f␤2␤»
-    # equivalent to:
-    say 2.&g.&f;
-    # or to:
-    say f g 2;
-    say &composed.arity; #  OUTPUT: «1␤»
-    say &composed.count; #  OUTPUT: «1␤»
-    say &composed.of;    #  OUTPUT: «(Mu)␤»
+sub f($p){ say 'f'; $p / 2 }
+sub g($p){ say 'g'; $p * 2 }
+
+my &composed = &f ∘ &g;
+say composed 2; # OUTPUT: «g␤f␤2␤»
+# equivalent to:
+say 2.&g.&f;
+# or to:
+say f g 2;
+say &composed.arity; #  OUTPUT: «1␤»
+say &composed.count; #  OUTPUT: «1␤»
+say &composed.of;    #  OUTPUT: «(Mu)␤»
 =end code
 
 =begin code
-    sub f($a, $b, $c) { [~] $c, $b, $a }
-    sub g($str){ $str.comb }
-    my &composed = &f ∘ &g;
-    say composed 'abc'; # OUTPUT: «cba␤»
-    # equivalent to:
-    say f |g 'abc';
+sub f($a, $b, $c) { [~] $c, $b, $a }
+sub g($str){ $str.comb }
+my &composed = &f ∘ &g;
+say composed 'abc'; # OUTPUT: «cba␤»
+# equivalent to:
+say f |g 'abc';
 =end code
 
 The single-arg candidate returns the given argument as is. The zero-arg candidate

doc/Type/CompUnit/Repository/FileSystem.pod6

@@ -61,12 +61,11 @@ matching C<$spec>.
 =head2 method need
 
 =for code :method :preamble<method !precomp-stores() {...};>
-    method need(
-        CompUnit::DependencySpecification $spec,
-        CompUnit::PrecompilationRepository $precomp = self.precomp-repository(),
-        CompUnit::PrecompilationStore :@precomp-stores = self!precomp-stores(),
-        --> CompUnit:D)
-
+method need(
+    CompUnit::DependencySpecification $spec,
+    CompUnit::PrecompilationRepository $precomp = self.precomp-repository(),
+    CompUnit::PrecompilationStore :@precomp-stores = self!precomp-stores(),
+    --> CompUnit:D)
 
 Loads and returns a L<CompUnit|/type/CompUnit> which is mapped to the highest version distribution
 matching C<$spec> from the first repository in the repository chain that contains

doc/Type/Date.pod6

@@ -81,7 +81,7 @@ the invocant if the day value is already the last day of the month.
 This should allow for much easier ranges like
 
 =for code :preamble<my $date>
-    $date .. $date.last-date-in-month
+$date .. $date.last-date-in-month
 
 for all remaining dates in the month.
 

doc/Type/Distribution/Hash.pod6

@@ -5,7 +5,7 @@
 =SUBTITLE Distribution::Hash
 
 =for code :preamble<role Distribution::Locally {}>
-    class Distribution::Hash does Distribution::Locally { }
+class Distribution::Hash does Distribution::Locally { }
 
 A L<Distribution|/type/Distribution> implementation backed by the filesystem. It
 does not require a C<META6.json> file, essentially providing a lower level

doc/Type/Distribution/Path.pod6

@@ -5,7 +5,7 @@
 =SUBTITLE Distribution::Path
 
 =for code :preamble<role Distribution::Locally {}>
-    class Distribution::Path does Distribution::Locally { }
+class Distribution::Path does Distribution::Locally { }
 
 A L<Distribution|/type/Distribution> implementation backed by the filesystem. It requires a
 C<META6.json> file at its root.

doc/Type/FatRat.pod6

@@ -29,7 +29,7 @@ Returns an implementation-specific string that produces an L<equivalent|/routine
 when given to L<EVAL|/routine/EVAL>.
 
 =for code :ok-test<raku>
-    say FatRat.new(1, 2).raku; # OUTPUT: «FatRat.new(1, 2)␤»
+say FatRat.new(1, 2).raku; # OUTPUT: «FatRat.new(1, 2)␤»
 
 =end pod
 

doc/Type/IO/Path.pod6

@@ -323,8 +323,8 @@ Returns a string that, when given passed through L«C<EVAL>|/routine/EVAL»
 gives the original invocant back.
 
 =for code :ok-test<raku>
-    "foo/bar".IO.raku.say;
-    # OUTPUT: IO::Path.new("foo/bar", :SPEC(IO::Spec::Unix), :CWD("/home/camelia"))
+"foo/bar".IO.raku.say;
+# OUTPUT: IO::Path.new("foo/bar", :SPEC(IO::Spec::Unix), :CWD("/home/camelia"))
 
 Note that this string includes the value of the C<.CWD> attribute that is set
 to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path

doc/Type/IO/Path/Cygwin.pod6

@@ -28,8 +28,8 @@ Returns a string that, when given passed through L«C<EVAL>|/routine/EVAL»
 gives the original invocant back.
 
 =for code :ok-test<raku>
-    IO::Path::Cygwin.new("foo/bar").raku.say;
-    # OUTPUT: IO::Path::Cygwin.new("foo/bar", :CWD("/home/camelia"))
+IO::Path::Cygwin.new("foo/bar").raku.say;
+# OUTPUT: IO::Path::Cygwin.new("foo/bar", :CWD("/home/camelia"))
 
 Note that this string includes the value of the C<.CWD> attribute that is set
 to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path

doc/Type/IO/Path/QNX.pod6

@@ -28,8 +28,8 @@ Returns a string that, when given passed through L«C<EVAL>|/routine/EVAL»
 gives the original invocant back.
 
 =for code :ok-test<raku>
-    IO::Path::QNX.new("foo/bar").raku.say;
-    # OUTPUT: IO::Path::QNX.new("foo/bar", :CWD("/home/camelia"))
+IO::Path::QNX.new("foo/bar").raku.say;
+# OUTPUT: IO::Path::QNX.new("foo/bar", :CWD("/home/camelia"))
 
 Note that this string includes the value of the C<.CWD> attribute that is set
 to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path

doc/Type/IO/Path/Unix.pod6

@@ -28,8 +28,8 @@ Returns a string that, when given passed through L«C<EVAL>|/routine/EVAL»
 gives the original invocant back.
 
 =for code :ok-test<raku>
-    IO::Path::Unix.new("foo/bar").raku.say;
-    # OUTPUT: IO::Path::Unix.new("foo/bar", :CWD("/home/camelia"))
+IO::Path::Unix.new("foo/bar").raku.say;
+# OUTPUT: IO::Path::Unix.new("foo/bar", :CWD("/home/camelia"))
 
 Note that this string includes the value of the C<.CWD> attribute that is set
 to L«C<$*CWD>|/language/variables#Dynamic_variables» when the path

doc/Type/Range.pod6

@@ -417,7 +417,7 @@ Returns an implementation-specific string that produces an
 L<equivalent|/routine/eqv> object when given to L<EVAL|/routine/EVAL>.
 
 =for code :ok-test<raku>
-    say (1..2).raku # OUTPUT: «1..2␤»
+say (1..2).raku # OUTPUT: «1..2␤»
 
 =head2 method fmt
 

doc/Type/Rat.pod6

@@ -51,8 +51,8 @@ Returns an implementation-specific string that produces an L<equivalent|/routine
 when given to L<EVAL|/routine/EVAL>.
 
 =for code :ok-test<raku>
-    say (1/3).raku;                # OUTPUT: «<1/3>␤»
-    say (2/4).raku;                # OUTPUT: «0.5␤»
+say (1/3).raku;                # OUTPUT: «<1/3>␤»
+say (2/4).raku;                # OUTPUT: «0.5␤»
 
 =end pod
 

doc/Type/Rational.pod6

@@ -26,8 +26,9 @@ both do the C<Rational> role.
 
 =head2 method new
 
-    =for code :preamble<subset NuT of Int; subset DeT of Int>
+    =begin code :preamble<subset NuT of Int; subset DeT of Int>
     method new(NuT:D $numerator, DeT:D $denominator --> Rational:D)
+    =end code
 
 Creates a new rational object from numerator and denominator, which it
 normalizes to the lowest terms. The C<$denominator> can be zero, in which
@@ -100,15 +101,17 @@ Number>. That is both its numerator and denominator are zero.
 
 =head2 method numerator
 
-    =for code :preamble<subset NuT of Int; subset DeT of Int>
+    =begin code :preamble<subset NuT of Int; subset DeT of Int>
     method numerator(Rational:D: --> NuT:D)
+    =end code
 
 Returns the numerator.
 
 =head2 method denominator
 
-    =for code :preamble<subset NuT of Int; subset DeT of Int>
+    =begin code :preamble<subset NuT of Int; subset DeT of Int>
     method denominator(Rational:D: --> DeT:D)
+    =end code
 
 Returns the denominator.
 

doc/Type/Signature.pod6

@@ -504,8 +504,8 @@ Typed L<lambdas|/language/functions#Blocks_and_lambdas> also work with
 constrained callable parameters.
 
 =for code :preamble<sub apply {...}>
-    say apply -> Int:D \x --> Int:D { 2 * x }, 3;  # OUTPUT: «6␤»
-    say apply -> Int:D \x --> Int:D { x ** 3 }, 3; # OUTPUT: «27␤»
+say apply -> Int:D \x --> Int:D { 2 * x }, 3;  # OUTPUT: «6␤»
+say apply -> Int:D \x --> Int:D { x ** 3 }, 3; # OUTPUT: «27␤»
 
 Note that this shorthand syntax is available only for parameters with the C<&>
 sigil. For others, you need to use the long version:

doc/Type/StrDistance.pod6

@@ -60,10 +60,11 @@ Defined as:
 
 Returns an C<after> string value.
 
-    =for code :preamble<my $str = "fold">
+    =begin code :preamble<my $str = "fold">
     my $str-dist = ($str ~~ tr/old/new/);
     say $str-dist.Str; # OUTPUT: «fnew␤»
     say ~$str-dist;    # OUTPUT: «fnew␤»
+    =end code
 
 =end pod
 

doc/Type/X/Proc/Async/BindOrUse.pod6

@@ -5,7 +5,7 @@
 =SUBTITLE Error due to trying to bind a handle that is also used
 
 =for code :preamble<role X::Proc::Async {}>
-    class X::Proc::Async::BindOrUse does X::Proc::Async {}
+class X::Proc::Async::BindOrUse does X::Proc::Async {}
 
 In general, it occurs when there's some mistake in the direction the stream
 flows, for instance:

writing-docs/EXAMPLES.md

@@ -6,9 +6,10 @@ documentation with some example.
 ## 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
+are considered to be code, but you can specify the `=for code` directive, or a
 combination of `=begin code` and `=end code` to better control which
-blocks are considered.
+blocks are considered. The POD6 directives also allow you to set
+attributes for a block of code.
 
 When using a `=for code` directive or a `=begin code`/`=end code`
 combination, the code block does not need to be indented and should not
@@ -127,3 +128,25 @@ previous annotations.
     =begin code :skip-test<compile time error>
     if 1 "missing a block";
     =end code
+
+### Code Indentation / Formatting
+
+Documentation can be formatted as code using multiple source
+styles.
+
+## Indented text
+
+4-space indented text is formatted as a code block. The indent is *not*
+part of the displayed code. It's not possible to add any POD6
+directives on this style.
+
+## =for code
+
+The following block of text is treated as code. The indentation level
+is from the beginning of the line, regardless of how the `=for`
+is indented.
+
+## =begin code / =end code
+
+The enclosed text is treated as code. The indentation level is
+relative to the indentation of the POD6 directives.

xt/examples-compilation.t

@@ -29,6 +29,8 @@ do hide $*ERR, but some of these are emitted from parts of
 the compiler that only know about the low level handle, not the
 Perl 6 level one.
 
+Error if leading whitespace is present in the code block.
+
 =end SYNOPSIS
 
 plan +my @files = Test-Files.pods;
@@ -41,6 +43,13 @@ for @files -> $file {
 }
 
 sub test-example ($eg) {
+    my @lines-all = $eg<contents>.lines;
+    my @lines-ws  = @lines-all.grep(/^ \s /);
+
+    if @lines-ws eq @lines-all {
+        flunk "$eg<file> chunk starting with «" ~ starts-with($eg<contents>) ~ '» has extra leading whitespace';
+        next;
+    }
     # #1355 - don't like .WHAT in examples
     if ! $eg<ok-test>.contains('WHAT') && $eg<contents>.contains('.WHAT') {
         flunk "$eg<file> chunk starting with «" ~ starts-with($eg<contents>) ~ '» uses .WHAT: try .^name instead';