On 9/26/18 6:12 PM, Peter Scott wrote:
On 9/26/2018 3:21 PM, ToddAndMargo wrote:
I use words all the time. I never would have figured it out
from
multi method words(Str:D $input: $limit = Inf --> Positional)
Do your really think any beginner would be able to figure out
"words" from the above?
If the beginner had studied the metasyntax of function prototypes,
probably. But this is not necessarily for beginners, this is reference
documentation, which has to serve a purpose unencumbered by pedagogical
weight. This documentation is not a tutorial, it is autogenerated. You
are relatively unique in insisting that the reference documentation also
function as a beginners' roadmap, so you are going to experience this
kind of frustration repeatedly.
I taught Perl 5 trainings for many years in addition to authoring books,
videos, and courses on same, and the difference between what is best for
learning and what is best for reference is stark. I heard about people
who claim to have taught themselves Perl 5 from the Camel instead of the
Llama, but they are few and far between, and in any case, most of the
Camel contains exposition, if dense. You're looking just at something
corresponding to the list of functions. I honestly think you'll get
further forcing yourself to plow through the new Learning Perl 6 book
than these random access forays into reference specs. brian just spent
two years of intense effort arranging it to fit precisely the graduated
path your questions tell me you need.
Hi Peter,
First off, courses, beginners books, and the likes, do not work for me.
What does work is just code what my customers and I need. And a lot of
what do is to Read The Freakin' Manual (RTFM, now-a-days called "just
Google it").
The Perl 6 routine's documentation is written as a refresher to
those how already know what they are doing, and as such is
pretty useless to common users seeking wisdom. Why even post
it to the general public? The design specifications and
not posted (except if you Google them).
*** I am not after the manual to teach me how to use Perl. ***
In several instances, I have know how to use functions and looked
backwards in the manual to see if there were any other bits
I could use. I COULD NOT REVERSE ENGINEER the manual
EVEN THOUGH I completely understood how to use the function.
This is bad. Really bad.
This is what I am after:
The manual should be written like a spoken language dictionary.
1) it should tell you what that word is
2) show you how to use it in context.
And I might point out that a dictionary is not a HOW TO
book to teach you the language.
3) when calling other term to explain things, it should
pick the easiest term available. It should not pick
any nasty, advanced terms. (Unless the writer enjoys
confusing the reader and bragging about how smart
he is. And he is a jerk.)
4) It can reference advanced topic or follow on topics
but keep them out of the topic. Dictionaries do this
all the time. "See such and such"
5) leave the common user knowing how to use the topic,
not wonder if the writer writes manuals for the
IRS in his spare time.
Perl 5's perldoc did a wonderful job of this.
I have been posting RFE about this as they come up.
So I am trying to be part of the solution instead
of constantly gripping about the problem.
-T
