El lun., 9 dic. 2019 a las 2:48, ToddAndMargo via perl6-users (< perl6-us...@perl.org>) escribió:
> On 2019-12-07 08:17, Philip Hazelden wrote: > > This is not IEEE-ese. Earlier, you defined IEEE-ese as > > > > Technical written material that uses so many obscure > > terms and unnecessary technical jargon mixed with > > deliberate obscurities that even a reader with > > intimate knowledge of the subject are confused. > > Example: read any published paper from IEEE. > > > > That is, IEEE-ese uses technical jargon *unnecessarily*. By contrast, > > what you quoted is simply using technical jargon *clearly and > > precisely*. (It does have a typo, the word "to" is missing between > > "invocant" and "Str"; and "Str.contains" links to the wrong anchor in > > the page.) It can probably be hard to tell the difference, if you aren't > > familiar with the technical jargon in question. But in this case, if you > > know what an "invocant" is, and what it means to "coerce" something, and > > to "call" a method, then the meaning is clear; and in fact, the way it > > was written seems like the obvious way to write it. > > > > If you don't know what those words mean, then the meaning won't be > > clear. (But even then, clicking the link on "Str.contains" and glancing > > down that page a little should give you some hints.) Perhaps, to make it > > easier for you to understand, the docs could stop using words like > > "invocant" and "coerce". But that makes it *harder* for people who do > > understand these words, because those people then have to read more > > words and translate them into their precise understanding. > > > > Perhaps it can be rewritten to make it clearer for people who don't know > > the jargon while not losing concision or expressiveness for people who > > do. But that's not necessarily an easy thing to do; and someone who > > doesn't know the jargon is unlikely to do it well. > > > > As for `|c`, that's part of the type signature. For people who can read > > type signatures, glancing at the type signature of a method can be much > > easier than reading a possible-imprecise description of how to use it. > > If you can't read type signatures, you're out of luck; but that's no > > reason to hide them from people who can. If you type `|` into the search > > box, there's an entry under "Reference" named "| (parameter)" (which > > admittedly also links to the wrong anchor in the page), and another > > under "Syntax" simply named "|", and either one of those will (with > > perhaps a bit more reading and following links) take you to > > https://docs.raku.org/type/Signature#Capture_parameters which describes > > what it does. > > Hi Phillip, > > Have you ever been to an IEEE seminar and attended a lecture > on a subject that you have intimate knowledge on hoping > to pick up some additional tips. In the lecture you keep > shaking your head saying to yourself "What, Huh? What > the Heck?". After the lecture you ask yourself why you > wasted both your time and your money? And here is the thing, > They are doing exactly what you stated are "cleanly and precisely" done. > These lecture are painstakingly peer > reviewed. So why can't you figure out what the heck is > going on and you KNOW THE SUBJECT? This is IEEE-eese. > > Now back to "contains". "method contains(Cool:D: |c)" > is not correct. It is missing the "$pos --> Bool" which > Those changes were made two months ago in this commit: https://github.com/rakudo/rakudo/commit/696eea2de6e67135b3b574ecb579ede16045ede6 We can't possible keep up with changes, even more so if those who notice the changes just keep it to themselves. We're still trying to reflect all changes that were made for the 6.d release a year ago. Other than that, it's clear from the context that it returns a Boolean, and concepts like signatures or the meaning of sigils can't be explained in every single place they appear. They can't even be linked, because they are not mentioned. In the definition of a method or sub, you're supposed to know a series of things: what's a method, what's a signature, and there are helpful reference and tutorial pages for that. Cheers JJ
