Integrate:

author Nicholas Clark <nick@ccl4.org>

Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)

committer Nicholas Clark <nick@ccl4.org>

Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)
author Nicholas Clark <nick@ccl4.org>
Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)
committer Nicholas Clark <nick@ccl4.org>
Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)
diff --git a/README.solaris b/README.solaris

index e1590d1..a8b32e0 100644 (file)
--- a/README.solaris
+++ b/README.solaris
@@ -26,11 +26,15 @@ install it under a different prefix from /usr/perl5.  Common prefixes
  to use are /usr/local and /opt/perl.
  
  You may wish to put your version of perl in the PATH of all users by
-changing the link /usr/bin/perl.  This is OK, as all perl scripts
-shipped with Solaris use an explicit path.  Solaris ships with a
-range of Solaris-specific modules.  If you choose to install your own
-version of perl you will find the source of many of these modules is
-available on CPAN under the Sun::Solaris:: namespace.
+changing the link /usr/bin/perl.  This is probably OK, as most perl
+scripts shipped with Solaris use an explicit path.  (There are a few
+exceptions, such as /usr/bin/rpm2cpio and /etc/rcm/scripts/README, but
+these are also sufficiently generic that the actual version of perl
+probably doesn't matter too much.)
+
+Solaris ships with a range of Solaris-specific modules.  If you choose
+to install your own version of perl you will find the source of many of
+these modules is available on CPAN under the Sun::Solaris:: namespace.
  
  Solaris may include two versions of perl, e.g. Solaris 9 includes
  both 5.005_03 and 5.6.1.  This is to provide stability across Solaris
@@ -587,7 +591,10 @@ software products, for example the Sun WebServer, which is part of
  the Solaris Server Intranet Extension, or the Sun Directory Services,
  part of Solaris for ISPs) or download the ANDIrand package from
  L<http://www.cosy.sbg.ac.at/~andi/>. If you use SUNWski, make a
-symbolic link /dev/urandom pointing to /dev/random.
+symbolic link /dev/urandom pointing to /dev/random.  For more details,
+see Document ID27606 entitled "Differing /dev/random support requirements
+within Solaris[TM] Operating Environments", available at
+http://sunsolve.sun.com .
  
  It may be possible to use the Entropy Gathering Daemon (written in
  Perl!), available from L<http://www.lothar.com/tech/crypto/>.
diff --git a/README.win32 b/README.win32

index 1e52ab8..0163441 100644 (file)
--- a/README.win32
+++ b/README.win32
@@ -41,13 +41,18 @@ additional software to run (other than what came with your operating
  system).  Currently, this port is capable of using one of the
  following compilers on the Intel x86 architecture:
  
-      Borland C++              version 5.02 or later
-      Microsoft Visual C++     version 4.2 or later
-      MinGW with gcc           gcc version 2.95.2 or later
+      Borland C++           version 5.02 or later
+      Microsoft Visual C++  version 4.2 or later
+      MinGW with gcc        gcc version 2.95.2 or later
  
  The last of these is a high quality freeware compiler.  Use version
  3.2.x or later for the best results with this compiler.
  
+The Microsoft Visual C++ compiler is also now being given away free in
+the "Visual C++ Toolkit 2003", and also as part of the ".NET Framework
+SDK".  This is the same compiler that ships with "Visual Studio .NET 2003
+Professional".
+
  This port can also be built on the Intel IA64 using:
  
        Microsoft Platform SDK   Nov 2001 (64-bit compiler and tools)
@@ -122,7 +127,8 @@ See L</"Make"> above.
  
  The nmake that comes with Visual C++ will suffice for building.
  You will need to run the VCVARS32.BAT file, usually found somewhere
