develooper Front page | perl.perl5.porters | Postings from November 2000

Pod updates

From:
Stephen P. Potter
Date:
November 6, 2000 14:57
Subject:
Pod updates
Message ID:
200011062357.SAA18173@spotter.yi.org
I ran podchecker across the pod directory and here are a goodly number of
changes to bring the pods more into "conformance" with the output.  There
are a couple of warnings that I chose to ignore for now, but I got all the
errors and a good percentage of the warnings.

Also, I'd like to recommend a change for POD itself.  Links are defined as:
         L<name>     A link (cross reference) to name
                         L<name>             manual page
                         L<name/ident>       item in manual page
                         L<name/"sec">       section in other manual page
                         L<"sec">            section in this manual page
                                             (the quotes are optional)
                         L</"sec">           ditto

This definition makes it very difficult for the translaters to guess
whether the link is internal or external.  I'd like to suggest the
following:
    L<name>	A link (cross reference) to name
		  L<name(#)>     A man page (# is optional)
		  L<name/"sec">  A section in other manual page (quotes
				 optional) If name missing, current man
				 page
	          L<name/"sec":ident> An item in manual page

It would probably make sense to actually make the # and quotes required,
then have the parsers skip anything in quotes.  That would clear up a good
number of errors right there.  Also, I'm not completely sure on the last
part.  I'm not sure what was meant to be the difference between sec and
ident since it isn't well defined in the perlpod man page.  I guessing it
means an "=item".  I would also leave alone the L<text|...> versions,
except as the ... corresponds to the above.

diff -ui pod/buildtoc.PL pod1/buildtoc.PL
--- pod/buildtoc.PL	Tue Oct 24 15:58:53 2000
+++ pod1/buildtoc.PL	Mon Nov  6 17:24:41 2000
@@ -332,7 +332,7 @@
 	Here should be listed all the extra programs' documentation, but they
 	don't all have manual pages yet:
 
-	=over
+	=over 4
 
 	=item a2p
 
@@ -385,13 +385,13 @@
 	}
 	if (s/^=head1 (.*)/=item $1/) {
 	    unhead2();
-	    output "=over\n\n" unless $inhead1;
+	    output "=over 4\n\n" unless $inhead1;
 	    $inhead1 = 1;
 	    output $_; nl(); next;
 	}
 	if (s/^=head2 (.*)/=item $1/) {
 	    unitem();
-	    output "=over\n\n" unless $inhead2;
+	    output "=over 4\n\n" unless $inhead2;
 	    $inhead2 = 1;
 	    output $_; nl(); next;
 	}
@@ -403,7 +403,7 @@
 	    s/\s+$//;
 	    next if /^[\d.]+$/;
 	    next if $pod eq 'perlmodlib' && /^ftp:/;
-	    ##print "=over\n\n" unless $initem;
+	    ##print "=over 4\n\n" unless $initem;
 	    output ", " if $initem;
 	    $initem = 1;
 	    s/\.$//;
diff -ui pod/perl.pod pod1/perl.pod
--- pod/perl.pod	Tue Oct 24 15:58:53 2000
+++ pod1/perl.pod	Mon Nov  6 16:22:02 2000
@@ -189,7 +189,7 @@
 Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
 rewrite that provides the following additional benefits:
 
-=over
+=over 4
 
 =item * modularity and reusability using innumerable modules 
 
diff -ui pod/perl5004delta.pod pod1/perl5004delta.pod
--- pod/perl5004delta.pod	Mon Aug 28 19:33:42 2000
+++ pod1/perl5004delta.pod	Mon Nov  6 16:24:38 2000
@@ -24,7 +24,10 @@
 C<%ENV = ()> and C<%ENV = @list> now work as expected (except on VMS
 where it generates a fatal error).
 
-=head2 "Can't locate Foo.pm in @INC" error now lists @INC
+=head2 Change to "Can't locate Foo.pm in @INC" error
+
+The error "Can't locate Foo.pm in @INC" now lists the contents of @INC
+for easier debugging.
 
 =head2 Compilation option: Binary compatibility with 5.003
 
@@ -198,7 +201,7 @@
 
 The new restrictions when tainting include:
 
-=over
+=over 4
 
 =item No glob() or <*>
 
@@ -258,7 +261,7 @@
 
 =head2 New and changed syntax
 
-=over
+=over 4
 
 =item $coderef->(PARAMS)
 
@@ -276,7 +279,7 @@
 
 =head2 New and changed builtin constants
 
-=over
+=over 4
 
 =item __PACKAGE__
 
@@ -289,7 +292,7 @@
 
 =head2 New and changed builtin variables
 
-=over
+=over 4
 
 =item $^E
 
@@ -322,7 +325,7 @@
 
 =head2 New and changed builtin functions
 
-=over
+=over 4
 
 =item delete on slices
 
@@ -544,7 +547,7 @@
 The C<UNIVERSAL> package automatically contains the following methods that
 are inherited by all other classes:
 
-=over
+=over 4
 
 =item isa(CLASS)
 
@@ -593,7 +596,7 @@
 
 See L<perltie> for other kinds of tie()s.
 
-=over
+=over 4
 
 =item TIEHANDLE classname, LIST
 
