Adds explanation of EVAL

With possible errors that can be found there. This would close #2099. If the new text is not satisfactory, please feel free to reopen specifying what's the part of the problem it does not solve.

Author: JJ

doc/Language/5to6-perlfunc.pod6

@@ -457,8 +457,10 @@ C<$filehandle.eof>. Returns C<True> if at end of file.
 
 =item eval EXPR
 
-Replaced by L<EVAL|/routine/EVAL>. Note that C<EVAL> does not do any
-L<exception handling|/language/exceptions>!
+The closest replacment is the L<EVAL|/routine/EVAL> function. However,
+this function has to be allowed explicitly using a pragma to work in the
+same way. Note that C<EVAL> does not do any L<exception
+handling|/language/exceptions>!
 
 =head2 evalbytes
 

doc/Type/Cool.pod6

@@ -7,13 +7,13 @@
     class Cool is Any { }
 
 C<Cool>, also known as the B<C>onvenient B<OO> B<L>oop, is a base class
-employed by a number of built-in classes that can be meaningfully coerced
-to a string and a number. For example, an L<Array> can be used in mathematical
-operations, where its numerical representation is the number of elements it
-contains. At the same time, it can be concatenated to a string, where its
-stringy representation is all of its elements L<joined|/routine/join> by
-a space. Because L<Array> is L<Cool>, the appropriate coercion happens
-automatically.
+employed by a number of built-in classes that can be meaningfully
+coerced to a string and a number. For example, an L<Array> can be used
+in mathematical operations, where its numerical representation is the
+number of elements it contains. At the same time, it can be concatenated
+to a string, where its stringy representation is all of its elements
+L<joined|/routine/join> by a space. Because L<Array> is L<Cool>, the
+appropriate coercion happens automatically.
 
 Methods in C<Cool> coerce the invocant to a more
 specific type, and then call the same method on that type. For example both
@@ -1311,31 +1311,46 @@ method EVAL(*%_)
 =for code
 sub EVAL($code where Cool|Blob, :$lang = 'perl6')
 
-Method form calls subroutine form with invocant as C<$code>, passing along
-named args, if any. Subroutine form coerces L<Cool> C<$code> to L<Str>.
-If C<$code> is a L<Blob>, it'll be processed using the same encoding as
-the C<$lang> compiler would: for C<perl6>, uses the encoding specified
-via C<--encoding> command line argument, or C<utf-8> if none were given;
-for C<Perl5>, processes using same rules as C<perl>.
+The method form calls subroutine form with invocant as C<$code>, passing
+along named args, if any. Subroutine form coerces L<Cool> C<$code> to
+L<Str>. If C<$code> is a L<Blob>, it'll be processed using the same
+encoding as the C<$lang> compiler would: for C<perl6>, uses the encoding
+specified via C<--encoding> command line argument, or C<utf-8> if none
+were given; for C<Perl5>, processes using same rules as C<perl>.
 
-This works as-is with a literal string parameter. More complex input, such as
-a variable or string with embedded code, is illegal by default. This can be
-overridden in any of several ways:
+This works as-is with a literal string parameter. More complex input,
+such as a variable or string with embedded code, is illegal by default.
+This can be overridden in any of several ways:
 
-    use MONKEY-SEE-NO-EVAL;
-    use MONKEY;  # shortcut that turns on all MONKEY pragmas
+    use MONKEY-SEE-NO-EVAL; # Or...
+    use MONKEY;             # shortcut that turns on all MONKEY pragmas
     use Test;
 
     # any of the above allows:
     EVAL "say { 5 + 5 }";   # OUTPUT: «10␤»
 
+In case the C<MONKEY-SEE-NO-EVAL> pragma is not activated, the compiler
+will complain with a C<EVAL is a very dangerous function!!!> exception.
+And it is essentially right, since that will run arbitrary code with the
+same permissions as the program. You should take care of cleaning the
+code that is going to pass through EVAL if you activate the
+C<MONKEY-SEE-NO-EVAL> pragma.
+
+Please note that you can interpolate to create routine names using
+quotation, as can be seen in
+L<this example|/language/quoting#index-entry-%26_(interpolation)>
+or  L<other ways to interpolate to create identifier names|/language/syntax#Identifiers>.
+This only works, however, for already declared functions and other
+objects and is thus safer to use.
+
 Symbols in the current lexical scope are visible to code in an C<EVAL>.
 
     my $answer = 42;
     EVAL 'say $answer;';    # OUTPUT: «42␤»
 
-However, since the set of symbols in a lexical scope is immutable after compile
-time, an EVAL can never introduce symbols into the surrounding scope.
+However, since the set of symbols in a lexical scope is immutable after
+compile time, an EVAL can never introduce symbols into the surrounding
+scope.
 
 =for code :skip-test
 EVAL 'my $lives = 9'; say $lives;   # error, $lives not declared

doc/Type/Signature.pod6

@@ -440,9 +440,9 @@ except the C<$var> is a definition for a routine.
 
 =head3 X<Coercion Type|coercion type (signature)>
 
-To accept one type but coerce it automatically to another, use the accepted
-type as an argument to the target type. If the accepted type is C<Any> it can
-be omitted.
+To accept one type but coerce it automatically to another, use the
+accepted type as an argument to the target type. If the accepted type is
+C<Any> it can be omitted.
 
     sub f(Int(Str) $want-int, Str() $want-str) {
         say $want-int.^name ~ ' ' ~ $want-str.^name
@@ -456,10 +456,10 @@ be omitted.
     foo "2016-12-01";
     # OUTPUT: «Date␤2016-12-01␤»
 
-The coercion is performed by calling the method with the name of the type
-to coerce to, if it exists (e.g. C<Foo(Bar)> coercer, would call method C<Foo>).
-The method is assumed to return the correct type—no additional checks on
-the result are currently performed.
+The coercion is performed by calling the method with the name of the
+type to coerce to, if it exists (e.g. C<Foo(Bar)> coercer, would call
+method C<Foo>). The method is assumed to return the correct type—no
+additional checks on the result are currently performed.
 
 Coercion can also be performed on return types: