| From: | CARNIL [...] cpan.org |
| Subject: | libperl-critic-perl: Documentation::RequirePodLinksIncludeText is obsolete |
Hi
This bug has been forwarded from http://bugs.debian.org/696912
Package: libperl-critic-perl
Version: 1.117-2
Severity: wishlist
(I know this should to go RT, but I'm out of brain for the day. I'll
forward it to RT probably tomorrow if someone doesn't beat me to it.)
Perl::Critic::Policy::Documentation::RequirePodLinksIncludeText says:
This Policy requires your POD links to contain text to override your POD
translator's default link text, where this is possible. Failure to
provide your own text leaves you at the mercy of the POD translator,
which may display something like "L<Foo>" as "the Foo manpage".
That display of L<Foo> as "the Foo manpage" was something that was only
done in Pod::Man and Pod::Text (and their predecessors). I fixed that
bug in November of 2001.
It's possible that some other formatters picked up that bad habit from
pod2man and pod2text, but I'm not aware of any, and this was discussed
quite a bit on pod-people@perl.org. Plus, perlpodspec specifically says:
* In case of L<...> codes with no "text|" part in them, older
formatters have exhibited great variation in actually displaying
the link or cross reference. For example, L<crontab(5)> would
render as "the crontab(5) manpage", or "in the crontab(5) manpage"
or just "crontab(5)".
Pod processors must now treat "text|"-less links as follows:
L<name> => L<name|name>
L</section> => L<"section"|/section>
L<name/section> => L<"section" in name|name/section>
and has since the beginning of that document years ago, so at this point
any formatter that does something else is just buggy and should be fixed.
It's time to kill this policy and let everyone who has been tediously
writing L<Pod::Parser|Pod::Parser> for the past 11 years unnecessarily
just write L<Pod::Parser> and be happy.
-- System Information:
Debian Release: wheezy/sid
APT prefers testing
APT policy: (990, 'testing'), (500, 'unstable'), (1, 'experimental')
Architecture: i386 (i686)
Kernel: Linux 3.2.0-3-686-pae (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
Versions of packages libperl-critic-perl depends on:
ii libb-keywords-perl 1.12-1
ii libconfig-tiny-perl 2.14-1
ii libemail-address-perl 1.895-1
ii libexception-class-perl 1.32-1
ii libfile-homedir-perl 0.99-1
pn libfile-spec-perl <none>
ii libfile-which-perl 1.09-1
ii libio-string-perl 1.08-2
ii liblist-moreutils-perl 0.33-1+b1
ii libpod-spell-perl 1.01-2
ii libppi-perl 1.215-1
ii libppix-regexp-perl 0.028-1
ii libppix-utilities-perl 1.001000-1
ii libreadonly-perl 1.03-4
ii libreadonly-xs-perl 1.04-2+b3
ii libstring-format-perl 1.16-1
ii libtask-weaken-perl 1.03-1
ii perl 5.14.2-16
ii perl-modules [libmodule-pluggable-perl] 5.14.2-16
ii perltidy 20101217-1
libperl-critic-perl recommends no packages.
libperl-critic-perl suggests no packages.
-- no debconf information
Thanks in advance,
Salvatore Bonaccorso, Debian Perl Group