Remove old MAIN documentation from functions

And replace it by a stub referring to the new CLI page

Author: lizmat

doc/Language/functions.pod6

@@ -1113,130 +1113,10 @@ for (2,4) X (1,2) -> ($a,$b) {
 In this case, we are coercing an C<Int> to a C<Bool>, which is then printed (put
 into a string context) in the C<for> loop that calls the function.
 
-X<|MAIN>X<|command line arguments>
 =head1 sub MAIN
 
-The sub with the special name C<MAIN> is executed after all relevant phasers.
-Its signature is the means by which command line arguments can be parsed. Multi
-methods are supported and a usage method is automatically generated and
-displayed if no command line arguments are provided. All command line arguments
-are also available in L<C<@*ARGS>|/language/variables#Dynamic_variables>, which
-can be mutated before being processed by C<MAIN>.
-
-Unlike other ordinary functions, any return value provided by C<MAIN> will be
-ignored by the invoker, even if explicitly set by means of a C<return> statement
-(that will terminate the C<MAIN> function). The default return code of C<MAIN> is always
-zero (C<0>, success).
-In order to provide any return value different from zero, a call
-to L<exit|https://docs.perl6.org/routine/exit> has to be performed.
-
-    #|(optional description for USAGE message)
-    sub MAIN( Int :$length = 24,
-               :file($data) where { .IO.f // die "file not found in $*CWD" } = 'file.dat',
-               Bool :v(:$verbose) #`( -verbose, --verbose, -v or --v ) )
-    {
-        say $length if $length.defined;
-        say $data   if $data.defined;
-        say 'Verbosity ', ($verbose ?? 'on' !! 'off');
-
-        exit 1;
-    }
-
-This C<MAIN> is defining two kind of aliases, as explained in
-L<Signatures|/type/Signature#Positional_vs._named_arguments>: C<:file($data)> aliases the
-content passed to the command-line parameter C<--file=> to the variable
-C<$data>; C<:v(:$verbose)> not only aliases C<v> to C<verbose>, but also creates
-a new command line parameter C<verbose> thanks to the specification of the C<:>.
-In fact, since this is an alias, both C<verbose> and C<v> can use single or
-double dashes (C<-> or C<-->).
-
-With C<file.dat> present, this will work this way
-=begin code :lang<shell>
-$ perl6 Main.p6
-24
-file.dat
-Verbosity off
-=end code
-
-Or this way with C<-v> or C<--verbose>
-
-=begin code :lang<shell>
-$ perl6 Main.p6 -v
-24
-file.dat
-Verbosity on
-=end code
-
-
-=head2 C<%*SUB-MAIN-OPTS>
-
-It's possible to alter how arguments are processed before they're passed
-to C<sub MAIN {}> by setting options in C<%*SUB-MAIN-OPTS> hash.  Due to the
-nature of dynamic variables, it is required to set up C<%*SUB-MAIN-OPTS>
-hash and fill it with the appropriate settings.  For instance:
-
-    my %*SUB-MAIN-OPTS =
-      :named-anywhere,    # allow named variables at any location
-      :!foo,              # don't allow foo
-    ;
-    sub MAIN ($a, $b, :$c, :$d) {
-        say "Accepted!"
-    }
-
-Available options are:
-
-=head3 C<named-anywhere>
-
-By default, named arguments passed to the program (i.e., C<MAIN>)
-cannot appear after any positional argument.
-However, if C«%*SUB-MAIN-OPTS<named-anywhere>» is
-set to a true value, named arguments can be specified anywhere, even after
-positional parameter. For example, the above program can be called with:
-
-=begin code :lang<shell>
-perl6 example.p6 1 --c=2 3 --d=4
-=end code
-
-=head2 X<Unit-scoped definition of MAIN|declarator,unit (MAIN)>
-
-If the entire program body resides within C<MAIN>, you can use the C<unit>
-declarator as follows:
-
-=begin code :skip-test<unit>
-unit sub MAIN( Int :$length = 24,
-                :file($data) where { .IO.f // die "file not found in $*CWD" } = 'file.dat',
-                Bool :v(:$verbose) #`( -verbose, --verbose, -v or --v ) );
-
-# rest of script is part of MAIN
-=end code
-
-Note that this is only appropriate if you do not need a C<proto> or C<multi> definition.
-
-X<|USAGE>X<|$*USAGE>
-=head1 sub C<USAGE>
-
-If no multi candidate of C<MAIN> is found for the given command line
-parameters, the sub C<USAGE> is called. If no such method is found,
-the compiler will output a default generated usage message.
-
-    #|(is it the answer)
-    multi MAIN(Int $i) { say $i == 42 ?? 'answer' !! 'dunno' }
-    #|(divide two numbers)
-    multi MAIN($a, $b){ say $a/$b }
-
-    sub USAGE() {
-    print Q:c:to/EOH/;
-    Usage: {$*PROGRAM-NAME} [number]
-
-    Prints the answer or 'dunno'.
-    EOH
-    }
-
-The default usage message is available inside C<sub USAGE> via read-only
-C<$*USAGE> variable. It will be generated based on available C<sub MAIN>
-candidates and their parameters. You can specify additional extended
-description for each candidate using C<#|(...)> Pod block to set
-L«C<WHY>|/routine/WHY».
+There is no C<sub MAIN> in Perl 6, but you can provide one to create a
+L<command line interface|create-cli> for your script.
 
 =end pod