Reformatting and reflow

Author: JJ

doc/Language/list.pod6

@@ -4,11 +4,11 @@
 
 =SUBTITLE Positional data constructs
 
-Lists have been a central part of computing since before there were computers,
-during which time many devils have taken up residence in their details. They
-were actually one of the hardest parts of Perl 6 to design, but through
-persistence and patience, Perl 6 has arrived with an elegant system for handling
-them.
+Lists have been a central part of computing since before there were
+computers, during which time many devils have taken up residence in
+their details. They were actually one of the hardest parts of Perl 6 to
+design, but through persistence and patience, Perl 6 has arrived with an
+elegant system for handling them.
 
 =head1 Literal lists
 
@@ -219,16 +219,17 @@ to an C<@>-sigiled variable.
     @s[1]; # does not say anything
     @s[4]; # says 42 two more times
 
-You may also use the C<.cache> method instead of C<.list>, depending
-on how you want the references handled.  See the L<page on C<Seq>|/type/Seq>
-for details.
+You may also use the C<.cache> method instead of C<.list>, depending on
+how you want the references handled.  See the L<page on
+C<Seq>|/type/Seq> for details.
 
 =comment TODO document .iterator
 
 =head2 Slips
 
 Sometimes you want to insert the elements of a list into another list.
-This can be done with a special type of list called a L<Slip|/type/Slip>.
+This can be done with a special type of list called a
+L<Slip|/type/Slip>.
 
     say (1, (2, 3), 4) eqv (1, 2, 3, 4);         # OUTPUT: «False␤»
     say (1, Slip.new(2, 3), 4) eqv (1, 2, 3, 4); # OUTPUT: «True␤»
@@ -329,11 +330,12 @@ to put an infinite list, lest your program hang and, eventually, run out of memo
     my @a = (loop { $i.say; last unless --$i }); # OUTPUT: «3␤2␤1␤»
     say "take off!";
 
-=head2 Flattening "Context"
+=head2 Flattening "context"
 
-When you have a list that contains sub-lists, but you only want one flat list,
-you may flatten the list to produce a sequence of values as if all parentheses
-were removed. This works no matter how many levels deep the parentheses are nested.
+When you have a list that contains sub-lists, but you only want one flat
+list, you may flatten the list to produce a sequence of values as if all
+parentheses were removed. This works no matter how many levels deep the
+parentheses are nested.
 
     say (1, (2, (3, 4)), 5).flat eqv (1, 2, 3, 4, 5) # OUTPUT: «True␤»
 
@@ -356,15 +358,16 @@ flattening:
 
 When a list appears as arguments to a function or method call, special
 syntax rules are at play: the list is immediately converted into a
-C<Capture>.  A C<Capture> itself has a List (C<.list>) and a Hash (C<.hash>).
-Any C<Pair> literals whose keys are not quoted, or which are not parenthesized,
-never make it into C<.list>.  Instead, they are considered to be named
-arguments and squashed into C<.hash>.  See the L<page on C<Capture>|/type/Capture>
-for the details of this processing.
+C<Capture>.  A C<Capture> itself has a List (C<.list>) and a Hash
+(C<.hash>). Any C<Pair> literals whose keys are not quoted, or which are
+not parenthesized, never make it into C<.list>.  Instead, they are
+considered to be named arguments and squashed into C<.hash>.  See the
+L<page on C<Capture>|/type/Capture> for the details of this processing.
 
-Consider the following ways to make a new C<Array> from a C<List>.  These ways
-place the C<List> in an argument list context and because of that, the C<Array>
-only contains C<1> and C<2> but not the C<Pair> C<:c(3)>, which is ignored.
+Consider the following ways to make a new C<Array> from a C<List>.
+These ways place the C<List> in an argument list context and because of
+that, the C<Array> only contains C<1> and C<2> but not the C<Pair>
+C<:c(3)>, which is ignored.
 
     Array.new(1, 2, :c(3));
     Array.new: 1, 2, :c(3);
@@ -615,33 +618,34 @@ by hand to undo the nesting:
 
     say gather [0, [(1, 2), [3, 4]], $(5, 6)].deepmap: *.take; # OUTPUT: «(1 2 3 4 5 6)␤»
 
-...future versions of Perl 6 might find a way to make this easier.  However,
-not returning Arrays or itemized lists from functions, when non-itemized lists
-are sufficient, is something that one should consider as a courtesy to their
-users:
+... Future versions of Perl 6 might find a way to make this easier.
+However, not returning Arrays or itemized lists from functions, when
+non-itemized lists are sufficient, is something that one should consider
+as a courtesy to their users:
 
