Re: Could this be any more obscure?

[ToddAndMargo via perl6-users]

On 10/2/18 9:38 PM, David Green wrote:


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


Hi David,

I really don't do well with such.  Thank you for
the tip anyway.

-T

Re: Could this be any more obscure?

[ToddAndMargo via perl6-users]

On 10/2/18 5:52 PM, David Green wrote:

On 2018-10-02 6:28 pm, ToddAndMargo wrote:
Question: in Perl syntaxland, is "postfix" short for "postcircumfix"? 

Again, search for "postcircumfix" in docs.perl6.org, and you will get this:

https://docs.perl6.org/language/operators#index-entry-postcircumfix_operator 



 >>term++  postfix
 >>(term)  circumfix
 >>term1[term2]    postcircumfix

So it's a postfix operator and circumfix operator put together: *after* 
one term, and *around* the other term.




-David



Hi David,

Still scratching me head, but it will sink in eventually.

Thank you!

-T

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Re: Could this be any more obscure?

[David Green]

On 2018-10-02 6:28 pm, ToddAndMargo wrote:
Question: in Perl syntaxland, is "postfix" short for "postcircumfix"? 

Again, search for "postcircumfix" in docs.perl6.org, and you will get this:

https://docs.perl6.org/language/operators#index-entry-postcircumfix_operator

>>term++  postfix
>>(term)  circumfix
>>term1[term2]    postcircumfix

So it's a postfix operator and circumfix operator put together: *after* 
one term, and *around* the other term.




-David

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/3/18 11:33 AM, ToddAndMargo wrote:

On 10/2/18 10:16 PM, David Green wrote:

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
 >By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much 
more than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



 >[RH] are mixing socialist political terms with what I am stating.  
[...]

 >I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  
But it does show how easy it is for something that is clear to one 
person to be misunderstood by another. Repeating something the same 
way doesn't make it clearer (that's one of the reasons we have 
teachers instead of only books, because they can reword things and 
take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  
What about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, 
Projects, and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David


Hi David,

I will look it up.

Any usa sources of the book?

-T


https://www.amazon.com/s/ref=nb_sb_noss

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 10:16 PM, David Green wrote:

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
 >By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



 >[RH] are mixing socialist political terms with what I am stating.  [...]
 >I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David


Hi David,

I will look it up.

Any usa sources of the book?

-T

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 9:02 PM, Richard Hainsworth wrote:
The Perl6 community is warm, generous, and intellectually inspiring. 
Those virtues should be defended against unseemly and intemperate 
language. Calling a documentation writer a 'jerk' is wrong.


Agreed.  They are very much so.  And since you are a native
English speaker, you know there is a difference between
calling someone a jerk for lording it over the recipient
that he knows more than you do and me calling anyone
on the Perl 6 community a jerk. I was criticizing a writing
style, not the Perl 6 community.  That you thought I had
I had done that is beyond me.

Re: Could this be any more obscure?

[Elizabeth Mattijsen]

> On 3 Oct 2018, at 02:48, ToddAndMargo  wrote:
> 
> On 10/2/18 2:24 AM, Elizabeth Mattijsen wrote:
>> Also, a hopefully less steep introduction:
>> 
>>   https://opensource.com/article/18/9/signatures-perl-6
>> 
> 
> Will do!  Thank you!
> 
> Do you have an index to other stuff you have written?

https://opensource.com/users/lizmat contains an index of the stuff I’ve written 
for opensource.com.

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Re: Could this be any more obscure?

[David Green]

On 2018-09-30 9:31 pm, ToddAndMargo wrote:
>By the way, schools have books.  Why is it do you suppose that that 
schools also have teacher?


Well, why is it, do you suppose, that hiring a tutor costs so much more 
than buying a book?


Certainly, some people learn better aurally than visually.  There are 
quite a few recorded P6 presentations around, but I don't know if 
there's a collected list anywhere, or one that links to recent talks 
(anything not too out-of-date).



>[RH] are mixing socialist political terms with what I am stating.  [...]
>I have been very clear what I am after, so I won't repeat it yet again.

The word "common" comes from Latin, and "typical" from Greek, but in 
this context they are synonyms. There's nothing political about it.  But 
it does show how easy it is for something that is clear to one person to 
be misunderstood by another. Repeating something the same way doesn't 
make it clearer (that's one of the reasons we have teachers instead of 
only books, because they can reword things and take different approaches).


There isn't any easy answer to coming up with documentation that works 
for everyone.  (You can't please all of the people all of the time.) 
Perl(5)doc is just a book, after all; but "be more like Perl 5" won't 
work, because Perl 6 is *different* from Perl 5.  Putting beginner and 
advanced docs together might end up with a mish-mash that makes nobody 
happy.  It seems likely to me that you're looking for example-based 
documentation that is organised very differently from docs.perl6.  What 
about Moritz's *Perl 6 Fundamentals*, "A Primer with Examples, Projects, 
and Case Studies"?


https://www.apress.com/gp/book/9781484228982

Is this something that better fits the way you think?


-David

Re: No. It is lucid! Re: Could this be any more obscure?

[Richard Hainsworth]

This could only too easily become a flame war, so I am replying once and 
will not answer again unless it is about substance.


The Perl6 community is warm, generous, and intellectually inspiring. 
Those virtues should be defended against unseemly and intemperate 
language. Calling a documentation writer a 'jerk' is wrong.


On 03/10/18 07:40, ToddAndMargo wrote:

On 9/30/18 9:11 PM, Richard Hainsworth wrote:

But I thought you just implied you wanted pro stuff, not beginner stuff. 


I have no idea how you got that out of what I said.  I want the
beginners stuff included with the pro stuff.
Yes the best of all worlds, and it must be short. Demand the impossible 
and complain when it does not happen. There are a number of people 
trying very hard to balance the contradictions of writing documentation. 
We need to support them and offer constructive suggestions. Clearly my 
post was wrong because you did not *think* about what I said, only 
reacted negatively to my British sense of humour.



So what is wanted is 'common user' stuff (see below).


You are mixing socialist political terms with what I
am stating.  By "common user" I mean a typical user.
The term was meant to differentiate typical users from
experts.
Where did 'socialist' come from? You said 'common user' and I was trying 
to elicit from you what it meant. But as it happens I do not think that 
'socialist' is a negative word, and for many people it means an emphasis 
on society and community (as in this very valuable Perl6 community) 
rather than on solitary individuals.


Actually, I do not understand what you are saying at all, eg., 'I 
have know how to use ...' is not clear.


Again, I have no idea how you got that out of what I said.
I quoted your words from your post. They are in quotes. Your use of 
English grammar is not standard, and consequently it is ambiguous.

When I use a function all the time, I know who to use the
you know 'who to use' or 'how to use'? It would be useful for you to 
read what you have written for mistakes before clicking on the 'send' 
button. That way, other people can understand you better.

function. The problem was that I could not reverse engineer
the documentation.
  In other words, I figured out how to
use the function from other sources than the documentation.
Had I used the documentation, I never would have figured it out.
That is the issue.
This use of 'reverse engineer' is obscure. But if you mean that you had 
to read around a bit in order to understand, I suggest that this is 
quite a normal intellectual activity. That is why repeatedly it has been 
suggested that you read a book.



But I am confused about what *you* want from the reference 
documentation.


I think maybe there is a translation issue between your native
language and mine.  I have been very clear what I am
after, so I won't repeat it yet again.
My native language is English. I was born to English parents, went to 
school in Leeds, went to University in London, studied computer science 
and economics in Birmingham, spent 20 years editing and translating into 
English from Russian in Moscow. I speak and write Russian, and I am 
learning Cantonese.


I do get it: you are following the example of the current crop of 
political leaders in the US. When someone demonstrates - as I did in the 
previous post, and in this one - that your English grammar and spelling 
are slovenly, you throw back the criticism as if I am guilty of the 
same, and charge that my native language is not English.


So no it is not a translation issue. What you want is not clear because 
(a) you do not write clearly, (b) you ask for different things at 
different times, (c) you assume that the world is predominantly the same 
as you, when it is not.




    3) when calling other term to explain things, it should
   pick the easiest term available. It should not pick
   any nasty, advanced terms.  (Unless the writer enjoys
   confusing the reader and bragging about how smart
   he is.  And he is a jerk.)
This does not seem to be correct English. 


You are again missing the point.  It is wonderful if the writer
wants to share an interesting, complex way of doing things.
But only AFTER he explains it in is simple terms.  You don't
share a calculus equation with someone until after you
teach them the fundamentals of arithmetic.
I did not miss the point. You deleted the part of my response where I 
agreed that there should be simple examples. You also deleted the part 
where I pointed out that calling someone a 'jerk' is not polite. It is 
possible to get carried away by beauty and elegance and forget the need 
to start with simple things. That might make the explanation cryptic; it 
does not make them a jerk.




We come again to this category: 'the common user'. This person 
(possibly there are more) is not a 'beginner' nor a 'pro'. What is to 
be expected of a 'common user' of perl6? Can we assume that a 'common 
user' has read an introduction to perl

Re: Could this be any more obscure?

[Peter Scott]

On 10/2/2018 5:45 PM, ToddAndMargo wrote:

On 10/2/18 5:31 PM, Curt Tilmes wrote:


On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo > wrote:


    Question: in Perl syntaxland, is "postfix" short
    for "postcircumfix"?


Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification



Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

in that list.


It's second in the list:



Searching within web page for the term you want usually finds it if it's 
there.  Ctrl-F postfix.

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:51 PM, Curt Tilmes wrote:



On Tue, Oct 2, 2018 at 8:46 PM ToddAndMargo > wrote:


On 10/2/18 5:31 PM, Curt Tilmes wrote:
 >
 > On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo
mailto:toddandma...@zoho.com>
 > >> wrote:
 >
 >     Question: in Perl syntaxland, is "postfix" short
 >     for "postcircumfix"?
 >
 >
 > Nope.  Each are different types of oeprator.  Here is the list:
 > https://docs.perl6.org/language/operators#Operator_classification
 >

Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

Here's the list cut/pasted from directly at the link I posted:

Operators can occur in several positions relative to a term:

+term   prefix
term1 + term2   infix
term++  postfix
(term)  circumfix
term1[term2]postcircumfix

 From that, you can see that postfix things go behind a single term 
while postcircumfix things go behind 1 term, and around another term.


One example on that page of a postcircumfix operator is the [] you 
linked to.





Hi Curt,

Thank you!

Larry removed the rest of the fuzz from my thinking.

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:51 PM, Larry Wall wrote:

On Tue, Oct 02, 2018 at 05:28:01PM -0700, ToddAndMargo wrote:
: On 10/2/18 11:23 AM, Ralph Mellor wrote:
: >So, to recap: a postfix `[]` acts on whatever is on its left,
: >pulling out elements from the thing on its left, treated as
: >a list like thing, with the elements selected according to
: >the index(es) inside the brackets.
: >
:
:
: Perfect!  Thank you!
:
: I am going to quote you in my write up.
:
: Question: in Perl syntaxland, is "postfix" short
: for "postcircumfix"?

Kinda the other way around.  A postcircumfix is just a special kind of
postfix that happens to enclose an extra argument, with the result that,
while your typical postfix has only one argument (like the $a of $a++),
your typical postcircumfix has two (like the @a and 42 of @a[42]).

The second syntactic argument is often interpreted as a slice or an
function argument list later on, but syntactically it's just a single
expression inside the bracketing chars.  So in @a[42,43], there are
still only two arguments, @a array and the 42,43 list expression.

Larry



Hi Larry,

Beautiful explanation!  You even tied their relationship
together, rather than leaving me thinking there were
two separate unrelated functions.   Thank you!

I am going to quote you too in my private write up.

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Tue, Oct 2, 2018 at 8:46 PM ToddAndMargo  wrote:

> On 10/2/18 5:31 PM, Curt Tilmes wrote:
> >
> > On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo  > > wrote:
> >
> > Question: in Perl syntaxland, is "postfix" short
> > for "postcircumfix"?
> >
> >
> > Nope.  Each are different types of oeprator.  Here is the list:
> > https://docs.perl6.org/language/operators#Operator_classification
> >
>
> Hi Curt,
>
> Maybe I am blind, but I can only find
>
> postcircumfix [ ]
> https://docs.perl6.org/language/operators#postcircumfix_[_]


Here's the list cut/pasted from directly at the link I posted:

Operators can occur in several positions relative to a term:
+term prefix
term1 + term2 infix
term++ postfix
(term) circumfix
term1[term2] postcircumfix

>From that, you can see that postfix things go behind a single term while
postcircumfix things go behind 1 term, and around another term.

One example on that page of a postcircumfix operator is the [] you linked
to.

Re: Could this be any more obscure?

[Larry Wall]

On Tue, Oct 02, 2018 at 05:28:01PM -0700, ToddAndMargo wrote:
: On 10/2/18 11:23 AM, Ralph Mellor wrote:
: >So, to recap: a postfix `[]` acts on whatever is on its left,
: >pulling out elements from the thing on its left, treated as
: >a list like thing, with the elements selected according to
: >the index(es) inside the brackets.
: >
: 
: 
: Perfect!  Thank you!
: 
: I am going to quote you in my write up.
: 
: Question: in Perl syntaxland, is "postfix" short
: for "postcircumfix"?

Kinda the other way around.  A postcircumfix is just a special kind of
postfix that happens to enclose an extra argument, with the result that,
while your typical postfix has only one argument (like the $a of $a++),
your typical postcircumfix has two (like the @a and 42 of @a[42]).

The second syntactic argument is often interpreted as a slice or an
function argument list later on, but syntactically it's just a single
expression inside the bracketing chars.  So in @a[42,43], there are
still only two arguments, @a array and the 42,43 list expression.

Larry

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 2:24 AM, Elizabeth Mattijsen wrote:

Also, a hopefully less steep introduction:


   https://opensource.com/article/18/9/signatures-perl-6



Will do!  Thank you!

Do you have an index to other stuff you have written?

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 2:01 AM, Simon Proctor wrote:

https://docs.perl6.org/type/Signature

Todd can I ask that you read this page of the docs for two reasons. 
Firstly understanding Signatures will go a long way to helping you to 
understand the rest of the docs, and secondly so you can give use your 
take on it pointing out any areas you think could be more clear.


I personally think that grasping the signature system is fundamental in 
moving from Perl 5 to Perl 6 and in reading the Perl6 docs.


Simon


In progress.   Thank you!

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 5:31 PM, Curt Tilmes wrote:


On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo > wrote:


Question: in Perl syntaxland, is "postfix" short
for "postcircumfix"?


Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification



Hi Curt,

Maybe I am blind, but I can only find

postcircumfix [ ]
https://docs.perl6.org/language/operators#postcircumfix_[_]

in that list.

:'(

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Tue, Oct 2, 2018 at 8:28 PM ToddAndMargo  wrote:

> Question: in Perl syntaxland, is "postfix" short
> for "postcircumfix"?
>

Nope.  Each are different types of oeprator.  Here is the list:
https://docs.perl6.org/language/operators#Operator_classification

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 11:23 AM, Ralph Mellor wrote:

So, to recap: a postfix `[]` acts on whatever is on its left,
pulling out elements from the thing on its left, treated as
a list like thing, with the elements selected according to
the index(es) inside the brackets.




Perfect!  Thank you!

I am going to quote you in my write up.

Question: in Perl syntaxland, is "postfix" short
for "postcircumfix"?


-T

Re: Could this be any more obscure?

[Rocco Caputo]

> On Oct 2, 2018, at 04:40, ToddAndMargo  wrote:
> 
> I am thinking of doing an RFE to place at the front
> of the routines documentation that introduces the reader
> on how to read THAT line in the documentation -- what
> the abbreviations and symbols and the like mean.


Referring the reader to the copy that already exists is better than duplicating 
that information.

Redundancy is tedious to read and hard to maintain.

Making the manual more readable for people who won't look things up isn't worth 
that.

-- 
Rocco Caputo 

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/2/18 6:06 AM, Rocco Caputo wrote:
On Oct 2, 2018, at 04:40, ToddAndMargo > wrote:


I am thinking of doing an RFE to place at the front
of the routines documentation that introduces the reader
on how to read THAT line in the documentation -- what
the abbreviations and symbols and the like mean.


Referring the reader to the copy that already exists is better than 
duplicating that information.


So it is already written?  Do you have a link to that?

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 9:11 PM, Richard Hainsworth wrote:

But I thought you just implied you wanted pro stuff, not beginner stuff. 


I have no idea how you got that out of what I said.  I want the
beginners stuff included with the pro stuff.


So what is wanted is 'common user' stuff (see below).


You are mixing socialist political terms with what I
am stating.  By "common user" I mean a typical user.
The term was meant to differentiate typical users from
experts.

Actually, I do not understand what you are saying at all, eg., 'I have 
know how to use ...' is not clear.


