Daniel, the thing about Todd is that his brain doesn't process the written word the way most people do. That is according to him by the way.
He is under the assumption that it is because of how he was taught to read. I think the issue is different. I think that he might be on the Autistic Spectrum like me. (And possibly Larry Wall himself.) The thing about Autistics is that their brains can be very different to Allistic people. I am not saying that is bad, only different. Parts of their brain can be more developed at the expense of other parts of the brain. That can mean that they have to use other parts of their brain to compensate for the underdeveloped parts. For example there is a woman on YouTube that processes language by thinking in pictures. Which can mean that she has difficulty remembering exactly what was said or written. If she heard the sentence “He took his dog for a walk”, she might picture the Gorton's Fisherman taking a beagle for a walk. So then if you asked her to repeat the sentence she might say something almost completely different. Anyway the problem is that Raku was designed by a linguist. So if you have difficulties with linguistic content you might be very confused. Again, according to Todd, he has difficulty with the linguistic content of the written word. I think that for me both the language and visual centers are overly expressed and highly connected so Raku is very easy for me. I often don't have to read the descriptions of the functions at all. Just the names and function signature is enough for me to figure it out. So something like his keepers would be completely pointless for me. Todd however needs those keepers to compensate for how his brain works differently. Again, I am not saying that is bad, only different. --- Now with all of that said, it is little wonder why Todd has difficulties with the function descriptions where others don't. I also think that if we just replaced what we have for something that works for Todd it might make it more difficult for others. Again because his brain is more unique than most. What we could do is try to include things from both groups. We want to be an inclusive community after all. There is a reason our mascot was designed to be appealing to youngsters. On Thu, Aug 27, 2020 at 6:59 PM Daniel Long Sockwell < dan...@codesections.com> wrote: > > 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 >
