search

Perl / perl5

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

The perlmodlib(1) manpage seems overly long + slightly garbled #13970

Open p5pRT opened 10 years ago

p5pRT commented 10 years ago

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

Searchable as RT122231$

p5pRT commented 10 years ago

From naesten@gmail.com

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

I've noticed three problems with the permodlib(1) manpage​:

1) It seems overly long\, and without a unifying theme.

  I mean\, first it's got some lists of module names\, then an   unexpected overview + mirror list of CPAN\, then some guidelines for   creating\, using\, and abusing modules in general.

  In fact\, it is so long that when I look at it on perldoc.org\, the   backgrounds start to "run out" soon after the section   \<http​://perldoc.perl.org/perlmodlib.html#Asia>. (I have no idea why   this may be; I'm using 32-bit Firefox 24.6 on Windows as my browser.   Yes\, I do my programming via SSH + remote X to my Debian system.)

  Wouldn't it be better to split this into three pages?

2) The list of "Pragmatic Modules" also includes the names of many   (all?) "perl*" manpages for some reason. At first I thought a   heading had gotten lost somehow\, but then I noticed that there are   more Pragmatic Modules after the "perl*" names\, so now I'm guessing   the story is something like "we rearranged the documentation sources   so that the perl* pages are now mixed in with the docs for the   pragmatic modules".

Flags​:   category=docs   severity=medium

Site configuration information for perl 5.18.2​:

Configured by Debian Project at Sat Mar 1 14​:00​:24 UTC 2014.

Summary of my perl5 (revision 5 version 18 subversion 2) configuration​:  
  Platform​:   osname=linux\, osvers=3.2.0-4-amd64\, archname=i486-linux-gnu-thread-multi-64int   uname='linux babin 3.2.0-4-amd64 #1 smp debian 3.2.54-2 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.18 -Darchlib=/usr/lib/perl/5.18 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.18.2 -Dsitearch=/usr/local/lib/perl/5.18.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 -Uversiononly -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dlibperl=libperl.so.5.18.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.8.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.18.2   gnulibc_version='2.17'   Dynamic Linking​:   dlsrc=dl_dlopen.xs\, dlext=so\, d_dlsymun=undef\, ccdlflags='-Wl\,-E'   cccdlflags='-fPIC'\, lddlflags='-shared -L/usr/local/lib -fstack-protector'

