raku / book

Using Raku – an unfinished book about Raku

NOTE:

This repository is retained only for archival purposes. The project is currently considered dead and only really useful for updating the documentation on https://docs.raku.org.

If you are looking for up-to-date Raku books, please check https://perl6book.com/ for an overview.

Reference documentation can be found at https://doc.raku.org/.

---

We are writing a book about Raku.

It will be some kind of example-driven introduction to Raku, and at the same time showing off the reasons why we love that language.

We plan to have monthly releases, see docs/release-guide.pod

"We" are Carl Mäsak, Jonathan Worthington, Patrick Michaud, Moritz Lenz, Jonathan Scott Duff (Scott) and anybody who's willing to work on it. If you're not on that list yet, you're still very welcome to join us.

You can find us on #perl6book on irc.freenode.net. Logs of the IRC discussions: http://irclog.perlgeek.de/perl6book/ (If you do not have an IRC client, you can use a web-based client at http://webchat.freenode.net/?randomnick=1&channels=perl6book&prompt=1 )

To build the PDF version of this book, you need to have the following software installed (for HTML output only, the first section of the prereqs is enough; 'make html' will be your friend):

• GNU make
• perl 5.10
• the Perl modules: Pod::PseudoPod::LaTeX version 1.101050 or newer Template version 2.22 or newer
• inkscape (for svg -> pdf conversion)
• A number of LaTeX packages (see lib/*.sty). Ubuntu 10.04 supplies most of what is needed with its texlive-latex-base, texlive-latex-extra, texlive-xetex, texlive-fonts-extra, texlive-latex-recommended and texlive-font-utils packages.
• Adobe's fonts and B&H Luxi Sans. To get those, install ttf-xfree86-nonfree (and uninstall t1-xfree86-nonfree) and Acrobat Reader then copy *.otf from /opt/Adobe/Reader9/Resource/Font/ to ~/.fonts/
• Run 'sudo fc-cache -f -v' to rebuild the cache in case the fonts are not found.

The book is produced from src/.pod chapters ultimately rendered into dist/.pdf using bin/* and lib/* files.

Just type 'make' on your command line, and the book should be built in dist/UsingRaku.a4.pdf, with an A4 paper size; to get U.S. letter size, type 'make PAPER=letter'. To get any PAPER width and height type 'make PAPER=6.125in,9.25in'; accepted length units are pt, in, cm and mm.

PDF versions of this book can be found at http://puffin.ch/perl/6/ and http://github.com/raku/book/downloads

All material in this repository is licensed under a CC-by-nc-sa license: http://creativecommons.org/licenses/by-nc-sa/2.5/ (attribution, noncommercial, share-alike), unless explicitly stated otherwise.

(Maybe we'll open up towards removing the noncommercial part at some point).

book's Issues

Using Perl6: Section 5.4: Traits used without prior explanation

This section begins: "Traits can apply implicit constraints:"

However, as far as I can tell, 'traits' have not previously been discussed in this book, and no definition of traits is provided at this point.

Using Perl6: Section 5.1: Why solicit abuse?

This section includes language such as: "You can abuse this to count how often a type check occurs."

In an introductory text like this, shouldn't you leave out ways to abuse the code?

The section goes on to say: "Avoid writing code like this in anything other than example code. Relying on the side effects of type checks produces unreliable code."

Could we get a better example -- one that encourages best practices rather than hackery?

In section 5.6.1, my $baker is wrong class.

my $baker is Cook.new( # wrong class
my $baker is Baker.new( # should be

Otherwise it doesn't illustrate the point the section is trying to demonstrate. Namely, method .cook doesn't get overridden.

Strange glyphs (even by perl standards ;-) in certain sections of document

See top of page 15 in Chapter 4 "Subs and Signatures" for an example. The following code looks fine in subs-and-sigs.pod:
my $dance = '';
my %moves =
hands-over-head => sub { $dance ~= '/o\ ' },
bird-arms => sub { $dance ~= '|/o| ' },
left => sub { $dance ~= '>o ' },
right => sub { $dance ~= 'o< ' },
arms-up => sub { $dance ~= '\o/ ' };

my @awesome-dance = ;
for @awesome-dance -> $move {
%moves{$move}.();
}

...but it looks strange in the .pdf (e.g., lots of upside-down question marks and other odd-looking glyphs).

Using Perl6 Section 4.6

First, the use of all() is unexplained. Some of us are familiar with junctions from Damian's Quantum::Superpositions talk, but the docs probably shouldn't require that you have been at a Perl Conference ten years ago to make sense of it. :-) Also, if you play with the code in this section, you find that what gets returned is a junction, which really won't make sense to the uninitiated.

Also, the first paragraph refers to "ordinary slicing access", but what does that refer to? Perl5 style slices? Other than the reference to the "Zen slice", there's been no reference to slicing in this document. Is the first section of the first example supposed to be "ordinary slicing", followed by the second section which is "signature binding"? Since neither does the unpacking in the actual signature of the subroutine, I find that unclear.

Next, there is the line 10 of the first example: "my :($first, *@rest) := (|@A)". A couple of issues with this... What's that colon doing after the my (I suspect this one is a typo)? What does the := operator do? Why are we creating a capture on the right hand side of the expression?

Inheritance section needs a much better example

In chapter "Classes and Objects", the "Inheritance" section uses Emplyee/Programmer/Cook/Baker/GeekCook as example.

The problem with is that it's pretty arbitrary, there doesn't seem to be an problem it actually solves. One doesn't know what behavior to expect from the classes, since there's no use case.

Instead a problem should be stated, to which a rather natural solution involves inheritance and polymorphism.

See also: http://lists.canonical.org/pipermail/kragen-tol/2011-August/000937.html

Error about the tree-way comparison operator

In the operators chapter, it is written :

The three-way comparison operators take two operands, and return -1 if the left is smaller, 0 when both are equal, and +1 if the right operand is larger.

It should be

... if the right operand is smaller

Gather ideas about fonts

A good idea might be to ask Chromatic, who's going to publish his own book soon.

Also looking into an edition of "Modern Operating Systems", the font combination used is Linotype Aldus / Palatino, ITC FlanklinGothic

Line numbering improvements

It would be nice to actually show the correct line number when going through a code block step-by-step like in the Basics section. Probably possible with additional markup, which in this case ain't that bad

Using Perl6: When are semicolons needed to close statements?

The PDF might benefit from centralizing in one place (probably early in the document) a discussion of which statements need to terminate in semicolons, which may take semicolons, and those for which semicolons are either superfluous or wrong.

In the code sample in Section 5.1, Constraints, we have 3 multis defined: 2 with semicolons, 1 without:

1 my $counter = 0;
2
3 multi a(Int $x) { };
4 multi a($x) { }
5 multi a($x where { $counter++; True }) { };

At first I thought, "It's a typo in line 4; I should add the semicolon at the end of the statement." Only later did I realize, "Multis are like subroutines. subroutine definitions in Perl 5 don't need terminating semicolons, so it's understandable that multis in Perl 6 don't need them either."

[PATCH] fixed a non-working example: $number vs $count

From a2771dde30fff4e1b318efab92a9409c9c286eec Mon Sep 17 00:00:00 2001
From: Piotr Fusik
Date: Tue, 17 Aug 2010 20:47:13 +0200
Subject: [PATCH] fixed a non-working example: $number vs $count

---
 src/subs-n-sigs.pod |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/src/subs-n-sigs.pod b/src/subs-n-sigs.pod
index 4f49826..bcf6fe8 100644
--- a/src/subs-n-sigs.pod
+++ b/src/subs-n-sigs.pod
@@ -269,7 +269,7 @@ Likewise, you can interpolate hashes into named arguments:

 =begin programlisting

-    sub order-shrimps($number, $from) {
+    sub order-shrimps($count, $from) {
         say "I'd like $count pieces of shrimp from the $from, please";
     }

-- 
1.6.5.1.1367.gcd48

chap4, 4.6 unpacking code sample failed to work

# same thing:
sub first-is-largest(@a) {
    my :($first, *@rest) := \(|@a); 
                                            ~~~~~~~~~~This line is not working in rakudo
    return $first >= all(@rest);
}

(17:06:38) woosley: rakudo: @A = 2, 3, 4; my :($f, *$o) := (|@A); say $f.perl
(17:06:41) p6eval: rakudo 549d2a: OUTPUT«===SORRY!===␤Malformed my at line 22, near ":($f, $o) "␤»

There doesn't seem to be a working way to cross-link to sections, tables etc.

It seems that X<> and L<> should work, but an L is just rendered as foo.

A<> links do not work inside N<> footnotes.

Footnotes seem to be rather fragile. For one, links to other contents with A<...> inside a footnote don't seem to work. src/operators.pod turns A A<sec:subtypes> into sec:subtypeson page 91.

Using Perl6: Section 5.2: why encourage trickery?

This section includes language such as: "This restriction allows a clever compiler optimization ..." and "With some trickery ..."

Wouldn't this be more appropriate in an O'Reilly book "Perl 6 Hacks"? Why should an introductory-level user of Perl 6 be at all interested in compiler optimizations? Is "trickery" the main reason a person should learn Perl 6?

Oops, typo already corrected on the repo

Using Perl6: .WHAT used without explanation

In Section 5 (and 5.2) the following code appears:

multi to-json($d) {
    die "Can't serialize an object of type " ~ $d.WHAT.perl
}

I think it's great to get introduced to .WHAT early on when you're exploring Perl6 for the first time.

The text needs a paragraph / tip mentioning what .WHAT does, and maybe a few others like .perl.

Using Perl6: Section 5.3: rock-scissors-paper example not working

This content is stored as http://nopaste.snit.ch/23640.

From: "kid51" at 192.168.1.3
Summary: Rakudo rock-scissors-paper example

Running this from Using Perl6 PDF:

use v6;

enum Symbol ;

multi wins(Scissors $, Paper $) { +1 }
multi wins(Paper $, Rock $) { +1 }
multi wins(Rock $, Scissors $) { +1 }
multi wins(::T $, T $) { 0 } # type capture
multi wins( $, $) { -1 }

sub play ($a,$b) {
given wins($a,$b) {
when +1 { say "Player One wins" }
when 0 { say "Draw" }
when -1 { say "Player Two wins" }
}
}

play(Scissors, Paper);
play(Paper, Paper);
play(Rock, Paper);

... gives this output:

Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Use of uninitialized value in numeric context
Player One wins
Player One wins
Player One wins

... no line numbers for uninitialized values; wrong results; did I type the example wrong?

Chapter 3 main example hyper operator

I'm going through the book using rakudo star - jab 2011, and in chapter 3, there's the following issue:

The code in the book says:

 my $label-area-width = 1 + [max] @scores».key».chars;

The '>>' after key causes the label_area_width to be too big, so I think it should be

 my $label-area-width = 1 + [max] @scores».key.chars;

Is it right?

[TODO] explain where whitespace is needed

miso2217 complained on #perl6 that there's no good documentation about where whitespace is needed. For example we need to explain that (and why) these two things are illegal:

 if(1) {  } # function call
 if 1{ }    # parses { } as postcircumfix

PDF output doesn't include bold text in verbatim code

In verbatim block code, B<...> should create bold code. And the latex output has all the required commands for it, it just seems that the current monospace font doesn't support it (which was the reason for chosing the "bera" mono font in the first place).

So font needs to be chose that supports bold monospace.

Problems with creating index file

When running make, the following error occurs:
= UsingPerl6.a4.idx --> UsingPerl6.a4.ind =
!! Input index error (file = UsingPerl6.a4.idx, line = 88):
-- Illegal null field.
!! Input index error (file = UsingPerl6.a4.idx, line = 92):
-- Illegal null field.
!! Input index error (file = UsingPerl6.a4.idx, line = 96):
-- Illegal null field.
make[1]: *** [UsingPerl6.a4.ind] Error 1
make[1]: Leaving directory `/home/jest/miszmasz/using-perl6/build'
make: *** [pdf] Error 2

This problem can be handled with entering build/ dir and running

makeindex UsingPerl6.a4.idx
make -I ../lib -f ../lib/Makefile

but this should happen just by running make for the first time.

X<regex, blah> in POD not displaying in PDF

p97 contains the following text:

Several other common control sequences each match a single character:

However nothing is printing after the colon.

The pod source shows the following:

X<regex, \w>
X<regex, \d>
X<regex, \s>
X<regex, \t>
X<regex, \h>
X<regex, \n>
X<regex, \v>
X<regex, \W>
X<regex, \D>
X<regex, \S>
X<regex, \T>
X<regex, \H>
X<regex, \N>
X<regex, \V>

Patrick

Invalid fontname `Minion Pro

The PDF produced contains only the code examples (that is I guess only the parts in courier).

Maybe this is related: when running make I get lots of these errors:

kpathsea: Invalid fontname Myriad Pro', contains ' ' kpathsea: Invalid fontnameMinion Pro', contains ' '

I do have the Minion fonts in .fonts (copied from the adobe dir as described in README):

zby@zby:~/progs/book$ ls .fonts/
AdobePiStd.otf CourierStd-Oblique.otf MinionPro-Bold.otf MyriadPro-BoldIt.otf MyriadPro-Regular.otf
CourierStd-BoldOblique.otf CourierStd.otf MinionPro-It.otf MyriadPro-Bold.otf
CourierStd-Bold.otf MinionPro-BoldIt.otf MinionPro-Regular.otf MyriadPro-It.otf

But in the .log files there are many other errors as well.

Chapter 3 (Operators) fails to mention xx

xx - the array replication operator

texlive-xetex

Most likely should be added to the prereqs mentioned in README.

Unable to build book

... Can't attach files to issues? Here's the build failure inlined:

Script started on Fri Apr 30 19:51:18 2010
�[32;1mcoke@slurpee�[0m �[37m~/sandbox/perl6-book�[0m �[36;1m(git:master) �[0m�[35;1m$ �[0mmake
perl bin/book-to-latex src/preface.pod src/basics.pod src/operators.pod src/subs-n-sigs.pod src/multi-dispatch.pod src/classes-and-objects.pod src/regexes.pod src/grammars.pod > build/book.tex
Use of uninitialized value in concatenation (.) or string at /Users/coke/usr/lib/perl5/site_perl/5.12.0/Pod/PseudoPod/LaTeX.pm line 200.
inkscape --export-pdf=build/mmd-table.pdf -D src/mmd-table.svg
cd build && pdflatex book.tex && pdflatex book.tex
This is pdfeTeX, Version 3.141592-1.21a-2.2 (Web2C 7.5.4)
entering extended mode
(./book.tex
LaTeX2e <2003/12/01>
Babel <v3.8d> and hyphenation patterns for american, french, german, ngerman, b
ahasa, basque, bulgarian, catalan, croatian, czech, danish, dutch, esperanto, e
stonian, finnish, greek, icelandic, irish, italian, latin, magyar, norsk, polis
h, portuges, romanian, russian, serbian, slovak, slovene, spanish, swedish, tur
kish, ukrainian, nohyphenation, loaded.
(/opt/local/share/texmf-dist/tex/latex/base/report.cls
Document Class: report 2004/02/16 v1.4f Standard LaTeX document class
(/opt/local/share/texmf-dist/tex/latex/base/size11.clo))
(/opt/local/share/texmf-dist/tex/latex/graphics/graphics.sty
(/opt/local/share/texmf-dist/tex/latex/graphics/trig.sty)
(/opt/local/share/texmf-dist/tex/latex/graphics/graphics.cfg)
(/opt/local/share/texmf-dist/tex/latex/graphics/pdftex.def))
(/opt/local/share/texmf-dist/tex/latex/graphics/graphicx.sty
(/opt/local/share/texmf-dist/tex/latex/graphics/keyval.sty))
(/opt/local/share/texmf-dist/tex/latex/carlisle/colortbl.sty
(/opt/local/share/texmf-dist/tex/latex/tools/array.sty)
(/opt/local/share/texmf-dist/tex/latex/graphics/color.sty
(/opt/local/share/texmf-dist/tex/latex/graphics/color.cfg)))
(/opt/local/share/texmf-dist/tex/latex/fancyvrb/fancyvrb.sty
Style option: `fancyvrb' v2.6, with DG/SPQR fixes <1998/07/17> (tvz)
No file fancyvrb.cfg.
)

! LaTeX Error: File `bera.sty' not found.

Type X to quit or to proceed,
or enter new name. (Default extension: sty)

Enter file name:
(/opt/local/share/texmf-dist/tex/latex/base/inputenc.sty
(/opt/local/share/texmf-dist/tex/latex/base/utf8.def
(/opt/local/share/texmf-dist/tex/latex/base/t1enc.dfu)
(/opt/local/share/texmf-dist/tex/latex/base/ot1enc.dfu)
(/opt/local/share/texmf-dist/tex/latex/base/omsenc.dfu)))
No file book.aux.
(/opt/local/share/texmf-dist/tex/context/base/supp-pdf.tex
(/opt/local/share/texmf-dist/tex/context/base/supp-mis.tex
loading : Context Support Macros / Miscellaneous (2004.10.26)
)
loading : Context Support Macros / PDF (2004.03.26)
)
Chapter 1.
[1{/opt/local/share/texmf-var/fonts/map/pdftex/updmap/pdftex.map}]
Overfull \hbox (2.24872pt too wide) in paragraph at lines 39--40
\OT1/cmr/m/n/10.95 win-dows is avail-able from \OT1/cmr/m/it/10.95 http://sourc
eforge.net/projects/parrotwin32/f[]iles/\OT1/cmr/m/n/10.95 .
[2] [3]
Chapter 2.

LaTeX Font Warning: Font shape OMS/cmtt/m/n' undefined (Font) usingOMS/cmsy/m/n' instead
(Font) for symbol `textbraceleft' on input line 117.

[4] [5]

LaTeX Warning: !h' float specifier changed to!ht'.

[6] [7] [8]

LaTeX Font Warning: Font shape OMS/cmtt/bx/n' undefined (Font) usingOMS/cmtt/m/n' instead
(Font) for symbol `textbraceleft' on input line 395.

[9]
Chapter 3.

! LaTeX Error: Command \guillemotright unavailable in encoding OT1.

See the LaTeX manual or LaTeX Companion for explanation.
Type H for immediate help.
...

l.432 ...-width = 1 + [max] @scores».key».chars;

?

! LaTeX Error: Command \guillemotright unavailable in encoding OT1.

See the LaTeX manual or LaTeX Companion for explanation.
Type H for immediate help.
...

l.432 ...-width = 1 + [max] @scores».key».chars;

? X
</opt/local/share/texmf-dist/fonts/type1/bluesky/cm/cmbx10.pfb></opt/local/shar
e/texmf-dist/fonts/type1/bluesky/cm/cmssbx10.pfb></opt/local/share/texmf-dist/f
onts/type1/bluesky/cm/cmsl10.pfb></opt/local/share/texmf-dist/fonts/type1/blues
ky/cm/cmsy10.pfb></opt/local/share/texmf-dist/fonts/type1/bluesky/cm/cmsy8.pfb>
</opt/local/share/texmf-dist/fonts/type1/bluesky/cm/cmtt8.pfb></opt/local/share
/texmf-dist/fonts/type1/bluesky/cm/cmtt10.pfb></opt/local/share/texmf-dist/font
s/type1/bluesky/cm/cmti10.pfb></opt/local/share/texmf-dist/fonts/type1/bluesky/
cm/cmr10.pfb></opt/local/share/texmf-dist/fonts/type1/bluesky/cm/cmbx12.pfb>
Output written on book.pdf (9 pages, 99040 bytes).
Transcript written on book.log.
make: *** [build/book.pdf] Error 1
�[32;1mcoke@slurpee�[0m �[37m~/sandbox/perl6-book�[0m �[36;1m(git:master) �[0m�[35;1m$ �[0mvi scr���[K��[K��[K��[K��[K��[Kexit

Script done on Fri Apr 30 19:53:59 2010

5.2 I can has state? -- bad spelling

The formally trained editor may object to this heading's grammar, but in fact there is a spelling error. I believe the heading should read "I can haz state?"

:)

Thank you for writing this book and using a tone that pays homage to the Camel Book! I laughed out loud when I read the heading. Please accept my praise.

Code inline in text needs better markup

Code inline in text paragraphs lacks a clear markup distinction from the text around it. The fixed-width font doesn't work out as recognition for pieces of code that ends in punctuation characters, and is followed by punctuation, like in "use v6;," where the semicolon is part of the code, but the the comma is part of the narrative text.

Need to write a lexer for perl6 for Pygments

This way we can use minted as our syntax highlighter. Currently, it doesn't work properly with Perl6

Using Perl6: Section 4.8: Introspection: issues

1. This section would benefit from a general definition of instrospection. It's not a term I ever had to ponder while learning Perl 5. Perhaps this definition from http://en.wikipedia.org/wiki/Introspection_(computer_science) would suffice: "In computing, type introspection is a capability of some object-oriented programming languages to determine the type of an object at runtime."
2. There is a TODO item near the end of this section concerning '&signature.cando'. Has that been implemented yet? If so, then the section needs a complete example.

Example code in Chapter 2 (Basics) produces swapped values

Running the example code with the specified data produces the following output:

Ana has won 2 games and 8 sets
Dave has won 2 games and 6 sets
Charlie has won 1 games and 4 sets
Beth has won 1 games and 4 sets

It seems that the values for won games and sets are being swapped. The following changes appear to fix the issue.

--- ttscores.pl 2010-05-28 11:14:32.000000000 -0700
+++ ttscores.pl.new     2010-05-28 11:12:02.000000000 -0700
@@ -11,13 +11,13 @@
     my ($p1, $p2)          = $pairing.split(' vs ');
     my ($r1, $r2)          = $result.split(':');

-    %sets{$p1} += $r1;
-    %sets{$p2} += $r2;
+    %games{$p1} += $r1;
+    %games{$p2} += $r2;

     if $r1 > $r2 {
-       %games{$p1}++;
+       %sets{$p1}++;
     } else {
-        %games{$p2}++;
+        %sets{$p2}++;
     }
 }

Get rid of inkscape dependency

converting svg to pdf requires inkscape currently. Imagemagick is apparently not capable of producing proper colored and vectorized pdfs. We need another solution.

chapter 3, ".sort:", new syntax out of nowhere

The example for a custom comparison function uses an apparently new kind of syntax (appending a colon after a method and adding a block there), but there is no explanation why and how exactly it works.

Using Perl 6 - Line numbers make copying code examples annoying

Minor annoyance when working from the PDF - I wonder if there is a better way of formatting the code examples so that the line numbers are visible but don't get selected when you copy/paste from the PDF into your text editor?

ePub generation support

See Modern Perl Book -- but do it better, with chapters etc. ;)

Chapter 6 example doesn't work with rakudo star 2011.01

Hi,

I've just tried:

multi to-json(Real $d) {
$d;
}
multi to-json(Bool $b) {
  $b ?? 'true' !! 'false';
}
multi to-json(Str $s){
'"'
    ~ $s.trans( ['"' , '\\' ] => [ '\"' , '\\\\' ])
    ~ '"';
}

multi to-json(Array $d) {
  return '[ '
  ~ $d.values.map({  to-json($_) }).join(', ')
    ~ ' ]';
 }
 multi to-json(Hash $d) {
   return '{ '
    ~ $d.pairs.map({ to-json(.key)
                     ~ ' : '
                 ~ to-json(.value) }).join(', ')
                   ~ ' }';
 }

When I do

say to-json({ a => @A , b => 1.23 });

perl6 chokes:

too few positional arguments: 2 passed, 3 (or more) expected
in 'to-json' at line 13:chapter6.p6
in <anon> at line 24:chapter6.p6
in 'Any::join' at line 1
in 'to-json' at line 26:chapter6.p6
in main program body at line 47:chapter6.p6

For some reason it looks like it doesn't like what's given to the 'map' method.

Cannot make on Ubuntu Karma

I followed the README and have everything installed. But I am getting the following error message on make:

cd build && make -I ../lib -f ../lib/Makefile
NOTE: You may ignore warnings about the following files:
UsingPerl6.letter.d
make[1]: Entering directory /home/kthakore/Development/Perl6/book/build' ../lib/Makefile:2261: UsingPerl6.letter.d: No such file or directory = UsingPerl6.letter.tex --> UsingPerl6.letter.d UsingPerl6.letter.pdf.1st.make (0-1) = make[1]: *** [UsingPerl6.letter.d] Error 1 make[1]: Leaving directory/home/kthakore/Development/Perl6/book/build'
make: *** [pdf] Error 2

Line numbering should be disabled in output sections

Using Perl6: Chap 5: Multis: need self-contained example

Turning to Chap 5, "Multis," I immediately groan when I see that to follow the arguments in this chapter, I have to download a separate distribution from github and figure out how to install it. I have to figure out how libraries work in Perl6, even though there has been no discussion of this at this point in the PDF. From a heuristic point of view -- actually getting people to study and learn Perl 6 -- this is definitely suboptimal.

I would recommend re-writing this chapter with a self-contained example that the reader could simply type in and play with.

Thank you very much.

Introduce line wrap into code blocks

Will probably be possible with minted

Need definition of "Nominal Type"

The phrase "nominal type" first appears on p44 in the error message:

Nominal type check failed for parameter..

The phrase is then used a lot in the "Multis" chapter, e.g. in the discussion of constraint checks vs. Nominal Types.

It would be nice to have a little sentence somewhere stating what a "Nominal Type" is.

Using Perl6: Section 5.5: nested signatures used without prior discussion

This section begins, "An earlier chapter showed how to use nested signatures ..."

As far as I could determine, the term 'nested signatures' appears here for the first time in the book, and I couldn't find anything earlier that looked like a nested signature.

Specifying exact dimensions of the generated PDF

I was trying to use an online service to have the perl6 book printed, but they require the uploaded PDF to have exact dimensions in points.

It should just be a matter of using the geometry package for the generated LaTeX and transfering the options from the command line. Everyone agrees? I volunteer :)

Make the book translatable

1. Apply gettext
2. Upload translations to transifex.net
3. Make PDFs from translated material.

Yeah, I know, long shot.

Need automatic line breaking in tables.

Table 11.6: String methods/functions is too wide because the text is not broken in lines.

Chapter 5.6

In the example:

known_languages => <perl5, perl6, c++>

Should be without commas:

 known_languages => <perl5 perl6 c++>

With latest release of rakudo* , the commas become part of the array.

Using Perl6, Section 4.5: Captures: issues

1. The PDF version I have from Aug 2010 states: "In one sense, a signature is a collection of parameters. Captures fill the same niche for arguments." This does not provide a definition of a capture; it merely provides an analogy to something else. We need a definition.
2. In what sense is a capture different from an array reference?
3. Code sample at start of 4.5.1: Does each capture in this array have to have arguments in the same position?

Using Perl6: Section 4.7: Currying: issues

Currying is not a concept one encounters in Perl 5. This section would benefit by having a general definition of currying. Perhaps this description from http://en.wikipedia.org/wiki/Currying would suffice: "[T]he technique of transforming a function that takes multiple arguments (or an n-tuple of arguments) in such a way that it can be called as a chain of functions each with a single argument."

Using Perl6: Section 4.5: Captures: issues

1. The PDF version I have from Aug 2010 states: "In one sense, a signature is a collection of parameters. Captures fill the same niche for arguments." This does not provide a definition of a capture; it merely provides an analogy to something else. We need a definition.
2. In what sense is a capture different from an array reference?
3. Code sample at start of 4.5.1: Does each capture in this array have to have arguments in the same position?