Finalize perldelta

[perl5.git] / pod / perlmodlib.PL

diff --git a/pod/perlmodlib.PL b/pod/perlmodlib.PL
index a82f22f..608b64e 100644 (file)
--- a/pod/perlmodlib.PL
+++ b/pod/perlmodlib.PL
@@ -5,35 +5,47 @@ use warnings;
 
 $ENV{LC_ALL} = 'C';
 
-use FindBin;
-chdir $FindBin::Bin or die "$0: Can't chdir $FindBin::Bin: $!";
+my $Quiet;
+@ARGV = grep { not($_ eq '-q' and $Quiet = 1) } @ARGV;
 
-my $Quiet = @ARGV && $ARGV[0] eq '-q';
-
-open (OUT, ">perlmodlib.pod") or die $!;
-my (@pragma, @mod, @files);
+if (@ARGV) {
+    my $workdir = shift;
+    chdir $workdir
+        or die "Couldn't chdir to '$workdir': $!";
+}
+require 'regen/regen_lib.pl';
 
 # MANIFEST itself is Unix style filenames, so we have to assume that Unix style
 # filenames will work.
 
-open (MANIFEST, "../MANIFEST") or die $!;
-@files = grep m#(?:\.pm|\.pod|_pm\.PL)#, map {s/\s.*//s; $_}
-    grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo)/# } <MANIFEST>;
+open MANIFEST, '<', 'MANIFEST'
+    or die "Can't open MANIFEST: $!";
+my @files =
+    grep !m#/perl.*\.pod#,
+    grep m#(?:\.pm|\.pod|_pm\.PL)#,
+    map {s/\s.*//s; $_}
+    grep { m#^(lib|ext|dist|cpan)/# && !m#/(?:t|demo)/# }
+    <MANIFEST>;
+close MANIFEST
+    or die "$0: failed to close MANIFEST: $!";
+
+my $out = open_new('pod/perlmodlib.pod', undef,
+                   {by => "$0 extracting documentation",
+                    from => 'the Perl source files'}, 1);
 
 my %exceptions = (
     'abbrev' => 'Text::Abbrev',
     'carp' => 'Carp',
     'getopt' => 'Getopt::Std',
-    'B<CGI::Carp>' => 'CGI::Carp',
-    'ModuleInfo' => 'Module::Build::ModuleInfo',
-    '$notes_name' => 'Module::Build::Notes',
     'Encode::MIME::NAME' => 'Encode::MIME::Name',
     'libnetFAQ' => 'Net::libnetFAQ',
 );
 
+my (@pragma, @mod);
+
 for my $filename (@files) {
-    unless (open MOD, '<', "../$filename") {
-       warn "Couldn't open ../$filename: $!";
+    unless (open MOD, '<', $filename) {
+        warn "Couldn't open $filename: $!";
        next;
     }
 
@@ -54,7 +66,8 @@ for my $filename (@files) {
     }
     my $title = <MOD>;
     chomp $title;
-    close MOD;
+    close MOD
+        or die "Error closing $filename: $!";
 
     ($name, $thing) = split / --? /, $title, 2;
 
@@ -80,17 +93,16 @@ for my $filename (@files) {
 # Much easier to special case it like this than special case the depending on
 # and parsing lib/Config.pod, or special case opening configpm and finding its
 # =head1 (which is not found with the $/="" above)
-push @mod, <<'CONFIG';
-=item Config
+push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
 
-Access Perl configuration information
 
-CONFIG
-
-print OUT <<'EOF';
-=for maintainers
-Generated by perlmodlib.PL -- DO NOT EDIT!
+# The intent of using =cut as the heredoc terminator is to make the whole file
+# parse as (reasonably) sane Pod as-is to anything that attempts to
+# brute-force treat it as such. The content is already useful - this just
+# makes it tidier, by stopping anything doing this mistaking the rest of the
+# Perl code for Pod. eg http://search.cpan.org/dist/perl/pod/perlmodlib.PL
 
+print $out <<'=cut';
 =head1 NAME
 
 perlmodlib - constructing new Perl modules and finding existing ones
@@ -137,11 +149,12 @@ The following pragmas are defined (and have their own documentation).
 
 =over 12
 
-EOF
+=cut
+
+print $out $_ for sort @pragma;
 
-print OUT $_ for (sort @pragma);
+print $out <<'=cut';
 
-print OUT <<EOF;
 =back
 
 =head2 Standard Modules
@@ -156,11 +169,12 @@ don't have the gdbm library.
 
 =over 12
 
-EOF
+=cut
+
+print $out $_ for sort @mod;
 
-print OUT $_ for (sort @mod);
+print $out <<'=cut', "=cut\n";
 
-print OUT <<'EOF';
 =back
 
 To find out I<all> modules installed on your system, including
@@ -1044,7 +1058,7 @@ its methods by loading dynamic C or C++ objects, but that should be
 totally transparent to the user of the module.  Likewise, the module
 might set up an AUTOLOAD function to slurp in subroutine definitions on
 demand, but this is also transparent.  Only the F<.pm> file is required to
-exist.  See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
+exist.  See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
 the AUTOLOAD mechanism.
 
 =head2 Guidelines for Module Creation
@@ -1104,7 +1118,7 @@ Let the objects look after themselves! Generally, avoid hard-wired
 class names as far as possible.
 
 Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
-C<< $r->func() >> would work (see L<perlbot> for more details).
+C<< $r->func() >> would work.
 
 Use autosplit so little used or newly added functions won't be a
 burden to programs that don't use them. Add test functions to
@@ -1328,7 +1342,7 @@ Give the module a version/issue/release number.
 
 To be fully compatible with the Exporter and MakeMaker modules you
 should store your module's version number in a non-my package
-variable called $VERSION.  This should be a floating point
+variable called $VERSION.  This should be a positive floating point
 number with at least two digits after the decimal (i.e., hundredths,
 e.g, C<$VERSION = "0.01">).  Don't use a "1.3.2" style version.
 See L<Exporter> for details.
@@ -1503,8 +1517,7 @@ that a module doesn't pollute any namespace it wasn't asked to.  The
 written contract for the module (A.K.A. documentation) may make other
 provisions.  But then you know when you C<use RedefineTheWorld> that
 you're redefining the world and willing to take the consequences.
-EOF
 
-close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
-close OUT      or warn "$0: failed to close OUT (perlmodlib.pod): $!";
+=cut
 
+read_only_bottom_close_and_rename($out);