Outdated documentation in perlopentut

p5pRT commented 10 years ago

Migrated from rt.perl.org#121839 (status was 'resolved')

Searchable as RT121839$

p5pRT commented 10 years ago

From the.rob.dixon@gmail.com

This is a bug report for perl from the.rob.dixon@gmail.com\, generated with the help of perlbug 1.39 running under perl 5.16.2.

The section in `perlopentut` titled "The Minus File" is simply wrong in the context of current best practice.

It says

... Perl's "open" function treats a file whose name is a single minus\, "-"\, in a special way. If you open minus for reading\, it really means to access the standard input. If you open minus for writing\, it really means to access the standard output.

However this applies only to a call like

open FH\, '>-';

which opens FH as a synonym of STDOUT.

If I was to do things "correctly" and write

open my $fh\, '>'\, '-';

then I would simply create an output file called `-`.

This needs to be fixed

Flags: category=docs severity=medium

Site configuration information for perl 5.16.2:

Configured by strawberry-perl at Fri Nov 2 00:34:53 2012.

Summary of my perl5 (revision 5 version 16 subversion 2) configuration:

Platform: osname=MSWin32\, osvers=4.0\, archname=MSWin32-x86-multi-thread uname='Win32 strawberry-perl 5.16.2.1 #1 Fri Nov 2 00:33:54 2012 i386' config_args='undef' hint=recommended\, useposix=true\, d_sigaction=undef useithreads=define\, usemultiplicity=define useperlio=define\, d_sfio=undef\, uselargefiles=define\, usesocks=undef use64bitint=undef\, use64bitall=undef\, uselongdouble=undef usemymalloc=n\, bincompat5005=undef Compiler: cc='gcc'\, ccflags =' -s -O2 -DWIN32 -DPERL_TEXTMODE_SCRIPTS -DPERL_IMPLICIT_CONTEXT -DPERL_IMPLICIT_SYS -fno-strict-aliasing -mms-bitfields'\, optimize='-s -O2'\, cppflags='-DWIN32' ccversion=''\, gccversion='4.6.3'\, gccosandvers='' intsize=4\, longsize=4\, ptrsize=4\, doublesize=8\, byteorder=1234 d_longlong=undef\, longlongsize=8\, d_longdbl=define\, longdblsize=12 ivtype='long'\, ivsize=4\, nvtype='double'\, nvsize=8\, Off_t='long long'\, lseeksize=8 alignbytes=8\, prototype=define Linker and Libraries: ld='g++'\, ldflags ='-s -L"C:\strawberry\perl\lib\CORE" -L"C:\strawberry\c\lib"' libpth=C:\strawberry\c\lib C:\strawberry\c\i686-w64-mingw32\lib libs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32 -ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr -lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32 perllibs=-lmoldname -lkernel32 -luser32 -lgdi32 -lwinspool -lcomdlg32 -ladvapi32 -lshell32 -lole32 -loleaut32 -lnetapi32 -luuid -lws2_32 -lmpr -lwinmm -lversion -lodbc32 -lodbccp32 -lcomctl32 libc=\, so=dll\, useshrplib=true\, libperl=libperl516.a gnulibc_version='' Dynamic Linking: dlsrc=dl_win32.xs\, dlext=dll\, d_dlsymun=undef\, ccdlflags=' ' cccdlflags=' '\, lddlflags='-mdll -s -L"C:\strawberry\perl\lib\CORE" -L"C:\strawberry\c\lib"'

Locally applied patches:

@INC for perl 5.16.2: C:/strawberry/perl/site/lib/MSWin32-x86-multi-thread C:/strawberry/perl/site/lib C:/strawberry/perl/vendor/lib C:/strawberry/perl/lib .

