Reflow and minor corrections

doc/Language/packages.pod6

@@ -12,15 +12,15 @@
 =end comment
 
 Packages are nested namespaces of named program elements.
-L<Modules|/language/module-packages>, classes,
-grammars, and others are types of packages. Like files in a directory, you can
-generally refer to named elements with their short-name if they are local, or
-with a longer name to disambiguate.
+L<Modules|/language/module-packages>, classes, grammars, and others are
+types of packages. Like files in a directory, you can generally refer to
+named elements with their short-name if they are local, or with the
+longer name that includes the namespace to disambiguate.
 
 =head1 Names
 
-A I<name> is anything that is a legal part of a variable name (not counting the
-sigil). This includes:
+A I<name> is anything that is a legal part of a variable name (not
+counting the sigil). This includes:
 
 =begin code
 class Foo {
@@ -46,24 +46,26 @@ C<::> is used to separate nested package names.
 
 =head2 Package-qualified names
 
-Ordinary package-qualified names look like; C<$Foo::Bar::quux> would be the
-C<$quux> variable in package C<Foo::Bar>; C<Foo::Bar::zape> would represent the
-C<&zape> variable in the same package.
+Ordinary package-qualified names look like this: C<$Foo::Bar::quux>,
+which would be the C<$quux> variable in package C<Foo::Bar>;
+C<Foo::Bar::zape> would represent the C<&zape> variable in the same
+package.
 
 Sometimes it's clearer to keep the sigil with the variable name, so an
 alternate way to write this is:
 
     Foo::Bar::<$quux>
 
-(This does not work with the C<&zape> variable) The name is resolved at compile
-time because the variable name is a constant.
+(This does not work with the C<&zape> variable) The name is resolved at
+compile time because the variable name is a constant.
 
-If the name part before C<::> is null, it means the package is unspecified and
-must be searched for. Generally this means that an initial C<::> following the
-main sigil is a no-op on names that are known at compile time, though C<::()>
-can also be used to introduce an interpolation. Also, in the absence of another
-sigil, C<::> can serve as its own sigil indicating intentional use of a
-not-yet-declared package name.
+If the name part before C<::> is null, it means the package is
+unspecified and must be searched for. Generally this means that an
+initial C<::> following the main sigil is a no-op on names that are
+known at compile time, though C<::()> can also be used to introduce an
+interpolation. Also, in the absence of another sigil, C<::> can serve as
+its own sigil indicating intentional use of a not-yet-declared package
+name.
 
 =head1 Pseudo-packages
 
@@ -97,29 +99,29 @@ anywhere in a name:
     CLIENT      The nearest CALLER that comes from a different package
 =end table
 
-The file's scope is known as C<UNIT>, but there are one or more lexical scopes
-outside of that corresponding to the linguistic setting (often known as the
-prelude in other cultures). Hence, the C<SETTING> scope is equivalent to
-C<UNIT::OUTERS>. For a standard Perl program C<SETTING> is the same as C<CORE>,
-but various startup options (such as C<-n> or C<-p>) can put you into a domain
-specific language, in which case C<CORE> remains the scope of the standard
-language, while C<SETTING> represents the scope defining the DSL that functions
-as the setting of the current file. When used as a search term in the middle of
-a name, C<SETTING> includes all its outer scopes up to C<CORE>. To get I<only>
+The file's scope is known as C<UNIT>, but there are one or more lexical
+scopes outside of that corresponding to the linguistic setting (often
+known as the prelude in other cultures). Hence, the C<SETTING> scope is
+equivalent to C<UNIT::OUTERS>. For a standard Perl 6 program C<SETTING>
+is the same as C<CORE>, but various startup options (such as C<-n> or
+C<-p>) can put you into a domain specific language, in which case
+C<CORE> remains the scope of the standard language, while C<SETTING>
+represents the scope defining the DSL that functions as the setting of
+the current file. When used as a search term in the middle of a name,
+C<SETTING> includes all its outer scopes up to C<CORE>. To get I<only>
 the setting's outermost scope, use C<UNIT::OUTER> instead.
 
 =head1 Looking up names
 
 =head2 Interpolating into names
 
-X<|::()>
-You may interpolate a string into a package or variable name using
-C<::($expr)> where you'd ordinarily put a package or variable name. The
-string is allowed to contain additional instances of C<::>, which will be
-interpreted as package nesting. You may only interpolate entire names,
-since the construct starts with C<::>, and either ends immediately or is
-continued with another C<::> outside the parentheses. Most symbolic references
-are done with this notation:
+X<|::()> You may interpolate a string into a package or variable name
+using C<::($expr)> where you'd ordinarily put a package or variable
+name. The string is allowed to contain additional instances of C<::>,
+which will be interpreted as package nesting. You may only interpolate
+entire names, since the construct starts with C<::>, and either ends
+immediately or is continued with another C<::> outside the parentheses.
+Most symbolic references are done with this notation:
 
 =for code :skip-test
 $foo = "Bar";
@@ -135,12 +137,13 @@ $::($foobar)::baz   # $Foo::Bar::baz
 $::($foo)::Bar::baz # $Bar::Bar::baz
 $::($foobar)baz     # ILLEGAL at compile time (no operator baz)
 
-An initial C<::> doesn't imply global. Here as part of the interpolation syntax
-it doesn't even imply package. After the interpolation of the C<::()>
-component, the indirect name is looked up exactly as if it had been there in
-the original source code, with priority given first to leading pseudo-package
-names, then to names in the lexical scope (searching scopes outwards, ending at
-C<CORE>). The current package is searched last.
+An initial C<::> doesn't imply global. Here as part of the interpolation
+syntax it doesn't even imply package. After the interpolation of the
+C<::()> component, the indirect name is looked up exactly as if it had
+been there in the original source code, with priority given first to
+leading pseudo-package names, then to names in the lexical scope
+(searching scopes outwards, ending at C<CORE>). The current package is
+searched last.
 
 Use the C<MY> pseudopackage to limit the lookup to the current lexical scope,
 and C<OUR> to limit the scopes to the current package scope.

doc/Language/syntax.pod6

@@ -16,18 +16,18 @@ verb is expected.
 It is also self-clocking, so that the parser can detect most of the
 common errors and give good error messages.
 
-=head1 Lexical Conventions
+=head1 Lexical conventions
 
-Perl 6 code is Unicode text, current implementations support UTF-8 as the
-input encoding.
+Perl 6 code is Unicode text. Current implementations support UTF-8 as
+the input encoding.
 
 See also L<Unicode versus ASCII symbols|/language/unicode_ascii>.
 
-=head2 Free Form
+=head2 Free form
 
-It is free-form, in the sense that you are mostly free to
-chose the amount of whitespace you chose, though in some cases, the presence
-or absence of whitespace carries meaning.
+Perl 6 code is also free-form, in the sense that you are mostly free to
+chose the amount of whitespace you use, though in some cases, the
+presence or absence of whitespace carries meaning.
 
 So you can write
 
@@ -63,17 +63,21 @@ though you can't leave out any of the remaining whitespace.
 X<|syntax,Unspace>
 
 In many places where the compiler would not allow a space you can use
-any whitespace that is quoted with a backslash. Unspaces in tokens are
-not supported. Newlines that are unspaced still count when the compiler
-produces line numbers. Use cases for unspace are separation of postfix
-operators and routine argument lists.
+any amount of whitespace, as long as it is quoted with a backslash.
+Unspaces in tokens are not supported. Newlines that are unspaced still
+count when the compiler produces line numbers. Use cases for unspace are
+separation of postfix operators and routine argument lists.
 
     sub alignment(+@l) { +@l };
     sub long-name-alignment(+@l) { +@l };
     alignment\         (1,2,3,4).say;
     long-name-alignment(3,5)\   .say;
     say Inf+Inf\i;
 
+In this case, our intention was to make the C<.> of both statements, as
+well as the parentheses, align, so we precede the whitespace used for
+padding with a C<\>.
+
 =head2 Separating statements with semicolons
 
 A Perl 6 program is a list of statements, separated by semicolons C<;>.