Merge branch 'master' of git@github.com:perl6/book

src/builtins.pod

@@ -12,58 +12,81 @@ X<type>
 X<coercion>
 
 Many operators work on a particular I<type> of data. If the type of the
-operands is different, a copy of the operands is converted to the needed type.
-For example C<$a + $b> will convert a copy of both C<$a> and C<$b> to numbers
-(unless they are numbers already). This implicit conversion is called
-I<coercion>.
+operands differs from the type of the operand, Perl will make copies of the
+operands and convert those to the needed types.  For example, C<$a + $b> will
+convert a copy of both C<$a> and C<$b> to numbers (unless they are numbers
+already). This implicit conversion is called I<coercion>.
 
-Not only operators coerce their arguments: C<if> and C<while> coerce to truth
-values (bool), C<for> views things as lists and so on.
+Besides operators, other syntactic elements coerce their elements: C<if> and
+C<while> coerce to truth values (bool), C<for> views things as lists, and so
+on.
+
+=for author
+
+I've explained this as a form of context in the Modern Perl book; it may work
+here too.
+
+=end for
 
 =head1 Numbers
 
-Perl 6 has a few different number types which you can intermix freely:
-Subtracting a floating point value from an integer works with C<123 - 12.1e1>
-without any further ado.
+Sometimes coercion is intuitively transparent.  Perl 6 has several numeric
+types which you can intermix freely.  For example, subtracting a floating point
+value from an integer works, as in C<123 - 12.1e1>.
 
-The most important types are
+The most important types are:
 
 =over
 
 =item Int
 
+X<Int>
+X<types; Int>
+
 C<Int> objects store integer numbers of arbitrary size. If you write a literal
-that consists only of digits, like C<12>, it is an C<Int>.
+that consists only of digits, such as C<12>, it is an C<Int>.
 
 =item Rat
 
-C<Rat> is short for I<rational> and stores fractional numbers without loss of
-precision, by keeping track of numerator and denominator as integers.
-Since arithmetics with large integers can become quite slow,
-rationals with too large denominator automatically degrade to C<Num>.
+X<Rat>
+X<rational type>
+X<types; rational>
+X<types; Rat>
+
+C<Rat>, short for I<rational>, stores fractional numbers without loss of
+precision.  Because C<Rat> tracks its numerator and denominator as integers,
+mathmatical operations on C<Rat>s with large components can become quite slow.
+For this reason, rationals with large denominators automatically degrade to
+C<Num>.
 
 Writing a fractional value with a dot as the decimal separator produces a
 C<Rat>, for example C<3.14>.
 
 =item Num
 
-C<Num> is the floating point type. It stores sign, mantissa and exponent with
-a fixed width each. Calculations involving C<Num> numbers are usually quite
+X<Num>
+X<types; Num>
+
+C<Num> is the floating point type. It stores sign, mantissa, and exponent, each
+with a fixed width. Calculations involving C<Num> numbers are usually quite
 fast, but subject to limited precision.
 
-Numbers in scientific notation like C<6.022e23> are of type C<Num>.
+Numbers in scientific notation such as C<6.022e23> are of type C<Num>.
 
 =item Complex
 
-C<Complex> is the complex number type. Complex numbers have two
-parts to them: a real part and in imaginary part. If either part
-is considered C<Nan>, then the entire number may possibly be C<Nan>.
+X<Complex>
+X<types; Complex>
+
+C<Complex> is the complex number type. Complex numbers have two parts to them:
+a real part and in imaginary part. If either part is C<Nan>, then the entire
+number may possibly be C<Nan>.
 
 Numbers in the form C<a + bi> are of type C<Complex>.
 
 =back
 
-The following operators are available for all number types.
+The following operators are available for all number types:
 
     Binary operators:
     Operator     Description
@@ -74,15 +97,14 @@ The following operators are available for all number types.
     +            addition
     -            subtraction
 
-    Unary oerators:
+    Unary operators:
     Operator     Description
     +            conversion to number
     -            negation
 
 Most mathematical functions are available both as methods and functions, so
 you can write both C<(-5).abs> and C<abs(-5)>.
 
-
     Method      Description
     abs         absolute value
     sqrt        square root
@@ -94,18 +116,34 @@ you can write both C<(-5).abs> and C<abs(-5)>.
     round       rounding to next integer
     sign        -1 for negative, 0 for 0, 1 for positive values
 
-The trigonometric functions C<sin, cos, tan, asin, acos, atan, sec, cosec,
-cotan, asec, acosec, acotan, sinh, cosh, tanh, asinh, acosh, atanh, sech,
-cosech, cotanh, asech, acosech> and C<acotanh> are available, and work in
-units of radians by defaults. The unit can be changed with an argument of
-C<Degree>, C<Gradians> or C<Circles>, for example C<180.sin(Degrees)> is
-approximately C<0>.
+X<trigonometric functions>
+X<operators; trigonometry>
+X<units>
+
+=for author
+
+Gradians?  Are these functions also methods?
+
+=end for
+
+The trigonometric functions C<sin>, C<cos>, C<tan>, C<asin>, C<acos>, C<atan>,
+C<sec>, C<cosec>, C<cotan>, C<asec>, C<acosec>, C<acotan>, C<sinh>, C<cosh>,
+C<tanh>, C<asinh>, C<acosh>, C<atanh>, C<sech>, C<cosech>, C<cotanh>, C<asech>,
+C<acosech> and C<acotanh> are available, and work in units of radians by
+default. You may specify the unit with an argument of C<Degrees>, C<Gradians> or
+C<Circles>. For example, C<180.sin(Degrees)> is approximately C<0>.
 
 =head1 Strings
 
+X<strings>
+X<Str>
+X<types; Str>
+X<Buf>
+X<types; Buf>
+
 Strings stored as C<Str> are sequences of characters, independent of character
-encoding. For storing binary data, C<Buf> is available. The C<encode> method
-converts a C<Str> to C<Buf>, C<decode> in the other direction.
+encoding. The C<Buf> type is available for storing binary data. The C<encode>
+method converts a C<Str> to C<Buf>. C<decode> goes the other direction.
 
 The following operations are available for strings:
 
@@ -141,17 +179,19 @@ TODO: Str and Buf operators, methods
 
 =head1 Bool
 
-A Boolean value is either C<True> or C<False>. It is used for making all sorts
-of decisions in a program.
+X<Bool>
+X<types; Bool>
 
-Any value can be evaluated in boolean context, the rules for deciding if a
-value is true or false depends on the type of the value:
+A Boolean value is either C<True> or C<False>.  Any value can coerce to a
+boolean in boolean context. The rules for deciding if a value is true or false
+depends on the type of the value:
 
 =over
 
 =item Strings
 
-Empty strings and C<"0"> evaluate to C<False>, all other strings to C<True>.
+Empty strings and C<"0"> evaluate to C<False>.  All other strings evaluate to
+C<True>.
 
 =item Numbers
 
@@ -164,16 +204,22 @@ empty, and to C<True> if they contain at least one value.
 
 =back
 
-Constructs such as C<if> automatically evaluate their condition in boolean
-context. You can force numeric context by putting a C<?> in front of an
-expression. With a C<!> instead the meaning is negated.
+Constructs such as C<if> automatically evaluate their conditions in
+boolean context. You can force an explicit boolean context by
+putting a C<?> in front of an expression. The C<!> prefix negates
+the boolean value.
 
 =begin programlisting
 
     my $num = 5;
+
     # implicit boolean context
     if $num { say "True" }
+
     # explicit boolean context
-    my $bool = ?$num;
+    my $bool    = ?$num;
+
+    # negated boolean context
+    my $not_num = !$num;
 
 =end programlisting

src/grammars.pod

@@ -5,6 +5,8 @@ example demonstrates how to parse JSON, a data exchange format already
 introduced in the chapter on multi dispatch (TODO: make this a proper
 reference).
 
+=begin programlisting
+
     # file lib/JSON/Tiny/Grammar.pg
 
     grammar JSON::Tiny::Grammar {
@@ -85,6 +87,8 @@ reference).
         say "Not quite...";
     }
 
