Restructure and reflow refs #2483

Author: JJ

doc/Language/create-cli.pod6

@@ -9,22 +9,22 @@ X<|command line arguments>
 
 The default command line interface of Perl 6 scripts consists of three parts:
 
-=item Parsing the command line parameters into a L<capture|/type/Capture>
+=head2 Parsing the command line parameters into a L<capture|/type/Capture>
 
 This looks at the values in L<@*ARGS|/language/variables#index-entry-@*ARGS>,
 interprets these according to some policy, and creates a C<Capture> object
 out of that.  An alternative way of parsing may be provided by the developer
 or installed using a module.
 
-=item Calling a provided MAIN subroutine using that capture
+=head2 Calling a provided C<MAIN> subroutine using that capture
 
 Standard L<multi dispatch|/language/functions#index-entry-declarator_multi-Multi-dispatch>
 is used to call the MAIN subroutine with the generated C<Capture> object.
 This means that your MAIN subroutine may be a C<multi sub>, each candidate
 of which is responsible for some part of processing the given command line
 arguments.
 
-=item Creating / showing usage information if calling MAIN failed
+=item2 Creating / showing usage information if calling C<MAIN> failed
 
 If multi dispatch failed, then the user of the script should be informed as
 well as possible as to why it failed.  By default, this is done by inspecting
@@ -34,7 +34,7 @@ was specified).  An alternative way of generating the usage information may
 be provided by the developer or installed using a module.
 
 X<|MAIN>
-=head2 sub MAIN
+=head1 sub MAIN
 
 The sub with the special name C<MAIN> will be executed after all relevant entry
 phasers (C<BEGIN>, C<CHECK>, C<INIT>, C<PRE>, C<ENTER>) have been run and
@@ -169,7 +169,7 @@ Usage:
 =end code
 
 X<|%*SUB-MAIN-OPTS>
-=head3 %*SUB-MAIN-OPTS
+=head2 %*SUB-MAIN-OPTS
 
 It's possible to alter how arguments are processed before they're passed
 to C<sub MAIN {}> by setting options in the C<%*SUB-MAIN-OPTS> hash.  Due to
@@ -188,7 +188,7 @@ For instance:
 Available options are:
 
 X<|named-anywhere>
-=head4 named-anywhere
+=head3 named-anywhere
 
 By default, named arguments passed to the program (i.e., C<MAIN>)
 cannot appear after any positional argument.  However, if
@@ -201,7 +201,7 @@ $ perl6 example.p6 1 --c=2 3 --d=4
 =end code
 
 X<|hidden-from-USAGE>
-=head3 is hidden-from-USAGE
+=head2 is hidden-from-USAGE
 
 Sometimes you want to exclude a C<MAIN> candidate from being shown in any
 automatically generated usage message.  This can be achieved by adding
@@ -238,7 +238,7 @@ Usage:
 Which, although technically correct, doesn't read as well.
 
 X<|declarator,unit (MAIN)>
-=head2 Unit-scoped definition of C<MAIN>
+=head1 Unit-scoped definition of C<MAIN>
 
 If the entire program body resides within C<MAIN>, you can use the C<unit>
 declarator as follows (adapting an earlier example):
@@ -295,11 +295,11 @@ in the ecosystem.
 X<|ARGS-TO-CAPTURE>
 =head2 sub ARGS-TO-CAPTURE
 
-The C<ARGS-TO-CAPTURE> subroutine should accept two parameters: a L<Callable|/type/Callable>
-representing the C<MAIN> unit to be executed (so it can be introspected if
-necessary) and an array with the arguments from the command line.  It
-should return a L<Capture|/type/Capture> object that will be used to
-dispatch the C<MAIN> unit.  A B<very> contrived example that will create
+The C<ARGS-TO-CAPTURE> subroutine should accept two parameters: a
+L<Callable|/type/Callable> representing the C<MAIN> unit to be executed (so it
+can be introspected if necessary) and an array with the arguments from the
+command line.  It should return a L<Capture|/type/Capture> object that will be
+used to dispatch the C<MAIN> unit.  A B<very> contrived example that will create
 a C<Capture> depending on some keyword that was entered (which can be handy
 during testing of a command line interface of a script):
 
@@ -312,9 +312,9 @@ during testing of a command line interface of a script):
           !! &*ARGS-TO-CAPTURE(&main, @args)
     }
 
-Note that the dynamic variable L<C<&*ARGS-TO-CAPTURE>|/language/variables#&*ARGS-TO-CAPTURE>
-is available to perform
-the default command line arguments to C<Capture> processing so you don't
+Note that the dynamic variable
+L<C<&*ARGS-TO-CAPTURE>|/language/variables#&*ARGS-TO-CAPTURE> is available to
+perform the default command line arguments to C<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)
@@ -351,9 +351,9 @@ You can also use multi subroutines to create the same effect:
         &*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
+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)

doc/Type/IO/Path.pod6

@@ -465,9 +465,11 @@ symlinked directories.
     '/'       .IO.parent.say; # OUTPUT: «"/".IO␤»
     IO::Path::Win32.new('C:/').parent.say; # OUTPUT: «"C:/".IO␤»
 
-If C<$level> is specified, the call is equivalent to calling C<.parent()> C<$level> times:
+If C<$level> is specified, the call is equivalent to calling C<.parent()>
+C<$level> times:
 
-    say "/etc/foo".IO.parent(2) eqv "/etc/foo".IO.parent.parent; # OUTPUT: «True␤»
+=for code
+say "/etc/foo".IO.parent(2) eqv "/etc/foo".IO.parent.parent; # OUTPUT: «True␤»
 
 =head2 method resolve
 
@@ -500,13 +502,13 @@ Defined as:
     method dir(IO::Path:D: Mu :$test = none('.', '..'))
 
 Returns the contents of a directory as a lazy list of C<IO::Path> objects
-representing relative paths, filtered by L<smartmatching|
-/language/operators#infix_~~> their names (as strings) against the C<:test>
-parameter.
+representing relative paths, filtered by
+L<smartmatching|/language/operators#infix_~~> their names (as strings) against
+the C<:test> parameter.
 
-Since the tests are performed against Str arguments, not IO, the tests are
-executed in the C<$*CWD>, instead of the target directory.
-When testing against file test operators, this won't work:
+Since the tests are performed against C<Str> arguments, not C<IO>, the tests are
+executed in the C<$*CWD>, instead of the target directory. When testing against
+file test operators, this won't work:
 
     dir('mydir', test => { .IO.d })
 
@@ -516,12 +518,12 @@ while this will:
 
 B<NOTE:> a C<dir> call opens a directory for reading, which counts towards
 maximum per-process open files for your program. Be sure to exhaust returned
-L<Seq|/type/Seq> before doing something like recursively performing more C<dir> calls.
-You can exhaust it by assigning to a C<@->sigiled variable or simply looping
-over it. Note how examples below push further dirs to look through into
-an L<Array|/type/Array>, rather than immediately calling C<dir> on them. See also
-L«C<IO::Dir> module|https://modules.perl6.org/dist/IO::Dir» that gives you finer
-control over closing dir handles.
+L<Seq|/type/Seq> before doing something like recursively performing more C<dir>
+calls. You can exhaust it by assigning to a C<@->sigiled variable or simply
+looping over it. Note how examples below push further dirs to look through into
+an L<Array|/type/Array>, rather than immediately calling C<dir> on them. See
+also L«C<IO::Dir> module|https://modules.perl6.org/dist/IO::Dir» that gives you
+finer control over closing dir handles.
 
 Examples: