Merge branch 'master' into supplied

Conflicts:
	htmlify.p6

Author: Mouq

.gitignore

@@ -6,6 +6,6 @@ html/routine/
 html/type/
 html/op/
 html/language/
-html/misc/
+html/syntax/
 html/images/type-graph*
 html/js/search.js

bin/p6doc

@@ -47,7 +47,7 @@ sub locate-module(Str $modulename) {
 }
 
 sub show-docs(Str $path, :$section) {
-   my $pager = %*ENV<PAGER> // ($*OS eq 'MSWin32' ?? 'more' !! 'less');
+   my $pager = %*ENV<PAGER> // ($*OS eq 'mswin32' ?? 'more' !! 'less');
    if not open($path).lines.grep( /^'=' | '#|' | '#='/ )  {
       say "No Pod found in $path";
       return;

html/css/style.css

@@ -43,7 +43,7 @@ pre a:hover, pre a:link:hover {
     color: inherit;
 }
 
-img {
+img, svg {
     max-width: 100%;
 }
 

htmlify.p6

@@ -120,18 +120,19 @@ sub svg-for-file($file) {
     $str;
 }
 
-# --sparse=5: 
+# --sparse=5: only process 1/5th of the files
+# mostly useful for performance optimizations, profiling etc.
 sub MAIN(
     Bool :$debug,
     Bool :$typegraph = False,
-    Int :$sparse
-        #=[ only process 1/Nth of the files
-            mostly useful for performance optimizations, profiling etc. ]
+    Int  :$sparse,
+    Bool :$disambiguation = True,
+    Bool :$search-file = True,
 ) {
     $*DEBUG = $debug;
 
     say 'Creating html/ subdirectories ...';
-    for '', <type language routine images misc> {
+    for '', <type language routine images syntax> {
         mkdir "html/$_" unless "html/$_".IO ~~ :e;
     }
 
@@ -148,24 +149,23 @@ sub MAIN(
         })
     }
 
-    tap-disambiguation-files;
-    tap-search-file;
+    tap-disambiguation-files if $disambiguation;
+    tap-search-file          if $search-file;
     tap-index-files;
 
-    for <routine misc> -> $kind {
+    for <routine syntax> -> $kind {
         tap-kind $kind;
     }
 
-
     process-pod-dir 'Type', :sorted-by{ %h{.key} // -1 }, :$sparse;
     #process-pod-dir 'Language', :$sparse;
 
     say 'Composing doc registry ...';
     $DR.compose;
 
     say 'Processing complete.';
-    if $sparse {
-        say "This is a sparse run. DO NOT SYNC WITH doc.perl6.org!";
+    if $sparse || !$search-file || !$disambiguation {
+        say "This is a sparse or incomplete run. DO NOT SYNC WITH doc.perl6.org!";
     }
 }
 
@@ -229,6 +229,7 @@ sub process-type-source(:$pod, :$podname, :$pod-is-complete) {
         :kind<type>,
         :subkinds($type ?? $type.packagetype !! 'class'),
         :categories($type ?? $type.categories !! Nil),
+        :$summary,
         :$pod,
         :$pod-is-complete,
         :name($podname),
@@ -368,17 +369,24 @@ sub find-definitions (:$pod, :$origin, :$min-level = -1) {
                             :categories($subkinds),
                 }
                 when 'class'|'role' {
+                    my $summary = '';
+                    if @c[$i+1] ~~ {$_ ~~ Pod::Block::Named and .name eq "SUBTITLE"} {
+                        $summary = @c[$i+1].contents[0].contents[0];
+                    } else {
+                        note "$name does not have an =SUBTITLE";
+                    }
                     %attr = :kind<type>,
                             :categories($tg.types{$name}.?categories//''),
+                            :$summary,
                 }
                 when 'variable'|'sigil'|'twigil'|'declarator'|'quote' {
                     # TODO: More types of syntactic features
-                    %attr = :kind<misc>,
+                    %attr = :kind<syntax>,
                             :categories($subkinds),
                 }
                 when $unambiguous {
                     # Index anything from an X<>
-                    %attr = :kind<misc>,
+                    %attr = :kind<syntax>,
                             :categories($subkinds),
                 }
                 default {
@@ -417,7 +425,7 @@ sub find-definitions (:$pod, :$origin, :$min-level = -1) {
                 # Determine proper subkinds
                 my Str @subkinds = first-code-block($chunk)\
                     .match(:g, /:s ^ 'multi'? (sub|method)»/)\
-                    .>>[0]>>.Str.uniq;
+                    .>>[0]>>.Str.unique;
 
                 note "The subkinds of routine $created.name() in $origin.name() cannot be determined."
                     unless @subkinds;
@@ -441,8 +449,8 @@ sub find-definitions (:$pod, :$origin, :$min-level = -1) {
 
 sub write-type-graph-images(:$force) {
     unless $force {
-        my $dest = 'html/images/type-graph-Any.svg'.path;
-        if $dest.e && $dest.modified >= 'type-graph.txt'.path.modified {
+        my $dest = 'html/images/type-graph-Any.svg'.IO;
+        if $dest.e && $dest.modified >= 'type-graph.txt'.IO.modified {
             say "Not writing type graph images, it seems to be up-to-date";
             say "To force writing of type graph images, supply the --typegraph";
             say "option at the command line, or delete";
@@ -519,7 +527,7 @@ sub tap-search-file () {
     ( $DR.lookup('language', :by<kind>),
       $DR.lookup('type',     :by<kind>),
       $DR.lookup('routine',  :by<kind>),
-      $DR.lookup('misc',    :by<kind>),
+      $DR.lookup('syntax',    :by<kind>),
     ).reduce({merge $^a: $^b}).map({
         .unique(:as{.name}).map({
             .subkinds.map(*.wordcase).map: -> $subkind {
@@ -690,6 +698,8 @@ sub footer-html() {
             incomplete. Your contribution is appreciated.
         </p>
         <p>
+            This documentation is provided under the terms of the Artistic
+            License 2.0.
             The Camelia image is copyright 2009 by Larry Wall.
         </p>
     ];

lib/HomePage.pod

@@ -1,5 +1,5 @@
 =begin Html
-<img style="float: right; margin: 0 0 1em 1em" src="/images/camelia.png"/>
+<img style="float: right; margin: 0 0 1em 1em" src="/images/camelia.png" alt =""/>
 Welcome to the official documentation of the <a href="http://perl6.org">Perl 6</a>
 programming language!
 Besides online browsing and searching, you can also
@@ -34,10 +34,15 @@ Z<<
 
 <hr>
 
+
+<p>The Perl 6 homepage offers <a href="http://perl6.org/documentation/">a
+comprehensive list of Perl 6 documentation</a>, including tutorials, HowTos
+and <a href="http://faq.perl6.org/">FAQs (Frequently Asked Questions)</a>.</p>
+
 <p>
-You may also be interested in the Perl 6 <a href="http://perlcabal.org/syn">synopses</a>,
-which are more complete than this documentation, but targeted toward compiler writers
-rather than users of the language.
+You may also be interested in the Perl 6 <a href="http://design.perl6.org">design documents</a>,
+which are in some places more complete than this documentation, but targeted
+toward compiler writers rather than users of the language.
 Documentation for the different but related <a href="http://perl.org/">Perl 5</a> language
 can be found <a href="http://perldoc.perl.org/">here</a>.
 </p>

lib/Language/grammars.pod

@@ -55,7 +55,7 @@ back up and try again if it fails to match something. This will usually do what
     =end code
 
 The only difference between the C<token> and C<rule> declarators is that the
-C<rule> declarator causes L<C<:sigspace>|/language/regexes#sigspace> to go into
+C<rule> declarator causes L<C<:sigspace>|/language/regexes#Sigspace> to go into
 effect for the Regex:
 
     =begin code :allow<B>
@@ -67,6 +67,8 @@ effect for the Regex:
 
 =head1 X<Creating Grammars|class,Grammar;declarator,grammar>
 
+=SUBTITLE Group of named regexes that form a formal grammar
+
     class Grammar is Cursor { }
 
 C<Grammar> is the superclass that classes automatically get when they

lib/Language/mop.pod

@@ -4,7 +4,44 @@
 
 =SUBTITLE Introspection and the Perl 6 Object System
 
-TODO
+Perl 6 is built on a meta object layer. That means that there are objects (the
+I<meta objects>) that control how various object-oriented constructs (such as
+classes, roles, methods, attributes, enums, ...) behave.
+
+To get a feeling for the meta object for C<class>, here is the same example
+twice: once as normal declarations in Perl 6, and once expressed through the
+meta model:
+
+    class A {
+        method x() { say 42 }
+    }
+
+    A.x();
+
+corresponds to:
+
+    constant A := Metamodel::ClassHOW.new_type( name => 'A' );  # class A {
+    A.^add_method('x', my method x(A:) { say 42 });             # method x() .. .
+    A.^compose;                                                 # }
+
+    A.x();
+
+(except that the declarative form runs at comple time, and the latter form
+does not).
+
+The meta object behind
+an object can be obtained with C<$obj.HOW>, where HOW stands for Higher Order
+Workings (or, I<HOW the *%@$ does this work?>).
+
+Here the calls with C<.^> are calls to the meta object, so C<A.^compose> is a
+shortcut for C<A.HOW.compose(A)>. The invocant is passed along in the
+parameter list as well, to make it possible to support prototype-style type
+systems, where there is just one meta object (and not one meta object per
+type, as standard Perl 6 does it).
+
+As the example above demonstrates, all object oriented features are available
+to the user, not just to the compiler. In fact the compiler also just emits
+call to the meta objects.
 
 =head1 Metamethods
 
@@ -24,17 +61,22 @@ quotes around the method name to call it indirectly:
 
 The type object of the type.
 
+For example C<42.WHAT> returns the C<Int> type object.
+
 =head2 X<WHICH|syntax,WHICH>
 
-The object's identity value.
+The object's identity value. This can be used for hashing and identity
+comparison, and is how the C<===> infix operator is implemented.
 
 =head2 X<WHO|syntax,WHO>
 
 The package supporting the object.
 
 =head2 X<WHERE|syntax,WHERE>
 
-The memory address of the object.
+The memory address of the object. Note that this is not stable in
+implementations with moving/compacting garbage collectors. Use C<WHICH> for a
+stable identity indicator.
 
 =head2 X<HOW|syntax,HOW>
 
@@ -47,6 +89,7 @@ The attached Pod value.
 =head2 X<DEFINITE|syntax,DEFINITE>
 
 The object has a valid concrete representation.
+Returns C<True> for instances and C<False> for type objects.
 
 =head2 X<VAR|syntax,VAR>
 

lib/Language/objects.pod

@@ -622,6 +622,8 @@ To get rid of using the same object twice, there is a shortcut:
 
 =head2 class Perl6::Metamodel::ClassHOW
 
+=SUBTITLE Meta object for a class
+
 Introspection is the process of getting information about an object or class
 at runtime. In Perl 6, all introspection goes through the meta object. The
 standard C<ClassHOW> for class-based objects offers these facilities:

lib/Language/operators.pod

@@ -218,6 +218,21 @@ The operator for calling one method, C<$invocant.method>.
 
 Technically this is not an operator, but syntax special-cased in the compiler.
 
+=head2 postfix C«.=»
+
+A mutating method call. C<$invocant.=method> desugars to
+C<$invocant = $invocant.method>, similar to L<C<op=>>.
+
+Technically this is not an operator, but syntax special-cased in the compiler.
+
+=head2 postfix C«.^»
+
+A meta-method call. C<$invocant.^method> calls C<method> on C<$invocant>'s
+metaclass. It desugars to C<$invocant.HOW.method($invocant, ...)>. See L<C<HOW>>
+for more information.
+
+Technically this is not an operator, but syntax special-cased in the compiler.
+
 =head2 postfix C«.?»
 
 Potential method calls. C<$invocant.?method> calls method C<method> on
@@ -240,7 +255,58 @@ L<Parcel> is returned.
 
 Technically this is not an operator, but syntax special-cased in the compiler.
 
-# TODO: .= .^ .:: .() .[] .{} .<>
+=head2 X«postfix C<.postfix>
+    |postfix,.postfix;postcircumfix,.( );postcircumfix,.[ ];postcircumfix,.{ };postcircumfix,.< >»
+
+In most cases, a dot may be placed before a postfix or postcircumfix:
+
+    @a[1, 2, 3];
+    @a.[1, 2, 3]; # Same
+
+This can be useful for visual clarity or brevity. For example, if an object's
+attribute is a function, putting a pair of paretheses after the attribute name
+will become part of the method call. So either two pairs of paretheses must be
+used, or a dot has to come before the parentheses to seperate it from the method
+call.
+
+    class Operation {
+        has $.symbol;
+        has &.function;
+    }
+    my $addition = Operation.new(:symbol<+>, :function{ $^a + $^b });
+    say $addition.function()(1, 2); # 3
+    # OR
+    say $addition.function.(1,2); # 3
+
+If the postfix is an identifier, however, it will be interpreted as a normal
+method call.
+
+    1.i # No such method 'i' for invocant of type 'Int'
+
+Technically this is not an operator, but syntax special-cased in the compiler.
+
+=head2 postfix C«.:<prefix>»
+
+A prefix can be called like a method using colonpair notation. For example:
+
+    my $a = 1;
+    say ++$a;     # 2
+    say $a.:<++>; # 3
+
+Technically this is not an operator, but syntax special-cased in the compiler.
+
+=head2 postfix C«.::»
+
+A class-qualified method call, used to call a method as defined in a parent
+class or role, even after it has been redefined in the child class.
+
+    class Bar {
+        method baz { 42 }
+    }
+    class Foo is Bar {
+        method baz { "nope" }
+    }
+    say Foo.Bar::baz; # 42
 
 =head1 Autoincrement Precedence