@@ -687,7 +690,7 @@
 Three new compilation flags are recognized by malloc.c.  (They have no
 effect if perl is compiled with system malloc().)
 
-=over
+=over 4
 
 =item -DPERL_EMERGENCY_SBRK
 
@@ -779,7 +782,7 @@
 
 Six new pragmatic modules exist:
 
-=over
+=over 4
 
 =item use autouse MODULE => qw(sub1 sub2 sub3)
 
@@ -979,7 +982,7 @@
 There have been quite a few changes made to DB_File. Here are a few of
 the highlights:
 
-=over
+=over 4
 
 =item *
 
@@ -1045,7 +1048,7 @@
 
 =head2 pod2html
 
-=over
+=over 4
 
 =item Sends converted HTML to standard output
 
@@ -1058,7 +1061,7 @@
 
 =head2 xsubpp
 
-=over
+=over 4
 
 =item C<void> XSUBs now default to returning nothing
 
@@ -1083,7 +1086,7 @@
 
 =head1 C Language API Changes
 
-=over
+=over 4
 
 =item C<gv_fetchmethod> and C<perl_call_sv>
 
@@ -1124,7 +1127,7 @@
 Many of the base and library pods were updated.  These
 new pods are included in section 1:
 
-=over
+=over 4
 
 =item L<perldelta>
 
@@ -1177,7 +1180,7 @@
    (X) A very fatal error (nontrappable).
    (A) An alien error message (not generated by Perl).
 
-=over
+=over 4
 
 =item "my" variable %s masks earlier declaration in same scope
 
diff -ui pod/perl5005delta.pod pod1/perl5005delta.pod
--- pod/perl5005delta.pod	Mon Jul 31 22:32:02 2000
+++ pod1/perl5005delta.pod	Mon Nov  6 16:24:53 2000
@@ -525,7 +525,7 @@
 
 =head2 New Modules
 
-=over
+=over 4
 
 =item B
 
@@ -596,7 +596,7 @@
 
 =head2 Changes in existing modules
 
-=over
+=over 4
 
 =item Benchmark
 
@@ -702,7 +702,7 @@
 
 =head1 New Diagnostics
 
-=over
+=over 4
 
 =item Ambiguous call resolved as CORE::%s(), qualify as such or use &
 
@@ -916,7 +916,7 @@
 
 =head1 Obsolete Diagnostics
 
-=over
+=over 4
 
 =item Can't mktemp()
 
diff -ui pod/perl56delta.pod pod1/perl56delta.pod
--- pod/perl56delta.pod	Fri Sep  1 19:02:28 2000
+++ pod1/perl56delta.pod	Mon Nov  6 16:26:30 2000
@@ -786,7 +786,7 @@
 already.  The fatal error has been downgraded to an optional warning:
 
         Possible unintended interpolation of @example in string
-        
+
 This warns you that C<"fred@example.com"> is going to turn into
 C<fred.com> if you don't backslash the C<@>.
 See http://www.plover.com/~mjd/perl/at-error.html for more details
@@ -1837,7 +1837,8 @@
 behavior, END blocks are not executed anymore when the C<-c> switch
 is used, or if compilation fails.
 
-See L<CHECK blocks> for how to run things when the compile phase ends.
+See L</"Support for CHECK blocks"> for how to run things when the compile 
+phase ends.
 
 =head2 Potential to leak DATA filehandles
 
@@ -2782,7 +2783,7 @@
 
 =head2 Compatible C Source API Changes
 
-=over
+=over 4
 
 =item C<PATCHLEVEL> is now C<PERL_VERSION>
 
diff -ui pod/perldebguts.pod pod1/perldebguts.pod
--- pod/perldebguts.pod	Mon Oct  9 09:45:04 2000
+++ pod1/perldebguts.pod	Mon Nov  6 16:27:46 2000
@@ -23,7 +23,7 @@
 general mechanisms is enabled by calling Perl with the B<-d> switch, the
 following additional features are enabled (cf. L<perlvar/$^P>):
 
-=over
+=over 4
 
 =item *
 
@@ -402,7 +402,7 @@
 
 The fields of interest which may appear in the last line are
 
-=over
+=over 4
 
 =item C<anchored> I<STRING> C<at> I<POS>
 
@@ -693,7 +693,7 @@
 
 Here is some explanation of that format:
 
-=over
+=over 4
 
 =item C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>
 
@@ -840,7 +840,7 @@
 
 Here are explanations for other I<Id>s above: 
 
-=over
+=over 4
 
 =item C<717> 
 
@@ -894,7 +894,7 @@
 
 If warn() string starts with
 
-=over
+=over 4
 
 =item C<!!!> 
 
diff -ui pod/perldebtut.pod pod1/perldebtut.pod
--- pod/perldebtut.pod	Wed Aug 30 10:50:53 2000
+++ pod1/perldebtut.pod	Mon Nov  6 16:41:17 2000
@@ -495,7 +495,7 @@
 
 	DB<1> p $deg, $num
 	f33.3
-		
+
 We can put another break point on any line beginning with a colon, we'll use
 line 17 as that's just as we come out of the subroutine, and we'd like to
 pause there later on:
@@ -538,7 +538,7 @@
 
 	DB<4> c 29  
 	main::f2c(temp:29):             return $c;