Locally applied patches​:   DEBPKG​:debian/cpan_definstalldirs - Provide a sensible INSTALLDIRS default for modules installed from CPAN.   DEBPKG​:debian/db_file_ver - http​://bugs.debian.org/340047 Remove overly restrictive DB_File version check.   DEBPKG​:debian/doc_info - Replace generic man(1) instructions with Debian-specific information.   DEBPKG​:debian/enc2xs_inc - http​://bugs.debian.org/290336 Tweak enc2xs to follow symlinks and ignore missing @​INC directories.   DEBPKG​:debian/errno_ver - http​://bugs.debian.org/343351 Remove Errno version check due to upgrade problems with long-running processes.   DEBPKG​:debian/libperl_embed_doc - http​://bugs.debian.org/186778 Note that libperl-dev package is required for embedded linking   DEBPKG​:fixes/respect_umask - Respect umask during installation   DEBPKG​:debian/writable_site_dirs - Set umask approproately for site install directories   DEBPKG​:debian/extutils_set_libperl_path - EU​:MM​: Set location of libperl.a to /usr/lib   DEBPKG​:debian/no_packlist_perllocal - Don't install .packlist or perllocal.pod for perl or vendor   DEBPKG​:debian/prefix_changes - Fiddle with *PREFIX and variables written to the makefile   DEBPKG​:debian/fakeroot - Postpone LD_LIBRARY_PATH evaluation to the binary targets.   DEBPKG​:debian/instmodsh_doc - Debian policy doesn't install .packlist files for core or vendor.   DEBPKG​:debian/ld_run_path - Remove standard libs from LD_RUN_PATH as per Debian policy.   DEBPKG​:debian/libnet_config_path - Set location of libnet.cfg to /etc/perl/Net as /usr may not be writable.   DEBPKG​:debian/mod_paths - Tweak @​INC ordering for Debian   DEBPKG​:debian/module_build_man_extensions - http​://bugs.debian.org/479460 Adjust Module​::Build manual page extensions for the Debian Perl policy   DEBPKG​:debian/prune_libs - http​://bugs.debian.org/128355 Prune the list of libraries wanted to what we actually need.   DEBPKG​:fixes/net_smtp_docs - [rt.cpan.org #36038] http​://bugs.debian.org/100195 Document the Net​::SMTP 'Port' option   DEBPKG​:debian/perlivp - http​://bugs.debian.org/510895 Make perlivp skip include directories in /usr/local   DEBPKG​:debian/cpanplus_definstalldirs - http​://bugs.debian.org/533707 Configure CPANPLUS to use the site directories by default.   DEBPKG​:debian/cpanplus_config_path - Save local versions of CPANPLUS​::Config​::System into /etc/perl.   DEBPKG​:debian/deprecate-with-apt - http​://bugs.debian.org/702096 Point users to Debian packages of deprecated core modules   DEBPKG​:debian/squelch-locale-warnings - http​://bugs.debian.org/508764 Squelch locale warnings in Debian package maintainer scripts   DEBPKG​:debian/skip-upstream-git-tests - Skip tests specific to the upstream Git repository   DEBPKG​:debian/patchlevel - http​://bugs.debian.org/567489 List packaged patches for 5.18.2-2+b1 in patchlevel.h   DEBPKG​:debian/skip-kfreebsd-crash - http​://bugs.debian.org/628493 [perl #96272] Skip a crashing test case in t/op/threads.t on GNU/kFreeBSD   DEBPKG​:fixes/document_makemaker_ccflags - http​://bugs.debian.org/628522 [rt.cpan.org #68613] Document that CCFLAGS should include $Config{ccflags}   DEBPKG​:debian/find_html2text - http​://bugs.debian.org/640479 Configure CPAN​::Distribution with correct name of html2text   DEBPKG​:debian/hurd_test_skip_stack - http​://bugs.debian.org/650175 Disable failing GNU/Hurd tests dist/threads/t/stack.t   DEBPKG​:fixes/manpage_name_Test-Harness - http​://bugs.debian.org/650451 [rt.cpan.org #73399] cpan/Test-Harness​: add NAME headings in modules with POD   DEBPKG​:debian/makemaker-pasthru - http​://bugs.debian.org/660195 [rt.cpan.org #28632] Make EU​::MM pass LD through to recursive Makefile.PL invocations   DEBPKG​:debian/perl5db-x-terminal-emulator.patch - http​://bugs.debian.org/668490 Invoke x-terminal-emulator rather than xterm in perl5db.pl   DEBPKG​:debian/cpan-missing-site-dirs - http​://bugs.debian.org/688842 Fix CPAN​::FirstTime defaults with nonexisting site dirs if a parent is writable   DEBPKG​:fixes/memoize_storable_nstore - [rt.cpan.org #77790] http​://bugs.debian.org/587650 Memoize​::Storable​: respect 'nstore' option not respected   DEBPKG​:fixes/net_ftp_failed_command - [rt.cpan.org #37700] http​://bugs.debian.org/491062 Net​::FTP​: cope gracefully with a failed command   DEBPKG​:fixes/perlbug-patchlist - [3541c11] http​://bugs.debian.org/710842 [perl #118433] Make perlbug look up the list of local patches at run time   DEBPKG​:fixes/module_metadata_security_doc - [68cdd4b] CVE-2013-1437 documentation fix   DEBPKG​:fixes/module_metadata_taint_fix - [bff978f] http​://bugs.debian.org/722210 [rt.cpan.org #88576] untaint version\, if needed\, in Module​::Metadata   DEBPKG​:fixes/IPC-SysV-spelling - http​://bugs.debian.org/730558 [rt.cpan.org #86736] Fix spelling of IPC_CREAT in IPC-SysV documentation

@​INC for perl 5.18.2​:   /etc/perl   /usr/local/lib/perl/5.18.2   /usr/local/share/perl/5.18.2   /usr/lib/perl5   /usr/share/perl5   /usr/lib/perl/5.18   /usr/share/perl/5.18   /usr/local/lib/site_perl   .

Environment for perl 5.18.2​:   HOME=/home/naesten   LANG=en_US.UTF-8   LANGUAGE (unset)   LC_COLLATE=C   LD_LIBRARY_PATH (unset)   LOGDIR (unset)   PATH=/home/naesten/hacking/pydoctor/bin​:/home/naesten/hacking/Nevow/bin​:/home/naesten/hacking/Twisted/bin​:/home/naesten/.cabal/bin​:/home/naesten/bin​:/usr/local/sbin​:/usr/local/bin​:/usr/sbin​:/usr/bin​:/sbin​:/bin​:/usr/games   PERL_BADLANG (unset)   SHELL=/usr/bin/zsh