-=item use Slips when you want to always merge with surrounding lists
-=item use non-itemized lists when you want to make it easy for the user to flatten
-=item use itemized lists to protect things the user probably will not want flattened
-=item use Arrays as non-itemized lists of itemized lists, if appropriate,
-=item use Arrays if the user is going to want to mutate the result without copying it first.
+=item Use C<Slip>s when you want to always merge with surrounding lists.
+=item Use non-itemized lists when you want to make it easy for the user to flatten.
+=item Use itemized lists to protect things the user probably will not want flattened.
+=item Use C<Arrays> as non-itemized lists of itemized lists, if appropriate.
+=item Use C<Array>s if the user is going to want to mutate the result without copying it first.
 
-The fact that all elements of an array are itemized (in C<Scalar> containers)
-is more a gentleman's agreement than a universally enforced rule, and it is
-less well enforced that typechecks in typed arrays.  See the section below
-on binding to Array slots.
+The fact that all elements of an array are itemized (in C<Scalar>
+containers) is more a gentleman's agreement than a universally enforced
+rule, and it is less well enforced that typechecks in typed arrays.  See
+the section below on binding to Array slots.
 
 =head2 Literal arrays
 
-Literal Arrays are constructed with a List inside square brackets.  The List is
-eagerly iterated (at compile time if possible) and values in the list are each
-type-checked and itemized.  The square brackets themselves will spill elements
-into surrounding lists when flattened, but the elements themselves will not
-spill due to the itemization.
+Literal C<Array>s are constructed with a C<List> inside square brackets.
+The C<List> is eagerly iterated (at compile time if possible) and values
+in it are each type-checked and itemized.  The square brackets
+themselves will spill elements into surrounding lists when flattened,
+but the elements themselves will not spill due to the itemization.
 
 =head2 Mutability
 
-Unlike lists, Arrays are mutable.  Elements may deleted, added, or changed.
+Unlike lists, C<Array>s are mutable.  Elements may deleted, added, or
+changed.
 
     my @a = "a", "b", "c";
     @a.say;                  # OUTPUT: «[a b c]␤»
@@ -655,22 +659,23 @@ Unlike lists, Arrays are mutable.  Elements may deleted, added, or changed.
 
 =head3 Assigning
 
-Assignment of a list to an Array is eager.  The list will be entirely evaluated,
-and should not be infinite or the program may hang.  Assignment to a slice of
-an C<Array> is, likewise, eager, but only up to the requested number of elements,
-which may be finite:
+Assignment of a list to an C<Array> is eager.  The list will be entirely
+evaluated, and should not be infinite or the program may hang.
+Assignment to a slice of an C<Array> is, likewise, eager, but only up to
+the requested number of elements, which may be finite:
 
     my @a;
     @a[0, 1, 2] = (loop { 42 });
     @a.say;                     # OUTPUT: «[42 42 42]␤»
 
-During assignment, each value will be typechecked to ensure it is a permitted
-type for the C<Array>.  Any C<Scalar> will be stripped from each value and a
-new C<Scalar> will be wrapped around it.
+During assignment, each value will be typechecked to ensure it is a
+permitted type for the C<Array>.  Any C<Scalar> will be stripped from
+each value and a new C<Scalar> will be wrapped around it.
 
 =head3 Binding
 
-Individual Array slots may be bound the same way C<$>-sigiled variables are:
+Individual Array slots may be bound the same way C<$>-sigiled variables
+are:
 
     my $b = "foo";
     my @a = 1, 2, 3;
@@ -679,11 +684,12 @@ Individual Array slots may be bound the same way C<$>-sigiled variables are:
     $b = "bar";
     @a.say;          # OUTPUT: «[1 2 "bar"]␤»
 
-...but binding Array slots directly to values is strongly discouraged.  If you do,
-expect surprises with built-in functions.  The only time this would be done is if
-a mutable container that knows the difference between values and Scalar-wrapped
-values is needed, or for very large Arrays where a native-typed array cannot be used.
-Such a creature should never be passed back to unsuspecting users.
+... But binding C<Array> slots directly to values is strongly
+discouraged.  If you do, expect surprises with built-in functions.  The
+only time this would be done is if a mutable container that knows the
+difference between values and Scalar-wrapped values is needed, or for
+very large C<Array>s where a native-typed array cannot be used. Such a
+creature should never be passed back to unsuspecting users.
 
 =end pod