perl.pod description of perl is horribly dated

[p5pRT]

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

Searchable as RT72710$

[p5pRT]

From @xdg

Created by @xdg

The Perl community has been doing a lot of work to refresh the
image of Perl as a modern, relevent programming language. Sadly,
the basic "man perl" page description of Perl hasn't kept up.

I suggest that the description in perl.pod be amended to reflect
the language used on http​://www.perl.org/about.html

Perl Info

Flags:
    category=docs
    severity=medium

Site configuration information for perl 5.10.1:

Configured by david at Mon Aug 24 07:23:49 EDT 2009.

Summary of my perl5 (revision 5 version 10 subversion 1) configuration:
   
  Platform:
    osname=linux, osvers=2.6.28-14-generic, archname=x86_64-linux-ld
    uname='linux vulcan 2.6.28-14-generic #46-ubuntu smp wed jul 8 07:41:18 utc 2009 x86_64 gnulinux '
    config_args='-de -Dusedevel -Dprefix=/opt/perl/5.10.1 -Dusemorebits -Uversiononly -Dmydomain=.hyperbolic.net [email protected] -Dperladmin=dagolden.cpan.org -Dcc=ccache gcc'
    hint=recommended, useposix=true, d_sigaction=define
    useithreads=undef, usemultiplicity=undef
    useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
    use64bitint=define, use64bitall=define, uselongdouble=define
    usemymalloc=n, bincompat5005=undef
  Compiler:
    cc='ccache gcc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
    optimize='-O2',
    cppflags='-fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
    ccversion='', gccversion='4.3.3', gccosandvers=''
    intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
    d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
    ivtype='long', ivsize=8, nvtype='long double', nvsize=16, Off_t='off_t', lseeksize=8
    alignbytes=16, prototype=define
  Linker and Libraries:
    ld='ccache gcc', ldflags =' -fstack-protector -L/usr/local/lib'
    libpth=/usr/local/lib /lib /usr/lib /lib64 /usr/lib64
    libs=-lnsl -ldb -ldl -lm -lcrypt -lutil -lc
    perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
    libc=/lib/libc-2.9.so, so=so, useshrplib=false, libperl=libperl.a
    gnulibc_version='2.9'
  Dynamic Linking:
    dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
    cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib -fstack-protector'

Locally applied patches:
    


@INC for perl 5.10.1:
    /opt/perl/5.10.1/lib/5.10.1/x86_64-linux-ld
    /opt/perl/5.10.1/lib/5.10.1
    /opt/perl/5.10.1/lib/site_perl/5.10.1/x86_64-linux-ld
    /opt/perl/5.10.1/lib/site_perl/5.10.1
    .


Environment for perl 5.10.1:
    HOME=/home/david
    LANG=en_US.UTF-8
    LANGUAGE (unset)
    LC_COLLATE=C
    LC_CTYPE=en_US.UTF-8
    LD_LIBRARY_PATH (unset)
    LOGDIR (unset)
    PATH=.:~/bin:~/git/utility-scripts:/opt/perl/5.10.1/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games
    PERLPATH=/opt/perl/5.10.1/bin
    PERL_BADLANG (unset)
    PERL_EXTUTILS_AUTOINSTALL=--default-deps
    SHELL=/bin/bash

[p5pRT]

From @richardfoley

Hi David,

Sounds like a fine idea. How about sending in a better suggestion...?

--
Richard Foley
Ciao - shorter than aufwiedersehen

http​://www.rfi.net/

On Thursday 11 February 2010 03​:28​:29 David Golden wrote​:

# New Ticket Created by "David Golden"
# Please include the string​: [perl #72710]
# in the subject line of all future correspondence about this issue.
# <URL​: http​://rt.perl.org/rt3/Ticket/Display.html?id=72710 >

This is a bug report for perl from xdaveg@​gmail.com,
generated with the help of perlbug 1.39 running under perl 5.10.1.

-----------------------------------------------------------------
[Please describe your issue here]

The Perl community has been doing a lot of work to refresh the
image of Perl as a modern, relevent programming language. Sadly,
the basic "man perl" page description of Perl hasn't kept up.

I suggest that the description in perl.pod be amended to reflect
the language used on http​://www.perl.org/about.html

[Please do not change anything below this line]
-----------------------------------------------------------------
---
Flags​:
category=docs
severity=medium
---
Site configuration information for perl 5.10.1​:

Configured by david at Mon Aug 24 07​:23​:49 EDT 2009.

