Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Todd Chester via perl6-users]

On 2019-12-11 14:26, Joseph Brenner wrote:

Joseph Brenner  wrote:

The signatures in the documentation are certainly helpful, but they're
no substitute for code examples.   I'd go after adding more code
examples, rather than removing other stuff.


But then, maybe I'm coming into this discussion in the middle-- is the
topic here adding command-line switches to suppress some type
checking, e.g. for one-liners?

That would make some sense to me, but I don't have any strong feelings about it.



The discussion changed into me not liking the way they
prssent the signatures in the doc pages.  You were on target.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Todd Chester via perl6-users]

On 2019-12-11 14:06, Joseph Brenner wrote:

The signatures in the documentation are certainly helpful, but they're
no substitute for code examples.   I'd go after adding more code
examples, rather than removing other stuff.



Hi Joseph,

I would compromise on that.

I would also like to see the doc's signature page explain in
detail what each position and symbol means before jumping
into various signatures.  In other words, start at the
beginning, not the middle.

-T

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Joseph Brenner]

Joseph Brenner  wrote:
> The signatures in the documentation are certainly helpful, but they're
> no substitute for code examples.   I'd go after adding more code
> examples, rather than removing other stuff.

But then, maybe I'm coming into this discussion in the middle-- is the
topic here adding command-line switches to suppress some type
checking, e.g. for one-liners?

That would make some sense to me, but I don't have any strong feelings about it.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Joseph Brenner]

The signatures in the documentation are certainly helpful, but they're
no substitute for code examples.   I'd go after adding more code
examples, rather than removing other stuff.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Simon Proctor]

 I would argue that signatures are great for any command line script
because you can use them with MAIN to get input checking.

On Wed, 11 Dec 2019, 18:07 Veesh Goldman,  wrote:

> I believe there's a disparity here between the needs of a sysadmin and
> people who program hardcore with Raku. That's what I'm seeing in the
> discussion here.
>
> Signatures are very important to those who write programs, because they
> help you arrange your code in a clean and maintainable and predictable way.
>
> Those who only write one-off scripts or one liners don't yet understand
> their value.
>
> My two cents on what's going on here.
>
> On Wed, Dec 11, 2019 at 7:17 PM yary  wrote:
>
>> > The signatures are very important to the developers.
>> > They only confuse the programmer.
>>
>> Speak for yourself, I'm not developing the innards of Raku, I'm just
>> using it for projects- like you. And I NEED the signatures. They tell me so
>> much!!
>>
>> -y
>>
>>
>> On Mon, Dec 9, 2019 at 6:53 PM ToddAndMargo via perl6-users <
>> perl6-users@perl.org> wrote:
>>
>>> On 2019-12-09 09:44, Trey Harris wrote:
>>> > Signatures are important to Raku.
>>>
>>> Trey,
>>>
>>> The signatures are very important to the developers.
>>> They only confuse the programmer.
>>>
>>> -T
>>>
>>

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Veesh Goldman]

I believe there's a disparity here between the needs of a sysadmin and
people who program hardcore with Raku. That's what I'm seeing in the
discussion here.

Signatures are very important to those who write programs, because they
help you arrange your code in a clean and maintainable and predictable way.

Those who only write one-off scripts or one liners don't yet understand
their value.

My two cents on what's going on here.

On Wed, Dec 11, 2019 at 7:17 PM yary  wrote:

> > The signatures are very important to the developers.
> > They only confuse the programmer.
>
> Speak for yourself, I'm not developing the innards of Raku, I'm just using
> it for projects- like you. And I NEED the signatures. They tell me so much!!
>
> -y
>
>
> On Mon, Dec 9, 2019 at 6:53 PM ToddAndMargo via perl6-users <
> perl6-users@perl.org> wrote:
>
>> On 2019-12-09 09:44, Trey Harris wrote:
>> > Signatures are important to Raku.
>>
>> Trey,
>>
>> The signatures are very important to the developers.
>> They only confuse the programmer.
>>
>> -T
>>
>

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[yary]

> The signatures are very important to the developers.
> They only confuse the programmer.

Speak for yourself, I'm not developing the innards of Raku, I'm just using
it for projects- like you. And I NEED the signatures. They tell me so much!!

-y


On Mon, Dec 9, 2019 at 6:53 PM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 09:44, Trey Harris wrote:
> > Signatures are important to Raku.
>
> Trey,
>
> The signatures are very important to the developers.
> They only confuse the programmer.
>
> -T
>

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 16:07, Trey Harris wrote:
On Mon, Dec 9, 2019 at 9:53 PM ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


On 2019-12-09 09:44, Trey Harris wrote:
 > Signatures are important to Raku.

Trey,

The signatures are very important to the developers.
They only confuse the programmer.

I explained in the context surrounding the sentence you clipped out why 
this is not true. (Assuming you’re defining “developers” as “programmers 
who work on Raku compiler and language internals” and “programmers” as 
“developers who have a working knowledge of Raku and use it regularly, 
but do not work on internals”. If you made this distinction explicit 
somewhere, I haven’t seen it.)


As I wrote in that earlier email, Raku puts a great deal of what would 
in other languages be considered /language syntax into/ routine 
signatures, and Signatures in Raku can do things that no other language 
is capable of. (Most individual features thereof, there are other 
languages that include them. But I don’t think any other language has 
put such a rich set of them together before, especially in the context 
of multi dispatch.) This means they /are/ important to the “programmer” 
in your construction.


And, in fact, I find it difficult to understand why you’d think most 
routine signatures would be /more/ useful to “developers” vs. 
“programmers” in your formulation: if one is modifying a routine in core 
or in the compiler, one has the definition, including signature, right 
there—signatures in the docs are not intended for them. If one is 
/using/ a routine in internals/core, or needs to refer to other versions 
of a multi, then that “developer” is acting as a “programmer” at that 
moment—they are using, not modifying, the routine in question, and yes, 
the doc signatures are useful to them, but no more so than for any other 
Raku programmer.


Let me make an observation on one of your earlier “keeper” emails, the 
one that has been memorialized in the archive 
. 
In it, beginning with the line where you repeat the signature verbatim, 
here’s a few lines of what you’ve written:


|multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool) 
"multi method" This means there are multiple ways to address this, as in 
multi method contains(Str:D: Cool:D $needle --> Bool) multi method 
contains(Str:D: Str:D $needle --> Bool) multi method contains(Str:D: 
Cool:D $needle, Int(Cool:D) $pos --> Bool) multi method contains(Str:D: 
Str:D $needle, Int:D $pos --> Bool) "Str" means it want to be fed data 
as a string. Str.foo [...] "-->Bool" means it return True or False |


in total, you spend 44 lines describing the signature. My observation is 
this:


/*Your English description of the method’s signature could be 
programmatically generated from the Signature itself.*/ (At least, 
adjusting slightly for standardizing the description.)


The only way in which this assertion /isn’t/ true is your use of words 
like “haystack” to try to explain the purpose of the arguments and verbs 
other than neutral ones like “passes”, “references”, and “returns” and 
instead use ones that are specific to the purpose of |.contains|—plus 
your mention of “Index starts at zero by way of string convention in 
Perl 6”—which I don’t entirely understand. (But if desired, all those 
qualities could be added as machine-readable annotations to |.contains| 
and other routines’ self-documenting Pods.)


I think there are two interesting conclusions to be drawn from this:

 1.

If you think these 44 lines are tremendously useful and would be
more useful than the signatures, then they could, in fact, be
programmatically generated and inserted into every single routine’s
documentation. Since this would add a great deal of bulk to the
docs, perhaps this could be done as hover text (perhaps even so that
each part of your description appeared as you hovered over the
relating Signature text), or something that is found under a
disclosure button.

There would, of course, be some routines for which this
autogenerated description would be insufficient. But those are the
ones where docs text is already given over to usage descriptions.

 2.

With the prior point stipulated, the question is raised: if you know
enough of Signatures to write what you wrote, how do you not “know
signatures”? If it’s because you spent a great deal of
trial-and-error to figure out what you wrote below the signature,
where those of us who understand Signatures just see (for the most
part) an algebraic expansion into 44 lines of English and
formatting—then perhaps the exercise of doing exactly what’s
described in the prior point would be a useful new feature for the
docs framework.

But for those of us who can read a signature and interpret it as an
extremely brief form of those 44 lines, 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Trey Harris]

On Mon, Dec 9, 2019 at 9:53 PM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

On 2019-12-09 09:44, Trey Harris wrote:
> > Signatures are important to Raku.
>
> Trey,
>
> The signatures are very important to the developers.
> They only confuse the programmer.
>
I explained in the context surrounding the sentence you clipped out why
this is not true. (Assuming you’re defining “developers” as “programmers
who work on Raku compiler and language internals” and “programmers” as
“developers who have a working knowledge of Raku and use it regularly, but
do not work on internals”. If you made this distinction explicit somewhere,
I haven’t seen it.)

As I wrote in that earlier email, Raku puts a great deal of what would in
other languages be considered *language syntax into* routine signatures,
and Signatures in Raku can do things that no other language is capable of.
(Most individual features thereof, there are other languages that include
them. But I don’t think any other language has put such a rich set of them
together before, especially in the context of multi dispatch.) This means
they *are* important to the “programmer” in your construction.

And, in fact, I find it difficult to understand why you’d think most
routine signatures would be *more* useful to “developers” vs. “programmers”
in your formulation: if one is modifying a routine in core or in the
compiler, one has the definition, including signature, right
there—signatures in the docs are not intended for them. If one is *using* a
routine in internals/core, or needs to refer to other versions of a multi,
then that “developer” is acting as a “programmer” at that moment—they are
using, not modifying, the routine in question, and yes, the doc signatures
are useful to them, but no more so than for any other Raku programmer.

Let me make an observation on one of your earlier “keeper” emails, the one
that has been memorialized in the archive
. In
it, beginning with the line where you repeat the signature verbatim, here’s
a few lines of what you’ve written:

multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos --> Bool)

"multi method"
 This means there are multiple ways to address this, as in

  multi method contains(Str:D: Cool:D $needle --> Bool)
  multi method contains(Str:D: Str:D $needle --> Bool)
  multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos
--> Bool)
  multi method contains(Str:D: Str:D $needle, Int:D $pos --> Bool)

"Str"
 means it want to be fed data as a string.  Str.foo
[...]
"-->Bool"
 means it return True or False

in total, you spend 44 lines describing the signature. My observation is
this:

*Your English description of the method’s signature could be
programmatically generated from the Signature itself.* (At least, adjusting
slightly for standardizing the description.)

The only way in which this assertion *isn’t* true is your use of words like
“haystack” to try to explain the purpose of the arguments and verbs other
than neutral ones like “passes”, “references”, and “returns” and instead
use ones that are specific to the purpose of .contains—plus your mention of
“Index starts at zero by way of string convention in Perl 6”—which I don’t
entirely understand. (But if desired, all those qualities could be added as
machine-readable annotations to .contains and other routines’
self-documenting Pods.)

I think there are two interesting conclusions to be drawn from this:

   1.

   If you think these 44 lines are tremendously useful and would be more
   useful than the signatures, then they could, in fact, be programmatically
   generated and inserted into every single routine’s documentation. Since
   this would add a great deal of bulk to the docs, perhaps this could be done
   as hover text (perhaps even so that each part of your description appeared
   as you hovered over the relating Signature text), or something that is
   found under a disclosure button.

   There would, of course, be some routines for which this autogenerated
   description would be insufficient. But those are the ones where docs text
   is already given over to usage descriptions.
   2.

   With the prior point stipulated, the question is raised: if you know
   enough of Signatures to write what you wrote, how do you not “know
   signatures”? If it’s because you spent a great deal of trial-and-error to
   figure out what you wrote below the signature, where those of us who
   understand Signatures just see (for the most part) an algebraic expansion
   into 44 lines of English and formatting—then perhaps the exercise of doing
   exactly what’s described in the prior point would be a useful new feature
   for the docs framework.

   But for those of us who can read a signature and interpret it as an
   extremely brief form of those 44 lines, eliminating the signature for those
   44 lines would not be a welcome change to 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Brian Duggan]