p5pRT commented 10 years ago

From @jkeenan

On Fri Jul 04 20​:28​:13 2014\, naesten@​gmail.com wrote​:

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

----------------------------------------------------------------- I've noticed three problems with the permodlib(1) manpage​:

1) It seems overly long\, and without a unifying theme.

I mean\, first it's got some lists of module names\, then an unexpected overview + mirror list of CPAN\, then some guidelines for creating\, using\, and abusing modules in general.

In fact\, it is so long that when I look at it on perldoc.org\, the backgrounds start to "run out" soon after the section \<http​://perldoc.perl.org/perlmodlib.html#Asia>. (I have no idea why this may be; I'm using 32-bit Firefox 24.6 on Windows as my browser. Yes\, I do my programming via SSH + remote X to my Debian system.)

Wouldn't it be better to split this into three pages?

The disjointed nature of 'perlmodlib' stems in part from the fact that it is an auto-generated document. Humans write the descriptive material but the lists of pragmata and standard modules are inserted by pod/perlmodlib.PL upon installation. I think it is useful to have a list of the libraries associated with a particular version of the core distribution and having this list mechanically generated no doubt saves release managers lots of time.

So far so good. But when it comes to a list of CPAN mirrors pod/perlmodlib.PL resorts to a hard-coded list mirrors. Since the Perl 5 Porters have no control whatsoever over mirrors\, this information is almost certainly out-of-date as of the time it is released. And in this day and age the average Perl user rarely needs to think about which mirror she is getting her CPAN libraries from. IMO it would be better to provide the user with a one-line command that could query the current state of CPAN mirrors in much the same way that CPAN.pm\, CPANPLUS and App​::cpanminus do. Toolchain Gang​: any suggestions?

I did learn something new from this document\, however! I never knew that 'perldoc perllocal' would give me a list of the non-core libraries I have installed on a particular machine.

Lastly\, with respect to the section called "Modules​: Creation\, Use\, and Abuse"​: Over the years many similar documents have been written; we probably have some of them in the core distribution itself. However\, anything "borrowed directly from Tim Bunce" is bound to be interesting\, so I'm going to give this section a more careful reading.

2) The list of "Pragmatic Modules" also includes the names of many (all?) "perl*" manpages for some reason. At first I thought a heading had gotten lost somehow\, but then I noticed that there are more Pragmatic Modules after the "perl*" names\, so now I'm guessing the story is something like "we rearranged the documentation sources so that the perl* pages are now mixed in with the docs for the pragmatic modules".

This appears to have been addressed in Perl 5.20.

Now\, as to what action should be taken ...

Based on past experience\, I can safely say that the question of how to revise a man page which has been part of the Perl 5 core distribution for a long time is one on which​:

* *Many* people will have an opinion.

* Forming a consensus on revisions will take time.

* Once a consensus has formed\, some *particular* person will have to take on the task of making revisions.

* *Many* people will have an opinion on the proposed revisions.

* Rinse. Repeat.

In principle (or\, at least\, my opinion)\, this discussion should take place first on the Perl 5 Porters mailing list and only move into the bug tracking system when an actual draft of revisions is ready for comment. But since this has been filed as an RT ticket and since all RT tickets are copied to the P5P list/newsgroup\, I recognize that the discussion will be recorded in RT in any case. In RT I am going to change the Status of this ticket to Stalled (which\, pending reaching consensus\, is where the issue lies). That should not prevent people from commenting on it on the list.

Thank you very much. Jim Keenan

p5pRT commented 10 years ago

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

p5pRT commented 10 years ago

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

p5pRT commented 10 years ago

From @karenetheridge

On Sun\, Jul 06\, 2014 at 06​:57​:03AM -0700\, James E Keenan via RT wrote​:

I did learn something new from this document\, however! I never knew that 'perldoc perllocal' would give me a list of the non-core libraries I have installed on a particular machine.

It doesn't -- iirc\, only modules installed via ExtUtils​::MakeMaker are listed. Since this list is incomplete\, we should stop mentioning it\, lest some tools come to rely on this.

p5pRT commented 10 years ago

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