-   
+
 And have a look at the return value:
 
 	DB<5> p $c
@@ -616,7 +616,7 @@
 	floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF <pe>'
 anchored(BOL) minlen 4
 	Omitting $` $& $' support.
-	 
+
 	EXECUTING...
 
 	Freeing REx: `^pe(a)*rl$'  
@@ -656,7 +656,7 @@
 
 	> perl -d my_cgi.pl -nodebug 
 
-Of course 'L<perldoc CGI>' and L<perlfaq9> will tell you more.
+Of course L<CGI> and L<perlfaq9> will tell you more.
 
 
 =head1 GUIs
diff -ui pod/perldebug.pod pod1/perldebug.pod
--- pod/perldebug.pod	Wed Aug 30 10:50:53 2000
+++ pod1/perldebug.pod	Mon Nov  6 16:42:26 2000
@@ -82,7 +82,7 @@
 See L<Dumpvalue> if you'd like to do this yourself.
 
 The output format is governed by multiple options described under
-L<"Options">.
+L<"Configurable Options">.
 
 =item V [pkg [vars]]
 
@@ -308,8 +308,8 @@
 1 only where it is safe to do so--that is, mostly for Boolean
 options.  It is always better to assign a specific value using C<=>.
 The C<option> can be abbreviated, but for clarity probably should
-not be.  Several options can be set together.  See L<"Options"> for
-a list of these.
+not be.  Several options can be set together.  See L<"Configurable Options"> 
+for a list of these.
 
 =item < ? 
 
diff -ui pod/perldelta.pod pod1/perldelta.pod
--- pod/perldelta.pod	Wed Oct 25 16:59:39 2000
+++ pod1/perldelta.pod	Mon Nov  6 16:44:33 2000
@@ -232,8 +232,6 @@
 
 The Shell module now has an OO interface.
 
-=item *
-
 =back
 
 =head1 Utility Changes
@@ -726,6 +724,8 @@
 
 =back
 
+=back
+
 =head1 New or Changed Diagnostics
 
 All regular expression compilation error messages are now hopefully
@@ -852,6 +852,8 @@
 
 st-store.t and st-retrieve may fail with Compaq C 6.2 on OpenVMS Alpha 7.2.
 
+=back
+
 =head2 Threads Are Still Experimental
 
 Multithreading is still an experimental feature.  Some platforms
@@ -880,8 +882,6 @@
 The compiler suite is slowly getting better but is nowhere near
 working order yet.  The backend part that has seen perhaps the most
 progress is the bytecode compiler.
-
-=back
 
 =head1 Reporting Bugs
 
diff -ui pod/perldiag.pod pod1/perldiag.pod
--- pod/perldiag.pod	Sun Nov  5 12:20:25 2000
+++ pod1/perldiag.pod	Mon Nov  6 16:45:50 2000
@@ -1116,8 +1116,8 @@
 
 =item Copy method did not return a reference
 
-(F) The method which overloads "=" is buggy. See L<overload/Copy
-Constructor>.
+(F) The method which overloads "=" is buggy. See 
+L<overload/Copy Constructor>.
 
 =item CORE::%s is not a keyword
 
@@ -1660,8 +1660,8 @@
 
 (W syntax) You've run afoul of the rule that says that any list operator
 followed by parentheses turns into a function, with all the list
-operators arguments found inside the parentheses.  See L<perlop/Terms
-and List Operators (Leftward)>.
+operators arguments found inside the parentheses.  See 
+L<perlop/Terms and List Operators (Leftward)>.
 
 =item Invalid %s attribute: %s
 
diff -ui pod/perldos.pod pod1/perldos.pod
--- pod/perldos.pod	Sat Oct 28 13:12:44 2000
+++ pod1/perldos.pod	Mon Nov  6 16:47:18 2000
@@ -229,8 +229,6 @@
 
 =head2 Prerequisites
 
-=over 4
-
 For building and installing non-XS modules, all you need is a working
 perl under DJGPP.  Non-XS modules do not require re-linking the perl
 binary, and so are simpler to build and install.
@@ -247,12 +245,8 @@
 perl binary from the source distribution so that all of the components
 of the perl binary are available for the required link step.
 
-=back
-
 =head2 Unpacking CPAN Modules
 
-=over 4
-
 First, download the module package from CPAN (e.g., the "Comma Separated
 Value" text package, Text-CSV-0.01.tar.gz).  Then expand the contents of
 the package into some location on your disk.  Most CPAN modules are
@@ -278,15 +272,11 @@
 This will create the new directory C<($DJDIR)/Text-CSV-0.01>, filling
 it with the source for this module.
 
-=back
-
 =head2 Building Non-XS Modules
 
 To build a non-XS module, you can use the standard module-building
 instructions distributed with perl modules.
 
-=over 4
-
     perl Makefile.PL
     make
     make test
@@ -296,16 +286,12 @@
 (sometimes) pod and/or man documentation.  No re-linking of the perl
 binary is needed to build, install or use non-XS modules.
 
-=back
-
 =head2 Building XS Modules
 
 To build an XS module, you must use the standard module-building
 instructions distributed with perl modules *PLUS* three extra
 instructions specific to the DJGPP "static link" build environment.
 
-=over 4
-
     set FNCASE=y
     perl Makefile.PL
     make
@@ -332,8 +318,6 @@
 by using the command:
 
         perl -S perldoc perllocal
-
-=back
 
 =head1 AUTHOR
 
diff -ui pod/perlembed.pod pod1/perlembed.pod
--- pod/perlembed.pod	Fri Aug  4 08:30:20 2000
+++ pod1/perlembed.pod	Mon Nov  6 16:54:42 2000
@@ -37,25 +37,25 @@
 
 =over 5
 
-L<Compiling your C program>
+=item Compiling your C program
 
-L<Adding a Perl interpreter to your C program>
+=item Adding a Perl interpreter to your C program
 
-L<Calling a Perl subroutine from your C program>
+=item Calling a Perl subroutine from your C program
 
-L<Evaluating a Perl statement from your C program>
+=item Evaluating a Perl statement from your C program
 
-L<Performing Perl pattern matches and substitutions from your C program>
+=item Performing Perl pattern matches and substitutions from your C program
 
-L<Fiddling with the Perl stack from your C program>
+=item Fiddling with the Perl stack from your C program
 
-L<Maintaining a persistent interpreter>
+=item Maintaining a persistent interpreter
 
-L<Maintaining multiple interpreter instances>
+=item Maintaining multiple interpreter instances
 
-L<Using Perl modules, which themselves use C libraries, from your C program>
+=item Using Perl modules, which themselves use C libraries, from your C program
 
-L<Embedding Perl under Win32>
+=item Embedding Perl under Win32
 
 =back 
 
@@ -258,9 +258,8 @@
 If you want to pass arguments to the Perl subroutine, you can add
 strings to the C<NULL>-terminated C<args> list passed to
 I<call_argv>.  For other data types, or to examine return values,
-you'll need to manipulate the Perl stack.  That's demonstrated in the
-last section of this document: L<Fiddling with the Perl stack from
-your C program>.
+you'll need to manipulate the Perl stack.  That's demonstrated in
+L<Fiddling with the Perl stack from your C program>.
 
 =head2 Evaluating a Perl statement from your C program
 
@@ -948,7 +947,7 @@
 
 Consult L<perlxs>, L<perlguts>, and L<perlapi> for more details.
 
-=head1 Embedding Perl under Windows
+=head1 Embedding Perl under Win32
 
 In general, all of the source code shown here should work unmodified under
 Windows.
diff -ui pod/perlfaq.pod pod1/perlfaq.pod
--- pod/perlfaq.pod	Tue Oct 31 09:20:32 2000
+++ pod1/perlfaq.pod	Mon Nov  6 16:54:56 2000
@@ -6,7 +6,7 @@
 
 This document is structured into the following sections:
 
-=over
+=over 4
 
 =item perlfaq: Structural overview of the FAQ.
 
diff -ui pod/perlfaq1.pod pod1/perlfaq1.pod
--- pod/perlfaq1.pod	Tue Oct 31 09:20:32 2000
+++ pod1/perlfaq1.pod	Mon Nov  6 16:55:38 2000
@@ -78,8 +78,8 @@
 perl source code from releases 1 through 4.  It has been modularized,
 object-oriented, tweaked, trimmed, and optimized until it almost doesn't
 look like the old code.  However, the interface is mostly the same, and
-compatibility with previous releases is very high. See L<perltrap/"Perl4
-to Perl5 Traps">.
+compatibility with previous releases is very high. 
+See L<perltrap/"Perl4 to Perl5 Traps">.
 
 To avoid the "what language is perl5?" confusion, some people prefer to
 simply use "perl" to refer to the latest version of perl and avoid using
diff -ui pod/perlfaq2.pod pod1/perlfaq2.pod
--- pod/perlfaq2.pod	Tue Oct 31 09:20:32 2000
+++ pod1/perlfaq2.pod	Mon Nov  6 16:56:17 2000
@@ -80,8 +80,8 @@
 
     % perl -V
 
-You might also want to check out L<perlfaq8/"How do I keep my own
-module/library directory?">.
+You might also want to check out 
+L<perlfaq8/"How do I keep my own module/library directory?">.
 
 =head2 I grabbed the sources and tried to compile but gdbm/dynamic loading/malloc/linking/... failed.  How do I make it work?
 
@@ -247,7 +247,7 @@
 
 Recommended books on (or mostly on) Perl follow.
 
-=over
+=over 4
 
 =item References
 
diff -ui pod/perlfaq5.pod pod1/perlfaq5.pod
--- pod/perlfaq5.pod	Tue Oct 31 09:20:32 2000
+++ pod1/perlfaq5.pod	Mon Nov  6 16:57:29 2000
@@ -294,8 +294,8 @@
     }
 
 For passing filehandles to functions, the easiest way is to 
-preface them with a star, as in func(*STDIN).  See L<perlfaq7/"Passing
-Filehandles"> for details.
+preface them with a star, as in func(*STDIN).  
+See L<perlfaq7/"Passing Filehandles"> for details.
 
 If you want to create many anonymous handles, you should check out the
 Symbol, FileHandle, or IO::Handle (etc.) modules.  Here's the equivalent
@@ -675,8 +675,8 @@
 Slavish adherence to portability concerns shouldn't get in the way of
 your getting your job done.)
 