Hi Folks,

While the tone of this conversation is a little unpleasant
I think there are good points about the readability of the
reference documentation.

For instance, I understand that List inherits from
"Cool", but listing trigonometric functions on this
page

  https://docs.raku.org/type/List

really hurts readability; nobody is going to call "cotan"
on a list.  In my opinion, this section should maybe have
a link to the "Cool" page at most, perhaps in a footnote.

Also this exact same list appears on every page that inherits
from Cool

  https://docs.raku.org/type/Range
  https://docs.raku.org/type/Map
  https://docs.raku.org/type/Seq
  https://docs.raku.org/type/Match
  etc

I get that the list of methods is comprehensive, but I would argue that
seeing things like Match.sqrt, Seq.log10 and Range.lc are distracting and
these pages could benefit a less pedantic presentation

Brian

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 03:31, Veesh Goldman wrote:
Nobody said not to do it. Please make more documentation available to 
the public.


But that doesn't mean that these docs need to change. It's reference, 
not guides.


And also it doesn't need to be a wiki. You could do everything on 
GitHub, where most people already do their collaboration, with the plus 
that you can deploy your repo as a static site for free.


In fact, you could also contribute guides to the official docs, just 
collaborate over GitHub. You can do reviews line by line, and anyone who 
works in the docs would get automatically updated.


I would like to discuss your idea anyways, so you could drop me a line 
on irc. I go by veesh on freenode and irc.perl.org 


Have a wonderful day,
Veesh


Hi Veesh,

When I come across a doc that I particularity dislike,
rather than just griping -- okay griping is fun too -- I
rather be able to write something I think solves the
issue.  And being that I usually will write myself
all kinds of notes anyway (keepers), I'd be most of
the way there anyway.

I am afraid I am terrible at irc, but you can always
write me off list.

-T

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 03:02, ToddAndMargo via perl6-users wrote:

I would


"It would", not "I would"

Stinkin' typos

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Veesh Goldman]

Nobody said not to do it. Please make more documentation available to the
public.

But that doesn't mean that these docs need to change. It's reference, not
guides.

And also it doesn't need to be a wiki. You could do everything on GitHub,
where most people already do their collaboration, with the plus that you
can deploy your repo as a static site for free.

In fact, you could also contribute guides to the official docs, just
collaborate over GitHub. You can do reviews line by line, and anyone who
works in the docs would get automatically updated.

I would like to discuss your idea anyways, so you could drop me a line on
irc. I go by veesh on freenode and irc.perl.org

Have a wonderful day,
Veesh

On Tue, Dec 10, 2019, 13:04 ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-10 02:37, ToddAndMargo via perl6-users wrote:
> > On 2019-12-10 01:14, Simon Proctor wrote:
> >>
> >>
> >> On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users
> >> mailto:perl6-users@perl.org>> wrote:
> >>
> >> On 2019-12-09 07:21, Simon Proctor wrote:
> >>  > I think this does highlight something we probably should document
> >> more.
> >>  >
> >>  > How to read signatures. Because it's a *very* powerful part of
> the
> >>  > language that if you don't understand you're only using it at
> >> half strength.
> >>  >
> >>  > multi method contains(Str:D: Cool:D $needle, Cool:D $pos -->
> >> Bool:D)
> >>  >
> >>  > If not some documentation magic, it's a core part of the
> >> language. It
> >>  > tell you this method is called on a defined Str (Str:D:) it
> >> takes 2
> >>  > positional arguments which have to be defined Cool types ($needle
> >> and
> >>  > $pos) and it returns a Boolean.
> >>  >
> >>  > That is the code as it will be written in the Str Role.
> >>  >
> >>  > I *highly* advise learning how signatures work.
> >>
> >>
> >>
> >> Firstly can I say I admire the fact that you are using Raku in
> >> production on a regular basis.
> >>
> >> Hi Simon,
> >>
> >> Did you see the How To post I made on ".contains"?  At
> >> the bottom of the How To, I take apart the signature
> >> and explain each part.
> >>
> >>
> >> I did. It's pretty good except your understanding of the first part
> >> Str:D :
> >>
> >> This indicates that this method will be used when it's called on a
> >> defined (D) String instance. The wording you use is a bit weird and it
> >> speak to my beliefe that you don't really get Signatures.
> >>
> >> Do you see anywhere in the docs where how to read
> >> signatures is explained?  (Don't get any ideas.  The
> >> signatures should not be there to start with.)
> >>
> >>
> >> Apart from here? https://docs.raku.org/type/Signature
> >>
> >> I read through this (and some bits on Captures) and was able to get
> >> enough information to give a talk at the Perl Conference in Glasgow in
> >> 2018.
> >>
> >> Here's the video :
> >>
> https://www.youtube.com/watch?v=V5rWtKIVmJc=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz
> >>
> >>
> >> Larry was there, it was rather stressful.
> >>
> >> An aside on the signatures: what is and what is
> >> not a separator can blow your mind.
> >>
> >>
> >> Not really. comma seperates arguments, colon can be used if you want
> >> to specify information about the calling instance or class.
> >>
> >>
> >> Do you think it help me or anyone else understand
> >> how to use ".contains" because I explained the
> >> "Signature"?  Seriously?
> >>
> >>
> >> No, I don't think you NEED the signature to understand contains. I
> >> think that understanding and being able to read signatures CAN help
> >> you understand more about how a subroutine or method works.
> >>
> >> To answer the question, look at all the various
> >> teaching manuals out there for Raku.  Do you see a
> >> SINGLE ONE, other that the one I posted, that
> >> uses the signatures as a teaching tool?
> >>
> >>
> >> I have every single book written about Raku (though of course most are
> >> Perl6) and most of them explain Signatures.
> >>
> >> Again I'm not saying that they should be used as a teaching tool, but
> >> the documentation has a lot of uses and it's not just teaching.
> >>
> >>
> >> And notice that I put the signature explanation
> >> at the bottom AFTER I explained how to use the
> >> function (method).  This is akin to the good math
> >> teachers that run circles around bad math teachers
> >> in both mechanics and theory by FIRST teaching the
> >> mechanics and them teaching the theory.  When
> >> teaching, you should never start with the theory.
> >> The docs do just that.
> >>
> >>
> >> So when I was first reading the docs I mostly just skipped over the
> >> signatures to get to the rest of the code. I didn't try and understand
> >> them too much "Oh this takes a string, makes sense".
> >>
> >> Over time I did start to learn them and 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 02:37, ToddAndMargo via perl6-users wrote:

On 2019-12-10 01:14, Simon Proctor wrote:



On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


    On 2019-12-09 07:21, Simon Proctor wrote:
 > I think this does highlight something we probably should document
    more.
 >
 > How to read signatures. Because it's a *very* powerful part of the
 > language that if you don't understand you're only using it at
    half strength.
 >
 > multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> 
Bool:D)

 >
 > If not some documentation magic, it's a core part of the
    language. It
 > tell you this method is called on a defined Str (Str:D:) it 
takes 2

 > positional arguments which have to be defined Cool types ($needle
    and
 > $pos) and it returns a Boolean.
 >
 > That is the code as it will be written in the Str Role.
 >
 > I *highly* advise learning how signatures work.



Firstly can I say I admire the fact that you are using Raku in 
production on a regular basis.


    Hi Simon,

    Did you see the How To post I made on ".contains"?  At
    the bottom of the How To, I take apart the signature
    and explain each part.


I did. It's pretty good except your understanding of the first part 
Str:D :


This indicates that this method will be used when it's called on a 
defined (D) String instance. The wording you use is a bit weird and it 
speak to my beliefe that you don't really get Signatures.


    Do you see anywhere in the docs where how to read
    signatures is explained?  (Don't get any ideas.  The
    signatures should not be there to start with.)


Apart from here? https://docs.raku.org/type/Signature

I read through this (and some bits on Captures) and was able to get 
enough information to give a talk at the Perl Conference in Glasgow in 
2018.


Here's the video : 
https://www.youtube.com/watch?v=V5rWtKIVmJc=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz 



Larry was there, it was rather stressful.

    An aside on the signatures: what is and what is
    not a separator can blow your mind.


Not really. comma seperates arguments, colon can be used if you want 
to specify information about the calling instance or class.



    Do you think it help me or anyone else understand
    how to use ".contains" because I explained the
    "Signature"?  Seriously?


No, I don't think you NEED the signature to understand contains. I 
think that understanding and being able to read signatures CAN help 
you understand more about how a subroutine or method works.


    To answer the question, look at all the various
    teaching manuals out there for Raku.  Do you see a
    SINGLE ONE, other that the one I posted, that
    uses the signatures as a teaching tool?


I have every single book written about Raku (though of course most are 
Perl6) and most of them explain Signatures.


Again I'm not saying that they should be used as a teaching tool, but 
the documentation has a lot of uses and it's not just teaching.



    And notice that I put the signature explanation
    at the bottom AFTER I explained how to use the
    function (method).  This is akin to the good math
    teachers that run circles around bad math teachers
    in both mechanics and theory by FIRST teaching the
    mechanics and them teaching the theory.  When
    teaching, you should never start with the theory.
    The docs do just that.


So when I was first reading the docs I mostly just skipped over the 
signatures to get to the rest of the code. I didn't try and understand 
them too much "Oh this takes a string, makes sense".


Over time I did start to learn them and that helped me getting better 
at programming Perl6.



    The "Signatures" in the docs only confuse and often
    have mistakes in them.  Trying to get them corrected
    is a fools errand too.


How do you mean? If there's a mistake in the signature you can fix it 
in the docs and put in a pull request to get it updated.


    The signatures are how the developers talk to each other.
    And judging by the results of their work, it works
    marvelously for them.  This kind of information is
    not appropriate for standard Rakoon that just wants to
    write code.


Here is where I have to respectfully disagree with you.

Writing Raku code without using Signatures and Multi Methods is like 
owning a Jaguar and only driving in first gear. I mean *technically* 
you can get where you want to go but you are forgoing a lot of the 
power of the language.


I generally write a couple of Raku scripts a week (more if I've got 
the time) and they *all* use Signatures. Most use multi methods too.


    You don't need to know how much current affects an LED
    diode to read the time on your digital clock.  This
    is what the signatures are doing.

    The Signatures only confuse.  They need to be left to
    the developers.


This is the problem, until you stop treating 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 01:14, Simon Proctor wrote:



On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


On 2019-12-09 07:21, Simon Proctor wrote:
 > I think this does highlight something we probably should document
more.
 >
 > How to read signatures. Because it's a *very* powerful part of the
 > language that if you don't understand you're only using it at
half strength.
 >
 > multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)
 >
 > If not some documentation magic, it's a core part of the
language. It
 > tell you this method is called on a defined Str (Str:D:) it takes 2
 > positional arguments which have to be defined Cool types ($needle
and
 > $pos) and it returns a Boolean.
 >
 > That is the code as it will be written in the Str Role.
 >
 > I *highly* advise learning how signatures work.



Firstly can I say I admire the fact that you are using Raku in 
production on a regular basis.


Hi Simon,

Did you see the How To post I made on ".contains"?  At
the bottom of the How To, I take apart the signature
and explain each part.


