documentation for the split command; webpage issues

[Anša Vernerová]

Hello,

I would like to report that the current documentation for the split command is erronerrous.
http://perldoc.perl.org/functions/split.html says:

--

In time-critical applications, it is worthwhile to avoid splitting into more fields than necessary. Thus, when assigning to a list, if LIMIT is omitted (or zero), then LIMIT is treated as though it were one larger than the number of variables in the list; for the following, LIMIT is implicitly 4:

    ($login, $passwd, $remainder) = split(/:/);

--


Calling the third argument $remainer is simply wrong - the remainder is the fourth argument, which is not assigned to anything. This must come from some edit of the older version of the documentation, which can be found e.g. at http://www.tu-chemnitz.de/docs/perldoc-html/functions/split.html :

--

The LIMIT parameter can be used to split a line partially

    ($login, $passwd, $remainder) = split(/:/, $_, 3);

When assigning to a list, if LIMIT is omitted, or zero, Perl supplies a LIMIT one larger than the number of variables in the list, to avoid unnecessary work. For the list above LIMIT would have been 4 by default. In time critical applications it behooves you not to split into more fields than you really need.

--

When I wanted to report this, I found it hard to find out where and how I should report. There is a contacts section at the bottom of the page, but neither Joe Allen's link nor the link to the project page seem to work - and reporting to the perl 5 porters list did not seem adequate. So I hope this is the right list to report such issues.

Anša

[Shlomi Fish]

Hi Anša,

On Tue, 19 Jun 2012 09:58:17 +0200
Anša Vernerová <ans...@gmail.com> wrote:

> Hello,
>
> I would like to report that the current documentation for the split command
> is erronerrous.
> http://perldoc.perl.org/functions/split.html says:
>

You can use the perlbug utility for that:

http://perldoc.perl.org/perlbug.html

> --
>
> When I wanted to report this, I found it hard to find out where and how I
> should report. There is a contacts section at the bottom of the page, but
> neither Joe Allen's link nor the link to the project page seem to work -
> and reporting to the perl 5 porters list did not seem adequate. So I hope
> this is the right list to report such issues.
>

Jon Allen's site appears to be down now (don't know why) but I was able to
access a snapshot on the Wayback Machine:

http://web.archive.org/web/20110724151052/http://perl.jonallen.info/projects/perldoc

This points to:

* https://github.com/jonallen/perldoc.perl.org

which is part of https://github.com/jonallen and there's an E-mail there. I
agree that Jon should restore his site to be online.

Regards,

Shlomi Fish

> Anša



--
-----------------------------------------------------------------
Shlomi Fish http://www.shlomifish.org/
UNIX Fortune Cookies - http://www.shlomifish.org/humour/fortunes/

Chuck Norris read the entire English Wikipedia in 24 hours. Twice.

Please reply to list if it's a mailing list post - http://shlom.in/reply .

[Leo Lapworth]

Hi,

On 19 June 2012 12:20, Shlomi Fish <shl...@shlomifish.org> wrote:

On Tue, 19 Jun 2012 09:58:17 +0200
Anša Vernerová <ans...@gmail.com> wrote:
> I would like to report that the current documentation for the split command
> is erronerrous.
> http://perldoc.perl.org/functions/split.html says:
>

You can use the perlbug utility for that:
http://perldoc.perl.org/perlbug.html

perlbug would work...

 

{snip}

 

This points to:

* https://github.com/jonallen/perldoc.perl.org

That's for changes to the perldoc.perl.org website - not the Perl documentations.

If it's a bug with the actual documentation you need to contact p5p who maintain it (this is mentioned at the bottom of every page on the http://perldoc.perl.org/ site.)

P5P mailing list is at: http://lists.perl.org/list/perl5-porters.html

I'll let them know.

Thanks for reporting it.

Leo

[Smylers]

Anša Vernerová writes:

> Hello, I would like to report that the current documentation for the
> split command is erronerrous.
> http://perldoc.perl.org/functions/split.html says:

Hi there. Thanks for spotting this, and taking the time to look into how
you can report it.

> This must come from some edit of the older version of the
> documentation, which can be found e.g. at
> http://www.tu-chemnitz.de/docs/perldoc-html/functions/split.html :

As it happens you can also get to older versions on the perldoc.perl.org
site -- see the 'Perl version' box near the top left, which lets you get
to pages like this: http://perldoc.perl.org/5.12.2/functions/split.html

However, an easier way to check precisely where this came from is to
look at the source repository, which is here:
http://perl5.git.perl.org/perl.git

Click on 'tree' to browse the files, guess that documentation is in the
'pod' subdirectory, see 'perlfunc.pod' in the list, and click 'blame',
which takes you to this page:
http://perl5.git.perl.org/perl.git/blame/HEAD:/pod/perlfunc.pod

Searching that for '$remainder' takes you to the line in question, then
clicking the commit ID at the start of that line goes to this commit:
http://perl5.git.perl.org/perl.git/commit/bd4675851936488a7b28a813c5b60248be3e733b?f=pod/perlfunc.pod

You can then click 'diff' to see exactly what was changed.

> When I wanted to report this, I found it hard to find out where and
> how I should report. There is a contacts section at the bottom of the
> page,

Those are contact details for the perldoc.perl.org site, which takes the
documentation that comes with Perl, formats it nicely, and makes it
available as a handy website. But JJ doesn't change the content, so that
needs to be reported upstream.

> reporting to the perl 5 porters list did not seem adequate.

The perlfunc documentation comes with perl, so the Perl 5 Porters are
indeed the people to report this to, preferably using the perlbug
command so that it gets tracked in their queue until resolved.

If you have a suggested correction you can submit a patch with your bug
report. (This would also get you in the credits of the next version of
Perl.) See perlhack for friendly instructions on how to do that:
http://perldoc.perl.org/perlhack.html

Cheers

Smylers
--
http://twitter.com/Smylers2