-For more information on file locking, see also L<perlopentut/"File
-Locking"> if you have it (new for 5.6).
+For more information on file locking, see also 
+L<perlopentut/"File Locking"> if you have it (new for 5.6).
 
 =back
 
diff -ui pod/perlfaq7.pod pod1/perlfaq7.pod
--- pod/perlfaq7.pod	Tue Oct 31 09:20:33 2000
+++ pod1/perlfaq7.pod	Mon Nov  6 16:58:30 2000
@@ -560,8 +560,8 @@
 variables.  It gives a global variable a temporary value.  my() is
 what you're looking for if you want private variables.
 
-See L<perlsub/"Private Variables via my()"> and L<perlsub/"Temporary
-Values via local()"> for excruciating details.
+See L<perlsub/"Private Variables via my()"> and 
+L<perlsub/"Temporary Values via local()"> for excruciating details.
 
 =head2 How can I access a dynamic variable while a similarly named lexical is in scope?
 
diff -ui pod/perlfaq8.pod pod1/perlfaq8.pod
--- pod/perlfaq8.pod	Wed Nov  1 13:32:48 2000
+++ pod1/perlfaq8.pod	Mon Nov  6 16:59:40 2000
@@ -571,9 +571,9 @@
 The IPC::Open2 module (part of the standard perl distribution) is an
 easy-to-use approach that internally uses pipe(), fork(), and exec() to do
 the job.  Make sure you read the deadlock warnings in its documentation,
-though (see L<IPC::Open2>).  See L<perlipc/"Bidirectional Communication
-with Another Process"> and L<perlipc/"Bidirectional Communication with
-Yourself">
+though (see L<IPC::Open2>).  See 
+L<perlipc/"Bidirectional Communication with Another Process"> and 
+L<perlipc/"Bidirectional Communication with Yourself">
 
 You may also use the IPC::Open3 module (part of the standard perl
 distribution), but be warned that it has a different order of
diff -ui pod/perlfilter.pod pod1/perlfilter.pod
--- pod/perlfilter.pod	Mon Jul 31 22:32:03 2000
+++ pod1/perlfilter.pod	Mon Nov  6 16:59:55 2000
@@ -2,7 +2,6 @@
 
 perlfilter - Source Filters
 
-
 =head1 DESCRIPTION
 
 This article is about a little-known feature of Perl called
diff -ui pod/perlfunc.pod pod1/perlfunc.pod
--- pod/perlfunc.pod	Sat Oct 28 13:17:45 2000
+++ pod1/perlfunc.pod	Mon Nov  6 17:01:23 2000
@@ -91,7 +91,7 @@
 arranged by category.  Some functions appear in more
 than one place.
 
-=over
+=over 4
 
 =item Functions for SCALARs or strings
 
@@ -2348,8 +2348,8 @@
 =item local EXPR
 
 You really probably want to be using C<my> instead, because C<local> isn't
-what most people think of as "local".  See L<perlsub/"Private Variables
-via my()"> for details.
+what most people think of as "local".  See 
+L<perlsub/"Private Variables via my()"> for details.
 
 A local modifies the listed variables to be local to the enclosing
 block, file, or eval.  If more than one value is listed, the list must
@@ -4265,9 +4265,9 @@
 If you're using strict, you I<must not> declare $a
 and $b as lexicals.  They are package globals.  That means
 if you're in the C<main> package and type
-  
+
     @articles = sort {$b <=> $a} @files;
-  
+
 then C<$a> and C<$b> are C<$main::a> and C<$main::b> (or C<$::a> and C<$::b>),
 but if you're in the C<FooPack> package, it's the same as typing
 
diff -ui pod/perlguts.pod pod1/perlguts.pod
--- pod/perlguts.pod	Sun Oct 15 22:27:46 2000
+++ pod1/perlguts.pod	Mon Nov  6 17:03:20 2000
@@ -1088,7 +1088,7 @@
 
 Inside such a I<pseudo-block> the following service is available:
 
-=over
+=over 4
 
 =item C<SAVEINT(int i)>
 
@@ -1161,7 +1161,7 @@
 or Perlish C<GV *>s).  Where the above macros take C<int>, a similar 
 function takes C<int *>.
 
-=over
+=over 4
 
 =item C<SV* save_scalar(GV *gv)>
 
diff -ui pod/perlhack.pod pod1/perlhack.pod
--- pod/perlhack.pod	Mon Nov  6 08:46:33 2000
+++ pod1/perlhack.pod	Mon Nov  6 17:07:49 2000
@@ -1031,7 +1031,7 @@
      7	call_method("PUSH", G_SCALAR|G_DISCARD);
      8	LEAVE;
      9	POPSTACK;
-       
+
 The lines which concern the mark stack are the first, fifth and last
 lines: they save away, restore and remove the current position of the
 argument stack. 
@@ -1154,7 +1154,7 @@
 
 Some of the functionality of the debugging code can be achieved using XS
 modules.
-    
+
     -Dr => use re 'debug'
     -Dx => use O 'Debug'
 
@@ -1216,7 +1216,7 @@
 
 Run until the end of the current function, then stop again.
 