Summary of my perl5 (revision 5 version 10 subversion 1) configuration​:

Platform​:
osname=linux, osvers=2.6.28-14-generic, archname=x86_64-linux-ld
uname='linux vulcan 2.6.28-14-generic #46-ubuntu smp wed jul 8 07​:41​:18
utc 2009 x86_64 gnulinux ' config_args='-de -Dusedevel
-Dprefix=/opt/perl/5.10.1 -Dusemorebits -Uversiononly
-Dmydomain=.hyperbolic.net -Dcf_email=xdaveg@​gmail.com
-Dperladmin=dagolden.cpan.org -Dcc=ccache gcc' hint=recommended,
useposix=true, d_sigaction=define
useithreads=undef, usemultiplicity=undef
useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef
use64bitint=define, use64bitall=define, uselongdouble=define
usemymalloc=n, bincompat5005=undef
Compiler​:
cc='ccache gcc', ccflags ='-fno-strict-aliasing -pipe -fstack-protector
-I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
optimize='-O2',
cppflags='-fno-strict-aliasing -pipe -fstack-protector
-I/usr/local/include' ccversion='', gccversion='4.3.3', gccosandvers=''
intsize=4, longsize=8, ptrsize=8, doublesize=8, byteorder=12345678
d_longlong=define, longlongsize=8, d_longdbl=define, longdblsize=16
ivtype='long', ivsize=8, nvtype='long double', nvsize=16,
Off_t='off_t', lseeksize=8 alignbytes=16, prototype=define
Linker and Libraries​:
ld='ccache gcc', ldflags =' -fstack-protector -L/usr/local/lib'
libpth=/usr/local/lib /lib /usr/lib /lib64 /usr/lib64
libs=-lnsl -ldb -ldl -lm -lcrypt -lutil -lc
perllibs=-lnsl -ldl -lm -lcrypt -lutil -lc
libc=/lib/libc-2.9.so, so=so, useshrplib=false, libperl=libperl.a
gnulibc_version='2.9'
Dynamic Linking​:
dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
cccdlflags='-fPIC', lddlflags='-shared -O2 -L/usr/local/lib
-fstack-protector'

Locally applied patches​:

---
@​INC for perl 5.10.1​:
/opt/perl/5.10.1/lib/5.10.1/x86_64-linux-ld
/opt/perl/5.10.1/lib/5.10.1
/opt/perl/5.10.1/lib/site_perl/5.10.1/x86_64-linux-ld
/opt/perl/5.10.1/lib/site_perl/5.10.1
.

---
Environment for perl 5.10.1​:
HOME=/home/david
LANG=en_US.UTF-8
LANGUAGE (unset)
LC_COLLATE=C
LC_CTYPE=en_US.UTF-8
LD_LIBRARY_PATH (unset)
LOGDIR (unset)

PATH=.​:~/bin​:~/git/utility-scripts​:/opt/perl/5.10.1/bin​:/usr/local/sbin​:/us
r/local/bin​:/usr/sbin​:/usr/bin​:/sbin​:/bin​:/usr/games
PERLPATH=/opt/perl/5.10.1/bin
PERL_BADLANG (unset)
PERL_EXTUTILS_AUTOINSTALL=--default-deps
SHELL=/bin/bash

[p5pRT]

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

[p5pRT]

From @xdg

On Thu, Feb 25, 2010 at 1​:29 PM, Richard Foley <Richard.Foley@​rfi.net> wrote​:

Hi David,

Sounds like a fine idea. How about sending in a better suggestion...?

That's a placeholder bug as a reminder for perl 5.13. I already
patched perl.pod for 5.11 for clarity about getting access to help via
perldoc.

I do think there will be some debate over what exactly it will say,
but when 5.12 is out the door that's probably the right time for that
discussion.

David

[p5pRT]

From @timbunce

On Thu, Feb 25, 2010 at 12​:31​:39PM -0500, David Golden wrote​:

On Thu, Feb 25, 2010 at 1​:29 PM, Richard Foley <Richard.Foley@​rfi.net> wrote​:

Hi David,

Sounds like a fine idea. How about sending in a better suggestion...?

That's a placeholder bug as a reminder for perl 5.13. I already
patched perl.pod for 5.11 for clarity about getting access to help via
perldoc.

I do think there will be some debate over what exactly it will say,
but when 5.12 is out the door that's probably the right time for that
discussion.

