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
