Documentation for contains does not explain every parameter

[JJ]

The problem

From this thread in the perl6-users mailing list referring to this page

Suggestions

Read the thread and see if some of the solutions proposed fits, or else address that problem.

[ToddAndMargo]

Suggested wording:

A second parameter can be added after the string to specify at which position in the string -- starting at zero -- to start looking for a match. Delimiter is a comma.

For example, "e" is the fifth character and occupies position four in the string:

say "abcdefghij".contains("e", 4); # position 4 is "e"
True

say "abcdefghij".contains("e", 5); # position 5 is "f"
False

[JJ]

@ToddAndMargo the documentation says

searches for $needle starting from $start.

It also shows the different forms of the multi, and examples which show that behavior:

say "Hello, World".contains(',', 3);       # OUTPUT: «True␤» 

Am I missing something here or what you suggest is already in the documentation?

[ToddAndMargo]

On 09/10/2018 03:35 AM, Juan Julián Merelo Guervós wrote: @ToddAndMargo <https://github.com/ToddAndMargo> the documentation says searches for $needle starting from $start.

Did you mean to write me off list? $needle and $start are meaningless. The second parameter is just not defined.

It also shows the different forms of the multi, and examples which show that behavior: |say "Hello, World".contains(',', 3); # OUTPUT: «True␤» |

It should say that "3" means start looking at the third position (starting at zero) in the string.

Am I missing something here or what you suggest is already in the documentation?

No, what is there is only a refresher for someone that already knows what it is suppose to say. Useless to someone trying to figure out how to use the function.

[JJ]

Still don't understand what you really want here. C<$needle> and C<$start> are the positional variable names used in the function definition. Do you want the documentation to say first and second parameter instead? That is,

searches for the first argument in the string starting from the number of characters indicated by the second argument

?
What I just did is just substitute the name of the variables (which is in the documentation) by its position.

[ToddAndMargo]

On 09/10/2018 03:45 AM, Juan Julián Merelo Guervós wrote: Still don't understand what you really want here. C<$needle> and C<$start> are the positional variable names used in the function definition. Do you want the documentation to say first and second parameter instead? That is, searches for the first argument in the string starting from the number of characters indicated by the second argument ? What I just did is just substitute the name of the variables (which is in the documentation) by its position.

What I want is the suggested wording I posted. The stuff you are stating is way, way over my head and would be way over the head of any beginner trying to use the manual to figure out how to use the function. In other words, don't go over the head of the target audience, unless you only want the very advanced user to be able to understand it. The manual is suppose to be a reference for beginners: much more so than advanced users that already know what they are doing. "C<$needle>" is meaningless to a beginner. The way I worded it, a beginner would easily be able to understand it.

[JJ]

Again, you are going to pardon me, but $needle is in the definition of the function:

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

which is in the documentation. That's how every method is defined in the documentation. It's further clarified by the examples, which are more or less the same than the examples that you suggest. Again, maybe using "first argument" and "second argument" might be clearer for a beginner, but those two arguments receive a name right there and I can't really see how that's an improvement.

[CurtTilmes]

On Mon, Sep 10, 2018 at 6:55 AM ToddAndMargo ***@***.***> wrote: "C<$needle>" is meaningless to a beginner.

The important bit is not "$needle". It is the description "searches for $needle in the string". It could say "$farble", and it would be just as meaningless, but once you see "searches for $farble in string", it clearly means that it searches for the value of the one string in the other string. "searching for a needle in a haystack" is just a common cliche in the English, so we typically use the variable $needle to evoke the concept of searching for one thing in another. Knowledge of that isn't necessary, however, because the document says "searches for $needle in the string." If this isn't clear, you should probably be reading tutorial information, not reference information. If it isn't clear that the syntax delimiter between two positional arguments is a comma, you should probably be reading tutorial information, not reference information. If it isn't clear that a count of characters into the string starts at 0, you should probably be reading tutorial information, not reference information. You could argue we need more available tutorial information, and I would agree. I disagree that we should add such tutorial information to the reference documents. Things like "a count of characters into a string starts at 0" or "we use commas to separate parameters" are not just extra information that could help a beginner understand things better (I agree they would!). I believe it would be *harmful* to add them to the reference information. These are very fundamental concepts, and should be explained clearly in the beginning of tutorial information, so that as one makes their way through the reference information one would already understand them. Repeating that level of information in every single page of the documentation would significantly *detract* from ones ability to find the relevant reference information. I'm not arguing that you should have understood the reference document as it stands, and if you don't (for some future page), please feel free to ask on the list and we'll be more than happy to explain in more detail how things work. I just think we should not try to turn the reference into a tutorial. (Adding a new tutorial page would be fine with me!) Curt

