Your expectations make no sense to me here.
First of all when I read documentation I assume that the
person writing it knew what they were saying. I constantly
test what they are saying, but what I am testing is (in an
ideal world) my comprehension of what they are saying and
not the correctness of what was said. If one thing does
not say "the same as" and 2 presented beside it do, that
difference is likely to not be an accident and deserves
analysis.
Secondly before jumping to beliefs, sanity check them.
For instance you say that you look at that example and
thought that the context should pass through to the
inside to the last argument. But in that case then ..
in that example would be the flip-flop operator, not the
range operator. However it gives a range, therefore the
context is not passed through. In other words there is
no way that what you describe as wanting could
possibly be what is documented there!
Thirdly my experience with the Perl documentation is that
it is very carefully written. Take, for instance, the
example that you point to and ask me to explain. Well
what does it say? It says, same as map assignment
above. It does not say that the construct is the same,
it says that the assignment is the same. Now one
of the key points about context is that what is being
assigned to on the LHS sets the context for the RHS. In
other words the context in which the assignment is
happening is part of the assignment. Given that I
fail to see how it is relevant to the rest of this
discussion.
Now you want me to produce PSI::ESP::Pod? Well we both
know that is a joke, but here are a few principles that
it would include:
- The Perl documentation was written by people who
know their subject well and do their best to be careful
about how they say things. It is generally unwise to
assume they omitted something by accident. It was
generally omitted on purpose, and by trying to figure
out what tangent they tried to avoid discussing you
will often notice interesting things.
- The Perl documentation deserves to be re-read. Upon
re-reading you will notice things that you missed before.
The same thing goes for reading books written by the
people who wrote that documentation.
- Details of the wording tend to be very significant.
Do not read it like you would normal sloppy speech.
Far more thought and energy went into documentation than
we normally put into what we say.
- Generally it is safe to assume that constructs fit
into categories that have already been explained. For
instance in perldata it explains that the two major
contexts are list and scalar and explains the division.
Unless further clarification is made, it is safe to
assume that any construct you see will fall fairly
cleanly into this classification.
- It is helpful to not think in terms of the
implementation, but rather to try to form a sense of
how Larry thinks. One thing that he has claimed, which
I can well believe, is that his thought process is
rather messy but he is very good at synthesis later.
In that case there are cracks, they show, but there are
also guiding principles. Learn the exceptions, but try
to find and keep those principles clear. (This is
called "trying to read Larry's mind.")
- (Unfortunately) it is often the case that sections
of the documentation try to say so much in so little
space that it is more useful for confirming what you
already know than it is for learning from. That is
life.
Now applying those principles to the section under
discussion, what do we get? We get that 2 out of 3
constructs are the same but the third is probably
different. Since we know from elsewhere that the way
that the others are expanded is different in scalar
context, we have a pretty good idea what was not
discussed. Since the principle that things generally
fall into scalar and list context has been laid out and
is key, from the example given we can take it that the
arguments to the slice are in list context because we
are getting the range operator rather than a flip-flop.
Given what we know about list context, you should now
have clear expectations about what happens if, for
instance, you put function calls in that argument list.
They will not be optimized away, but they will be
called, and they will be called in list context. The
return values will not show, but side-effects will.
Now none of this is laid out explicitly. Indeed if
you were not reading carefully, paying close attention
to wording you would miss it. However if you know it
and go back to the documentation, it really is there.
Don't take shortcuts. Don't make up absurd theories.
Don't form parallels to other (just as carefully
worded) sections in trying to misunderstand. It is
there.
Of course for most people it is only going to be
useful if they already know it and therefore can make
educated guesses about why things were phrased as
they were.
But what merlyn said is not poppycock.
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.