Environment for perl 5.16.2: HOME (unset) LANG (unset) LANGUAGE (unset) LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=C:\Program Files (x86)\ImageMagick-6.8.3-Q16;C:\Program Files\ImageMagick-6.8.3-Q16;C:\Program Files (x86)\NVIDIA Corporation\PhysX\Common;C:\Program Files (x86)\PC Connectivity Solution\;C:\Program Files\Common Files\Microsoft Shared\Windows Live;C:\Program Files (x86)\PHP\;C:\Windows\system32;C:\Windows;C:\Windows\System32\Wbem;C:\Windows\System32\WindowsPowerShell\v1.0\;C:\Program Files\jEdit;C:\usr\local\ppt\bin;C:\Program Files (x86)\GnuWin32\bin;C:\Program Files (x86)\Smart Projects\IsoBuster;C:\Program Files (x86)\Oracle\Berkeley DB 11gR2 5.3.15\bin;C:\Program Files (x86)\Git\cmd;C:\Program Files (x86)\Bazaar;C:\Program Files (x86)\Lua\5.1;C:\Program Files (x86)\Lua\5.1\clibs;C:\strawberry\c\bin;C:\strawberry\perl\site\bin;C:\strawberry\perl\bin;C:\Program Files\TortoiseSVN\bin;C:\MediaInfoCLI;C:\Program Files (x86)\MKVToolNix;C:\Program Files (x86)\Subversion\bin;C:\Program Files (x86)\Common Files\Ulead Systems\MPEG;C:\Program Files (x86)\QuickTime\QTSystem\;C:\Program Files\Microsoft Network Monitor 3\;C:\Program Files\Calibre2\;C:\Program Files (x86)\MySQL\MySQL Utilities 1.3.4\;C:\Program Files (x86)\Common Files\Acronis\SnapAPI\;C:\Program Files\WinRAR;C:\Program Files\Common Files\Microsoft Shared\Windows Live;C:\Program Files (x86)\Common Files\Hackety Hack\0.r1529\..;C:\Program Files (x86)\IDM Computer Solutions\UltraCompare\;C:\ffmpeg\bin;C:\Program Files (x86)\Serviio\lib;C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\x86_amd64;C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\amd64;C:\SWIG;C:\MinGW\bin;C:\MinGW\MSYS\1.0\bin;C:\Python27;C:\Curl;C:\pkg-config\bin;C:\glib\bin;C:\gettext-runtime\bin;C:\Program Files (x86)\IDM Computer Solutions\UltraEdit\;C:\LuaRocks\2.0;C:\Program Files (x86)\Android\android-sdk\platform-tools;C:\Ruby193\bin;C:\Ruby193.DevKit\bin;C:\Program Files (x86)\Nmap;C:\MobiPerl;C:\Program Files (x86)\EaseUS\Todo Backup\bin\x64\ PERL_BADLANG (unset) SHELL (unset)

p5pRT commented 10 years ago

From @khwilliamson

On 05/09/2014 09:19 PM\, Rob Dixon (via RT) wrote:

# New Ticket Created by Rob Dixon # Please include the string: [perl #121839] # in the subject line of all future correspondence about this issue. # \<URL: https://rt-archive.perl.org/perl5/Ticket/Display.html?id=121839 >

This is a bug report for perl from the.rob.dixon@gmail.com\, generated with the help of perlbug 1.39 running under perl 5.16.2.

-----------------------------------------------------------------

The section in `perlopentut` titled "The Minus File" is simply wrong in the context of current best practice.

It says

... Perl's "open" function treats a file whose name is a single minus\, "-"\, in a special way. If you open minus for reading\, it really means to access the standard input. If you open minus for writing\, it really means to access the standard output.

However this applies only to a call like

open FH\, '>-';

which opens FH as a synonym of STDOUT.

If I was to do things "correctly" and write

open my $fh\, '>'\, '-';

then I would simply create an output file called `-`.

This needs to be fixed

It would be helpful if you could supply a patch with proposed wording.

p5pRT commented 10 years ago

The RT System itself - Status changed from 'new' to 'open'

p5pRT commented 10 years ago

From @jkeenan

On Fri May 09 20:19:33 2014\, the.rob.dixon@gmail.com wrote:

This is a bug report for perl from the.rob.dixon@gmail.com\, generated with the help of perlbug 1.39 running under perl 5.16.2.

-----------------------------------------------------------------

The section in `perlopentut` titled "The Minus File" is simply wrong in the context of current best practice.

It says

... Perl's "open" function treats a file whose name is a single minus\, "-"\, in a special way. If you open minus for reading\, it really means to access the standard input. If you open minus for writing\, it really means to access the standard output.

Where is the text you are citing found?

I searched in both perl 5.16 -- the version you used to generate the bug report -- and in blead and I could not find these texts anywhere\, much less in pod/perlopentut.pod.

##### perl -v | head -2 | tail -1 This is perl 5\, version 16\, subversion 3 (v5.16.3) built for x86_64-linux

