perldoc strict
perldoc -f sort
[download]

Frankly actually one of my few complaints about the perl documentation set is that it is poorly organized. I have encountered numerous examples of where you need to read several different docs with apparently nothing to do with each other in order to understand the behaviour of one thing that isn't documented explicitly.

Likewise on the nice day... ;-)

Yves / DeMerphq
--
When to use Prototypes?
Advanced Sorting - GRT - Guttman Rosler Transform

And just to give you a hard time about it:

Why would I look under either when trying to understand the strange behaviour of $a or $b?

There's nothing wrong with $a and $b. You can declare them with my, with local. They hold all kinds of scalar values and references. They're nice variables, get off their backs. :)

It's not like $| (ever try putting a reference in there?), or $_ (stomp stomp stomp stomp) or even $1 (Hey! It's readonly!) .

There's something wrong with sort. It uses these perfectly nice variables in strange and perverse ways so it's worth mentioning with sort -- let's mention it there. And there's something wrong with strict because it intentionally exempts $a and $b from stricture so that sort can get away with its perversity -- we should mention it there too.

But otherwise it's not the fault of the variables. Quit blaming the variables! :)

But if you want a footnote in perlvar I'm sure no-one would reject your patch, though.

Well I would say they should be documented under perlvar because of one simple reason: They allow action at a distance, which can be one of the most perverse bugs to track down.

Consider a novice-perl maintainer. He has to modify an old module. He uses the vars $a and $b to effect some change. Unknown to him however some part of the code calls a subroutine that overwrites $a and $b. He gets weird results and cant explain them. He looks in perlvar but sees no mention. He doesnt even know that sort is being used so he doesnt know to look in perlfunc. He doesnt look at the strict documentation because like a good novice he has strict turned on already. How other by asking or by luck is he to know or figure out what the hell is going on? (Oh im assuming that as a novice he found using the debugger as imposing as I did at the start and doesnt use it, or doesnt know how at all.)

See what I mean?

But you're right that instead of submitting a bug report, I should submit a patch. Which I will do.

Yves / DeMerphq
--
When to use Prototypes?
Advanced Sorting - GRT - Guttman Rosler Transform

$a and $b are not Perl predefined variables. So they do not belong into perlvar :-)
They are only of special use and meaning in a sort. So one might consider the occurance of $a and $b oustide of that as an error, but if that would raise an error you'd loose the ability to write custom sort subs.
Regarding your notes on the perl manpages, do you think that the unix manpages are better organized?
Well I think, if one is going to learn perl $a and $b should be noted along with the usage of strict, so one always remembers, that $a and $b will be used by a sort and so one better does not use them unless one explicitely wants to.
Having said that I think $a and $b are noted in the right place in the right document in a good (but worth improving) documentation.

Have a nice day
All decision is left to your taste

<Confusion>

How do you reconcile

$a and $b are not Perl predefined variables. So they do not belong into perlvar :-)

with

They are only of special use and meaning in a sort. So one might consider the occurance of $a and $b oustide of that as an error, but if that would raise an error you'd loose the ability to write custom sort subs.

The very fact that neither $a or $b need to be defined suggests to me that they are predeclared by perl itself. The fact that they are special only in the context of a sort function (which is nebulously defined BTW) which I agree is unlike the other perlvars does not mean they arent special. If anything it just means they are _more_ special. ;-)

</Confusion>

Regarding your notes on the perl manpages, do you think that the unix manpages are better organized?

No, nor are Microsofts. But thats not an argument by my book. Perl is amazingly well documented (IMO) but improving them is on ongoing task that should be supported (also IMO)

I didnt say that $a and $b _shouldnt_ be documented in the places they are, but merely that they should _also_ be documented in perlvar (perhaps with reference to the other documentation.)

Yves / DeMerphq
--
When to use Prototypes?
Advanced Sorting - GRT - Guttman Rosler Transform