Front page | perl.perl5.porters |
Postings from February 2000
REPORT: orphaned and mutilated pods
From:
Tom Christiansen
Date:
February 8, 2000 05:35
Subject:
REPORT: orphaned and mutilated pods
Message ID:
19767.950016909@chthon
The following pods are orphaned in the pod/ directory, by which I
mean that they are not mentioned in the main perl.pod file:
Win32
perlfilter
perllexwarn
perlunicode
Not all are completely dead, though
% cd /usr/local/src/perl5.5.650/pod
% egrep "L<perl(filter|lexwarn|unicode)>" *.pod
perldelta.pod:in the current lexical scope. See L<perlunicode>, L<utf8> and L<byte> for
perldelta.pod:level using the C<use warnings> pragma. See L<warnings> and L<perllexwarn>
perldelta.pod:See L<perllexwarn>.
perlrun.pod:See L<perllexwarn>.
perlrun.pod:See L<perllexwarn>.
There's also this, which of course isn't linked:
perldelta.pod:=item perlfilter.pod
The following symlinks are no longer there:
% cd /usr/local/src/perl5.005_63/pod
% find . -type l -ls
180485 0 lrwxr-xr-x 1 root users 15 Jan 15 16:44 ./perlamiga.pod -> ../README.amiga
180486 0 lrwxr-xr-x 1 root users 16 Jan 15 16:44 ./perlcygwin.pod -> ../README.cygwin
180487 0 lrwxr-xr-x 1 root users 13 Jan 15 16:44 ./perldos.pod -> ../README.dos
180488 0 lrwxr-xr-x 1 root users 14 Jan 15 16:44 ./perlhpux.pod -> ../README.hpux
180489 0 lrwxr-xr-x 1 root users 13 Jan 15 16:44 ./perlos2.pod -> ../README.os2
180490 0 lrwxr-xr-x 1 root users 15 Jan 15 16:44 ./perlos390.pod -> ../README.os390
180491 0 lrwxr-xr-x 1 root users 15 Jan 15 16:44 ./perlwin32.pod -> ../README.win32
Note, however, the difference between Win32.pod and perlwin32.pod:
% ls -Ll *in32*pod
-r--r--r-- 1 tchrist users 9463 Nov 1 09:51 Win32.pod
-r--r--r-- 1 tchrist users 31057 Dec 9 04:08 perlwin32.pod
Now, these (or some of these) are indeed mentioned, at once point:
% cd /usr/local/src/perl5.5.650/pod
% grep README perlport.pod
=item The Cygwin environment for Win32; L<README.cygwin>,
=item L<README.vms>, L<perlvms.pod>
Perl on VOS is discussed in F<README.vos> in the perl distribution.
=item L<README.vos>
=item L<README.os390>, L<README.posix-bc>, L<README.vmesa>
=item Amiga, L<README.amiga>
=item Atari, L<README.mint> and Guido Flohr's web page
=item Be OS, L<README.beos>
=item HP 300 MPE/iX, L<README.mpeix> and Mark Bixby's web page
=item Plan 9, L<README.plan9>
in doubt, consult the platform-specific README files in the Perl
However, those are *NOT* valid L<> fields! How do you expect
anything to find those? They don't get pod2manned and intalled
anywhere. They aren't in a database of links. We have the
same problem with this:
perldelta.pod:See L<INSTALL> and L<README.Y2K>.
I did a little check,
% cd /usr/local/src/perl5.5.650/pod
% perl -lne 'while (m#(L<(.*?)(/[^>]+)?>)#g) { print "$ARGV: $1" unless -e "$2.pod"} ' *.pod
And hten some hand edits, and came of with the following problems.
Many can be classed into the following groups:
1) Links to real programs that are not themselves installed
with manpages (eg: dprofpp, xsubpp, perlcc).
2) Links to random files that are NOT installed as manpages and
are thus useless (eg: INSTALL, README.*>
3) Links to things we don't have anymore (eg: perlvms, perlwin32)
4) Links to things that should not be in L<> because the
translators should already be inferring linkage, or else
the translators are broken. (eg:
L<printf(3)>
and L<http://www.cs.utah.edu/~beazley/SWIG>).
There are many other bizarre cases down here that caught my eye but
which don't fit into other categories, including
Is MakeMaker a L<>inkable program/module/doc/entity?
Can you have C<> within L<>?
What's the diff between L<"pack"> and L<"pack>?
What does L<foo.pod> mean compared with L<foo>?
Enjoy. As it were.
--tom
perl.pod: L<xsubpp>
perl5004delta.pod: L<"$^M">
perl5004delta.pod: L<MakeMaker>
perl5005delta.pod: L<INSTALL>
perl5005delta.pod: L<INSTALL>
perl5005delta.pod: L<C<our> is now a reserved word>
perl5005delta.pod: L<README.threads>
perl5005delta.pod: L<README.beos>
perl5005delta.pod: L<README.dos>
perl5005delta.pod: L<README.mint>
perl5005delta.pod: L<README.mpeix>
perl5005delta.pod: L<README.os390>
perl5005delta.pod: L<README.vos>
perl5005delta.pod: L<perlwin32>
perl5005delta.pod: L<README.vms>
perlcompile.pod: L<perlcc>
perlcompile.pod: L<perlcc>
perldelta.pod: L<INSTALL>
perldelta.pod: L<README.Y2K>
perldelta.pod: L<dprofpp>
perldelta.pod: L<perlvms>
perldelta.pod: L<perlvms>
perldiag.pod: L<perlvms>
perldiag.pod: L<perlvms/"exec LIST">
perldiag.pod: L<perlvms>
perlfaq3.pod: L<xsubpp>
perlfaq8.pod: L<perlvms>
perlfaq8.pod: L<perlplan9>
perlfunc.pod: L<perlcc>
perlfunc.pod: L<sprintf(3)>
perlfunc.pod: L<printf(3)>
perlfunc.pod: L</pack>
perlfunc.pod: L<"pack">
perlguts.pod: L<perlbug>
perlipc.pod: L<tty(4)>
perllocale.pod: L<setlocale(3)>
perllocale.pod: L<setlocale(3)>
perllocale.pod: L<setlocale(3)>
perllocale.pod: L<POSIX (3)/localeconv>
perllocale.pod: L<POSIX (3)/isalnum>
perllocale.pod: L<POSIX (3)/isalpha>
perllocale.pod: L<POSIX (3)/isdigit>
perllocale.pod: L<POSIX (3)/isgraph>
perllocale.pod: L<POSIX (3)/islower>
perllocale.pod: L<POSIX (3)/isprint>
perllocale.pod: L<POSIX (3)/ispunct>
perllocale.pod: L<POSIX (3)/isspace>
perllocale.pod: L<POSIX (3)/isupper>
perllocale.pod: L<POSIX (3)/isxdigit>
perllocale.pod: L<POSIX (3)/localeconv>
perllocale.pod: L<POSIX (3)/setlocale>
perllocale.pod: L<POSIX (3)/strcoll>
perllocale.pod: L<POSIX (3)/strftime>
perllocale.pod: L<POSIX (3)/strtod>
perllocale.pod: L<POSIX (3)/strxfrm>
perlmod.pod: L<perlcc>
perlop.pod: L<"qr//">
perlport.pod: L<perlwin32>
perlport.pod: L<README.cygwin>
perlport.pod: L<README.vms>
perlport.pod: L<perlvms.pod>
perlport.pod: L<README.vos>
perlport.pod: L<README.os390>
perlport.pod: L<README.posix-bc>
perlport.pod: L<README.vmesa>
perlport.pod: L<README.amiga>
perlport.pod: L<README.mint>
perlport.pod: L<README.beos>
perlport.pod: L<README.mpeix>
perlport.pod: L<README.plan9>
perltoc.pod: L<perlwin32>
perltoc.pod: L<perlvms.pod>
perltoc.pod: L<README.vos>
perltoc.pod: L<README.os390>
perltoc.pod: L<README.posix-bc>
perltoc.pod: L<README.vmesa>
perltoc.pod: L<README.amiga>
perltoc.pod: L<README.mint>
perltoc.pod: L<README.beos>
perltoc.pod: L<README.mpeix>
perltoc.pod: L<README.plan9>
perlvar.pod: L<perlcc>
perlxs.pod: L<http://www.cs.utah.edu/~beazley/SWIG>