merlyn,
Let me preface my post by stating that I agree with most of what you are saying. I do think it is confusing to be able to use the keywords interchangeably but not have interchangeable behavior - regardless of it being documented. Since both the Camel and Llama are copyrighted, I will quote from perldoc perlsyn.

The "foreach" keyword is actually a synonym for the "for" keyword, so you can use "foreach" for readability or "for" for brevity.

I know that the rest of the documentation explains the distinct differences in the behavior (implicit aliasing and localizing), but how hard would it be to add:

"Caution: While the keywords are interchangeable, the behavior of the looping constructs are not. What appears in the parens after the keywords determines the internal behavior".

It certainly isn't your fault that most people don't carefully read the documentation nor is it mine. That doesn't negate the fact that it happens everyday. Taking that one snippet out of context would lead people to believe they are the same thing. Using the "Try It And See" method in a naive way supports this since interchanging for and foreach keywords results in identical behavior.

In summary, it is my belief that that because the keywords are interchangeable and there are no big red warning flags in the documentation, people are going to incorrectly believe there is no difference.