Again, I have no idea how you got that out of what I said.
When I use a function all the time, I know who to use the
function.  The problem was that I could not reverse engineer
the documentation.  In other words, I figured out how to
use the function from other sources than the documentation.
Had I used the documentation, I never would have figured it out.
That is the issue.



But I am confused about what *you* want from the reference documentation.


I think maybe there is a translation issue between your native
language and mine.  I have been very clear what I am
after, so I won't repeat it yet again.



    3) when calling other term to explain things, it should
   pick the easiest term available. It should not pick
   any nasty, advanced terms.  (Unless the writer enjoys
   confusing the reader and bragging about how smart
   he is.  And he is a jerk.)
This does not seem to be correct English. 


You are again missing the point.  It is wonderful if the writer
wants to share an interesting, complex way of doing things.
But only AFTER he explains it in is simple terms.  You don't
share a calculus equation with someone until after you
teach them the fundamentals of arithmetic.


We come again to this category: 'the common user'. This person (possibly 
there are more) is not a 'beginner' nor a 'pro'. What is to be expected 
of a 'common user' of perl6? Can we assume that a 'common user' has read 
an introduction to perl6?


You are mixing socialist political terms with what
I am saying again.


Perl 5's perldoc did a wonderful job of this.

I never liked perldoc. 'To whom how', as they say in Russian.


I find perldocs from the command line a total pain in the butt.
Fortunately, it is repeated on web beautifully.



I have been posting RFE about this as they come up.
So I am trying to be part of the solution instead
of constantly gripping about the problem.


Indeed this discussion has, at times, been gripping, but I hope you 
don't think I have been griping. ;)


I think that there is a translation and maybe a cultural difference
that has lead you to misconstrue my statements.  That or you are
just trying to pick a fight.  Your "buffoon in the White House"
statement is definitely trying to pick a fight.

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 10/1/18 4:17 PM, Brandon Allbery wrote:
That just sounds like the backing store got restored from backup, losing 
anything added after the backup was taken. Which is not the best way to 
do things (incrementals are nice), but if things had gone wrong enough 
might have been the best they could do.


That does sound very plausible.

Re: Could this be any more obscure?

[Ralph Mellor]

>> On 10/1/18 3:37 PM, Donald Hunter wrote:
>>  > Methods don't accept [], values that are positional do that.
>> Is your distinction that [] is actually a routine in itself
>> and not part of the method?  And I am lumping them together?
On 10/2/18 12:18 AM, Laurent Rosenfeld via perl6-users wrote:
> Yes, [] acts on the result (a positional, e.g. a list) returned by
> function or method, it does not act on the function or method itself.

"acts on the result" is a beautiful way to state it.

Just to be clear, the fact that it acts on the result of a method
or function doesn't mean a method or function or result has to
be involved. Consider:

@array[0]

A variable `@array` may well not be a result of anything.



The thing on the left of a postfix `[...]` may not even do the `Positional`
role.

The postfix `[]` operattor turns into an an `AT-POS` method call if
the thing on the left is a `Positional`. The Positional role defines
an `AT-POS` method. Anything that does the `Positional` role will
work as the left hand side of a postfix `[...]`.

But other types that *don't* do the `Positional` role can still have
an `AT-POS` method and a postfix `[...]` will work with them too.

--

In particular the built in `Any` has an `AT-POS`.

So you can append a `[...]` to any single thing and it'll work:

42[0]

The above results in 42.

42[1]

yields "Index out of range. Is: 1, should be in 0..0"

-

So, to recap: a postfix `[]` acts on whatever is on its left,
pulling out elements from the thing on its left, treated as
a list like thing, with the elements selected according to
the index(es) inside the brackets.

--
raiph

Re: Could this be any more obscure?

[Elizabeth Mattijsen]

Also, a hopefully less steep introduction:

 
  https://opensource.com/article/18/9/signatures-perl-6


> On 2 Oct 2018, at 11:01, Simon Proctor  wrote:
> 
> https://docs.perl6.org/type/Signature
> 
> Todd can I ask that you read this page of the docs for two reasons. Firstly 
> understanding Signatures will go a long way to helping you to understand the 
> rest of the docs, and secondly so you can give use your take on it pointing 
> out any areas you think could be more clear.
> 
> I personally think that grasping the signature system is fundamental in 
> moving from Perl 5 to Perl 6 and in reading the Perl6 docs. 
> 
> Simon
> 
> On Tue, 2 Oct 2018 at 09:41, ToddAndMargo  wrote:
> >> Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  >> > a écrit :
> >> 
> >> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >>  > And again: this is only because you know perl 5. People are not born
> >>  > knowing perl 5; to someone who doesn't know it, perldoc raises
> >> the same
> >>  > kinds of questions you have been asking, and the answers have to be
> >>  > found in perlsyn or perldata, etc. Which is exactly what you have
> >> been
> >>  > complaining about with respect to perl 6 doing the same kind of
> >> thing.
> >> 
> >> Geez Louise Bradley!  The above is a really bad argument!
> >> 
> >> "perldocs -f xxx" is a bazillion times easier to understand
> >> than Perl 6's manual, regardless if you know Perl 5 or not.
> >> 
> >> And, by the way, I wonder just how may are coming to Perl 6
> >> without ANY Perl 5 experience?
> >> 
> >> In every instance I can look up, perldocs puts Perl 6's
> >> documentation to shame.
> >> 
> >> A simple comparison: which one leaves you knowing how to use
> >> the function and which one leaves you wondering "What the h***???"
> >> 
> >> $ perldoc -f join
> >>   join EXPR,LIST
> >>   Joins the separate strings of LIST into a single
> >> string with
> >>   fields separated by the value of EXPR, and returns
> >> that new
> >>   string. Example:
> >> 
> >>  my $rec = join(':',
> >> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
> >> 
> >>   Beware that unlike "split", "join" doesn't take a pattern
> >>   as its first argument. Compare "split".
> >> 
> >> 
> >> 
> >> https://docs.perl6.org/routine/join#(List)_routine_join
> >> 
> >>   (List) routine join
> >> 
> >>   Defined as:
> >> 
> >>   subjoin($separator, *@list --> Str:D)
> >>   method join(List:D: $separator --> Str:D)
> >> 
> >>   Treats the elements of the list as strings, interleaves
> >>   them with $separator and concatenates everything into a
> >>   single string.
> >> 
> >>   Example:
> >> 
> >>   join ', ', ; # RESULT: «a, b, c»
> >> 
> >>   Note that the method form does not flatten sublists:
> >> 
> >>   say (1, ).join('|'); # OUTPUT: «1|a b c␤»
> >> 
> >> 
> >> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> >> and the method does not?  They are suppose to be identical.
> >> 
> >> -T
> >> 
> 
> On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:
> > Hi Todd,
> > I disagree with you. The P6 documentation can certainly be improved, but 
> > it is quite good and clear already. Remember that it is technical 
> > documentation, not a tutorial.
> > 
> > And the example you chose to give does not support your point: the P6 
> > documentation for join is just at least as clear as the P5 documentation 
> > on the same function.
> > 
> > When I wrote my book on Perl 6, there was no other P6 book around, so I 
> > had to rely heavily on the existing documentation for all kinds of 
> > syntax details, and I found that is was quite useful and even easy (and 
> > it has improved quite a bit since then). You're welcome to help 
> > improving the documentation, but, please, don't say it's bad just 
> > because you don't want to make the effort needed to understand it.
> > 
> > If you don't understand the signatures in the documentation, you've 
> > basically two possible solutions: just skip them, as you can certainly 
> > understand how to use a built-in function without understanding the 
> > signature (but it is still very useful to have the signature definition 
> > in the documentation), or bite the bullet and learn how to read signatures.
> > 
> > Despite your denegation, I think that what you really need is to read a 
> > good tutorial or book on Perl 6. If you had made a real effort to read 
> > such introductory material, you would probably not have needed to ask 
> > about 90% of the questions you asked lately. Do yourself a favor: read 
> > good introductory material (tutorials or books).
> > 
> > HTH,
> > Laurent.
> > 
> > 
> 
> Hi Laurent,
> 
> You already know what to expect. 

Re: Could this be any more obscure?

[Simon Proctor]

https://docs.perl6.org/type/Signature

Todd can I ask that you read this page of the docs for two reasons. Firstly
understanding Signatures will go a long way to helping you to understand
the rest of the docs, and secondly so you can give use your take on it
pointing out any areas you think could be more clear.

I personally think that grasping the signature system is fundamental in
moving from Perl 5 to Perl 6 and in reading the Perl6 docs.

Simon

On Tue, 2 Oct 2018 at 09:41, ToddAndMargo  wrote:

> >> Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  >> > a écrit :
> >>
> >> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >>  > And again: this is only because you know perl 5. People are not
> born
> >>  > knowing perl 5; to someone who doesn't know it, perldoc raises
> >> the same
> >>  > kinds of questions you have been asking, and the answers have to
> be
> >>  > found in perlsyn or perldata, etc. Which is exactly what you have
> >> been
> >>  > complaining about with respect to perl 6 doing the same kind of
> >> thing.
> >>
> >> Geez Louise Bradley!  The above is a really bad argument!
> >>
> >> "perldocs -f xxx" is a bazillion times easier to understand
> >> than Perl 6's manual, regardless if you know Perl 5 or not.
> >>
> >> And, by the way, I wonder just how may are coming to Perl 6
> >> without ANY Perl 5 experience?
> >>
> >> In every instance I can look up, perldocs puts Perl 6's
> >> documentation to shame.
> >>
> >> A simple comparison: which one leaves you knowing how to use
> >> the function and which one leaves you wondering "What the h***???"
> >>
> >> $ perldoc -f join
> >>   join EXPR,LIST
> >>   Joins the separate strings of LIST into a single
> >> string with
> >>   fields separated by the value of EXPR, and returns
> >> that new
> >>   string. Example:
> >>
> >>  my $rec = join(':',
> >> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
> >>
> >>   Beware that unlike "split", "join" doesn't take a
> pattern
> >>   as its first argument. Compare "split".
> >>
> >>
> >>
> >> https://docs.perl6.org/routine/join#(List)_routine_join
> >>
> >>   (List) routine join
> >>
> >>   Defined as:
> >>
> >>   subjoin($separator, *@list --> Str:D)
> >>   method join(List:D: $separator --> Str:D)
> >>
> >>   Treats the elements of the list as strings, interleaves
> >>   them with $separator and concatenates everything into a
> >>   single string.
> >>
> >>   Example:
> >>
> >>   join ', ', ; # RESULT: «a, b, c»
> >>
> >>   Note that the method form does not flatten sublists:
> >>
> >>   say (1, ).join('|'); # OUTPUT: «1|a b c␤»
> >>
> >>
> >> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> >> and the method does not?  They are suppose to be identical.
> >>
> >> -T
> >>
>
> On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:
> > Hi Todd,
> > I disagree with you. The P6 documentation can certainly be improved, but
> > it is quite good and clear already. Remember that it is technical
> > documentation, not a tutorial.
> >
> > And the example you chose to give does not support your point: the P6
> > documentation for join is just at least as clear as the P5 documentation
> > on the same function.
> >
> > When I wrote my book on Perl 6, there was no other P6 book around, so I
> > had to rely heavily on the existing documentation for all kinds of
> > syntax details, and I found that is was quite useful and even easy (and
> > it has improved quite a bit since then). You're welcome to help
> > improving the documentation, but, please, don't say it's bad just
> > because you don't want to make the effort needed to understand it.
> >
> > If you don't understand the signatures in the documentation, you've
> > basically two possible solutions: just skip them, as you can certainly
> > understand how to use a built-in function without understanding the
> > signature (but it is still very useful to have the signature definition
> > in the documentation), or bite the bullet and learn how to read
> signatures.
> >
> > Despite your denegation, I think that what you really need is to read a
> > good tutorial or book on Perl 6. If you had made a real effort to read
> > such introductory material, you would probably not have needed to ask
> > about 90% of the questions you asked lately. Do yourself a favor: read
> > good introductory material (tutorials or books).
> >
> > HTH,
> > Laurent.
> >
> >
>
> Hi Laurent,
>
> You already know what to expect.  You are an advanced user.
> And I would have to tentatively agree with you. The documentation
> does "seem" to be extraordinarily well written for advanced
> developer level users.  Just the sort of reader that does not
> need t

Re: Could this be any more obscure?

[ToddAndMargo]

Le dim. 30 sept. 2018 à 11:32, ToddAndMargo > a écrit :


On 9/26/18 7:27 PM, Brandon Allbery wrote:
 > And again: this is only because you know perl 5. People are not born
 > knowing perl 5; to someone who doesn't know it, perldoc raises
the same
 > kinds of questions you have been asking, and the answers have to be
 > found in perlsyn or perldata, etc. Which is exactly what you have
been
 > complaining about with respect to perl 6 doing the same kind of
thing.

Geez Louise Bradley!  The above is a really bad argument!

"perldocs -f xxx" is a bazillion times easier to understand
than Perl 6's manual, regardless if you know Perl 5 or not.

And, by the way, I wonder just how may are coming to Perl 6
without ANY Perl 5 experience?

In every instance I can look up, perldocs puts Perl 6's
documentation to shame.

A simple comparison: which one leaves you knowing how to use
the function and which one leaves you wondering "What the h***???"

$ perldoc -f join
  join EXPR,LIST
  Joins the separate strings of LIST into a single
string with
  fields separated by the value of EXPR, and returns
that new
  string. Example:

 my $rec = join(':',
$login,$passwd,$uid,$gid,$gcos,$home,$shell);

  Beware that unlike "split", "join" doesn't take a pattern
  as its first argument. Compare "split".



https://docs.perl6.org/routine/join#(List)_routine_join

  (List) routine join

  Defined as:

  subjoin($separator, *@list --> Str:D)
  method join(List:D: $separator --> Str:D)

  Treats the elements of the list as strings, interleaves
  them with $separator and concatenates everything into a
  single string.

  Example:

  join ', ', ; # RESULT: «a, b, c»

  Note that the method form does not flatten sublists:

  say (1, ).join('|'); # OUTPUT: «1|a b c␤»


Oh and what the &*@% is a "*@list"?  And why does the sub have one
and the method does not?  They are suppose to be identical.

-T



On 9/30/18 4:01 AM, Laurent Rosenfeld wrote:

Hi Todd,
I disagree with you. The P6 documentation can certainly be improved, but 
it is quite good and clear already. Remember that it is technical 
documentation, not a tutorial.


And the example you chose to give does not support your point: the P6 
documentation for join is just at least as clear as the P5 documentation 
on the same function.


When I wrote my book on Perl 6, there was no other P6 book around, so I 
had to rely heavily on the existing documentation for all kinds of 
syntax details, and I found that is was quite useful and even easy (and 
it has improved quite a bit since then). You're welcome to help 
improving the documentation, but, please, don't say it's bad just 
because you don't want to make the effort needed to understand it.


If you don't understand the signatures in the documentation, you've 
basically two possible solutions: just skip them, as you can certainly 
understand how to use a built-in function without understanding the 
signature (but it is still very useful to have the signature definition 
in the documentation), or bite the bullet and learn how to read signatures.


Despite your denegation, I think that what you really need is to read a 
good tutorial or book on Perl 6. If you had made a real effort to read 
such introductory material, you would probably not have needed to ask 
about 90% of the questions you asked lately. Do yourself a favor: read 
good introductory material (tutorials or books).


HTH,
Laurent.




Hi Laurent,

You already know what to expect.  You are an advanced user.
And I would have to tentatively agree with you. The documentation
does "seem" to be extraordinarily well written for advanced
developer level users.  Just the sort of reader that does not
need to use it as they already know what is going on.

When you know how to use a function but can't reverse
engineer how to do it from the documentation, then you
are in real trouble.

I am thinking of doing an RFE to place at the front
of the routines documentation that introduces the reader
on how to read THAT line in the documentation -- what
the abbreviations and symbols and the like mean.

If I do, I will post it here first for criticism.

Your thoughts?

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/1/18 1:20 AM, Siavash wrote:


You can read the thread here:
https://www.nntp.perl.org/group/perl.perl6.users/2018/09/msg5757.html

On 2018-10-01 04:21:43 +0330, ToddAndMargo wrote:

Hi All,

My "Perl" box got corrupted and in the process of rebuilding
it I lost this thread except for one one message from JJ.
Anyway, I am not deliberately ignoring anyone, I just
lost the thread.

:'(

-T


Thank you!

Something must has appeased the imap gods and the entire thread
came storming back one entry at a time.

But the note I sent says it had be erased did not.  Then a day
later it appeared too.


Hm

Re: Could this be any more obscure?

[ToddAndMargo]

Le mar. 2 oct. 2018 à 08:05, ToddAndMargo > a écrit :


On 10/1/18 3:37 PM, Donald Hunter wrote:
 > toddandma...@zoho.com 
(ToddAndMargo) writes:
 >>
 >> Hi Curt,
 >>
 >> Perfect! Thank you!
 >>
 >> So all methods that respond with --> Positional will accept []
 >>
 >> Awesome!
 >>
 >> -T
 >
 > Not quite.
 >
 > All methods that respond with --> Positional, provide a
Positional that
 > will accept []
 >
 > Methods don't accept [], values that are positional do that.
 >
 > Cheers,
 > Donald.
 >

Hi Donald,

I am confused.  I though we both said the same thing?
Is your distinction that [] is actually a routine in itself
and not part of the method?  And I am lumping them together?

-T



On 10/2/18 12:18 AM, Laurent Rosenfeld via perl6-users wrote:
Yes, [] acts on the result (a positional, e.g. a list) returned by 
function or method, it does not act on the function or method itself.


You have more or less the same in Perl 5, for example:

my $first_item = (split /;/, $string)[0];

Here, the [0] acts on the list returned by split.



"acts on the result" is a beautiful way to state it.

Thank you!

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

Yes, [] acts on the result (a positional, e.g. a list) returned by function
or method, it does not act on the function or method itself.

You have more or less the same in Perl 5, for example:

my $first_item = (split /;/, $string)[0];

Here, the [0] acts on the list returned by split.


Le mar. 2 oct. 2018 à 08:05, ToddAndMargo  a écrit :

> On 10/1/18 3:37 PM, Donald Hunter wrote:
> > toddandma...@zoho.com (ToddAndMargo) writes:
> >>
> >> Hi Curt,
> >>
> >> Perfect! Thank you!
> >>
> >> So all methods that respond with --> Positional will accept []
> >>
> >> Awesome!
> >>
> >> -T
> >
> > Not quite.
> >
> > All methods that respond with --> Positional, provide a Positional that
> > will accept []
> >
> > Methods don't accept [], values that are positional do that.
> >
> > Cheers,
> > Donald.
> >
>
> Hi Donald,
>
> I am confused.  I though we both said the same thing?
> Is your distinction that [] is actually a routine in itself
> and not part of the method?  And I am lumping them together?
>
> -T
>

Re: Could this be any more obscure?

[ToddAndMargo]

On 10/1/18 3:37 PM, Donald Hunter wrote:

toddandma...@zoho.com (ToddAndMargo) writes:


Hi Curt,

Perfect! Thank you!

So all methods that respond with --> Positional will accept []

Awesome!

-T


Not quite.

All methods that respond with --> Positional, provide a Positional that
will accept []

Methods don't accept [], values that are positional do that.

Cheers,
Donald.



Hi Donald,

I am confused.  I though we both said the same thing?
Is your distinction that [] is actually a routine in itself
and not part of the method?  And I am lumping them together?

-T

Re: Could this be any more obscure?

[Donald Hunter]

toddandma...@zoho.com (ToddAndMargo) writes:
>
> Hi Curt,
>
> Perfect! Thank you!
>
> So all methods that respond with --> Positional will accept []
>
> Awesome!
>
> -T

Not quite.

All methods that respond with --> Positional, provide a Positional that
will accept []

Methods don't accept [], values that are positional do that.

Cheers,
Donald.

Re: No. It is lucid! Re: Could this be any more obscure?

[Brandon Allbery]

That just sounds like the backing store got restored from backup, losing
anything added after the backup was taken. Which is not the best way to do
things (incrementals are nice), but if things had gone wrong enough might
have been the best they could do.

On Mon, Oct 1, 2018 at 7:13 PM ToddAndMargo  wrote:

> On 9/30/18 9:11 PM, Richard Hainsworth wrote:
> > your 'perl' box was corrupted.
>
>
> Somewhere the imap daemons got appeased and suddenly a day later,
> I watched it all come blazing back.
>
> Hopefully tomorrow I will get a chance to read over what yo wrote.
>
> By the way, the eMail I send about the thread disappearing
> got removed when the rest came back.   Hmm
>


-- 
brandon s allbery kf8nh
allber...@gmail.com

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:58 AM, JJ Merelo wrote:

There is one line per signature, or definition.


You misunderstand.  I was proposing a different
way of stating it such that you did not have to
keep repeating lines with slight differences

Re: No. It is lucid! Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 9:11 PM, Richard Hainsworth wrote:

your 'perl' box was corrupted.



Somewhere the imap daemons got appeased and suddenly a day later,
I watched it all come blazing back.

Hopefully tomorrow I will get a chance to read over what yo wrote.

By the way, the eMail I send about the thread disappearing
got removed when the rest came back.   Hmm

Re: Could this be any more obscure?

[Siavash]

You can read the thread here:
https://www.nntp.perl.org/group/perl.perl6.users/2018/09/msg5757.html

On 2018-10-01 04:21:43 +0330, ToddAndMargo wrote:
> Hi All,
>
> My "Perl" box got corrupted and in the process of rebuilding
> it I lost this thread except for one one message from JJ.
> Anyway, I am not deliberately ignoring anyone, I just
> lost the thread.
>
> :'(
>
> -T

No. It is lucid! Re: Could this be any more obscure?

[Richard Hainsworth]

Todd,

I've already added to this conversation given that your 'perl' box was 
corrupted. But when I read this post last week, I felt it needed some 
response.


You actually have touched on some deep issues. Please allow for some 
humour below.




First off, courses, beginners books, and the likes, do not work for me.

So you do not want to read beginners' stuff, just the stuff real pros want.
What does work is just code what my customers and I need. And a lot of 
what do is to Read The Freakin' Manual (RTFM, now-a-days called "just

Google it").
Read the manual. Got it. I do that a lot for many languages, eg. php, 
css, html. Actually, the manuals for css and html are bloody awful. Much 
better are tutorial sites. So the problem of documenting something 
complex in a balanced way is not unique to perl6, and it is a deep issue.


The Perl 6 routine's documentation is written as a refresher to
those how already know what they are doing, and as such is
pretty useless to common users seeking wisdom. 
But I thought you just implied you wanted pro stuff, not beginner stuff. 
So what is wanted is 'common user' stuff (see below).

Why even post
it to the general public?  The design specifications and
not posted (except if you Google them).
This is a misrepresentation of reality. Larry wrote about the 
'whirlpool' rather than 'waterfall' concept of development. Perl6 was 
not written to specs, rather the specs and the language and the tests 
(considered a part of the specs) have co-evolved. There is a link to 
them on the main perl6.org page, but the documents are historical, not 
prescriptive. And so the links to them are not given prominence, so as 
not to confuse the commoner, as it were.


*** I am not after the manual to teach me how to use Perl. ***

Well I agree, if you want beginner stuff to learn, first read a book.

In several instances, I have know how to use functions and looked
backwards in the manual to see if there were any other bits
I could use.  I COULD NOT REVERSE ENGINEER the manual
EVEN THOUGH I completely understood how to use the function.
This is bad.  Really bad.
Actually, I do not understand what you are saying at all, eg., 'I have 
know how to use ...' is not clear. Do you already know about some 
'functions' and want to know more, or do you need to know about a 
function? Even though you SHOUTED at us, I do not know what you mean by 
'reverse engineer the manual'. So I cannot fathom why not being able to 
do so is bad.


This is what I am after:

The manual should be written like a spoken language dictionary.
First 'should' is subjective to you. It is not imperative to those who 
contribute. It *is* a part of the process of writing the documentation 
to evolve a style and a terminology to accomplish several 
self-contradictory things, eg., brevity and comprehensiveness. The 
balance is not easy to accomplish, and we all want something better. 
This is a deep issue. There is no single answer for everyone.


 1) it should tell you what that word is
Everyone would agree with this point. Frankly, having read the 
documentation for other software, the perl6 docs succeed very well. 
However, I think your problem is that you don't like the terminology 
that is being developed by perl6  documentation contributors (part of 
the deep issue).


But all spoken language dictionaries (I looked up 'if' and 'as' on 
Websters, Collins, and Oxford dictionary sites) have terminology and 
special signs for pronunciation, or for grammatical function, eg., 
pronoun, conjunction, adverb. To understand a dictionary, you have to 
learn about the terminology.


If you look up words for other spoken languages, eg., Cantonese, then 
you get things like sentential particles or classifiers, neither of 
which exist in English. (A bit like the difference between perl6 and 
perl5). This means that you actually have to know something about a 
language before being able to use the dictionary, and dictionaries for 
different languages are, well, different.


 2) show you how to use it in context.
