Also, a hopefully less steep introduction: <plug> https://opensource.com/article/18/9/signatures-perl-6 </plug>
> On 2 Oct 2018, at 11:01, Simon Proctor <simon.proc...@gmail.com> 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 <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/
