Change 27330 failed to decontaminate SvCUR/GvFLAGS when upgrading an

[perl5.git] / pod / perl.pod

diff --git a/pod/perl.pod b/pod/perl.pod
index 15e4e84..2f3b109 100644 (file)
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -4,114 +4,175 @@ perl - Practical Extraction and Report Language
 
 =head1 SYNOPSIS
 
 
 =head1 SYNOPSIS
 

-B<perl>        S<[ B<-sTuU> ]> S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
-    S<[ B<-cw> ] [ B<-d>[:I<debugger>] ] [ B<-D>[I<number/list>] ]>
-    S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal>] ]>
-    S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ]>
-    S<[ B<-P> ]> S<[ B<-S> ]> S<[ B<-x>[I<dir>] ]>
-    S<[ B<-i>[I<extension>] ]> S<[ B<-e> I<'command'> ] 
-    [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
-
-For ease of access, the Perl manual has been split up into several sections:
+B<perl>        S<[ B<-sTtuUWX> ]>
+       S<[ B<-hv> ] [ B<-V>[:I<configvar>] ]>
+       S<[ B<-cw> ] [ B<-d>[B<t>][:I<debugger>] ] [ B<-D>[I<number/list>] ]>
+       S<[ B<-pna> ] [ B<-F>I<pattern> ] [ B<-l>[I<octal>] ] [ B<-0>[I<octal/hexadecimal>] ]>
+       S<[ B<-I>I<dir> ] [ B<-m>[B<->]I<module> ] [ B<-M>[B<->]I<'module...'> ] [ B<-f> ]>
+       S<[ B<-A>[I<module>][=I<assertions>] ]>
+       S<[ B<-C [I<number/list>] >]>
+       S<[ B<-P> ]>
+       S<[ B<-S> ]>
+       S<[ B<-x>[I<dir>] ]>
+       S<[ B<-i>[I<extension>] ]>
+       S<[ B<-e> I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+
+If you're new to Perl, you should start with L<perlintro>, which is a 
+general intro for beginners and provides some background to help you
+navigate the rest of Perl's extensive documentation.
+
+For ease of access, the Perl manual has been split up into several sections.
+
+=head2 Overview

 
     perl               Perl overview (this section)
 
     perl               Perl overview (this section)

-    perlfaq            Perl frequently asked questions
+    perlintro          Perl introduction for beginners

     perltoc            Perl documentation table of contents
     perltoc            Perl documentation table of contents

-    perlbook           Perl book information

 
 

-    perlsyn            Perl syntax
-    perldata           Perl data structures
-    perlop             Perl operators and precedence
-    perlsub            Perl subroutines
-    perlfunc           Perl builtin functions
+=head2 Tutorials
+

     perlreftut         Perl references short introduction
     perldsc            Perl data structures intro
     perlreftut         Perl references short introduction
     perldsc            Perl data structures intro

-    perlrequick                Perl regular expressions quick start
-    perlpod            Perl plain old documentation
+    perllol            Perl data structures: arrays of arrays
+
+    perlrequick        Perl regular expressions quick start
+    perlretut          Perl regular expressions tutorial
+
+    perlboot           Perl OO tutorial for beginners
+    perltoot           Perl OO tutorial, part 1
+    perltooc           Perl OO tutorial, part 2
+    perlbot            Perl OO tricks and examples
+

     perlstyle          Perl style guide
     perlstyle          Perl style guide

+
+    perlcheat          Perl cheat sheet

     perltrap           Perl traps for the unwary
     perltrap           Perl traps for the unwary

+    perldebtut         Perl debugging tutorial

 
 

+    perlfaq            Perl frequently asked questions
+      perlfaq1         General Questions About Perl
+      perlfaq2         Obtaining and Learning about Perl
+      perlfaq3         Programming Tools
+      perlfaq4         Data Manipulation
+      perlfaq5         Files and Formats
+      perlfaq6         Regexes
+      perlfaq7         Perl Language Issues
+      perlfaq8         System Interaction
+      perlfaq9         Networking
+
+=head2 Reference Manual
+
+    perlsyn            Perl syntax
+    perldata           Perl data structures
+    perlop             Perl operators and precedence
+    perlsub            Perl subroutines
+    perlfunc           Perl built-in functions
+      perlopentut      Perl open() tutorial
+      perlpacktut      Perl pack() and unpack() tutorial
+    perlpod            Perl plain old documentation
+    perlpodspec        Perl plain old documentation format specification

     perlrun            Perl execution and options
     perldiag           Perl diagnostic messages
     perlrun            Perl execution and options
     perldiag           Perl diagnostic messages

-    perllexwarn                Perl warnings and their control
-    perldebtut         Perl debugging tutorial
+    perllexwarn        Perl warnings and their control

     perldebug          Perl debugging
     perldebug          Perl debugging

-

     perlvar            Perl predefined variables
     perlvar            Perl predefined variables

-    perllol            Perl data structures: arrays of arrays
-    perlopentut                Perl open() tutorial
-    perlretut          Perl regular expressions tutorial
-

     perlre             Perl regular expressions, the rest of the story
     perlre             Perl regular expressions, the rest of the story

+    perlreref          Perl regular expressions quick reference

     perlref            Perl references, the rest of the story
     perlref            Perl references, the rest of the story

-

     perlform           Perl formats
     perlform           Perl formats

-
-    perlboot           Perl OO tutorial for beginners
-    perltoot           Perl OO tutorial, part 1
-    perltooc           Perl OO tutorial, part 2

     perlobj            Perl objects
     perlobj            Perl objects

-    perlbot            Perl OO tricks and examples

     perltie            Perl objects hidden behind simple variables
     perltie            Perl objects hidden behind simple variables

+      perldbmfilter    Perl DBM filters

 
     perlipc            Perl interprocess communication
     perlfork           Perl fork() information
     perlnumber         Perl number semantics
 
     perlthrtut         Perl threads tutorial
 
     perlipc            Perl interprocess communication
     perlfork           Perl fork() information
     perlnumber         Perl number semantics
 
     perlthrtut         Perl threads tutorial

-    perlothrtut                Perl old threads tutorial
+      perlothrtut      Old Perl threads tutorial

 
     perlport           Perl portability guide
     perllocale         Perl locale support
 
     perlport           Perl portability guide
     perllocale         Perl locale support

-    perlunicode                Perl unicode support
+    perluniintro       Perl Unicode introduction
+    perlunicode        Perl Unicode support

     perlebcdic         Considerations for running Perl on EBCDIC platforms
 
     perlsec            Perl security
 
     perlmod            Perl modules: how they work
     perlebcdic         Considerations for running Perl on EBCDIC platforms
 
     perlsec            Perl security
 
     perlmod            Perl modules: how they work

-    perlmodinstall     Perl modules: how to install from CPAN

     perlmodlib         Perl modules: how to write and use
     perlmodstyle       Perl modules: how to write modules with style
     perlmodlib         Perl modules: how to write and use
     perlmodstyle       Perl modules: how to write modules with style

+    perlmodinstall     Perl modules: how to install from CPAN

     perlnewmod         Perl modules: preparing a new module for distribution
 
     perlnewmod         Perl modules: preparing a new module for distribution
 

-    perlfaq1           General Questions About Perl
-    perlfaq2           Obtaining and Learning about Perl
-    perlfaq3           Programming Tools
-    perlfaq4           Data Manipulation
-    perlfaq5           Files and Formats
-    perlfaq6           Regexes
-    perlfaq7           Perl Language Issues
-    perlfaq8           System Interaction
-    perlfaq9           Networking
+    perlutil           utilities packaged with the Perl distribution
+
+    perlcompile        Perl compiler suite intro
+
+    perlfilter         Perl source filters

 
 

-    perlcompile                Perl compiler suite intro
+    perlglossary       Perl Glossary
+
+=head2 Internals and C Language Interface

 
     perlembed          Perl ways to embed perl in your C or C++ application
 
     perlembed          Perl ways to embed perl in your C or C++ application

-    perldebguts                Perl debugging guts and tips
+    perldebguts        Perl debugging guts and tips

     perlxstut          Perl XS tutorial
     perlxs             Perl XS application programming interface
     perlclib           Internal replacements for standard C library functions
     perlguts           Perl internal functions for those doing extensions
     perlcall           Perl calling conventions from C
     perlxstut          Perl XS tutorial
     perlxs             Perl XS application programming interface
     perlclib           Internal replacements for standard C library functions
     perlguts           Perl internal functions for those doing extensions
     perlcall           Perl calling conventions from C

-    perlutil           utilities packaged with the Perl distribution
-    perlfilter         Perl source filters
-    perldbmfilter      Perl DBM filters
+

     perlapi            Perl API listing (autogenerated)
     perlintern         Perl internal functions (autogenerated)
     perliol            C API for Perl's implementation of IO in Layers
     perlapio           Perl internal IO abstraction interface
     perlapi            Perl API listing (autogenerated)
     perlintern         Perl internal functions (autogenerated)
     perliol            C API for Perl's implementation of IO in Layers
     perlapio           Perl internal IO abstraction interface

-    perltodo           Perl things to do
+

     perlhack           Perl hackers guide
 
     perlhack           Perl hackers guide
 

+=head2 Miscellaneous
+
+    perlbook           Perl book information
+    perltodo           Perl things to do
+
+    perldoc            Look up Perl documentation in Pod format
+

     perlhist           Perl history records
     perldelta          Perl changes since previous version
     perlhist           Perl history records
     perldelta          Perl changes since previous version

+    perl593delta       Perl changes in version 5.9.3
+    perl592delta       Perl changes in version 5.9.2
+    perl591delta       Perl changes in version 5.9.1
+    perl590delta       Perl changes in version 5.9.0
+    perl588delta       Perl changes in version 5.8.8
+    perl587delta       Perl changes in version 5.8.7
+    perl586delta       Perl changes in version 5.8.6
+    perl585delta       Perl changes in version 5.8.5
+    perl584delta       Perl changes in version 5.8.4
+    perl583delta       Perl changes in version 5.8.3
+    perl582delta       Perl changes in version 5.8.2
+    perl581delta       Perl changes in version 5.8.1
+    perl58delta        Perl changes in version 5.8.0
+    perl573delta       Perl changes in version 5.7.3

     perl572delta       Perl changes in version 5.7.2
     perl571delta       Perl changes in version 5.7.1
     perl570delta       Perl changes in version 5.7.0
     perl572delta       Perl changes in version 5.7.2
     perl571delta       Perl changes in version 5.7.1
     perl570delta       Perl changes in version 5.7.0

-    perl56delta                Perl changes in version 5.6
+    perl561delta       Perl changes in version 5.6.1
+    perl56delta        Perl changes in version 5.6

     perl5005delta      Perl changes in version 5.005
     perl5004delta      Perl changes in version 5.004
 
     perl5005delta      Perl changes in version 5.005
     perl5004delta      Perl changes in version 5.004
 

+    perlartistic       Perl Artistic License
+    perlgpl            GNU General Public License
+
+=head2 Language-Specific
+
+    perlcn             Perl for Simplified Chinese (in EUC-CN)
+    perljp             Perl for Japanese (in EUC-JP)
+    perlko             Perl for Korean (in EUC-KR)
+    perltw             Perl for Traditional Chinese (in Big5)
+
+=head2 Platform-Specific
+

     perlaix            Perl notes for AIX
     perlamiga          Perl notes for AmigaOS
     perlapollo         Perl notes for Apollo DomainOS
     perlaix            Perl notes for AIX
     perlamiga          Perl notes for AmigaOS
     perlapollo         Perl notes for Apollo DomainOS


@@ -122,27 +183,32 @@ For ease of access, the Perl manual has been split up into several sections:
     perldgux           Perl notes for DG/UX
     perldos            Perl notes for DOS
     perlepoc           Perl notes for EPOC
     perldgux           Perl notes for DG/UX
     perldos            Perl notes for DOS
     perlepoc           Perl notes for EPOC

+    perlfreebsd        Perl notes for FreeBSD

     perlhpux           Perl notes for HP-UX
     perlhurd           Perl notes for Hurd
     perlhpux           Perl notes for HP-UX
     perlhurd           Perl notes for Hurd

-    perlmachten                Perl notes for Power MachTen
+    perlirix           Perl notes for Irix
+    perllinux          Perl notes for Linux
+    perlmachten        Perl notes for Power MachTen

     perlmacos          Perl notes for Mac OS (Classic)
     perlmacos          Perl notes for Mac OS (Classic)

+    perlmacosx         Perl notes for Mac OS X

     perlmint           Perl notes for MiNT
     perlmpeix          Perl notes for MPE/iX
     perlmint           Perl notes for MiNT
     perlmpeix          Perl notes for MPE/iX

-    perlnetware                Perl notes for NetWare
+    perlnetware        Perl notes for NetWare
+    perlopenbsd        Perl notes for OpenBSD

     perlos2            Perl notes for OS/2
     perlos390          Perl notes for OS/390
     perlos2            Perl notes for OS/2
     perlos390          Perl notes for OS/390

+    perlos400          Perl notes for OS/400

     perlplan9          Perl notes for Plan 9
     perlqnx            Perl notes for QNX
     perlsolaris        Perl notes for Solaris
     perlplan9          Perl notes for Plan 9
     perlqnx            Perl notes for QNX
     perlsolaris        Perl notes for Solaris

+    perlsymbian        Perl notes for Symbian

     perltru64          Perl notes for Tru64
     perltru64          Perl notes for Tru64

-    perluts             Perl notes for UTS
+    perluts            Perl notes for UTS

     perlvmesa          Perl notes for VM/ESA
     perlvms            Perl notes for VMS
     perlvos            Perl notes for Stratus VOS
     perlwin32          Perl notes for Windows
 
     perlvmesa          Perl notes for VM/ESA
     perlvms            Perl notes for VMS
     perlvos            Perl notes for Stratus VOS
     perlwin32          Perl notes for Windows
 

-(If you're intending to read these straight through for the first time,
-the suggested order will tend to reduce the number of forward references.)

 
 By default, the manpages listed above are installed in the 
 F</usr/local/man/> directory.  
 
 By default, the manpages listed above are installed in the 
 F</usr/local/man/> directory.  


@@ -229,7 +295,8 @@ L<perlguts>, and L<xsubpp>.
 
 =item *
 
 
 =item *
 

-roll-your-own magic variables (including multiple simultaneous DBM implementations)
+roll-your-own magic variables (including multiple simultaneous DBM
+implementations)

 
 Described in L<perltie> and L<AnyDBM_File>.
 
 
 Described in L<perltie> and L<AnyDBM_File>.
 


@@ -249,25 +316,20 @@ Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
 
 object-oriented programming
 
 
 object-oriented programming
 

-Described in L<perlobj>, L<perltoot>, and L<perlbot>.
-
-=item *
-
-compilability into C code or Perl bytecode
-
-Described in L<B> and L<B::Bytecode>.
+Described in L<perlobj>, L<perlboot>, L<perltoot>, L<perltooc>,
+and L<perlbot>.

 
 =item *
 
 support for light-weight processes (threads)
 
 
 =item *
 
 support for light-weight processes (threads)
 

-Described in L<perlthrtut> and L<Thread>.
+Described in L<perlthrtut> and L<threads>.

 
 =item *
 
 
 =item *
 

-support for internationalization, localization, and Unicode 
+support for Unicode, internationalization, and localization

 
 

-Described in L<perllocale> and L<utf8>.
+Described in L<perluniintro>, L<perllocale> and L<Locale::Maketext>.

 
 =item *
 
 
 =item *
 


@@ -286,7 +348,7 @@ Described in L<perlre>, with additional examples in L<perlop>.
 enhanced debugger and interactive Perl environment,
 with integrated editor support
 
 enhanced debugger and interactive Perl environment,
 with integrated editor support
 

-Described in L<perldebug>.
+Described in L<perldebtut>, L<perldebug> and L<perldebguts>.

 
 =item *
 
 
 =item *
 


@@ -326,8 +388,10 @@ Perl developers, please write to perl-thanks@perl.org .
  a2p   awk to perl translator
  s2p   sed to perl translator
 
  a2p   awk to perl translator
  s2p   sed to perl translator
 

- http://www.perl.com/      the Perl Home Page
- http://www.perl.com/CPAN   the Comprehensive Perl Archive
+ http://www.perl.org/       the Perl homepage
+ http://www.perl.com/       Perl articles (O'Reilly)
+ http://www.cpan.org/       the Comprehensive Perl Archive
+ http://www.pm.org/         the Perl Mongers

 
 =head1 DIAGNOSTICS
 
 
 =head1 DIAGNOSTICS