No quibble here. But perl6 documentation does provide examples. I would 
agree that there should often be more. Contributions are welcome. As 
programmers work through different contexts, they come up with 
interesting examples. I don't think anyone has rejected new examples.


And I might point out that a dictionary is not a HOW TO
book to teach you the language.
We all agree. There is a difference between reference documentation and 
tutorials. The problem is that it is difficult to discern from your own 
explanations (even this very post) what it is you want. And given my 
experience in other languages, sometimes tutorials are good, sometimes 
manuals are good. Often `stackoverflow` is the best goto. There is not a 
single experience. Personally for perl6, the docs are the best.


But I am confused about what *you* want from the reference documentation.


    3) when calling other term to explain things, it should
 

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 7:07 AM, Peter Scott wrote:
gain, covered in the excellent tutorial material that you are determined 
not to read and are instead extracting message by message from the 
members of this list. That latter approach is going to end up being more 
frustrating and alienating for you in the long term than gritting your 
teeth and forcing yourself to read a book.


Books don't work for me.  I have explained why in exhaustive detail.
My head is not hitting the table one more time.

When I learn something, I write it down in my own words with my own
examples.  I am up to 144 now.  I am, so to speak, creating
my own manual.  If you are curious, pick a topic, if I have
a Todd special for it, I will post it back.   (Pick a few, as
I may not have something on all of them.)  It will give you
an insight as to how my mind works.

By the way, schools have books.  Why is it do you suppose that
that schools also have teacher?  Should not all that be covered
in the book with complete understanding on the part of the reader?
No?

If you find my questions out of line, please just do not answer them.

Re: Could this be any more obscure?

[Richard Hainsworth]

Todd,

Since your 'perl box' got corrupted, may be you missed Yary's message 
(copied below). Yary shared a frank viewpoint that I entirely agree with.


Several people have said 'read a book'. Reading a book - even if it can 
be hard sometimes - is a courteous thing to do in a community that has 
repeatedly asked you to do so. 'round hole square peg' is not a 
courteous response.


You say you read the documentation, but when you asked for a tutorial on 
NativeCall, and I pointed out that I had added one, you said that you 
read the documentation months ago. I think I added the tutorial over a 
year ago. Which indicates you did not read the documentation. It would 
have been polite - before you posted your first request - just to check. 
In fact, the function you mentioned was complex and a short tutorial 
will never cover all the bases. So a question based on an initial 
reading would have been welcome. In fact, even though I wrote the 
tutorial, I relied on the help of several others, and I still do not 
understand all the nuances. So extra specific questions would be useful.


Your ideas about documentation that work for you conflict with mine. I 
have commented on one of your RFE's and you want considerable changes of 
style to match your whims.


That is not to say that your contributions to this community are 
unwanted, unwelcome, or trivial. The opposite is true: your questions - 
the substance not the form - have elicited some fascinating and lucid 
responses.


Further, you have mentioned several times that you write notes to 
yourself about Perl6. Why not make them available in some way, eg. on 
github (its free and there are ways to put up static html pages)?


Richard, aka finanalyst


On 01/10/18 01:26, yary wrote:

Todd, allow me to distill the situation from my POV.

There are many sources of Perl 5 docs. "perldoc -f ..." is one of 
them, and it works well for you.


There are also a choice of Perl 6 docs. "https://docs.perl6.org/"; is 
one of them, and it doesn't work well for you, but of all the perl6 
docs, it's the one you return to out of necessity.


Those two documents were built for different purposes, and 
written/generated via very different organizational structure.


As a fellow perl6 newbie, I also hit frustrating points, and I relate 
to many of your questions and posts, but '"perldocs -f xxx" is a 
bazillion times easier to understand than Perl 6's manual' makes me 
mad and not want to engage. To me that reads like a general insult. I 
imagine what you meant was "perldoc -f works better for my purposes" 
and out of the heat of the moment, I expect you'd agree, and 
eventually you post doc RFE's which is the best outcome.


An analogy. "Ikea docs are great because they explain everything with 
pictures." ok that works for me.


"I love the words method but I can't make heads or tails of 
docs.perl6.org/words . How come [] and () 
do different things? What the heck is Inf doing there?" works for me.


"Here's an RFE for the words method that summarizes what I've figured 
out. And it doesn't even have words, it's all diagrams, just like the 
Ikea manual!" ok that works for me.


"The writing on docs.perl6.org/words  is 
no good. How is anyone supposed to build software with it? Compare to 
the Ikea docs- so much better- you can build anything with them!" Not 
helpful, turns me off to the discussion.


"docs.perl6.org ." and "perdoc -f" are 
different animals, created for different goals. Yes please help 
clarify the perl6 docs, ask questions and distill the answers. Perhaps 
someday Perl 6 will have its own on-line combined 
reference-and-tutorial similar to "perldoc -f" but that is not the 
primary purpose of "docs.perl6.org ."


My request to help me remain involved in your threads: try keeping the 
broad judgments to yourself, acknowledge that these documents are 
works in progress with different goals, focus on finding the weak 
points which highlight a misunderstanding, and communicate those.



-y

On Sun, Sep 30, 2018 at 3:48 AM, ToddAndMargo > wrote:


On 9/30/18 3:02 AM, Siavash wrote:

Because one is a method and the other is a sub. Look at "List:D:".
And they are not identical, the last example showed the
difference.


The sub sure seems like it slurps to me.

$ p6 'join( ", ", 1, 2, 3).say;'
1, 2, 3

What am I missing?

Re: Could this be any more obscure?

[ToddAndMargo]

Hi All,

My "Perl" box got corrupted and in the process of rebuilding
it I lost this thread except for one one message from JJ.
Anyway, I am not deliberately ignoring anyone, I just
lost the thread.

:'(

-T

Re: Could this be any more obscure?

[yary]

Todd, allow me to distill the situation from my POV.

There are many sources of Perl 5 docs. "perldoc -f ..." is one of them, and
it works well for you.

There are also a choice of Perl 6 docs. "https://docs.perl6.org/"; is one of
them, and it doesn't work well for you, but of all the perl6 docs, it's the
one you return to out of necessity.

Those two documents were built for different purposes, and
written/generated via very different organizational structure.

As a fellow perl6 newbie, I also hit frustrating points, and I relate to
many of your questions and posts, but '"perldocs -f xxx" is a bazillion
times easier to understand than Perl 6's manual' makes me mad and not want
to engage. To me that reads like a general insult. I imagine what you meant
was "perldoc -f works better for my purposes" and out of the heat of the
moment, I expect you'd agree, and eventually you post doc RFE's which is
the best outcome.

An analogy. "Ikea docs are great because they explain everything with
pictures." ok that works for me.

"I love the words method but  I can't make heads or tails of
docs.perl6.org/words. How come [] and () do different things? What the heck
is Inf doing there?" works for me.

"Here's an RFE for the words method that summarizes what I've figured out.
And it doesn't even have words, it's all diagrams, just like the Ikea
manual!" ok that works for me.

"The writing on docs.perl6.org/words is no good. How is anyone supposed to
build software with it? Compare to the Ikea docs- so much better- you can
build anything with them!" Not helpful, turns me off to the discussion.

"docs.perl6.org." and "perdoc -f" are different animals, created for
different goals. Yes please help clarify the perl6 docs, ask questions and
distill the answers. Perhaps someday Perl 6 will have its own on-line
combined reference-and-tutorial similar to "perldoc -f" but that is not the
primary purpose of "docs.perl6.org."

My request to help me remain involved in your threads: try keeping the
broad judgments to yourself, acknowledge that these documents are works in
progress with different goals, focus on finding the weak points which
highlight a misunderstanding, and communicate those.


-y

On Sun, Sep 30, 2018 at 3:48 AM, ToddAndMargo  wrote:

> On 9/30/18 3:02 AM, Siavash wrote:
>
>> Because one is a method and the other is a sub. Look at "List:D:".
>> And they are not identical, the last example showed the difference.
>>
>
> The sub sure seems like it slurps to me.
>
> $ p6 'join( ", ", 1, 2, 3).say;'
> 1, 2, 3
>
> What am I missing?
>

Re: Could this be any more obscure?

[Peter Scott]

On 9/30/18 2:45 AM, ToddAndMargo wrote:

The manual need to be written for the common user to
understand, not just developer level and very advanced
users.  They don't need the manual anyway. 


Of course we do. I constantly refer to the Perl 5 manual rather than 
waste memory on rote information.  I'm always looking up format 
descriptors in printf, for instance, and the near-endless special cases 
in split.


