search

Perl / perl5

🐪 The Perl programming language
https://dev.perl.org/perl5/
Other
1.91k stars 543 forks source link

central documentation of dual-lived modules hard to find #15673

Open p5pRT opened 7 years ago

p5pRT commented 7 years ago

Migrated from rt.perl.org#129918 (status was 'open')

Searchable as RT129918$

p5pRT commented 7 years ago

From @wchristian

This is a bug report for perl from walde.christian@​gmail.com\, generated with the help of perlbug 1.39 running under perl 5.14.2.

While trying to figure out the answers to questions on a dual-lived module i searched the perl documentation for clues and found that information on their different life cycles is spread all over the core documentation and that their apparent official name differs from the common use name.

What follows is a list of sightings of information on them i made.

- http​://perldoc.perl.org/perlhack.html#Patching-a-core-module - http​://perldoc.perl.org/perlhack.html#Updating-perldelta - http​://perldoc.perl.org/perlpolicy.html#MAINTENANCE-AND-SUPPORT - http​://perldoc.perl.org/perlglossary.html#dual-lived - http​://perldoc.perl.org/perlsource.html#Core-modules

I think this could be improved to make it easier for people coming in to find relevant information.

Changes i think would be beneficial would be a direct link from the glossary entry to the perlsource entry\, as well as adding "Core Module" to the mention of "dual-lived" and its permutations to indicate that dual-lived modules are a subgroup of the core modules.

Flags​:   category=docs   severity=low

Site configuration information for perl 5.14.2​:

Configured by Debian Project at Tue Sep 30 10​:36​:44 UTC 2014.

Summary of my perl5 (revision 5 version 14 subversion 2) configuration​:  
  Platform​:   osname=linux\, osvers=3.2.0-4-amd64\, archname=i486-linux-gnu-thread-multi-64int   uname='linux binet 3.2.0-4-amd64 #1 smp debian 3.2.60-1+deb7u3 i686 gnulinux '   config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -D_FORTIFY_SOURCE=2 -g -O2 -fstack-protector --param=ssp-buffer-size=4 -Wformat -Werror=format-security -Dldflags= -Wl\,-z\,relro -Dlddlflags=-shared -Wl\,-z\,relro -Dcccdlflags=-fPIC -Darchname=i486-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.14 -Darchlib=/usr/lib/perl/5.14 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.14.2 -Dsitearch=/usr/local/lib/perl/5.14.2 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Duse64bitint -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Ud_ualarm -Uusesfio -Uusenm -Ui_libutil -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dlibperl=libperl.so.5.14.2 -des'   hint=recommended\, useposix=true\, d_sigaction=define   useithreads=define\, usemultiplicity=define   useperlio=define\, d_sfio=undef\, uselargefiles=define\, usesocks=undef   use64bitint=define\, use64bitall=undef\, uselongdouble=undef   usemymalloc=n\, bincompat5005=undef   Compiler​:   cc='cc'\, ccflags ='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64'\,   optimize='-O2 -g'\,   cppflags='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include'   ccversion=''\, gccversion='4.7.2'\, gccosandvers=''   intsize=4\, longsize=4\, ptrsize=4\, doublesize=8\, byteorder=12345678   d_longlong=define\, longlongsize=8\, d_longdbl=define\, longdblsize=12   ivtype='long long'\, ivsize=8\, nvtype='double'\, nvsize=8\, Off_t='off_t'\, lseeksize=8   alignbytes=4\, prototype=define   Linker and Libraries​:   ld='cc'\, ldflags =' -fstack-protector -L/usr/local/lib'   libpth=/usr/local/lib /lib/i386-linux-gnu /lib/../lib /usr/lib/i386-linux-gnu /usr/lib/../lib /lib /usr/lib   libs=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt   perllibs=-ldl -lm -lpthread -lc -lcrypt   libc=\, so=so\, useshrplib=true\, libperl=libperl.so.5.14.2   gnulibc_version='2.13'   Dynamic Linking​:   dlsrc=dl_dlopen.xs\, dlext=so\, d_dlsymun=undef\, ccdlflags='-Wl\,-E'   cccdlflags='-fPIC'\, lddlflags='-shared -L/usr/local/lib -fstack-protector'

@​INC for perl 5.14.2​:   /etc/perl   /usr/local/lib/perl/5.14.2   /usr/local/share/perl/5.14.2   /usr/lib/perl5   /usr/share/perl5   /usr/lib/perl/5.14   /usr/share/perl/5.14   /usr/local/lib/site_perl   .

Environment for perl 5.14.2​:   HOME=/root   LANG (unset)   LANGUAGE (unset)   LD_LIBRARY_PATH (unset)   LOGDIR (unset)   PATH=/usr/local/sbin​:/usr/local/bin​:/usr/sbin​:/usr/bin​:/sbin​:/bin   PERL_BADLANG (unset)   SHELL=/bin/bash

p5pRT commented 7 years ago

From @jkeenan

On Wed\, 19 Oct 2016 15​:33​:18 GMT\, walde.christian@​gmail.com wrote​:

This is a bug report for perl from walde.christian@​gmail.com\, generated with the help of perlbug 1.39 running under perl 5.14.2.

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

