Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
p5pRT opened this issue Oct 19, 2016 · 4 comments
Open

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

p5pRT opened this issue Oct 19, 2016 · 4 comments

Comments

@p5pRT
Copy link

p5pRT commented Oct 19, 2016

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

Searchable as RT129918$

@p5pRT
Copy link
Author

p5pRT commented Oct 19, 2016

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
Copy link
Author

p5pRT commented Nov 19, 2016

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<ext/> and the dual-life modules are in F<t/>
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
Copy link
Author

p5pRT commented Nov 19, 2016

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

@p5pRT
Copy link
Author

p5pRT commented Dec 29, 2016

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<ext/> and the dual-life modules are in F<t/>
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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants