Merge branch 'master' into course

.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: test
+on:
+  push:
+    branches: [ master ]
+    paths:
+      - 'doc/**'
+  pull_request:
+    branches: [ master ]
+    paths:
+      - 'doc/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Run tests
+        run: ./util/github-action-test.sh t
+        env:
+          TEST_IMAGE: docker.io/jjmerelo/perl6-doccer:latest

.gitignore

@@ -1,5 +1,4 @@
 *.swp
-index.data
 *~
 html/*.html
 html/css/app.css
@@ -14,7 +13,7 @@ html/images/type-graph*
 html/js/search.js
 html/js/app.js
 .precomp
-precompiled
+.pod-precomp
 assets/assetpack.db
 assets/cache
 .sass-cache/
@@ -35,3 +34,4 @@ package-lock.json
 .idea
 *.iml
 .cache-doc
+precompiled/

CONTRIBUTING.md

@@ -93,9 +93,9 @@ questions come up in the process feel free to ask in
 [#raku IRC channel](https://raku.org/community/irc).
 
 If the documentation for a type does not exist, create the skeleton of the doc
-with the helper tool `util/new-type.p6`. Say you want to create `MyFunnyRole`:
+with the helper tool `util/new-type.raku`. Say you want to create `MyFunnyRole`:
 
-    $ perl6 util/new-type.p6 --kind=role MyFunnyRole
+    $ raku util/new-type.raku --kind=role MyFunnyRole
 
 Fill the documentation file `doc/Type/MyFunnyRole.pod6` like this:
 
@@ -163,7 +163,7 @@ See [Writing and Testing Examples](writing-docs/EXAMPLES.md)
 ## Testing method completeness
 
 To get a list of methods that are found via introspection but not found in any
-Pod6 file under `doc/Type/`, use `util/list-missing-methods.p6`. It takes a
+Pod6 file under `doc/Type/`, use `util/list-missing-methods.raku`. It takes a
 directory or filepath as argument and limits the listing to the given file or
 any Pod6 files found. All methods listed in `util/ignored-methods.txt` are
 ignored.

CREDITS

@@ -299,6 +299,10 @@ E: sgeoster@gmail.com
 N: ShimmerFairy
 E: rnddim@gmail.com
 
+N: Sizhe Zhao
+E: prc.zhao@outlook.com
+U: Prince213
+
 N: skids
 E: bri@abrij.org
 

META6.json

@@ -1,6 +1,6 @@
 {
   "name": "p6doc",
-  "description": "Raku documentation (tools and docs)",
+  "description": "Raku™ documentation (tools and docs)",
   "version": "1.006d",
   "perl": "6.*",
   "authors": [
@@ -10,16 +10,14 @@
   "test-depends": [
     "File::Temp",
     "Test::META",
-    "Perl6::TypeGraph"
+    "Doc::TypeGraph",
+    "Pod::To::HTML"
   ],
   "build-depends": [
-    "File::Find:ver<0.1.1+>"
+    "File::Find:ver<0.1.1+>",
+    "Pod::To::BigPage"
   ],
-  "provides": {
-    "Pod::Cache": "lib/Pod/Cache.pm6",
-    "Pod::Convenience": "lib/Pod/Convenience.pm6",
-    "Test-Files": "lib/Test-Files.pm6"
-  },
+  "provides": {},
   "support": {
     "source": "git://github.com/Raku/doc.git"
   },

Makefile

@@ -69,7 +69,7 @@ xtest:
 
 # Content tests
 ctest:
-	prove --exec raku -r t/07-tabs.t xt/perl-nbsp.t  xt/trailing-whitespace.t
+	prove --exec raku -r t/05-tabs.t xt/perl-nbsp.t  xt/trailing-whitespace.t
 
 start: run
 

README.md

@@ -1,17 +1,15 @@
-# Official Documentation of Raku
+# Official Documentation of Raku™
 
-[![Build Status](https://travis-ci.org/Raku/doc.svg?branch=master)](https://travis-ci.org/Raku/doc) [![artistic](https://img.shields.io/badge/license-Artistic%202.0-blue.svg?style=flat)](https://opensource.org/licenses/Artistic-2.0) [![Run Status](https://api.shippable.com/projects/591e99923f2f790700098a30/badge?branch=master)](https://app.shippable.com/github/Raku/doc) [![CircleCI](https://circleci.com/gh/Raku/doc.svg?style=shield)](https://circleci.com/gh/Raku/doc/tree/master)
+[![artistic](https://img.shields.io/badge/license-Artistic%202.0-blue.svg?style=flat)](https://opensource.org/licenses/Artistic-2.0)
+[![CircleCI](https://circleci.com/gh/Raku/doc/tree/master.svg?style=svg)](https://circleci.com/gh/Raku/doc/tree/master)
+[![test](https://github.com/Raku/doc/actions/workflows/test.yml/badge.svg)](https://github.com/Raku/doc/actions/workflows/test.yml)
 
 An HTML version of this documentation can be found
 at [https://docs.raku.org/](https://docs.raku.org/) and also
 at [`rakudocs.github.io`](https://rakudocs.github.io) (which is
 actually updated more frequently).
 This is currently the recommended way to consume the documentation.
 
-This documentation is updated frequently to a GitHub mirror
-https://rakudocs.github.io but that might be out of sync with the
-official one.
-
 ## Docker container
 
 This documentation is also published as
@@ -27,11 +25,11 @@ or
     docker run --rm -it -p 31415:3000 jjmerelo/perl6-doc
 
 in case you want it published somewhere else. You can direct your
-browser to http://localhost:3000 (or 31415, as the case may be).
+browser to `http://localhost:3000` (or 31415, as the case may be).
 
 ## README in other languages
 
-* [中文（Chinese）](resources/i18n/zh/README.zh.md)
+* [README in Chinese](resources/i18n/zh/README.zh.md)
 * [README in Dutch](resources/i18n/nl/README.nl.md)
 * [README in French](resources/i18n/fr/README.fr.md)
 * [README in German](resources/i18n/de/README.de.md)
@@ -42,32 +40,32 @@ browser to http://localhost:3000 (or 31415, as the case may be).
 
 ## Install rakudoc
 
-Please see https://github.com/raku/rakudoc for the
-command line tool for viewing the documentation
+Please see https://github.com/Raku/rakudoc for the
+command line tool for viewing the documentation.
 
 ## Building the HTML documentation
 
 Note: If you just want a copy of the build HTML site and don't want to deal
-with the build yourself, you can clone it from here: https://github.com/rakudocs/rakudocs.github.io
+with the build yourself, you can clone it from here: https://github.com/rakudocs/rakudocs.github.io.
 
 The documentation can be rendered to static HTML pages and/or served in a local
 web site. This process involves creating a cache of precompiled
 documents, so that generation after the first time is sped up.
 
 These are the prerequisites you need to install to generate documentation.
 
-* perl 5.20 or later
+* perl 5.20 or later.
 * node 10 or later.
 * graphviz.
 * [Documentable](https://github.com/Raku/Documentable).
 
-Please follow these instructions (in Ubuntu) to install them
+Please follow these instructions (in Ubuntu) to install them:
 
     sudo apt install perl graphviz # perl not installed by default in 18.04
     curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
     sudo apt-get install -y nodejs
     cpanm --installdeps .
-    zef install Documentable
+    zef install --deps-only . ; # from inside this checkout
 
 > You can install perl and node any way you want, including version managers, as
 > long as they're available to run from the command line.
@@ -104,8 +102,8 @@ examples) are not (yet) available in these formats.
 
 These are the prerequisites you need to install:
 
-* Pod::To::BigPage 0.5.2 or later
-* Pandoc (EPUB only)
+* Pod::To::BigPage 0.5.2 or later.
+* Pandoc (EPUB only).
 
 You can follow these instructions to install them on Ubuntu or Debian:
 
@@ -167,7 +165,7 @@ explains briefly how to get started contributing documentation.
 
 ## Some notes:
 
-**Q:** Why aren't you embedding the docs in the CORE sources?<br>
+**Q:** Why aren't you embedding the docs in the CORE sources?<br />
 **A:** Several reasons:
 
   1. This documentation is intended to be universal with
@@ -179,7 +177,7 @@ explains briefly how to get started contributing documentation.
   3. A separate repo in the Raku Github account invites
      more potential contributors and editors.
 
-**Q:** Should I include methods from superclasses or roles?<br>
+**Q:** Should I include methods from superclasses or roles?<br />
 **A:** No. The HTML version already includes methods from superclasses and
        roles.
 
@@ -219,6 +217,6 @@ 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/Raku/doc/commit/1f7cc4efa0da38b5a9bf544c9b13cc335f87f7f6))
-* Table sorter plugin from https://github.com/christianbach/tablesorter ;
+* Examples from Stack Overflow; [MIT License](http://creativecommons.org/licenses/MIT) ([ref #1](http://stackoverflow.com/a/43669837/215487) for [1f7cc4e](https://github.com/Raku/doc/commit/1f7cc4efa0da38b5a9bf544c9b13cc335f87f7f6))
+* Table sorter plugin from https://github.com/christianbach/tablesorter;
   [MIT License](http://creativecommons.org/licenses/MIT)

assets/documentable.json

@@ -1,7 +1,7 @@
 {
-  "title-page": "Raku Documentation",
+  "title-page": "Raku™ Documentation",
   "pod-root-path": "https://github.com/Raku/doc/blob/master/doc",
-  "irc-link": "https://webchat.freenode.net/?channels=#raku",
+  "irc-link": "https://web.libera.chat/?channel=#raku",
   "kinds": [
     {
       "kind": "language",

assets/js/main.js

@@ -108,7 +108,7 @@ function setup_debug_mode(){
                 console.info("checking for dead links");
 
                 function report_broken_link(url) {
-                    $('html').find('#search').after('<div style="text-align: center;">Broken link: ' + url + ' found. Please report at <a href="https://webchat.freenode.net/?channels=#raku">irc.freenode.net#raku</a></div>');
+                    $('html').find('#search').after('<div style="text-align: center;">Broken link: ' + url + ' found. Please report at <a href="https://web.libera.chat/?channel=#raku">irc.libera.chat#raku</a></div>');
                 }
 
                 var seen_link = [];

doc/HomePage.pod6

@@ -1,11 +1,8 @@
 =begin Html
 <img style="float: right; margin: 0 0 1em 1em; width:261px" src="/images/Camelia.svg" alt="" id="home_logo"/>
-Welcome to the official documentation of the <a href="https://raku.org">Raku</a>
-programming language!
-Besides online browsing and searching, you can also
-<a href="/raku.html">view everything in one file</a> or
-<a href="https://github.com/Raku/doc">contribute</a>
-by reporting issues or sending patches.
+Welcome to the official documentation of the <a href="https://raku.org">Raku™</a>
+programming language! Browse the sections below or use the search in the top
+navigation.
 
 <hr/>
 
@@ -47,6 +44,7 @@ by reporting issues or sending patches.
 <dd>
     Information about the Raku development community, email lists, IRC and IRC bots, and blogs
 </dd>
+</dl>
 <hr/>
 
 

doc/Language/101-basics.pod6

@@ -1,6 +1,6 @@
 =begin pod :kind("Language") :subkind("Language") :category("beginning")
 
-=TITLE  Raku by example 101
+=TITLE  Raku™ by example 101
 
 =SUBTITLE A basic introductory example of a Raku program
 
@@ -344,8 +344,8 @@ tournament.
 When two array items have the same value, C<sort> leaves them in the same order
 as it found them. Computer scientists call this a I<stable sort>. The program
 takes advantage of this property of Raku's C<sort> to achieve the goal by
-sorting twice: first by the number of sets won (the primary criterion), then
-by the number of matches won (the secondary criterion).
+sorting twice: first by the number of sets won (the secondary criterion), then
+by the number of matches won (the primary criterion).
 
 After the first sorting step, the names are in the order C<Beth Charlie Dave
 Ana>. After the second sorting step, it's still the same, because no one has
@@ -428,7 +428,7 @@ my @people = <Luke Matthew Mark>;
 say "The synoptics are: {@people}";
 # OUTPUT: «The synoptics are: Luke Matthew Mark␤»
 
-say "{%sets}␤";
+say "{%sets}";
 # OUTPUT (From the table tennis tournament):
 
 # Charlie 4
@@ -439,7 +439,7 @@ say "{%sets}␤";
 
 When array and hash variables appear directly in a double-quoted string (and
 not inside curly braces), they are only interpolated if their name is
-followed by a postcircumfix E<mdash> a bracketing pair that follows a
+followed by a postcircumfix operator E<mdash> a bracketing pair that follows a
 statement. It's also ok to have a method call between the variable name and
 the postcircumfix.
 
@@ -466,12 +466,13 @@ say "we have @flavors.sort.join(', ')";
 B<1.> The input format of the example program is redundant: the first line
 containing the name of all players is not necessary, because you can find out
 which players participated in the tournament by looking at their names in the
-subsequent rows.
+subsequent rows, so in principle we could safely remove it.
 
 How can you make the program run if you do not use the C<@names> variable?
 Hint: C<%hash.keys> returns a list of all keys stored in C<%hash>.
 
-B<Answer:> Remove the line C<my @names = $file.get.words;>, and change:
+B<Answer:> After removing the first line in C<scores.txt>, remove the line C<my
+@names = $file.get.words;> (which would read it), and change:
 
 =begin code :preamble<my @names;my %sets;my %matches>
 my @sorted = @names.sort({ %sets{$_} }).sort({ %matches{$_} }).reverse;