$ find . -type f | xargs grep -inE '(Minus File|function treats a file|open minus)' ./cpan/Pod-Perldoc/corpus/perlfunc.pod:351: -M Script start time minus file modification time\, in days. ./pod/perlfunc.pod:396: -M Script start time minus file modification time\, in days. ##### $ ./perl -Ilib -v | head -2 | tail -1 This is perl 5\, version 21\, subversion 4 (v5.21.4 (v5.21.3-56-gf702f02*)) built for x86_64-linux [ $ find . -type f | xargs grep -inE '(Minus File|function treats a file|open minus)' ./cpan/Pod-Perldoc/corpus/perlfunc.pod:351: -M Script start time minus file modification time\, in days. ./pod/perlfunc.pod:396: -M Script start time minus file modification time\, in days. #####

Thank you very much. Jim Keenan

p5pRT commented 10 years ago

From @iabyn

On Fri\, Aug 22\, 2014 at 05:32:06PM -0700\, James E Keenan via RT wrote:

Where is the text you are citing found?

I searched in both perl 5.16 -- the version you used to generate the bug report -- and in blead and I could not find these texts anywhere\, much less in pod/perlopentut.pod.

It's present up to 5.19.2:

=head2 The Minus File

Again following the lead of the standard shell utilities\, Perl's C\ function treats a file whose name is a single minus\, "-"\, in a special way. If you open minus for reading\, it really means to access the standard input. If you open minus for writing\, it really means to access the standard output.

After which it was removed with this commit:

commit b25a8b16a0df7e9516919b58acaed4610ca963a2 Author: Tom Christiansen \tchrist@perl\.com AuthorDate: Fri Jul 12 10:20:36 2013 -0400 Commit: Ricardo Signes \rjbs@cpan\.org CommitDate: Tue Jul 23 21:25:54 2013 -0700

Don't patch perlopentut: rewrite it completely

So I guess the ticket can be closed.

-- You live and learn (although usually you just live).

p5pRT commented 10 years ago

From tchrist@perl.com

Dave Mitchell \davem@iabyn\.com wrote on Mon\, 25 Aug 2014 20:55:40 BST:

On Fri\, Aug 22\, 2014 at 05:32:06PM -0700\, James E Keenan via RT wrote:

Where is the text you are citing found?

I searched in both perl 5.16 -- the version you used to generate the bug report -- and in blead and I could not find these texts anywhere\, much less in pod/perlopentut.pod.

It's present up to 5.19.2:
=head2 The Minus File

Again following the lead of the standard shell utilities\, Perl's
C\<open> function treats a file whose name is a single minus\, "\-"\, in a
special way\.  If you open minus for reading\, it really means to access
the standard input\.  If you open minus for writing\, it really means to
access the standard output\.
After which it was removed with this commit:
commit b25a8b16a0df7e9516919b58acaed4610ca963a2
Author&#8203;:     Tom Christiansen \<tchrist@&#8203;perl\.com>
AuthorDate&#8203;: Fri Jul 12 10&#8203;:20&#8203;:36 2013 \-0400
Commit&#8203;:     Ricardo Signes \<rjbs@&#8203;cpan\.org>
CommitDate&#8203;: Tue Jul 23 21&#8203;:25&#8203;:54 2013 \-0700

    Don't patch perlopentut&#8203;: rewrite it completely

Yes\, Ricardo kindly checked in the brief rewrite I did of perlopentut last year\, the one I wrote with the aim of making that manpage much shorter and clearer\, hitting the important points and omitting esotoric trivia. Minus was one of those (many\, many) bits I decided was not core knowledge crucial for a new learner to know when first starting.

The old one was more of of FMTEYEWTK about I/O than a tut\, so the name was always a bit off anyway.

The minus thing is of course still in perlfunc's open entry\, since that sort of reference doc needs to be exhaustive in detail\, however painful that should be. It's certainly the longest function description in the Camel's chapter on functions\, covering I-dunno-how-many pages.

So I guess the ticket can be closed.

I should think so.

thanks\,

--tom

p5pRT commented 10 years ago

From @jkeenan

Thanks to all for taking the time to look at this. Marking ticket Resolved.

p5pRT commented 10 years ago

@jkeenan - Status changed from 'open' to 'resolved'

Perl / perl5