perlmod and perlstyle improvements

• Outward links for perlmod
• Tweak perlmodstyle version notes
• Link perlnewmod to perlmodstyle

3 files changed, 34 insertions, 3 deletions

diff --git a/pod/perlmod.pod b/pod/perlmod.pod
index f708cc0de5..0ed4bd9134 100644
--- a/pod/perlmod.pod
+++ b/pod/perlmod.pod
@@ -4,6 +4,27 @@ perlmod - Perl modules (packages and symbol tables)
 
 =head1 DESCRIPTION
 
+=head2 Is this the document you were after?
+
+There are other documents which might contain the information that you're
+looking for:
+
+=over 2
+
+=item This doc
+
+Perl's packages, namespaces, and some info on classes.
+
+=item L<perlnewmod>
+
+Tutorial on making a new module.
+
+=item L<perlmodstyle>
+
+Best practices for making a new module.
+
+=back
+
 =head2 Packages
 X<package> X<namespace> X<variable, global> X<global variable> X<global>
 
diff --git a/pod/perlmodstyle.pod b/pod/perlmodstyle.pod
index 5622d3244d..5a52eaf9a4 100644
--- a/pod/perlmodstyle.pod
+++ b/pod/perlmodstyle.pod
@@ -630,9 +630,9 @@ don't want CPAN.pm to list it as most recent use an '_' after the
 regular version number followed by at least 2 digits, eg. 1.20_01. If
 you do this, the following idiom is recommended:
 
-  $VERSION = "1.12_01";
-  $XS_VERSION = $VERSION; # only needed if you have XS code
-  $VERSION = eval $VERSION;
+  our $VERSION = "1.12_01"; # so CPAN distribution will have right filename
+  our $XS_VERSION = $VERSION; # only needed if you have XS code
+  $VERSION = eval $VERSION; # so "use Module 0.002" won't warn on underscore
 
 With that trick MakeMaker will only read the first line and thus read
 the underscore, while the perl interpreter will evaluate the $VERSION
@@ -644,6 +644,13 @@ Never release anything (even a one-word documentation patch) without
 incrementing the number.  Even a one-word documentation patch should
 result in a change in version at the sub-minor level.
 
+Once picked, it is important to stick to your version scheme, without
+reducing the number of digits. This is because "downstream" packagers,
+such as the FreeBSD ports system, interpret the version numbers in
+various ways. If you change the number of digits in your version scheme,
+you can confuse these systems so they get the versions of your module
+out of order, which is obviously bad.
+
 =head2 Pre-requisites
 
 Module authors should carefully consider whether to rely on other
diff --git a/pod/perlnewmod.pod b/pod/perlnewmod.pod
index 7555f974a8..26c4c13979 100644
--- a/pod/perlnewmod.pod
+++ b/pod/perlnewmod.pod
@@ -23,6 +23,9 @@ trying to do, and you've had to write the code yourself, consider
 packaging up the solution into a module and uploading it to CPAN so that
 others can benefit.
 
+You should also take a look at L<perlmodstyle> for best practices in
+making a module.
+
 =head2 Warning
 
 We're going to primarily concentrate on Perl-only modules here, rather