Update about.rakudoc (#4650)

CREDITS

@@ -107,6 +107,10 @@ E: [email protected]
 N: David M. Cawthon
 E: [email protected]
 
+N: David Simon Schultz
+U: schultzdavid
+E: [email protected]
+
 N: Dmitriy Olshevskiy
 E: [email protected]
 
@@ -117,6 +121,10 @@ N: Elizabeth Mattijsen
 U: lizmat
 E: [email protected]
 
+N: Eric Forste
+U: arkiuat
+E: [email protected]
+
 N: ennio
 E: [email protected]
 
@@ -376,7 +384,8 @@ N: Wenzel P. P. Peppmeyer
 U: gfldex
 E: [email protected]
 
-N: Will "Coke" Coleda
+N: Will Coleda
+N: Coke
 E: [email protected]
 
 N: Xtreak

doc/Language/about.rakudoc

@@ -2,7 +2,7 @@
 
 =TITLE About the docs
 
-=SUBTITLE How to contribute to Raku and to the documents, how to generate the docs locally
+=SUBTITLE How to locally generate the Raku documentation; and how to contribute to it.
 
 This document collection represents the on-going effort to document the
 Raku programming language with the goals of being comprehensive,

doc/Language/control.rakudoc

@@ -273,6 +273,27 @@ for it more strongly:
     $_ = 1; if 42 -> $a { $_.say;  $a.say } ; # says "1" then says "42"
     $_ = 1; if 42       { $_.say; $^a.say } ; # says "1" then says "42"
 
+This is especially useful for patterns of the kind
+"if something does not evaluate to False, do something with it":
+
+    sub get-user-id($username) { #`(return 0 if no such username exists) }
+
+    if prompt 'Enter username: ' -> $username {
+        if get-user-id($username) -> $user-id {
+            say "Found id $user-id for name $username";
+        }
+    }
+
+Here C<$username> and C<$user-id> are only defined inside
+their respective C<if> block that guarantees their being C<True>.
+This gives this solution an advantage
+over the more conventional C<my $username = …; if $username {…}>.
+
+Compare L<C<with>|/language/control#with>, which tests
+for definedness rather than truth, and topicalizes by default.
+(The second C<if> in the above example could be replaced by C<with> if the routine
+C<get-user-id> returned C<Nil> rather than 0 for nonexistent usernames.)
+
 =head2 X<C<else/elsif>|Control flow,else elsif>
 
 A compound conditional may be produced by following an C<if> conditional
@@ -583,7 +604,7 @@ list when they are needed, so to read a file line by line, you could
 use:
 
 =for code
-for $*IN.lines -> $line { .say }
+for $*IN.lines -> $ln { $ln.say }
 
 Iteration variables are always lexical, so you don't need to use C<my> to give
 them the appropriate scope. Also, they are read-only aliases. If you need them

doc/Language/modules.rakudoc

@@ -312,7 +312,7 @@ no matter whether the using program adds any tag or not.
     =end code
 
 5. Multiple tags may be used in the C<export> trait, but they must
-   all be separated by either commas, or whitespace, but not both.
+   all be separated by whitespace, with or without commas.
 
    =begin code
    sub foo() is export(:foo :s2 :net) {}

doc/Language/perl-op.rakudoc

@@ -52,7 +52,7 @@ also used for method calls.  So Perl's C«$arrayref->[7]» becomes
 Raku's C<$arrayref.[7]> and C«$user->name» becomes C<$user.name>.
 Note that dereferencing is rare in Raku.
 
-Raku uses the C<->> to attach L<C<Signature>|/type/Signature>s to
+Raku uses the C«->» to attach L<C<Signature>|/type/Signature>s to
 L<C<Block>|/type/Block>s.
 
 =head2 Auto-increment and auto-decrement

doc/Language/pod.rakudoc

@@ -550,9 +550,16 @@ C<my $var = 1; say $var;>
 
 C<my $var = 1; say $var;>
 
+If the enclosed code itself contains an unmatched C«>»,
+enclose it in C<C« »>
+=for code :lang<rakudoc>
+C«sub f(Int --> Int) {}»
+
+C«sub f(Int --> Int) {}»
+
 =head2 Links
 
-To create a link enclose it in C<L< >>:
+To create a link enclose it in C<L< >>
 
 =for code :lang<rakudoc>
 Raku homepage L<https://raku.org>

doc/Language/pragmas.rakudoc

@@ -55,16 +55,27 @@ use v6.*;         # Enables the available experimental preview features
 
 =head2 X<MONKEY-GUTS|Pragmas,MONKEY-GUTS>
 
+C<use MONKEY-GUTS;>
+
 This pragma is not currently part of any Raku specification, but is present
 in Rakudo as a synonym to C<use nqp> (see below).
 
 =head2 X<MONKEY-SEE-NO-EVAL|Pragmas,MONKEY-SEE-NO-EVAL>
+C<use EVAL;>
+
+Enables usage of the C<EVAL> routine,
+which due to its dangerousness would otherwise trigger a compiler error.
+For details, see L<routine C<EVAL>|/type/Independent-routines#routine_EVAL>.
 
-L<EVAL|/routine/EVAL>
+Note that, unlike the I<routine>, the C<EVAL> I<method> on an object
+can be executed without this pragma,
+i.e. an absence of C<MONKEY> pragmas is no guarantee against C<EVAL> calls.
 
 =head2 X<MONKEY-TYPING|Pragmas,MONKEY-TYPING>
 
-L<augment|/syntax/augment>
+C<use MONKEY-TYPING;>
+
+Enables C<augment> for adding methods (though not attributes) to existing classes and grammars. See L<augment|/syntax/augment>.
 
 =head2 X<MONKEY|Pragmas,MONKEY>
 

doc/Language/quoting.rakudoc

@@ -193,8 +193,8 @@ interpolated whenever the occur (unless escaped); that's why, in the example
 above, C<"$color"> became C<blue>.
 
 Variables with other sigils, however, only trigger interpolation when you follow
-the variable with the appropriate postfix (C<[]> for Arrays, C«<>», for Hashes,
-C<&> for Subs). This allows you to write expressions like
+the variable with the appropriate postfix (C<[]> for Arrays, C«<>» or C«{}» for Hashes,
+C<()> for Subs). This allows you to write expressions like
 C<"[email protected]"> without interpolating the C<@raku> variable.
 
 To interpolate an Array (or other L<C<Positional>|/type/Positional> variable),
@@ -562,6 +562,14 @@ some multi line
 =end code
 
 I<Heredocs> include the newline from before the terminator.
+A common idiom to remove it is to put a L<C<chomp>|/type/Str#routine_chomp> at the beginning, for example:
+
+=begin code
+my $s = chomp q:to/END/;
+The result will have
+no final newline.
+END
+=end code
 
 To allow interpolation of variables use the C<qq> form, but you will then have
 to escape metacharacters C<\{> as well as C<$> if it is not the sigil for a