Quite a lot of thought when into the wording of http​://www.perl.org/about.html

There might be some useful chunks to borrow.

Tim.

[p5pRT]

From @xdg

On Thu, Feb 25, 2010 at 6​:13 PM, Tim Bunce <Tim.Bunce@​pobox.com> wrote​:

I do think there will be some debate over what exactly it will say,
but when 5.12 is out the door that's probably the right time for that
discussion.

Quite a lot of thought when into the wording of http​://www.perl.org/about.html

There might be some useful chunks to borrow.

Which is almost exactly what the RT ticket says.

I think *after* 5.12 ships, *then* someone can bring in the text of
that page as a starting point for discussion.

From my recent conversation with Larry about changing the "abstract"
on the first line of the man page, his stipulation about changes was
that both historical back-ronyms for PERL be preserved to humorous
effect. So someone with a sense humor will have to figure out how to
integrate that with the perl.org text.

(And my sense of humor is about shot, these days, so that rules me out.)

-- David

[p5pRT]

From @cpansprout

On Thu Feb 25 16​:02​:52 2010, xdaveg@​gmail.com wrote​:

On Thu, Feb 25, 2010 at 6​:13 PM, Tim Bunce <Tim.Bunce@​pobox.com>
wrote​:

I do think there will be some debate over what exactly it will say,
but when 5.12 is out the door that's probably the right time for
that
discussion.

Quite a lot of thought when into the wording of
http​://www.perl.org/about.html

There might be some useful chunks to borrow.

Which is almost exactly what the RT ticket says.

I think *after* 5.12 ships, *then* someone can bring in the text of
that page as a starting point for discussion.

From my recent conversation with Larry about changing the "abstract"
on the first line of the man page, his stipulation about changes was
that both historical back-ronyms for PERL be preserved to humorous
effect. So someone with a sense humor will have to figure out how to
integrate that with the perl.org text.

(And my sense of humor is about shot, these days, so that rules me
out.)

Does commit 72033c1 address this?

--

Father Chrysostomos

[p5pRT]

From @xdg

On Sat, Jan 7, 2012 at 4​:23 AM, Father Chrysostomos via RT
<perlbug-followup@​perl.org> wrote​:

Does commit 72033c1 address this?

Minimally, yes.

[p5pRT]

From @rjbs

I agree that perl.pod deserves more work, still. It reads too much like a superbrief summary of
perl500delta. I'll have go at something in a branch.

[p5pRT]

From [Unknown Contact. See original ticket]

I agree that perl.pod deserves more work, still. It reads too much like a superbrief summary of
perl500delta. I'll have go at something in a branch.

[p5pRT]

From @perhunter

On 01/15/2012 10​:25 PM, Ricardo SIGNES via RT wrote​:

I agree that perl.pod deserves more work, still. It reads too much like a superbrief summary of
perl500delta. I'll have go at something in a branch.

<off list>

hi ricardo,

last spring someone in london.pm (leopold iirc) asked about fixing up
perldoc.perl.org. i got inspired and drafted up several docs that i felt
were needed. at the moment i don't have access to them (he should have
some drafts) due to a disk problem. in any case the concepts of the docs
i think are valuable. one of them is what i was calling perlblurb. it is
based on perldoc perl but with short paragraph descriptions of each doc
and not a fairly useless one liner. text would also include related or
see also docs, level of skills needed, read early or later when needed,
etc.). basically a proper guide to what each doc really is and why it is
useful to read.

what do you think of this idea? when i get my files back, i can send
them to you. i don't want to post on p5p publicly yet (or ever! :).
hence our idea was to publish them on perldoc.perl first and later get
p5p to incorporate them. the other docs were a metadoc on how to read
the perldocs (tips, ideas, skimming, skill levels), a perl resources doc
(like the community doc but broader in scope) and another one.

thanx,

uri

[p5pRT]

From @jkeenan

On Sun Jan 15 19​:25​:51 2012, rjbs wrote​:

I agree that perl.pod deserves more work, still. It reads too much
like a superbrief summary of
perl500delta. I'll have go at something in a branch.

Have you created that branch?

Thank you very much.
Jim Keenan

[p5pRT]

From @rjbs

No, but FWIW it's still in my very short list of "claimed" RT tickets. :-/

[p5pRT]

From @jkeenan

On Wed Apr 04 18​:40​:34 2012, rjbs wrote​:

No, but FWIW it's still in my very short list of "claimed" RT tickets. :-/

