Why was documentation for open FILEHANDLE removed from perlfunc?

As Curtis and Ed both point out in the comments, perldoc -f open contains the following passage which does document the behavior. I must admit to only being able to notice that part if I search for the string $ARTICLE ;-)

As a shortcut a one-argument call takes the filename from the global scalar variable of the same name as the filehandle:

$ARTICLE = 100;
open(ARTICLE) or die "Can't find article $ARTICLE: $!\n";

Here $ARTICLE must be a global (package) scalar variable - not one declared with my or state.

While writing "How does open 0; print <0>; turn every Perl program into a quine?", I realized that the documentation of how open behaves when no filename expressions is provided was removed from perlfunc.

After a few rounds of git bisect, it seems the information was removed as part of commit 1578dcc… with the commit message “[perl #117223] Remove IO::File example from perlfunc.”

Methinks the commit does a little more than that. Inter alia, I do not think the following should have been removed:

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 18ecd40..129012c 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -3909,12 +3909,6 @@ FILEHANDLE is an expression, its value is the real filehandle.  (This is
 considered a symbolic reference, so C<use strict "refs"> should I<not> be
 in effect.)

-If EXPR is omitted, the global (package) scalar variable of the same
-name as the FILEHANDLE contains the filename.  (Note that lexical
-variables--those declared with C<my> or C<state>--will not work for this
-purpose; so if you're using C<my> or C<state>, specify EXPR in your
-call to open.)
-

The associated bug report does not seem to justify the removal of documentation of existing behavior either:

Perfunc contains some example code for 'read_myfile_munged'. There are various problems with that code but I don't need to list them all here - the simplest thing is just to remove it since IO::File is no longer needed to create filehandles that get automatically closed.

Right now, I am assuming the explanation of open FILEHANDLE fell victim to an editing error that went unnoticed (after all, I hope no one used this ~~feature~~ unexpected behavior), because after reading perldoc -f open many times, I simply cannot see this behavior documented anywhere in versions after this commit.

It is behavior that exists, and should be documented.

Before I put time into a patch, I would like to find out if there is a reason the behavior of open FILEHANDLE should NOT be documented.