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 <toddandma...@zoho.com> wrote: > >> Le dim. 30 sept. 2018 à 11:32, ToddAndMargo <toddandma...@zoho.com > >> <mailto:toddandma...@zoho.com>> 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: > >> > >> sub join($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 ', ', <a b c>; # RESULT: «a, b, c» > >> > >> Note that the method form does not flatten sublists: > >> > >> say (1, <a b c>).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 > -- Simon Proctor Cognoscite aliquid novum cotidie http://www.khanate.co.uk/
