Merge branch 'master' of https://github.com/perl6/doc into grammars-pod

CONTRIBUTING.md

@@ -174,12 +174,17 @@ Report issues at https://github.com/perl6/doc/issues. You can use the
 following labels when tagging tickets:
 
 * site   - presentation issue with the website (e.g. invalid HTML)
-* docs   - missing or incorrect documentation
+* docs   - missing or incorrect documentation (use 'NOTSPECCED' instead, if this is for a feature present in a compiler, but not in the Perl 6 test suite)
 * build  - scripts or libraries that generate the site
-* search - the search component
+* search - the search component, either for items that are on the site but not searchable, or for search functionality)
+
+Contributors may also specify one of the following tags.
 
 * LHF    - for a beginner to work on
-* big    - a big issue, may require some research
+* big    - a big issue, requires research or consensus
+
+If you would like to contribute documentation or other bug fixes, please use
+github's Pull request feature.
 
 ## Website Styles
 

META.info

@@ -3,7 +3,8 @@
     "name"        : "p6doc",
     "version"     : "*",
     "description" : "Perl 6 documentation (tools and docs)",
-    "depends"     : [ "URI", "File::Temp", "JSON::Fast", "Pod::To::BigPage", "Pod::To::HTML" ],
+    "depends"     : [ "URI", "File::Temp", "JSON::Fast", "Pod::To::BigPage", "Pod::To::HTML",
+                      "OO::Monitors" ],
     "build-depends" : [ "File::Find" ],
     "provides"    : {
         "Perl6::Type"                   : "lib/Perl6/Type.pm",

assets/sass/style.scss

@@ -545,5 +545,6 @@ div.highlight span.c-Singleline, div.highlight span.c {
 }
 
 a[href*="//"]:not([href*="perl6.org"])::after {
+    padding-left: 2px;
     content: url(/images/External-link-04-bold-12x12.svg);
 }

doc/HomePage.pod6

@@ -3,7 +3,7 @@
 Welcome to the official documentation of the <a href="https://perl6.org">Perl 6</a>
 programming language!
 Besides online browsing and searching, you can also
-Z<< <a>download</a> an offline HTML or PDF copy, and>>
+<a href="/perl6.xhtml">view everything in one file</a> or
 <a href="https://github.com/perl6/doc">contribute</a>
 by reporting mistakes or sending patches.
 

doc/Language/5to6-nutshell.pod6

@@ -37,22 +37,9 @@ If the module that you were using has not been converted to Perl 6, and no
 alternative is listed in this document, then its use under Perl 6 may not
 have been addressed yet.
 
-There are multiple projects aiming to make it possible to C<use> Perl 5
-modules directly from Perl 6 code:
-
-=defn  L<v5|https://github.com/rakudo-p5/v5/>
-A slang that lets Rakudo itself parse blocks of Perl 5 code, and compile
-them to the same bytecode that it compiles Perl 6 code to.
-
-=defn  L<Inline::Perl5|https://github.com/niner/Inline-Perl5/>
-Uses an embedded instance of the C<perl> interpreter to run Perl 5 code
-called from your Perl 6 script.
-
-Of these, Inline::Perl5 is currently the furthest along and the most
-promising.
-
-
-
+The L<Inline::Perl5|https://github.com/niner/Inline-Perl5/> project makes
+it possible to C<use> Perl 5 modules directly from Perl 6 code by using
+an embedded instance of the C<perl> interpreter to run Perl 5 code.
 
 =head1 Syntax
 

doc/Language/5to6-perlfunc.pod6

@@ -209,10 +209,12 @@ it as a method, e. g. C<$fh.chmod(0o755)>.
 =item chomp VARIABLE
 
 The behavior of C<chomp> is different than in Perl 5. It leaves the
-target unaffected and I<returns> the target with a final logical newline
-removed. I. e. C<$x = "howdy\n";$y = chomp($x);> results in C<$x>
+target unaffected and I<returns> a copy of the target with a final logical newline
+removed, e.g. C<$x = "howdy\n";$y = chomp($x);> results in C<$x>
 containing "howdy\n" and C<$y> containing "howdy". Also works as a
-method, i. e. C<$y = $x.chomp>.
+method, e.g. C<$y = $x.chomp>. As with many other methods, also works
+with assignment to modify the target in place, e.g. C<$x.=chomp> results
+in C<$x> containing "howdy".
 
 =head2 chop
 

doc/Language/about.pod6

@@ -93,7 +93,7 @@ example, often contain the methods the class implements.
 Definitions must be in one of the following forms to be recognized as
 the start of a documentable named, say, Z.  First the code in the document source:
 
-=begin code
+=begin code :skip-test
 
 =item X<C<How to use the Z infix> | infix,Z> (This a special case, which
 is always considered a definition)
@@ -131,7 +131,7 @@ You can add emphasis with bold (B<V< B<> >>) or italicized (B<V< I<> >>),
 with or without code formatting (B<V< C<> >>).  Due to current parser limitations,
 special steps have to be taken to use B<V< X<> >> with other formatting codes; for example:
 
-=begin code
+=begin code :skip-test
 =item X<B<foo>|foo> a fancy subroutine
 =end code
 

doc/Language/classtut.pod6

@@ -145,7 +145,8 @@ key principles of object oriented design.
 The first declaration specifies instance storage for a callback – a bit of
 code to invoke in order to perform the task that an object represents:
 
-    has &!callback;
+=for code :skip-test
+has &!callback;
 
 X<|sigils,&>
 X<|twigils>
@@ -158,7 +159,8 @@ this attribute is private to the class.
 
 The second declaration also uses the private twigil:
 
-    has Task @!dependencies;
+=for code :skip-test
+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
@@ -168,7 +170,8 @@ class (or some subclass of it).
 
 The third attribute represents the state of completion of a task:
 
-    has Bool $.done;
+=for code :skip-test
+has Bool $.done;
 
 X<|twigils,.>
 X<|twigils,accessors>
@@ -210,26 +213,27 @@ 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:
 
-    has Task @!dependencies;
-    has $.ready = not @!dependencies;
+=for code :skip-test
+has Task @!dependencies;
+has $.ready = not @!dependencies;
 
 =head1 Static fields?
 
 Perl 6 has no B<static> keyword. Nevertheless, any class may declare anything
 that a module can, so making a scoped variable sounds like good idea.
 
-       =begin code
+    =begin code
 
-       class Singleton {
-           my Singleton $instance;
-           method new {!!!}
-           submethod instance {
-               $instance = Singleton.bless unless $instance;
-               $instance;
-           }
-       }
+    class Singleton {
+        my Singleton $instance;
+        method new {!!!}
+        submethod instance {
+            $instance = Singleton.bless unless $instance;
+            $instance;
+        }
+    }
 
-       =end code
+    =end code
 
 Class attributes defined by L<my|/syntax/my> or L<our|/syntax/our> may also be initialized when
 being declared, however we are implementing the Singleton pattern here and
@@ -238,9 +242,11 @@ predict the moment when attribute initialization will be executed, because
 it can take place during compilation, runtime or both, especially when
 importing the class using the L<use|/syntax/use> keyword.
 
+    =begin code :skip-test
     class HaveStaticAttr {
           my Foo $.foo = some_complicated_subroutine;
     }
+    =end code
 
 Class attributes may also be declared with a secondary sigil – in a similar
 manner to object attributes – that will generate read-only accessors if the
@@ -256,9 +262,11 @@ 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
     method add-dependency(Task $dependency) {
         push @!dependencies, $dependency;
     }
+    =end code
 
 X<|invocant>
 
@@ -274,13 +282,15 @@ attribute.
 
 The C<perform> method contains the main logic of the dependency handler:
 
+    =begin code :skip-test
     method perform() {
         unless $!done {
             .perform() for @!dependencies;
             &!callback();
             $!done = True;
         }
     }
+    =end code
 
 It takes no parameters, working instead with the object's attributes. First,
 it checks if the task has already completed by checking the C<$!done>
@@ -377,7 +387,8 @@ 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>:
 
-    submethod BUILD(:&!callback, :@!dependencies) { }
+=for code :skip-test
+submethod BUILD(:&!callback, :@!dependencies) { }
 
 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
@@ -389,6 +400,7 @@ more information.
 The C<BUILD> method is responsible for initializing all attributes and must also
 handle default values:
 
+    =begin code :skip-test
     has &!callback;
     has @!dependencies;
     has Bool ($.done, $.ready);
@@ -398,6 +410,7 @@ handle default values:
             :$!done = False,
             :$!ready = not @!dependencies
         ) { }