I did. It's pretty good except your understanding of the first part Str:D :

This indicates that this method will be used when it's called on a 
defined (D) String instance. The wording you use is a bit weird and it 
speak to my beliefe that you don't really get Signatures.


Do you see anywhere in the docs where how to read
signatures is explained?  (Don't get any ideas.  The
signatures should not be there to start with.)


Apart from here? https://docs.raku.org/type/Signature

I read through this (and some bits on Captures) and was able to get 
enough information to give a talk at the Perl Conference in Glasgow in 2018.


Here's the video : 
https://www.youtube.com/watch?v=V5rWtKIVmJc=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz


Larry was there, it was rather stressful.

An aside on the signatures: what is and what is
not a separator can blow your mind.


Not really. comma seperates arguments, colon can be used if you want to 
specify information about the calling instance or class.



Do you think it help me or anyone else understand
how to use ".contains" because I explained the
"Signature"?  Seriously?


No, I don't think you NEED the signature to understand contains. I think 
that understanding and being able to read signatures CAN help you 
understand more about how a subroutine or method works.


To answer the question, look at all the various
teaching manuals out there for Raku.  Do you see a
SINGLE ONE, other that the one I posted, that
uses the signatures as a teaching tool?


I have every single book written about Raku (though of course most are 
Perl6) and most of them explain Signatures.


Again I'm not saying that they should be used as a teaching tool, but 
the documentation has a lot of uses and it's not just teaching.



And notice that I put the signature explanation
at the bottom AFTER I explained how to use the
function (method).  This is akin to the good math
teachers that run circles around bad math teachers
in both mechanics and theory by FIRST teaching the
mechanics and them teaching the theory.  When
teaching, you should never start with the theory.
The docs do just that.


So when I was first reading the docs I mostly just skipped over the 
signatures to get to the rest of the code. I didn't try and understand 
them too much "Oh this takes a string, makes sense".


Over time I did start to learn them and that helped me getting better at 
programming Perl6.



The "Signatures" in the docs only confuse and often
have mistakes in them.  Trying to get them corrected
is a fools errand too.


How do you mean? If there's a mistake in the signature you can fix it in 
the docs and put in a pull request to get it updated.


The signatures are how the developers talk to each other.
And judging by the results of their work, it works
marvelously for them.  This kind of information is
not appropriate for standard Rakoon that just wants to
write code.


Here is where I have to respectfully disagree with you.

Writing Raku code without using Signatures and Multi Methods is like 
owning a Jaguar and only driving in first gear. I mean *technically* you 
can get where you want to go but you are forgoing a lot of the power of 
the language.


I generally write a couple of Raku scripts a week (more if I've got the 
time) and they *all* use Signatures. Most use multi methods too.


You don't need to know how much current affects an LED
diode to read the time on your digital clock.  This
is what the signatures are doing.

The Signatures only confuse.  They need to be left to
the developers.


This is the problem, until you stop treating signatures as some kind of 
weird messaging system only to be used 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-10 00:57, Fernando Santagata wrote:
On Tue, Dec 10, 2019 at 3:53 AM ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


On 2019-12-09 09:44, Trey Harris wrote:
 > Signatures are important to Raku.

Trey,

The signatures are very important to the developers.
They only confuse the programmer.

-T


I'm a programmer, not an expert in language design, I don't even have a 
formal education about programming, because when I attended university 
there was no such thing yet.
I started studying Raku in December 2015 and I have to admit that at 
first I didn't understand signatures.So I went on and I read the 
documentation page on signatures. That solved my problem.
I'm talking about the 2015 version of the documentation, which is now 
much improved and I'm writing this just because I think that the people 
who have been writing that documentation for all those years really, 
really deserve to be thanked.

A lot.

--
Fernando Santagata


Hi Fernando,

You make good points.  Please do not misinterpret my issues
with they way the docs are presented as diminishing the work
those people have put into it.  Good grief, I have enough
problems with folks thinks I am calling others dogs.

As to you not having a formal education in programming, I
have a customer how is probably only one of five people
in the country that can do what he does.  It is a treat
to be around him.  And guess what?  He only has a high school
education.  He knows more than PHd's. Your accomplishments
in programming are to be admired.

-T

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Simon Proctor]

On Tue, 10 Dec 2019 at 02:40, ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 07:21, Simon Proctor wrote:
> > I think this does highlight something we probably should document more.
> >
> > How to read signatures. Because it's a *very* powerful part of the
> > language that if you don't understand you're only using it at half
> strength.
> >
> > multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)
> >
> > If not some documentation magic, it's a core part of the language. It
> > tell you this method is called on a defined Str (Str:D:) it takes 2
> > positional arguments which have to be defined Cool types ($needle and
> > $pos) and it returns a Boolean.
> >
> > That is the code as it will be written in the Str Role.
> >
> > I *highly* advise learning how signatures work.
>
>
>
Firstly can I say I admire the fact that you are using Raku in production
on a regular basis.



> Hi Simon,
>
> Did you see the How To post I made on ".contains"?  At
> the bottom of the How To, I take apart the signature
> and explain each part.
>
>
I did. It's pretty good except your understanding of the first part Str:D :

This indicates that this method will be used when it's called on a defined
(D) String instance. The wording you use is a bit weird and it speak to my
beliefe that you don't really get Signatures.



> Do you see anywhere in the docs where how to read
> signatures is explained?  (Don't get any ideas.  The
> signatures should not be there to start with.)
>
>
Apart from here? https://docs.raku.org/type/Signature

I read through this (and some bits on Captures) and was able to get enough
information to give a talk at the Perl Conference in Glasgow in 2018.

Here's the video :
https://www.youtube.com/watch?v=V5rWtKIVmJc=PLQTGmZanuBovAKtE0dDs7rdTUvxnOwvEz

Larry was there, it was rather stressful.


> An aside on the signatures: what is and what is
> not a separator can blow your mind.
>

Not really. comma seperates arguments, colon can be used if you want to
specify information about the calling instance or class.


>
> Do you think it help me or anyone else understand
> how to use ".contains" because I explained the
> "Signature"?  Seriously?
>
>
No, I don't think you NEED the signature to understand contains. I think
that understanding and being able to read signatures CAN help you
understand more about how a subroutine or method works.


> To answer the question, look at all the various
> teaching manuals out there for Raku.  Do you see a
> SINGLE ONE, other that the one I posted, that
> uses the signatures as a teaching tool?
>

I have every single book written about Raku (though of course most are
Perl6) and most of them explain Signatures.

Again I'm not saying that they should be used as a teaching tool, but the
documentation has a lot of uses and it's not just teaching.


>
> And notice that I put the signature explanation
> at the bottom AFTER I explained how to use the
> function (method).  This is akin to the good math
> teachers that run circles around bad math teachers
> in both mechanics and theory by FIRST teaching the
> mechanics and them teaching the theory.  When
> teaching, you should never start with the theory.
> The docs do just that.
>

So when I was first reading the docs I mostly just skipped over the
signatures to get to the rest of the code. I didn't try and understand them
too much "Oh this takes a string, makes sense".

Over time I did start to learn them and that helped me getting better at
programming Perl6.


>
> The "Signatures" in the docs only confuse and often
> have mistakes in them.  Trying to get them corrected
> is a fools errand too.
>
>
How do you mean? If there's a mistake in the signature you can fix it in
the docs and put in a pull request to get it updated.


> The signatures are how the developers talk to each other.
> And judging by the results of their work, it works
> marvelously for them.  This kind of information is
> not appropriate for standard Rakoon that just wants to
> write code.
>
>
Here is where I have to respectfully disagree with you.

Writing Raku code without using Signatures and Multi Methods is like owning
a Jaguar and only driving in first gear. I mean *technically* you can get
where you want to go but you are forgoing a lot of the power of the
language.

I generally write a couple of Raku scripts a week (more if I've got the
time) and they *all* use Signatures. Most use multi methods too.



> You don't need to know how much current affects an LED
> diode to read the time on your digital clock.  This
> is what the signatures are doing.
>
> The Signatures only confuse.  They need to be left to
> the developers.
>
>
This is the problem, until you stop treating signatures as some kind of
weird messaging system only to be used by "the developers" you will be
coding with one hand tied behind you back. You'll also keep asking the same
questions over and over again.

Please take a moment to really try and 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Fernando Santagata]

On Tue, Dec 10, 2019 at 3:53 AM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 09:44, Trey Harris wrote:
> > Signatures are important to Raku.
>
> Trey,
>
> The signatures are very important to the developers.
> They only confuse the programmer.
>
> -T
>

I'm a programmer, not an expert in language design, I don't even have a
formal education about programming, because when I attended university
there was no such thing yet.
I started studying Raku in December 2015 and I have to admit that at first
I didn't understand signatures.So I went on and I read the documentation
page on signatures. That solved my problem.
I'm talking about the 2015 version of the documentation, which is now much
improved and I'm writing this just because I think that the people who have
been writing that documentation for all those years really, really deserve
to be thanked.
A lot.

-- 
Fernando Santagata

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-09 09:44, Trey Harris wrote:
ToddAndMargo, I have watched you on these lists and on GitHub issues for 
years. I’ve engaged a few times but have generally pulled back again, 
always in reaction to the same pattern of behavior:


1. You ask a question about something.

2. It is explained in various ways until you say you get it (and offer 
sample code to show that you do, indeed, seem to get it).