+=end programlisting
+
 A grammar contains various named regexes, one of which is
 called C<TOP>, and is called by C<JSON::Tiny.parse($string)>.
 
@@ -123,6 +127,8 @@ C<:sigspace> modifier. Which in turn internally replaces all whitespaces in
 the regex to calls to the C<ws> token. So all you've got to do is to override
 that:
 
+=begin programlisting
+
     grammar JSON::Tiny::Grammar::WithComments
         is JSON::Tiny::Grammar {
 
@@ -140,6 +146,8 @@ that:
         say "It's valid (modified) JSON";
     }
 
+=end programlisting
+
 The first two lines introduce a grammar that inherits from
 C<JSON::Tiny::Grammar>. The inheritance is specified with the C<is> trait.
 This means that the grammar rules are now called from the child grammar if it
@@ -159,6 +167,8 @@ have to write a function that traverses the match tree recursively, and
 search for bits and pieces you are interested in. Since this is a cumbersome
 task, an alternative solution exist: I<actions method>.
 
+=begin programlisting
+
     class JSON::Tiny::Actions {
         method TOP($/, $what) {
             make $/{$what}.ast;
@@ -231,6 +241,8 @@ task, an alternative solution exist: I<actions method>.
     # RAKUDO doesn't call action methods at the
     # end of each each rule yet
 
+=end programlisting
+
 We pass an actions object to the grammar's C<parse> method. Whenever the
 grammar engine finishes parsing one rule, or encounters a C<{*}> token in the
 grammar, it calls an method of the match object, with the same name as
@@ -252,6 +264,8 @@ Although the rules and action methods live in different namespaces (and in a
 real-world project probably even in separate files), we show them side by
 side to make the correspondence easier to see.
 
+=begin programlisting
+
     rule TOP {
         ^ [
             | <object> {*}      #= object
@@ -262,20 +276,28 @@ side to make the correspondence easier to see.
         make $/{$what}.ast;
     }
 
+=end programlisting
+
 The rule has an alternation with two branches, labeled by C<#= object>
 and C<#= array>. The first argument to the C<TOP> method is the current match
 object, the second is the label. The action method accesses the capture with
 the same name as branch, obtains the AST attached to it, and sets it to the
 AST of current match object by calling C<make>.
 
+=begin programlisting
+
     rule object     { '{' ~ '}' <pairlist>      {*}   }
     method object($/) {
         make %($<pairlist>.ast)
     }
 
+=end programlisting
+
 The action method for C<object> extracts the AST of the C<pairlist> submatch,
 and turns it into a hash by putting it inside C<%( ... )>.
 
+=begin programlisting
+
     rule pairlist   {
         <pair> ** ','
         {*}
@@ -284,17 +306,23 @@ and turns it into a hash by putting it inside C<%( ... )>.
         make = $<pair>».ast;
     }
 
+=end programlisting
+
 The C<pairlist> rule just matches multiple pairs, and the corresponding action
 method calls the C<.ast> method on each matched pair, and installs the result
 list in its own AST.
 
+=begin programlisting
+
     rule pair {
         <string> ':' <value>        {*}
     }
     method pair($/) {
         make ( $<string>.ast => $<value>.ast );
     }
 
+=end programlisting
+
 A pair consists of a string key and a value, so the action method constructs a
 Perl 6 pair with the C<< => >> operator.
 

src/preface.pod

@@ -30,15 +30,7 @@ book is not a comprehensive reference. It is a series of tutorials.
 
 =head1 Relationship between Perl 6 and Perl 5
 
-=for author
-RFC:
-This first sentence may set a tone we would rather avoid. Should we use
-something more along the lines of it being the newest member of the Perl
-family, as in masak++'s "How Perl 6 could kill us all!" post? The
-subsequent sentences would be fine as they are. --eternaleye
-=end for
-
-Perl 6 is the next major evolution of the language known as Perl. It
+Perl 6 is the newest member of the family of languages known as Perl. It
 represents a major break in syntactic and semantic compatibility from
 Perl 5, thus a major version number increase. However, this does not
 mean that Perl 5 is going away. In fact, quite the opposite. Both Perl 5