headers
simon | 18 May 2006 14:35
Picon

perldoc -f qw (and others)

Hello,

Most Perl functions have some sort of entry available
for the user who learns how to type:

    perldoc -f func_name

So perldoc -f sort (or map or grep) all return pretty
useful information.

I'm a little concerned that for the newer user, the qw()
entry:

  perldoc -f qw

   qw/STRING/
     Generalized quotes.  See "Regexp Quote-Like Operators" in
     perlop.

is a little on the brutal side! (And the same is true for qx(), qq(), etc).

My thinking is this:

  * The user has to work out how to find the
    "Regexp Quote-Like Operators" section in perlop, and

  * Then has to be motivated enough to go and do it. Now while
    this is less trouble for people who are in an environment
    where "Regexp Quote-Like Operators" is a hyperlink to that
    section in the perlop page, (such as is the case on perldoc.perl.org
(Continue reading)

Permalink | Reply | 4 comments |
headers
brian d foy | 18 May 2006 23:07
Picon
Gravatar

Re: perldoc -f qw (and others)

In article <62829.210.15.216.58.1147955757.squirrel <at> 64.34.200.215>,
<simon <at> unisolve.com.au> wrote:

>   perldoc -f qw
> 
>    qw/STRING/
>      Generalized quotes.  See "Regexp Quote-Like Operators" in
>      perlop.
> 
> is a little on the brutal side! (And the same is true for qx(), qq(), etc).
> 
> My thinking is this:
> 
>   * The user has to work out how to find the
>     "Regexp Quote-Like Operators" section in perlop, and

>   1. What do you think about this?

I think it's not much work to look in perlop.

>   2. If you agree that "perldoc -f qw" should return some
>      actual content about the qw function,

I think it's fine. It's not a function, it's an operator.
Permalink | Reply | 3 comments |
headers
Flavio Poletti | 19 May 2006 00:25
Picon
Favicon
Gravatar

Re: perldoc -f qw (and others)

[snip]
>>   * The user has to work out how to find the
>>     "Regexp Quote-Like Operators" section in perlop, and
>
>>   1. What do you think about this?
>
> I think it's not much work to look in perlop.
>
>>   2. If you agree that "perldoc -f qw" should return some
>>      actual content about the qw function,
>
> I think it's fine. It's not a function, it's an operator.
>

Then this should go out of the "scope" of perldoc -f.

Either it should remain in, so it would be better to give immediate help
without hunting, or it should go out because it's an operator and not a
function. The hybrid way seems confusing to me.

Just my 2c,

   Flavio.
Permalink | Reply | 2 comments |
headers
Simon Taylor | 19 May 2006 02:02
Picon

Re: perldoc -f qw (and others)


> >>   * The user has to work out how to find the
> >>     "Regexp Quote-Like Operators" section in perlop, and
> >>
> >>   1. What do you think about this?
> >
> > I think it's not much work to look in perlop.
> >
> >>   2. If you agree that "perldoc -f qw" should return some
> >>      actual content about the qw function,
> >
> > I think it's fine. It's not a function, it's an operator.
>
> Then this should go out of the "scope" of perldoc -f.
>
> Either it should remain in, so it would be better to give immediate help
> without hunting, or it should go out because it's an operator and not a
> function. The hybrid way seems confusing to me.

I suppose I'm happy that qw() can be described as a function and as an 
operator, depending on the context of the documentation. 

(After all, it's listed in perlfunc under the heading "Functions for list 
data", and I don't see that thinking about it in this way hinders 
comprehension).

I'm really not that interested in experienced developers who *know* what qw() 
does, rather I'm much more concerned about the person who is new to Perl
who sees usage like,
(Continue reading)

Permalink | Reply | 0 comments |
headers
Smylers | 19 May 2006 09:32

Re: perldoc -f qw (and others)

Flavio Poletti writes:

> > >   2. If you agree that "perldoc -f qw" should return some actual
> > >   content about the qw function,
> >
> > I think it's fine. It's not a function, it's an operator.
> 
> Then this should go out of the "scope" of perldoc -f.

Yes.  It pretty much is.

> Either it should remain in, so it would be better to give immediate
> help without hunting, or it should go out because it's an operator and
> not a function.

But if it went, people who don't know that it's an operator would do
perldoc -f qw and get the 'No documentation' message, which doesn't help
them.  So it  makes sense to be more helpful than that by pointing out
that it's an operator and telling them where they _can_ read about it.

> The hybrid way seems confusing to me.

If we don't have cross references in the documentation then either
everything is only mentioned in one place (and you have to know exactly
where to look), or text is copied into lots of places, making the
documentation much bigger (and harder to maintain).

I don't see why somebody who's capable of programming Perl would have
trouble with the concept of cross references in documentation.
(Continue reading)

Permalink | Reply | 0 comments |
headers
Flavio Poletti | 19 May 2006 18:09
Picon
Favicon
Gravatar

Re: perldoc -f qw (and others)

After thinking about the recent discussion regarding the operators, I was
hit by a simple consideration: we (the human) are debating about something
that it (the computer) should manage.

On the one hand, the docs for the quote-like operators are in perlop. I
think that we all like this (the "they're operators!" party being somewhat
more enthusiast ;). On the other hand, I also think that we all like
"perldoc -f whatever" being *immediately* useful, without forcing to do
one more step (for the joy of the "laziness" party).

Both points of view are correct IMHO, what's probably wrong is thinking
they're opposite :) I'd like to propose a little patch to Pod/Perldoc.pm,
which looks for sensible documentation in perlop for the following
operators:

 m q qq qr qx qw s tr y

We're lucky that the description of these operators has (more or less) the
same structure that we find in perlfunc.

If you think this could be helpful, I'd be glad to propose the patch to
Mr. Sean M. Burke, who seems to be the responsible for Pod::Perldoc
maintenance. The patch seems to work on my system but - ehr - that's only
my system :)

Best regards,

   Flavio.

--- the following patch applies to Pod/Perldoc.m v. 3.14 ---
(Continue reading)

Permalink | Reply | 501 comments |
headers
brian d foy | 19 May 2006 20:29
Picon
Gravatar

Re: perldoc -f qw (and others)

In article
<22279.194.237.142.10.1148054960.squirrel <at> upmail.polettix.it>, Flavio
Poletti <flavio <at> polettix.it> wrote:

> If you think this could be helpful, I'd be glad to propose the patch to
> Mr. Sean M. Burke, who seems to be the responsible for Pod::Perldoc
> maintenance. The patch seems to work on my system but - ehr - that's only
> my system :)

This is a bad idea. Where is it going to end? What other patches will
we need to make the -f switch do something its not documented to do,
which is look up things in perlfunc?
Permalink | Reply | 501 comments |

Gmane