3. You complain the docs do not describe it in a way that you (or 
anyone—you frequently invoke yourself as the avatar of the “ordinary 
programmer” as opposed  to, for example, the “IEEE member”.


4. You’re invited to fix the docs. You do not. (Here’s where I’ve 
engaged more than once: suggesting specific new text and asking if it 
would have clarified for you. You’ve either ignored it or simply replied 
that it would not without further constructive feedback.)


5. And then—a few months later, you bring the very same issue up in 
slightly different form.




And folks say that some of the things I write are offensive.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-09 09:44, Trey Harris wrote:

Signatures are important to Raku.


Trey,

The signatures are very important to the developers.
They only confuse the programmer.

-T

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-09 07:35, Curt Tilmes wrote:
Hmm... Project for someone bored -- We've already got a great Signature 
parser, how about creating a simplified human (HTML) description 
automagically from any Signature, then linking it from the actual 
Signature on each page...



I second that request!

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-09 12:31, Philip Hazelden wrote:



On Mon, Dec 9, 2019 at 1:47 AM ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


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.


This is important: they really, really aren't.

You've offered me a hypothetical in which someone discusses a subject 
that I'm expert in, and I leave confused. In actuality, what happened is 
that I read some text on a subject that I'm no expert in, and I found it 
plainly clear. The difference between "confusing, even to experts" and 
"not confusing, even to non-experts" is profound.


One thing that these situations do have in common is that to a newcomer, 
both situations may be confusing. They would be confused by the 
hypothetical because in the hypothetical, the discussion is genuinely 
confusing. And they may be confused by the actual text, because they may 
lack the background to understand it, even though it's not confusing to 
someone who does have that background. So although there's a profound 
difference between the two situations, a newcomer may experience them 
the same, and may have no way to distinguish the genuinely-confusing 
from the merely above-their-level.


(After all, for someone to reliably predict how an expert would react in 
a situation, they must be able to apply the knowledge and experience of 
an expert. If someone were to say: "well, if I knew more than I know 
now, I would think X; but at my actual current knowledge level, I think 
Y"... that person would sound very confused.)


You refer to yourself as a newbie. And you have repeatedly said that for 
something to be IEEE-ese, it must be confusing not just to newcomers, 
but confusing to experts.


And so I ask: given that you are not an expert, what makes you think you 
can tell the difference between IEEE-ese and and something that merely 
happens to confuse you? How do you distinguish the genuinely-confusing 
from the above-your-level, given that you admit to not having reached 
expert level?


If you say that the documentation is confusing to you, I will accept 
this without question; you are probably the world's leading expert on 
what is confusing to you, and I have no reason to disbelieve you. If you 
say that the documentation is confusing to other newcomers, I may be 
inclined to trust your judgment.


But you repeatedly accuse the Raku documentation of being confusing to 
experts. (You accuse it of being IEEE-ese, and you define IEEE-ese as 
confusing to experts.) I do not trust your judgment on that matter. If 
you think I should, I invite you to say why.


Do you see ANYONE on this mailing list, other than
me asking how to untangle "method contains(Cool:D: |c)",
even though they are "cleanly and precisely" done?
(Well most of the time.)


Indeed, I do not.

To me, this state of affairs suggests that although the documentation is 
confusing to you, it is not confusing to others; thus, not IEEE-ese.


Or they are ignoring them and going elsewhere.

Perhaps to you, this state of affairs suggests something different. If 
so, I can't think what that would be.


Hi Philip,

You make some interesting points.  What you missed exposing
was the presentation of the teaching.

Have you seen any of Larry's responses on this group?  He
takes complex subject apart and makes then extremely to understand.  He 
targets who he is speaking to.  He is

extremely talented at it.

Now those IEEE lectures I wasted money on, I was as much
of an expert, if not more so, then the presenter.  Their
presentations stunk.  I could not figure out heads from
tails.  The information was peer reviewed, absolutely
accurate, and completely useless -- also know as
"IEEE-eese".  IEEE-eese seeks to confuse, not to
communicate.  IEEE is known for it.  You quickly
learn to go elsewhere for information.  So again,
this is back to the way the information is presented.

Let delve into an example from another field.

You are trying to document how to use a cell phone.
Would describing the specification of the internal
processor be appropriate?  Yes and no.

"Yes", if your target audience were fellow engineers.

"No", if it was the user.

This is about determining your target audience.

Now back to Raku.

Take a look at

https://github.com/rakudo/rakudo/commit/696eea2de6e67135b3b574ecb579ede16045ede6

This is where the incorrect information presented on
the Docs for .contains is being corrected (among
other things).  The commit is a fascinating insight
into how the developers are doing their thing.
As a BS in Electrical and Computer 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Philip Hazelden]

(Apologies, forgot to reply all.)

On Mon, Dec 9, 2019 at 1:47 AM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> 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.


This is important: they really, really aren't.

You've offered me a hypothetical in which someone discusses a subject that
I'm expert in, and I leave confused. In actuality, what happened is that I
read some text on a subject that I'm no expert in, and I found it plainly
clear. The difference between "confusing, even to experts" and "not
confusing, even to non-experts" is profound.

One thing that these situations do have in common is that to a newcomer,
both situations may be confusing. They would be confused by the
hypothetical because in the hypothetical, the discussion is genuinely
confusing. And they may be confused by the actual text, because they may
lack the background to understand it, even though it's not confusing to
someone who does have that background. So although there's a profound
difference between the two situations, a newcomer may experience them the
same, and may have no way to distinguish the genuinely-confusing from the
merely above-their-level.

(After all, for someone to reliably predict how an expert would react in a
situation, they must be able to apply the knowledge and experience of an
expert. If someone were to say: "well, if I knew more than I know now, I
would think X; but at my actual current knowledge level, I think Y"... that
person would sound very confused.)

You refer to yourself as a newbie. And you have repeatedly said that for
something to be IEEE-ese, it must be confusing not just to newcomers, but
confusing to experts.

And so I ask: given that you are not an expert, what makes you think you
can tell the difference between IEEE-ese and and something that merely
happens to confuse you? How do you distinguish the genuinely-confusing from
the above-your-level, given that you admit to not having reached expert
level?

If you say that the documentation is confusing to you, I will accept this
without question; you are probably the world's leading expert on what is
confusing to you, and I have no reason to disbelieve you. If you say that
the documentation is confusing to other newcomers, I may be inclined to
trust your judgment.

But you repeatedly accuse the Raku documentation of being confusing to
experts. (You accuse it of being IEEE-ese, and you define IEEE-ese as
confusing to experts.) I do not trust your judgment on that matter. If you
think I should, I invite you to say why.

Do you see ANYONE on this mailing list, other than
> me asking how to untangle "method contains(Cool:D: |c)",
> even though they are "cleanly and precisely" done?
> (Well most of the time.)


Indeed, I do not.

To me, this state of affairs suggests that although the documentation is
confusing to you, it is not confusing to others; thus, not IEEE-ese.

Perhaps to you, this state of affairs suggests something different. If so,
I can't think what that would be.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Trey Harris]

On Mon, Dec 9, 2019 at 10:25 Simon Proctor  wrote:

> I *highly* advise learning how signatures work.
>

This, this, a thousand times this.

ToddAndMargo, I have watched you on these lists and on GitHub issues for
years. I’ve engaged a few times but have generally pulled back again,
always in reaction to the same pattern of behavior:

1. You ask a question about something.

2. It is explained in various ways until you say you get it (and offer
sample code to show that you do, indeed, seem to get it).

3. You complain the docs do not describe it in a way that you (or
anyone—you frequently invoke yourself as the avatar of the “ordinary
programmer” as opposed  to, for example, the “IEEE member”.

4. You’re invited to fix the docs. You do not. (Here’s where I’ve engaged
more than once: suggesting specific new text and asking if it would have
clarified for you. You’ve either ignored it or simply replied that it would
not without further constructive feedback.)

5. And then—a few months later, you bring the very same issue up in
slightly different form.

If, as you implied when suggesting your “grand idea”, you believe you are
capable of writing decent documentation, may I suggest you do so in any
form whatsoever—and then start referring to it *yourself*? Then, perhaps we
could start to have your repetitive complaints be repetitive only in form
and not in substance as well, which would at least constitute some sort of
progress.

But as for the particular issue you’ve homed in on and for which you’ve
used such disparagement: it’s been observed by at least six different
people in the past couple of years (just from searching my mail) that your
eyes seem to slide over signatures, and they seem to offend you (as this
“IEEE” comment reiterates), so you gain no insight from their being there.

Perl 5 is not a language where signatures are precise enough to lend much
insight, so it’s totally unsurprising that its docs do not rely on
signatures beyond extremely schematic ones (“LIST”, “VARIABLE”,
“EXPR”)—which you find easier to understand. Fine.

But Raku, on the other hand, is a language that has pushed its syntax into
signatures at a level that I think might be unique among languages (at
least insofar as how many things can be done with those signatures that
would ordinarily be in the language grammar).

This may seem unPerlish, but it has had the enormous advantage of giving
Raku the Perlish “DWIMminess” while still having an actual specification,
so as to avoid Raku repeating Perl’s issue of being an “empirical language”
that can only be defined by its own implementation. It also allows library
programmers to do language munging in ways that previously often required
complex and fiddly messing around with Perl innards, often in XS or C.

So: Signatures are important to Raku. *Extremely* important. Your demand
that they be swept under the rug and hidden from docs because they’re
cryptic to you  is unreasonable. Learn how Signatures work—books, blog
posts and tutorials are available to explain at least the basics, and the
Signature class’s docs itself is quite readable. Then, and only then, will
you be in a position to judge whether their prominent inclusion in
documentation is an asset or not.

Trey

Re: Raku, docs, help [was: Re: vulgar?]

[Parrot Raiser]

That looks like a great recommendation.

On 12/9/19, Mike Stok  wrote:
>
>> On Dec 9, 2019, at 10:24 AM, Curt Tilmes  wrote:
>>
>> On Mon, Dec 9, 2019 at 10:07 AM ToddAndMargo via perl6-users
>> mailto:perl6-users@perl.org>> wrote:
>> On 2019-12-09 02:00, JJ Merelo wrote:
>> > Other than that, it's clear from the context that it returns a Boolean
>> You still need to change the target audience of the docs
>> from the Developers to the Rakoons.
>>
>> The reference documentation (especially deep inside) is NOT intended for
>> brand new people to the language.
>>
>> They need to start with the introduction, the tutorials, the books, even
>> classes (many are available for free on youtube).
>>
>> The reference documentation is for someone already somewhat familiar with
>> the language, but can't remember the exact calling sequence, or order of
>> arguments, or exactly what gets returned, etc.  The MOST important piece
>> of documentation needed is the precise signature that concisely presents
>> that information.  That is much more important the accompanying verbiage.
>>
>> If one hasn't yet learned what "()" ":D" or "-->" mean, I would kindly
>> suggest that they should review the introductory documentation or some
>> tutorials prior to delving into the detailed technical reference
>> documentation.
>>
>> Curt
>>
>
>
> I have found that https://www.divio.com/blog/documentation/
>  helped me understand more about
> why I have had problems writing documentation.
>
> Mike
>
> --
>
> Mike Stok 
> http://www.stok.ca/~mike/
>
> The "`Stok' disclaimers" apply.
>
>
>
>
>
>
>

Re: Raku, docs, help [was: Re: vulgar?]

[Mike Stok]

> On Dec 9, 2019, at 10:24 AM, Curt Tilmes  wrote:
> 
> On Mon, Dec 9, 2019 at 10:07 AM ToddAndMargo via perl6-users 
> mailto:perl6-users@perl.org>> wrote:
> On 2019-12-09 02:00, JJ Merelo wrote:
> > Other than that, it's clear from the context that it returns a Boolean
> You still need to change the target audience of the docs
> from the Developers to the Rakoons.
> 
> The reference documentation (especially deep inside) is NOT intended for 
> brand new people to the language.
> 
> They need to start with the introduction, the tutorials, the books, even 
> classes (many are available for free on youtube).
> 
> The reference documentation is for someone already somewhat familiar with the 
> language, but can't remember the exact calling sequence, or order of 
> arguments, or exactly what gets returned, etc.  The MOST important piece of 
> documentation needed is the precise signature that concisely presents that 
> information.  That is much more important the accompanying verbiage.
> 
> If one hasn't yet learned what "()" ":D" or "-->" mean, I would kindly 
> suggest that they should review the introductory documentation or some 
> tutorials prior to delving into the detailed technical reference 
> documentation.
> 
> Curt
> 


I have found that https://www.divio.com/blog/documentation/ 
 helped me understand more about why 
I have had problems writing documentation. 

Mike

-- 

Mike Stok 
http://www.stok.ca/~mike/

The "`Stok' disclaimers" apply.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Curt Tilmes]

On Mon, Dec 9, 2019 at 10:29 AM Simon Proctor 
wrote:

> I think this does highlight something we probably should document more.
>
> How to read signatures. Because it's a *very* powerful part of the
> language that if you don't understand you're only using it at half strength.
>
> multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)
>
> If not some documentation magic, it's a core part of the language. It tell
> you this method is called on a defined Str (Str:D:) it takes 2 positional
> arguments which have to be defined Cool types ($needle and $pos) and it
> returns a Boolean.
>
> That is the code as it will be written in the Str Role.
>
> I *highly* advise learning how signatures work.
>

Hmm... Project for someone bored -- We've already got a great Signature
parser, how about creating a simplified human (HTML) description
automagically from any Signature, then linking it from the actual Signature
on each page...

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Curt Tilmes]

On Mon, Dec 9, 2019 at 10:07 AM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 02:00, JJ Merelo wrote:
> > Other than that, it's clear from the context that it returns a Boolean
> You still need to change the target audience of the docs
> from the Developers to the Rakoons.
>

The reference documentation (especially deep inside) is NOT intended for
brand new people to the language.

They need to start with the introduction, the tutorials, the books, even
classes (many are available for free on youtube).