[ToddAndMargo]

On 09/10/2018 04:37 AM, Curt Tilmes wrote: On Mon, Sep 10, 2018 at 6:55 AM ToddAndMargo ***@***.***> wrote: > "C<$needle>" is meaningless to a beginner. > The important bit is not "$needle". It is the description "searches for $needle in the string". It could say "$farble", and it would be just as meaningless, but once you see "searches for $farble in string", it clearly means that it searches for the value of the one string in the other string. "searching for a needle in a haystack" is just a common cliche in the English, so we typically use the variable $needle to evoke the concept of searching for one thing in another. Knowledge of that isn't necessary, however, because the document says "searches for $needle in the string." If this isn't clear, you should probably be reading tutorial information, not reference information. If it isn't clear that the syntax delimiter between two positional arguments is a comma, you should probably be reading tutorial information, not reference information. If it isn't clear that a count of characters into the string starts at 0, you should probably be reading tutorial information, not reference information. You could argue we need more available tutorial information, and I would agree. I disagree that we should add such tutorial information to the reference documents. Things like "a count of characters into a string starts at 0" or "we use commas to separate parameters" are not just extra information that could help a beginner understand things better (I agree they would!). I believe it would be *harmful* to add them to the reference information. These are very fundamental concepts, and should be explained clearly in the beginning of tutorial information, so that as one makes their way through the reference information one would already understand them. Repeating that level of information in every single page of the documentation would significantly *detract* from ones ability to find the relevant reference information. I'm not arguing that you should have understood the reference document as it stands, and if you don't (for some future page), please feel free to ask on the list and we'll be more than happy to explain in more detail how things work. I just think we should not try to turn the reference into a tutorial. (Adding a new tutorial page would be fine with me!) Curt

Hi Curt, As a beginner, I look to the manual to understand what functions do. If you throw advanced concepts at me in the reference, it will go over my head and only cause confusion. And it will make the manual into something only an advanced user can understand. The precise user who doesn't need to use the manual anyway. A good example of throwing concept over the head of beginners is multi method contains(Cool:D: Str(Cool) $needle, Cool $start? --> Bool:D) as in what the heck is that suppose to mean? It only causes confusion. Those kinds on references are best for the language's "specification" reference. Not the manual. Maybe put something like that at the end of the reference as a refresher for those that already know what they are doing, but they don't need the reference anyway. I look to the manual for the way I look at a spoken language dictionary. It says what the word is and shows example usage. A dictionary is not intended to replace a course on learning how speak the language. I am not after the manual being a tutorial. I am after it being understandable. To me multi method contains(Cool:D: Str(Cool) $needle, Cool $start? --> Bool:D) is like looking up "Pas de deux" in an English dictionary and being told "Go learn to speak French, then come back and you will understand". (In which case, I'd not need to come back, so ...) This is what the function is. This is what is does. This is how to use it. All done in understandable terms. If you do not need to use advanced terms to explain the function, then don't. KISS: Keep It Simple and Stupid. The manual is not the place for "specifications". It is for the users, not the developers.

…

-T

[finanalyst]

