develooper 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>



nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About