SPUG: Docs on "-l" wrong?

[Yitzchak Scott-Thoennes]

On Mon, Aug 25, 2003 at 12:05:59PM -0700, Tim Maher <tim at consultix-inc.com> wrote:
> 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) = ""'

Its somewhat confusing to say it chomps $/ when it really chomps
(implied: $/ off the end of) $_.

> 
> 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.

Would an extra sentence after the perl -lpe line that explains how it works
work for you?

>             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.

Would it work just to rewrite the switches as -ln -0 -e?  Or do you
think further explanation is needed?  If you can come up with a better
example not using find and -print0, that would be good.  Perhaps
something that prints the first sentence of each paragraph of input?