Typo in "use" documentation

[p5pRT]

Migrated from rt.perl.org#116429 (status was 'resolved')

Searchable as RT116429$

[p5pRT]

From @jimav

This is a bug report for perl from james_avera@​yahoo.com,
generated with the help of perlbug 1.39 running under perl 5.14.2.

---

It looks like there's a typo in the pod for "use", which says
"The importation can be made conditional; see if."

("see if" ?)

I'm guessing this was meant to say "see below" or similar.

Actually, the sentence could just say the whole story, e.g.
"The importantion does not occur if LIST is an empty list."

---

---

Flags​:
  category=docs
  severity=low

---

Site configuration information for perl 5.14.2​:

Configured by Debian Project at Tue Nov 27 00​:34​:23 UTC 2012.

Summary of my perl5 (revision 5 version 14 subversion 2) configuration​:
 
  Platform​:
  osname=linux, osvers=2.6.42-32-generic, archname=x86_64-linux-gnu-thread-multi
  uname='linux allspice 2.6.42-32-generic #51-ubuntu smp wed sep 26 21​:33​:09 utc 2012 x86_64 x86_64 x86_64 gnulinux '
  config_args='-Dusethreads -Duselargefiles -Dccflags=-DDEBIAN -Dcccdlflags=-fPIC -Darchname=x86_64-linux-gnu -Dprefix=/usr -Dprivlib=/usr/share/perl/5.14 -Darchlib=/usr/lib/perl/5.14 -Dvendorprefix=/usr -Dvendorlib=/usr/share/perl5 -Dvendorarch=/usr/lib/perl5 -Dsiteprefix=/usr/local -Dsitelib=/usr/local/share/perl/5.14.2 -Dsitearch=/usr/local/lib/perl/5.14.2 -Dman1dir=/usr/share/man/man1 -Dman3dir=/usr/share/man/man3 -Dsiteman1dir=/usr/local/man/man1 -Dsiteman3dir=/usr/local/man/man3 -Duse64bitint -Dman1ext=1 -Dman3ext=3perl -Dpager=/usr/bin/sensible-pager -Uafs -Ud_csh -Ud_ualarm -Uusesfio -Uusenm -Ui_libutil -DDEBUGGING=-g -Doptimize=-O2 -Duseshrplib -Dlibperl=libperl.so.5.14.2 -des'
  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 -DDEBIAN -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64',
  optimize='-O2 -g',
  cppflags='-D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fno-strict-aliasing -pipe -fstack-protector -I/usr/local/include'
  ccversion='', gccversion='4.6.3', 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 =' -fstack-protector -L/usr/local/lib'
  libpth=/usr/local/lib /lib/x86_64-linux-gnu /lib/../lib /usr/lib/x86_64-linux-gnu /usr/lib/../lib /lib /usr/lib
  libs=-lgdbm -lgdbm_compat -ldb -ldl -lm -lpthread -lc -lcrypt
  perllibs=-ldl -lm -lpthread -lc -lcrypt
  libc=, so=so, useshrplib=true, libperl=libperl.so.5.14.2
  gnulibc_version='2.15'
  Dynamic Linking​:
  dlsrc=dl_dlopen.xs, dlext=so, d_dlsymun=undef, ccdlflags='-Wl,-E'
  cccdlflags='-fPIC', lddlflags='-shared -O2 -g -L/usr/local/lib -fstack-protector'

Locally applied patches​:
 

---

@​INC for perl 5.14.2​:
  /home/jima/lib/perl
  /home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi
  /home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi
  /home/jima/perl5/lib/perl5
  /etc/perl
  /usr/local/lib/perl/5.14.2
  /usr/local/share/perl/5.14.2
  /usr/lib/perl5
  /usr/share/perl5
  /usr/lib/perl/5.14
  /usr/share/perl/5.14
  /usr/local/lib/site_perl
  .

---

Environment for perl 5.14.2​:
  HOME=/home/jima
  LANG=en_US.UTF-8
  LANGUAGE=
  LD_LIBRARY_PATH=/home/jima/local/lib
  LOGDIR (unset)
  PATH=/home/jima/perl5/bin​:/home/jima/bin​:/home/jima/local/bin​:/home/jima/jima_tools/bin​:/usr/bin​:/bin​:/usr/sbin​:/sbin​:/usr/bin/X11​:/usr/local/bin​:/usr/local/sbin​:/usr/games​:.
  PERL5LIB=/home/jima/lib/perl​:/home/jima/perl5/lib/perl5/x86_64-linux-gnu-thread-multi​:/home/jima/perl5/lib/perl5
  PERL_BADLANG (unset)
  PERL_LOCAL_LIB_ROOT=/home/jima/perl5
  PERL_MB_OPT=--install_base /home/jima/perl5
  PERL_MM_OPT=INSTALL_BASE=/home/jima/perl5
  SHELL=/bin/bash

[p5pRT]

From @doy

On Wed, Jan 16, 2013 at 03​:20​:49PM -0800, Jim Avera wrote​:

It looks like there's a typo in the pod for "use", which says
"The importation can be made conditional; see if."

("see if" ?)

I'm guessing this was meant to say "see below" or similar.

Actually, the sentence could just say the whole story, e.g.
"The importantion does not occur if LIST is an empty list."

No, this is a reference to the 'if' module - see 'perldoc if'.

-doy

[p5pRT]

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

[p5pRT]

From @csjewell

