Now you may wish the documentation to be clearer and more verbose.

However the documentation is right. Optimizations notwithstanding, those two constructs are supposed to be the same as each other. Within Perl you are not supposed to be able to tell any difference. And when the documentation points to two constructs and says that they are the same, then they darned well better be the same in all contexts! Else the documentation is wrong. Which is why the documentation did not so document the case which is not the same in scalar context!

As for the reasonableness or not of this interpretation, I can only speak for myself. Perhaps I read unusually closely, but on this item I distinctly remember when I originally encountered that documentation that I understood the phrase "the same as" and correctly figured out how it would behave in scalar context. Indeed you can see that in my tenth post here. Now why do I remember that? Because I remember looking at it and wondering what was different between the two that were not listed as being the same.

So while you could certainly ask for clearer documentation of that fact, the documentation is supposed to be able to interpreted that closely. And in fact we have at least one real life example of someone who did just that.

Now read what merlyn wrote, again. He never asserted that it is reasonably documented. He just said that it is documented and derivable from the documentation. Contrary to your assertion, that claim is not "poppycock".

Actually, there are lots of ways to tell those apart. I've mentioned a few (did you read (tye)Re4: List context or not? that I mentioned in my update above?).

I'm glad that you could "guess" what would happen in a scalar context. But I thought you said that it is documented? You have quite an interesting definition of "documented" if it includes "guess" in the process.

You also bring up an important concept in Perl: That the use of a scalar context should prevent an operation from wasting the time and/or space of generating a whole list of values.

To me

@days[3,4,5]   # same as ($days[3],$days[4],$days[5])

implied (but did not document) that these two constructs should be the same to the point of neither one wastefully generating a list when used in a scalar context. And I thought the implementation would be smart enough to not even generate the list of subscripts (much less generate the list of values). To do this, the operations that would generate the list of subscripts need to know that they don't need to do this work.

So that documentation implied to me that the context in which an array slice is used would be "passed inside" the brackets to the code for the subscripts (just like how the context in which a function is called gets "passed inside" to the code for the return value).

And for the example given, you can't tell that this isn't what was happening since all of the following return the same value:

    scalar( @days[3,4,5] )
    @days[ scalar( 3,4,5 ) ]
    scalar( ($days[3],$days[4],$days[5]) )
    $days[5]
[download]

Unfortunately, that optimization has not been implemented. If it were, then the following would also be true:

@days[3,4,@a]   # same as ($days[3],$days[4],$days[@a])

which it (currently) isn't.

So now I can tell you that I find that your apparent definition of the term "documented" is, frankly, poppycock. The most I'd be willing to admit is that the behavior of an array slice in a scalar context is "hinted at in the documentation", but I consider even that a stretch.

Which is why the documentation did not so document the case which is not the same in scalar context!

Well, that is an interesting assertion. I won't believe it unless you can find the author of the section and convince me that they actually recall making that conscious decision.

My guess was actually that the words "same as" were omitted in that case simply because that would make the comment long enough that it might wrap and ruin the format of the example!

Perhaps you should post PSI::ESP::Pod to CPAN. q-:

Finally, if "same as" in comments of example code is supposed to mean "same to the point of returning the same value in a scalar context", then please explain, from the same perldata.pod:

($map{'red'}, $map{'blue'}, $map{'green'}) = (0x00f, 0x0f0, 0xf00);

[...]

# same as map assignment above
%map = ('red',0x00f,'blue',0x0f0,'green',0xf00);
[download]

and why these two don't return the same values when used in a scalar context?
        - tye (but my friends call me "Tye")

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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.")
6. (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.