The reference documentation is for someone already somewhat familiar with
the language, but can't remember the exact calling sequence, or order of
arguments, or exactly what gets returned, etc.  The MOST important piece of
documentation needed is the precise signature that concisely presents that
information.  That is much more important the accompanying verbiage.

If one hasn't yet learned what "()" ":D" or "-->" mean, I would kindly
suggest that they should review the introductory documentation or some
tutorials prior to delving into the detailed technical reference
documentation.

Curt

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Simon Proctor]

I think this does highlight something we probably should document more.

How to read signatures. Because it's a *very* powerful part of the language
that if you don't understand you're only using it at half strength.

multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)

If not some documentation magic, it's a core part of the language. It tell
you this method is called on a defined Str (Str:D:) it takes 2 positional
arguments which have to be defined Cool types ($needle and $pos) and it
returns a Boolean.

That is the code as it will be written in the Str Role.

I *highly* advise learning how signatures work.

On Mon, 9 Dec 2019 at 14:54, ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-09 02:00, JJ Merelo wrote:
> > Other than that, it's clear from the context that it returns a Boolean
>
> JJ,
>
> You are a teacher.  In technical writing, you NEVER leave
> anything to "Context", even if it is "intuitively
> obvious to the student and left for him to figure out
> on his own".
>
> If you meant until the commit gets in place just
> go by context, then I apologize for misinterpreting
> you.
>
> The commit looks nice.  I would have liked it if they
> had used the "the needle and the haystack" instead of
> just "needle" (what am I poking?), but I can live
> with what they came up with.
>
> multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)
>
> In the above, it is not real obvious to the Riff-Raff
> (me), who is not have developer level ledge, that the
> "Str:D" in inside the parenthesis, but instead feeding
> the method.  You have to get use to the cryptography.
>
> You still need to change the target audience of the docs
> from the Developers to the Rakoons.
>
> -T
>


-- 
Simon Proctor
Cognoscite aliquid novum cotidie

http://www.khanate.co.uk/

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-09 02:00, JJ Merelo wrote:

Other than that, it's clear from the context that it returns a Boolean


JJ,

You are a teacher.  In technical writing, you NEVER leave
anything to "Context", even if it is "intuitively
obvious to the student and left for him to figure out
on his own".

If you meant until the commit gets in place just
go by context, then I apologize for misinterpreting
you.

The commit looks nice.  I would have liked it if they
had used the "the needle and the haystack" instead of
just "needle" (what am I poking?), but I can live
with what they came up with.

multi method contains(Str:D: Cool:D $needle, Cool:D $pos --> Bool:D)

In the above, it is not real obvious to the Riff-Raff
(me), who is not have developer level ledge, that the
"Str:D" in inside the parenthesis, but instead feeding
the method.  You have to get use to the cryptography.

You still need to change the target audience of the docs
from the Developers to the Rakoons.

-T

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[JJ Merelo]

El lun., 9 dic. 2019 a las 2:48, ToddAndMargo via perl6-users (<
perl6-users@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

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

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
tells you the result of the method.  (Hidden by the
IEEE-eese and "is intuitively obvious and left up
to the student to figure out for himself.")

But for the purpose of the rest of my letter, lets say it is
correct.

Okay here goes.  In technical writing, there are usually three
different targets for your audience.

1) your peers.  A civil Engineer to another civil engineer.
In your case other advanced developer level folks.

2) to someone is a parallel field.   A mechanical engineer to
an electrical engineer.  A Raku programmer to a C++ programmer.
(I do talk to C and C++ programmers on occasion.  They are great with 
explaining system calls)


3) to those either new to the field or outside the field, general public 
so to speak.  An allopath explaining an

injury to a patient.  In your case, explaining how a Raku
function works to me, as I am a beginner.

So, you have to ask, which one of the three were these
documents in general and "method contains(Cool:D: |c)"
in specific targets at?

1) follow developers and advanced users that don't need
them and have their own spec's?

2) to someone in a parallel programming field?  They
will never figure them out and just ignore them
and think you are a nut.

3) to newbies, such as myself.  Or even refreshers
to regular users?  They can't understand them.

This is where the documentation falls on its face.
The TARGET audience need to be 3 above not 1.
Perl5's Perldocs actually manages to both target
both 1, 2 and 3 above.

Ask yourself, do you see ANY tutorial on Raku that uses
the "method contains(Cool:D: |c)" jargon and explains
them?  Do you see ANYONE EVER using "method contains
(Cool:D: |c)" to explain things EVER?

Do you see ANYONE on this mailing list, other than
me asking how to untangle "method contains(Cool:D: |c)",
even though they are "cleanly 

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[JJ Merelo]

El sáb., 7 dic. 2019 a las 17:24, Philip Hazelden (<
philip.hazel...@gmail.com>) escribió:

> On Sat, Dec 7, 2019 at 12:04 PM ToddAndMargo via perl6-users <
> perl6-users@perl.org> wrote:
>
>> On 2019-12-07 03:00, Tom Browder wrote:
>> > Forgot to reply to all.
>> >
>> > -- Forwarded message -
>> > From: *Tom Browder* > tom.brow...@gmail.com>>
>> > Date: Sat, Dec 7, 2019 at 04:58
>> > Subject: Raku, docs, help [was: Re: vulgar?]
>> > To: ToddAndMargo mailto:toddandma...@zoho.com>>
>> >
>> >
>> > On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users
>> > mailto:perl6-users@perl.org>> wrote:
>> >
>> > On 2019-12-06 18:34, Tom Browder wrote:
>> >  > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
>> >  > mailto:perl6-users@perl.org>> wrote:
>> >  >>
>> >  >> On 2019-12-06 04:19, Tom Browder wrote:
>> >
>> >
>> > Todd, I was a bit harsh in my last reply, but I do see a huge
>> difference
>> > between a bug report and a PR. In the PR, you have to show exactly what
>> > the wording should be in its entire context, while in the bug report
>> > your suggestions are less in context. To me, that automatically
>> > increases the friction in the  conversation.
>> >
>> > Some other points about help via comms other than email that are
>> > valuable to me:
>> >
>> > 1. when using IRC, it is easy to put chunks of real code into a Github
>> > gist. That way everyone can see it and discuss it by line number or
>> > other reference
>> >
>> > 2. on the #raku channels, there is a built-in REPL so all can see your
>> > code chunks in action
>> >
>> > Finally, I really don't have any more good arguments about your
>> > discontent with the docs, but I leave you with these words about my
>> > experience here:
>> >
>> > Any help you can contribute to the docs will usually be greatly
>> > appreciated, but you are better off to start in small bits, correcting
>> > typos, improving grammar, etc.
>> > And I agree with you that much of the descriptions are in "IEEE-ese."
>> To
>> > help with that I have added several "cookbook" examples in such areas,
>> > as much to help me as to help others. Given the way I've seen you
>> > operate I think that adding better examples from your "keepers" would
>> be
>> > very useful.
>> > > Merry Christmas!
>> >
>> > -Tom
>> >
>> > P.S. One more thing about Perl vs. Raku docs: I believe over the years
>> > there has been much money applied to the Perl infrastructure by
>> > commercial users of Perl, especially in the early days of the Internet.
>> > On the other hand, I believe Raku has had comparatively little
>> > commercial support and has had to rely on those unpaid people who love
>> > the language and its community and who freely donate their time to its
>> > improvement. It can only get better, but maybe not with quite as steep
>> a
>> > growth curve as Perl has had.
>>
>> Hi Tom,
>>
>> Seems I was a bit blunt with my criticism of the docs and
>> hurt a lot of feelings.
>>
>> Perl 5's docs are a good example of Kaisen (constant change)
>> as is the Linux kernel and Fedora. Raku itself is also
>> a masterpiece of Kaisen too.  The docs are not though, but
>> maybe they will catch up in the future.  Probably the
>> developers are too busy doing their magic (that was
>> a compliment -- not one get their nickers in a twist).
>>
>> What would be nice is if there was place to put suggestions
>> as to improvements to the docs.
>>
>> Guys like me a perfect for such as we do not know what
>> it is suppose to say and don't see what we expect to see.
>>
>> An example of IEEE-eese would be
>> https://docs.raku.org/routine/contains
>>
>>  method contains(Cool:D: |c)
>>
>> And
>>
>> Coerces the invocant Str, and calls Str.contains
>> on it. Please refer to that version of the method
>> for arguments and general syntax.
>>
>> Must win the IEEE-eese award for the week.  I have no
>> idea what was just said.  What the dickens is `|c`
>> anyway?
>>
>
> 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
>

Created issue 3112 https://github.com/Raku/doc/issues/3112, fixed and
redeployed. Thanks for the report. https://docs.raku.org/routine/contains

Cheers

JJ

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[Philip Hazelden]

On Sat, Dec 7, 2019 at 12:04 PM ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-07 03:00, Tom Browder wrote:
> > Forgot to reply to all.
> >
> > -- Forwarded message -
> > From: *Tom Browder* mailto:tom.brow...@gmail.com
> >>
> > Date: Sat, Dec 7, 2019 at 04:58
> > Subject: Raku, docs, help [was: Re: vulgar?]
> > To: ToddAndMargo mailto:toddandma...@zoho.com>>
> >
> >
> > On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users
> > mailto:perl6-users@perl.org>> wrote:
> >
> > On 2019-12-06 18:34, Tom Browder wrote:
> >  > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
> >  > mailto:perl6-users@perl.org>> wrote:
> >  >>
> >  >> On 2019-12-06 04:19, Tom Browder wrote:
> >
> >
> > Todd, I was a bit harsh in my last reply, but I do see a huge difference
> > between a bug report and a PR. In the PR, you have to show exactly what
> > the wording should be in its entire context, while in the bug report
> > your suggestions are less in context. To me, that automatically
> > increases the friction in the  conversation.
> >
> > Some other points about help via comms other than email that are
> > valuable to me:
> >
> > 1. when using IRC, it is easy to put chunks of real code into a Github
> > gist. That way everyone can see it and discuss it by line number or
> > other reference
> >
> > 2. on the #raku channels, there is a built-in REPL so all can see your
> > code chunks in action
> >
> > Finally, I really don't have any more good arguments about your
> > discontent with the docs, but I leave you with these words about my
> > experience here:
> >
> > Any help you can contribute to the docs will usually be greatly
> > appreciated, but you are better off to start in small bits, correcting
> > typos, improving grammar, etc.
> > And I agree with you that much of the descriptions are in "IEEE-ese." To
> > help with that I have added several "cookbook" examples in such areas,
> > as much to help me as to help others. Given the way I've seen you
> > operate I think that adding better examples from your "keepers" would be
> > very useful.
> > > Merry Christmas!
> >
> > -Tom
> >
> > P.S. One more thing about Perl vs. Raku docs: I believe over the years
> > there has been much money applied to the Perl infrastructure by
> > commercial users of Perl, especially in the early days of the Internet.
> > On the other hand, I believe Raku has had comparatively little
> > commercial support and has had to rely on those unpaid people who love
> > the language and its community and who freely donate their time to its
> > improvement. It can only get better, but maybe not with quite as steep a
> > growth curve as Perl has had.
>
> Hi Tom,
>
> Seems I was a bit blunt with my criticism of the docs and
> hurt a lot of feelings.
>
> Perl 5's docs are a good example of Kaisen (constant change)
> as is the Linux kernel and Fedora. Raku itself is also
> a masterpiece of Kaisen too.  The docs are not though, but
> maybe they will catch up in the future.  Probably the
> developers are too busy doing their magic (that was
> a compliment -- not one get their nickers in a twist).
>
> What would be nice is if there was place to put suggestions
> as to improvements to the docs.
>
> Guys like me a perfect for such as we do not know what
> it is suppose to say and don't see what we expect to see.
>
> An example of IEEE-eese would be
> https://docs.raku.org/routine/contains
>
>  method contains(Cool:D: |c)
>
> And
>
> Coerces the invocant Str, and calls Str.contains
> on it. Please refer to that version of the method
> for arguments and general syntax.
>
> Must win the IEEE-eese award for the week.  I have no
> idea what was just said.  What the dickens is `|c`
> anyway?
>

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 har

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-07 03:59, ToddAndMargo via perl6-users wrote:

