Merge pull request #1 from perl6/master

update from base

Author: lukasvalle

README.md

@@ -8,6 +8,10 @@ This is currently the recommended way to consume the documentation.
 There is also a command line tool called `p6doc`, which you can use to
 browse the documentation once it's installed (see below).
 
+This documentation is updated frequently to a GitHub mirror
+https://perl6docs.github.io but that might be out of sync with the
+official one.
+
 ## Docker container
 
 This documentation is also published as

doc/HomePage.pod6

@@ -34,8 +34,7 @@ by reporting mistakes or sending patches.
 
 <dt><a href="/programs.html">Perl 6 Programs</a></dt>
 <dd>
-    A collection of documents describing how to
-    run the Perl 6 executable program and other utilities,
+    A collection of documents describing the variables that affect the the Perl 6 executable, how to run the p6doc documentation front-end,
     how to debug Perl 6 programs, and how to hack on Perl 6
     source code.
 </dd>

doc/Language/5to6-nutshell.pod6

@@ -42,7 +42,7 @@ an embedded instance of the C<perl> interpreter to run Perl 5 code.
 
 This is as simple as:
 
-=for code :skip-test<Inline module not always present when testing>
+=for code :skip-test<needs ecosystem>
 # the :from<Perl5> makes Perl 6 load Inline::Perl5 first (if installed)
 # and then load the Scalar::Util module from Perl 5
 use Scalar::Util:from<Perl5> <looks_like_number>;
@@ -578,7 +578,7 @@ arguments. For example, C<31 | 33> returns a different result than C<"31" |
 In Perl 6, those single-character ops have been removed, and replaced by
 two-character ops which coerce their arguments to the needed context.
 
-=begin code :skip-test
+=begin code :lang<text>
 # Infix ops (two arguments; one on each side of the op)
 +&  +|  +^  And Or Xor: Numeric
 ~&  ~|  ~^  And Or Xor: String
@@ -1581,7 +1581,7 @@ sub baz($z) { say "baz $z" }
 To use this module, simply C<use Bar> and the functions C<foo> and
 C<bar> will be available
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar;
 foo(1);    #=> "foo 1"
 bar(2);    #=> "bar 2"
@@ -1628,30 +1628,30 @@ module.
 So, to import only the C<foo> routine, we do the following in the
 calling code:
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar <foo>;
 foo(1);       #=> "foo 1"
 
 Here we see that even though C<bar> is exportable, if we don't
 explicitly import it, it's not available for use.  Hence this causes an
 "Undeclared routine" error at compile time:
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar <foo>;
 foo(1);
 bar(5);       #!> "Undeclared routine: bar used at line 3"
 
 However, this will work
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar <foo bar>;
 foo(1);       #=> "foo 1"
 bar(5);       #=> "bar 5"
 
 Note also that C<baz> remains unimportable even if specified in the
 C<use> statement:
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar <foo bar baz>;
 baz(3);       #!> "Undeclared routine: baz used at line 2"
 
@@ -1678,7 +1678,7 @@ sub baz() is export(:DEFAULT:FNORBL) { }  # added to both
 
 So now you can use the C<Bar> module like this:
 
-=for code :skip-test
+=for code :skip-test<needs dummy module>
 use Bar;                     # imports foo / baz
 use Bar :FNORBL;             # imports bar / baz
 use Bar :ALL;                # imports foo / bar / baz

doc/Language/5to6-perlvar.pod6

@@ -173,7 +173,7 @@ No longer exists in Perl 6.  Because each Repository is responsible for
 remembering which modules have been loaded already. You can get a list
 of all loaded modules (compilation units) like so:
 
-=for code :skip-test<missing module>
+=for code :skip-test<needs dummy module>
 use Test;
 use MyModule;
 say flat $*REPO.repo-chain.map(*.loaded); #-> (MyModule Test)

doc/Language/about.pod6

@@ -71,7 +71,7 @@ All of the paragraphs and blocks following that directive, up until the
 next directive of the same level, will be considered part of the
 documentable. So, in:
 
-=begin code :allow<R> :skip-test
+=begin code :allow<R> :lang<pod6>
 =head2 R<My Definition>
 
 Some paragraphs, followed by some code:
@@ -148,4 +148,4 @@ Notice that text after a pipe ('|') has no formatting. Also note that B<V< C<> >
 preserves spaces and treats text as verbatim.
 =end pod
 
-# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

doc/Language/classtut.pod6

@@ -223,8 +223,8 @@ this attribute is private to the class.
 
 The second declaration also uses the private twigil:
 
-=for code :skip-test
-has Task @!dependencies;
+    =for code :preamble<class Task {}>
+    has Task @!dependencies;
 
 However, this attribute represents an array of items, so it requires the
 C<@> sigil. These items each specify a task that must be completed before
@@ -276,9 +276,9 @@ those with and without accessors):
 The assignment is carried out at object build time. The right-hand side is
 evaluated at that time, and can even reference earlier attributes:
 
-=for code :skip-test
-has Task @!dependencies;
-has $.ready = not @!dependencies;
+    =for code :preamble<class Task {}>
+    has Task @!dependencies;
+    has $.ready = not @!dependencies;
 
 Writable attributes are accessible through writable containers:
 
@@ -367,7 +367,7 @@ ignore the C<new> method temporarily; it's a special type of method.
 Consider the second method, C<add-dependency>, which adds a new task to a
 task's dependency list.
 
