Documents aliases and adds example to MAIN

Although, as it happens with stale issues, a part of it (the
documentation of aliases) had already been addressed (and the
documentation it refers to moved somewhere else). Closes #1696

doc/Language/create-cli.pod6

@@ -168,6 +168,31 @@ Usage:
     --verbose         required verbosity
 =end code
 
+As any other subroutine, C<MAIN> can define
+L<aliases|/Signature#index-entry-aliases> for its named parameters.
+
+=for code
+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
+) {
+    say $length if $length.defined;
+    say $file   if $file.defined;
+    say 'Verbosity ', ($verbose ?? 'on' !! 'off');
+}
+
+In which case, these aliases will also be listed as alternatives with C<--help>:
+
+=for code :lang<text>
+Usage:
+  frobnicate.p6 [--size|--length=<Int>] [--verbose] [<file>]
+
+    [<file>]                 an existing file to frobnicate
+    --size|--length=<Int>    length needed for frobnication
+    --verbose                required verbosity
+
+
 X<|%*SUB-MAIN-OPTS>
 =head2 %*SUB-MAIN-OPTS
 

doc/Language/functions.pod6

@@ -1043,30 +1043,32 @@ the routine itself to accept a wider input. When invoked, the arguments are
 narrowed automatically to the stricter type, and therefore within the routine
 the arguments have always the desired type.
 
-In the case the arguments cannot be converted to the stricter type, a I<Type Check> error
-is thrown.
+In the case the arguments cannot be converted to the stricter type, a I<Type
+Check> error is thrown.
 
 =begin code
 sub double(Int(Cool) $x) {
     2 * $x
 }
 
-say double '21';    # OUTPUT: «42␤»
-say double  21;     # OUTPUT: «42␤»
-say double Any;     # Type check failed in binding $x; expected 'Cool' but got 'Any'
+say double '21';# OUTPUT: «42␤»
+say double  21; # OUTPUT: «42␤»
+say double Any; # Type check failed in binding $x; expected 'Cool' but got 'Any'
 =end code
 
-In the above example, the L<Int|/type/Int> is the target type to which the argument C<$x> will be coerced, and
-L<Cool|/type/Cool> is the type that the routine accepts as wider input.
+In the above example, the L<Int|/type/Int> is the target type to which the
+argument C<$x> will be coerced, and L<Cool|/type/Cool> is the type that the
+routine accepts as wider input.
 
-If the accepted wider input type is L<Any|/type/Any>, it is possible to abbreviate the coercion C<Int(Any)>
-omitting the C<Any> type, thus resulting in  C<Int()>.
+If the accepted wider input type is L<Any|/type/Any>, it is possible to
+abbreviate the coercion C<Int(Any)> omitting the C<Any> type, thus resulting in
+C<Int()>.
 
-The coercion works by looking for a method with the same name
-as the target type: if such method is found on the argument, it is invoked to
-convert the latter to the expected narrow type.
-From the above, it is clear that it is possible to provide coercion among user types
-just providing the required methods:
+The coercion works by looking for a method with the same name as the target
+type: if such method is found on the argument, it is invoked to convert the
+latter to the expected narrow type. From the above, it is clear that it is
+possible to provide coercion among user types just providing the required
+methods:
 
 =begin code
 class Bar {

doc/Language/setbagmix.pod6

@@ -32,7 +32,7 @@ Collection of distinct objects
 
 If you want to keep track of the B<number of times each object appeared>,
 you can use a L<Bag|/type/Bag> or L<BagHash|/type/BagHash>. In these
-Baggy containers each element has a weight (an unsigned integer)
+C<Baggy> containers each element has a weight (an unsigned integer)
 indicating the number of times the same object has been included in the
 collection.
 

doc/Type/Signature.pod6

@@ -829,6 +829,17 @@ before slipping.
     say C.new(|%h.Map);
     # OUTPUT: «C.new(x => 5, y => 20, z => [1, 2])␤»
 
+You can create as many aliases to a named argument as you want:
+
+=for code
+sub alias-named(:color(:$colour),
+                :variety(:style(:sort(:type(:class($kind)))))) {
+    return $colour ~ " " ~ $kind
+}
+say alias-named(color => "red", style => "A");
+say alias-named(colour => "green", variety => "B");
+say alias-named(color => "white", class => "C");
+
 X<|optional argument>
 =head2 Optional and mandatory arguments