Completed macro intro. Refs #2514

Author: JJ

doc/Language/experimental.pod6

@@ -69,7 +69,37 @@ macro is-mighty( $who ) {
 say is-mighty "Freija";# OUTPUT: «Freija is mighty!␤»
 =end code
 
+Since macro expansion happens at parse time, care must be taken when using
+external variables in them:
+
+=begin code :skip-test<need use experimental>
+use experimental :macros;
+my $called;
+macro called() {
+    $called++;
+    quasi { "Called" }
+};
+say called() ~ " $called times";
+say called() ~ " $called times"; # OUTPUT: «Called 2 times␤Called 2 times␤»
+=end code
+
+Since macros are expanded at parse time, C<$called> will be the result when run
+time starts, which is already C<2>, as printed. Initializing C<$called> with 0,
+however, will make this print C<Called 0 times> since that initialization is run
+I<after> the parse phase, when the macros are expanded.
+
+Macros are terribly useful when complicated, computed initializations need to be
+done. However, they are still in the I<experimental> nursery for a good reason.
+Although the features shown above are not very likely to change, anything, even
+their very presence, might change at any one time depending in necessities, so
+it would be best to keep them away from production code. Meanwhile, taking a
+look at
+L<this article by Masak|https://perl6advent.wordpress.com/2012/12/23/day-23-macros/>
+as well as
+L<C<007>|https://github.com/masak/007>, a new macro language, which might show
+the shape of things to come.
 
 =end pod
 
+
 # vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6