Hi Todd,
Thanks for your detailed reply; it really helped me to understand your
perspective on all this. I have a few responses to particular points
you raise
My perspective on Raku's docs are that they are meant
as a refresher for those that already know what they
are doing.
My perspective is _very_ different. I first started programming Raku
less than two months ago. In that time, I've learned almost entirely
from the official docs (supplemented by some of the wonderful Advent
blog posts, the occasional Stack Overflow question, and some truly kind
people answering questions on IRC – but I didn't buy any books and, like
you, have had the official docs open nearly contentiously as I
programmed Raku). Throughout that learning process, I found the docs
helpful and informative. Even when I wasn't all that familiar with Raku,
I could follow the docs -- I didn't grasp *everything* when I was just
getting started, of course, but I learned enough to keep going. And, as
I did, I was able to dive into some of the more obscure corners of the
docs and learn a tremendous amount.
[They seem to have the attitude that]
"If you don't understand the Docs, it is because
you don't know what you are doing."
I 100% agree with you that "if you don't understand the docs, it's
because you don't know what you are doing" isn't a good approach to
take. All I can say is that I _never_ got the sense that anyone
involved in Raku's docs had that attitude, and I found the docs
refreshingly easy to understand -- even when I was brand new to Raku.
Lets go to operator classification:
https://docs.raku.org/languag/operators#Operator_classification
"Operators are just subroutines with funny names. The
funny names are composed of the category name (infix,
prefix, postfix, circumfix, postcircumfix), followed
by a colon, and a list of the operator name or names
(two components in the case of circumfix and
postcircumfix). A expanded explanation of all these
operators and what they mean is included in this table:
https://docs.raku.org/language/operators#Operator_classification";
Okay, "funny names" means they are "esoteric"
https://www.wordnik.com/words/esoteric
adjective: Intended for or understood by only a small
group, especially one with specialized knowledge
A few thoughts on this example. First, it appears to be from an older
version of the documentation: the current
docs.raku.org/language/operators page doesn't contain that paragraph.
Instead, the "Operator classification" section starts with a very clear
table showing exactly what "prefix", "infix", "postfix", "circumfix",
"postcircumfix", and "method" operators look like. I can remember first
reading that table and being very grateful for how clear it was -- I'd
heard a few mentions of "postcircumfix operators" before but wasn't
clear on what the term meant. So it was great to have a table lay out
that "postcirmfix" just means `term1[term2]`.
Also, I don't have the same reaction to the phrase "funny names" that
you do -- I don't think of "funny names" as necessarily being esoteric.
They could just be a bit unusual. For example, if you want to get the
numerator and denominator of a rational number in Raku, you use a method
that's comprised of the first two letters of "numerator" and
"denominator": that is, you call `Rat.nude`. Now, *I'd* say that
`Rat.nude` is a bit of a funny name, but there's sure nothing esoteric
about it!
Now when you are writing docs, you need to start small
and work up to the complicated.
Yep, I agree with you 100%. The difference, I guess, is that I
generally think Raku's docs did a great job of doing so.
Very few of the other [methods are documented] this way.
This one also started with an error in the cryptogram
as well. (That is another complaint about the
documentation. The cryptograms are often wrong.)
And there should be zero tolerance for "insider knowledge".
This might be a bit ironic, but I can't follow what you're saying here.
What do you mean by "cryptogram"? To me, that strikes me as _much_ more
of an esoteric term than anything in the Raku docs -- but maybe it has a
common meaning in this context that I just haven't come across (and that
a basic Internet search didn't turn up).
And "in your face example" would be one of my all time
favorite routines which is "lines". I use "lines"
ALL-THE-TIME.
https://docs.raku.org/routine/lines
"Defined as:
sub lines(Str(Cool))
method lines()
Coerces the invocant (and in sub form, the argument)
to Str, decomposes it into lines (with the newline
characters stripped), and returns the list of lines."
Okay, that sorta-kinda says what it means.
Do you see this explained?
To pick out particular lines:
$ cat Lines.txt | raku -e '.say for lines()[3,2,5]'
Line 3
Line 2
Line 5
If it is, it is buried somewhere.
This is so fascinating to me -- you provide that as an example of poor
documentation, but *I* would look at that as an area where Raku (with
the help of its docs) just clicks perfectly into place. Everything that
the docs explain for this and related topics fits together into a
cohesive whole, and after reading the docs, I not only see how the language
works, but am also left with the feeling that the language couldn't
possibly work any other way.
I'd like to walk through this in more detail -- maybe you'll at least
understand how I feel that way about these docs, even if you don't quite
feel that way yourself.
So, we're trying to figure our how `.say for lines()[3,2,5]` works.
What do we know about `lines`? Well, from the docs you quoted, we know
that it takes a `Str(Cool)` -- that is, a `Cool` that it can coerce into
a `Str`. In this case, we know exactly what that is from the text right
below what you quoted
Without any arguments, sub lines operates on $*ARGFILES, which
defaults to $*IN in the absence of any filenames.
This means that `lines` with get the text of `Lines.txt` that you passed
in via standard input as its argument. So the code you posted is
equivalent to the following psudocode:
for lines($string-of-text-from-Lines-dot-txt)[3,2,5] -> $line {
say($line);
}
Ok, what next? Well, again from the docs you quoted, we know that
`lines` "returns a list of lines". So our psudocode is really more
like:
for ($line1, $line2, $line3 … $lineN)[3,2,5] -> $line {
say($line)
}
That is, we have a `List` followed by `[3,2,5]`. What do the docs tell
us about `List`s? Well docs.raku.org/type/List tells us that
List implements Positional and as such provides supports for
subscripts
That last word is a link; following it takes us to
docs.raku.org/language/subscripts and _that_ page tells us about slices:
When multiple elements of a collection need to be accessed, there's a
shortcut to doing multiple separate subscripting operations: Simply
specify a list of indices/keys in the subscript, to get back a list of
elements - also called a "slice" - in the same order.
And that tells us exactly what `[3,2,5]` is doing: it gives us element
3, element 2, and then element 5 from the list of lines -- which is to
say that it gives us the fourth, third, and sixth lines of the input
file (adjusting by one because the `List` is zero indexed).
For me, this is where Raku shines: there's no documentation specifically
about how `lines()[3,2,5]` works because there's _nothing special_ about
how it works. That is to say, there's no special case that handles
`lines()[3,2,5]` any differently than any other expression. `lines` is
_just_ a subroutine; `[3,2,5]` is _just_ a slice; `for` is _just_ a
loop. (OK, there's arguably a slight special casing of `lines()` in the
way it takes $*IN. Honestly, if I had my druthers, I might cut that,
but I understand why that wouldn't be popular.) In combination, they
let us do something powerful -- print just a subset of lines from a
file, in any order we specify. But their power just falls out of
natural, emergent properties of Raku, each of which is simple on its
own.
So, basically the documentation is what it is. My way of
coping is to create my own set of documentation, which
I call "keepers". So far I am up to 220 of them. You will
see me occasionally posting some of them to this group.
That seems like a really great idea. Have you considered posting any to
a wider audience than this mailing list? Just yesterday, I was
struggling to get conditional compilation to work, and that turned out
to be enough material for a blog post:
www.codesections.com/blog/raku-unit-testing-with-conditional-compilation/
If you're willing to post your "keepers", I bet others would enjoy
reading them as well.
Hope that explains it. I ADORE Raku. The only thing
I dislike is the documentation.
I'm glad you like Raku -- I feel the same way. Now, I'm going to get
back to trying to improve the documentation; I've submitted two pull
requests today, and am making decent progress towards a third. Maybe
one day, you'll like the docs as much as you like the language itself.
Sorry for being so long winded.
Likewise!
Best regards,
Daniel