While trying to figure out the answers to questions on a dual-lived module i searched the perl documentation for clues and found that information on their different life cycles is spread all over the core documentation and that their apparent official name differs from the common use name.

Can you be more specific as to "different life cycles" and differences between the "apparent official name" and "common use name" of certain dual-life modules? Which dual-life modules have this name clash?

What follows is a list of sightings of information on them i made.

- http​://perldoc.perl.org/perlhack.html#Patching-a-core-module - http​://perldoc.perl.org/perlhack.html#Updating-perldelta - http​://perldoc.perl.org/perlpolicy.html#MAINTENANCE-AND-SUPPORT - http​://perldoc.perl.org/perlglossary.html#dual-lived

The Glossary is maintained upstream on CPAN\, apparently as part of the 'perlfaq' distribution. So that's where suggestions for revisions specific to the Glossary have to be made.

- http​://perldoc.perl.org/perlsource.html#Core-modules

I ran this regex over blead​:

##### $ ack -i 'dual(\s|-)?li[vf]e' pod #####

I then excluded all finds found in pod/perlNNNNdelta.pod files. That left these finds for review​:

##### pod/perlpolicy.pod 318​:Updates to dual-life modules should consist of minimal patches to 320​:dual-life modules for which CPAN is canonical should be coordinated with 348​:New versions of dual-life modules should NOT be imported into maint. 534​:but\, with very few exceptions\, documentation isn't "dual-life" --

pod/perlsource.pod 37​:which can be released on cpan are known as "dual-life" modules. 59​:This directory is for dual-life modules where the blead source is 66​:This directory contains dual-life modules where the CPAN module is 74​:For some dual-life modules\, it has not yet been determined if the CPAN 92​:Tests for modules in F\ and the dual-life modules are in F\ 189​:information about a dual-life module.

pod/perlhack.pod 556​:Adding\, deprecating\, removing\, or upgrading core or dual-life modules 972​:suite. This is useful for modules that have a dual life on CPAN. #####

I think the discussion in 'perlsource' is good -- but of course I would think that\, because I'm the most recent committer to those paragraphs. ;-) The finds in 'perlpolicy' and 'perlhack' are more tangential. Can you provide specific suggestions for improvements?

Thank you very much. -- James E Keenan (jkeenan@​cpan.org)

p5pRT commented 7 years ago

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

p5pRT commented 7 years ago

From @jkeenan

On Sat\, 19 Nov 2016 23​:32​:27 GMT\, jkeenan wrote​:

On Wed\, 19 Oct 2016 15​:33​:18 GMT\, walde.christian@​gmail.com wrote​:

This is a bug report for perl from walde.christian@​gmail.com\, generated with the help of perlbug 1.39 running under perl 5.14.2.

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

While trying to figure out the answers to questions on a dual-lived module i searched the perl documentation for clues and found that information on their different life cycles is spread all over the core documentation and that their apparent official name differs from the common use name.

Can you be more specific as to "different life cycles" and differences between the "apparent official name" and "common use name" of certain dual-life modules? Which dual-life modules have this name clash?

What follows is a list of sightings of information on them i made.

- http​://perldoc.perl.org/perlhack.html#Patching-a-core-module - http​://perldoc.perl.org/perlhack.html#Updating-perldelta - http​://perldoc.perl.org/perlpolicy.html#MAINTENANCE-AND-SUPPORT - http​://perldoc.perl.org/perlglossary.html#dual-lived

The Glossary is maintained upstream on CPAN\, apparently as part of the 'perlfaq' distribution. So that's where suggestions for revisions specific to the Glossary have to be made.

- http​://perldoc.perl.org/perlsource.html#Core-modules

I ran this regex over blead​:

##### $ ack -i 'dual(\s|-)?li[vf]e' pod #####

I then excluded all finds found in pod/perlNNNNdelta.pod files. That left these finds for review​:

##### pod/perlpolicy.pod 318​:Updates to dual-life modules should consist of minimal patches to 320​:dual-life modules for which CPAN is canonical should be coordinated with 348​:New versions of dual-life modules should NOT be imported into maint. 534​:but\, with very few exceptions\, documentation isn't "dual-life" --

pod/perlsource.pod 37​:which can be released on cpan are known as "dual-life" modules. 59​:This directory is for dual-life modules where the blead source is 66​:This directory contains dual-life modules where the CPAN module is 74​:For some dual-life modules\, it has not yet been determined if the CPAN 92​:Tests for modules in F\ and the dual-life modules are in F\ 189​:information about a dual-life module.

pod/perlhack.pod 556​:Adding\, deprecating\, removing\, or upgrading core or dual-life modules 972​:suite. This is useful for modules that have a dual life on CPAN. #####

I think the discussion in 'perlsource' is good -- but of course I would think that\, because I'm the most recent committer to those paragraphs. ;-) The finds in 'perlpolicy' and 'perlhack' are more tangential. Can you provide specific suggestions for improvements?

Thank you very much.

Christian\, any thoughts on this?

Thank you very much. -- James E Keenan (jkeenan@​cpan.org)