Added example usage and SEE ALSO links to similar modules in doc for if.pm

2 files changed, 48 insertions, 4 deletions

diff --git a/dist/if/if.pm b/dist/if/if.pm
index 1fb5f3deb4..376f26ba31 100644
--- a/dist/if/if.pm
+++ b/dist/if/if.pm
@@ -31,23 +31,63 @@ if - C<use> a Perl module if a condition holds
 
 =head1 DESCRIPTION
 
+The C<if> module is used to conditionally load another module.
 The construct
 
   use if CONDITION, MODULE => ARGUMENTS;
 
-has no effect unless C<CONDITION> is true.  In this case the effect is
-the same as of
+will load MODULE only if CONDITION evaluates to true.
+The above statement has no effect unless C<CONDITION> is true.
+If the CONDITION does evaluate to true, then the above line has
+the same effect as:
 
   use MODULE ARGUMENTS;
 
-Above C<< => >> provides necessary quoting of C<MODULE>.  If not used (e.g.,
-no ARGUMENTS to give), you'd better quote C<MODULE> yourselves.
+The use of C<< => >> above provides necessary quoting of C<MODULE>.
+If you don't use the fat comma (eg you don't have any ARGUMENTS),
+then you'll need to quote the MODULE.
+
+=head2 EXAMPLES
+
+The following line is taken from the testsuite for L<File::Map>:
+
+  use if $^O ne 'MSWin32', POSIX => qw/setlocale LC_ALL/;
+
+If run on any operating system other than Windows,
+this will import the functions C<setlocale> and C<LC_ALL> from L<POSIX>.
+On Windows it does nothing.
+
+The following is used to L<deprecate> core modules beyond a certain version of Perl:
+
+  use if $] > 5.016, 'deprecate';
+
+This line is taken from L<Text::Soundex> 3.04,
+and marks it as deprecated beyond Perl 5.16.
+If you C<use Text::Soundex> in Perl 5.18, for example,
+and you have used L<warnings>,
+then you'll get a warning message
+(the deprecate module looks to see whether the
+calling module was C<use>'d from a core library directory,
+and if so, generates a warning),
+unless you've installed a more recent version of L<Text::Soundex> from CPAN.
 
 =head1 BUGS
 
 The current implementation does not allow specification of the
 required version of the module.
 
+=head1 SEE ALSO
+
+L<Module::Requires> can be used to conditionally load one or modules,
+with constraints based on the version of the module.
+Unlike C<if> though, L<Module::Requires> is not a core module.
+
+L<Module::Load::Conditional> provides a number of functions you can use to
+query what modules are available, and then load one or more of them at runtime.
+
+L<provide> can be used to select one of several possible modules to load,
+based on what version of Perl is running.
+
 =head1 AUTHOR
 
 Ilya Zakharevich L<mailto:ilyaz@cpan.org>.
diff --git a/t/porting/known_pod_issues.dat b/t/porting/known_pod_issues.dat
index 900567ceb9..d505ef47a9 100644
--- a/t/porting/known_pod_issues.dat
+++ b/t/porting/known_pod_issues.dat
@@ -62,6 +62,7 @@ File::chdir
 File::Copy::Recursive
 File::Findgrep
 File::MMagic
+File::Map
 File::ShareDir
 flock(3)
 fsync(3c)
@@ -97,6 +98,7 @@ Module::Find
 Module::Info
 Module::Pluggable
 Module::Pluggable::Object
+Module::Requires
 Module::Starter
 Moo
 Moose
@@ -133,6 +135,7 @@ Pod::PXML
 poll(2)
 prctl(2)
 printf(3)
+provide
 pstruct
 ptar(1)
 ptargrep(1)
@@ -166,6 +169,7 @@ Test::Harness::TAP
 Test::Inline
 Test::MockObject
 Text::Autoformat
+Text::Soundex
 Text::Template
 Text::Unidecode
 Time::Object