The amount of syntactic capacity in function/method calls is far greater 
in Perl 6 than in Perl 5. Your argument is like asking why C functions 
are so much harder to learn than assembler where all one has to do is 
push words onto a stack and jump.  The features of signatures and types 
are much larger in Perl 6 than their Perl 5 equivalents (where 
everything is a list except for weird prototypes that even the manuals 
advise you not to use) and critical to using the language properly and 
effectively.


Understanding these key concepts among others is foundational to 
programming in Perl 6 and is, again, covered in the excellent tutorial 
material that you are determined not to read and are instead extracting 
message by message from the members of this list. That latter approach 
is going to end up being more frustrating and alienating for you in the 
long term than gritting your teeth and forcing yourself to read a book.

Re: Could this be any more obscure?

[Siavash]

In the second line of my reply I was referring to the difference in
flattening.

In the first line I was saying that sub takes a list, but method
doesn't, its invocant is a list.


On 2018-09-30 14:18:53 +0330, ToddAndMargo wrote:
> On 9/30/18 3:02 AM, Siavash wrote:
>> Because one is a method and the other is a sub. Look at "List:D:".
>> And they are not identical, the last example showed the difference.
>
> The sub sure seems like it slurps to me.
>
> $ p6 'join( ", ", 1, 2, 3).say;'
> 1, 2, 3
>
> What am I missing?

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:48 AM, JJ Merelo wrote:

Nothing less that good Oklahoma tar and turkey feathers will do.

JJ


Will do!

Perl6 is a shining example of kaisen.  Every new thing
I learn about it, I adore it.

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

Hi Todd,
I disagree with you. The P6 documentation can certainly be improved, but it
is quite good and clear already. Remember that it is technical
documentation, not a tutorial.

And the example you chose to give does not support your point: the P6
documentation for join is just at least as clear as the P5 documentation on
the same function.

When I wrote my book on Perl 6, there was no other P6 book around, so I had
to rely heavily on the existing documentation for all kinds of syntax
details, and I found that is was quite useful and even easy (and it has
improved quite a bit since then). You're welcome to help improving the
documentation, but, please, don't say it's bad just because you don't want
to make the effort needed to understand it.

If you don't understand the signatures in the documentation, you've
basically two possible solutions: just skip them, as you can certainly
understand how to use a built-in function without understanding the
signature (but it is still very useful to have the signature definition in
the documentation), or bite the bullet and learn how to read signatures.

Despite your denegation, I think that what you really need is to read a
good tutorial or book on Perl 6. If you had made a real effort to read such
introductory material, you would probably not have needed to ask about 90%
of the questions you asked lately. Do yourself a favor: read good
introductory material (tutorials or books).

HTH,
Laurent.


Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  a
écrit :

> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> > And again: this is only because you know perl 5. People are not born
> > knowing perl 5; to someone who doesn't know it, perldoc raises the same
> > kinds of questions you have been asking, and the answers have to be
> > found in perlsyn or perldata, etc. Which is exactly what you have been
> > complaining about with respect to perl 6 doing the same kind of thing.
>
> Geez Louise Bradley!  The above is a really bad argument!
>
> "perldocs -f xxx" is a bazillion times easier to understand
> than Perl 6's manual, regardless if you know Perl 5 or not.
>
> And, by the way, I wonder just how may are coming to Perl 6
> without ANY Perl 5 experience?
>
> In every instance I can look up, perldocs puts Perl 6's
> documentation to shame.
>
> A simple comparison: which one leaves you knowing how to use
> the function and which one leaves you wondering "What the h***???"
>
> $ perldoc -f join
>  join EXPR,LIST
>  Joins the separate strings of LIST into a single string with
>  fields separated by the value of EXPR, and returns that new
>  string. Example:
>
> my $rec = join(':',
> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
>
>  Beware that unlike "split", "join" doesn't take a pattern
>  as its first argument. Compare "split".
>
>
>
> https://docs.perl6.org/routine/join#(List)_routine_join
>
>  (List) routine join
>
>  Defined as:
>
>  subjoin($separator, *@list --> Str:D)
>  method join(List:D: $separator --> Str:D)
>
>  Treats the elements of the list as strings, interleaves
>  them with $separator and concatenates everything into a
>  single string.
>
>  Example:
>
>  join ', ', ; # RESULT: «a, b, c»
>
>  Note that the method form does not flatten sublists:
>
>  say (1, ).join('|'); # OUTPUT: «1|a b c␤»
>
>
> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> and the method does not?  They are suppose to be identical.
>
> -T
>

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 12:51, ToddAndMargo ()
escribió:

> On 9/30/18 3:00 AM, JJ Merelo wrote:
> > Hi
> >
> > El dom., 30 sept. 2018 a las 11:18, ToddAndMargo ( > >) escribió:
> >
> > On 9/30/18 1:21 AM, JJ Merelo wrote:
> >  >
> >  >
> >  > El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via
> > perl6-users
> >  > (mailto:perl6-users@perl.org>
> > >>)
> escribió:
> >  >
> >  > the words method is extracting items from an input string. The
> >  > $limit parameter tells the words method to extract not more
> than
> >  > $limit items from the string. Setting the default to Inf only
> > tells
> >  > the  method to extract as many items as it can from the input
> > (i.e.
> >  > to process the whole string), without any limit. But since
> > the input
> >  > string cannot be infinite, the number of items will also not
> be
> >  > infinite. So, the Inf default for $limit just states that
> > there is
> >  > no limit, but you'll never get an infinity of items from a
> >  > non-infinite string.
> >  >
> >  >
> >  > There's no Inf default now in the definition (after latest code
> >  > changes), and it's been changed in the documentation accordingly.
> > It's
> >  > left in the examples, however (since that "default" is in the
> > code too,
> >  > and is tested in roast), but that can be eliminated if it leads to
> >  > confusion.
> >  >
> >  > Cheers
> >  >
> >  > JJ
> >
> >
> > Hi JJ,
> >
> > I am confused.  I thought that
> >
> >$limit = Inf
> > used in
> >
> >multi method words(Str:D $input: $limit = Inf --> Seq)
> > meant that the default was "Inf"
> >
> >
> > It's not now: https://docs.perl6.org/routine/words#class_Str
> >
> >
> > Also, it is not stated that $limit is optional.  I would
> > propose adding a "?" to the end of $limit:
> >
> >multi method words(Str:D $input : $limit? = Inf --> Seq)
> >
> >
> > That's not how it's defined. There are two forms in the method, which
> > effectively could be resumed to a single one
> >  method words(Str:D: $limit?)
> >
> > But that's simply not how it's defined in the source. The fact that
> > there are two multis indicate quite clearly that $limit is optional, but
> > if that's not enough, the examples should clarify that.
> >
> > Cheers
> >
> > --
> > JJ
>
>
>
> Would it not be much more readable to only have one line?
> I personally get lost if there are more than two lines.
>

There is one line per signature, or definition.


-- 
JJ

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:00 AM, JJ Merelo wrote:

Hi

El dom., 30 sept. 2018 a las 11:18, ToddAndMargo (>) escribió:


On 9/30/18 1:21 AM, JJ Merelo wrote:
 >
 >
 > El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via
perl6-users
 > (mailto:perl6-users@perl.org>
>>) escribió:
 >
 >     the words method is extracting items from an input string. The
 >     $limit parameter tells the words method to extract not more than
 >     $limit items from the string. Setting the default to Inf only
tells
 >     the  method to extract as many items as it can from the input
(i.e.
 >     to process the whole string), without any limit. But since
the input
 >     string cannot be infinite, the number of items will also not be
 >     infinite. So, the Inf default for $limit just states that
there is
 >     no limit, but you'll never get an infinity of items from a
 >     non-infinite string.
 >
 >
 > There's no Inf default now in the definition (after latest code
 > changes), and it's been changed in the documentation accordingly.
It's
 > left in the examples, however (since that "default" is in the
code too,
 > and is tested in roast), but that can be eliminated if it leads to
 > confusion.
 >
 > Cheers
 >
 > JJ


Hi JJ,

I am confused.  I thought that

       $limit = Inf
used in

       multi method words(Str:D $input: $limit = Inf --> Seq)
meant that the default was "Inf"


It's not now: https://docs.perl6.org/routine/words#class_Str


Also, it is not stated that $limit is optional.  I would
propose adding a "?" to the end of $limit:

       multi method words(Str:D $input : $limit? = Inf --> Seq)


That's not how it's defined. There are two forms in the method, which 
effectively could be resumed to a single one

     method words(Str:D: $limit?)

But that's simply not how it's defined in the source. The fact that 
there are two multis indicate quite clearly that $limit is optional, but 
if that's not enough, the examples should clarify that.


Cheers

--
JJ




Would it not be much more readable to only have one line?
I personally get lost if there are more than two lines.

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 12:35, ToddAndMargo ()
escribió:

> On 9/30/18 3:17 AM, JJ Merelo wrote:
> >
> > I actually found the Perl 6 description more readable. And the example
> > is better too.
>
> I was showing the different philosophies.  And I do agree,
> the Perl 6 was one of the better descriptions.  Perl 6
> usually gets it butt kicked by perldocs.
>

See what I mean by iteration?

Cheers


-- 
JJ

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:02 AM, Siavash wrote:

Because one is a method and the other is a sub. Look at "List:D:".
And they are not identical, the last example showed the difference.


The sub sure seems like it slurps to me.

$ p6 'join( ", ", 1, 2, 3).say;'
1, 2, 3

What am I missing?

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 12:31, ToddAndMargo ()
escribió:

> On 9/30/18 3:03 AM, JJ Merelo wrote:
> >
> >
> > El dom., 30 sept. 2018 a las 11:32, ToddAndMargo ( > >) escribió:
> >
> > On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >  > And again: this is only because you know perl 5. People are not
> born
> >  > knowing perl 5; to someone who doesn't know it, perldoc raises
> > the same
> >  > kinds of questions you have been asking, and the answers have to
> be
> >  > found in perlsyn or perldata, etc. Which is exactly what you have
> > been
> >  > complaining about with respect to perl 6 doing the same kind of
> > thing.
> >
> > Geez Louise Bradley!  The above is a really bad argument!
> >
> > "perldocs -f xxx" is a bazillion times easier to understand
> > than Perl 6's manual, regardless if you know Perl 5 or not.
> >
> >
> > Hey, thanks. The (admittedly not so many) people working (on a purely
> > volunteer basis, mostly) on the Perl 6 documentation are grateful for
> > this general appreciation of our work.
> >
> > And, by the way, I wonder just how may are coming to Perl 6
> > without ANY Perl 5 experience?
> >
> >
> > Around 30%, according to the survey. That's not written in stone,
> > however, and might (and will) change in the future.
> >
> >
> > In every instance I can look up, perldocs puts Perl 6's
> > documentation to shame.
> >
> > Again, thanks. We'll stand here, quietly, waiting for the tar and
> > feathers to fall on us.
> >
> > Cheers
> >
> > JJ
> >
>
> Hi JJ,
>
> It is all part of Kaisen (constant improvement).  I am
> volunteering my very scarce time too.
>
> My apologies if my blunt description of the problem is
> offensive in any way.
>

It's not so much  the bluntness as the iteration.

>
> And yes, perldocs had a lot of year of Kaisen behind it.
>

Perl 6 docs were started, almost single-handedly, by Moritz in 2009. No
serious work (as in, more people helping, Moritz's work was quite serious
and professional) was done until circa 2012, and more serious work after
2014, leading up to the Christmas release. Approximately 200 persons have
worked on it, with ~ 40 persons putting in work (as in doing commits and
pull requests) every month. Kaizen needs time, but more than that need
human resources. That type of comparisons is unfair, but most of all it
does not really help to make improvements unless particular areas of
improvement are identified.


> -T
>
> Do you prefer chicken feather or pigeon feathers?
>
> :-)
>

Nothing less that good Oklahoma tar and turkey feathers will do.

JJ

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:17 AM, JJ Merelo wrote:


I actually found the Perl 6 description more readable. And the example
is better too.


I was showing the different philosophies.  And I do agree,
the Perl 6 was one of the better descriptions.  Perl 6
usually gets it butt kicked by perldocs.

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:17 AM, JJ Merelo wrote:


But I think the example should show the slurpy part too. (join ', ',
1, 2, 3)


It does now https://github.com/perl6/doc/issues/2344 Thanks for the 
suggestion.


Cheers



How about showing it both as a sub and as a method?

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:02 AM, Siavash wrote:

People have suggested you to try a book and you have disagreed.


Square peg, round hole

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 3:03 AM, JJ Merelo wrote:



El dom., 30 sept. 2018 a las 11:32, ToddAndMargo (>) escribió:


On 9/26/18 7:27 PM, Brandon Allbery wrote:
 > And again: this is only because you know perl 5. People are not born
 > knowing perl 5; to someone who doesn't know it, perldoc raises
the same
 > kinds of questions you have been asking, and the answers have to be
 > found in perlsyn or perldata, etc. Which is exactly what you have
been
 > complaining about with respect to perl 6 doing the same kind of
thing.

Geez Louise Bradley!  The above is a really bad argument!

"perldocs -f xxx" is a bazillion times easier to understand
than Perl 6's manual, regardless if you know Perl 5 or not.


Hey, thanks. The (admittedly not so many) people working (on a purely 
volunteer basis, mostly) on the Perl 6 documentation are grateful for 
this general appreciation of our work.


And, by the way, I wonder just how may are coming to Perl 6
without ANY Perl 5 experience?


Around 30%, according to the survey. That's not written in stone, 
however, and might (and will) change in the future.



In every instance I can look up, perldocs puts Perl 6's
documentation to shame.

Again, thanks. We'll stand here, quietly, waiting for the tar and 
feathers to fall on us.


Cheers

JJ



Hi JJ,

It is all part of Kaisen (constant improvement).  I am
volunteering my very scarce time too.

My apologies if my blunt description of the problem is
offensive in any way.

And yes, perldocs had a lot of year of Kaisen behind it.

-T

Do you prefer chicken feather or pigeon feathers?

:-)

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 2:55 AM, Laurent Rosenfeld via perl6-users wrote:
The star in the signature states that @list is a slurpy (or variadic) 
parameter, i.e. that @list will slurp up all remaining arguments 
provided to the subroutine.


See: https://docs.perl6.org/type/Signature#index-entry-slurpy_argument



Cool.  Thank you.

Why does the definition of the sub not have one?  If
it is a mistake, I will post it.

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/26/18 6:12 PM, Peter Scott wrote:

On 9/26/2018 3:21 PM, ToddAndMargo wrote:


I use words all the time.  I never would have figured it out
from

    multi method words(Str:D $input: $limit = Inf --> Positional)

Do your really think any beginner would be able to figure out
"words" from the above?


If the beginner had studied the metasyntax of function prototypes, 
probably.  But this is not necessarily for beginners, this is reference 
documentation, which has to serve a purpose unencumbered by pedagogical 
weight.  This documentation is not a tutorial, it is autogenerated.  You 
are relatively unique in insisting that the reference documentation also 
function as a beginners' roadmap, so you are going to experience this 
kind of frustration repeatedly.


I taught Perl 5 trainings for many years in addition to authoring books, 
videos, and courses on same, and the difference between what is best for 
learning and what is best for reference is stark.  I heard about people 
who claim to have taught themselves Perl 5 from the Camel instead of the 
Llama, but they are few and far between, and in any case, most of the 
Camel contains exposition, if dense. You're looking just at something 
corresponding to the list of functions.  I honestly think you'll get 
further forcing yourself to plow through the new Learning Perl 6 book 
than these random access forays into reference specs.  brian just spent 
two years of intense effort arranging it to fit precisely the graduated 
path your questions tell me you need.


Hi Peter,

First off, courses, beginners books, and the likes, do not work for me.
What does work is just code what my customers and I need. And a lot of 
what do is to Read The Freakin' Manual (RTFM, now-a-days called "just

Google it").

The Perl 6 routine's documentation is written as a refresher to
those how already know what they are doing, and as such is
pretty useless to common users seeking wisdom.  Why even post
it to the general public?  The design specifications and
not posted (except if you Google them).

*** I am not after the manual to teach me how to use Perl. ***

In several instances, I have know how to use functions and looked
backwards in the manual to see if there were any other bits
I could use.  I COULD NOT REVERSE ENGINEER the manual
EVEN THOUGH I completely understood how to use the function.
This is bad.  Really bad.

This is what I am after:

The manual should be written like a spoken language dictionary.

 1) it should tell you what that word is

 2) show you how to use it in context.

And I might point out that a dictionary is not a HOW TO
book to teach you the language.

3) when calling other term to explain things, it should
   pick the easiest term available. It should not pick
   any nasty, advanced terms.  (Unless the writer enjoys
   confusing the reader and bragging about how smart
   he is.  And he is a jerk.)

4) It can reference advanced topic or follow on topics
   but keep them out of the topic.  Dictionaries do this
   all the time. "See such and such"

5) leave the common user knowing how to use the topic,
   not wonder if the writer writes manuals for the
   IRS in his spare time.



Perl 5's perldoc did a wonderful job of this.

I have been posting RFE about this as they come up.
So I am trying to be part of the solution instead
of constantly gripping about the problem.

-T

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 12:04, Siavash ()
escribió:

>
> On 2018-09-30 13:01:32 +0330, ToddAndMargo wrote:
> > On 9/26/18 7:27 PM, Brandon Allbery wrote:
> >> And again: this is only because you know perl 5. People are not born
> >> knowing perl 5; to someone who doesn't know it, perldoc raises the
> >> same kinds of questions you have been asking, and the answers have
> >> to be found in perlsyn or perldata, etc. Which is exactly what you
> >> have been complaining about with respect to perl 6 doing the same
> >> kind of thing.
> >
> > Geez Louise Bradley!  The above is a really bad argument!
> >
> > "perldocs -f xxx" is a bazillion times easier to understand
> > than Perl 6's manual, regardless if you know Perl 5 or not.
> >
> > And, by the way, I wonder just how may are coming to Perl 6
> > without ANY Perl 5 experience?
> >
> > In every instance I can look up, perldocs puts Perl 6's
> > documentation to shame.
> >
> > A simple comparison: which one leaves you knowing how to use
> > the function and which one leaves you wondering "What the h***???"
> >
> > $ perldoc -f join
> > join EXPR,LIST
> > Joins the separate strings of LIST into a single string with
> > fields separated by the value of EXPR, and returns that new
> > string. Example:
> >
> >my $rec = join(':',
> > $login,$passwd,$uid,$gid,$gcos,$home,$shell);
> >
> > Beware that unlike "split", "join" doesn't take a pattern
> > as its first argument. Compare "split".
> >
> >
> >
> > https://docs.perl6.org/routine/join#(List)_routine_join
> >
> > (List) routine join
> >
> > Defined as:
> >
> > subjoin($separator, *@list --> Str:D)
> > method join(List:D: $separator --> Str:D)
> >
> > Treats the elements of the list as strings, interleaves
> > them with $separator and concatenates everything into a
> > single string.
> >
> > Example:
> >
> > join ', ', ; # RESULT: «a, b, c»
> >
> > Note that the method form does not flatten sublists:
> >
> > say (1, ).join('|'); # OUTPUT: «1|a b c␤»
> >
>
> I actually found the Perl 6 description more readable. And the example
> is better too.
>
> But I think the example should show the slurpy part too. (join ', ', 1, 2,
> 3)
>

It does now https://github.com/perl6/doc/issues/2344 Thanks for the
suggestion.

Cheers

JJ

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 11:32, ToddAndMargo ()
escribió:

> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> > And again: this is only because you know perl 5. People are not born
> > knowing perl 5; to someone who doesn't know it, perldoc raises the same
> > kinds of questions you have been asking, and the answers have to be
> > found in perlsyn or perldata, etc. Which is exactly what you have been
> > complaining about with respect to perl 6 doing the same kind of thing.
>
> Geez Louise Bradley!  The above is a really bad argument!
>
> "perldocs -f xxx" is a bazillion times easier to understand
> than Perl 6's manual, regardless if you know Perl 5 or not.
>

Hey, thanks. The (admittedly not so many) people working (on a purely
volunteer basis, mostly) on the Perl 6 documentation are grateful for this
general appreciation of our work.


>
> And, by the way, I wonder just how may are coming to Perl 6
> without ANY Perl 5 experience?
>

Around 30%, according to the survey. That's not written in stone, however,
and might (and will) change in the future.


> In every instance I can look up, perldocs puts Perl 6's
> documentation to shame.
>
> Again, thanks. We'll stand here, quietly, waiting for the tar and feathers
to fall on us.

Cheers

JJ

Re: Could this be any more obscure?

[Siavash]

On 2018-09-30 13:01:32 +0330, ToddAndMargo wrote:
> On 9/26/18 7:27 PM, Brandon Allbery wrote:
>> And again: this is only because you know perl 5. People are not born
>> knowing perl 5; to someone who doesn't know it, perldoc raises the
>> same kinds of questions you have been asking, and the answers have
>> to be found in perlsyn or perldata, etc. Which is exactly what you
>> have been complaining about with respect to perl 6 doing the same
>> kind of thing.
>
> Geez Louise Bradley!  The above is a really bad argument!
>
> "perldocs -f xxx" is a bazillion times easier to understand
> than Perl 6's manual, regardless if you know Perl 5 or not.
>
> And, by the way, I wonder just how may are coming to Perl 6
> without ANY Perl 5 experience?
>
> In every instance I can look up, perldocs puts Perl 6's
> documentation to shame.
>
> A simple comparison: which one leaves you knowing how to use
> the function and which one leaves you wondering "What the h***???"
>
> $ perldoc -f join
> join EXPR,LIST
> Joins the separate strings of LIST into a single string with
> fields separated by the value of EXPR, and returns that new
> string. Example:
>
>my $rec = join(':',
> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
>
> Beware that unlike "split", "join" doesn't take a pattern
> as its first argument. Compare "split".
>
>
>
> https://docs.perl6.org/routine/join#(List)_routine_join
>
> (List) routine join
>
> Defined as:
>
> subjoin($separator, *@list --> Str:D)
> method join(List:D: $separator --> Str:D)
>
> Treats the elements of the list as strings, interleaves
> them with $separator and concatenates everything into a
> single string.
>
> Example:
>
> join ', ', ; # RESULT: «a, b, c»
>
> Note that the method form does not flatten sublists:
>
> say (1, ).join('|'); # OUTPUT: «1|a b c␤»
>

I actually found the Perl 6 description more readable. And the example
is better too.

But I think the example should show the slurpy part too. (join ', ', 1, 2, 3)

>
> Oh and what the &*@% is a "*@list"?

It seems you want to read a signature without learning how signatures
work.
https://docs.perl6.org/type/Signature#Slurpy_%28A.K.A._variadic%29_parameters

> And why does the sub have one
> and the method does not?  They are suppose to be identical.
>
> -T

Because one is a method and the other is a sub. Look at "List:D:".
And they are not identical, the last example showed the difference.

People have suggested you to try a book and you have disagreed. But to
me it looks like you are reading different chapters of a book different
people are writing for you on the mailing list.

Re: Could this be any more obscure?

[JJ Merelo]

Hi

El dom., 30 sept. 2018 a las 11:18, ToddAndMargo ()
escribió:

> On 9/30/18 1:21 AM, JJ Merelo wrote:
> >
> >
> > El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via perl6-users
> > (mailto:perl6-users@perl.org>>) escribió:
> >
> > the words method is extracting items from an input string. The
> > $limit parameter tells the words method to extract not more than
> > $limit items from the string. Setting the default to Inf only tells
> > the  method to extract as many items as it can from the input (i.e.
> > to process the whole string), without any limit. But since the input
> > string cannot be infinite, the number of items will also not be
> > infinite. So, the Inf default for $limit just states that there is
> > no limit, but you'll never get an infinity of items from a
> > non-infinite string.
> >
> >
> > There's no Inf default now in the definition (after latest code
> > changes), and it's been changed in the documentation accordingly. It's
> > left in the examples, however (since that "default" is in the code too,
> > and is tested in roast), but that can be eliminated if it leads to
> > confusion.
> >
> > Cheers
> >
> > JJ
>
>
> Hi JJ,
>
> I am confused.  I thought that
>
>   $limit = Inf
> used in
>
>   multi method words(Str:D $input: $limit = Inf --> Seq)
> meant that the default was "Inf"
>

It's not now: https://docs.perl6.org/routine/words#class_Str

>
> Also, it is not stated that $limit is optional.  I would
> propose adding a "?" to the end of $limit:
>
>   multi method words(Str:D $input : $limit? = Inf --> Seq)
>

That's not how it's defined. There are two forms in the method, which
effectively could be resumed to a single one
method words(Str:D: $limit?)

But that's simply not how it's defined in the source. The fact that there
are two multis indicate quite clearly that $limit is optional, but if
that's not enough, the examples should clarify that.

Cheers

-- 
JJ

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

The star in the signature states that @list is a slurpy (or variadic)
parameter, i.e. that @list will slurp up all remaining arguments provided
to the subroutine.

See: https://docs.perl6.org/type/Signature#index-entry-slurpy_argument



Le dim. 30 sept. 2018 à 11:32, ToddAndMargo  a
écrit :

> On 9/26/18 7:27 PM, Brandon Allbery wrote:
> > And again: this is only because you know perl 5. People are not born
> > knowing perl 5; to someone who doesn't know it, perldoc raises the same
> > kinds of questions you have been asking, and the answers have to be
> > found in perlsyn or perldata, etc. Which is exactly what you have been
> > complaining about with respect to perl 6 doing the same kind of thing.
>
> Geez Louise Bradley!  The above is a really bad argument!
>
> "perldocs -f xxx" is a bazillion times easier to understand
> than Perl 6's manual, regardless if you know Perl 5 or not.
>
> And, by the way, I wonder just how may are coming to Perl 6
> without ANY Perl 5 experience?
>
> In every instance I can look up, perldocs puts Perl 6's
> documentation to shame.
>
> A simple comparison: which one leaves you knowing how to use
> the function and which one leaves you wondering "What the h***???"
>
> $ perldoc -f join
>  join EXPR,LIST
>  Joins the separate strings of LIST into a single string with
>  fields separated by the value of EXPR, and returns that new
>  string. Example:
>
> my $rec = join(':',
> $login,$passwd,$uid,$gid,$gcos,$home,$shell);
>
>  Beware that unlike "split", "join" doesn't take a pattern
>  as its first argument. Compare "split".
>
>
>
> https://docs.perl6.org/routine/join#(List)_routine_join
>
>  (List) routine join
>
>  Defined as:
>
>  subjoin($separator, *@list --> Str:D)
>  method join(List:D: $separator --> Str:D)
>
>  Treats the elements of the list as strings, interleaves
>  them with $separator and concatenates everything into a
>  single string.
>
>  Example:
>
>  join ', ', ; # RESULT: «a, b, c»
>
>  Note that the method form does not flatten sublists:
>
>  say (1, ).join('|'); # OUTPUT: «1|a b c␤»
>
>
> Oh and what the &*@% is a "*@list"?  And why does the sub have one
> and the method does not?  They are suppose to be identical.
>
> -T
>

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 2:37 AM, Laurent Rosenfeld via perl6-users wrote:
There is no need for a question mark after the $limit parameter, since 
supplying a default value for a parameter is sufficient to make this 
parameter optional.



In this instance "yes", it is redundant.

But, other instances where a default value is not provided
and the variable is optional, "no".

And "yes" in all instances as it makes it more readable,
EVEN IF it has some redundancy in it. If one hint doesn't
get you, the other will.

Also, the "?" makes it clear that the variable is
optional.  Supplying it with a default value does not
always sink it that it is optional, unless you have had
to go through the pain of decrypting it once before

The goal is to make the documentation easy to use.  It
should not require a herculean effort to understand.
The manual need to be written for the common user to
understand, not just developer level and very advanced
users.  They don't need the manual anyway.

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

There is no need for a question mark after the $limit parameter, since
supplying a default value for a parameter is sufficient to make this
parameter optional.



Le dim. 30 sept. 2018 à 11:17, ToddAndMargo  a
écrit :

> On 9/30/18 1:21 AM, JJ Merelo wrote:
> >
> >
> > El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via perl6-users
> > (mailto:perl6-users@perl.org>>) escribió:
> >
> > the words method is extracting items from an input string. The
> > $limit parameter tells the words method to extract not more than
> > $limit items from the string. Setting the default to Inf only tells
> > the  method to extract as many items as it can from the input (i.e.
> > to process the whole string), without any limit. But since the input
> > string cannot be infinite, the number of items will also not be
> > infinite. So, the Inf default for $limit just states that there is
> > no limit, but you'll never get an infinity of items from a
> > non-infinite string.
> >
> >
> > There's no Inf default now in the definition (after latest code
> > changes), and it's been changed in the documentation accordingly. It's
> > left in the examples, however (since that "default" is in the code too,
> > and is tested in roast), but that can be eliminated if it leads to
> > confusion.
> >
> > Cheers
> >
> > JJ
>
>
> Hi JJ,
>
> I am confused.  I thought that
>
>   $limit = Inf
> used in
>
>   multi method words(Str:D $input: $limit = Inf --> Seq)
> meant that the default was "Inf"
>
> Also, it is not stated that $limit is optional.  I would
> propose adding a "?" to the end of $limit:
>
>   multi method words(Str:D $input : $limit? = Inf --> Seq)
>
> This would keep with the subroutine rules for the declarations
> of optional variables.
>
> -T
>

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/26/18 7:27 PM, Brandon Allbery wrote:
And again: this is only because you know perl 5. People are not born 
knowing perl 5; to someone who doesn't know it, perldoc raises the same 
kinds of questions you have been asking, and the answers have to be 
found in perlsyn or perldata, etc. Which is exactly what you have been 
complaining about with respect to perl 6 doing the same kind of thing.


Geez Louise Bradley!  The above is a really bad argument!

"perldocs -f xxx" is a bazillion times easier to understand
than Perl 6's manual, regardless if you know Perl 5 or not.

And, by the way, I wonder just how may are coming to Perl 6
without ANY Perl 5 experience?

In every instance I can look up, perldocs puts Perl 6's
documentation to shame.

A simple comparison: which one leaves you knowing how to use
the function and which one leaves you wondering "What the h***???"

$ perldoc -f join
join EXPR,LIST
Joins the separate strings of LIST into a single string with
fields separated by the value of EXPR, and returns that new
string. Example:

   my $rec = join(':', 
$login,$passwd,$uid,$gid,$gcos,$home,$shell);


Beware that unlike "split", "join" doesn't take a pattern
as its first argument. Compare "split".



https://docs.perl6.org/routine/join#(List)_routine_join

(List) routine join

Defined as:

subjoin($separator, *@list --> Str:D)
method join(List:D: $separator --> Str:D)

Treats the elements of the list as strings, interleaves
them with $separator and concatenates everything into a
single string.

Example:

join ', ', ; # RESULT: «a, b, c»

Note that the method form does not flatten sublists:

say (1, ).join('|'); # OUTPUT: «1|a b c␤»


Oh and what the &*@% is a "*@list"?  And why does the sub have one
and the method does not?  They are suppose to be identical.

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/30/18 1:21 AM, JJ Merelo wrote:



El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via perl6-users 
(mailto:perl6-users@perl.org>>) escribió:


the words method is extracting items from an input string. The
$limit parameter tells the words method to extract not more than
$limit items from the string. Setting the default to Inf only tells
the  method to extract as many items as it can from the input (i.e.
to process the whole string), without any limit. But since the input
string cannot be infinite, the number of items will also not be
infinite. So, the Inf default for $limit just states that there is
no limit, but you'll never get an infinity of items from a
non-infinite string.


There's no Inf default now in the definition (after latest code 
changes), and it's been changed in the documentation accordingly. It's 
left in the examples, however (since that "default" is in the code too, 
and is tested in roast), but that can be eliminated if it leads to 
confusion.


Cheers

JJ



Hi JJ,

I am confused.  I thought that

 $limit = Inf
used in

 multi method words(Str:D $input: $limit = Inf --> Seq)
meant that the default was "Inf"

Also, it is not stated that $limit is optional.  I would
propose adding a "?" to the end of $limit:

 multi method words(Str:D $input : $limit? = Inf --> Seq)

This would keep with the subroutine rules for the declarations
of optional variables.

-T

Re: Could this be any more obscure?

[JJ Merelo]

El dom., 30 sept. 2018 a las 10:15, Laurent Rosenfeld via perl6-users (<
perl6-users@perl.org>) escribió:

> the words method is extracting items from an input string. The $limit
> parameter tells the words method to extract not more than $limit items from
> the string. Setting the default to Inf only tells the  method to extract as
> many items as it can from the input (i.e. to process the whole string),
> without any limit. But since the input string cannot be infinite, the
> number of items will also not be infinite. So, the Inf default for $limit
> just states that there is no limit, but you'll never get an infinity of
> items from a non-infinite string.
>

There's no Inf default now in the definition (after latest code changes),
and it's been changed in the documentation accordingly. It's left in the
examples, however (since that "default" is in the code too, and is tested
in roast), but that can be eliminated if it leads to confusion.

Cheers

JJ

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

