Merge branch 'extra-twigils' of github.com:perl6/doc into extra-twigils

Author: JJ

.travis.yml

@@ -10,6 +10,8 @@ addons:
       - g++-4.8
       - ruby-sass
 
+fast_finish: true
+
 branches:
   except:
     - gh-pages
@@ -35,11 +37,10 @@ install:
   - export PATH="$PATH:/$HOME/.rakudobrew/moar-nom/install/share/perl6/site/bin"
   - travis_retry zef --/tap-harness --force --/test install LWP::Simple
   - travis_retry zef --/tap-harness --depsonly install .
-  - travis_retry zef --/tap-harness install Pod::To::HTML
 
 script:
   - make test
-  - export CXX=g++-4.8
+  - export CXX=$(command -v g++-4.8 >/dev/null 2>&1; if [ $? -eq 1 ]; then printf "g++"; else printf "g++-4.8"; fi)
   - $CXX --version
   - make html
 matrix:

CONTRIBUTING.md

@@ -23,16 +23,13 @@ in the [#perl6 IRC channel](https://perl6.org/community/irc).
     - [Broken links](#broken-links)
     - [Heading numbering](#heading-numbering)
 - [Reporting bugs](#reporting-bugs)
-- [Website Styles](#website-styles)
 - [Building the documentation](#building-the-documentation)
     - [Dependency installation](#dependency-installation)
         - [Rakudo](#rakudo)
         - [Zef](#zef)
         - [Pod::To::HTML](#podtohtml)
         - [Mojolicious / Web Server](#mojolicious--web-server)
         - [SASS compiler](#sass-compiler)
-        - [pygmentize](#pygmentize)
-        - [Inline::Python](#inlinepython)
     - [Build and view the documentation](#build-and-view-the-documentation)
 
 ## General principles
@@ -82,11 +79,11 @@ Fill the documentation file `doc/Type/MyFunnyRole.pod6` like this:
 
     =head2 method do-it
 
-        method do-it(Int $how-often) returns Nil:D
+        method do-it(Int $how-often --> Nil:D)
 
     Method description here
 
-        MyFunnyRole.do-it(2);   # example output
+        MyFunnyRole.do-it(2);   # OUTPUT: «example output␤»
 
 
 When documenting a pair of a sub and a method which both do the same thing, the
@@ -96,6 +93,15 @@ more lines with the signatures. Other allowed words instead of `method` are
 `term`. If you wish to hide a heading from any index prefix it with the empty
 comment `Z<>`.
 
+When providing a code example result or output, use this style:
+
+    # For the result of an expression.
+    1 + 2;     # RESULT: «3»
+    # For the output.
+    say 1 + 3; # OUTPUT: «3␤»
+    # For the explanatory comment
+    do-work;   # We call do-work sub
+
 ## Running tests
 
 Any contributions should pass the `make test` target. This insures basic
@@ -174,22 +180,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
-
-* LHF    - for a beginner to work on
-* big    - a big issue, may require some research
+* search - the search component, either for items that are on the site but not searchable, or for search functionality)
 
-## Website Styles
+Contributors may also specify one of the following tags.
 
-The `html/css/style.css` file is built from `assets/sass/style.sass`. Please
-don't edit `html/css/style.css` directly, as your changes will be lost
-the next time the SASS file is processed.
+* LHF    - for a beginner to work on
+* big    - a big issue, requires research or consensus
 
-[SASS](http://sass-lang.com/) is a superset of CSS, so if you don't know SASS,
-just write in regular CSS. Run `app.pl` to automatically process SASS and copy
-the result over to `html/css/style.css`
+If you would like to contribute documentation or other bug fixes, please use
+github's Pull request feature.
 
 ## Building the documentation
 
@@ -261,55 +262,6 @@ or the [CSS::Sass Perl 5 module](https://modules.perl6.org/repo/CSS::Sass)
 The SASS files are compiled when you run `make html`, or `make sass`, or
 start the development webserver (`./app-start`).
 
-#### pygmentize
-
-This program adds syntax highlighting to the code examples.  Highlighting of
-Perl 6 code was added in version 2.0, so you need at least this version if
-you wish to produced syntax highlighted documentation on your local
-computer.
-
-If you use Debian/Jessie, you can install `pygmentize` via the
-`python-pygments` package:
-
-    $ aptitude install python-pygments
-
-On Ubuntu install the package `python-pygments`:
-
-    $ sudo apt-get install python-pygments
-
-On Fedora the package is also named `python-pygments`:
-
-    $ sudo yum install python-pygments
-
-Otherwise, you probably need to use [`pip`](https://pip.pypa.io/en/latest/)
-(the Python package installer):
-
-    $ pip install pygmentize
-
-#### Inline::Python
-
-`Inline::Python` is optional, however will speed up documentation builds
-using syntax highlighting.
-
-First, you'll need the Python Devel header files and libraries if they have not
-already been installed:
-
-On Debian, install the `python-dev` package:
-
-    aptitude install python-dev
-
-On Ubuntu, the package is also named `python-dev`:
-
-    sudo apt-get install python-dev
-
-On Fedora, install the `python-devel` package:
-
-    sudo yum install python-devel
-
-Use `zef` to install the `Inline::Python` module:
-
-    $ zef install Inline::Python
-
 ### Build and view the documentation
 
 To actually build the documentation all you now need to do is run

CREDITS

@@ -301,8 +301,8 @@ E: email@froggs.de
 N: Tokuhiro Matsuno
 E: tokuhirom@gmail.com
 
-N: u0097636@kuleuven.be
-E: claudio.ramirez@kuleuven.be
+N: Claudio Ramirez
+E: pub.claudio@gmail.com
 
 N: ugexe
 E: nlogan@gmail.com

META.info renamed to META6.json

@@ -1,9 +1,11 @@
 {
     "perl"        : "6.*",
     "name"        : "p6doc",
-    "version"     : "*",
+    "version"     : "1.001001",
     "description" : "Perl 6 documentation (tools and docs)",
-    "depends"     : [ "URI", "File::Temp", "JSON::Fast", "Pod::To::BigPage", "Pod::To::HTML" ],
+    "license"     : "Artistic-2.0",
+    "depends"     : [ "URI", "File::Temp", "JSON::Fast", "Pod::To::BigPage", "Pod::To::HTML",
+                      "OO::Monitors", "IO::String" ],
     "build-depends" : [ "File::Find" ],
     "provides"    : {
         "Perl6::Type"                   : "lib/Perl6/Type.pm",

README.md

@@ -75,7 +75,7 @@ You can then view the examples documentation by pointing your web browser at
 You will need at least [Mojolicious](https://metacpan.org/pod/Mojolicious)
 installed and you will need [nodejs](https://nodejs.org) to perform highlighting.
 
---------
+---------
 
 ## Help Wanted!
 
@@ -166,3 +166,4 @@ files indicate the copyright and license terms at the top of the file. Currently
 * [jQuery Cookie plugin](https://github.com/js-cookie/js-cookie):
   Copyright 2006, 2015 Klaus Hartl & Fagner Brack;
   [MIT License](http://creativecommons.org/licenses/MIT)
+* Examples from Stack Overflow [MIT License](http://creativecommons.org/licenses/MIT); ([ref #1](http://stackoverflow.com/a/43669837/215487) for [1f7cc4e](https://github.com/perl6/doc/commit/1f7cc4efa0da38b5a9bf544c9b13cc335f87f7f6))

app.pl

@@ -35,7 +35,7 @@
     before_dispatch => sub {
         my $c = shift;
         $c->req->url->path( $c->req->url->path =~ s/::/\$COLON\$COLON/gr )
-            if $c->req->url->path =~ m{^/type/};
+            if $c->req->url->path =~ m{^/type/} and $^O =~ m/MSWin/i;
     }
 );
 

assets/sass/_highlights.scss

@@ -72,7 +72,9 @@
   color: #900;
 }
 /* Regex/Grammars */
-
+.string.regexp.construct {
+  color: #0078FF;
+}
 /* `token`, `regex` */
 .storage.type.declare.regexp.named {
   color: #393276;

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

@@ -1,4 +1,4 @@
-=begin pod
+=begin pod :tag<convert>
 
 =TITLE 5to6-nutshell
 
@@ -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