rjbs​: Are you going to get to this, or can it be delegated to
someone(s) else?

Thanks.
Jim Keenan

[p5pRT]

From @rjbs

On Sun Mar 25 12​:15​:59 2012, jkeenan wrote​:

On Sun Jan 15 19​:25​:51 2012, rjbs wrote​:

I agree that perl.pod deserves more work, still. It reads too much
like a superbrief summary of
perl500delta. I'll have go at something in a branch.

Have you created that branch?

Check out http​://perl5.git.perl.org/perl.git/commitdiff/3a15abda70a53173e8b39f73f1000bc52

--
rjbs

[p5pRT]

From @rjbs

* James E Keenan via RT <perlbug-followup@​perl.org> [2013-01-27T20​:00​:13]

On Wed Apr 04 18​:40​:34 2012, rjbs wrote​:

No, but FWIW it's still in my very short list of "claimed" RT tickets. :-/

rjbs​: Are you going to get to this, or can it be delegated to
someone(s) else?

I would like to note, only because it astounded me, that I just finished
writing my patch and alerting you to it... *before* seeing this email. How
about that?

--
rjbs

[p5pRT]

From @jkeenan

On Sun Jan 27 19​:57​:04 2013, rjbs wrote​:

On Sun Mar 25 12​:15​:59 2012, jkeenan wrote​:

On Sun Jan 15 19​:25​:51 2012, rjbs wrote​:

I agree that perl.pod deserves more work, still. It reads too
much
like a superbrief summary of
perl500delta. I'll have go at something in a branch.

Have you created that branch?

Check out

http​://perl5.git.perl.org/perl.git/commitdiff/3a15abda70a53173e8b39f73f1000bc52

I like it, with only one question​: Should we continue to be so
Unix-specific in this line​:

#####
+B<awk>, and B<sh>, making it familiar and easy to use for Unix users to
#####

[p5pRT]

From @rjbs

* James E Keenan via RT <perlbug-followup@​perl.org> [2013-01-28T21​:46​:54]

I like it, with only one question​: Should we continue to be so
Unix-specific in this line​:

#####
+B<awk>, and B<sh>, making it familiar and easy to use for Unix users to
#####

I thought about that myself, but I think it is accurate, fair, and unoffensive.
Users of sed, awk, and sh will be almost perforce Unix users. Perl was
clearly inspired in large part by these tools, and it it easy to move from awk
and sh to Perl in a non-coincidental way. It makes Perl especially easy for
Unix users (or at least "power users," these days) to take what they know from
other toolkit pieces and come to Perl.

I thought about adding similar language relating to users coming to Perl from
Ruby or JavaScript and finding similar regular expressions or common data
types, but did not write anything.

--
rjbs

[p5pRT]

From @doughera88

On Tue, 29 Jan 2013, Ricardo Signes wrote​:

* James E Keenan via RT <perlbug-followup@​perl.org> [2013-01-28T21​:46​:54]

I like it, with only one question​: Should we continue to be so
Unix-specific in this line​:

#####
+B<awk>, and B<sh>, making it familiar and easy to use for Unix users to
#####

I thought about that myself, but I think it is accurate, fair, and unoffensive.
Users of sed, awk, and sh will be almost perforce Unix users. Perl was
clearly inspired in large part by these tools, and it it easy to move from awk
and sh to Perl in a non-coincidental way. It makes Perl especially easy for
Unix users (or at least "power users," these days) to take what they know from
other toolkit pieces and come to Perl.

I like the update. One quibble​: I think you meant "anywhere" not
"anyway"​:

Inline Patch

diff --git a/pod/perl.pod b/pod/perl.pod
index 3eb6d8d..a7ffbeb 100644
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -307,7 +307,7 @@ language for the long haul on major projects, whatever your bent.
 
 Perl's roots in text processing haven't been forgotten over the years.
 It still boasts some of the most powerful regular expressions to be
-found anyway, and its support for Unicode text is world-class.  It
+found anywhere, and its support for Unicode text is world-class.  It
 handles all kinds of structured text, too, through an extensive
 collection of extensions.  Those libraries, collected in the CPAN,
 provide ready-made solutions to an astounding array of problems.  When

-- 

  Andy Dougherty doughera@​lafayette.edu

[p5pRT]

From @rjbs

Resolved by c1264fa.

--
rjbs

[p5pRT]

From [Unknown Contact. See original ticket]

Resolved by c1264fa.

--
rjbs

[p5pRT]

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