the words method is extracting items from an input string. The $limit
parameter tells the words method to extract not more than $limit items from
the string. Setting the default to Inf only tells the  method to extract as
many items as it can from the input (i.e. to process the whole string),
without any limit. But since the input string cannot be infinite, the
number of items will also not be infinite. So, the Inf default for $limit
just states that there is no limit, but you'll never get an infinity of
items from a non-infinite string.



Le ven. 28 sept. 2018 à 19:31, ToddAndMargo  a
écrit :

> On 9/26/18 11:34 PM, JJ Merelo wrote:
> >
> >
> > El mié., 26 sept. 2018 a las 23:31, Laurent Rosenfeld via perl6-users
> > (mailto:perl6-users@perl.org>>) escribió:
> >
> > You can set a limit to the number of items (words) you want to
> > retrieve: you will get only the first $limit words.
> >
> > If you don't supply any limit, Inf can be thought as the default
> > value for the number of items, i.e. there is no limit and the
> > routine will return as many words as it can from the source input.
> >
> >
> > And this is one of the things I love Perl 6 for, its consistency.
> > Infinity is literally no limit. Using it meaning "no limit" is genius.
> > Not "0 in this case means no limit" or "-1 means no limit" or "this
> > constant meaning unavailable" or whatever. Infinity has no limit, we use
> > them as a parameter to imply that argument has no limit.
> >
> > Cheers
> >
> > JJ
>
>
> Hi JJ,
>
> The more I learn about Perl 6, the more I prefer it over Perl 5.
>
> To your list, I might add, everything starts counting from zero
> (Perl5 m/ starts at $1).  So no guessing!
>
> My problem with the default set to Inf is that Inf means a number
> too large for the numbers of bits allocated to the variable to
> handle.
>
> RTFM: https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
>   The value Inf is an instance of Num and represents value that's
>   too large to represent in 64-bit double-precision floating
>   point number (roughly, above 1.7976931348623158e308 for
>   positive Inf and below -1.7976931348623157e308 for negative Inf)
>   as well as returned from certain operations as defined by the
>   IEEE 754-2008 standard.
>
> So how am I suppose to enter that as a value?  What it really means
> is "all of them".  "Inf" is just a poor way of stating "all words"
> as the default.  "A tremendously large numbers of words" is just
> a weird way of saying "all of them".
>
> And yes, I am blanking on how to best clean that up. We have no
> value (that I know of) for "all".
>
> -T
>

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/29/18 12:44 AM, JJ Merelo wrote:


       Inf when used as an instance of Num and represents a
       value that's too large to represent in 64-bit double-precision
s      floating point number


Not "when". Inf _is_ a Num. And it does not represent that. You can 
represent any number with double or simple precision, only, well, you'll 
lose some precision.



Very well stated.

In the above, I was quoting the manual for Inf.  I do not even think it
should be in there.  I will post an RFE in a few minutes

Re: Could this be any more obscure?

[JJ Merelo]

Hi

El sáb., 29 sept. 2018 a las 7:53, ToddAndMargo ()
escribió:

> Proposed addition to "words":
>
>   "$limits" is an optional argument.  When left empty, the
>   value defaults to Inf (Infinity), meaning "without bound"
>   or "no limit"
>
>
Inf means without bonds _always_. It says so in the wikipedia definition
you have used above.

Proposed addition to "Inf":
>
>   The value Inf (Infinity) represents "without bound" or
>   "no limit" (meaning "all possible values") when used
>   as an argument.
>

It means that when used as an argument, and when it's not used an argument,
as in, that is what it is. It means without bonds when assigned to a
variable, and when you see it sitting pretty in the middle of a long
sentence. It _means_ that.


>   Inf when used as an instance of Num and represents a
>   value that's too large to represent in 64-bit double-precision
> s  floating point number
>

Not "when". Inf _is_ a Num. And it does not represent that. You can
represent any number with double or simple precision, only, well, you'll
lose some precision.


> Oh my goodness gracious did you top yourself with Perl 6.  I love
> it.  You are some kind of freaking genius that only occurs in humans
> every 100 years of so.  You do not want newcomers running screaming
> in terror when they first see the documentation: "make simple things
> complicated and the complicated ones impossible."
>

As in inserting a symbol like Infinity into a language so that when you
want to use it as a loop bookend it never ends, no matter what happens? Or
using Inf exactly by its meaning, "larger than anything". How do you do
that in other languages? You do all kind of things. You can have a special
constant, use 0 or -1 as limit (or some other impossible number which you
have to interpret ad hoc), or simply have different signatures for with or
without limits. How's that any simpler than using Infinity meaning no
limits, and always meaning no limits?
Perl 6 makes writing programs meaningful and expressive. That's achieved
through clever language design, such as this simple thing.

Cheers

JJ

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 6:28 PM, Larry Wall wrote:

On Fri, Sep 28, 2018 at 03:50:31PM -0700, ToddAndMargo wrote:
: On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:
: > > I am NOT asking it to limit my request to Infinity.
: >
: >Yes you are, implicitly. If you don't pass any parameter for
: >$limit, $limit will take the default value supplied by the
: >signature, i.e. Inf.
:
: True, but that is not what the manual says Inf is.  Lower in this
: thread I made a suggest addition to the wording of Inf.  Would
: you mind looking at it and offering your criticism?

Why do you want to burden the definition of what something *is* with
all the things you can *do* with it?  The former is tractable, while
the latter is not.

It seems to me that you are applying a different standard to human and
computer languages here.  In both human and computer languages, what
something *is* has little to do with what something *does*.  These are
different abstraction levels.  You're fine with this in English, so
trying to flatten out all the abstraction levels is tending to work
against your understanding of computer languages here, I suspect.

The word "knife" is a noun, but if I "knife" someone, I'm using a noun
(what the word is) as a verb (what the word can do).  Human language is
full of these borrowings of abstraction level, so much so that linguists
even have a name for them in general, the "emic vs etic" distinction.
In non-linguistic terms, "what you said vs what you really meant".
What it is, vs what it does.

Originally these were coined on the phonetic vs phonemic level, so we
see lots of places in English where the phonetics don't match up with
how they are used:

 The prince made some prints.

Here you pronounce those words identically on a phonetic level, but on
a higher phonemic level (or even on a morphophonemic level), "prince" is
only one morpheme, while "prints" is two morphemes "print" and the plural
"s".  But this etic/emic distinction works at higher levels as well:

 Here's a you-can-even-use-a-sentence-as-an-adjective example.

Here the etic description of "you-can-even-use-a-sentence-as-an-adjective"
is that of a sentence.  That's what it *is*.  But language is flexible
enough that I can choose (emically) to slot the whole sentence in as
a adjective.  That's what the sentence can *do*.  (Or that's what you
can do with a sentence, if you prefer.)  The fact that you can do this
takes nothing away from what a sentence *is*, because that's at a lower
abstraction level.

Going up the linguistic stack even further, every time you read a metaphor
in a poem (or in a newspaper article for that matter), you are using
your knowledge of English to realize that the poet (or reporter) is
relying on you, the Gentle Reader, to realize that the writer is
using a metaphor.  A metaphor is when you say one thing but mean
something else by it.  The words of a metaphor are what it "is", but
the meaning it produces in your brain is what it "does".

The fact that the $limit is using a particular value with a particular
representation in memory ("what the manual says Inf is") has almost
nothing to do with how we choose to use it metaphorically in an interface,
except insofar as it's extremely convenient to have a floating-point value
that happens to compare as larger than any integer you want to name.
That comparison is a thing that Inf can *do*, which is the abstraction level on
which the $limit API is working.  The fact that it can be used this way
is not at all contradictory to the description of what the Inf value *is*.

But the description of what it can do really belongs on the many places
where it can be used in various metaphorical ways, not in the definition
of what it is.  The floating-point Inf value really has no clue whatsoever
about all the ways it might be used.  It probably doesn't even realize
it can be compared with an integer.  :)

Larry




Hi Larry,

I really enjoyed the read.  Thank you!

Now in my personal life, I am really guilty of telling
bad jokes:

Two guys walked into a bar.
A third guy ducked.

This goes to your beautifully written example of the
writer expecting the reader to realize he is using a
metaphor.  It is up to the "victim" of my bad joke to
realize that "bar" has two meanings: a place
where alcoholic beverages are sold and a metal rod.

In programming and in other things mathematical, you
expect definitions to be literal.  You do not expect
metaphors.  The "literal" definition of Infinity is
what made me realize what was happening.  I will
explain more in a follow paragraphs.

Now I do adore the "words" method and use it frequently.
When I went to the manual to see if there was any other way
to use it, I was astonished at how they got from point A
to point B.  This is because I took the definition of Inf
in the manual literally.

Now look up the definition of Infinity, which is to
be taken literally

   https://en.wikipedia.org/wiki/Infinity
  Infinity (symbol: ∞) is 

RE: Could this be any more obscure?

[Mark Devine]

I guess I’m extra impressed with esoteric linguistic references.  Your replies 
were concise and I understood them pretty quickly.

Mark


From: Brandon Allbery 
Sent: Friday, September 28, 2018 21:51
To: Mark Devine 
Cc: la...@wall.org; ToddAndMargo ; perl6-users 

Subject: Re: Could this be any more obscure?

I'm not sure it's any better than my attempt; it has that "people's eyes will 
glaze over" feel to it.

On Fri, Sep 28, 2018 at 9:50 PM Mark Devine 
mailto:m...@markdevine.com>> wrote:
Kudos to the Benevolent Dictator!

I'll have to loop over this a few times, but it's a blast...

Mark

-Original Message-
From: Larry Wall mailto:la...@wall.org>>
Sent: Friday, September 28, 2018 21:28
To: ToddAndMargo mailto:toddandma...@zoho.com>>
Cc: perl6-users@perl.org<mailto:perl6-users@perl.org>
Subject: Re: Could this be any more obscure?

On Fri, Sep 28, 2018 at 03:50:31PM -0700, ToddAndMargo wrote:
: On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:
: > > I am NOT asking it to limit my request to Infinity.
: >
: >Yes you are, implicitly. If you don't pass any parameter for
: >$limit, $limit will take the default value supplied by the
: >signature, i.e. Inf.
:
: True, but that is not what the manual says Inf is.  Lower in this
: thread I made a suggest addition to the wording of Inf.  Would
: you mind looking at it and offering your criticism?

Why do you want to burden the definition of what something *is* with all the 
things you can *do* with it?  The former is tractable, while the latter is not.

It seems to me that you are applying a different standard to human and computer 
languages here.  In both human and computer languages, what something *is* has 
little to do with what something *does*.  These are different abstraction 
levels.  You're fine with this in English, so trying to flatten out all the 
abstraction levels is tending to work against your understanding of computer 
languages here, I suspect.

The word "knife" is a noun, but if I "knife" someone, I'm using a noun (what 
the word is) as a verb (what the word can do).  Human language is full of these 
borrowings of abstraction level, so much so that linguists even have a name for 
them in general, the "emic vs etic" distinction.
In non-linguistic terms, "what you said vs what you really meant".
What it is, vs what it does.

Originally these were coined on the phonetic vs phonemic level, so we see lots 
of places in English where the phonetics don't match up with how they are used:

The prince made some prints.

Here you pronounce those words identically on a phonetic level, but on a higher 
phonemic level (or even on a morphophonemic level), "prince" is only one 
morpheme, while "prints" is two morphemes "print" and the plural "s".  But this 
etic/emic distinction works at higher levels as well:

Here's a you-can-even-use-a-sentence-as-an-adjective example.

Here the etic description of "you-can-even-use-a-sentence-as-an-adjective"
is that of a sentence.  That's what it *is*.  But language is flexible enough 
that I can choose (emically) to slot the whole sentence in as a adjective.  
That's what the sentence can *do*.  (Or that's what you can do with a sentence, 
if you prefer.)  The fact that you can do this takes nothing away from what a 
sentence *is*, because that's at a lower abstraction level.

Going up the linguistic stack even further, every time you read a metaphor in a 
poem (or in a newspaper article for that matter), you are using your knowledge 
of English to realize that the poet (or reporter) is relying on you, the Gentle 
Reader, to realize that the writer is using a metaphor.  A metaphor is when you 
say one thing but mean something else by it.  The words of a metaphor are what 
it "is", but the meaning it produces in your brain is what it "does".

The fact that the $limit is using a particular value with a particular 
representation in memory ("what the manual says Inf is") has almost nothing to 
do with how we choose to use it metaphorically in an interface, except insofar 
as it's extremely convenient to have a floating-point value that happens to 
compare as larger than any integer you want to name.
That comparison is a thing that Inf can *do*, which is the abstraction level on 
which the $limit API is working.  The fact that it can be used this way is not 
at all contradictory to the description of what the Inf value *is*.

But the description of what it can do really belongs on the many places where 
it can be used in various metaphorical ways, not in the definition of what it 
is.  The floating-point Inf value really has no clue whatsoever about all the 
ways it might be used.  It probably doesn't even realize it can be compared 
with an integer.  :)

Larry


--
brandon s allbery kf8nh
allber...@gmail.com<mailto:allber...@gmail.com>

Re: Could this be any more obscure?

[Brandon Allbery]

I'm not sure it's any better than my attempt; it has that "people's eyes
will glaze over" feel to it.

On Fri, Sep 28, 2018 at 9:50 PM Mark Devine  wrote:

> Kudos to the Benevolent Dictator!
>
> I'll have to loop over this a few times, but it's a blast...
>
> Mark
>
> -Original Message-
> From: Larry Wall 
> Sent: Friday, September 28, 2018 21:28
> To: ToddAndMargo 
> Cc: perl6-users@perl.org
> Subject: Re: Could this be any more obscure?
>
> On Fri, Sep 28, 2018 at 03:50:31PM -0700, ToddAndMargo wrote:
> : On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:
> : > > I am NOT asking it to limit my request to Infinity.
> : >
> : >Yes you are, implicitly. If you don't pass any parameter for
> : >$limit, $limit will take the default value supplied by the
> : >signature, i.e. Inf.
> :
> : True, but that is not what the manual says Inf is.  Lower in this
> : thread I made a suggest addition to the wording of Inf.  Would
> : you mind looking at it and offering your criticism?
>
> Why do you want to burden the definition of what something *is* with all
> the things you can *do* with it?  The former is tractable, while the latter
> is not.
>
> It seems to me that you are applying a different standard to human and
> computer languages here.  In both human and computer languages, what
> something *is* has little to do with what something *does*.  These are
> different abstraction levels.  You're fine with this in English, so trying
> to flatten out all the abstraction levels is tending to work against your
> understanding of computer languages here, I suspect.
>
> The word "knife" is a noun, but if I "knife" someone, I'm using a noun
> (what the word is) as a verb (what the word can do).  Human language is
> full of these borrowings of abstraction level, so much so that linguists
> even have a name for them in general, the "emic vs etic" distinction.
> In non-linguistic terms, "what you said vs what you really meant".
> What it is, vs what it does.
>
> Originally these were coined on the phonetic vs phonemic level, so we see
> lots of places in English where the phonetics don't match up with how they
> are used:
>
> The prince made some prints.
>
> Here you pronounce those words identically on a phonetic level, but on a
> higher phonemic level (or even on a morphophonemic level), "prince" is only
> one morpheme, while "prints" is two morphemes "print" and the plural "s".
> But this etic/emic distinction works at higher levels as well:
>
> Here's a you-can-even-use-a-sentence-as-an-adjective example.
>
> Here the etic description of "you-can-even-use-a-sentence-as-an-adjective"
> is that of a sentence.  That's what it *is*.  But language is flexible
> enough that I can choose (emically) to slot the whole sentence in as a
> adjective.  That's what the sentence can *do*.  (Or that's what you can do
> with a sentence, if you prefer.)  The fact that you can do this takes
> nothing away from what a sentence *is*, because that's at a lower
> abstraction level.
>
> Going up the linguistic stack even further, every time you read a metaphor
> in a poem (or in a newspaper article for that matter), you are using your
> knowledge of English to realize that the poet (or reporter) is relying on
> you, the Gentle Reader, to realize that the writer is using a metaphor.  A
> metaphor is when you say one thing but mean something else by it.  The
> words of a metaphor are what it "is", but the meaning it produces in your
> brain is what it "does".
>
> The fact that the $limit is using a particular value with a particular
> representation in memory ("what the manual says Inf is") has almost nothing
> to do with how we choose to use it metaphorically in an interface, except
> insofar as it's extremely convenient to have a floating-point value that
> happens to compare as larger than any integer you want to name.
> That comparison is a thing that Inf can *do*, which is the abstraction
> level on which the $limit API is working.  The fact that it can be used
> this way is not at all contradictory to the description of what the Inf
> value *is*.
>
> But the description of what it can do really belongs on the many places
> where it can be used in various metaphorical ways, not in the definition of
> what it is.  The floating-point Inf value really has no clue whatsoever
> about all the ways it might be used.  It probably doesn't even realize it
> can be compared with an integer.  :)
>
> Larry
>