+    =end code
 
 See L<Object Construction|/language/objects#Object_Construction> for more
 options to influence object construction and attribute initialization.
@@ -408,7 +421,8 @@ After creating a class, you can create instances of the class.  Declaring a
 custom constructor provides a simple way of declaring tasks along with their
 dependencies. To create a single task with no dependencies, write:
 
-    my $eat = Task.new({ say 'eating dinner. NOM!' });
+=for code :skip-test
+my $eat = Task.new({ say 'eating dinner. NOM!' });
 
 An earlier section explained that declaring the class C<Task> installed a
 type object in the namespace.  This type object is a kind of "empty
@@ -419,6 +433,7 @@ modifying or accessing an existing object.
 
 Unfortunately, dinner never magically happens.  It has dependent tasks:
 
+    =begin code :skip-test
     my $eat =
         Task.new({ say 'eating dinner. NOM!' },
             Task.new({ say 'making dinner' },
@@ -429,18 +444,21 @@ Unfortunately, dinner never magically happens.  It has dependent tasks:
                 Task.new({ say 'cleaning kitchen' })
             )
         );
+    =end code
 
 Notice how the custom constructor and sensible use of whitespace makes task dependencies clear.
 
 Finally, the C<perform> method call recursively calls the C<perform> method
 on the various other dependencies in order, giving the output:
 
