document named arrays, and add some second-level headings (#4677)

Author: arkiuat

doc/Language/create-cli.rakudoc

@@ -113,6 +113,8 @@ Hello, paul
 Hello, mary
 =end code
 
+=head2 Multiple named parameters, and C<where> clauses
+
 A more complicated example using a single positional and multiple
 named parameters, and also showing that C<where> clauses can also be applied
 to C<MAIN> arguments:
@@ -157,7 +159,11 @@ Usage:
 =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. But there's an easy way to make that usage
+be regarded as a bit terse.
+
+=head2 Improve usage messages with rakudoc comments
+
+But there's an easy way to make that usage
 message better by providing hints using pod features:
 
 =for code :method<False>
@@ -210,6 +216,8 @@ Usage:
     -v                     Display verbose output
 =end code
 
+=head2 Command lines and usage messages: more examples
+
 The following are valid ways to call C<demo>:
 
 =for code :lang<text>
@@ -253,6 +261,7 @@ And here's the signature that produces each type of argument:
    C<True> (because passing an option without an argument is equivalent
    to passing C<True>)
 
+=head2 Aliases for named parameters
 
 As any other subroutine, C<MAIN> can define
 L<aliases|/language/signatures#Argument_aliases> for its named parameters.
@@ -279,6 +288,34 @@ Usage:
     --verbose                required verbosity
 =end code
 
+=head2 Named arrays
+
+The MAIN subroutine can also use a kind of named parameter not available
+to ordinary subs: the named array.  This enables, for instance, providing
+two different short arrays as arguments on a command line.
+
+Declare a named-array parameter with C<:@> in sub MAIN's signature:
+
+    # inside file 'named-array.raku'
+    sub MAIN(:@n) {
+        .raku.say for @n
+    }
+
+You can use this on the command line by repeating the named-array
+parameter with different values each time.
+
+=begin code :lang<shell>
+$ raku named-array.raku --n=foo --n=23 --n=6.3 --n=3e8 --n=2+2i --n=bar
+"foo"
+IntStr.new(23, "23")
+RatStr.new(6.3, "6.3")
+NumStr.new(300000000e0, "3e8")
+ComplexStr.new(<2+2i>, "2+2i")
+"bar"
+=end code
+
+=head2 Enumerations
+
 L<C<Enumeration>|/type/Enumeration>s can be used in signatures with arguments converted
 automatically to its corresponding C<enum> symbol: