Merge pull request #2955 from uzluisf/doc-proofreading

Proofread some documents

doc/Language/create-cli.pod6

@@ -12,47 +12,48 @@ The default command line interface of Perl 6 scripts consists of three parts:
 =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
+interprets these according to some policy, and creates a L<Capture/type/Capture>
+object out of that. An alternative way of parsing may be provided by the developer
 or installed using a module.
 
 =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
+is used to call the C<MAIN> subroutine with the generated C<Capture> object.
+This means that your C<MAIN> subroutine may be a C<multi sub>, each candidate
 of which is responsible for some part of processing the given command line
 arguments.
 
 =head2 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
-the signature of each MAIN candidate sub, and any associated pod information.
+well as possible as to why it failed. By default, this is done by inspecting
+the signature of each C<MAIN> candidate sub, and any associated Pod information.
 The result is then shown to the user on STDERR (or on STDOUT if C<--help>
-was specified).  An alternative way of generating the usage information may
+was specified). An alternative way of generating the usage information may
 be provided by the developer or installed using a module.
 
 X<|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
-the mainline of the script has been executed.  No error will occur if there
-is no MAIN sub: your script will then just have to do the work, such as
-argument parsing, in the mainline of the script.
-
-Any normal exit from the MAIN sub will result in an exit code of C<0>,
-indicating success.  Any return value of the MAIN sub will be ignored.
-If an exception is thrown that is not handled inside the MAIN sub, then the
-exit code will be C<1>.  If the dispatch to MAIN failed, a usage message
+the L<mainline|/language/glossary#index-entry-Mainline> of the script has been
+executed. No error will occur if there is no C<MAIN> sub: your script will
+then just have to do the work, such as argument parsing, in the mainline of
+the script.
+
+Any normal exit from the C<MAIN> sub will result in an exit code of C<0>,
+indicating success. Any return value of the C<MAIN> sub will be ignored.
+If an exception is thrown that is not handled inside the C<MAIN> sub, then the
+exit code will be C<1>. If the dispatch to C<MAIN> failed, a usage message
 will be displayed on STDERR and the exit code will be C<2>.
 
 The command line parameters are present in the C<@*ARGS> dynamic variable
 and may be altered in the mainline of the script before the C<MAIN> unit is
 called.
 
-The signature of (the candidates of the multi) sub MAIN determines which
+The signature of (the candidates of the multi) sub C<MAIN> determines which
 candidate will actually be called using the standard
 L<multi dispatch|/language/glossary#index-entry-Multi-Dispatch> semantics.
 
@@ -63,7 +64,8 @@ A simple example:
         say "Hello $name, how are you?"
     }
 
-If you call that script without any parameters:
+If you call that script without any parameters, you get the following
+usage message:
 
 =begin code :lang<shell>
 $ perl6 hello.p6
@@ -95,10 +97,10 @@ Another way to do this is to make C<sub MAIN> a C<multi sub>:
     multi sub MAIN()      { say "Hello bashful, how are you?" }
     multi sub MAIN($name) { say "Hello $name, how are you?"   }
 
-Which would give the same output as the examples above.  Whether you should
+Which would give the same output as the examples above. Whether you should
 use either method to achieve the desired goal is entirely up to you.
 
-A more complicated example using a single positional and  multiple
+A more complicated example using a single positional and multiple
 named parameters:
 
 =for code :method<False>
@@ -141,7 +143,7 @@ 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. But there's an easy way to make that usage
 message better by providing hints using pod features:
 
 =for code :method<False>
@@ -197,7 +199,7 @@ X<|%*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
+to C<sub MAIN {}> by setting options in the C<%*SUB-MAIN-OPTS> hash. Due to
 the nature of dynamic variables, it is required to set up the
 C<%*SUB-MAIN-OPTS> hash and fill it with the appropriate settings.
 For instance:
