From 13a2d996abe42696bc5ca08abf08030d440c6148 Mon Sep 17 00:00:00 2001 From: "Stephen P. Potter" Date: Mon, 6 Nov 2000 13:56:43 -0500 Subject: [PATCH] Pod updates Message-Id: <200011062357.SAA18173@spotter.yi.org> p4raw-id: //depot/perl@7585 --- README.dos | 16 ---------------- README.os2 | 18 +++++++++--------- README.win32 | 6 +++--- pod/buildtoc.PL | 8 ++++---- pod/perl.pod | 2 +- pod/perl5004delta.pod | 35 +++++++++++++++++++---------------- pod/perl5005delta.pod | 8 ++++---- pod/perl56delta.pod | 7 ++++--- pod/perldebguts.pod | 10 +++++----- pod/perldebtut.pod | 8 ++++---- pod/perldebug.pod | 6 +++--- pod/perldelta.pod | 8 ++++---- pod/perldiag.pod | 8 ++++---- pod/perlembed.pod | 27 +++++++++++++-------------- pod/perlfaq.pod | 2 +- pod/perlfaq1.pod | 4 ++-- pod/perlfaq2.pod | 6 +++--- pod/perlfaq5.pod | 8 ++++---- pod/perlfaq7.pod | 4 ++-- pod/perlfaq8.pod | 6 +++--- pod/perlfilter.pod | 1 - pod/perlfunc.pod | 10 +++++----- pod/perlguts.pod | 4 ++-- pod/perlhack.pod | 8 ++++---- pod/perlhist.pod | 2 -- pod/perlipc.pod | 4 ++-- pod/perllexwarn.pod | 2 +- pod/perllocale.pod | 19 ++++++++++--------- pod/perlmodlib.pod | 28 ++++++++++++++++++++++------ pod/perlnumber.pod | 4 ++-- pod/perlop.pod | 10 +++++----- pod/perlopentut.pod | 24 ++++++++++++------------ pod/perlport.pod | 2 +- pod/perlre.pod | 2 +- pod/perlsub.pod | 6 +++--- pod/perltie.pod | 8 ++++---- pod/perltoot.pod | 2 +- pod/perltootc.pod | 2 +- pod/perlunicode.pod | 2 +- 39 files changed, 169 insertions(+), 168 deletions(-) diff --git a/README.dos b/README.dos index 3fd5760..fe649ed 100644 --- a/README.dos +++ b/README.dos @@ -229,8 +229,6 @@ goes under C<($DJDIR)/lib/perl5/pod>. =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 @@ an XS extension module. In addition, you will have to have built your 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 @@ to unpack and expand these files. For example: 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 @@ This is sufficient because non-XS modules install only ".pm" files and (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 @@ -333,8 +319,6 @@ by using the command: perl -S perldoc perllocal -=back - =head1 AUTHOR Laszlo Molnar, F [Installing/building perl] diff --git a/README.os2 b/README.os2 index b12ee0b..19af8c5 100644 --- a/README.os2 +++ b/README.os2 @@ -394,12 +394,12 @@ is considered a bug and should be fixed soon. =over 4 -=item +=item * Did you run your programs with C<-w> switch? See L. -=item +=item * Do you try to run I shell commands, like C<`copy a b`> (internal for F), or C<`glob a*b`> (internal for ksh)? You @@ -1163,18 +1163,18 @@ eventually). =over 4 -=item +=item * Since L is present in EMX, but is not functional, it is emulated by perl. To disable the emulations, set environment variable C. -=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 @@ L: Note that C does not work with the current version of EMX. -=item +=item * Since F is used for globing (see L), the bugs of F plague perl as well. @@ -1517,9 +1517,9 @@ cannot test it. For the details of the current situation with calling external programs, see L. -=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 @@ preliminary. Most notable problems: -=over +=over 4 =item C diff --git a/README.win32 b/README.win32 index 8e29acc..dc90ada 100644 --- a/README.win32 +++ b/README.win32 @@ -620,11 +620,11 @@ by C. =over 4 -Gary Ng E71564.1743@CompuServe.COME +=item Gary Ng E71564.1743@CompuServe.COME -Gurusamy Sarathy Egsar@activestate.comE +=item Gurusamy Sarathy Egsar@activestate.comE -Nick Ing-Simmons Enick@ni-s.u-net.comE +=item Nick Ing-Simmons Enick@ni-s.u-net.comE =back diff --git a/pod/buildtoc.PL b/pod/buildtoc.PL index 90deff4..ff8d33c 100644 --- a/pod/buildtoc.PL +++ b/pod/buildtoc.PL @@ -332,7 +332,7 @@ podset( @modules[ sort { $modname[$a] cmp $modname[$b] } 0 .. $#modules ] ); 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 @@ sub podset { } 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 @@ sub podset { 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 --git a/pod/perl.pod b/pod/perl.pod index 9f3824d..97514ee 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -189,7 +189,7 @@ But wait, there's more... Begun in 1993 (see L), 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 --git a/pod/perl5004delta.pod b/pod/perl5004delta.pod index 8cec3ab..7151d86 100644 --- a/pod/perl5004delta.pod +++ b/pod/perl5004delta.pod @@ -24,7 +24,10 @@ problems. See the F file in the distribution for details. 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 @@ hole was just plugged. The new restrictions when tainting include: -=over +=over 4 =item No glob() or <*> @@ -258,7 +261,7 @@ the F file for how to use it. =head2 New and changed syntax -=over +=over 4 =item $coderef->(PARAMS) @@ -276,7 +279,7 @@ S{FOO}->($bar) >>>. =head2 New and changed builtin constants -=over +=over 4 =item __PACKAGE__ @@ -289,7 +292,7 @@ into strings. =head2 New and changed builtin variables -=over +=over 4 =item $^E @@ -322,7 +325,7 @@ there is no C long name for this variable. =head2 New and changed builtin functions -=over +=over 4 =item delete on slices @@ -544,7 +547,7 @@ subroutine: The C package automatically contains the following methods that are inherited by all other classes: -=over +=over 4 =item isa(CLASS) @@ -593,7 +596,7 @@ have C available as a plain subroutine in the current package. See L for other kinds of tie()s. -=over +=over 4 =item TIEHANDLE classname, LIST @@ -687,7 +690,7 @@ install the optional module Devel::Peek.) 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 @@ See F in the perl distribution. Six new pragmatic modules exist: -=over +=over 4 =item use autouse MODULE => qw(sub1 sub2 sub3) @@ -979,7 +982,7 @@ those who need trigonometric functions only for real numbers. 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 @@ For example, you can now say =head2 pod2html -=over +=over 4 =item Sends converted HTML to standard output @@ -1058,7 +1061,7 @@ Use the B<--outfile=FILENAME> option to write to a file. =head2 xsubpp -=over +=over 4 =item C XSUBs now default to returning nothing @@ -1083,7 +1086,7 @@ XSUB's return type is really C. =head1 C Language API Changes -=over +=over 4 =item C and C @@ -1124,7 +1127,7 @@ which can be more efficient. See L for details. Many of the base and library pods were updated. These new pods are included in section 1: -=over +=over 4 =item L @@ -1177,7 +1180,7 @@ increasing order of desperation): (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 --git a/pod/perl5005delta.pod b/pod/perl5005delta.pod index b133c0d..d863453 100644 --- a/pod/perl5005delta.pod +++ b/pod/perl5005delta.pod @@ -525,7 +525,7 @@ The hints files for most Unix platforms have seen incremental improvements. =head2 New Modules -=over +=over 4 =item B @@ -596,7 +596,7 @@ Various pragmata to control behavior of regular expressions. =head2 Changes in existing modules -=over +=over 4 =item Benchmark @@ -702,7 +702,7 @@ L gives a tutorial on threads. =head1 New Diagnostics -=over +=over 4 =item Ambiguous call resolved as CORE::%s(), qualify as such or use & @@ -916,7 +916,7 @@ fix the problem can be found in L. =head1 Obsolete Diagnostics -=over +=over 4 =item Can't mktemp() diff --git a/pod/perl56delta.pod b/pod/perl56delta.pod index 9f30314..d11f908 100644 --- a/pod/perl56delta.pod +++ b/pod/perl56delta.pod @@ -786,7 +786,7 @@ regardless of whether or not the array has been used or declared 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 if you don't backslash the C<@>. See http://www.plover.com/~mjd/perl/at-error.html for more details @@ -1837,7 +1837,8 @@ run in compile-only mode. Since this is typically not the expected behavior, END blocks are not executed anymore when the C<-c> switch is used, or if compilation fails. -See L for how to run things when the compile phase ends. +See L for how to run things when the compile +phase ends. =head2 Potential to leak DATA filehandles @@ -2782,7 +2783,7 @@ See L for further information about that. =head2 Compatible C Source API Changes -=over +=over 4 =item C is now C diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod index 742423b..20cc546 100644 --- a/pod/perldebguts.pod +++ b/pod/perldebguts.pod @@ -23,7 +23,7 @@ frame was called with are copied to the @DB::args array. The general mechanisms is enabled by calling Perl with the B<-d> switch, the following additional features are enabled (cf. L): -=over +=over 4 =item * @@ -402,7 +402,7 @@ shorter than 7 chars. The fields of interest which may appear in the last line are -=over +=over 4 =item C I C I @@ -693,7 +693,7 @@ Devel::Peek module. Here is some explanation of that format: -=over +=over 4 =item C @@ -840,7 +840,7 @@ per glob - for glob name, and glob stringification magic. Here are explanations for other Is above: -=over +=over 4 =item C<717> @@ -894,7 +894,7 @@ these categories. If warn() string starts with -=over +=over 4 =item C diff --git a/pod/perldebtut.pod b/pod/perldebtut.pod index 2916897..ece5848 100644 --- a/pod/perldebtut.pod +++ b/pod/perldebtut.pod @@ -495,7 +495,7 @@ And a print to show what values we're currently using: 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 @@ it for inspection. In this case though, we simply continue down to line 29: 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 @@ the DEBUGGING flag for this one: floating `'$ at 4..2147483647 (checking floating) stclass `EXACTF ' anchored(BOL) minlen 4 Omitting $` $& $' support. - + EXECUTING... Freeing REx: `^pe(a)*rl$' @@ -656,7 +656,7 @@ script from the command-line, try something like this: > perl -d my_cgi.pl -nodebug -Of course 'L' and L will tell you more. +Of course L and L will tell you more. =head1 GUIs diff --git a/pod/perldebug.pod b/pod/perldebug.pod index faff39b..01f35e1 100644 --- a/pod/perldebug.pod +++ b/pod/perldebug.pod @@ -82,7 +82,7 @@ recursively, unlike the real C function in Perl. See L 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 @@ For historical reasons, the C<=value> is optional, but defaults to 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