Re: A comparison between P5 docs and p6 docs
Ordinarily I would agree with you. But I know my own brain and how it works. I only learn by doing. Have tried to change that and can't. A good tutorial book *will* make you "do." The brian d foy book does exactly that with things to try, and questions to explore in your own code. It takes you on a structured, pre-thought-out journey through the concepts and features in an optimal order.
Re: A comparison between P5 docs and p6 docs
The signatures in the docs are often the exact same signatures
as the code they are documenting.
> Str.^lookup('contains').candidates.map: *.signature.say
(Str:D: Cool:D $needle, *%_)
(Str:D: Str:D $needle, *%_)
(Str:D: Cool:D $needle, Cool:D $pos, *%_)
(Str:D: Str:D $needle, Int:D $pos, *%_)
So the name of the positional parameters tend to be whatever
the person who wrote the code decided to call them.
If you have a better idea, you could create an issue or pull-request.
---
The real problem is that someone has to be able to see it
from the beginner's perspective, but also has to know how
it actually works.
They also have to have the time and ambition to go through them.
If you create a detailed issue, or pull-request, at least people
will know where their work is needed.
---
There have been cases where documenting something
lead to the discovery of a bug in the implementation.
On Tue, Sep 11, 2018 at 7:05 PM ToddAndMargo wrote:
>
> On 09/11/2018 08:17 AM, Laurent Rosenfeld via perl6-users wrote:
> > Hi Todd,
> >
> > I fully agree with Tom B.'s message that you should really set out to
> > read a Perl 6 book. Many of the things you asked are covered in most of
> > the available books. And the available books are easier than the
> > official documentation for a beginner to start understand the basic
> > underlying concepts.
> >
> > I should add that you don't even have to /buy/ one book, since my own
> > /Think Perl 6/ book is freely available on the Internet (Creative
> > Commons license): https://greenteapress.com/wp/think-perl-6/. Well, if
> > you are interested in reading it, I'd suggest you look for the PDF on my
> > Github repository
> > (https://github.com/LaurentRosenfeld/thinkperl6/tree/master/PDF),
> > because it is more up-to-date (number of small corrections made
> > following comments from readers).
> >
> > So it would take you just a few minutes (at no cost) to download it and
> > start enjoying it.
> >
> > Cheers,
> > Laurent.
>
>
> Hi Laurent,
>
> Ordinarily I would agree with you. But I know my own brain and
> how it works. I only learn by doing. Have tried to change that
> and can't.
>
> When I "dive in", I open up the reference docs and bang away.
> I also use Google, but that is next to useless in Perl 6 as Perl 5
> hits drowned Perl 6 out.
>
> I am 62 years old, have a bachelors degree in Electronic and
> Computer Engineering, Cum Laude and have been programming
> things all my life. I live with the reference page open
> while pounding out code.
>
> Perl 6's document are next to useless for me. This is the first
> time I have come across references that were so badly done.
> And programming of the Automated Test Equipment I did
> had some documents to behold. CP-M was not fun either.
>
> Do not misunderstand, I ADORE Perl 6. It is a wonderful clean
> up of Perl 5, especially the subroutine definitions and regex's.
> The only step backward is the docs.
>
> The developers have their own specification/documentation.
> The reference docs need to be written for the rest of us.
>
> By the way, I never mastered Perl 5's regex's. I used them,
> but could never figure out exactly what I did. In Perl 6
> I now can throw them together off the top of my head. It
> is kind of fun.
>
> -T
>
> --
> ~~
> Computers are like air conditioners.
> They malfunction when you open windows
> ~~
Re: A comparison between P5 docs and p6 docs
On 09/11/2018 08:17 AM, Laurent Rosenfeld via perl6-users wrote: Hi Todd, I fully agree with Tom B.'s message that you should really set out to read a Perl 6 book. Many of the things you asked are covered in most of the available books. And the available books are easier than the official documentation for a beginner to start understand the basic underlying concepts. I should add that you don't even have to /buy/ one book, since my own /Think Perl 6/ book is freely available on the Internet (Creative Commons license): https://greenteapress.com/wp/think-perl-6/. Well, if you are interested in reading it, I'd suggest you look for the PDF on my Github repository (https://github.com/LaurentRosenfeld/thinkperl6/tree/master/PDF), because it is more up-to-date (number of small corrections made following comments from readers). So it would take you just a few minutes (at no cost) to download it and start enjoying it. Cheers, Laurent. Hi Laurent, Ordinarily I would agree with you. But I know my own brain and how it works. I only learn by doing. Have tried to change that and can't. When I "dive in", I open up the reference docs and bang away. I also use Google, but that is next to useless in Perl 6 as Perl 5 hits drowned Perl 6 out. I am 62 years old, have a bachelors degree in Electronic and Computer Engineering, Cum Laude and have been programming things all my life. I live with the reference page open while pounding out code. Perl 6's document are next to useless for me. This is the first time I have come across references that were so badly done. And programming of the Automated Test Equipment I did had some documents to behold. CP-M was not fun either. Do not misunderstand, I ADORE Perl 6. It is a wonderful clean up of Perl 5, especially the subroutine definitions and regex's. The only step backward is the docs. The developers have their own specification/documentation. The reference docs need to be written for the rest of us. By the way, I never mastered Perl 5's regex's. I used them, but could never figure out exactly what I did. In Perl 6 I now can throw them together off the top of my head. It is kind of fun. -T -- ~~ Computers are like air conditioners. They malfunction when you open windows ~~
Re: A comparison between P5 docs and p6 docs
On 09/11/2018 08:52 AM, Tom Browder wrote:
On Tue, Sep 11, 2018 at 10:39 AM Parrot Raiser <1parr...@gmail.com> wrote:
One of the paradoxes of documentation, and the teaching of many
abstract topics, is that those with the most in-depth knowledge of the
...
I agree with you for the most part. But the docs DO have examples,
and any reader who sees the lack of a suitable one should file an
issue or contribute a suitable change.
I got my start here as a noob p6 user (coming from years of p5 use)
contributing to the docs. And I, too, found many examples too obtuse
for a noob, and have changed some of them.
As experienced as Todd seems to be in p5, he should be able to improve
the docs one way or the other (but get a good book in the meantime;
Andrew Shitov's "Perl 6 at a Glance" is short and sweet for a first
book, Laurent's "Think Perl 6: How to Think Like a Computer Scientist"
for a deeper look).
Cheers,
-Tom
Hi Tom,
There are indeed some examples. They are seldom explained
or even useful. As such are pretty useless. It is my impression
that sometimes the writer is showing off his skills as to how
complicated he can get.
Here is a useless example from contains:
say "Hello, World".contains(',', 1); # OUTPUT: «False»
The "1" is not explained. It took me 20 minutes to figure
out it was the starting position to start looking
in the string. Initially I tough is was an extra command
for case sensitivity, multiple matches, etc..
The docs need to be written in the same fashion as a
spoken language dictionary.
Here is what the word mean
Here is how to use it in sentence.
This is how I would write "contains" in perdoc fashion
(It is posted on issue 2303):
STR contains SUBSTR,POSITION
STR contains SUBSTR
Search for the existence of a SUBSTR in STR starting at
or after POSITION. If POSITION is omitted, starts'
searching from the beginning of the string (0).
If the SUBSTR is located, "contains" returns "True",
otherwise it returns "False".
Examples:
my Str $Haystack = "abc";
my Str $Needle = "c";
my Int $StartIndex = 1; # index to start looking, default = 0
my Bool $Result;
$Result = $Haystack.contains( "c", $StartIndex );
say $Result;'
True
say "abc".contains( "b", 1 ); # start looking at index 1
True
say "abc".contains( "z" ); # start looking at default index 0
False
You walk away knowing exactly how to use the function. And you do not
have to have developer level knowledge to use it!
-T
Re: A comparison between P5 docs and p6 docs
On 09/11/2018 04:53 AM, Tom Browder wrote: Todd, some free advice: 1. DOCUMENTATION The docs are a volunteer effort. You can help by contributing changes and submitting issues. Hi Tom, I have started contributing to this effort as well. One of the big hurdles is that those maintaining the documents expect you to have developer lever knowledge of their wring to understand it. Perldocs does not do this. The developers have their own specification to work with. The Docs need to be written for the rest of us. Here is my latest on "contains" in perldocs fashion: https://github.com/perl6/doc/issues/2303 But, it is like hitting your head on a brick wall. -T
Re: A comparison between P5 docs and p6 docs
One of the paradoxes of documentation, and the teaching of many abstract topics, is that those with the most in-depth knowledge of the topic,are the least suitable to explain it, precisely because of that knowledge. They can't remember what it felt like not to know something, and they've usually learnt a jargon to simplify and speed discussions. That has to be filtered through 2 or 3 layers of ignorance before it's diluted to comprehensibility. If you don't know what you don't know, it's hard to plot a route to mastery. (On the other hand, more than one expert has said something like "the best way to learn a topic is to teach a course in it".) In wanders the noob, and s/he is surrounded by weird words, some utterly new, which may or may not have their usual meanings if they aren't. It's hard to start exploring Wonderland when you don't even know how to ask the way to the rabbit hole. My impression of the Perl 6 documentation is that it was written by the designers and implementors, for their needs, a by-product of the development process. Since it's at the intersection of linguistics and computer science, the terminology tends to be a blend of both, seasoned with a pinch of local dialect. It's designed to answer questions like "what category of language is it?", "what programming paradigms does it favour?", "how is [some feature] designed?". For someone constructing a taxonomy of computer languages, or looking for interesting compiler techniques, it's great. That doesn't help the (English major) beginner who wants to find and fix incorrectly cased names in a file, or extract some data. It's also like the Unix documentation, an example-free zone. That assumes that the reader is skilled in converting abstract categories into explanatory examples for themselves, possibly one of the fundamental skills of programming. (It's much more natural to learn an abstract principle for re-use by having it explained through a concrete example.) I'm still trying to map a path into the jungle from practical daily treks, and it takes ruthless pruning of the language's features to avoid diversions and use of as-yet-unexplained features. (P5 can be tricky that way, too, but there's not as much to hide behind the curtain.) Trainee sales droids are taught not to mention "features", unless they can explain at least 2 "benefits" to the mark, (sorry, "prospect"). I'm going to start out with 5 ways to produce valid P6 that does absolutely nothing, and proceed from there. It'll be interesting to see if that approach works. (Apologies to Tom Browder for duplication; I had to edit the start of the message to make sense )
Re: A comparison between P5 docs and p6 docs
On Tue, Sep 11, 2018 at 10:31 AM Simon Proctor wrote: > > It's a very good read. :) Yes it is!
Re: A comparison between P5 docs and p6 docs
It's a very good read. :) On Tue, 11 Sep 2018 at 16:19 Laurent Rosenfeld via perl6-users < perl6-users@perl.org> wrote: > Hi Todd, > > I fully agree with Tom B.'s message that you should really set out to read > a Perl 6 book. Many of the things you asked are covered in most of the > available books. And the available books are easier than the official > documentation for a beginner to start understand the basic underlying > concepts. > > I should add that you don't even have to *buy* one book, since my own *Think > Perl 6* book is freely available on the Internet (Creative Commons > license): https://greenteapress.com/wp/think-perl-6/. Well, if you are > interested in reading it, I'd suggest you look for the PDF on my Github > repository (https://github.com/LaurentRosenfeld/thinkperl6/tree/master/PDF), > because it is more up-to-date (number of small corrections made following > comments from readers). > > So it would take you just a few minutes (at no cost) to download it and > start enjoying it. > > Cheers, > Laurent. > > Le mar. 11 sept. 2018 à 13:26, ToddAndMargo a > écrit : > >> Hi All, >> >> Not to beat a dead horse, but Perl 6's docs are >> miserably hard to understand. >> >> Here is a comparison of Perl 5's perldocs and Perl 6's >> docs: >> >> Perl 5: >> >> $ perldoc -f index >> index STR,SUBSTR,POSITION >> index STR,SUBSTR >> The index function searches for one string within another, >> but without the wildcard-like behavior of a full regular- >> expression pattern match. It returns the position of >> the first occurrence of SUBSTR in STR at or after POSITION. >> If POSITION is omitted, starts searching from the beginning >> of the string. POSITION before the beginning of the string >> or after its end is treated as if it were the beginning >> or the end, respectively. POSITION and the return value >> are based at zero. If the substring is not found, "index" >> returns -1. >> >> Perl 6: >> >> https://docs.perl6.org/routine/index >> >> Documentation for sub index assembled from the following types: >> class Cool >> >> From Cool >> (Cool) routine index >> >> Defined as: >> >> multi subindex(Str(Cool) $s, Str:D $needle, Int(Cool) $startpos >> = 0 --> Int) >> multi method index(Str(Cool) $needle, Int(Cool) $startpos = 0 --> >> Int) >> >> Coerces the first two arguments (in method form, also counting >> the invocant) to Str, and searches for $needle in the string >> starting from $startpos. It returns the offset into the string >> where $needle was found, and an undefined value if it was not >> found. >> >> See the documentation in type Str for examples. >> >> >> "Cources"??? Seriously: >> >> https://www.merriam-webster.com/dictionary/coerce >> Definition of coerce coerced; coercing >> transitive verb >> 1 : to compel to an act or choice >> was coerced into agreeing >> abusers who coerce their victims into silence >> >> 2 : to achieve by force or threat >> coerce compliance >> coerce obedience >> >> 3 : to restrain or dominate by force >> >> And what the heck is a "multi sub" and a "multi method" anyway? >> AND WHY DO I EVEN CARE? I just what to know how to use the >> stinking thing! Geepers Creapers !!! (I am trying to avoid >> swearing.) >> >> Perl 5's perldoc just tells you what you need to know to use the >> stinker. It is concise and to the point. Perl 6 is a nightmare >> to understand. >> >> Thank for putting up with my frustration. >> >> -T >> > -- Simon Proctor Cognoscite aliquid novum cotidie
Re: A comparison between P5 docs and p6 docs
Hi Todd, I fully agree with Tom B.'s message that you should really set out to read a Perl 6 book. Many of the things you asked are covered in most of the available books. And the available books are easier than the official documentation for a beginner to start understand the basic underlying concepts. I should add that you don't even have to *buy* one book, since my own *Think Perl 6* book is freely available on the Internet (Creative Commons license): https://greenteapress.com/wp/think-perl-6/. Well, if you are interested in reading it, I'd suggest you look for the PDF on my Github repository (https://github.com/LaurentRosenfeld/thinkperl6/tree/master/PDF), because it is more up-to-date (number of small corrections made following comments from readers). So it would take you just a few minutes (at no cost) to download it and start enjoying it. Cheers, Laurent. Le mar. 11 sept. 2018 à 13:26, ToddAndMargo a écrit : > Hi All, > > Not to beat a dead horse, but Perl 6's docs are > miserably hard to understand. > > Here is a comparison of Perl 5's perldocs and Perl 6's > docs: > > Perl 5: > > $ perldoc -f index > index STR,SUBSTR,POSITION > index STR,SUBSTR > The index function searches for one string within another, > but without the wildcard-like behavior of a full regular- > expression pattern match. It returns the position of > the first occurrence of SUBSTR in STR at or after POSITION. > If POSITION is omitted, starts searching from the beginning > of the string. POSITION before the beginning of the string > or after its end is treated as if it were the beginning > or the end, respectively. POSITION and the return value > are based at zero. If the substring is not found, "index" > returns -1. > > Perl 6: > > https://docs.perl6.org/routine/index > > Documentation for sub index assembled from the following types: > class Cool > > From Cool > (Cool) routine index > > Defined as: > > multi subindex(Str(Cool) $s, Str:D $needle, Int(Cool) $startpos > = 0 --> Int) > multi method index(Str(Cool) $needle, Int(Cool) $startpos = 0 --> Int) > > Coerces the first two arguments (in method form, also counting > the invocant) to Str, and searches for $needle in the string > starting from $startpos. It returns the offset into the string > where $needle was found, and an undefined value if it was not > found. > > See the documentation in type Str for examples. > > > "Cources"??? Seriously: > > https://www.merriam-webster.com/dictionary/coerce > Definition of coerce coerced; coercing > transitive verb > 1 : to compel to an act or choice > was coerced into agreeing > abusers who coerce their victims into silence > > 2 : to achieve by force or threat > coerce compliance > coerce obedience > > 3 : to restrain or dominate by force > > And what the heck is a "multi sub" and a "multi method" anyway? > AND WHY DO I EVEN CARE? I just what to know how to use the > stinking thing! Geepers Creapers !!! (I am trying to avoid > swearing.) > > Perl 5's perldoc just tells you what you need to know to use the > stinker. It is concise and to the point. Perl 6 is a nightmare > to understand. > > Thank for putting up with my frustration. > > -T >
Re: A comparison between P5 docs and p6 docs
Todd, some free advice: 1. DOCUMENTATION The docs are a volunteer effort. You can help by contributing changes and submitting issues. Try to use the docs first instead of using an internet search. That will help you submit issues if you don't find what you are looking for. You really need to buy one of the fine Perl 6 books that are available. See the perl6.org webite and this page: https://perl6.org/resources/https://perl6.org/resources/ (look at the bottom left-hand side) See this page for book choice help: https://perl6book.com/ Anyone on the #perl6 IRC (or this mailing list) will be happy to explain their preferences. 2. DESIGN The original Perl 6 specifications are here (linked from the bottom-right of perl6.org): https://design.perl6.org/ The specifications are defined in the test suite (also linked from the bottom-right of per6.org): https://github.com/perl6/roast 3. YOUR CODE USE One of the great features of Perl 6, to me, is the ability to use kebab case, e.g.,: my $some-var = 'a'; When you submit code examples, making them less wordy and "noisy" would help us help you. Perl 6 code can be be written very sparsely. Best regards, -Tom
A comparison between P5 docs and p6 docs
Hi All, Not to beat a dead horse, but Perl 6's docs are miserably hard to understand. Here is a comparison of Perl 5's perldocs and Perl 6's docs: Perl 5: $ perldoc -f index index STR,SUBSTR,POSITION index STR,SUBSTR The index function searches for one string within another, but without the wildcard-like behavior of a full regular- expression pattern match. It returns the position of the first occurrence of SUBSTR in STR at or after POSITION. If POSITION is omitted, starts searching from the beginning of the string. POSITION before the beginning of the string or after its end is treated as if it were the beginning or the end, respectively. POSITION and the return value are based at zero. If the substring is not found, "index" returns -1. Perl 6: https://docs.perl6.org/routine/index Documentation for sub index assembled from the following types: class Cool From Cool (Cool) routine index Defined as: multi subindex(Str(Cool) $s, Str:D $needle, Int(Cool) $startpos = 0 --> Int) multi method index(Str(Cool) $needle, Int(Cool) $startpos = 0 --> Int) Coerces the first two arguments (in method form, also counting the invocant) to Str, and searches for $needle in the string starting from $startpos. It returns the offset into the string where $needle was found, and an undefined value if it was not found. See the documentation in type Str for examples. "Cources"??? Seriously: https://www.merriam-webster.com/dictionary/coerce Definition of coerce coerced; coercing transitive verb 1 : to compel to an act or choice was coerced into agreeing abusers who coerce their victims into silence 2 : to achieve by force or threat coerce compliance coerce obedience 3 : to restrain or dominate by force And what the heck is a "multi sub" and a "multi method" anyway? AND WHY DO I EVEN CARE? I just what to know how to use the stinking thing! Geepers Creapers !!! (I am trying to avoid swearing.) Perl 5's perldoc just tells you what you need to know to use the stinker. It is concise and to the point. Perl 6 is a nightmare to understand. Thank for putting up with my frustration. -T
