fix re debug segvs in global destruction, and a tweak to Benchmark to prevent infinit...

[p5sagit/p5-mst-13.2.git] / lib / version.pod

diff --git a/lib/version.pod b/lib/version.pod
index 509089c..0f4f20d 100644 (file)
--- a/lib/version.pod
+++ b/lib/version.pod
@@ -55,13 +55,24 @@ and to not rely on hidden behavior of the parser.
 =item * Be careful
 
 If you are using Module::Build or ExtUtils::MakeMaker, so that you can
-release your module to CPAN, you have to recognize that none of those
-programs currently handles version objects natively (yet).  That also
-goes for the CPAN indexer (PAUSE).  Although there are modules on CPAN
-that employ the version module internally, the support for assigning a
-module $VERSION scalar is still lacking.  Both Module::Build and the 
-PAUSE indexer will [hopefully soon] include support for version 
-objects.
+release your module to CPAN, you have to recognize that neither of those
+programs completely handles version objects natively (yet).  If you use
+version objects with Module::Build, you should add an explicit dependency
+to the release of version.pm in your Build.PL:
+
+  my $builder = Module::Build->new(
+     ...
+     requires => {
+         ... ,
+         'version'    => 0.50,
+        ...,
+     },
+     ...
+  );
+
+and it should Just Work(TM).  Module::Build will [hopefully soon] 
+include full support for version objects; there are no current plans 
+to patch ExtUtils::MakeMaker to support version objects.
 
 =head2 What IS a version
 
@@ -250,6 +261,19 @@ must be quoted to be converted properly.  For this reason, it is strongly
 recommended that all initializers to qv() be quoted strings instead of
 bare numbers.
 
+To prevent the C<qv()> function from being exported to the caller's namespace,
+either use version with a null parameter:
+
+  use version ();
+
+or just require version, like this:
+
+  require version;
+
+Both methods will prevent the import() method from firing and exporting the
+C<qv()> sub.  This is true of subclasses of version as well, see
+L<SUBCLASSING> for details.
+
 =back
 
 For the subsequent examples, the following three objects will be used:
@@ -559,14 +583,10 @@ derived class:
 See also L<version::AlphaBeta> on CPAN for an alternate representation of
 version strings.
 
-B<NOTE:> the L<qv> operator is not a class method and will not be inherited
-in the same way as the other methods.  L<qv> will always return an object of
-type L<version> and not an object in the derived class.  If you need to
-have L<qv> return an object in your derived class, add something like this:
-
-  *::qv = sub { return bless version::qv(shift), __PACKAGE__ };
-
-as seen in the test file F<t/02derived.t>.
+B<NOTE:> Although the L<qv> operator is not a true class method, but rather a
+function exported into the caller's namespace, a subclass of version will 
+inherit an import() function which will perform the correct magic on behalf
+of the subclass.
 
 =head1 EXPORT