On 2019-12-07 03:00, Tom Browder wrote:

Forgot to reply to all.

-- Forwarded message -
From: *Tom Browder* <mailto:tom.brow...@gmail.com>>

Date: Sat, Dec 7, 2019 at 04:58
Subject: Raku, docs, help [was: Re: vulgar?]
To: ToddAndMargo mailto:toddandma...@zoho.com>>


On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


    On 2019-12-06 18:34, Tom Browder wrote:
 > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
 > mailto:perl6-users@perl.org>> wrote:
 >>
 >> On 2019-12-06 04:19, Tom Browder wrote:


Todd, I was a bit harsh in my last reply, but I do see a huge 
difference between a bug report and a PR. In the PR, you have to show 
exactly what the wording should be in its entire context, while in the 
bug report your suggestions are less in context. To me, that 
automatically increases the friction in the  conversation.


Some other points about help via comms other than email that are 
valuable to me:


1. when using IRC, it is easy to put chunks of real code into a Github 
gist. That way everyone can see it and discuss it by line number or 
other reference


2. on the #raku channels, there is a built-in REPL so all can see your 
code chunks in action


Finally, I really don't have any more good arguments about your 
discontent with the docs, but I leave you with these words about my 
experience here:


Any help you can contribute to the docs will usually be greatly 
appreciated, but you are better off to start in small bits, correcting 
typos, improving grammar, etc.
And I agree with you that much of the descriptions are in "IEEE-ese." 
To help with that I have added several "cookbook" examples in such 
areas, as much to help me as to help others. Given the way I've seen 
you operate I think that adding better examples from your "keepers" 
would be very useful.

> Merry Christmas!

-Tom

P.S. One more thing about Perl vs. Raku docs: I believe over the years 
there has been much money applied to the Perl infrastructure by 
commercial users of Perl, especially in the early days of the 
Internet. On the other hand, I believe Raku has had comparatively 
little commercial support and has had to rely on those unpaid people 
who love the language and its community and who freely donate their 
time to its improvement. It can only get better, but maybe not with 
quite as steep a growth curve as Perl has had.


Hi Tom,

Seems I was a bit blunt with my criticism of the docs and
hurt a lot of feelings.

Perl 5's docs are a good example of Kaisen (constant change)
as is the Linux kernel and Fedora. Raku itself is also
a masterpiece of Kaisen too.  The docs are not though, but
maybe they will catch up in the future.  Probably the
developers are too busy doing their magic (that was
a compliment -- not one get their nickers in a twist).

What would be nice is if there was place to put suggestions
as to improvements to the docs.

Guys like me a perfect for such as we do not know what
it is suppose to say and don't see what we expect to see.

An example of IEEE-eese would be
https://docs.raku.org/routine/contains

     method contains(Cool:D: |c)

And

    Coerces the invocant Str, and calls Str.contains
    on it. Please refer to that version of the method
    for arguments and general syntax.

Must win the IEEE-eese award for the week.  I have no
idea what was just said.  What the dickens is `|c`
anyway?

And I know how to use contains!  I use it a ton.  If
I had relied on the doc, I'd be in the dark.

I have only used the #raku channel a few time.  I used
the #perl6 one a lot.  Seems the the #raku channel
has some powerful new toys!  The channels are wonderful
if you can catch someone of newbie duty.

I have been using the REPL utility a tons since I found
out about it yesterday.  What a marvelous tool!  I hate
to ask how long it has been around and I did not know
about it.  It even takes subs!

-T

Did you catch my WinPopUps post?


You know what, one thing I am unclear about with the docs
is "who is the intended audience?"

Is it the users (advanced or new), the developers, or
both?

If I am not mistaken, the developers have their own
specifications.  If I am correct, the docs need
to be redirected toward to user.

Re: Fwd: Raku, docs, help [was: Re: vulgar?]

[ToddAndMargo via perl6-users]

On 2019-12-07 03:00, Tom Browder wrote:

Forgot to reply to all.

-- Forwarded message -
From: *Tom Browder* mailto:tom.brow...@gmail.com>>
Date: Sat, Dec 7, 2019 at 04:58
Subject: Raku, docs, help [was: Re: vulgar?]
To: ToddAndMargo mailto:toddandma...@zoho.com>>


On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users 
mailto:perl6-users@perl.org>> wrote:


On 2019-12-06 18:34, Tom Browder wrote:
 > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
 > mailto:perl6-users@perl.org>> wrote:
 >>
 >> On 2019-12-06 04:19, Tom Browder wrote:


Todd, I was a bit harsh in my last reply, but I do see a huge difference 
between a bug report and a PR. In the PR, you have to show exactly what 
the wording should be in its entire context, while in the bug report 
your suggestions are less in context. To me, that automatically 
increases the friction in the  conversation.


Some other points about help via comms other than email that are 
valuable to me:


1. when using IRC, it is easy to put chunks of real code into a Github 
gist. That way everyone can see it and discuss it by line number or 
other reference


2. on the #raku channels, there is a built-in REPL so all can see your 
code chunks in action


Finally, I really don't have any more good arguments about your 
discontent with the docs, but I leave you with these words about my 
experience here:


Any help you can contribute to the docs will usually be greatly 
appreciated, but you are better off to start in small bits, correcting 
typos, improving grammar, etc.
And I agree with you that much of the descriptions are in "IEEE-ese." To 
help with that I have added several "cookbook" examples in such areas, 
as much to help me as to help others. Given the way I've seen you 
operate I think that adding better examples from your "keepers" would be 
very useful.

> Merry Christmas!

-Tom

P.S. One more thing about Perl vs. Raku docs: I believe over the years 
there has been much money applied to the Perl infrastructure by 
commercial users of Perl, especially in the early days of the Internet. 
On the other hand, I believe Raku has had comparatively little 
commercial support and has had to rely on those unpaid people who love 
the language and its community and who freely donate their time to its 
improvement. It can only get better, but maybe not with quite as steep a 
growth curve as Perl has had.


Hi Tom,

Seems I was a bit blunt with my criticism of the docs and
hurt a lot of feelings.

Perl 5's docs are a good example of Kaisen (constant change)
as is the Linux kernel and Fedora. Raku itself is also
a masterpiece of Kaisen too.  The docs are not though, but
maybe they will catch up in the future.  Probably the
developers are too busy doing their magic (that was
a compliment -- not one get their nickers in a twist).

What would be nice is if there was place to put suggestions
as to improvements to the docs.

Guys like me a perfect for such as we do not know what
it is suppose to say and don't see what we expect to see.

An example of IEEE-eese would be
https://docs.raku.org/routine/contains

method contains(Cool:D: |c)

And

   Coerces the invocant Str, and calls Str.contains
   on it. Please refer to that version of the method
   for arguments and general syntax.

Must win the IEEE-eese award for the week.  I have no
idea what was just said.  What the dickens is `|c`
anyway?

And I know how to use contains!  I use it a ton.  If
I had relied on the doc, I'd be in the dark.

I have only used the #raku channel a few time.  I used
the #perl6 one a lot.  Seems the the #raku channel
has some powerful new toys!  The channels are wonderful
if you can catch someone of newbie duty.

I have been using the REPL utility a tons since I found
out about it yesterday.  What a marvelous tool!  I hate
to ask how long it has been around and I did not know
about it.  It even takes subs!

-T

Did you catch my WinPopUps post?

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-07 01:42, Elizabeth Mattijsen wrote:

Well, for one you seem to have missed the fact that RT is no longer used to 
report bugs in Rakudo.  So I'd argue, yes, you do appear*not*  to know how to 
report bugs.



I haven't reported any in a while to Perl 6, so I you
won't find any of my stuff on the new reporter.

I take that back.  I did break my rule and report one
over here:

zef requires git
https://github.com/rakudo/star/issues/145

Round and Round and Round we went.  Coke finally
took it seriously.  Learned my lesson though.

As far as reporting bugs, I report bazillions of them
all over the place.

Seems to me I hurt a lot of feelings by slamming the
poor documentation.  It is not my intention.  I
do very much value the help you and other have given
me in the past.

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-07 01:37, Elizabeth Mattijsen wrote:

On 7 Dec 2019, at 01:17, ToddAndMargo via perl6-users  
wrote:
Oh and not to beat a dead horse, but perl 5's perldocs
wipes raku's docs face.


Now, that is what *I* call vulgar.


Interesting.  It means it outdoes you by quiet a bit.
Another way of sayig it would be "left you in its
dust".  I don't even want to know what you interpreted
it as.  Maybe there is some translation peculiarity?





So it is possible to write
a doc reference that serves both the developer and
the user.  Raku just does not want to.


Raku is a collection of volunteers.  You seem to be a user of all the goodies 
that Raku brings.  Yet you appear to refuse to contribute to the project.  So 
I'd argue you should be glad at what you get.



How do you figure?

I just don't have the time to put up with the guard dog.
I did try a bit ago and gave up.  You have to argue and
argue and argue.

Other parts, I am happy to contribute were I can. I
am light years behind you, so if you mean development level,
probably not in this lifetime would I catch up to you.

Did I hurt your feeling by saying the docs stink?
Compared to Perl 5's, Perl 6's are really are awful.

Fwd: Raku, docs, help [was: Re: vulgar?]

[Tom Browder]

Forgot to reply to all.

-- Forwarded message -
From: Tom Browder 
Date: Sat, Dec 7, 2019 at 04:58
Subject: Raku, docs, help [was: Re: vulgar?]
To: ToddAndMargo 


On Fri, Dec 6, 2019 at 23:23 ToddAndMargo via perl6-users <
perl6-users@perl.org> wrote:

> On 2019-12-06 18:34, Tom Browder wrote:
> > On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
> >  wrote:
> >>
> >> On 2019-12-06 04:19, Tom Browder wrote:


Todd, I was a bit harsh in my last reply, but I do see a huge difference
between a bug report and a PR. In the PR, you have to show exactly what the
wording should be in its entire context, while in the bug report your
suggestions are less in context. To me, that automatically increases the
friction in the  conversation.

Some other points about help via comms other than email that are valuable
to me:

1. when using IRC, it is easy to put chunks of real code into a Github
gist. That way everyone can see it and discuss it by line number or other
reference

2. on the #raku channels, there is a built-in REPL so all can see your code
chunks in action

Finally, I really don't have any more good arguments about your discontent
with the docs, but I leave you with these words about my experience here:

Any help you can contribute to the docs will usually be greatly
appreciated, but you are better off to start in small bits, correcting
typos, improving grammar, etc.
And I agree with you that much of the descriptions are in "IEEE-ese." To
help with that I have added several "cookbook" examples in such areas, as
much to help me as to help others. Given the way I've seen you operate I
think that adding better examples from your "keepers" would be very useful.

Merry Christmas!

-Tom

P.S. One more thing about Perl vs. Raku docs: I believe over the years
there has been much money applied to the Perl infrastructure by commercial
users of Perl, especially in the early days of the Internet. On the other
hand, I believe Raku has had comparatively little commercial support and
has had to rely on those unpaid people who love the language and its
community and who freely donate their time to its improvement. It can only
get better, but maybe not with quite as steep a growth curve as Perl has
had.