-- 
brandon s allbery kf8nh
allber...@gmail.com

RE: Could this be any more obscure?

[Mark Devine]

Kudos to the Benevolent Dictator!

I'll have to loop over this a few times, but it's a blast...

Mark

-Original Message-
From: Larry Wall  
Sent: Friday, September 28, 2018 21:28
To: ToddAndMargo 
Cc: perl6-users@perl.org
Subject: Re: Could this be any more obscure?

On Fri, Sep 28, 2018 at 03:50:31PM -0700, ToddAndMargo wrote:
: On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:
: > > I am NOT asking it to limit my request to Infinity.
: >
: >Yes you are, implicitly. If you don't pass any parameter for
: >$limit, $limit will take the default value supplied by the
: >signature, i.e. Inf.
: 
: True, but that is not what the manual says Inf is.  Lower in this
: thread I made a suggest addition to the wording of Inf.  Would
: you mind looking at it and offering your criticism?

Why do you want to burden the definition of what something *is* with all the 
things you can *do* with it?  The former is tractable, while the latter is not.

It seems to me that you are applying a different standard to human and computer 
languages here.  In both human and computer languages, what something *is* has 
little to do with what something *does*.  These are different abstraction 
levels.  You're fine with this in English, so trying to flatten out all the 
abstraction levels is tending to work against your understanding of computer 
languages here, I suspect.

The word "knife" is a noun, but if I "knife" someone, I'm using a noun (what 
the word is) as a verb (what the word can do).  Human language is full of these 
borrowings of abstraction level, so much so that linguists even have a name for 
them in general, the "emic vs etic" distinction.
In non-linguistic terms, "what you said vs what you really meant".
What it is, vs what it does.

Originally these were coined on the phonetic vs phonemic level, so we see lots 
of places in English where the phonetics don't match up with how they are used:

The prince made some prints.

Here you pronounce those words identically on a phonetic level, but on a higher 
phonemic level (or even on a morphophonemic level), "prince" is only one 
morpheme, while "prints" is two morphemes "print" and the plural "s".  But this 
etic/emic distinction works at higher levels as well:

Here's a you-can-even-use-a-sentence-as-an-adjective example.

Here the etic description of "you-can-even-use-a-sentence-as-an-adjective"
is that of a sentence.  That's what it *is*.  But language is flexible enough 
that I can choose (emically) to slot the whole sentence in as a adjective.  
That's what the sentence can *do*.  (Or that's what you can do with a sentence, 
if you prefer.)  The fact that you can do this takes nothing away from what a 
sentence *is*, because that's at a lower abstraction level.

Going up the linguistic stack even further, every time you read a metaphor in a 
poem (or in a newspaper article for that matter), you are using your knowledge 
of English to realize that the poet (or reporter) is relying on you, the Gentle 
Reader, to realize that the writer is using a metaphor.  A metaphor is when you 
say one thing but mean something else by it.  The words of a metaphor are what 
it "is", but the meaning it produces in your brain is what it "does".

The fact that the $limit is using a particular value with a particular 
representation in memory ("what the manual says Inf is") has almost nothing to 
do with how we choose to use it metaphorically in an interface, except insofar 
as it's extremely convenient to have a floating-point value that happens to 
compare as larger than any integer you want to name.
That comparison is a thing that Inf can *do*, which is the abstraction level on 
which the $limit API is working.  The fact that it can be used this way is not 
at all contradictory to the description of what the Inf value *is*.

But the description of what it can do really belongs on the many places where 
it can be used in various metaphorical ways, not in the definition of what it 
is.  The floating-point Inf value really has no clue whatsoever about all the 
ways it might be used.  It probably doesn't even realize it can be compared 
with an integer.  :)

Larry

Re: Could this be any more obscure?

[Larry Wall]

On Fri, Sep 28, 2018 at 03:50:31PM -0700, ToddAndMargo wrote:
: On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:
: > > I am NOT asking it to limit my request to Infinity.
: >
: >Yes you are, implicitly. If you don't pass any parameter for
: >$limit, $limit will take the default value supplied by the
: >signature, i.e. Inf.
: 
: True, but that is not what the manual says Inf is.  Lower in this
: thread I made a suggest addition to the wording of Inf.  Would
: you mind looking at it and offering your criticism?

Why do you want to burden the definition of what something *is* with
all the things you can *do* with it?  The former is tractable, while
the latter is not.

It seems to me that you are applying a different standard to human and
computer languages here.  In both human and computer languages, what
something *is* has little to do with what something *does*.  These are
different abstraction levels.  You're fine with this in English, so
trying to flatten out all the abstraction levels is tending to work
against your understanding of computer languages here, I suspect.

The word "knife" is a noun, but if I "knife" someone, I'm using a noun
(what the word is) as a verb (what the word can do).  Human language is
full of these borrowings of abstraction level, so much so that linguists
even have a name for them in general, the "emic vs etic" distinction.
In non-linguistic terms, "what you said vs what you really meant".
What it is, vs what it does.

Originally these were coined on the phonetic vs phonemic level, so we
see lots of places in English where the phonetics don't match up with
how they are used:

The prince made some prints.

Here you pronounce those words identically on a phonetic level, but on
a higher phonemic level (or even on a morphophonemic level), "prince" is
only one morpheme, while "prints" is two morphemes "print" and the plural
"s".  But this etic/emic distinction works at higher levels as well:

Here's a you-can-even-use-a-sentence-as-an-adjective example.

Here the etic description of "you-can-even-use-a-sentence-as-an-adjective"
is that of a sentence.  That's what it *is*.  But language is flexible
enough that I can choose (emically) to slot the whole sentence in as
a adjective.  That's what the sentence can *do*.  (Or that's what you
can do with a sentence, if you prefer.)  The fact that you can do this
takes nothing away from what a sentence *is*, because that's at a lower
abstraction level.

Going up the linguistic stack even further, every time you read a metaphor
in a poem (or in a newspaper article for that matter), you are using
your knowledge of English to realize that the poet (or reporter) is
relying on you, the Gentle Reader, to realize that the writer is
using a metaphor.  A metaphor is when you say one thing but mean
something else by it.  The words of a metaphor are what it "is", but
the meaning it produces in your brain is what it "does".

The fact that the $limit is using a particular value with a particular
representation in memory ("what the manual says Inf is") has almost
nothing to do with how we choose to use it metaphorically in an interface,
except insofar as it's extremely convenient to have a floating-point value
that happens to compare as larger than any integer you want to name.
That comparison is a thing that Inf can *do*, which is the abstraction level on
which the $limit API is working.  The fact that it can be used this way
is not at all contradictory to the description of what the Inf value *is*.

But the description of what it can do really belongs on the many places
where it can be used in various metaphorical ways, not in the definition
of what it is.  The floating-point Inf value really has no clue whatsoever
about all the ways it might be used.  It probably doesn't even realize
it can be compared with an integer.  :)

Larry

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 4:36 PM, Curt Tilmes wrote:



On Fri, Sep 28, 2018 at 7:23 PM ToddAndMargo > wrote:


How about just:

       When used as an argument, the value Inf (Infinity)
       represents "without bound" or "no limit".

That would have certainly tipped me off


I think you are trying to tie its meaning as an argument to the value 
itself.  That isn't really how it works.

Inf is just the value higher than any other value.

Its interpretation as an argument is dependent on the routine it is an 
argument to.


For .words($limit), you could say that passing in Inf for a $llimit (the 
default) would keep making words with no limit.


In some other method,  it could have some other meaning.

I could say for my foo($x) function that passing in $x=Inf causes it to 
throw an Exception (or even  print out "yowza" or whatever.)  That's up 
to the way I want to use it for my function.


For a limit, it makes sense that if you count up to a value, that 
passing in Inf for that value would mean that you never reach it, since 
it the value is infinite.


Curt



H. More thinking required.

Thank you!

Re: Could this be any more obscure?

[Curt Tilmes]

On Fri, Sep 28, 2018 at 7:23 PM ToddAndMargo  wrote:

> How about just:
>
>   When used as an argument, the value Inf (Infinity)
>   represents "without bound" or "no limit".
>
> That would have certainly tipped me off
>

I think you are trying to tie its meaning as an argument to the value
itself.  That isn't really how it works.
Inf is just the value higher than any other value.

Its interpretation as an argument is dependent on the routine it is an
argument to.

For .words($limit), you could say that passing in Inf for a $llimit (the
default) would keep making words with no limit.

In some other method,  it could have some other meaning.

I could say for my foo($x) function that passing in $x=Inf causes it to
throw an Exception (or even  print out "yowza" or whatever.)  That's up to
the way I want to use it for my function.

For a limit, it makes sense that if you count up to a value, that passing
in Inf for that value would mean that you never reach it, since it the
value is infinite.

Curt

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 3:54 PM, Curt Tilmes wrote:

When used as an argument, the value Inf (Infinity)
         represents "without bound" or "no limit"


Thank you!

How about just:

 When used as an argument, the value Inf (Infinity)
 represents "without bound" or "no limit".

That would have certainly tipped me off

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Fri, Sep 28, 2018 at 6:49 PM ToddAndMargo  wrote:

> On 9/28/18 3:45 PM, ToddAndMargo wrote:
> >
> >   The value Inf (Infinity) represents "without bound" or
> >   "no limit" (meaning "all possible values") when used
> >   as an argument.
>
>
> Better written would be:
>
> When used as an argument, the value Inf (Infinity)
> represents "without bound" or "no limit", meaning
> "all possible values".
>

It doesn't really mean "all possible values".  It means a number that is
higher than any expressible number.

If you say 1000..Inf, it means numbers that start at 1000, and go up
forever, never ending.

It doesn't include things like 50, or 172, or 42, etc.  It certainly
doesn't mean "all possible values".

For words(Inf), it means you keep making words forever, but that isn't
because infinity is "all possible values", it is because you never reach
infinity.

Curt

Re: Could this be any more obscure?

[Brandon Allbery]

