Re: Current Issues with perlipc.pod - should they be fixed?

On Fri, Dec 3, 2010 at 9:56 AM, Tom Christiansen <[email protected]> wrote:
>
>> after I posted my series of patches to perlipc.pod , I saw that
>> tchrist posted his version, which got accepted immediately. As a
>> downside to that, I'll have to restart my work. However, I noticed
>> that perlipc.pod still has many perceived issues.
>
> Having real issues is quite distinct from having perceived issues.
> In the case of perlipc, all are from the latter set.
>
>> Here is a list of things I noticed:
>
>> * =ABdefined($Config{sig_name}) =A0|| die "No sigs?"; =BB
>
>> Shouldn't it be using "or" instead of "||" or maybe an if?
>
> No, it should not. =A0That conflicts with my own way of speaking
> Perl, one which is self-consistent, perfectly safe, and followed
> by a good number of core developers, such as Rafael Manfredi.
>
> If you break my style, you break the document. =A0And upon my
> style, Damian has said:
>
> =A0 =A0And yes, they evince no lack of style.
>
> =A0 =A0Not my espoused style, but so many people forget that PBP was--at
> =A0 =A0its heart--a plea for code to be written in *any* consistent style=
,
> =A0 =A0consciously and rationally chosen to meet one's own needs. =A0No-o=
ne,
> =A0 =A0I'm sure, would every accuse you of failing to do that.
>
> If Damian does not condemn me, who are you to do so?
>
> VETO
>
>> *
>> <<<
>> foreach $name (split(" ", $Config{sig_name})) {
>> =A0 =A0 =A0 =A0 $signo{$name} =3D $i;
>> =A0 =A0 =A0 =A0 $signame[$i] =A0=3D $name;
>> =A0 =A0 =A0 =A0 $i++;
>> =A0 =A0 }
>> >>>
>
>> "foreach my $name" (Gotta practice what we preach). Furthermore, someone=
 said
>> we should recommend using a CPAN module for that instead.
>
> The tone and style of the Perl Documentation as set by Larry and myself i=
s
> to omit cluttering declarations from tiny snippets. =A0They otherwise
> distract from what the point of what is being illustrated. =A0The excepti=
on
> is if the point of the snippet is the declaration. =A0Putting in declarat=
ions
> for every two-bit line of code is madness. =A0Look at perlfunc!
>
> VETO
>
>> * unless (kill(0 =3D> $pid) || $!{EPERM}) {
>> =A0 =A0 =A0 =A0 warn "$pid looks dead";
>> =A0 =A0 }
>
>> unless and and ||? That's a bit confusing.
>
> I'm sorry you're confused. =A0Me, I find DeMorgan's
> Law confusing and therefore avoid its application
> wherever possible.
>
> =A0 =A0unless I killed it or else I got a permission error
> =A0 =A0 =A0 =A0it looks dead
>
> is perfectly clear.
>
> Let's try it your way:
>
> =A0 =A0if (!kill(0 =3D> $pid) && !$!{EPERM}) {
> =A0 =A0 =A0 =A0warn "$pid it looks dead";
> =A0 =A0}
>
> See what a mess you've made?
>
> Don't be ridiculous. =A0Making people compute boolean
> algebra in their heads through a surfeit of boolean
> ops is a recipe for confusion.
>
> VETO
>
>> *
>
>> <<<
>> my $ALARM_EXCEPTION =3D "alarm clock restart";
>> =A0 =A0 eval {
>> =A0 =A0 =A0 =A0 local $SIG{ALRM} =3D sub { die $ALARM_EXCEPTION };
>> =A0 =A0 =A0 =A0 alarm 10;
>> =A0 =A0 =A0 =A0 flock(FH, 2) =A0 =A0# blocking write lock
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 || die "cannot flock: $!=
";
>> =A0 =A0 =A0 =A0 alarm 0;
>> =A0 =A0 };
>> =A0 =A0 if ($@ && $@ !~ quotemeta($ALARM_EXCEPTION)) { die }
>> >>>
>
>> Non-lexical filehandle.
>
> Touch noogies. =A0This is a tiny example. =A0$Did $you $really
> $want $more $punctuation? @How %about $we *name $the &function,
> $too, Like::
>
> =A0 =A0my $throw_up_and_alarm_exception_using_die =3D sub {
> =A0 =A0 =A0 =A0die $ALARM_EXCEPTION;
> =A0 =A0};
>
> =A0 =A0Or better yet, we can name our function:
>
> =A0 =A0THROW_UP_AND_ALARM_EXCEPTION_USING_DIE {
> =A0 =A0 =A0 =A0die $ALARM_EXCEPTION;
> =A0 =A0};
>
> Except now you'll likely get yourself in a snit for it not having
> enough #$%^W#$$^ marks.
>
> VETO
>
>> *
>
>> <<<
>> # system return val is backwards, so && not ||
>> #
>> $ENV{PATH} .=3D ":/etc:/usr/etc";
>> =A0 =A0 if =A0( =A0 =A0 =A0system("mknod", =A0$path, "p")
>> =A0 =A0 =A0 =A0 =A0 =A0 && system("mkfifo", $path) )
>> =A0 =A0 {
>> =A0 =A0 =A0 =A0 die "mk{nod,fifo} $path failed";
>> =A0 =A0 }
>> >>>
>
>> We probably want local $ENV{PATH} here, and can't we expect the
>> mkfifo system call to work globally already?
>
> No, we most certainly cannot expect that! =A0I didn't put that code in
> there out of imagined problems. =A0I put it in there because if I didn't,
> it failed on some of systems I tested it on. =A0Why? =A0Because you canno=
t
> count on the user to have those in his path, that's why.
>
> VETO
>
> As for the local(), I feel that again falls in the needless
> category, although not so strongly as my other positions.
>
>
>> *
>> <<<
>> =A0chdir(); =A0 =A0# go home
>> =A0 =A0 my $FIFO =3D ".signature";
>
>> =A0 =A0 while (1) {
>> =A0 =A0 =A0 =A0 unless (-p $FIFO) {
>> =A0 =A0 =A0 =A0 =A0 =A0 unlink $FIFO; =A0 # discard any failure, will ca=
tch later
>> =A0 =A0 =A0 =A0 =A0 =A0 require POSIX; =A0# delayed loading of heavy mod=
ule
>> =A0 =A0 =A0 =A0 =A0 =A0 POSIX::mkfifo($FIFO, 0700)
>> =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0 || die "=
can't mkfifo $FIFO: $!";
>> =A0 =A0 =A0 =A0 }
>
>> =A0 =A0 =A0 =A0 # next line blocks till there's a reader
>> =A0 =A0 =A0 =A0 open (FIFO, "> $FIFO") =A0|| die "can't open $FIFO: $!";
>> =A0 =A0 =A0 =A0 print FIFO "John Smith (smith\@host.org)\n", `fortune -s=
`;
>> =A0 =A0 =A0 =A0 close(FIFO) =A0 =A0 =A0 =A0 =A0 =A0 || die "can't close =
$FIFO: $!";
>> =A0 =A0 =A0 =A0 sleep 2; =A0 =A0 =A0 =A0 =A0 =A0 =A0 =A0# to avoid dup s=
ignals
>> =A0 =A0 }
>> >>>
>
>> Bareword filehandle,
>
> Cope. =A0VETO.
>
>> and 2-args open
>
> THIS IS A MYTH!
>
> There is nothing whatsoever wrong with using two-argument
> open when you have complete control over the content of
> those strings and you are not setting the encoding in the
> open itself.
>
> VETO.
>
>> and || instead of or.
>
> Broken style. =A0VETO.
>
>> I won't mention
>> bareword filehandles again, but the exist in many other places.
>
> VETO
>
>> *
>> <<<
>> =A0 =A0 =A0 use FileHandle;
>> =A0 =A0 use IPC::Open2;
>> =A0 =A0 $pid =3D open2(*Reader, *Writer, "cat -un");
>> =A0 =A0 print Writer "stuff\n";
>> =A0 =A0 $got =3D <Reader>;
>> >>>
>
>> We need to make it use strict friendly.
>
> No, we do not. =A0Vide fricking supra.
>
>> *
>> <<<
>> =A0#!/usr/bin/perl -w
>> >>>
>
>> use warnings instead of "-w".
>
> ACK
>
>> *
>
>> <<<
>> my ($remote, $port, $iaddr, $paddr, $proto, $line);
>
>> =A0 =A0 $remote =A0=3D shift || "localhost";
>> =A0 =A0 $port =A0 =A0=3D shift || 2345; =A0# random port
>> =A0 =A0 if ($port =3D~ /\D/) { $port =3D getservbyname($port, "tcp") }
>> =A0 =A0 die "No port" unless $port;
>> =A0 =A0 $iaddr =A0 =3D inet_aton($remote) =A0 =A0 =A0 || die "no host: $=
remote";
>> >>>
>> we should declare the variables at first assignment instead of all in on=
e
>> place.
>
> What? =A0Three lines away is too far? =A0I think not!
>
> Anyway, that style is optimal for this construct:
>
> =A0 =A0my ( $remote, =A0 =A0 =A0 # asdfasdf
> =A0 =A0 =A0 =A0 $port, =A0 =A0 =A0 =A0 # asdfasdf
> =A0 =A0 =A0 =A0 $iaddr, =A0 =A0 =A0 =A0# asdfasdf
> =A0 =A0 =A0 =A0 $paddr, =A0 =A0 =A0 =A0# asdfasdf
> =A0 =A0 =A0 =A0 $proto, =A0 =A0 =A0 =A0# asdfasdf
> =A0 =A0 =A0 =A0 $line =A0 =A0 =A0 =A0 =A0# asdfasdf
> =A0 =A0);
>
> Are you saying my variable names are so obscure that it needs that
> sort of commenting at the point of declaration?
>
>> *
>> Shouldn't the example use IO::Socket and friends?
>
> No, do not Bowdlerize working code.
>
> *HOWEVER*
>
> A version or two of things using IO::Socket might reaonable go in there o=
n
> top of that--assuming you deem IO::Socket's documentation inadequate.
>
> But to strike away how to do this in the only place it exists in the
> documentation is inadvisable in the extreme, so much so that I'm sorely
> tempted to use stronger language.
>
> Fortunately, this time I shan't.
>
>> And here's a multithreaded version. =A0It's multithreaded in that
>> like most typical servers, it spawns (fork()s) a slave server to
>> handle the client request so that the master server can quickly
>> go back to service a new client.
>> >>>
>
>> The term "multithreaded" is misleading it. It is multi-processed - not
>> multithreaded, because it does not use threads.
>
> It was how we talked about things when that code was written. =A0I wrote
> plenty of perl4 client-server code, and that's what it was. =A0I believe
> the Camel and the Cookbook have notes clarifying the original usage.
> I can dig those out if need be.
>
>> *
>> <<<
>> Section 5 of CPAN's F<modules> file is devoted to "Networking, Device
>> Control (modems), and Interprocess Communication", and contains numerous
>> unbundled modules numerous networking modules, Chat and Expect operation=
s,
>> CGI programming, DCE, FTP, IPC, NNTP, Proxy, Ptty, RPC, SNMP, SMTP, Teln=
et,
>> Threads, and ToolTalk--to name just a few.
>> >>>
>
>> We should no longer mention that modules file.
>
> ACK.
>
>> Should I send patches to correct all these issues
>
> I am not going to tell you want to do. =A0But I will say
> that I do not believe 97% of your "corrections" have
> any merit whatsoever, and in fact suffer from demerits.
>
>> (because the Perl
>> documentation should represent the best practices)?
>
> I again direct you to Damian's quote. =A0Your statement
> is simple, seductive, and misleading to the point of
> being wrong.
>
>> And I hope that this time all my work will not be for
>> naught again.
>
> Work on things that need working on, and it won't be.
> Work on things that don't need working on, and it may.
>
> Nobody can tell you what to do, but that is my opinion,
> and I may be wrong.
>
> --tom

This thread is really depressing.  Personally, I like all of Shlomi's
suggestions.  I can't fathom why bareword global filehandles are still
pervasive in the perl docs.  But instead of the community getting to
discuss the merits of the changes and then have some kind of vote, one
maintainer with a big ego can just say, "VETO VETO VETO ... my docs
are already perfect!"  Is that how things work in the perl community?
What incentive would I or Shlomi or anyone else have to spend their
time to try to improve the docs if this is how things work.