Merge pull request #2504 from uzluisf/master

Whitespace and minor improvements. Refs #2354

Author: JJ

doc/Language/py-nutshell.pod6

@@ -5,17 +5,17 @@
 =SUBTITLE Learning Perl 6 from Python, in a nutshell
 
 This page is an attempt to provide a way to learn Perl 6
-for folks coming from a Python background.  We discuss
+for folks coming from a Python background. We discuss
 the equivalent syntax in Perl 6 for a number of Python
 constructs and idioms.
 
 =head1 Basic syntax
 
 =head2 Hello, world
 
-Let's start with printing "Hello, world!". L<put> in Perl 6 is the
-equivalent of L<print> in Python.  Like Python 2, parentheses are
-optional. A return is added to the end of the line.
+Let's start with printing "Hello, world!". The L<put> keyword in Perl 6
+is the equivalent of L<print> in Python. Like Python 2, parentheses are
+optional. A newline is added to the end of the line.
 
 Python 2
 
@@ -31,14 +31,14 @@ Perl 6
 
     put "Hello, world!"
 
-There is also L<say>, which behaves similarly, but will call
+There is also the L<say> keyword, which behaves similarly, but will call
 the L<gist> method of its argument.
 
 Perl 6
 
-   my $hello; ...;
-   say "Hello, world!";  # also prints "Hello, world"
-   say $hello;           # same as: put $hello.gist
+   my $hello = "Hello, world!";
+   say $hello;  # also prints "Hello, world!"
+                # same as: put $hello.gist
 
 In Python, C<'> and C<"> are interchangeable.
 In Perl 6, both may be used for quoting, but double
@@ -57,14 +57,14 @@ Perl 6
 
 In Python, a newline signifies the end of a statement.
 There are a few exceptions: A backslash before a newline
-continues a statement across lines.  Also if there is
+continues a statement across lines. Also if there is
 an unmatched opening parentheses, square bracket, or curly
 brace, the statement continues across lines, until the
 matching curly braces are closed.
 
 In Perl 6, a semicolon signifies the end of a statement.
 The semicolon may be omitted if it is the last statement
-of a block.  The semicolon may also be omitted if there
+of a block. The semicolon may also be omitted if there
 is a closing curly brace followed by a newline.
 
 Python
@@ -79,11 +79,12 @@ Perl 6
 
     say 1 + 2 +
         3 + 4;
-    if True { say 1 + 2 }
+    say 1 +
+        2;
 
 =head2 Blocks
 
-In Python, indentation is used to indicate a block.  Perl 6
+In Python, indentation is used to indicate a block. Perl 6
 uses curly braces.
 
 Python
@@ -102,7 +103,7 @@ Perl 6
         say "1 is not 2."
     }
 
-Parentheses are optional in both languages in expressions in
+Parentheses are optional in both languages for expressions in
 conditionals, as shown above.
 
 =head2 Variables
@@ -113,16 +114,18 @@ In Python, variables are declared and initialized at the same time:
 foo = 12
 bar = 19
 
-In Perl 6, C<my> declares a lexical variable.  A variable can be
-initialized with C<=>.  i.e. these can be written as two statements or one.
+In Perl 6, the C<my> declarator declares a lexical variable. A variable can be
+initialized with C<=>. This variable can either be declared first and later
+initialized or declared and initialized at once.
+
 
     my $foo;       # declare
     $foo = 12;     # initialize
     my $bar = 19;  # both at once
 
 Also, as you may have noticed, variables in Perl 6 usually start with
-sigils -- symbols indicating the type of their container.  Variables
-starting with a C<$> hold scalars.  Variables starting with an C<@>
+sigils -- symbols indicating the type of their container. Variables
+starting with a C<$> hold scalars. Variables starting with an C<@>
 hold arrays, and variables starting with a C<%> hold a hash (dict).
 Immutable variables can be sigil-less, if they are declared with a C<\>.
 
@@ -156,8 +159,9 @@ Perl 6
 =head2 Scope
 
 In Python, functions and classes create a new scope, but no other
-block constructor (e.g. loops, conditionals) creates a scope.  In
-Python 2, list comprehensions do not create a new scope, but in Python 3, they do.
+block constructor (e.g. loops, conditionals) creates a scope. In
+Python 2, list comprehensions do not create a new scope, but in
+Python 3, they do.
 
 In Perl 6, every block creates a lexical scope.
 
@@ -223,7 +227,7 @@ Perl 6
     my $l = * + 12    # same as above
 
 A C<*> in an expression will become a placeholder for the argument,
-and transform the expression into a lambda at compile time.  Each
+and transform the expression into a lambda at compile time. Each
 C<*> in an expression is a separate positional parameter.
 
 See the section below for more constructs regarding subroutines and blocks.
@@ -250,9 +254,9 @@ Perl 6
     say squares[4]();
     # 4, 16 since each loop iteration has a lexically scoped x,
 
-Note that C<^N> is like C<range(N)>.  Similarly,
+Note that C<^N> is like C<range(N)>. Similarly,
 C<N..^M> works like C<range(N, M)> (a list from N
-to M - 1).  C<N..M> is a list from N to M.  The
+to M - 1). The range C<N..M> is a list from N to M. The
 C<^> before or after the C<..> indicates that the
 beginning or ending endpoint of the list (or both)
 should be excluded.