-like C:\MSDEV4.2\BIN.  This will set your build environment.
+like C:\MSDEV4.2\BIN or C:\Program Files\Microsoft Visual Studio\VC98\Bin.
+This will set your build environment.
  
  You can also use dmake to build using Visual C++; provided, however,
  you set OSRELEASE to "microsft" (or whatever the directory name
@@ -131,6 +137,84 @@ and edit win32/config.vc to change "make=nmake" into "make=dmake".  The
  latter step is only essential if you want to use dmake as your default
  make for building extensions using MakeMaker.
  
+=item Microsoft Visual C++ Toolkit 2003
+
+This free toolkit contains the same compiler and linker that ship with
+Visual Studio .NET 2003 Professional, but doesn't contain everything
+necessary to build Perl.
+
+You will also need to download the "Platform SDK" (the "Core SDK" and "MDAC
+SDK" components are required) for header files, libraries and rc.exe, and
+".NET Framework SDK" for more libraries and nmake.exe.  Note that the latter
+(which also includes the free compiler and linker) requires the ".NET
+Framework Redistributable" to be installed first.  This can be downloaded and
+installed separately, but is included in the "Visual C++ Toolkit 2003" anyway.
+
+These packages can all be downloaded by searching in the Download Center at
+http://www.microsoft.com/downloads/search.aspx?displaylang=en
+
+Note that the "Platform SDK February 2003" download requires Internet Explorer
+5.0 to function.  Alternatively, the very latest version at the time of writing
+(called "Windows XP Service Pack 2 Platform SDK RC2") is now available as an
+ISO-9660 CD image file and does not require IE5 to be downloaded but will only
+work on Windows XP.
+
+According to the download pages the Toolkit and the .NET Framework SDK are only
+supported on Windows 2000/XP/2003, so trying to use these tools on Windows
+95/98/ME and even Windows NT probably won't work.
+
+Install the Toolkit first, then the Platform SDK, then the .NET Framework SDK.
+Setup your environment as follows (assuming default installation locations
+were chosen):
+
+       SET PATH=%SystemRoot%\system32;%SystemRoot%;C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin;C:\Program Files\Microsoft SDK\Bin;C:\Program Files\Microsoft.NET\SDK\v1.1\Bin
+       SET INCLUDE=C:\Program Files\Microsoft Visual C++ Toolkit 2003\include;C:\Program Files\Microsoft SDK\include;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include
+       SET LIB=C:\Program Files\Microsoft Visual C++ Toolkit 2003\lib;C:\Program Files\Microsoft SDK\lib;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
+
+Several required files will still be missing:
+
+=over 4
+
+=item *
+
+cvtres.exe is required by link.exe when using a .res file.  It is actually
+installed by the .NET Framework SDK, but into a location such as the
+following:
+
+       C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322
+
+Copy it from there to C:\Program Files\Microsoft SDK\Bin
+
+=item *
+
+lib.exe is normally used to build libraries, but link.exe with the /lib
+option also works, so create a batch file called lib.bat in
+C:\Program Files\Microsoft Visual C++ Toolkit 2003\bin containing:
+
+       @echo off
+       link /lib %*
+
+This will work as long as "lib.exe" is invoked simply as "lib" (which it is
+during the Perl build process).
+
+=item *
+
+setargv.obj is required to build perlglob.exe (and perl.exe if the USE_SETARGV
+option is enabled).  The Platform SDK supplies this object file in source form
+in C:\Program Files\Microsoft SDK\src\crt.  Copy setargv.c, cruntime.h and
+internal.h from there to some temporary location and build setargv.obj using
+
+       cl.exe /c /I. /D_CRTBLD setargv.c
+
+Then copy setargv.obj to C:\Program Files\Microsoft SDK\lib
+
+=back
+
+Perl should now build using the win32/Makefile.  You will need to edit that
+file to comment-out CCTYPE = MSVC60 (since that enables delay-loading of the
+Winsock DLL which the free toolkit does not support) and to set CCHOME,
+CCINCDIR and CCLIBDIR as per the environment setup above.
+
  =item Microsoft Platform SDK 64-bit Compiler
  
  The nmake that comes with the Platform SDK will suffice for building
@@ -139,8 +223,8 @@ shells available after you install the Platform SDK from the Start Menu.
  
  =item MinGW release 3 with gcc
  
-The latest release of MinGW at the time of writing is 3.1.0, which comes 
-with gcc-3.2.3, and can be downloaded here:
+The latest release of MinGW at the time of writing is 3.1.0, which contains 
+gcc-3.2.3.  It can be downloaded here:
  
      http://www.mingw.org/
  
@@ -151,7 +235,7 @@ You also need dmake.  See L</"Make"> above on how to get it.
  
  =item MinGW release 1 with gcc
  
-The MinGW-1.1 bundle comes with gcc-2.95.3.
+The MinGW-1.1 bundle contains gcc-2.95.3.
  
  Make sure you install the binaries that work with MSVCRT.DLL as indicated
  in the README for the GCC bundle.  You may need to set up a few environment
@@ -197,8 +281,7 @@ Make sure you are in the "win32" subdirectory under the perl toplevel.
  This directory contains a "Makefile" that will work with
  versions of nmake that come with Visual C++ or the Platform SDK, and
  a dmake "makefile.mk" that will work for all supported compilers.  The
-defaults in the dmake makefile are setup to build using Microsoft Visual
-C++ 6.0 or newer.
+defaults in the dmake makefile are setup to build using MinGW/gcc.
  
  =item *
  
@@ -224,7 +307,7 @@ If you have either the source or a library that contains des_fcrypt(),
  enable the appropriate option in the makefile.  A ready-to-use version
  of fcrypt.c, based on the version originally written by Eric Young at
  ftp://ftp.funet.fi/pub/crypt/mirrors/dsi/libdes/, is bundled with the
-distribution. Set CRYPT_SRC to fcrypt.c to use this version.
+distribution and CRYPT_SRC is set to use it.
  Alternatively, if you have built a library that contains des_fcrypt(),
  you can set CRYPT_LIB to point to the library name.
  Perl will also build without des_fcrypt(), but the crypt() builtin will
@@ -301,19 +384,20 @@ Please report any other failures as described under L<BUGS AND CAVEATS>.
  Type "dmake install" (or "nmake install").  This will put the newly
  built perl and the libraries under whatever C<INST_TOP> points to in the
  Makefile.  It will also install the pod documentation under
-C<$INST_TOP\$VERSION\lib\pod> and HTML versions of the same under
-C<$INST_TOP\$VERSION\lib\pod\html>.  To use the Perl you just installed,
-you will need to add two components to your PATH environment variable,
-C<$INST_TOP\$VERSION\bin> and C<$INST_TOP\$VERSION\bin\$ARCHNAME>.
-For example:
+C<$INST_TOP\$INST_VER\lib\pod> and HTML versions of the same under
+C<$INST_TOP\$INST_VER\lib\pod\html>.
  
-    set PATH c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
+To use the Perl you just installed you will need to add a new entry to
+your PATH environment variable: C<$INST_TOP\bin>, e.g.
  
-If you opt to comment out INST_VER and INST_ARCH in the makefiles, the
-installation structure is much simpler.  In that case, it will be
-sufficient to add a single entry to the path, for instance:
+    set PATH=c:\perl\bin;%PATH%
  
-    set PATH c:\perl\bin;%PATH%
+If you opted to uncomment C<INST_VER> and C<INST_ARCH> in the makefile
+then the installation structure is a little more complicated and you will
+need to add two new PATH components instead: C<$INST_TOP\$INST_VER\bin> and
+C<$INST_TOP\$INST_VER\bin\$ARCHNAME>, e.g.
+
+    set PATH=c:\perl\5.6.0\bin;c:\perl\5.6.0\bin\MSWin32-x86;%PATH%
  
  =head2 Usage Hints for Perl on Win32
  
@@ -394,7 +478,7 @@ enclosing the whole argument within double quotes.  The backslash and
  the pair of double quotes surrounding the argument will be stripped by
  the C runtime.
  
-The file redirection characters "<", ">", and "|" can be quoted by
+The file redirection characters "E<lt>", "E<gt>", and "|" can be quoted by
  double quotes (although there are suggestions that this may not always
  be true).  Single quotes are not treated as quotes by the shell or
  the C runtime, they don't get stripped by the shell (just to make
@@ -574,11 +658,11 @@ cannot be built using the generic steps shown in the previous section.
  
  To ensure smooth transitioning of existing code that uses the
  ActiveState port, there is a bundle of Win32 extensions that contains
-all of the ActiveState extensions and most other Win32 extensions from
+all of the ActiveState extensions and several other Win32 extensions from
  CPAN in source form, along with many added bugfixes, and with MakeMaker
  support.  This bundle is available at:
  
-   http://www.cpan.org/authors/id/GSAR/libwin32-0.18.zip
+   http://www.cpan.org/modules/by-module/Win32/libwin32-0.191.zip
  
  See the README in that distribution for building and installation
  instructions.  Look for later versions that may be available at the
@@ -603,6 +687,8 @@ binaries transparently.  This means that you could use a 32-bit build
  of Perl on a 64-bit system.  Given this, why would one want to build
  a 64-bit build of Perl?  Here are some reasons why you would bother:
  
+=over
+
  =item *
  
  A 64-bit native application will run much more efficiently on
@@ -623,6 +709,8 @@ Embedding Perl inside a 64-bit application.
  
  =back
  
+=back
+
  =head2 Running Perl Scripts
  
  Perl scripts on UNIX use the "#!" (a.k.a "shebang") line to
@@ -691,7 +779,9 @@ Here's a diversion:  copy "runperl.bat" to "runperl", and type
  "runperl".  Explain the observed behavior, or lack thereof. :)
  Hint: .gnidnats llits er'uoy fi ,"lrepnur" eteled :tniH
  
-=item Miscellaneous Things
+=back
+
+=head2 Miscellaneous Things
  
  A full set of HTML documentation is installed, so you should be
  able to use it if you have a web browser installed on your
@@ -716,8 +806,6 @@ If you find bugs in perl, you can run C<perlbug> to create a
  bug report (you may have to send it manually if C<perlbug> cannot
  find a mailer on your system).
  
-=back
-
  =head1 BUGS AND CAVEATS
  
  Norton AntiVirus interferes with the build process, particularly if 
@@ -738,7 +826,7 @@ Some of the built-in functions do not act exactly as documented in
  L<perlfunc>, and a few are not implemented at all.  To avoid
  surprises, particularly if you have had prior exposure to Perl
  in other operating environments or if you intend to write code
-that will be portable to other environments.  See L<perlport>
+that will be portable to other environments, see L<perlport>
  for a reasonably definitive list of these differences.
  
  Not all extensions available from CPAN may build or work properly
@@ -756,8 +844,8 @@ variable in the handler.  Using signals under this port should
  currently be considered unsupported.
  
  Please send detailed descriptions of any problems and solutions that 
-you may find to <F<perlbug@perl.com>>, along with the output produced
-by C<perl -V>.
+you may find to E<lt>F<perlbug@perl.org>E<gt>, along with the output
+produced by C<perl -V>.
  
  =head1 ACKNOWLEDGEMENTS
  
@@ -801,6 +889,6 @@ Win9x support was added in 5.6 (Benjamin Stuhl).
  
  Support for 64-bit Windows added in 5.8 (ActiveState Corp).
  
-Last updated: 20 April 2002
+Last updated: 30 July 2004
  
  =cut
diff --git a/lib/bigint.pm b/lib/bigint.pm

index 73923ee..69f80a2 100644 (file)
--- a/lib/bigint.pm
+++ b/lib/bigint.pm
@@ -197,7 +197,7 @@ bigint - Transparent BigInteger support for Perl
  
  =head1 SYNOPSIS
  
-  use bignt;
+  use bigint;
  
    $x = 2 + 4.5,"\n";                   # BigInt 6
    print 2 ** 512,"\n";                 # really is what you think it is
diff --git a/lib/overload.pm b/lib/overload.pm

index 6fc69d6..aa2f383 100644 (file)
--- a/lib/overload.pm
+++ b/lib/overload.pm
@@ -704,7 +704,10 @@ Package C<overload.pm> provides the following public functions:
  
  =item overload::StrVal(arg)
  
-Gives string value of C<arg> as in absence of stringify overloading.
+Gives string value of C<arg> as in absence of stringify overloading. If you
+are using this to get the address of a reference (useful for checking if two
+references point to the same thing) then you may be better off using
+C<Scalar::Util::refaddr()>, which is faster.
  
  =item overload::Overloaded(arg)
  
diff --git a/pod/perldiag.pod b/pod/perldiag.pod

index cf73cf8..4654d60 100644 (file)
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -783,6 +783,16 @@ usually double the curlies to get the same effect though, because the
  inner curlies will be considered a block that loops once.  See
  L<perlfunc/last>.
  
+=item Can't load '%s' for module %s
+
+(F) The module you tried to load failed to load a dynamic extension. This
+may either mean that you upgraded your version of perl to one that is
+incompatible with your old dynamic extensions (which is known to happen
+between major versions of perl), or (more likely) that your dynamic
+extension was built against an older version of the library that is
+installed on your system. You may need to rebuild your old dynamic
+extensions.
+
  =item Can't localize lexical variable %s
  
  (F) You used local on a variable name that was previously declared as a
@@ -821,6 +831,12 @@ autoload, but there is no function to autoload.  Most probable causes
  are a misprint in a function/method name or a failure to C<AutoSplit>
  the file, say, by doing C<make install>.
  
+=item Can't locate loadable object for module %s in @INC
+
+(F) The module you loaded is trying to load an external library, like
+for example, C<foo.so> or C<bar.dll>, but the L<DynaLoader> module was
+unable to locate this library.  See L<DynaLoader>.
+
  =item Can't locate object method "%s" via package "%s"
  
  (F) You called a method correctly, and it correctly indicated a package
@@ -2608,6 +2624,11 @@ C<limit datasize n> (where C<n> is the number of kilobytes) to check
  the current limits and change them, and in ksh/bash/zsh use C<ulimit -a>
  and C<ulimit -d n>, respectively.
  
+=item Out of memory during %s extend
+
+(X) An attempt was made to extend an array, a list, or a string beyond
+the largest possible memory allocation.
+
  =item Out of memory during "large" request for %s
  
  (F) The malloc() function returned 0, indicating there was insufficient
@@ -2615,11 +2636,6 @@ remaining memory (or virtual memory) to satisfy the request. However,
  the request was judged large enough (compile-time default is 64K), so a
  possibility to shut down by trapping this error is granted.
  
-=item Out of memory during %s extend
-
-(X) An attempt was made to extend an array, a list, or a string beyond
-the largest possible memory allocation.
-
  =item Out of memory during request for %s
  
  (X|F) The malloc() function returned 0, indicating there was
@@ -3635,22 +3651,6 @@ before now.  Check your control flow.
  (F) Perl can't peek at the stdio buffer of filehandles when it doesn't
  know about your kind of stdio.  You'll have to use a filename instead.
  
-=item "-T" is on the #! line, it must also be used on the command line
-
-(X) The #! line (or local equivalent) in a Perl script contains the
-B<-T> option, but Perl was not invoked with B<-T> in its command line.
-This is an error because, by the time Perl discovers a B<-T> in a
-script, it's too late to properly taint everything from the environment.
-So Perl gives up.
-
-If the Perl script is being executed as a command using the #!
-mechanism (or its local equivalent), this error can usually be fixed by
-editing the #! line so that the B<-T> option is a part of Perl's first
-argument: e.g. change C<perl -n -T> to C<perl -T -n>.
-
-If the Perl script is being executed as C<perl scriptname>, then the
-B<-T> option must appear on the command line: C<perl -T scriptname>.
-
  =item Target of goto is too deeply nested
  
  (F) You tried to use C<goto> to reach a label that was too deeply nested
@@ -3728,6 +3728,22 @@ see L<perl58delta> for more details.
  (F) Your version of the C library apparently doesn't do times().  I
  suspect you're not running on Unix.
  
+=item "-T" is on the #! line, it must also be used on the command line
+
+(X) The #! line (or local equivalent) in a Perl script contains the
+B<-T> option, but Perl was not invoked with B<-T> in its command line.
+This is an error because, by the time Perl discovers a B<-T> in a
+script, it's too late to properly taint everything from the environment.
+So Perl gives up.
+
+If the Perl script is being executed as a command using the #!
+mechanism (or its local equivalent), this error can usually be fixed by
+editing the #! line so that the B<-T> option is a part of Perl's first
+argument: e.g. change C<perl -n -T> to C<perl -T -n>.
+
+If the Perl script is being executed as C<perl scriptname>, then the
+B<-T> option must appear on the command line: C<perl -T scriptname>.
+
  =item To%s: illegal mapping '%s'
  
  (F) You tried to define a customized To-mapping for lc(), lcfirst,
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod

index b23b8f6..127c789 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -5877,11 +5877,9 @@ tell() on pipes, fifos, and sockets usually returns -1.
  
  There is no C<systell> function.  Use C<sysseek(FH, 0, 1)> for that.
  
-Do not use tell() on a filehandle that has been opened using
-sysopen(), use sysseek() for that as described above.  Why?  Because
-sysopen() creates unbuffered, "raw", filehandles, while open() creates
-buffered filehandles.  sysseek() make sense only on the first kind,
-tell() only makes sense on the second kind.
+Do not use tell() (or other buffered I/O operations) on a file handle
+that has been manipulated by sysread(), syswrite() or sysseek().
+Those functions ignore the buffering, while tell() does not.
  
  =item telldir DIRHANDLE
  
diff --git a/pod/perlhack.pod b/pod/perlhack.pod

index 0d7581c..3b360a6 100644 (file)
--- a/pod/perlhack.pod
+++ b/pod/perlhack.pod
@@ -38,12 +38,14 @@ releases of Perl are shepherded by a ``pumpking'', a porter
  responsible for gathering patches, deciding on a patch-by-patch
  feature-by-feature basis what will and will not go into the release.
  For instance, Gurusamy Sarathy was the pumpking for the 5.6 release of
-Perl, and Jarkko Hietaniemi is the pumpking for the 5.8 release, and
-Hugo van der Sanden will be the pumpking for the 5.10 release.
+Perl, and Jarkko Hietaniemi was the pumpking for the 5.8 release, and
+Hugo van der Sanden and Rafael Garcia-Suarez share the pumpking for
+the 5.10 release.
  
  In addition, various people are pumpkings for different things.  For
-instance, Andy Dougherty and Jarkko Hietaniemi share the I<Configure>
-pumpkin.
+instance, Andy Dougherty and Jarkko Hietaniemi did a grand job as the
+I<Configure> pumpkin up till the 5.8 release. For the 5.10 release
+H.Merijn Brand took over.
  
  Larry sees Perl development along the lines of the US government:
  there's the Legislature (the porters), the Executive branch (the
diff --git a/pod/perlintro.pod b/pod/perlintro.pod

index 7429dfb..cb115ec 100644 (file)
--- a/pod/perlintro.pod
+++ b/pod/perlintro.pod
@@ -560,7 +560,7 @@ The results end up in C<$1>, C<$2> and so on.
  
      # a cheap and nasty way to break an email address up into parts
  
-    if ($email =~ /([^@])+@(.+)/) {
+    if ($email =~ /([^@]+)@(.+)/) {
          print "Username is $1\n";
          print "Hostname is $2\n";
      }
diff --git a/pod/perlnewmod.pod b/pod/perlnewmod.pod

index 642d005..d8bd400 100644 (file)
--- a/pod/perlnewmod.pod
+++ b/pod/perlnewmod.pod
@@ -73,9 +73,10 @@ want to do in advance.
  
  Dig into a bunch of modules to see how they're written. I'd suggest
  starting with L<Text::Tabs|Text::Tabs>, since it's in the standard
-library and is nice and simple, and then looking at something like
-L<Time::Zone|Time::Zone>, L<File::Copy|File::Copy> and then some of the
-C<Mail::*> modules if you're planning on writing object oriented code.
+library and is nice and simple, and then looking at something a little
+more complex like L<File::Copy|File::Copy>.  For object oriented
+code, C<WWW::Mechanize> or the C<Email::*> modules provide some good
+examples.
  
  These should give you an overall feel for how modules are laid out and
  written.
@@ -84,8 +85,8 @@ written.
  
  There are a lot of modules on CPAN, and it's easy to miss one that's
  similar to what you're planning on contributing. Have a good plough
-through the modules list and the F<by-module> directories, and make sure
-you're not the one reinventing the wheel!
+through the L<http://search.cpan.org> and make sure you're not the one
+reinventing the wheel!
  
  =item Discuss the need
  
@@ -119,18 +120,29 @@ wanted and not currently available, it's time to start coding.
  
  =over 3
  
-=item Start with F<h2xs>
+=item Start with F<module-starter> or F<h2xs>
  
-Originally a utility to convert C header files into XS modules,
-L<h2xs|h2xs> has become a useful utility for churning out skeletons for
-Perl-only modules as well. If you don't want to use the
-L<Autoloader|Autoloader> which splits up big modules into smaller
-subroutine-sized chunks, you'll say something like this:
+The F<module-starter> utility is distributed as part of the
+L<Module::Starter|Module::Starter> CPAN package.  It creates a directory
+with stubs of all the necessary files to start a new module, according
+to recent "best practice" for module development, and is invoked from
+the command line, thus:
  
-    h2xs -AX -n Net::Acme
+    module-starter --module=Foo::Bar \
+       --author="Your Name" --email=yourname@cpan.org
  
-The C<-A> omits the Autoloader code, C<-X> omits XS elements, and C<-n>
-specifies the name of the module.
+If you do not wish to install the L<Module::Starter|Module::Starter>
+package from CPAN, F<h2xs> is an older tool, originally intended for the
+development of XS modules, which comes packaged with the Perl
+distribution. 
+
+A typical invocation of L<h2xs|h2xs> for a pure Perl module is:
+
+    h2xs -AX --skip-exporter --use-new-tests -n Foo::Bar 
+
+The C<-A> omits the Autoloader code, C<-X> omits XS elements,
+C<--skip-exporter> omits the Exporter code, C<--use-new-tests> sets up a
+modern testing environment, and C<-n> specifies the name of the module.
  
  =item Use L<strict|strict> and L<warnings|warnings>
  
@@ -164,10 +176,9 @@ your module at fault.
  
  =item Use L<Exporter|Exporter> - wisely!
  
-C<h2xs> provides stubs for L<Exporter|Exporter>, which gives you a
-standard way of exporting symbols and subroutines from your module into
-the caller's namespace. For instance, saying C<use Net::Acme qw(&frob)>
-would import the C<frob> subroutine.
+L<Exporter|Exporter> gives you a standard way of exporting symbols and
+subroutines from your module into the caller's namespace. For instance,
+saying C<use Net::Acme qw(&frob)> would import the C<frob> subroutine.
  
  The package variable C<@EXPORT> will determine which symbols will get
  exported when the caller simply says C<use Net::Acme> - you will hardly
@@ -180,21 +191,23 @@ export set - look at L<Exporter> for more details.
  
  The work isn't over until the paperwork is done, and you're going to
  need to put in some time writing some documentation for your module.
-C<h2xs> will provide a stub for you to fill in; if you're not sure about
-the format, look at L<perlpod> for an introduction. Provide a good
-synopsis of how your module is used in code, a description, and then
-notes on the syntax and function of the individual subroutines or
-methods. Use Perl comments for developer notes and POD for end-user
-notes.
+C<module-starter> or C<h2xs> will provide a stub for you to fill in; if
+you're not sure about the format, look at L<perlpod> for an
+introduction. Provide a good synopsis of how your module is used in
+code, a description, and then notes on the syntax and function of the
+individual subroutines or methods. Use Perl comments for developer notes
+and POD for end-user notes.
  
  =item Write tests
  
  You're encouraged to create self-tests for your module to ensure it's
  working as intended on the myriad platforms Perl supports; if you upload
  your module to CPAN, a host of testers will build your module and send
-you the results of the tests. Again, C<h2xs> provides a test framework
-which you can extend - you should do something more than just checking
-your module will compile.
+you the results of the tests. Again, C<module-starter> and C<h2xs>
+provide a test framework which you can extend - you should do something
+more than just checking your module will compile.
+L<Test::Simple|Test::Simple> and L<Test::More|Test::More> are good
+places to start when writing a test suite.
  
  =item Write the README
  
@@ -212,15 +225,15 @@ does in detail, and the user-visible changes since the last release.
  
  =item Get a CPAN user ID
  
-Every developer publishing modules on CPAN needs a CPAN ID. See the
-instructions at C<http://www.cpan.org/modules/04pause.html> (or
-equivalent on your nearest mirror) to find out how to do this.
+Every developer publishing modules on CPAN needs a CPAN ID.  Visit
+C<http://pause.perl.org/>, select "Request PAUSE Account", and wait for
+your request to be approved by the PAUSE administrators.
  
  =item C<perl Makefile.PL; make test; make dist>
  
-Once again, C<h2xs> has done all the work for you. It produces the
-standard C<Makefile.PL> you'll have seen when you downloaded and
-installs modules, and this produces a Makefile with a C<dist> target.
+Once again, C<module-starter> or C<h2xs> has done all the work for you.
+They produce the standard C<Makefile.PL> you see when you download and
+install modules, and this produces a Makefile with a C<dist> target.
  
  Once you've ensured that your module passes its own tests - always a
  good thing to make sure - you can C<make dist>, and the Makefile will
@@ -235,31 +248,9 @@ you can upload your module to CPAN.
  =item Announce to the modules list
  
  Once uploaded, it'll sit unnoticed in your author directory. If you want
-it connected to the rest of the CPAN, you'll need to tell the modules
-list about it. The best way to do this is to email them a line in the
-style of the modules list, like this:
-
-  Net::Acme bdpOP   Interface to Acme Frobnicator servers      FOOBAR
-  ^         ^^^^^   ^                                          ^
-  |         |||||   Module description                         Your ID
-  |         ||||| 
-  |         ||||\-Public Licence: (p)standard Perl, (g)GPL, (b)BSD,
-  |         ||||                  (l)LGPL, (a)rtistic, (o)ther
-  |         ||||
-  |         |||\- Interface: (O)OP, (r)eferences, (h)ybrid, (f)unctions
-  |         |||
-  |         ||\-- Language: (p)ure Perl, C(+)+, (h)ybrid, (C), (o)ther
-  |         ||
-  Module    |\--- Support: (d)eveloper, (m)ailing list, (u)senet, (n)one
-  Name      |
-            \---- Development: (i)dea, (c)onstructions, (a)lpha, (b)eta,
-                               (R)eleased, (M)ature, (S)tandard
-
-plus a description of the module and why you think it should be
-included. If you hear nothing back, that means your module will
-probably appear on the modules list at the next update. Don't try
-subscribing to C<modules@perl.org>; it's not another mailing list. Just
-have patience.
+it connected to the rest of the CPAN, you'll need to go to "Register
+Namespace" on PAUSE.  Once registered, your module will appear in the
+by-module and by-category listings on CPAN.
  
  =item Announce to clpa
  
@@ -278,9 +269,12 @@ maintaining a software project...
  
  Simon Cozens, C<simon@cpan.org>
  
+Updated by Kirrily "Skud" Robert, C<skud@cpan.org>
+
  =head1 SEE ALSO
  
  L<perlmod>, L<perlmodlib>, L<perlmodinstall>, L<h2xs>, L<strict>,
-L<Carp>, L<Exporter>, L<perlpod>, L<Test>, L<ExtUtils::MakeMaker>,
+L<Carp>, L<Exporter>, L<perlpod>, L<Test::Simple>, L<Test::More>
+L<ExtUtils::MakeMaker>, L<Module::Build>, L<Module::Starter>
  http://www.cpan.org/ , Ken Williams' tutorial on building your own
  module at http://mathforum.org/~ken/perl_modules.html
diff --git a/pod/perlop.pod b/pod/perlop.pod

index b24036a..22fd501 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -2034,6 +2034,14 @@ you say
  the compiler will precompute the number which that expression
  represents so that the interpreter won't have to.
  
+=head2 No-ops
+
+Perl doesn't officially have a no-op operator, but the bare constants
+C<0> and C<1> are special-cased to not produce a warning in a void
+context, so you can for example safely do
+
+    1 while foo();
+
  =head2 Bitwise String Operators
  
  Bitstrings of any size may be manipulated by the bitwise operators
diff --git a/pod/perlrun.pod b/pod/perlrun.pod

index c3e9de8..2de2311 100644 (file)
--- a/pod/perlrun.pod
+++ b/pod/perlrun.pod
@@ -523,6 +523,10 @@ folks use it for their backup files:
  
      $ perl -pi~ -e 's/foo/bar/' file1 file2 file3...
  
+Note that because B<-i> renames or deletes the original file before
+creating a new file of the same name, UNIX-style soft and hard links will
+not be preserved.
+
  Finally, the B<-i> switch does not impede execution when no
  files are given on the command line.  In this case, no backup is made
  (the original file cannot, of course, be determined) and processing
diff --git a/pod/perltodo.pod b/pod/perltodo.pod

index 5dbe882..23fd3f5 100644 (file)
--- a/pod/perltodo.pod
+++ b/pod/perltodo.pod
@@ -275,7 +275,7 @@ for example POSIX passes Exporter some very memory hungry data structures.
  
  =head2 Optimize away @_
  
-The old perltodo notes "Look at the "reification" code in C<av.c>"
+The old perltodo notes "Look at the "reification" code in C<av.c>".
  
  =head2 switch ops
  
@@ -297,3 +297,9 @@ be useful to have a reasonable general benchmarking suite that roughly
  represented what current perl programs do, and measurably reported whether
  tweaks to the core improve, degrade or don't really affect performance, to
  guide people attempting to optimise the guts of perl.
+
+=head2 readpipe(LIST)
+
+system() accepts a LIST syntax (and a PROGRAM LIST syntax) to avoid
+running a shell. readpipe() (the function behind qx//) could be similarly
+extended.
author	Nicholas Clark <nick@ccl4.org>
	Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)
committer	Nicholas Clark <nick@ccl4.org>
	Fri, 10 Sep 2004 10:24:09 +0000 (10:24 +0000)
README.solaris		patch \| blob \| blame \| history
README.win32		patch \| blob \| blame \| history
lib/bigint.pm		patch \| blob \| blame \| history
lib/overload.pm		patch \| blob \| blame \| history
pod/perldiag.pod		patch \| blob \| blame \| history
pod/perlfunc.pod		patch \| blob \| blame \| history
pod/perlhack.pod		patch \| blob \| blame \| history
pod/perlintro.pod		patch \| blob \| blame \| history
pod/perlnewmod.pod		patch \| blob \| blame \| history
pod/perlop.pod		patch \| blob \| blame \| history
pod/perlrun.pod		patch \| blob \| blame \| history
pod/perltodo.pod		patch \| blob \| blame \| history