pod nits from various perl porters

p4raw-id: //depot/perl@4368

3 files changed, 61 insertions, 4 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 1c93ed14bb..5a054e13b3 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -1126,7 +1126,64 @@ instead of
 
 =item Getopt::Long
 
-[TODO - Johan Vromans <jvromans@squirrel.nl>]
+Getopt::Long licensing has changed to allow the Perl Artistic License
+as well as the GPL. It used to be GPL only, which got in the way of
+non-GPL applications that wanted to use Getopt::Long.
+
+Getopt::Long encourages the use of Pod::Usage to produce help
+messages. For example:
+
+    use Getopt::Long;
+    use Pod::Usage;
+    my $man = 0;
+    my $help = 0;
+    GetOptions('help|?' => \$help, man => \$man) or pod2usage(2);
+    pod2usage(1) if $help;
+    pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+
+    __END__
+
+    =head1 NAME
+
+    sample - Using GetOpt::Long and Pod::Usage
+
+    =head1 SYNOPSIS
+
+    sample [options] [file ...]
+
+     Options:
+       -help            brief help message
+       -man             full documentation
+
+    =head1 OPTIONS
+
+    =over 8
+
+    =item B<-help>
+
+    Print a brief help message and exits.
+
+    =item B<-man>
+
+    Prints the manual page and exits.
+
+    =back
+
+    =head1 DESCRIPTION
+
+    B<This program> will read the given input file(s) and do someting
+    useful with the contents thereof.
+
+    =cut
+
+See L<Pod::Usage> for details.
+
+A bug that prevented the non-option call-back E<lt>E<gt> from being
+specified as the first argument has been fixed.
+
+To specify the characters E<lt> and E<gt> as option starters, use
+E<gt>E<lt>. Note, however, that changing option starters is strongly
+deprecated. 
 
 =item IO
 
@@ -1559,7 +1616,7 @@ two from 1 to 32 (or 64, if your platform supports that).
 =item Integer overflow in %s number
 
 (W) The hexadecimal, octal or binary number you have specified either
-as a literal in your code or as a scalar is too big for your
+as a literal or as an argument to hex() or oct() is too big for your
 architecture, and has been converted to a floating point number.  On a
 32-bit architecture the largest hexadecimal, octal or binary number
 representable without overflow is 0xFFFFFFFF, 037777777777, or
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index ba1e3746e1..527f73bbe6 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -1629,7 +1629,7 @@ known value, using trustworthy data.  See L<perlsec>.
 =item Integer overflow in %s number
 
 (W) The hexadecimal, octal or binary number you have specified either
-as a literal in your code or as a scalar is too big for your
+as a literal or as an argument to hex() or oct() is too big for your
 architecture, and has been converted to a floating point number.  On a
 32-bit architecture the largest hexadecimal, octal or binary number
 representable without overflow is 0xFFFFFFFF, 037777777777, or
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d8c82bbeda..42c5d2bdd5 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -1978,7 +1978,7 @@ L</oct>.)  If EXPR is omitted, uses C<$_>.
     print hex 'aF';   # same
 
 Hex strings may only represent integers.  Strings that would cause
-integer overflow trigger a mandatory error message.
+integer overflow trigger a warning.
 
 =item import