@@ -288,11 +292,11 @@ Perl 6 also has C<for> loops and C<while> loops:
         $j += 1
     }
 
-(Perl 6 also has a few more looping constructs: C<repeat, until>,
-C<repeat, while>, C<until>, and C<loop>.)
+(Perl 6 also has a few more looping constructs: C<repeat...until>,
+C<repeat...while>, C<until>, and C<loop>.)
 
 C<last> leaves a loop in Perl 6, and is analogous to
-C<break> in Python.  C<continue> in Python is C<next>
+C<break> in Python. C<continue> in Python is C<next>
 in Perl 6.
 
 Python
@@ -317,8 +321,8 @@ Using C<if> as a statement modifier (as above) is acceptable
 in Perl 6, even outside of a list comprehension.
 
 The C<yield> statement within a C<for> loop in Python, which produces a
-C<generator>, is like a C<gather>/C<take> construct in Perl 6.  These both print
-1, 2, 3.
+C<generator>, is like a C<gather>/C<take> construct in Perl 6. These
+both print 1, 2, 3.
 
 I<Python>
 
@@ -446,16 +450,16 @@ Perl 6
     my $square = { $^x ** 2 };          # placeholder variable
     my $square = { $_ ** 2 };           # topic variable
 
-Placeholder variables are lexicographically ordered to form positional parameters.
-i.e. these are the same:
+Placeholder variables are lexicographically ordered to form positional
+parameters. Thus these are the same:
 
     my $power = { $^x ** $^y };
     my $power = -> $x, $y { $x ** $y };
 
 =head2 X<List comprehensions|Python>
 
-Postfix statement modifiers and blocks can be combined to make list
-comprehensions.
+Postfix statement modifiers and blocks can be combined to
+easily create list comprehensions in Perl 6.
 
 Python
 
@@ -468,7 +472,7 @@ Perl 6
     say ( { $^i * 2 } for 3, 9 );                      # OUTPUT: «(6 18)␤»
     say ( -> \i { i * 2 } for 3, 9 );                  # OUTPUT: «(6 18)␤»
 
-Conditionals can be applied, but the C<if> comes first,
+Conditionals can be applied, but the C<if> keyword comes first,
 unlike in Python where the if comes second.
 
 =for code :lang<python>
@@ -496,7 +500,8 @@ C<grep> (which is like Python's C<filter>) is an alternative.
 
 Here's an example from the Python
 L<docs|https://docs.python.org/3/tutorial/classes.html#class-and-instance-variables>.
-First, "instance variables", aka attributes in Perl 6:
+First let's go over "instance variables" which are known as attributes
+in Perl 6:
 
 Python:
 
@@ -511,8 +516,8 @@ Perl 6:
         has $.name;
     }
 
-Constructors by default take named arguments in Perl 6,
-and use the method C<new>.
+For each created class, Perl 6 provides the constructor method C<new>
+by default which takes named arguments.
 
 Python:
 
@@ -524,13 +529,12 @@ print e.name
 
 Perl 6
 
-    class Dog {}; ...;
-    my $d = Dog.new(:name<Fido>);
+    my $d = Dog.new(:name<Fido>); # or: Dog.new(name => 'Fido')
     my $e = Dog.new(:name<Buddy>);
     say $d.name;
     say $e.name;
 
-Class attributes in Perl 6 can be declared in a few ways.  One way
+Class attributes in Perl 6 can be declared in a few ways. One way
 is to just declare a lexical variable and a method for accessing it.
 
 Python:
@@ -562,7 +566,8 @@ Perl 6:
     say $d.name;
     say $e.name;
 
-To mutate attributes, in Perl 6 you"ll want to use C<is rw>:
+In order to mutate attributes in Perl 6, you must use
+the C<is rw> trait on the attributes:
 
 Python:
 
@@ -611,7 +616,9 @@ Perl 6
     my $d = Dog.new;
     $d.jump;
 
-Multiple inheritance is possible by using C<is> multiple times, or with C<also>.
+Multiple inheritance is possible by using the C<is> trait as many times
+as required. Alternatively, it can be used in conjuntion with the
+C<also> keyword.
 
 Python
 
@@ -638,7 +645,7 @@ or
 =head2 X<Decorators|Python>
 
 Decorators in Python are a way of wrapping a function
-in another one.  In Perl 6, this is done with C<wrap>.
+in another one. In Perl 6, this is done with C<wrap>.
 
 Python
 
@@ -728,16 +735,15 @@ run on entering or leaving a block.
 
 =head2 X<C<input>|Python>
 
-In Python 3, the C<input> keyword is used to prompt the user. C<input> can be
-provided with an optional argument which is written to standard output without
-a trailing newline:
+In Python 3, the C<input> keyword is used to prompt the user. This keyword
+can be provided with an optional argument which is written to standard output
+without a trailing newline:
 
 =begin code :lang<python>
 user_input = input("Say hi → ")
 print(user_input)
 =end code
 
-
 When prompted, you can enter C<Hi> or any other string, which will be stored
 in the C<user_input> variable. This is similar to L<prompt> in Perl 6: