SPUG: Docs on "-l" wrong?

[Tim Maher]

SPUGsters,

Does anybody think the -l documentation from "perldoc perlrun"
is any good? This is a confusing topic in the first place, IMHO, and
this man page makes it moreso. See my comments below.  And I'd welcome
yours too.

-Tim
       -l[octnum]
            enables automatic line-ending processing.  It has two
            separate effects.  First, it automatically chomps $/
            (the input record separator) when used with -n or -p.
            Second, it assigns "$\" (the output record separator)
            to have the value of octnum so that any print state­
            ments will have that separator added back on.  If
            octnum is omitted, sets "$\" to the current value of
            $/.  For instance, to trim lines to 80 columns:

                perl -lpe 'substr($_, 80) = ""'

Tim's comment:
The whole point of this example, which unfortunately goes unstated,
is that when you truncate lines, you lose their attached newlines,
so without -l adding the "\n" back in automagically, the (long) lines
would not be separated by anything.  I'm left wondering, is this passage
meant to be an aid to developing the readers knowledge, or a test of it?
8-}  This is fine documentation written for the people who don't need it,
but not the others.

            Note that the assignment "$\ = $/" is done when the
            switch is processed, so the input record separator
            can be different than the output record separator if
            the -l switch is followed by a -0 switch:

                gnufind / -print0 | perl -ln0e 'print "found $_" if -p'

            This sets "$\" to newline and then sets $/ to the
            null character.

Tim says:
Instead of leaving it to the reader to disentangle the confusing
prose and wonder whether 0 is an argument to -n or something
else, I'd prefer an explicit statement that -l is donating the
terminal newlines to the solution (via $\), and -0 is setting $/
to the null character.

-Tim
*------------------------------------------------------------*
| Tim Maher (206) 781-UNIX  (866) DOC-PERL  (866) DOC-UNIX   |
| tim(AT)Consultix-Inc.Com  TeachMeUnix.Com  TeachMePerl.Com |
*+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-*
|  Watch for my Book: "Minimal Perl for Shell Programmers"   |
*------------------------------------------------------------*