It looks like there's a typo in the pod for "use", which says
"The importation can be made conditional; see if."

("see if" ?)

*Looks* being the operative word here. The 'if' the documentation is
referring to is the one described here​: https://metacpan.org/module/if

[p5pRT]

From [email protected]

On Thu, Jan 17, 2013 at 12​:24 AM, Jesse Luehrs <doy@​tozt.net> wrote​:

On Wed, Jan 16, 2013 at 03​:20​:49PM -0800, Jim Avera wrote​:

It looks like there's a typo in the pod for "use", which says
"The importation can be made conditional; see if."

("see if" ?)

I'm guessing this was meant to say "see below" or similar.

Actually, the sentence could just say the whole story, e.g.
"The importantion does not occur if LIST is an empty list."

No, this is a reference to the 'if' module - see 'perldoc if'.

  Yep​:

$ perldoc -uf use | grep 'made conditional'
The importation can be made conditional; see L<if>.
$

  If there's a problem here, it's that the pod formatting does not
distinguish links in any way, unless links are implemented (as seen on
http​://perldoc.perl.org/perlfunc.html#use-Module-VERSION-LIST).

  (I guess a C<< see "perldoc if" >> or, using the man page convention, C<<
see if(3) >> would be clearer?)

  But the pod is correct.

Eirik

[p5pRT]

From @mauke

On 17.01.2013 08​:43, Eirik Berg Hanssen wrote​:

$ perldoc -uf use | grep 'made conditional'
The importation can be made conditional; see L<if>.
$

If there's a problem here, it's that the pod formatting does not
distinguish links in any way, unless links are implemented (as seen on
http​://perldoc.perl.org/perlfunc.html#use-Module-VERSION-LIST).

(I guess a C<< see "perldoc if" >> or, using the man page convention,
C<< see if(3) >> would be clearer?)

But the pod is correct.

If we're going for a POD workaround, I'd suggest something like "see
L<the if module|if>" or "see L<C<perldoc if>|if>".

--
Lukas Mai <l.mai@​web.de>

[p5pRT]

From @tamias

On Thu, Jan 17, 2013 at 08​:59​:25AM +0100, Lukas Mai wrote​:

On 17.01.2013 08​:43, Eirik Berg Hanssen wrote​:

$ perldoc -uf use | grep 'made conditional'
The importation can be made conditional; see L<if>.
$

If there's a problem here, it's that the pod formatting does not
distinguish links in any way, unless links are implemented (as seen on
http​://perldoc.perl.org/perlfunc.html#use-Module-VERSION-LIST).

(I guess a C<< see "perldoc if" >> or, using the man page convention,
C<< see if(3) >> would be clearer?)

But the pod is correct.

If we're going for a POD workaround, I'd suggest something like "see
L<the if module|if>" or "see L<C<perldoc if>|if>".

"perldoc if" presupposes that the reader is reading the documentation with
perldoc. L<the if module|if> seems better to me. Or even​:

  The importation can be made conditional by using the L<if> module.

Ronald

[p5pRT]

From @rjbs

* Ronald J Kimball <rjk@​tamias.net> [2013-01-17T20​:40​:23]

"perldoc if" presupposes that the reader is reading the documentation with
perldoc. L<the if module|if> seems better to me. Or even​:

The importation can be made conditional by using the L<if> module.

Thanks, done as 08ed354.

--
rjbs

[p5pRT]

From @rjbs

Addressed by 116429.

[p5pRT]

From [Unknown Contact. See original ticket]

Addressed by 116429.

[p5pRT]

@rjbs - Status changed from 'open' to 'resolved'

[p5pRT]

From @jimav

*Looks* being the operative word here. The 'if' the documentation is
referring to is the
one described here​: https://metacpan.org/module/if

That isn't quite the same, is it?

("use if" not only doesn't import but it doesn't 'require' the module
either... so side-effects of compiling or executing the module's
outer-scope code do not occur. )

[p5pRT]

From @doy

On Wed, Jan 16, 2013 at 06​:26​:17PM -0800, Jim Avera wrote​:

*Looks* being the operative word here. The 'if' the documentation
is referring to is the
one described here​: https://metacpan.org/module/if

That isn't quite the same, is it?

("use if" not only doesn't import but it doesn't 'require' the
module either... so side-effects of compiling or executing the
module's outer-scope code do not occur. )

"use if" does both require the module and call import (and this is
indicated by both the code and the documentation). What makes you think
that it doesn't?

-doy

[p5pRT]

From @jimav

Well, 'cause the docs say so​: "use if ... has no effect unless
CONDITION is true", which I assume means no effect whatever.

My point was that the 'if' module allows conditional *loading* of
modules, which is not the same thing as whether importation occurs (i.e.
whether the import method is called).

[p5pRT]

From @doy

On Mon, Jan 21, 2013 at 12​:14​:35AM -0800, Jim Avera wrote​:

Well, 'cause the docs say so​: "use if ... has no effect unless
CONDITION is true", which I assume means no effect whatever.

My point was that the 'if' module allows conditional *loading* of
modules, which is not the same thing as whether importation occurs
(i.e. whether the import method is called).

The docs say that it has no effect unless CONDITION is true, but that
when CONDITION is true, it behaves identically to "use MODULE". This
includes calling import.

"use if 0, 'Foo'" does nothing at all, but "use if 1, 'Foo'" is
equivalent to "use Foo" (meaning, "BEGIN { require Foo; Foo->import }").

-doy