Todd, This seems to be an age in which 'opinion' and being uneducated seems to count for more than working hard to learn. I'm too old now to change my view that working hard to learn and respecting the views of the learned are virtuous. Sorry if that sounds hard, but I think the people who work hard on perl6, whether answering questions, writing documentation, writing tests, and so on, are worthy of respect. After looking at the perl6 documentation, and I have been following its development with enthusiasm since waiting for the next Apocalypse from Larry, yet I still do not understand all of it eg., :D, but I recognise that this form of concise expression has a great value if I can learn to read it. The documentation may not be for beginners, and everyone believes there needs to be more. In other words, if you want to create something that is 'better' for beginners, then do so. In fact Curt was suggesting the same thing. But because it is for beginners, this community rightly would call it a tutorial and not a reference. I agree here with Curt that reference material should favour brevity over beginner-ness. In fact, the majority of the people using this documentation will be developers who have knowledge of other languages. Having worked with computers since I was 15 and now I am 60 (but never as a professional) and looked at many languages, my experience is that when I read the documentation of a new language the first time, I rarely understand it. It's only after re-reading several times that the terminology and concepts begin to sink in. Also, because I use multiple languages in what I do, eg., php, html, css, twig, js, c, java, perl5, I often forget what the correct syntax is for a particular language. So I need a quick way to check, and to see a short example. I do not need excessive explanations, or repetitions of basic concepts such as 0-based counting. As to the complaint about $needle, I found almost exactly the same names for parameters in the php reference on strpos() (http://www.php.net/manual/en/function.strpos.php). Also, the reference has a concise description of the function, which it then explains. Regards, Richard

…

On 11/09/18 10:23, ToddAndMargo wrote: On 09/10/2018 04:37 AM, Curt Tilmes wrote: > On Mon, Sep 10, 2018 at 6:55 AM ToddAndMargo ***@***.***> > wrote: > > > "C<$needle>" is meaningless to a beginner. > > > > The important bit is not "$needle". It is the description "searches for > $needle in the string". It could say "$farble", and it would be just as > meaningless, but once you see "searches for $farble in string", it clearly > means that it searches for the value of the one string in the other > string. "searching for a needle in a haystack" is just a common cliche in > the English, so we typically use the variable $needle to evoke the concept > of searching for one thing in another. Knowledge of that isn't necessary, > however, because the document says "searches for $needle in the string." > If this isn't clear, you should probably be reading tutorial information, > not reference information. If it isn't clear that the syntax delimiter > between two positional arguments is a comma, you should probably be reading > tutorial information, not reference information. If it isn't clear that a > count of characters into the string starts at 0, you should probably be > reading tutorial information, not reference information. > > You could argue we need more available tutorial information, and I would > agree. I disagree that we should add such tutorial information to the > reference documents. > > Things like "a count of characters into a string starts at 0" or "we use > commas to separate parameters" are not just extra information that could > help a beginner understand things better (I agree they would!). I believe > it would be *harmful* to add them to the reference information. These are > very fundamental concepts, and should be explained clearly in the beginning > of tutorial information, so that as one makes their way through the > reference information one would already understand them. Repeating that > level of information in every single page of the documentation would > significantly *detract* from ones ability to find the relevant reference > information. > > I'm not arguing that you should have understood the reference document as > it stands, and if you don't (for some future page), please feel free to ask > on the list and we'll be more than happy to explain in more detail how > things work. I just think we should not try to turn the reference into a > tutorial. (Adding a new tutorial page would be fine with me!) > > Curt Hi Curt, As a beginner, I look to the manual to understand what functions do. If you throw advanced concepts at me in the reference, it will go over my head and only cause confusion. And it will make the manual into something only an advanced user can understand. The precise user who doesn't need to use the manual anyway. A good example of throwing concept over the head of beginners is multi method contains(Cool:D: Str(Cool) $needle, Cool $start? --> Bool:D) as in what the heck is that suppose to mean? It only causes confusion. Those kinds on references are best for the language's "specification" reference. Not the manual. Maybe put something like that at the end of the reference as a refresher for those that already know what they are doing, but they don't need the reference anyway. I look to the manual for the way I look at a spoken language dictionary. It says what the word is and shows example usage. A dictionary is not intended to replace a course on learning how speak the language. I am not after the manual being a tutorial. I am after it being understandable. To me multi method contains(Cool:D: Str(Cool) $needle, Cool $start? --> Bool:D) is like looking up "Pas de deux" in an English dictionary and being told "Go learn to speak French, then come back and you will understand". (In which case, I'd not need to come back, so ...) This is what the function is. This is what is does. This is how to use it. All done in understandable terms. If you do not need to use advanced terms to explain the function, then don't. KISS: Keep It Simple and Stupid. The manual is not the place for "specifications". It is for the users, not the developers. -T — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2303 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAWMnCEcszZ53FzMsnZx70TbFAlmQGmIks5uZx6zgaJpZM4WgYt8>.

[ToddAndMargo]

On 09/10/2018 08:18 PM, Richard Hainsworth wrote: Todd, This seems to be an age in which 'opinion' and being uneducated seems to count for more than working hard to learn. I'm too old now to change my view that working hard to learn and respecting the views of the learned are virtuous. Sorry if that sounds hard, but I think the people who work hard on perl6, whether answering questions, writing documentation, writing tests, and so on, are worthy of respect. After looking at the perl6 documentation, and I have been following its development with enthusiasm since waiting for the next Apocalypse from Larry, yet I still do not understand all of it eg., :D, but I recognise that this form of concise expression has a great value if I can learn to read it. The documentation may not be for beginners, and everyone believes there needs to be more. In other words, if you want to create something that is 'better' for beginners, then do so. In fact Curt was suggesting the same thing. But because it is for beginners, this community rightly would call it a tutorial and not a reference. I agree here with Curt that reference material should favour brevity over beginner-ness. In fact, the majority of the people using this documentation will be developers who have knowledge of other languages. Having worked with computers since I was 15 and now I am 60 (but never as a professional) and looked at many languages, my experience is that when I read the documentation of a new language the first time, I rarely understand it. It's only after re-reading several times that the terminology and concepts begin to sink in. Also, because I use multiple languages in what I do, eg., php, html, css, twig, js, c, java, perl5, I often forget what the correct syntax is for a particular language. So I need a quick way to check, and to see a short example. I do not need excessive explanations, or repetitions of basic concepts such as 0-based counting. As to the complaint about $needle, I found almost exactly the same names for parameters in the php reference on strpos() (http://www.php.net/manual/en/function.strpos.php). Also, the reference has a concise description of the function, which it then explains. Regards, Richard

Hi Richard, If I have been in anyway disrespectful, I do apologize. It was never my intent to be disrespectful in any way. I rather admire the graciousness of those who have shared their intellectual knowledge with me. I have been involved in electronics since a very small child. I now have a bachelors degree in Electronic and Computer Engineering, Cum Laude. And I have you beat by two years. So, young man, I have been programming things for years and years. Some of the documentation I used when I was doing automated testing was really something to behold. Perl 6's is worse. For an example of what I am speaking of, look at how Perl 5's perldocs does "index" as opposed to Perl 6. 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 sub index(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. Do you see a difference. In Perl 5's "perldoc -f", you walk away knowing how to use the function. In Perl 6, you walk away scratching your head wondering what the h*** did I just read? Perl 6 is a wonderful clean up of Perl 5, especially the sub declarations and regex's. The only step backward I see it the documentation. I too am a YUGE fan of brevity. M$'s documents use 1000 words where 10 will do. Drives me nuts. "Get to the point!" What I am after is being able to read the documentation and know how to use the function afterward. The "$needle", now that I know the story behind it, would be a lot more helpful if "$haystack" were somewhere to be found. I though it was some kind of reserved word. Now if the only thing this crotchety old man wanted to do was to to complain, then it would be different. But I do contribute. It took me over a half hour to figure out the documentation and write an explanation that made sense. Okay, if I was to write "contains" in the style of Perl 5's perldocs, I would write it like this. "contains": 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 See any difference? This is how perldoc would have done it. And "perldoc -f" IS NOT A TUTORIAL. Which one would you leave understanding the function? At any point in my example did you need developer level knowledge of Perl 6? I am not after a tutorial. I am after the same level of functionality that perldoc gives. Please feel free to use my example above. I don't care if you keep around the confusing developer lever definition if you also include auseful (to beginners) description as well. multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos) Means nothing to someone just trying to figure out how to use the function. And, young man, do not be disrespectful of me. I am working my butt off trying to learn Perl 6. And I put a lot of work into trying to write a useful explanation of the function to assist others. Do not change the subject by telling me the documentation is not a tutorial. No one ever accused "perldoc -f" of being a tutorial. This is all part of Kaisen (constant improvement) of which open source shines to brightly. If you did not initially realize that the function docs were unnecessarily complicated for beginners and typical users, now you know. Also, the developers has their own specification sheet. There is no need to duplicate it in the function docs.

…

-T

[CurtTilmes]

1. The signature provides a concise, correct description of the calling sequence that is simply
   critical in a reference document, even though it may make the document look more complicated.

Even though it appears simpler, this:

 STR contains SUBSTR,POSITION
 STR contains SUBSTR

is an incomplete description of that calling sequence, perhaps suitable for a tutorial, but not sufficient for a reference document.

2. Search for the existence of a SUBSTR in STR starting at or after POSITION.

Referring to this thing we search for as $substr instead of $needle could be a good idea. I'm not opposed to that at all. (I kind of like $needle for historic reasons, but can see how $substr might be clearer.)

3. If POSITION is omitted, starts searching from the beginning of the string (0).

Except for the redundant (0), I like this too.

I'm also not opposed to using $position instead of $pos, although I prefer the abbreviation.

4. If the SUBSTR is located, "contains" returns "True", otherwise it returns "False".

Putting the quotes around the values would be incorrect, otherwise I like this.
"True" indicates a a string, while True is a special Boolean value.

If you made it If $substr is located, returns True, otherwise returns False. I could go with this.

5. Your example seems a little verbose, I prefer the existing examples.

6. The existing document is missing the return type -- It should definitely get a --> Bool:D stuck at the end of the signature.

7. The existing document seems to have inconsistent indications for coercion, sometime separate signatures for Cool/Str, but then sometimes together Cool/Int. There should be a standard, and all signatures should follow it.

8. In the existing document, this:

Coerces the invocant (represented in the signature by Str:D: and first argument (which we are calling $needle) to Str (if it's not already, that is, the first and third multi),

I hate...

Are we really going to add such language to every single routine that takes a Str? (I do like the 'Note' with the link to traps.)

Are we really going to add "(which we are calling $blah)" to every single placeholder we refer to?

This is simply extraneous verbiage that were we to decide was helpful must be added to almost every single description...

[ToddAndMargo]

Hi Curt,

Thank you for reopening!

I do not like $needle unless there is corresponding $haystack somewhere near by. When I first saw needle, I thought needle was yet another reference that I did not understand. This is why in the first example I posted, I used both $Needle and $Haystack. When written this way, it makes a lot of sense. And it is fun to write too.

I put quotes around True and False as I wanted to differentiate them from the spoken (English) True and the programming True. But I do see you point. How about putting them in italics?

I like to spell things out like $Position, instead of $pos as I want to make it as clear as possible. When explaining concepts, I think it is best to write them out. The programmer can shorten then to $p later if he wants.

As for the "redundant (0)", I did this on purpose. I don't always know when things start counting from one or from zero. Perl 5's match "m/" is a real offender here as they start from one. (Talk about having to rewrite a bunch of stuff when converting from P5 to P6!). Now strings in other language's or other language's functions may or may not start at zero and if you are familiar with others (I am several), it is easy to goof them up, even if you know that Perl 6 starts at zero. I am king of the goof ups.

The thing I would like to see the most in the documentation is the functions written plainly for new and regular users and not require the speciality knowledge of the developers to figure out. The developers have their own specifications sheets. Leave the docs to the rest of us riff-raff!

-T

[ToddAndMargo]

Speaking of not explaining every parameter. Where in the following does it state that there is a single return parameter and that it is of type boolean ("Bool")?

And what the heck is Int(Cool:D)? Is it an Int or a Cool and is constrained D or not?

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

[finanalyst]

Todd, The language you use may be unremarkable in the society you keep, but for me, and perhaps others in the global community of sixy perl, it's irritating and comes off as whiny. Since we are both adults, as in over sixty, I'm being frank. I have programmed in C for embedded systems and dispaired at the documentation, translated from Chinese, and got next to no feedback. I am developing a couple of web sites in GRAV, which uses PHP and Twig, and some other technologies. At a certain point the documentation seems good, but then stops, and I get told to look at the source code. There is a long way to go for perl6 documentation! I think the perldoc equivalent is broken and I haven't even tried using it. Mostly when I need something I find it in the language docs, and when that fails, a question on IRC gets an almost immediate response. For a community based initiative, perl6 is way way better than many commercial products. The things I think need working on are actually current topics on the developers' list, eg how to index stuff, so that when you type in a keyword you get relevant information. My feeling is that there needs to be a rethink about the way documentation is provided. But just how eludes me. But I also think that in some ways perl6 documentation is at the leading edge for languages. I get that it forms a sort of language in itself, explaining a language in something other language than itself is not easy. However, after some work it becomes easier. I remember when I first came across Backus Naur formalism and found it difficult. Now it's the easiest thing to understand. The way some other languages are documented, eg PHP, seems quite primitive in comparison. Perhaps the documentation could do with an introduction that explains how to unpack the definitions. By the way I'm in the middle of Brian Foy's perl6 book. It explains a number of things I hadn't twigged before. Eg :D. Well worth reading. Also I remember not so long ago Brian asking all sorts of finicky questions, without getting hissy about the way things are now. The result is his book. This community is generous and helpful. I think that is something worth keeping. Which means accepting it for what it is without imposing an attitude, and finding ways to add piecemeal improvements. Some are accepted, some are not. Regards, Richard

…

On Wed, 12 Sep 2018, 07:35 ToddAndMargo, ***@***.***> wrote: On 09/10/2018 08:18 PM, Richard Hainsworth wrote: > Todd, > > This seems to be an age in which 'opinion' and being uneducated seems to > count for more than working hard to learn. I'm too old now to change my > view that working hard to learn and respecting the views of the learned > are virtuous. Sorry if that sounds hard, but I think the people who work > hard on perl6, whether answering questions, writing documentation, > writing tests, and so on, are worthy of respect. > > After looking at the perl6 documentation, and I have been following its > development with enthusiasm since waiting for the next Apocalypse from > Larry, yet I still do not understand all of it eg., :D, but I recognise > that this form of concise expression has a great value if I can learn to > read it. > > The documentation may not be for beginners, and everyone believes there > needs to be more. > > In other words, if you want to create something that is 'better' for > beginners, then do so. In fact Curt was suggesting the same thing. But > because it is for beginners, this community rightly would call it a > tutorial and not a reference. > > I agree here with Curt that reference material should favour brevity > over beginner-ness. In fact, the majority of the people using this > documentation will be developers who have knowledge of other languages. > > Having worked with computers since I was 15 and now I am 60 (but never > as a professional) and looked at many languages, my experience is that > when I read the documentation of a new language the first time, I rarely > understand it. It's only after re-reading several times that the > terminology and concepts begin to sink in. Also, because I use multiple > languages in what I do, eg., php, html, css, twig, js, c, java, perl5, I > often forget what the correct syntax is for a particular language. So I > need a quick way to check, and to see a short example. I do not need > excessive explanations, or repetitions of basic concepts such as 0-based > counting. > > As to the complaint about $needle, I found almost exactly the same names > for parameters in the php reference on strpos() > (http://www.php.net/manual/en/function.strpos.php). Also, the reference > has a concise description of the function, which it then explains. > > Regards, > Richard Hi Richard, If I have been in anyway disrespectful, I do apologize. It was never my intent to be disrespectful in any way. I rather admire the graciousness of those who have shared their intellectual knowledge with me. I have been involved in electronics since a very small child. I now have a bachelors degree in Electronic and Computer Engineering, Cum Laude. And I have you beat by two years. So, young man, I have been programming things for years and years. Some of the documentation I used when I was doing automated testing was really something to behold. Perl 6's is worse. For an example of what I am speaking of, look at how Perl 5's perldocs does "index" as opposed to Perl 6. 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 sub index(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. Do you see a difference. In Perl 5's "perldoc -f", you walk away knowing how to use the function. In Perl 6, you walk away scratching your head wondering what the h*** did I just read? Perl 6 is a wonderful clean up of Perl 5, especially the sub declarations and regex's. The only step backward I see it the documentation. I too am a YUGE fan of brevity. M$'s documents use 1000 words where 10 will do. Drives me nuts. "Get to the point!" What I am after is being able to read the documentation and know how to use the function afterward. The "$needle", now that I know the story behind it, would be a lot more helpful if "$haystack" were somewhere to be found. I though it was some kind of reserved word. Now if the only thing this crotchety old man wanted to do was to to complain, then it would be different. But I do contribute. It took me over a half hour to figure out the documentation and write an explanation that made sense. Okay, if I was to write "contains" in the style of Perl 5's perldocs, I would write it like this. "contains": 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 See any difference? This is how perldoc would have done it. And "perldoc -f" IS NOT A TUTORIAL. Which one would you leave understanding the function? At any point in my example did you need developer level knowledge of Perl 6? I am not after a tutorial. I am after the same level of functionality that perldoc gives. Please feel free to use my example above. I don't care if you keep around the confusing developer lever definition if you also include auseful (to beginners) description as well. multi method contains(Str:D: Cool:D $needle, Int(Cool:D) $pos) Means nothing to someone just trying to figure out how to use the function. And, young man, do not be disrespectful of me. I am working my butt off trying to learn Perl 6. And I put a lot of work into trying to write a useful explanation of the function to assist others. Do not change the subject by telling me the documentation is not a tutorial. No one ever accused "perldoc -f" of being a tutorial. This is all part of Kaisen (constant improvement) of which open source shines to brightly. If you did not initially realize that the function docs were unnecessarily complicated for beginners and typical users, now you know. Also, the developers has their own specification sheet. There is no need to duplicate it in the function docs. -T — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#2303 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAWMnLwc0WW0ieVkeodE19PndA0kAAUTks5uaEjDgaJpZM4WgYt8> .