develooper Front page | perl.perl5.porters | Postings from February 2001

[PATCH: perl@8892] reduce podchecker ERRORs

Thread Next
From:
Prymmer/Kahn
Date:
February 25, 2001 12:02
Subject:
[PATCH: perl@8892] reduce podchecker ERRORs
Message ID:
Pine.BSF.4.21.0102251153450.27050-100000@shell8.ba.best.com

Hi,

It seems that I am not the only person running podchecker lately, but
I think I've come up with some "fixes" that have not yet been posted.

I did note that the checkpods script is still distributed and even
mentioned in the pod/Makefile.SH.  Is its functionality not already
incorporated into podchecker?  Should pod/Makefile.SH mention podchecker?
Is checkpods deprecated?

The command I was running was simply:

  ./perl pod/podchecker -warnings -warnings pod/perl*.pod

so it was not as extensive.  Enclosed patch attempts to eliminate the
ERRORs reported in the respecitve files and reduce the WARNINGs (some but
not all to zero).

Do note that I've turned common expressions such as I/O into Input-Output
so as to appease podchecker's ideas about linking, and I have removed 
most ($section_number) markup since podchecker claims that it is
deprecated.  Hence this patch may not be without controversy:

diff -ru perl.8892/pod/perlfunc.pod perl/pod/perlfunc.pod
--- perl.8892/pod/perlfunc.pod	Sun Feb 25 11:38:41 2001
+++ perl/pod/perlfunc.pod	Sun Feb 25 11:42:17 2001
@@ -336,7 +336,7 @@
 
 The C<-T> and C<-B> switches work as follows.  The first block or so of the
 file is examined for odd characters such as strange control codes or
-characters with the high bit set.  If too many strange characters (>30%)
+characters with the high bit set.  If too many strange characters (more than 30%)
 are found, it's a C<-B> file, otherwise it's a C<-T> file.  Also, any file
 containing null in the first block is considered a binary file.  If C<-T>
 or C<-B> is used on a filehandle, the current stdio buffer is examined
@@ -375,7 +375,7 @@
 
 Accepts an incoming socket connect, just as the accept(2) system call
 does.  Returns the packed address if it succeeded, false otherwise.
-See the example in L<perlipc/"Sockets: Client/Server Communication">.
+See the example in L<perlipc/"Sockets: Client-Server Communication">.
 
 On systems that support a close-on-exec flag on files, the flag will
 be set for the newly opened file descriptor, as determined by the
@@ -438,7 +438,7 @@
 Binds a network address to a socket, just as the bind system call
 does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
+L<perlipc/"Sockets: Client-Server Communication">.
 
 =item binmode FILEHANDLE, DISCIPLINE
 
@@ -755,7 +755,7 @@
 Attempts to connect to a remote socket, just as the connect system call
 does.  Returns true if it succeeded, false otherwise.  NAME should be a
 packed address of the appropriate type for the socket.  See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
+L<perlipc/"Sockets: Client-Server Communication">.
 
 =item continue BLOCK
 
@@ -1794,7 +1794,7 @@
 =item getpriority WHICH,WHO
 
 Returns the current priority for a process, a process group, or a user.
-(See L<getpriority(2)>.)  Will raise a fatal exception if used on a
+(See L<getpriority>.)  Will raise a fatal exception if used on a
 machine that doesn't implement getpriority(2).
 
 =item getpwnam NAME
@@ -1975,7 +1975,7 @@
 standard Unix shell F</bin/csh> would do.  This is the internal function
 implementing the C<< <*.c> >> operator, but you can use it directly.
 If EXPR is omitted, C<$_> is used.  The C<< <*.c> >> operator is
-discussed in more detail in L<perlop/"I/O Operators">.
+discussed in more detail in L<perlop/"Input-Output Operators">.
 
 Beginning with v5.6.0, this operator is implemented using the standard
 C<File::Glob> extension.  See L<File::Glob> for details.
@@ -2119,7 +2119,7 @@
 There is no builtin C<import> function.  It is just an ordinary
 method (subroutine) defined (or inherited) by modules that wish to export
 names to another module.  The C<use> function calls the C<import> method
-for the package used.  See also L</use()>, L<perlmod>, and L<Exporter>.
+for the package used.  See also L</use>, L<perlmod>, and L<Exporter>.
 
 =item index STR,SUBSTR,POSITION
 
@@ -2338,7 +2338,7 @@
 =item listen SOCKET,QUEUESIZE
 
 Does the same thing that the listen system call does.  Returns true if
-it succeeded, false otherwise.  See the example in L<perlipc/"Sockets: Client/Server Communication">.
+it succeeded, false otherwise.  See the example in L<perlipc/"Sockets: Client-Server Communication">.
 
 =item local EXPR
 
@@ -2492,7 +2492,7 @@
     %hash = map { ("\L$_", 1) } @array  # this also works
     %hash = map {  lc($_), 1  } @array  # as does this.
     %hash = map +( lc($_), 1 ), @array  # this is EXPR and works!
-      
+
     %hash = map  ( lc($_), 1 ), @array  # evaluates to (1, @array)
 
 or to force an anon hash constructor use C<+{>
@@ -2866,7 +2866,7 @@
 
 will have exactly the opposite restrictions.
 
-If you want a "real" C C<open> (see L<open(2)> on your system), then you
+If you want a "real" C C<open> (see L<open> on your system), then you
 should use the C<sysopen> function, which involves no such magic (but
 may use subtly different filemodes than Perl open(), which is mapped
 to C fopen()).  This is
@@ -3540,7 +3540,7 @@
 
 This is the internal function implementing the C<< <EXPR> >>
 operator, but you can use it directly.  The C<< <EXPR> >>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
+operator is discussed in more detail in L<perlop/"Input-Output Operators">.
 
     $line = <STDIN>;
     $line = readline(*STDIN);		# same thing
@@ -3563,7 +3563,7 @@
 (however you've defined lines with C<$/> or C<$INPUT_RECORD_SEPARATOR>).
 This is the internal function implementing the C<qx/EXPR/>
 operator, but you can use it directly.  The C<qx/EXPR/>
-operator is discussed in more detail in L<perlop/"I/O Operators">.
+operator is discussed in more detail in L<perlop/"Input-Output Operators">.
 
 =item recv SOCKET,SCALAR,LENGTH,FLAGS
 
@@ -4146,7 +4146,7 @@
 SOCKET.  DOMAIN, TYPE, and PROTOCOL are specified the same as for
 the system call of the same name.  You should C<use Socket> first
 to get the proper definitions imported.  See the examples in
-L<perlipc/"Sockets: Client/Server Communication">.
+L<perlipc/"Sockets: Client-Server Communication">.
 
 On systems that support a close-on-exec flag on files, the flag will
 be set for the newly opened file descriptor, as determined by the
@@ -4442,7 +4442,7 @@
 
 Returns a string formatted by the usual C<printf> conventions of the C
 library function C<sprintf>.  See below for more details
-and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
+and see L<sprintf> or L<printf> on your system for an explanation of
 the general principles.
 
 For example:
diff -ru perl.8892/pod/perlhack.pod perl/pod/perlhack.pod
--- perl.8892/pod/perlhack.pod	Sun Feb 25 11:40:16 2001
+++ perl/pod/perlhack.pod	Sun Feb 25 11:42:30 2001
@@ -382,7 +382,7 @@
 
 =over 4
 
-=item It's easier
+=item It is easier
 
 If you have more than one machine that you want to keep in track with
 bleadperl, it's easier to rsync the patches only once and then apply
@@ -1241,7 +1241,7 @@
 =item break source.c:xxx
 
 Tells the debugger that we'll want to pause execution when we reach
-either the named function (but see L</Function names>!) or the given
+either the named function (but see L<perlguts/Internal Functions>!) or the given
 line in the named source file.
 
 =item step
@@ -1299,7 +1299,7 @@
     (gdb) break Perl_pp_add
     Breakpoint 1 at 0x46249f: file pp_hot.c, line 309.
 
-Notice we use C<Perl_pp_add> and not C<pp_add> - see L<perlguts/Function Names>.
+Notice we use C<Perl_pp_add> and not C<pp_add> - see L<perlguts/Internal Functions>.
 With the breakpoint in place, we can run our program:
 
     (gdb) run -e '$b = "6XXXX"; $c = 2.3; $a = $b + $c'
@@ -1371,7 +1371,7 @@
             }
         }
 
-< finish this later >
+C< finish this later >
 
 =head2 Patching
 
diff -ru perl.8892/pod/perlipc.pod perl/pod/perlipc.pod
--- perl.8892/pod/perlipc.pod	Sun Feb 25 11:41:13 2001
+++ perl/pod/perlipc.pod	Sun Feb 25 11:42:41 2001
@@ -352,7 +352,7 @@
 The fork() has to come before the setsid() to ensure that you aren't a
 process group leader (the setsid() will fail if you are).  If your
 system doesn't have the setsid() function, open F</dev/tty> and use the
-C<TIOCNOTTY> ioctl() on it instead.  See L<tty(4)> for details.
+C<TIOCNOTTY> ioctl() on it instead.  See L<tty> for details.
 
 Non-Unix users should check their Your_OS::Process module for other
 solutions.
@@ -578,7 +578,7 @@
 	exit;
     }
 
-=head1 Sockets: Client/Server Communication
+=head1 Sockets: Client-Server Communication
 
 While not limited to Unix-derived operating systems (e.g., WinSock on PCs
 provides socket support, as do some VMS libraries), you may not have
@@ -978,7 +978,7 @@
 
 =over 4
 
-=item C<Proto>
+=item C<'Proto'>
 
 This is which protocol to use.  In this case, the socket handle returned
 will be connected to a TCP socket, because we want a stream-oriented
@@ -986,7 +986,7 @@
 Not all sockets are this of this type.  For example, the UDP protocol
 can be used to make a datagram socket, used for message-passing.
 
-=item C<PeerAddr>
+=item C<'PeerAddr'>
 
 This is the name or Internet address of the remote host the server is
 running on.  We could have specified a longer name like C<"www.perl.com">,
@@ -995,7 +995,7 @@
 current machine you're running on.  The corresponding Internet address
 for localhost is C<"127.1">, if you'd rather use that.
 
-=item C<PeerPort>
+=item C<'PeerPort'>
 
 This is the service name or port number we'd like to connect to.
 We could have gotten away with using just C<"daytime"> on systems with a
Only in perl.8892/pod: perllocale.pod
diff -ru perl.8892/pod/perlop.pod perl/pod/perlop.pod
--- perl.8892/pod/perlop.pod	Sun Feb 25 11:40:53 2001
+++ perl/pod/perlop.pod	Sun Feb 25 11:42:54 2001
@@ -91,7 +91,7 @@
 constructors C<[]> and C<{}>.
 
 See also L<Quote and Quote-like Operators> toward the end of this section,
-as well as L<"I/O Operators">.
+as well as L<"Input-Output Operators">.
 
 =head2 The Arrow Operator
 
@@ -1133,7 +1133,7 @@
 a glue language, and one of the things it glues together is commands.
 Just understand what you're getting yourself into.
 
-See L<"I/O Operators"> for more discussion.
+See L<"Input-Output Operators"> for more discussion.
 
 =item s/PATTERN/REPLACEMENT/egimosx
 
@@ -1571,7 +1571,7 @@
 
 =back
 
-=head2 I/O Operators
+=head2 Input-Output Operators
 
 There are several I/O operators you should know about.
 
End of Patch.

Peter Prymmer





Thread Next


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