Bug#837718: perl-doc: "perldoc -f rmdir" recommends legacy File::Path::rmtree instead of File::Path::remove_tree

[Daniel Kahn Gillmor]

Package: perl-doc
Version: 5.22.2-3
Severity: minor

perldoc should be consistent about the interfaces it recommends.
File::Path suggests that remove_tree is preferred and rmtree is
legacy.  "perldoc -f rmdir" suggests that rmtree is preferred.

0 dkg at alice:~/tmp$ perldoc -f rmdir | cat
    rmdir FILENAME
    rmdir   Deletes the directory specified by FILENAME if that directory is
            empty. If it succeeds it returns true; otherwise it returns
            false and sets $! (errno). If FILENAME is omitted, uses $_.

            To remove a directory tree recursively ("rm -rf" on Unix) look
            at the "rmtree" function of the File::Path module.

0 dkg at alice:~/tmp$ perldoc File::Path | head -n31
NAME
    File::Path - Create or remove directory trees

VERSION
    This document describes version 2.09 of File::Path, released 2013-01-17.

SYNOPSIS
      use File::Path qw(make_path remove_tree);

      make_path('foo/bar/baz', '/zug/zwang');
      make_path('foo/bar/baz', '/zug/zwang', {
          verbose => 1,
          mode => 0711,
      });

      remove_tree('foo/bar/baz', '/zug/zwang');
      remove_tree('foo/bar/baz', '/zug/zwang', {
          verbose => 1,
          error  => \my $err_list,
      });

      # legacy (interface promoted before v2.00)
      mkpath('/foo/bar/baz');
      mkpath('/foo/bar/baz', 1, 0711);
      mkpath(['/foo/bar/baz', 'blurfl/quux'], 1, 0711);
      rmtree('foo/bar/baz', 1, 1);
      rmtree(['foo/bar/baz', 'blurfl/quux'], 1, 1);

      # legacy (interface promoted before v2.06)
      mkpath('foo/bar/baz', '/zug/zwang', { verbose => 1, mode => 0711 });
      rmtree('foo/bar/baz', '/zug/zwang', { verbose => 1, mode => 0711 });
0 dkg at alice:~/tmp$ 

-- System Information:
Debian Release: stretch/sid
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 4.7.0-rc7-amd64 (SMP w/4 CPU cores)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages perl-doc depends on:
ii  perl  5.22.2-3

perl-doc recommends no packages.

Versions of packages perl-doc suggests:
ii  groff-base            1.22.3-8
ii  man-db [man-browser]  2.7.5-1

-- no debconf information