Some work on create-cli.rakudoc (#4688)

* make example more elementary

* improve some explanations

* make alias example about single-letter variants for long-form args

This should be the most interesting use case for parameter aliases in the CLI context.

* add missing comma

* add references to Q syntax

* linkfix & whitespace

* 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

@@ -104,7 +104,7 @@ If you want to pass an indeterminate number of parameters to be dealt with in
 C<sub MAIN>, you can use L<slurpy parameters|/language/signatures#Slurpy_parameters>:
 
     # inside file 'hello-all.raku'
-    sub MAIN(*@all) { @all.map: -> $name { say "Hello, " ~ $name } }
+    sub MAIN(*@all) { for @all -> $name { say "Hello, " ~ $name } }
 
 =begin code :lang<shell>
 $ raku hello-all.raku peter paul mary
@@ -131,7 +131,10 @@ sub MAIN(
     say 'Verbosity ', ($verbose ?? 'on' !! 'off');
 }
 
-With C<file.dat> present, this will work this way:
+The clause C<where *.IO.f> checks that the string C<$file> corresponds to the name of a file that actually exists.
+The part C<= 'file.dat'> specifies a default value for C<$file> in case no argument for it is given.
+
+If a file C<file.dat> is present, a call with no arguments will work this way:
 =begin code :lang<shell>
 $ raku frobnicate.raku
 24
@@ -158,12 +161,12 @@ Usage:
   frobnicate.raku [--length=<Int>] [--verbose] [<file>]
 =end code
 
-Although you don't have to do anything in your code to do this, it may still
-be regarded as a bit terse.
+Such usage messages are generated completely automatically for you.
+If they seem too terse, you can easily add more information to them.
 
 =head2 Improve usage messages with rakudoc comments
 
-But there's an easy way to make that usage
+There's an easy way to make the autogenerated usage
 message better by providing hints using pod features:
 
 =for code :method<False>
@@ -265,12 +268,13 @@ And here's the signature that produces each type of argument:
 
 As any other subroutine, C<MAIN> can define
 L<aliases|/language/signatures#Argument_aliases> for its named parameters.
+In particular, this can be used to define single-letter alternative names.
 
 =for code :method<False>
 sub MAIN(
   Str   $file where *.IO.f = 'file.dat',  #= an existing file to frobnicate
-  Int  :size(:$length) = 24,              #= length/size needed for frobnication
-  Bool :$verbose,                         #= required verbosity
+  Int  :l(:$length) = 24,                 #= length needed for frobnication
+  Bool :v(:$verbose),                     #= required verbosity
 ) {
     say $length if $length.defined;
     say $file   if $file.defined;
@@ -284,8 +288,8 @@ Usage:
   frobnicate.raku [--size|--length=<Int>] [--verbose] [<file>]
 
     [<file>]                 an existing file to frobnicate
-    --size|--length=<Int>    length needed for frobnication
-    --verbose                required verbosity
+    -l|--length=<Int>        length needed for frobnication
+    -v|--verbose             required verbosity
 =end code
 
 =head2 Named arrays
@@ -327,14 +331,15 @@ enum Flag  (
 );
 
 sub MAIN(Flag $flag = FLAG_FOO) {
-    say "Flagging $flag";
+    say "Flagging $flag with value $flag.value()";
 }
 =end code
 
 This will work correctly with
 
 =for code :lang<text>
-raku MAIN-enum.raku FLAG_BAR
+raku MAIN-enum.raku FLAG_BAZ
+# OUTPUT: «Flagging FLAG_BAZ with value 4␤»
 
 but will die if called with something that is not a C<Flag>.
 
@@ -495,6 +500,11 @@ 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 usage message.
 
+In the following example, we print a custom usage message via
+a L<Q string|/language/quoting>
+(with the C<:c|/language/quoting#Interpolating_closures> flag enabling interpolation of curly braces,
+and the C<:to|/language/quoting#Heredocs:_:to> flag for stating it all as a heredoc):
+
     #|(is it the answer)
     multi MAIN(Int $i) { say $i == 42 ?? 'answer' !! 'dunno' }
     #|(divide two numbers)
@@ -514,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
@@ -545,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
@@ -586,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.