It only means that in some cases. Consider if you are writing code that
places items in a grid, and you support Inf as a grid coordinate meaning
"not on the grid" which might be represented differently or which might
place it at whatever edge of the grid is relevant (without forcing you to
know the size of the grid, so it's more useful in a general library).

There's no "think simple" that covers all the use cases. And "if it's not
think simple, then remove it" means you do extra work for no good reason
except to make the documentation happy.

On Fri, Sep 28, 2018 at 6:46 PM ToddAndMargo  wrote:

> On 9/28/18 10:37 AM, Brandon Allbery wrote:
> > We're going to have a problem if "infinity" is not allowed in the
> > presence of some programmers. "All values" can mean too many things in
> > too many situations. And I don't think using * works here, quite,
> > precisely because it can mean too many things.
>
> Agreed.
>
> I think the issue is with the wording of Inf:
>
> https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
>   The value Inf is an instance of Num and represents value that's
>   too large to represent in 64-bit double-precision floating
>   point number
>
> Looking at
> https://en.wikipedia.org/wiki/Infinity
> Infinity (symbol: ∞) is a concept describing something
> without any bound or larger than any natural number.
>
> "without any bound" is what Inf is being used for here.
> I see it as "larger than any natural number".  So I
> am probably the one at fault.
>
> When I read the manual, Perl Speak over rules common speak.
> So I was taking Inf's Perl defination literally.
>
> Proposed change for your criticism:
>
>   The value Inf (Infinity) represents "without bound" or
>   "no limit" (meaning "all possible values") when used
>   as an argument.
>
>   Inf when used as an instance of Num and represents a
>   value that's too large to represent in 64-bit double-precision
>   floating point number
>
> What do you think?
>
> -T
>


-- 
brandon s allbery kf8nh
allber...@gmail.com

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/27/18 12:40 AM, Laurent Rosenfeld via perl6-users wrote:

 > I am NOT asking it to limit my request to Infinity.

Yes you are, implicitly. If you don't pass any parameter for $limit, 
$limit will take the default value supplied by the signature, i.e. Inf.


True, but that is not what the manual says Inf is.  Lower in this
thread I made a suggest addition to the wording of Inf.  Would
you mind looking at it and offering your criticism?

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 3:45 PM, ToddAndMargo wrote:


  The value Inf (Infinity) represents "without bound" or
  "no limit" (meaning "all possible values") when used
  as an argument.



Better written would be:

   When used as an argument, the value Inf (Infinity)
   represents "without bound" or "no limit", meaning
   "all possible values".

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 10:37 AM, Brandon Allbery wrote:
We're going to have a problem if "infinity" is not allowed in the 
presence of some programmers. "All values" can mean too many things in 
too many situations. And I don't think using * works here, quite, 
precisely because it can mean too many things.


Agreed.

I think the issue is with the wording of Inf:

https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
 The value Inf is an instance of Num and represents value that's
 too large to represent in 64-bit double-precision floating
 point number

Looking at
https://en.wikipedia.org/wiki/Infinity
   Infinity (symbol: ∞) is a concept describing something
   without any bound or larger than any natural number.

"without any bound" is what Inf is being used for here.
I see it as "larger than any natural number".  So I
am probably the one at fault.

When I read the manual, Perl Speak over rules common speak.
So I was taking Inf's Perl defination literally.

Proposed change for your criticism:

 The value Inf (Infinity) represents "without bound" or
 "no limit" (meaning "all possible values") when used
 as an argument.

 Inf when used as an instance of Num and represents a
 value that's too large to represent in 64-bit double-precision
 floating point number

What do you think?

-T

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 12:34 PM, Curt Tilmes wrote:


On Fri, Sep 28, 2018 at 2:57 PM ToddAndMargo > wrote:


On 9/28/18 10:42 AM, Curt Tilmes wrote:
 > Indeed we do, we have a special value just for that -- Inf or ∞.

Inf or ∞ still means (to me) a number too large to represent.
But, I can't think of another way to say "all of them".


So if I was to ask you what limit I should use to make an iterator that 
created all of the numbers?


I could set the limit at 2:  1..2 and you would get 2 numbers.
I could set the limit at 1000: 1..1000 and you would get 1000 numbers.

If you wanted all the numbers, where would you stop?  What limit would 
you use?


We use ∞  :   Try this   .say for 1..∞
It will give you all the numbers starting with 1 that Perl is capable of 
making (it may take a while...)


Exactly the same for .words.

You can say .words(2) and you get at most 2 words, the limit is 2.
You can say .words(1000) and you get at most 1000 words, the limit is 1000.
(Note you can get less that 1000 -- it isn't saying how many words, it 
isn't a count.  It is a limit.  it is setting the limit it won't go past.)


If you don't want it to stop, you say .words(∞) or .words(Inf), or, 
since an infinite limit is the default, just .words() or .words.
and it won't stop no matter how many it has already given you until it 
reaches the end.


Curt




Hi Curt,

I absolutely understand.  I just don't like the wording of Inf
in this case.

https://en.wikipedia.org/wiki/Infinity
   Infinity (symbol: ∞) is a concept describing something
   without any bound or larger than any natural number.

"without any bound" is what it is being used for here.
I see it as "larger than any natural number".  So I
am probably the one at fault.

"Except" this is where I got Perl's definition of it:

https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
 The value Inf is an instance of Num and represents value that's
 too large to represent in 64-bit double-precision floating
 point number

So the manual is describing it as "larger than any natural
[Perl] number", not as "without any bound" .

Time for an RFE on
https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
to add "without any bound" to the verbiage.

Yes I am picking nits.

-T

Re: Could this be any more obscure?

[Curt Tilmes]

On Fri, Sep 28, 2018 at 2:57 PM ToddAndMargo  wrote:

> On 9/28/18 10:42 AM, Curt Tilmes wrote:
> > Indeed we do, we have a special value just for that -- Inf or ∞.
>
> Inf or ∞ still means (to me) a number too large to represent.
> But, I can't think of another way to say "all of them".
>

So if I was to ask you what limit I should use to make an iterator that
created all of the numbers?

I could set the limit at 2:  1..2 and you would get 2 numbers.
I could set the limit at 1000: 1..1000 and you would get 1000 numbers.

If you wanted all the numbers, where would you stop?  What limit would you
use?

We use ∞  :   Try this   .say for 1..∞
It will give you all the numbers starting with 1 that Perl is capable of
making (it may take a while...)

Exactly the same for .words.

You can say .words(2) and you get at most 2 words, the limit is 2.
You can say .words(1000) and you get at most 1000 words, the limit is 1000.
(Note you can get less that 1000 -- it isn't saying how many words, it
isn't a count.  It is a limit.  it is setting the limit it won't go past.)

If you don't want it to stop, you say .words(∞) or .words(Inf), or, since
an infinite limit is the default, just .words() or .words.
and it won't stop no matter how many it has already given you until it
reaches the end.

Curt

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/28/18 10:42 AM, Curt Tilmes wrote:

Indeed we do, we have a special value just for that -- Inf or ∞.


Inf or ∞ still means (to me) a number too large to represent.
But, I can't think of another way to say "all of them".

Re: Could this be any more obscure?

[Curt Tilmes]

On Fri, Sep 28, 2018 at 1:32 PM ToddAndMargo  wrote:

> So how am I suppose to enter that as a value?


You can enter it as just plain Inf, or, if you are up to it, my preferred
form:  ∞



> What it really means is "all of them".


It means infinite.

For the .words() method, you can pass in an optional $limit parameter.

If you pass in a 0, you don't get any words.  If you pass in a 2, you get 2
words,
if you pass in ∞, or Inf, or the limit is 'infinity'.  It doesn't stop
early.  Since that
is so often the case, it is the default, so if you don't say to limit the
words
before the end, you just get all of them.

"Inf" is just a poor way of stating "all words"
> as the default.  "A tremendously large numbers of words" is just
> a weird way of saying "all of them".
>

An infinite limit isn't "a very large number".  It is special.  You can
never
reach that limit, no matter how many words you parse.

And yes, I am blanking on how to best clean that up. We have no
> value (that I know of) for "all".'
>

Indeed we do, we have a special value just for that -- Inf or ∞.

Curt

Re: Could this be any more obscure?

[Brandon Allbery]

We're going to have a problem if "infinity" is not allowed in the presence
of some programmers. "All values" can mean too many things in too many
situations. And I don't think using * works here, quite, precisely because
it can mean too many things.

On Fri, Sep 28, 2018 at 1:32 PM ToddAndMargo  wrote:

> On 9/26/18 11:34 PM, JJ Merelo wrote:
> >
> >
> > El mié., 26 sept. 2018 a las 23:31, Laurent Rosenfeld via perl6-users
> > (mailto:perl6-users@perl.org>>) escribió:
> >
> > You can set a limit to the number of items (words) you want to
> > retrieve: you will get only the first $limit words.
> >
> > If you don't supply any limit, Inf can be thought as the default
> > value for the number of items, i.e. there is no limit and the
> > routine will return as many words as it can from the source input.
> >
> >
> > And this is one of the things I love Perl 6 for, its consistency.
> > Infinity is literally no limit. Using it meaning "no limit" is genius.
> > Not "0 in this case means no limit" or "-1 means no limit" or "this
> > constant meaning unavailable" or whatever. Infinity has no limit, we use
> > them as a parameter to imply that argument has no limit.
> >
> > Cheers
> >
> > JJ
>
>
> Hi JJ,
>
> The more I learn about Perl 6, the more I prefer it over Perl 5.
>
> To your list, I might add, everything starts counting from zero
> (Perl5 m/ starts at $1).  So no guessing!
>
> My problem with the default set to Inf is that Inf means a number
> too large for the numbers of bits allocated to the variable to
> handle.
>
> RTFM: https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
>   The value Inf is an instance of Num and represents value that's
>   too large to represent in 64-bit double-precision floating
>   point number (roughly, above 1.7976931348623158e308 for
>   positive Inf and below -1.7976931348623157e308 for negative Inf)
>   as well as returned from certain operations as defined by the
>   IEEE 754-2008 standard.
>
> So how am I suppose to enter that as a value?  What it really means
> is "all of them".  "Inf" is just a poor way of stating "all words"
> as the default.  "A tremendously large numbers of words" is just
> a weird way of saying "all of them".
>
> And yes, I am blanking on how to best clean that up. We have no
> value (that I know of) for "all".
>
> -T
>


-- 
brandon s allbery kf8nh
allber...@gmail.com

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/26/18 11:34 PM, JJ Merelo wrote:



El mié., 26 sept. 2018 a las 23:31, Laurent Rosenfeld via perl6-users 
(mailto:perl6-users@perl.org>>) escribió:


You can set a limit to the number of items (words) you want to
retrieve: you will get only the first $limit words.

If you don't supply any limit, Inf can be thought as the default
value for the number of items, i.e. there is no limit and the
routine will return as many words as it can from the source input.


And this is one of the things I love Perl 6 for, its consistency. 
Infinity is literally no limit. Using it meaning "no limit" is genius. 
Not "0 in this case means no limit" or "-1 means no limit" or "this 
constant meaning unavailable" or whatever. Infinity has no limit, we use 
them as a parameter to imply that argument has no limit.


Cheers

JJ



Hi JJ,

The more I learn about Perl 6, the more I prefer it over Perl 5.

To your list, I might add, everything starts counting from zero
(Perl5 m/ starts at $1).  So no guessing!

My problem with the default set to Inf is that Inf means a number
too large for the numbers of bits allocated to the variable to
handle.

RTFM: https://docs.perl6.org/type/Num#index-entry-Inf_%28definition%29-Inf
 The value Inf is an instance of Num and represents value that's
 too large to represent in 64-bit double-precision floating
 point number (roughly, above 1.7976931348623158e308 for
 positive Inf and below -1.7976931348623157e308 for negative Inf)
 as well as returned from certain operations as defined by the
 IEEE 754-2008 standard.

So how am I suppose to enter that as a value?  What it really means
is "all of them".  "Inf" is just a poor way of stating "all words"
as the default.  "A tremendously large numbers of words" is just
a weird way of saying "all of them".

And yes, I am blanking on how to best clean that up. We have no
value (that I know of) for "all".

-T

Re: Could this be any more obscure?

[Alessandro Costantini]

> Il giorno 26 set 2018, alle ore 08:57, Todd Chester  
> ha scritto:
> 
> Hi All,
> 
> Over on
>https://docs.perl6.org/routine/words
> I see
> 
>   multi method words(Str:D $input: $limit = Inf --> Positional)

$input is the method invocant (hence the “:”) constrained to a defined string 
object.

$limit is the number of words (chunks separated by whitespace) you may want 
from $input

- -> constrains the return type to an object that consumes the role of 
Positional


> HOW IN THE WORLD did they convert `$limit = Inf` into an
> array index!?!?

I think $limit is the number of words you want, not an array index.

> https://docs.perl6.org/type/Num#Inf
> And `Inf` means a number larger than Perl can handle or Infinity.
> What does that have to do with ANYTHING!?

I think the method returns a lazy Seq, so no limits.

> Yours in confusion,
> -T
> 
> And the worst part is that I know how to use "words" and use it
> frequently.  And the documentation is a nightmare to understand.
> 
> Link to Positional:
> https://docs.perl6.org/type/Positional
>   Role for objects which support indexing them using
>   postcircumfix:«[ ]» (usually list-like objects).
>   Example types with Positional role include List,
>   Array, Range, and Buf.
> 
> I like him using `Str:D $input:` rather than just `Str:D:`
> and it is more intuitive

Re: Could this be any more obscure?

[Brad Gilbert]

In Perl 6 most normal operators are subroutines:

@a[1..3]
&postcircumfix:« [  ] »( @a,1..3 ) # same as above

Since they are just subroutines they often just call something else.

# an overly simplified version
sub postcircumfix:« [  ] » ( @array, **@indicies ) {
gather {
for @indicies -> $index {
take @array.AT-POS( $index )
}
}
}

When you define such a subroutine for the first time, it modifies the parser.

In the case of &postcircumfix:« [  ] », it can take ANY VALUE as its
first argument.
On `Positional` arguments it calls `.AT-POS`.
If it isn't `Positional`, it will pretend that it is a list of one value.

   1[0];   # pretend that `1` is the same as `(1,)`

This means it can be found everywhere throughout the language.

---

We do not want to describe every bit of the language that interacts
with the `.words` method.
This is because that would be the entire language on one page.

When you talked about [], this is inadvertently what you asked for.

---

In the case of the `.words()` document we say that it is called on
`Str` and returns a `Seq`.
(The docs were wrong about it returning a `Positional`)

We document that it returns the parts of the string that aren't whitespace.

We document that you can give a limit to how many values it returns.
(arguably, this isn't needed because you can just call `.head($limit)` instead)

If we changed it to `selection` it would make it seem more complicated
than it really is.
Selection could mean that it could select the second and third values.
`.words()` doesn't do that.

The closest synonyms would be:
cap
maximum
upper bound
cutoff point
farthest point
end
max count

We do not document every single operator that operates on a `Seq`, on that page.
(Almost every single one of them.)
Again, [] is one of them.

We do not document on that page all of the methods of `Seq`.
(There is a page specifically for that)

On Wed, Sep 26, 2018 at 9:18 PM ToddAndMargo  wrote:
>
> On 9/26/18 7:11 PM, Brandon Allbery wrote:
> > That's not helping. What didn't you understand?
>
> >>  It just improves error messages.
>
> My understanding it that if it uses "--Positinal"
> I can use []

Re: Could this be any more obscure?

[Laurent Rosenfeld via perl6-users]

> I am NOT asking it to limit my request to Infinity.

Yes you are, implicitly. If you don't pass any parameter for $limit, $limit
will take the default value supplied by the signature, i.e. Inf.



Le jeu. 27 sept. 2018 à 02:48, ToddAndMargo  a
écrit :

> On 9/26/18 4:33 PM, The Sidhekin wrote:
> > On Wed, Sep 26, 2018 at 11:40 PM ToddAndMargo  > > wrote:
> >
> > What I don't understand is:
> >
> >multi method words(Str:D $input: $limit = Inf --> Positional)
> >
> > Specifically "$limit = Inf".  Why are we using "$limit" instead
> > of "$selection"
> >
> >Perhaps this would be easier if you explain where you're getting
> > "$selection", and what you think it is.
>
> $ p6 '"a b c d e".words[ 2, 4 ].say;'
> (c e)
>
> or
>
> $ p6 '"a b c d e".words()[ 2, 4 ].say;'
> (c e)
>
> I am selecting the 2nd and 4th word starting from zero.  Inside
> the brackets I am asking it to select th e 2nd and 4th words for me.
>
> I am NOT asking it to limit my request to Infinity.
>
>
>
> >
> > And where is it stated what goes in the () and what goes
> > in the []?
> >
> >
> >The () is part of a method call syntax; method arguments go there:
> > https://docs.perl6.org/language/syntax#Subroutine_calls
>
> Where does it state that
>
> $ p6 '"a b c d e".words(3).say;'
> (a b c)
>
> means the first three words, starting at zero?
>
>
> >The [] is a postcircumfix operator; index arguments go there:
> > https://docs.perl6.org/language/operators#postcircumfix_[_]
>
> Where does
>
>  multi method words(Str:D $input: $limit = Inf --> Positional)
>
> state that I can do such?
>
> I ask this because not all methods will take []
>
>
> $ p6 '"a b c d e".contains( "a","b" ).say;'
> Cannot convert string to number: base-10 number must begin with valid
> digits or '.' in '⏏b' (indicated by ⏏)
>in block  at -e line 1
>
> $ p6 '"a b c d e".contains( 1, 3 ).say;'
> Ambiguous call to 'contains(Str: Int, Int)'; these signatures all match:
> :(Str:D: Cool:D $needle, Cool:D $pos, *%_)
> :(Str:D: Cool:D $needle, Cool:D $pos, *%_)
>in block  at -e line 1
>
>
> Also, where is it stated that
>
> $ p6 '"a b c d e".words(3)[ 2, 4 ].say;'
> (c Nil)
>
> will send the first three words to [2,4] ?
>
> Thank you for helping me with this!
>
> -T
>

Re: Could this be any more obscure?

[JJ Merelo]

El jue., 27 sept. 2018 a las 3:51, ToddAndMargo ()
escribió:

> On 9/26/18 6:31 PM, ToddAndMargo wrote:
> > On 9/26/18 6:18 PM, Curt Tilmes wrote:>
> >  >  > The methods don't take [].  You are calling [] on the thing
> > that the
> >  >  > methods return.
> >
> >>>
> >>> Yes, I know.  And it is human readable too.  It is one of the
> >>> many reasons I adore Perl 6.
> >>>
> >>> Where in
> >>>  multi method words(Str:D $input: $limit = Inf --> Positional)
> >>> does it state that "words" will do that?  Not all methods will.
> >>> So it need to be stated when they will.
> >>>
> >>>
> >
> >
> >
> >  > The part where it says "--> Positional" says the thing that gets
> >  > returned is Positional.
> >  >
> >  > A Positional thing has all sorts of methods and operators you can use,
> >  > including []
> >  >
> >  > Not all methods will, of course.  Only those that say "--> Positional"
> >  > return a Positional that acts like that.
> >  >
> >  > Curt
> >
> > Hi Curt,
> >
> > Perfect! Thank you!
> >
> > So all methods that respond with --> Positional will accept []
> >
> > Awesome!
> >
> > -T
>
>
>
> I do believe the reason I spaced on this was that when I see "-->"
> what goes through my head is "this is the value(s) returned".
> I had not idea it would reflect backwards and affect the method.
>

It does not.

say "Flim Flam Flum".words[2] # OUTPUT: «Flum␤»

is exactly the same as

say "Flim Flam Flum".words()[2] # OUTPUT: «Flum␤»

And exactly the same as

say "Flim Flam Flum".words(Inf)[2] # OUTPUT: «Flum␤»

And exactly the same as

my @flim-flam-flum = "Flim Flam Flum".words; # @flim-flam-flum carries
an @, ergo it's a Positional
say @flim-flam-flum[2] # OUTPUT: «Flum␤»

In Perl 6 you can chain calls, that's what is meant by postcircumfix, it
means you can put the operator like thing (in this case, []) _behind_
(post) the thing you are calling, plus you are putting the arguments
_inside_ the operator (that's the circumfix part). You can also do

say "Flim Flam Flum".words[1,2][0] # OUTPUT: «Flam␤»

You are first post-circumfixing [] over the return value of words, getting
2 elements in a Positional (an List in this case, Positional is a Role, not
a Class), and them post-circumfixing again getting the first of these two
elements. You can do this to exhaustion, as long as it's an object method
or a post-circumfix operator, chaining the one after the other. None of
them is "reflecting" on anything, you are just chaining calls, which is a
nice and compact thing to do.

Cheers
-- 
JJ

Re: Could this be any more obscure?

[JJ Merelo]

El jue., 27 sept. 2018 a las 3:19, Brandon Allbery ()
escribió:

> Additionally: Perl 5 docs don't run into this because perl 5 has only 3
> types: scalar, list, hash.
>
> Perl 6 has lots of types, each of which has its own behavior. We use roles
> to package up common
>

_and_ roles _and_ contexts.

behaviors. Positional is the role for "can be indexed" / "understands []".
> Don't just assume you know what Positional is because you know its English
> meaning; look at what it actually does, and you will find the []
> documentation.
>

Right: https://docs.perl6.org/type/Positional Just type "Positional" into
the search box, and scroll down to where it says "Roles".

Cheers

JJ

Re: Could this be any more obscure?

[JJ Merelo]

El mié., 26 sept. 2018 a las 23:31, Laurent Rosenfeld via perl6-users (<
perl6-users@perl.org>) escribió:

> You can set a limit to the number of items (words) you want to retrieve:
> you will get only the first $limit words.
>
> If you don't supply any limit, Inf can be thought as the default value for
> the number of items, i.e. there is no limit and the routine will return as
> many words as it can from the source input.
>

And this is one of the things I love Perl 6 for, its consistency. Infinity
is literally no limit. Using it meaning "no limit" is genius. Not "0 in
this case means no limit" or "-1 means no limit" or "this constant meaning
unavailable" or whatever. Infinity has no limit, we use them as a parameter
to imply that argument has no limit.

Cheers

JJ

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/26/18 7:28 PM, Brandon Allbery wrote:
I often feel like perlmonks is about 80% of what's wrong with perl 5 
these days.


And they are  G-R-O-U-C-H-Y  too!!!

Re: Could this be any more obscure?

[Curt Tilmes]

On Wed, Sep 26, 2018 at 10:30 PM ToddAndMargo  wrote:

>
> > You can also call .elems to see how many elements there are and
> > .AT-POS() (same as []), .EXISTS-POS() to see if an element exists, etc.
>

One small correction before the nit-pickers jump on me...
.AT-POS() isn't *really* the same as [] -- [] is much smarter and can do
more stuff...  One of
the things it can do is the same as .AT-POS().

Curt

Re: Could this be any more obscure?

[ToddAndMargo]

On 9/26/18 7:28 PM, Curt Tilmes wrote:



On Wed, Sep 26, 2018 at 10:19 PM ToddAndMargo > wrote:



My understanding it that if it uses "--Positinal"
I can use []


Yes.  Everything described here: https://docs.perl6.org/type/Positional

You can also call .elems to see how many elements there are and 
.AT-POS() (same as []), .EXISTS-POS() to see if an element exists, etc.


"a b c d e".words.elems
5
"a b c d e".words(3).elems
3
"a b c d e".words.AT-POS(2)
c
"a b c d e".words(3).EXISTS-POS(4)
False

Curt


Thank you!