-=item
+=item 'enter'
 
 Just pressing Enter will do the most recent operation again - it's a
 blessing when stepping through miles of source code.
@@ -1460,7 +1460,7 @@
 All done. Now let's create the patch. F<Porting/patching.pod> tells us
 that if we're making major changes, we should copy the entire directory
 to somewhere safe before we begin fiddling, and then do
-    
+
     diff -ruN old new > patch
 
 However, we know which files we've changed, and we can simply do this:
diff -ui pod/perlhist.pod pod1/perlhist.pod
--- pod/perlhist.pod	Sat Sep  2 13:18:00 2000
+++ pod1/perlhist.pod	Mon Nov  6 17:08:00 2000
@@ -1,5 +1,3 @@
-=pod
-
 =head1 NAME
 
 perlhist - the Perl history records
diff -ui pod/perlipc.pod pod1/perlipc.pod
--- pod/perlipc.pod	Fri Sep  8 10:10:28 2000
+++ pod1/perlipc.pod	Mon Nov  6 17:08:50 2000
@@ -952,7 +952,7 @@
 
 Here are what those parameters to the C<new> constructor mean:
 
-=over
+=over 4
 
 =item C<Proto>
 
@@ -1147,7 +1147,7 @@
 It does this by calling the C<< IO::Socket::INET->new() >> method with
 slightly different arguments than the client did.
 
-=over
+=over 4
 
 =item Proto
 
diff -ui pod/perllexwarn.pod pod1/perllexwarn.pod
--- pod/perllexwarn.pod	Mon Aug 28 19:13:40 2000
+++ pod1/perllexwarn.pod	Mon Nov  6 17:09:21 2000
@@ -468,7 +468,7 @@
         bless [], $class ;
     }
 
-   
+
     1 ;
 
 The code below makes use of both modules, but it only enables warnings from 
diff -ui pod/perllocale.pod pod1/perllocale.pod
--- pod/perllocale.pod	Tue Aug 29 15:59:59 2000
+++ pod1/perllocale.pod	Mon Nov  6 17:11:34 2000
@@ -124,8 +124,8 @@
 
 =back
 
-C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in L<LOCALE
-CATEGORIES>.
+C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in 
+L<LOCALE CATEGORIES>.
 
 The default behavior is restored with the S<C<no locale>> pragma, or
 upon reaching the end of block enclosing C<use locale>.
@@ -348,8 +348,8 @@
 the same.  In this case, try running under a locale
 that you can list and which somehow matches what you tried.  The
 rules for matching locale names are a bit vague because
-standardization is weak in this area.  See again the L<Finding
-locales> about general rules.
+standardization is weak in this area.  See again the 
+L<Finding locales> about general rules.
 
 =head2 Fixing system locale configuration
 
@@ -580,11 +580,12 @@
 that is affected by its contents.  (Those with experience of standards
 committees will recognize that the working group decided to punt on the
 issue.)  Consequently, Perl takes no notice of it.  If you really want
-to use C<LC_MONETARY>, you can query its contents--see L<The localeconv
-function>--and use the information that it returns in your application's
-own formatting of currency amounts.  However, you may well find that
-the information, voluminous and complex though it may be, still does not
-quite meet your requirements: currency formatting is a hard nut to crack.
+to use C<LC_MONETARY>, you can query its contents--see 
+L<The localeconv function>--and use the information that it returns in your 
+application's own formatting of currency amounts.  However, you may well 
+find that the information, voluminous and complex though it may be, still 
+does not quite meet your requirements: currency formatting is a hard nut 
+to crack.
 
 =head2 LC_TIME
 
diff -ui pod/perlmodlib.pod pod1/perlmodlib.pod
--- pod/perlmodlib.pod	Wed Aug 30 10:50:54 2000
+++ pod1/perlmodlib.pod	Mon Nov  6 17:12:35 2000
@@ -775,7 +775,7 @@
 some of which require a C compiler to build.  Major categories of
 modules are:
 
-=over
+=over 4
 
 =item *
 Language Extensions and Documentation Tools
@@ -845,7 +845,7 @@
 Registered CPAN sites as of this writing include the following.
 You should try to choose one close to you:
 
-=over
+=over 4
 
 =item Africa
 
diff -ui pod/perlnumber.pod pod1/perlnumber.pod
--- pod/perlnumber.pod	Mon Jul 31 22:32:05 2000
+++ pod1/perlnumber.pod	Mon Nov  6 17:13:10 2000
@@ -91,7 +91,7 @@
 
 These conversions are governed by the following general rules:
 
-=over
+=over 4
 
 =item *
 
@@ -141,7 +141,7 @@
 architecture.  C<sprintf "%u", -1> therefore provides the same result as
 C<sprintf "%u", ~0>.
 
-=over
+=over 4
 
 =item Arithmetic operators except, C<no integer>
 
diff -ui pod/perlop.pod pod1/perlop.pod
--- pod/perlop.pod	Thu Nov  2 12:48:18 2000
+++ pod1/perlop.pod	Mon Nov  6 17:15:33 2000
@@ -798,7 +798,7 @@
 and is useful when the value you are interpolating won't change over
 the life of the script.  However, mentioning C</o> constitutes a promise
 that you won't change the variables in the pattern.  If you change them,
