Your skill will accomplish
what the force of many cannot
Actually, the terse syntax examples given in the Perl documentation convey subtle meaning to those who are aware of the conventions being used and changing "chmod LIST" to "chmod MODE,LIST" would convey incorrect information to such people. (To become such a person, in part, one just needs to read, understand, and remember the 2nd paragraph of perlfunc.)
I don't mind being told "mkdir FILENAME" because it hints at this possibility:
I started down the road of proposing that one of those conventions might actually be involved in the choice of "FILENAME" over "DIRNAME", because I noticed this:
But that doesn't make sense for a lot of reasons.
I also noticed:
So, how does opendir describe its argument?
Now, that needs to say "DIRHANDLE" and not "FILEHANDLE", because you can't use a Perl DIRHANDLE as a Perl FILEHANDLE so that distinction is rather important. There is no such distinction between a FILENAME and a DIRNAME for Perl (nor for Unix, nor for Windows).
But why is that "EXPR" and not "FILENAME"? Well, it is a common choice:
One could argue that "do EXPR" helps to convey the point that "any (other) expression gets interpretted as a file name" as opposed to possibly implying that Perl does something like looking at the value to see if it looks like a file name.
And that might explain the choice of "EXPR" for these cases as well:
Though, I think the case of noticing FILEHANDLE and DIRHANDLE exceptions really is about examining the value not about different syntax, so I find the "EXPR" choice less valuable here. But changing "stat EXPR" to "stat FILENAME" draws too much attention to the distinction between "FILE" and "DIR" in:
While I think changing "DBNAME" to "FILENAME" would significantly improve the clarity here:
(Because "DBNAME" isn't a "FILENAME" in most contexts I deal with -- though, perhaps "FILENAME" was avoided since suffixes likely get appended.)
How about places that don't use "EXPR"?
I find "OLDNAME" a much better choice than "OLDFILE". Similar to the starting complaint, "OLDFILE" could be the name of a directory. But more important, for me, is that "OLDFILE" doesn't as clearly convey that what is given is the name of a file not some handle or other representation. I also wouldn't go more explicit like these:
because I would worry about implying that these can't be used on directories [which isn't something I worry about implying for mkdir() or rmdir()]. One could argue for:
but I'd probably depart even further and go with:
After considering the broader context, I think most of the uses of "FILENAME" really should be changed to "DIRNAME". Not because I find those uses of "FILENAME" confusing or inappropriate, but because they are cases where the distinction doesn't matter and so "DIRNAME" is just slightly clearer. (I find many cases that are a lot more in need of improvement than the one that started this thread.)
Contrast that with changing "lstat EXPR" to "lstat FILENAME". I don't like "lstat FILENAME" as it sounds like it might be trying to imply that you can't use it on directories or links, but only on plain files. But I also see no reason to use "EXPR" for that case. I think I prefer "lstat PATHNAME".
So my updates would only be as follows:
So I'd explicitly leave these unchanged: