reorder section on intercepting USAGE and MAIN

The subsection `sub RUN-MAIN` clearly doesn't belong under the section on usage message interception. It fits slightly better under the section on intercepting CLI argument parsing, where I've put it now. It would probably fit best under the last section "Intercepting MAIN calling", but for that edit one would have to make sure to get the history right.

The new order of sections also has the advantage that everything on usage messages is contiguous, and everything on custom CLI handling & MAIN calling.

Author: schultzdavid

doc/Language/create-cli.rakudoc

@@ -524,6 +524,46 @@ candidates and their parameters. As shown before, you can specify an
 additional extended description for each candidate using a
 C<#|(...)> Pod block to set L«C<WHY>|/routine/WHY».
 
+
+=head1 Intercepting usage message generation (2018.10, v6.d and later)
+
+You can replace or augment the default way of usage message generation
+(after a failed dispatch to MAIN) by supplying a C<GENERATE-USAGE> subroutine
+yourself, or by importing one from any of the
+L<Getopt|https://raku.land/?q=getopt> modules available in the
+ecosystem.
+
+=head2 X<sub GENERATE-USAGE|Subroutines,GENERATE-USAGE>
+
+The C<GENERATE-USAGE> subroutine should accept a L<C<Callable>|/type/Callable> representing the
+C<MAIN> subroutine that didn't get executed because the dispatch failed.
+This can be used for introspection. All the other parameters are the
+parameters that were set up to be sent to C<MAIN>. It should return the
+string of the usage information you want to be shown to the user. An example
+that will just recreate the L<C<Capture>|/type/Capture> that was created from processing the
+arguments:
+
+    sub GENERATE-USAGE(&main, |capture) {
+        capture<foo>:exists
+          ?? "You're not allowed to specify a --foo"
+          !! &*GENERATE-USAGE(&main, |capture)
+    }
+
+You can also use multi subroutines to create the same effect:
+
+    multi GENERATE-USAGE(&main, :$foo!) {
+        "You're not allowed to specify a --foo"
+    }
+    multi GENERATE-USAGE(&main, |capture) {
+        &*GENERATE-USAGE(&main, |capture)
+    }
+
+Note that the dynamic variable
+L<C<&*GENERATE-USAGE>|/language/variables#&*GENERATE-USAGE> is available to
+perform the default usage message generation so you don't have to reinvent the
+whole wheel if you don't want to.
+
+
 =head1 Intercepting CLI argument parsing (2018.10, v6.d and later)
 
 You can replace or augment the default way of argument parsing by supplying an
@@ -555,21 +595,13 @@ L<C<&*ARGS-TO-CAPTURE>|/language/variables#&*ARGS-TO-CAPTURE> is available to
 perform the default command line arguments to L<C<Capture>|/type/Capture> processing so you don't
 have to reinvent the whole wheel if you don't want to.
 
-=head1 Intercepting usage message generation (2018.10, v6.d and later)
-
-You can replace or augment the default way of usage message generation
-(after a failed dispatch to MAIN) by supplying a C<GENERATE-USAGE> subroutine
-yourself, or by importing one from any of the
-L<Getopt|https://raku.land/?q=getopt> modules available in the
-ecosystem.
-
 =head2 X<sub RUN-MAIN|Subroutines,RUN-MAIN>
 
     sub RUN-MAIN(&main, $mainline, :$in-as-argsfiles)
 
 This routine allows complete control over the handling of C<MAIN>. It gets a
 L<C<Callable>|/type/Callable> that is the C<MAIN> that should be executed, the return value of the
-mainline execution and additional named variables: C<:in-as-argsfiles> which
+mainline execution and an additional named variable: C<:in-as-argsfiles> which
 will be C<True> if STDIN should be treated as C<$*ARGFILES>.
 
 If C<RUN-MAIN> is not provided, a default one will be run that looks for
@@ -596,36 +628,6 @@ RUN-MAIN( &new-main, Nil );
 This will print the name (first argument) of the generated object.
 
 
-=head2 X<sub GENERATE-USAGE|Subroutines,GENERATE-USAGE>
-
-The C<GENERATE-USAGE> subroutine should accept a L<C<Callable>|/type/Callable> representing the
-C<MAIN> subroutine that didn't get executed because the dispatch failed.
-This can be used for introspection. All the other parameters are the
-parameters that were set up to be sent to C<MAIN>. It should return the
-string of the usage information you want to be shown to the user. An example
-that will just recreate the L<C<Capture>|/type/Capture> that was created from processing the
-arguments:
-
-    sub GENERATE-USAGE(&main, |capture) {
-        capture<foo>:exists
-          ?? "You're not allowed to specify a --foo"
-          !! &*GENERATE-USAGE(&main, |capture)
-    }
-
-You can also use multi subroutines to create the same effect:
-
-    multi GENERATE-USAGE(&main, :$foo!) {
-        "You're not allowed to specify a --foo"
-    }
-    multi GENERATE-USAGE(&main, |capture) {
-        &*GENERATE-USAGE(&main, |capture)
-    }
-
-Note that the dynamic variable
-L<C<&*GENERATE-USAGE>|/language/variables#&*GENERATE-USAGE> is available to
-perform the default usage message generation so you don't have to reinvent the
-whole wheel if you don't want to.
-
 =head1 Intercepting MAIN calling (before 2018.10, v6.e)
 
 An older interface enabled one to intercept the calling to C<MAIN> completely.