+    =begin code :skip-test
     making some money
     going to the store
     buying food
     cleaning kitchen
     making dinner
     eating dinner. NOM!
+    =end code
 
 =head1 Inheritance
 
@@ -477,7 +495,7 @@ other means, such as attribute accessors.
 Now, any object of type Programmer can make use of the methods and accessors
 defined in the Employee class as though they were from the Programmer class.
 
-    =begin code
+    =begin code :skip-test
     my $programmer = Programmer.new(
         salary => 100_000,
         known_languages => <Perl5 Perl6 Erlang C++>,
@@ -494,7 +512,7 @@ Of course, classes can override methods and attributes defined by parent
 classes by defining their own.  The example below demonstrates the C<Baker>
 class overriding the C<Cook>'s C<cook> method.
 
-    =begin code
+    =begin code :skip-test
     class Cook is Employee {
         has @.utensils  is rw;
         has @.cookbooks is rw;
@@ -545,7 +563,7 @@ algorithm to linearize multiple inheritance hierarchies, which is a
 significant improvement over Perl 5's default approach
 (depth-first search) to handling multiple inheritance.
 
-    =begin code
+    =begin code :skip-test
     class GeekCook is Programmer is Cook {
         method new( *%params ) {
             push( %params<cookbooks>, "Cooking for Geeks" );
@@ -580,6 +598,7 @@ Classes to be inherited from can be listed in the class declaration body by
 prefixing the C<is> trait with C<also>. This also works for the role
 composition trait C<does>.
 
+    =begin code :skip-test
     class GeekCook {
         also is Programmer;
         also is Cook;
@@ -589,6 +608,7 @@ composition trait C<does>.
     role A {};
     role B {};
     class C { also does A; also does B }
+    =end code
 
 =head1 Introspection
 
@@ -599,21 +619,25 @@ a controlling object) for some properties, such as its type.
 Given an object C<$o> and the class definitions from the previous sections,
 we can ask it a few questions:
 
+    =begin code :skip-test
     if $o ~~ Employee { say "It's an employee" };
     if $o ~~ GeekCook { say "It's a geeky cook" };
     say $o.WHAT;
     say $o.perl;
     say $o.^methods(:local)».name.join(', ');
     say $o.^name;
+    =end code
 
 The output can look like this:
 
+    =begin code :skip-test
     It's an employee
     (Programmer)
     Programmer.new(known_languages => ["Perl", "Python", "Pascal"],
             favorite_editor => "gvim", salary => "too small")
     code_to_solve, known_languages, favorite_editor
     Programmer
+    =end code
 
 The first two tests each smart-match against a class name. If the object is
 of that class, or of an inheriting class, it returns true. So the object in
@@ -640,8 +664,9 @@ it is actually a method call on its I<meta class>, which is a class managing
 the properties of the C<Programmer> class – or any other class you are
 interested in. This meta class enables other ways of introspection too:
 
-    say $o.^attributes.join(', ');
-    say $o.^parents.map({ $_.^name }).join(', ');
+=for code :skip-test
+say $o.^attributes.join(', ');
+say $o.^parents.map({ $_.^name }).join(', ');
 
 Finally C<$o.^name> calls the C<name> method on the meta object, which
 unsurprisingly returns the class name.