@@ -216,7 +218,7 @@ X<|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
+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:
@@ -229,9 +231,9 @@ X<|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
-a C<hidden-from-USAGE> trait to the specification of the MAIN candidate
-you do not want to show.  Expanding on an earlier example:
+automatically generated usage message. This can be achieved by adding
+a C<hidden-from-USAGE> trait to the specification of the C<MAIN> candidate
+you do not want to show. Expanding on an earlier example:
 
     # inside file 'hello.p6'
     multi sub MAIN() is hidden-from-USAGE {
@@ -323,10 +325,10 @@ X<|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
-a C<Capture> depending on some keyword that was entered (which can be handy
-during testing of a command line interface of a script):
+command line. It should return a L<Capture|/type/Capture> object that will be
+used to dispatch the C<MAIN> unit. The following is 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):
 
     sub ARGS-TO-CAPTURE(&main, @args --> Capture) {
         # if we only specified "frobnicate" as an argument
@@ -357,14 +359,14 @@ Defined as:
 
     sub RUN-MAIN(&main, $mainline, :$in-as-argsfiles)
 
-This routine allows complete control over the handling of C<MAIN>.  It gets a
-C<Callable> that is the MAIN that should be executed, the return value of the
-mainline execution  and additional named variables: C<:in-as-argsfiles> which
+This routine allows complete control over the handling of C<MAIN>. It gets a
+C<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
 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
-subroutines of the old interface, such as C<MAIN_HELPER> and C<USAGE>.  If
-found, will execute following the "old" semantics.
+subroutines of the old interface, such as C<MAIN_HELPER> and C<USAGE>. If
+found, it will execute following the "old" semantics.
 
 =begin code
 class Hero {
@@ -391,9 +393,9 @@ X<|GENERATE-USAGE>
 
 The C<GENERATE-USAGE> subroutine should accept a C<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
+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 C<Capture> that was created from processing the
 arguments:
 
@@ -423,13 +425,13 @@ An older interface enabled one to intercept the calling to C<MAIN> completely.
 This depended on the existence of a C<MAIN_HELPER> subroutine that would be
 called if a C<MAIN> subroutine was found in the mainline of a program.
 
-This interface was never documented.  However, any programs using this
-undocumented interface will continue to function until C<v6.e>.  From v6.d
+This interface was never documented. However, any programs using this
+undocumented interface will continue to function until C<v6.e>. From v6.d
 onward, the use of the undocumented API will cause a C<DEPRECATED> message.
 
 Ecosystem modules can provide both the new and the old interface for
 compatibility with older versions of Perl 6: if a newer Perl 6 recognizes
-the new (documented) interface, it will use that.  If there is no new
+the new (documented) interface, it will use that. If there is no new
 interface subroutine available, but the old C<MAIN_HELPER> interface is,
 then it will use the old interface.
 

doc/Language/exceptions.pod6

@@ -7,7 +7,7 @@
 Exceptions in Perl 6 are objects that hold information about errors. An
 error can be, for example, the unexpected receiving of data or a network
 connection no longer available, or a missing file. The information that
-an exception objects store is, for instance, a human-readable message
+an exception object stores is, for instance, a human-readable message
 about the error condition, the backtrace of the raising of the error,
 and so on.
 
@@ -33,8 +33,8 @@ Typed exceptions provide more information about the error stored
 within an exception object.
 
 For example, if while executing C<.zombie copy> on an object, a needed path
-C<foo/bar> becomes unavailable, then an L<X::IO::DoesNotExist|/type/X::IO::DoesNotExist> exception can be
-raised:
+C<foo/bar> becomes unavailable, then an
+L<X::IO::DoesNotExist|/type/X::IO::DoesNotExist> exception can be raised:
 
     die X::IO::DoesNotExist.new(:path("foo/bar"), :trying("zombie copy"))
 
@@ -376,7 +376,7 @@ printing a backtrace along with the message:
 
     class X::WithoutLineNumber is X::AdHoc {
         multi method gist(X::WithoutLineNumber:D:) {
-                $.payload
+            $.payload
         }
     }
     die X::WithoutLineNumber.new(payload => "message")

doc/Language/experimental.pod6

@@ -5,8 +5,8 @@
 =SUBTITLE Preview of upcoming new language features available for user evaluation
 
 During Perl 6 development, new features are often made available for
-users to experimental with before their design is completed. Eventually
-these features may be made part of the Perl 6 specification.  To use these
+users as experimental before their design is completed. Eventually
+these features may be made part of the Perl 6 specification. To use these
 features, one uses the C<experimental> pragma in program source code, for
 example, like this:
 
@@ -19,9 +19,8 @@ These are the features that, for the time being, are experimental.
 Pack is a feature that allows binary serialization of general data structures,
 and is inherited from
 L<Perl's pack|http://perldoc.perl.org/functions/pack.html>.
-The C<pack> order creates a
-C<Buf> by packing data structures in a certain way given by a I<packing string>
-with the options shown
+The C<pack> order creates a C<Buf> by packing data structures in a certain
+way given by a I<packing string> with the options shown
 L<in the description of C<unpack>|/type/Blob#method_unpack>. You turn it on by
 inserting this pragma at the beginning of your program:
 
@@ -120,8 +119,8 @@ it would be best to keep them away from production code. Meanwhile, taking a
 look at
 L<this article by Masak|https://perl6advent.wordpress.com/2012/12/23/day-23-macros/>
 as well as
-L<C<007>|https://github.com/masak/007>, a new macro language, which might show
-the shape of things to come.
+L<C<007>|https://github.com/masak/007>, a new macro language, might provide
+a glimpse into the things to come.
 
 =head2 X<B<cached>|:cached>