perlipc-manpage doesn't describe perlipc command

[p5pRT]

Migrated from rt.perl.org#114936 (status was 'rejected')

Searchable as RT114936$

[p5pRT]

From perl-diddler@tlinx.org

Created by perl-diddler@tlinx.org

I just noticed this (again\, really)\, that perlipc isn't a command\, yet when I look up commands relevant to "something"\, it shows me me perlipc(1).

It certainly isn't about the perlipc command! ;-)

Likely\, since it is about a concept rather than a specific command\, it should be in section (5)\, but having it come up listed in the user-commands section(1)\, is definitely off.

In looking at the perl manpages\, it looks like perl is just ignoring manpage categories all-together. I don't why perl is not following the 25-year old standard\, but it sticks out like a wart -- python doesn't have this problem (not that I'm a great fan of python\, but at least it doesn't clutter up section one with a bunch of things that aren't commands).

There are over 200 perl "commands" documented\, that should be able to be entered on the command line​:

ls /usr/share/man/man1/perl*|wc   202 202 9639

In section 3\, mostly cpan functions are documented\, but oddly\, so is the 'pod' format -- which should be under section '5'...

Given the magnitude of the problem\, I doubt this can be fixed with a wave of the hand (but what do I know!?)... But I hope people would agree that it really should be fixed as we go forward... For reference\, the manpage sections are usually able to be found by doing a 'man man'\, and\, at least on my system\, do state the purpose of each section​:

  The table below shows the section numbers of the manual followed by the   types of pages they contain.

  0 Header files (usually found in /usr/include)   1 Executable programs or shell commands   2 System calls (functions provided by the kernel)   3 Library calls (functions within program libraries)   4 Special files (usually found in /dev)   5 File formats and conventions eg /etc/passwd   6 Games   7 Miscellaneous (including macro packages and conven-   tions)\, e.g. man(7)\, groff(7)   8 System administration commands (usually only for root)   9 Kernel routines [Non standard]

As it is\, I don't think it paints perl in a positive light.

Ideas? Something that can be fixed. Over time? Or necessary for backward compatibility with obscurity? ;^/

Perl Info

``` Flags: category=docs severity=low This perlbug was built using Perl 5.14.2 - Wed Feb 8 15:59:25 UTC 2012 It is being executed now by Perl 5.14.2 - Wed Feb 8 15:55:36 UTC 2012. Site configuration information for perl 5.14.2: Configured by abuild at Wed Feb 8 15:55:36 UTC 2012. Summary of my perl5 (revision 5 version 14 subversion 2) configuration: Platform: osname=linux, osvers=3.1.0-1.2-default, archname=x86_64-linux-thread-multi uname='linux build09 3.1.0-1.2-default #1 smp thu nov 3 14:45:45 utc 2011 (187dde0) x86_64 x86_64 x86_64 gnulinux ' config_args='-ds -e -Dprefix=/usr -Dvendorprefix=/usr -Dinstallusrbinperl -Dusethreads -Di_db -Di_dbm -Di_ndbm -Di_gdbm -Dd_dbm_open -Duseshrplib=true -Doptimize=-fmessage-length=0 -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -Wall -pipe -Accflags=-DPERL_USE_SAFE_PUTENV -Dotherlibdirs=/usr/lib/perl5/site_perl' hint=recommended, useposix=true, d_sigaction=define useithreads=define, usemultiplicity=define useperlio=define, d_sfio=undef, uselargefiles=define, usesocks=undef use64bitint=define, use64bitall=define, uselongdouble=undef usemymalloc=n, bincompat5005=undef Compiler: cc='cc', ccflags ='-D_REENTRANT -D_GNU_SOURCE -DPERL_USE_SAFE_PUTENV -fno-strict-aliasing -pipe -fstack-protector -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64', optimize='-fmessage-length=0 -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -Wall -pipe', cppflags='-D_REENTRANT -D_GNU_SOURCE -DPERL_USE_SAFE_PUTENV -fno-strict-aliasing -pipe -fstack-protector' ccversion='', gccversion='4.6.2', 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='double', nvsize=8, Off_t='off_t', lseeksize=8 alignbytes=8, prototype=define Linker and Libraries: ld='cc', ldflags =' -L/usr/local/lib64 -fstack-protector' libpth=/lib64 /usr/lib64 /usr/local/lib64 libs=-lm -ldl -lcrypt -lpthread perllibs=-lm -ldl -lcrypt -lpthread libc=/lib64/libc-2.14.1.so, so=so, useshrplib=true, libperl=libperl.so gnulibc_version='2.14.1' Dynamic Linking: dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E -Wl,-rpath,/usr/lib/perl5/5.14.2/x86_64-linux-thread-multi/CORE' cccdlflags='-fPIC', lddlflags='-shared -L/usr/local/lib64 -fstack-protector' Locally applied patches: @INC for perl 5.14.2: /usr/lib/perl5/site_perl/5.14.2/x86_64-linux-thread-multi /usr/lib/perl5/site_perl/5.14.2 /usr/lib/perl5/vendor_perl/5.14.2/x86_64-linux-thread-multi /usr/lib/perl5/vendor_perl/5.14.2 /usr/lib/perl5/5.14.2/x86_64-linux-thread-multi /usr/lib/perl5/5.14.2 /usr/lib/perl5/site_perl/5.14.2/x86_64-linux-thread-multi /usr/lib/perl5/site_perl/5.14.2 /usr/lib/perl5/site_perl . Environment for perl 5.14.2: HOME=/home/law LANG=en_US.UTF-8 LANGUAGE (unset) LC_COLLATE=C LC_CTYPE=en_US.UTF-8 LD_LIBRARY_PATH (unset) LOGDIR (unset) PATH=.:/sbin:/usr/local/sbin:/home/law/bin:/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/X11R6/bin:/usr/games:/opt/kde3/bin:/usr/lib/mit/bin:/usr/lib/mit/sbin:/usr/lib/qt3/bin:/usr/sbin:/etc/local/func_lib:/home/law/lib:/home/law/bin/lib PERL5OPT=-CSA PERL_BADLANG (unset) SHELL=/bin/bash ```

[p5pRT]

From @iabyn

On Sun\, Sep 16\, 2012 at 02​:36​:59PM -0700\, Linda Walsh wrote​:

I just noticed this (again\, really)\, that perlipc isn't a command\, yet when I look up commands relevant to "something"\, it shows me me perlipc(1).

It certainly isn't about the perlipc command! ;-)

Likely\, since it is about a concept rather than a specific command\, it should be in section (5)\, but having it come up listed in the user-commands section(1)\, is definitely off.

Historically\, there was the perl man page\, which went in section 1. Then it got very big\, so it got split into several files for convenience\, each with the 'perl' prefix. So logically they are still part of section 1. They certainly shouldn't be in section 5\, which describes file formats.

I would say let sleeping dogs lie.

-- My get-up-and-go just got up and went.

[p5pRT]

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

[p5pRT]

From @doy

On Tue\, Sep 18\, 2012 at 04​:28​:45PM +0100\, Dave Mitchell wrote​:

On Sun\, Sep 16\, 2012 at 02​:36​:59PM -0700\, Linda Walsh wrote​:

I just noticed this (again\, really)\, that perlipc isn't a command\, yet when I look up commands relevant to "something"\, it shows me me perlipc(1).

It certainly isn't about the perlipc command! ;-)

Likely\, since it is about a concept rather than a specific command\, it should be in section (5)\, but having it come up listed in the user-commands section(1)\, is definitely off.

Historically\, there was the perl man page\, which went in section 1. Then it got very big\, so it got split into several files for convenience\, each with the 'perl' prefix. So logically they are still part of section 1. They certainly shouldn't be in section 5\, which describes file formats.

I would say let sleeping dogs lie.

Note also that all of the zsh man pages (zshbuiltins\, zshoptions\, zshmisc\, etc) are all in section 1. This doesn't seem to be that odd of a convention.

-doy

[p5pRT]

From @tux

On Tue\, 18 Sep 2012 16​:28​:45 +0100\, Dave Mitchell \davem@​iabyn\.com wrote​:

On Sun\, Sep 16\, 2012 at 02​:36​:59PM -0700\, Linda Walsh wrote​:

I just noticed this (again\, really)\, that perlipc isn't a command\, yet when I look up commands relevant to "something"\, it shows me me perlipc(1).

It certainly isn't about the perlipc command! ;-)

Likely\, since it is about a concept rather than a specific command\, it should be in section (5)\, but having it come up listed in the user-commands section(1)\, is definitely off.

Historically\, there was the perl man page\, which went in section 1. Then it got very big\, so it got split into several files for convenience\, each with the 'perl' prefix. So logically they are still part of section 1. They certainly shouldn't be in section 5\, which describes file formats.

I also would expect the in section 1\, where command behaviour is described. Certainly not in section 5.

I would say let sleeping dogs lie.

I wholeheartedly agree

-- H.Merijn Brand http​://tux.nl Perl Monger http​://amsterdam.pm.org/ using perl5.00307 .. 5.14 porting perl5 on HP-UX\, AIX\, and openSUSE http​://mirrors.develooper.com/hpux/ http​://www.test-smoke.org/ http​://qa.perl.org http​://www.goldmark.org/jeff/stupid-disclaimers/

[p5pRT]

From perl-diddler@tlinx.org

H. Merijn Brand via RT wrote​:

On Tue\, 18 Sep 2012 16​:28​:45 +0100\, Dave Mitchell \davem@​iabyn\.com wrote​:

On Sun\, Sep 16\, 2012 at 02​:36​:59PM -0700\, Linda Walsh wrote​:

I just noticed this (again\, really)\, that perlipc isn't a command\, yet when I look up commands relevant to "something"\, it shows me me perlipc(1).

It certainly isn't about the perlipc command! ;-)

Likely\, since it is about a concept rather than a specific command\, it should be in section (5)\, but having it come up listed in the user-commands section(1)\, is definitely off.

Historically\, there was the perl man page\, which went in section 1. Then it got very big\, so it got split into several files for convenience\, each with the 'perl' prefix. So logically they are still part of section 1. They certainly shouldn't be in section 5\, which describes file formats.

Historically\, we didn't use computers\, so perl shouldn't be putting it's manpages anywhere.

If you really want to use history as a defense\, then it could be equally argued that perl should have no manpages in any section.

There are uncountable examples doing something the historical way is not only not appropriate\, but could get you killed. Try crossing a road without looking for oncoming vehicles. Traditionally\, You wouldn't have to look -- as it would be "right there"... high speed vehicles didn't exist. Or a better example.. that fits with perl a bit more.

There was a man\, lets call him Perlman\, who built a home in the country down the road a ways from a market. in a town who went to market. After a few years\, a crossroad was built across his road. Now the man had to look both directions and usually did as he drove through the intersection leaving it to others to accommodate him (after all\, he was there first).

Time passed and people decided a stop sign was needed at the intersection as traffic had gotten heavy enough that caution was warranted. Since the man was a fixture in the area -- people knew his quirks and worked around him -- while everyone else stopped\, they knew ol' Perlman wouldn't change.

A few years later\, the stop sign grew into a stop-light with a crosswalk and walk lights for pedestrians. Perlman still didn't adapt and you can imagine the rest...

Things change. Burying one's head in the sand and attempting to emulate a sleeping dog is likely to get you run over.

I also would expect the in section 1\, where command behaviour is described. Certainly not in section 5.

You would expect "the" in section 1? But articles come in the pre-amble section!

What command behavior is perlipc documenting?

Trying to use other projects as an excuse (like zsh)\, is pointless and a demonstration of faulty reasoning. zsh IS a command. It is a command line processor. All of it's functions are typeable on the command line.

Perl is a programming language -- not a shell.

perlipc doesn't describe the perl command. It describes how to do some programming task in the language. But it is not a description of how to run a command\, perl or otherwise.

That perl has GROWN beyond 1 manpage\, is wonderful -- it MEANS it can be ORGANIZED -- into sections... why do you think all the sections were created?

Unix at one point\, had only 1 manpage. It likely only had 1 section. But as it grew\, so did a need for classification to allow better organization and better ways of searching -- it can aid in people being able to find information.

Why would you want to break that?

If you are using the man command\, by default\, it will search all sections anyway\, but if I only wanted to limit my search to perl specific file formats (4)\, or concepts (5)\, or perl's builtin functions (3)\, I can't do that\, because perl is not organized. Everything starts out small and if successful\, grows\, that is almost never a good excuse for not adapting to its larger size.

I can't believe some people would think organization was a bad thing...but coming from the most vocal of the perl community on this topic\, I should have known better. Perl is meant to be chaotic\, unmanageable\, unreadable\, unmaintainable... etc.etc.etc.... There are those in the perl community who actually believe and want to promote that image. STOP IT! You do Perl and the community a disservice.

[p5pRT]

From chromatic@wgz.org

On Tuesday\, September 18\, 2012 01​:29​:51 PM Linda W wrote​:

I can't believe some people would think organization was a bad thing...but coming from the most vocal of the perl community on this topic\, I should have known better. Perl is meant to be chaotic\, unmanageable\, unreadable\, unmaintainable... etc.etc.etc.... There are those in the perl community who actually believe and want to promote that image. STOP IT! You do Perl and the community a disservice.

Characterizing people who disagree with you as working to destroy Perl is a very silly and unfair strawman argument.

Doubly so for people like Dave and Merijn who have done so many positive (and sadly thankless) things for Perl.

Please stop.

-- c

[p5pRT]

From perl-diddler@tlinx.org

chromatic via RT wrote​:

On Tuesday\, September 18\, 2012 01​:29​:51 PM Linda W wrote​:

I can't believe some people would think organization was a bad thing...but coming from the most vocal of the perl community on this topic\, I should have known better. Perl is meant to be chaotic\, unmanageable\, unreadable\, unmaintainable... etc.etc.etc.... There are those in the perl community who actually believe and want to promote that image. STOP IT! You do Perl and the community a disservice.

Characterizing people who disagree with you as working to destroy Perl is a very silly and unfair strawman argument.

Doubly so for people like Dave and Merijn who have done so many positive (and sadly thankless) things for Perl.

Please stop.

---

  I said people who want to keep it chaotic or unmaintainable\, etc\, were doing a disservice. You turn that into my saying they want to destroy perl?

  Could you describe the logic you used to come to that conclusion?

  Though I might add that those who are complicit in their support for obfuscation are likely doing it for similar reasons. Destroying perl? And here I thought it was about the secret plan to destroy the world\, pinky?

[p5pRT]

@iabyn - Status changed from 'open' to 'rejected'

[p5pRT]

From @rjbs

* Linda W \perl\-diddler@​tlinx\.org [2012-09-18T16​:29​:51]

Historically\, we didn't use computers\, so perl shouldn't be putting it's manpages anywhere.

Linda\, you have been removed from the perl5-porters mailing list. You seem determined to insult the other members of this list and to avoid\, at all costs\, a civil tone.

I am willing to suffer through ill treatment if it means I can get my job done\, but nobody else here signed up for that\, and I am tired of seeing other contributors needled.

I do not take this action lightly\, because I value the openness of this forum as a place where *everyone* can help improve the language and community. If\, in a few months\, you have come to understand the gulf between your behavior and what is acceptable here\, we can talk about lifting this ban.

I'm sorry it has come to this.

-- rjbs