Re: vulgar?

[Elizabeth Mattijsen]

> On 7 Dec 2019, at 00:30, ToddAndMargo via perl6-users  
> wrote:
> What makes you think I do not know how to use
> the bug reporting system?

Well, for one you seem to have missed the fact that RT is no longer used to 
report bugs in Rakudo.  So I'd argue, yes, you do appear *not* to know how to 
report bugs.


> I have reported such things before.  It is like
> spitting in the wind.

Again, yet you appear to use Raku, built and maintained by developers, but you 
act like a paying customer complaining about the help desk.  You get what you 
pay for.  If you do not report bugs, the bugs will surely stay.  If you *do* 
report bugs, then *maybe* they'll get fixed.  That's the reality.  Deal with it.



> The IEEE-eese stays.
> It is the culture and they are not changing it.

Again, the "they" you are referring to, is a community of *VOLUNTEERS*.


> If you have hours and hours and hours to spend
> arguing with the guard dog, you can get minor
> changes made.

Have you considered the *possibility* that what you want, may not be such a 
good thing after all??


> If you post to them an example that
> your think makes things more understandable, they
> tell you to learn the IEEE-eese.  I gave up.

I don't think you have.

Re: vulgar?

[Elizabeth Mattijsen]

> On 7 Dec 2019, at 01:17, ToddAndMargo via perl6-users  
> wrote:
> Oh and not to beat a dead horse, but perl 5's perldocs
> wipes raku's docs face.

Now, that is what *I* call vulgar.


> So it is possible to write
> a doc reference that serves both the developer and
> the user.  Raku just does not want to.

Raku is a collection of volunteers.  You seem to be a user of all the goodies 
that Raku brings.  Yet you appear to refuse to contribute to the project.  So 
I'd argue you should be glad at what you get.

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-06 18:34, Tom Browder wrote:

On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
 wrote:


On 2019-12-06 04:19, Tom Browder wrote:

Todd, arguing via email is almost guaranteed to be fruitless. You need
to learn to use Github and make pull requests (PRs)  for the EXACT
changes you think should be made to the docs.

...

Hi Tom,
What makes you think I do not know how to use
the bug reporting system?


Todd, a Pull Request is NOT a bug report. YOU get a Github account,
and YOU fork the Raku docs repository and YOU either make changes on
your Github fork via a browser or, better, clone your fork onto your
favorite local host and make desired changes there. Then, when you are
satisfied, you commit your changes, push them to your Github account,
and then submit a Pull Request which lets a member either approve your
changes or suggest something else.


Hi Tom,

I do have a GitHub account and I do occasional use it on
other projects.  And a Pull request and an Enhancement
request on a Bagzilla are a difference without a distinction.

Some projects take requests gracefully and some do not.
Raku does not.  LibreOffice does not either. Fedora
is wonderful about it.

Here is an example of a LibreOffice request opened by me
years ago.  They keep ignoring and ignoring the request
no matter how may people sign on.  Commend 45 rips them
to no end.
https://bugs.documentfoundation.org/show_bug.cgi?id=33173#c45



I wish you could get over your aversion to reading what we have in the
docs.


I do read them.  If I can get past the IEEE-eese, then
they are useful.  Usually, they are so poorly written
that I have to google around or ask elsewhere to find
an answer. They are really bad compared to Perl 5's docs.


For example, one of the first things you should learned, a long
time ago was about the REPL which you just found about today.


REPL is a wonderful tool.  I wish I'd learned about it earlier.
The few times Larry Wall has answered some of my questions,
he has used

$ alias p6
alias p6='perl6 -e'

to show me examples.  If Larry did it that way, I never thought
of doing it another way.

REPL sure gets you out of quoting hell!




Also, if you would find an IRC client and join channel #raku, you
could ask questions AND try out code online while people are watching.


I am on that too at times.  There are several that are on Newbie duty 
that are real mensches.




I realize we all don't search for things or learn them the same way,
but goodness knows the folks who have been helping you on this mailing
list have shown great patience in the face of a lot of criticism
without a lot of constructive help from you in return.


My only criticism is the documentations and I stand by that.
Don't let it hurt your feelings.  It is not intended too.

The people on this group are wonderful.  And when I can I do try to help 
other people.  Plus I ALWAYS feedback to others

who help me and ALWAYS thank them.  As I learn, I will be
able to help more and more.  What goes around comes around.

I really dislike it when you help someone and they never
respond back, so you don't know if your were accurate or not.

Before coming to Raku, I started with Perl 5.  Their
documentation is wonderful.  Their NewGroup is also
very helpful, though much more "course" that this mailing
list.

When I programed in P5, I had a web windows open to their
docs.  Very easy to deal with.  Not so with P6, but I
am beating a dead horse again.