-    =begin code :skip-test
+    =begin code :skip-test<incomplete code>
     method add-dependency(Task $dependency) {
         push @!dependencies, $dependency;
     }
@@ -386,7 +386,7 @@ attribute.
 
 The C<perform> method contains the main logic of the dependency handler:
 
-    =begin code :skip-test
+    =begin code :skip-test<incomplete code>
     method perform() {
         unless $!done {
             .perform() for @!dependencies;
@@ -490,8 +490,9 @@ allowed to bind things to C<&!callback> and C<@!dependencies> directly. To
 do this, we override the C<BUILD> submethod, which is called on the brand
 new object by C<bless>:
 
-=for code :skip-test
-submethod BUILD(:&!callback, :@!dependencies) { }
+    =begin code :preamble<has &.callback; has @.dependencies;>
+    submethod BUILD(:&!callback, :@!dependencies) { }
+    =end code
 
 Since C<BUILD> runs in the context of the newly created C<Task> object, it
 is allowed to manipulate those private attributes. The trick here is that
@@ -503,15 +504,15 @@ more information.
 The C<BUILD> method is responsible for initializing all attributes and must also
 handle default values:
 
-    =begin code :skip-test
+    =begin code
     has &!callback;
     has @!dependencies;
     has Bool ($.done, $.ready);
     submethod BUILD(
             :&!callback,
             :@!dependencies,
             :$!done = False,
-            :$!ready = not @!dependencies
+            :$!ready = not @!dependencies,
         ) { }
     =end code
 

doc/Language/concurrency.pod6

@@ -758,7 +758,7 @@ execution before normal completion:
      $cancellation.cancel;
      sleep 10;
 
-should only output 0 to 5,
+should only output 0 to 5.
 
 Despite the apparent advantage the L<Scheduler|/type/Scheduler> interface provides over
 that of L<Thread|/type/Thread> all of functionality is available through higher level

doc/Language/control.pod6

@@ -89,7 +89,7 @@ Class bodies behave like simple blocks for any top level expression; same goes
 to roles and other packages, like grammars (which are actually classes)
 or modules.
 
-=begin code :skip-test<Fails>
+=begin code :skip-test<dies deliberately>
 class C {
     say "I live";
     die "I will never live!"

doc/Language/experimental.pod6

@@ -61,7 +61,7 @@ Macro processing happens during parsing time. A macro generates an abstract
 syntax tree, which is grafted into the program syntax tree. C<quasi> is the
 routine that performs this task.
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro does-nothing() {
     quasi {}
 };
@@ -72,7 +72,7 @@ X<|quasi (macros)>
 Macros are a kind of routine, so they can take arguments in exactly the same
 way, and act also in almost the same way.
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro is-mighty( $who ) {
     quasi { "$who is mighty!"}
 };
@@ -86,7 +86,7 @@ including the quotes. Please note that we can also eliminate the parentheses for
 a macro call, following the same rules as a routine. You can use the unquoting
 construct C<{{{}}}> to get rid of this kind of thing:
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 macro is-mighty( $who ) {
     quasi { {{{$who}}} ~ " is mighty!"}
 };
@@ -96,7 +96,7 @@ say is-mighty "Freija";  # OUTPUT: «Freija is mighty!␤»
 Since macro expansion happens at parse time, care must be taken when using
 external variables in them:
 
-=begin code :skip-test<need use experimental>
+=begin code :skip-test<needs experimental>
 use experimental :macros;
 my $called;
 macro called() {
@@ -136,7 +136,7 @@ It can be used when heavy calculations are involved, as in this sample that uses
 L<amicable numbers|https://perl6advent.wordpress.com/2018/12/25/calling-numbers-names/#more-7528>,
 taken from the 2018 Advent Calendar:
 
-=begin code :skip-test<Uses experimental>
+=begin code :skip-test<needs experimental>
 use experimental :cached;
 
 sub aliquot-parts( $number ) is cached {

doc/Language/functions.pod6

@@ -362,7 +362,7 @@ arguments. Consider this basic example:
     congratulate('being a cool number', 'Fred');     # OK
     congratulate('being a cool number', 'Fred', 42); # OK
 
-=for code :skip-test<Proto match error>
+=for code :skip-test<illustrates error>
 congratulate('being a cool number', 42);         # Proto match error
 
 The proto insists that all C<multi congratulate> subs conform to the basic
@@ -395,7 +395,7 @@ with. Parameter defaults and type coercions will work but are not passed on.
 proto mistake-proto(Str() $str, Int $number = 42) {*}
 multi mistake-proto($str, $number) { say $str.^name }
 mistake-proto(7, 42);  # OUTPUT: «Int␤» -- not passed on
-=for code :skip-test<compilation error>
+=for code :skip-test<illustrates error>
 mistake-proto('test'); # fails -- not passed on
 
 =head2 X<only|declarator>
@@ -764,7 +764,7 @@ type, variable, routine, attribute, or other language object.
 
 Examples of traits are:
 
-=for code :skip-test
+=for code :skip-test<incomplete code>
 class ChildClass is ParentClass { ... }
 #                ^^ trait, with argument ParentClass
 has $.attrib is rw;
@@ -1025,9 +1025,10 @@ say square-root(-4);    # OUTPUT: «0+2i␤»
 
 Another use case is to re-dispatch to methods from parent classes.
 
-=begin code 
+=for code
 say Version.new('1.0.2') # OUTPUT: v1.0.2
 
+=begin code
 class LoggedVersion is Version {
     method new(|c) {
         note "New version object created with arguments " ~ c.perl;