-Perl won't even notice.  See also L<"qr//">.
+Perl won't even notice.  See also L<"qr/STRING/imosx">.
 
 If the PATTERN evaluates to the empty string, the last
 I<successfully> matched regular expression is used instead.
@@ -1338,7 +1338,7 @@
 quoting constructs, Perl performs different numbers of passes, from
 one to five, but these passes are always performed in the same order.
 
-=over
+=over 4
 
 =item Finding the end
 
@@ -1392,7 +1392,7 @@
 The next step is interpolation in the text obtained, which is now
 delimiter-independent.  There are four different cases.
 
-=over
+=over 4
 
 =item C<<<'EOF'>, C<m''>, C<s'''>, C<tr///>, C<y///>
 
@@ -1842,8 +1842,8 @@
 or so.
 
 Used on numbers, the bitwise operators ("&", "|", "^", "~", "<<",
-and ">>") always produce integral results.  (But see also L<Bitwise
-String Operators>.)  However, C<use integer> still has meaning for
+and ">>") always produce integral results.  (But see also 
+L<Bitwise String Operators>.)  However, C<use integer> still has meaning for
 them.  By default, their results are interpreted as unsigned integers, but
 if C<use integer> is in effect, their results are interpreted
 as signed integers.  For example, C<~0> usually evaluates to a large
diff -ui pod/perlopentut.pod pod1/perlopentut.pod
--- pod/perlopentut.pod	Mon Jul 31 22:32:05 2000
+++ pod1/perlopentut.pod	Mon Nov  6 17:17:28 2000
@@ -73,8 +73,8 @@
 This is not a bug, but a feature.  Because C<open> mimics the shell in
 its style of using redirection arrows to specify how to open the file, it
 also does so with respect to extra white space around the filename itself
-as well.  For accessing files with naughty names, see L<"Dispelling
-the Dweomer">.
+as well.  For accessing files with naughty names, see 
+L<"Dispelling the Dweomer">.
 
 =head2 Pipe Opens
 
@@ -107,13 +107,13 @@
 because in the traditional C<fork>/C<exec> model, running the other
 program happens only in the forked child process, which means that
 the failed C<exec> can't be reflected in the return value of C<open>.
-Only a failed C<fork> shows up there.  See L<perlfaq8/"Why doesn't open()
-return an error when a pipe open fails?"> to see how to cope with this.
-There's also an explanation in L<perlipc>.
+Only a failed C<fork> shows up there.  See 
+L<perlfaq8/"Why doesn't open() return an error when a pipe open fails?"> 
+to see how to cope with this.  There's also an explanation in L<perlipc>.
 
 If you would like to open a bidirectional pipe, the IPC::Open2
-library will handle this for you.  Check out L<perlipc/"Bidirectional
-Communication with Another Process">
+library will handle this for you.  Check out 
+L<perlipc/"Bidirectional Communication with Another Process">
 
 =head2 The Minus File
 
@@ -126,8 +126,8 @@
 If minus can be used as the default input or default output, what happens
 if you open a pipe into or out of minus?  What's the default command it
 would run?  The same script as you're currently running!  This is actually
-a stealth C<fork> hidden inside an C<open> call.  See L<perlipc/"Safe Pipe
-Opens"> for details.
+a stealth C<fork> hidden inside an C<open> call.  See 
+L<perlipc/"Safe Pipe Opens"> for details.
 
 =head2 Mixing Reads and Writes
 
@@ -684,9 +684,9 @@
 Check out Term::ReadKey and Term::ReadLine.
 
 What else can you open?  To open a connection using sockets, you won't use
-one of Perl's two open functions.  See L<perlipc/"Sockets: Client/Server
-Communication"> for that.  Here's an example.  Once you have it,
-you can use FH as a bidirectional filehandle.
+one of Perl's two open functions.  See 
+L<perlipc/"Sockets: Client/Server Communication"> for that.  Here's an 
+example.  Once you have it, you can use FH as a bidirectional filehandle.
 
     use IO::Socket;
     local *FH = IO::Socket::INET->new("www.perl.com:80");
diff -ui pod/perlos2.pod pod1/perlos2.pod
--- pod/perlos2.pod	Sat Oct 28 13:02:43 2000
+++ pod1/perlos2.pod	Mon Nov  6 17:18:57 2000
@@ -394,12 +394,12 @@
 
 =over 4
 
-=item
+=item *
 
 Did you run your programs with C<-w> switch? See 
 L<Starting OS/2 (and DOS) programs under Perl>.
 
-=item
+=item *
 
 Do you try to run I<internal> shell commands, like C<`copy a b`>
 (internal for F<cmd.exe>), or C<`glob a*b`> (internal for ksh)? You
@@ -1163,18 +1163,18 @@
 
 =over 4
 
-=item
+=item *
 
 Since L<flock(3)> is present in EMX, but is not functional, it is 
 emulated by perl.  To disable the emulations, set environment variable
 C<USE_PERL_FLOCK=0>.
 
-=item
+=item *
 
 Here is the list of things which may be "broken" on
 EMX (from EMX docs):
 
-=over
+=over 4
 
 =item *
 
@@ -1205,7 +1205,7 @@
 
 Note that C<kill -9> does not work with the current version of EMX.
 
-=item
+=item *
 
 Since F<sh.exe> is used for globing (see L<perlfunc/glob>), the bugs
 of F<sh.exe> plague perl as well. 
@@ -1517,9 +1517,9 @@
 For the details of the current situation with calling external programs,
 see L<Starting OS/2 (and DOS) programs under Perl>.
 
-=over
+=over 4
 
-=item
+=item *
 
 External scripts may be called by name.  Perl will try the same extensions
 as when processing B<-S> command-line switch.
@@ -1549,7 +1549,7 @@
 
 Most notable problems: 
 
-=over
+=over 4
 
 =item C<COND_WAIT> 
 
diff -ui pod/perlport.pod pod1/perlport.pod
--- pod/perlport.pod	Tue Oct 24 15:58:53 2000
+++ pod1/perlport.pod	Mon Nov  6 17:19:04 2000
@@ -1210,7 +1210,7 @@
 precompiled binary and source code form from http://www.novell.com/
 as well as from CPAN.
 
-=item 
+=item  *
 
 Plan 9, F<README.plan9>
 
diff -ui pod/perlre.pod pod1/perlre.pod
--- pod/perlre.pod	Mon Aug 21 14:40:02 2000
+++ pod1/perlre.pod	Mon Nov  6 17:20:52 2000
@@ -1129,7 +1129,7 @@
 notion of better/worse for combining operators.  In the description
 below C<S> and C<T> are regular subexpressions.
 
-=over
+=over 4
 
 =item C<ST>
 
diff -ui pod/perlsub.pod pod1/perlsub.pod
--- pod/perlsub.pod	Mon Jul 31 22:32:06 2000
+++ pod1/perlsub.pod	Mon Nov  6 17:22:13 2000
@@ -169,8 +169,8 @@
 
 Like the flattened incoming parameter list, the return list is also
 flattened on return.  So all you have managed to do here is stored
-everything in C<@a> and made C<@b> an empty list.  See L<Pass by
-Reference> for alternatives.
+everything in C<@a> and made C<@b> an empty list.  See 
+L<Pass by Reference> for alternatives.
 
 A subroutine may be called using an explicit C<&> prefix.  The
 C<&> is optional in modern Perl, as are parentheses if the
@@ -697,7 +697,7 @@
 C<local> operator still shines.  In fact, in these three places, you
 I<must> use C<local> instead of C<my>.
 
-=over
+=over 4
 
 =item 1. You need to give a global variable a temporary value, especially $_.
 
diff -ui pod/perltie.pod pod1/perltie.pod
--- pod/perltie.pod	Fri Nov  3 15:54:53 2000
+++ pod1/perltie.pod	Mon Nov  6 17:22:26 2000
@@ -71,7 +71,7 @@
     use strict;
     $Nice::DEBUG = 0 unless defined $Nice::DEBUG;
 
-=over
+=over 4
 
 =item TIESCALAR classname, LIST
 
@@ -225,7 +225,7 @@
     use Carp;
     use strict;
 
-=over
+=over 4
 
 =item TIEARRAY classname, LIST
 
@@ -400,7 +400,7 @@
 
 Here are the methods for the DotFiles tied hash.
 
-=over
+=over 4
 
 =item TIEHASH classname, LIST
 
@@ -655,7 +655,7 @@
 
     package Shout;
 
-=over
+=over 4
 
 =item TIEHANDLE classname, LIST
 
diff -ui pod/perltoot.pod pod1/perltoot.pod
--- pod/perltoot.pod	Mon Jul 31 22:32:06 2000
+++ pod1/perltoot.pod	Mon Nov  6 17:35:58 2000
@@ -1700,7 +1700,7 @@
 It would be nice to combine Alias with
 something like Class::Struct or Class::MethodMaker.
 
-=head2 NOTES
+=head1 NOTES
 
 =head2 Object Terminology
 
diff -ui pod/perltootc.pod pod1/perltootc.pod
--- pod/perltootc.pod	Mon Jul 31 22:32:06 2000
+++ pod1/perltootc.pod	Mon Nov  6 17:36:10 2000
@@ -12,7 +12,7 @@
 
 Here are a few examples where class attributes might come in handy:
 
-=over
+=over 4
 
 =item *
 
diff -ui pod/perlunicode.pod pod1/perlunicode.pod
--- pod/perlunicode.pod	Wed Oct 25 15:59:34 2000
+++ pod1/perlunicode.pod	Mon Nov  6 17:36:34 2000
@@ -10,7 +10,7 @@
 
 The following areas need further work.
 
-=over
+=over 4
 
 =item Input and Output Disciplines
 
diff -ui pod/perlwin32.pod pod1/perlwin32.pod
--- pod/perlwin32.pod	Thu Oct 26 09:01:35 2000
+++ pod1/perlwin32.pod	Mon Nov  6 17:37:03 2000
@@ -620,11 +620,11 @@
 
 =over 4
 
-Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
+=item Gary Ng E<lt>71564.1743@CompuServe.COME<gt>
 
-Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
+=item Gurusamy Sarathy E<lt>gsar@activestate.comE<gt>
 
-Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
+=item Nick Ing-Simmons E<lt>nick@ni-s.u-net.comE<gt>
 
 =back
 
Only in pod1: poderrors



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