Chuckle,  they are really "grouchy" about Raku.  They
think is is Java.  (P5's subs are a living nightmare.)
Where I like P5, I ADORE Raku. The very moment I saw
P6's sub declarations, I dropped P5 and forced myself
into P6.

Perl (either) is not my first programming language.
I write in "Top Down" and live and die with modules.
Raku is well written for my way of programming.
I adore it.

Did you see my write up on hashes?  JJ caught a booboo.
You catch any?

I am currently working on a module for Windows popups.
I have already posted here my simple Msg substitute.
I will post back when I get it finished.  It will be
a while though.

-T





Best regards,

-Tom




--
~~
Computers are like air conditioners.
They malfunction when you open windows
~~

Re: vulgar?

[Tom Browder]

On Fri, Dec 6, 2019 at 17:31 ToddAndMargo via perl6-users
 wrote:
>
> On 2019-12-06 04:19, Tom Browder wrote:
> > Todd, arguing via email is almost guaranteed to be fruitless. You need
> > to learn to use Github and make pull requests (PRs)  for the EXACT
> > changes you think should be made to the docs.
...
> Hi Tom,
> What makes you think I do not know how to use
> the bug reporting system?

Todd, a Pull Request is NOT a bug report. YOU get a Github account,
and YOU fork the Raku docs repository and YOU either make changes on
your Github fork via a browser or, better, clone your fork onto your
favorite local host and make desired changes there. Then, when you are
satisfied, you commit your changes, push them to your Github account,
and then submit a Pull Request which lets a member either approve your
changes or suggest something else.

I wish you could get over your aversion to reading what we have in the
docs. For example, one of the first things you should learned, a long
time ago was about the REPL which you just found about today.

The REPL is mentioned in several places, one place a person new to the
language wold be looking:

  On the home page (raku.org), select the "Download" menu tab on the top row.
  In the right column, in the second pane entitled "Introductory
Material", select the "Raku Guide"
  In the "Table of Contents" in the left column, select "1.4, Running Raku Code"

Granted, it isn't shouted out, but if you had looked around the
various pages you would have found it.

Also, if you would find an IRC client and join channel #raku, you
could ask questions AND try out code online while people are watching.

I realize we all don't search for things or learn them the same way,
but goodness knows the folks who have been helping you on this mailing
list have shown great patience in the face of a lot of criticism
without a lot of constructive help from you in return.

Best regards,

-Tom

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-06 15:30, ToddAndMargo via perl6-users wrote:

On 2019-12-06 04:19, Tom Browder wrote:

Todd, arguing via email is almost guaranteed to be fruitless. You need
to learn to use Github and make pull requests (PRs)  for the EXACT
changes you think should be made to the docs.


Hi Tom,

What makes you think I do not know how to use
the bug reporting system?

I have reported such things before.  It is like
spitting in the wind.  The IEEE-eese stays.
It is the culture and they are not changing it.
If you have hours and hours and hours to spend
arguing with the guard dog, you can get minor
changes made.  If you post to them an example that
your think makes things more understandable, they
tell you to learn the IEEE-eese.  I gave up.

-T


Oh and not to beat a dead horse, but perl 5's perldocs
wipes raku's docs face.  So it is possible to write
a doc reference that serves both the developer and
the user.  Raku just does not want to.

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-06 04:19, Tom Browder wrote:

Todd, arguing via email is almost guaranteed to be fruitless. You need
to learn to use Github and make pull requests (PRs)  for the EXACT
changes you think should be made to the docs.


Hi Tom,

What makes you think I do not know how to use
the bug reporting system?

I have reported such things before.  It is like
spitting in the wind.  The IEEE-eese stays.
It is the culture and they are not changing it.
If you have hours and hours and hours to spend
arguing with the guard dog, you can get minor
changes made.  If you post to them an example that
your think makes things more understandable, they
tell you to learn the IEEE-eese.  I gave up.

-T

Re: vulgar?

[Parrot Raiser]

It has been said that any sound the human voice can utter is rude in
some language.

It is also rather obvious that people who acquire second and
subsequent languages informally tend to learn a very high proportion
of "taboo" expressions. (Possibly because in many cases their
principal source is military, and Mother's not around to say "No dear,
we don't say that".)

Even the most rigourous definitions are made more comprehensible by
clear, correct, examples, but any attempt to make technical writing
anything but utterly moribund encounters a barrage of managerial and
editorial flak, (at least in my experience). I think it's a residue of
academics' attempts to achieve profundity through obscurity.  If it's
clear, it can't be important, (and won't attract grants.)

Project teams tend to acquire a specialised jargon from shared
experiences, which speeds internal communication, but (sometimes
deliberately) excludes non-members. Given that, and an unusually deep
acquaintance with the topic, the people who know most about a piece of
software are probably the least suitable to document it for general
users. They've forgotten what other people don't know. (Their "unknown
unknowns".)

Re: vulgar?

[Elizabeth Mattijsen]

> On 6 Dec 2019, at 13:19, Tom Browder  wrote:
> Note the Perl docs have been refined, by experts, since the late
> 1980s, while the Raku docs have been expanding, by individuals with
> itches to scratch and varying talents, for probably much less than 20
> years.

The very first commit (by Moritz Lenz++) to the doc repository is from:

Date:   Fri Jun 8 17:43:57 2012 +0200

so I would argue, 7.5 years at most!

Re: vulgar?

[Tom Browder]

On Fri, Dec 6, 2019 at 05:04 ToddAndMargo via perl6-users
 wrote:
> I have uncovered several booboos in the docs.  I find them
> to not be all that accurate either.  I really don't trust
> them.  And since they are written in IEEE-eese, booboos are
> really hard to spot.
...
> And when I do spot them, it is really hard to get a fix
> past the bug reporter's guard dog.  You have to argue and
> argue and argue.  I don't report a lot of bugs to them
> anymore do to this. It is far more effective to report
> them here.

Todd, arguing via email is almost guaranteed to be fruitless. You need
to learn to use Github and make pull requests (PRs)  for the EXACT
changes you think should be made to the docs. With apologies to you,
sometimes it is difficult for a simple man like me to help when your
code is too complex ("golfed") or incomplete to sort out easily in
your email. Your "keepers" could be a PR for changes to the docs.

Note the Perl docs have been refined, by experts, since the late
1980s, while the Raku docs have been expanding, by individuals with
itches to scratch and varying talents, for probably much less than 20
years.

Best regards,

-Tom

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-06 01:24, Laurent Rosenfeld via perl6-users wrote:
Manual pages (which are reference material) and tutorials are two very 
different kinds of writing. Manual pages are usually more difficult to 
understand than (good) tutorials, because they have to be *very 
accurate* and as complete as possible (if not exhaustive), while 
tutorials can leave out some intricacies or gory details.




Hi Laurent,

Definition:  IEEE-eese

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.

I have uncovered several booboos in the docs.  I find them
to not be all that accurate either.  I really don't trust
them.  And since they are written in IEEE-eese, booboos are
really hard to spot.

And guys like me are the perfect ones to spot such booboos
as we don't know what to expect and don't think we see what
we see. IEEE-eese put a clamp on that.

And when I do spot them, it is really hard to get a fix
past the bug reporter's guard dog.  You have to argue and
argue and argue.  I don't report a lot of bugs to them
anymore do to this. It is far more effective to report
them here.

Have you seen perldocs for Perl 5?  They contain everything
a developer would need and a wonderful explanation for
the rest of us to use, EVEN ME.  They are beautifully
written.  Perl 5's docs wipe Perl 6's docs faces.

I apologize if I offend anyone, but Perl 6's docs stink.
They need to be readable by both developers and users
alike. They are obviously not.   Perl 5's docs prove this
is possible.

And by the way, the developers have their own set of
specifications.  There is no excuse for writing the Perl
6 docs in IEEE-eese.

-T

Re: vulgar?

[Laurent Rosenfeld via perl6-users]

Manual pages (which are reference material) and tutorials are two very
different kinds of writing. Manual pages are usually more difficult to
understand than (good) tutorials, because they have to be *very accurate*
and as complete as possible (if not exhaustive), while tutorials can leave
out some intricacies or gory details.



Le ven. 6 déc. 2019 à 07:30, ToddAndMargo via perl6-users <
perl6-users@perl.org> a écrit :

> On 2019-12-05 02:38, Tom Browder wrote:
> > I have had several email conversations with Andrew and he seems like a
> > nice person to me. I sometimes think non-native English speakers pick up
> > bad speech habits because of the absolutely sewer-mouthed "popular"
> > folks on Twitter.
>
>
> For a non-native speaker, he sure runs circles around my
> native speaking ability.  Kind of humbling.
>
> I am glad this is a not a typical thing for him.  His
> writing and examples are really well done.  Not
> one sign of IEEE-eese anywhere.  And I perfectly
> understand everything he says.  He makes the complex
> seem simple.  And that takes talent.
>
> In college, I had several Vietnamese friends that when
> they got together and started speaking Vietnamese to
> each other, they swore in English like a sailor.  When
> I started laughing, I got the "what?" from them.  When
> I told them they were swearing in English, they
> adamantly denied it.  They did not even realizing
> they were.   It was hysterical.
>
> Maybe we could talk him into a re-write of the manual pages?
>

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-05 03:03, William Michels via perl6-users wrote:

I trust you'll find Andy Shitov meant no vulgarity on his blog. I've
been meaning to invite more people via CC: when I send emails to
perl6-users@perl.org. Your comment gives me an excuse to contact Andy
so he can tell you that himself.


So "Shitov" is his actual name.  Poor guy probably
gets razed a lot about it from his English speaking
friends.  Hopefully he stays in a good humor about it.
One of those unfortunate translation things like
the planet "Uranus" (Your Anus).

His tutorial is something to behold.  He make the complex
simple and very understandable.  That takes some talent.
Maybe we should talk him into rewriting the IEEE-eese in
the awful manual pages so they can be used as a reference
from those that are not at the developer level?

I do have to admit I do swear at times, but it is usually when
hurt myself or I can't figure out '\'.  (Okay, I know Q[\].
Single quotes do not mean literal in Raku.)  But I seldom
do swear in writing.

 The idea that no gentleman ever swears is all wrong.
 He can swear and still be a gentleman, if he does it
 in a nice and benevolent and affectionate way.

 --Mark Twain  - Private and Public Morals speech, 1906

Re: vulgar?

[ToddAndMargo via perl6-users]

On 2019-12-05 02:38, Tom Browder wrote:
I have had several email conversations with Andrew and he seems like a 
nice person to me. I sometimes think non-native English speakers pick up 
bad speech habits because of the absolutely sewer-mouthed "popular" 
folks on Twitter.



For a non-native speaker, he sure runs circles around my
native speaking ability.  Kind of humbling.

I am glad this is a not a typical thing for him.  His
writing and examples are really well done.  Not
one sign of IEEE-eese anywhere.  And I perfectly
understand everything he says.  He makes the complex
seem simple.  And that takes talent.

In college, I had several Vietnamese friends that when
they got together and started speaking Vietnamese to
each other, they swore in English like a sailor.  When
I started laughing, I got the "what?" from them.  When
I told them they were swearing in English, they
adamantly denied it.  They did not even realizing
they were.   It was hysterical.

Maybe we could talk him into a re-write of the manual pages?

Re: vulgar?

[Erez Schatz]

Not in the least, I was just pointing that "vulgarity" is in the eye of 
the beholder. Words are just words. Sometimes they are names, other 
times they are swear words, other times they are just text. All in the 
way you see them.


Erez

On 05/12/2019 12:58, Tobias Leich wrote:

"it's the level of vulgarity you'd expect from a guy called S***ov."
... and know it's getting personal... -.-

Erez Schatz mailto:moonb...@gmail.com>> schrieb 
am Do., 5. Dez. 2019, 11:42:


it's the level of vulgarity you'd expect from a guy called S***ov.

But seriously, it's nothing you won't see on basic cable or the
Linux Kernel mailing list.

Erez

On 12/5/19 12:38 PM, Tom Browder wrote:

On Thu, Dec 5, 2019 at 03:57 Todd Chester via perl6-users
mailto:perl6-users@perl.org>> wrote
...

I really like this guys style of writing and examples
for Perl6.

    But he can be a bit vulgar at times, which I ignore.
Is he doing it on purpose?


Todd, I took a quick glance at the link you gave and all I saw
was reference to the Brain* language (whose author I believe
should be ashamed of himself for that name--something like
"Braincramp" would have been better).

I have all Andrew's books and read many of his blogs and never
noticed any trend of vulgarity (which, I too, am sensitive to). 
I do see evidence of several Perl and Raku people whose speech
can sometimes be quite crude and blasphemous, but I'm afraid
that's the modern world: good manners and civility have all but
disappeared in public places. I will say, though, that the #Raku
IRC channel has much less coarse lingo and much more kindness
than most other places I visit.

I have had several email conversations with Andrew and he seems
like a nice person to me. I sometimes think non-native English
speakers pick up bad speech habits because of the absolutely
sewer-mouthed "popular" folks on Twitter.

Best regards,

-Tom

Re: vulgar?

[William Michels via perl6-users]

Hi Todd,

There's a well-known, non-English-based computer language with an
unfortunate name here:

https://en.wikipedia.org/wiki/Brainfuck
https://rosettacode.org/wiki/Rosetta_Code:Brainf***

I trust you'll find Andy Shitov meant no vulgarity on his blog. I've
been meaning to invite more people via CC: when I send emails to
perl6-users@perl.org. Your comment gives me an excuse to contact Andy
so he can tell you that himself.

HTH, Bill.

On Thu, Dec 5, 2019 at 1:57 AM Todd Chester via perl6-users
 wrote:
>
> Hi All,
>
> I really like this guys style of writing and examples
> for Perl6.
>
> But he can be a bit vulgar at times, which I ignore.
> Is he doing it on purpose?  Or is there some translation
> error and he does not realize he is swearing?
>
> Warning: if you go here there are some dirty words
> in the titles:
>
> https://andrewshitov.com/category/using-perl-6/
>
> -T

Re: vulgar?

[Tobias Leich]

"it's the level of vulgarity you'd expect from a guy called S***ov."
... and know it's getting personal... -.-

Erez Schatz  schrieb am Do., 5. Dez. 2019, 11:42:

> it's the level of vulgarity you'd expect from a guy called S***ov.
>
> But seriously, it's nothing you won't see on basic cable or the Linux
> Kernel mailing list.
>
> Erez
> On 12/5/19 12:38 PM, Tom Browder wrote:
>
> On Thu, Dec 5, 2019 at 03:57 Todd Chester via perl6-users <
> perl6-users@perl.org> wrote
> ...
>
>> I really like this guys style of writing and examples
>> for Perl6.
>>
>> But he can be a bit vulgar at times, which I ignore.
>> Is he doing it on purpose?
>
>
> Todd, I took a quick glance at the link you gave and all I saw was
> reference to the Brain* language (whose author I believe should be ashamed
> of himself for that name--something like "Braincramp" would have been
> better).
>
> I have all Andrew's books and read many of his blogs and never noticed any
> trend of vulgarity (which, I too, am sensitive to).  I do see evidence of
> several Perl and Raku people whose speech can sometimes be quite crude and
> blasphemous, but I'm afraid that's the modern world: good manners and
> civility have all but disappeared in public places. I will say, though,
> that the #Raku IRC channel has much less coarse lingo and much more
> kindness than most other places I visit.
>
> I have had several email conversations with Andrew and he seems like a
> nice person to me. I sometimes think non-native English speakers pick up
> bad speech habits because of the absolutely sewer-mouthed "popular" folks
> on Twitter.
>
> Best regards,
>
> -Tom
>
>

Re: vulgar?

[Erez Schatz]

it's the level of vulgarity you'd expect from a guy called S***ov.

But seriously, it's nothing you won't see on basic cable or the Linux 
Kernel mailing list.


Erez

On 12/5/19 12:38 PM, Tom Browder wrote:
On Thu, Dec 5, 2019 at 03:57 Todd Chester via perl6-users 
mailto:perl6-users@perl.org>> wrote

...

I really like this guys style of writing and examples
for Perl6.

But he can be a bit vulgar at times, which I ignore.
Is he doing it on purpose?


Todd, I took a quick glance at the link you gave and all I saw was 
reference to the Brain* language (whose author I believe should be 
ashamed of himself for that name--something like "Braincramp" would 
have been better).


I have all Andrew's books and read many of his blogs and never noticed 
any trend of vulgarity (which, I too, am sensitive to).  I do see 
evidence of several Perl and Raku people whose speech can sometimes be 
quite crude and blasphemous, but I'm afraid that's the modern world: 
good manners and civility have all but disappeared in public places. I 
will say, though, that the #Raku IRC channel has much less coarse 
lingo and much more kindness than most other places I visit.


I have had several email conversations with Andrew and he seems like a 
nice person to me. I sometimes think non-native English speakers pick 
up bad speech habits because of the absolutely sewer-mouthed "popular" 
folks on Twitter.


Best regards,

-Tom

Re: vulgar?

[Tom Browder]

On Thu, Dec 5, 2019 at 03:57 Todd Chester via perl6-users <
perl6-users@perl.org> wrote
...

> I really like this guys style of writing and examples
> for Perl6.
>
> But he can be a bit vulgar at times, which I ignore.
> Is he doing it on purpose?


Todd, I took a quick glance at the link you gave and all I saw was
reference to the Brain* language (whose author I believe should be ashamed
of himself for that name--something like "Braincramp" would have been
better).

I have all Andrew's books and read many of his blogs and never noticed any
trend of vulgarity (which, I too, am sensitive to).  I do see evidence of
several Perl and Raku people whose speech can sometimes be quite crude and
blasphemous, but I'm afraid that's the modern world: good manners and
civility have all but disappeared in public places. I will say, though,
that the #Raku IRC channel has much less coarse lingo and much more
kindness than most other places I visit.

I have had several email conversations with Andrew and he seems like a nice
person to me. I sometimes think non-native English speakers pick up bad
speech habits because of the absolutely sewer-mouthed "popular" folks on
Twitter.

Best regards,

-Tom

vulgar?

[Todd Chester via perl6-users]

Hi All,

I really like this guys style of writing and examples
for Perl6.

But he can be a bit vulgar at times, which I ignore.
Is he doing it on purpose?  Or is there some translation
error and he does not realize he is swearing?

Warning: if you go here there are some dirty words
in the titles:

https://andrewshitov.com/category/using-perl-6/

-T