Tweaks and reflowing for the cc/linker split.

[p5sagit/p5-mst-13.2.git] / pod / perlmodlib.PL

diff --git a/pod/perlmodlib.PL b/pod/perlmodlib.PL
index d87785f..39e9613 100644 (file)
--- a/pod/perlmodlib.PL
+++ b/pod/perlmodlib.PL
@@ -2,7 +2,7 @@
 
 $ENV{LC_ALL} = 'C';
 
-open (OUT, ">perlmodlib.tmp") or die $!;
+open (OUT, ">perlmodlib.pod") or die $!;
 my (@pragma, @mod, @MANIFEST);
 
 open (MANIFEST, "../MANIFEST") or die $!;
@@ -10,34 +10,57 @@ open (MANIFEST, "../MANIFEST") or die $!;
 push @MANIFEST, 'lib/Config.pod', 'lib/Errno.pm', 'lib/lib.pm',
     'lib/DynaLoader.pm', 'lib/XSLoader.pm';
 
+# If run in a clean source tree, these will be missing because they are
+# generated by the build.
+my %generated = (
+    'encoding' => 'Allows you to write your script in non-ascii or non-utf8',
+    'lib' => 'Manipulate @INC at compile time',
+    'ops' => 'Restrict unsafe operations when compiling',
+    'Config' => 'Access Perl configuration information',
+    'DynaLoader' => 'Dynamically load C libraries into Perl code',
+    'Errno' => 'System errno constants',
+    'O' => 'Generic interface to Perl Compiler backends',
+    'Safe' => 'Compile and execute code in restricted compartments',
+    'XSLoader' => 'Dynamically load C libraries into Perl code',
+);
+
+# If run in a clean source tree, these should not be reported.
+# These are considered 'modules' by this script, but they really are not.
+my %suppressed = map {$_ => 1} qw(
+    B::O
+    Encode::encoding
+    Opcode::Safe
+    Opcode::ops
+);
+
 for (@MANIFEST) {
-     my $filename;
-     next unless s|^lib/|| or m|^ext/|;
-     my ($origfilename) = ($filename) = m|^(\S+)|;
-     $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
-     next unless $filename =~ m!\.p(m|od)$!;
-     unless (open (MOD, "../lib/$filename")) {
-       unless (open (MOD, "../$origfilename")) {
-           warn "Couldn't open ../$origfilename: $!";
-           next;
-       }
-       $filename = $origfilename;
-     }
+    my $filename;
+    next unless s|^lib/|| or m|^ext/|;
+    my ($origfilename) = ($filename) = m|^(\S+)|;
+    $filename =~ s|^[^/]+/|| if $filename =~ s|^ext/||;
+    next unless $filename =~ m!\.p(m|od)$!;
+    unless (open (MOD, "../lib/$filename")) {
+        unless (open (MOD, "../$origfilename")) {
+            warn "Couldn't open ../$origfilename: $!";
+            next;
+        }
+        $filename = $origfilename;
+    }
 
 
      my ($name, $thing);
      my $foundit=0;
      {
-        local $/="";
-        while (<MOD>) {
-            next unless /^=head1 NAME/;
-            $foundit++;
-            last;
-        }
+         local $/="";
+         while (<MOD>) {
+             next unless /^=head1 NAME/;
+             $foundit++;
+             last;
+         }
      }
      unless ($foundit) {
-        warn "$filename missing =head1 NAME (okay if there is respective .pod)\n";
-        next;
+         warn "$filename missing =head1 NAME (OK if respective .pod exists)\n";
+         next;
      }
      my $title = <MOD>;
      chomp($title);
@@ -49,14 +72,18 @@ for (@MANIFEST) {
      $perlname =~ s!\b(\w+)/\1\b!$1!;
      $perlname =~ s!/!::!g;
 
+     # modules with non standard locations
+     $perlname =~ s{Base64::QuotedPrint}{QuotedPrint};
+
      ($name, $thing) = split / --? /, $title, 2;
 
      unless ($name and $thing) {
-        warn "$filename missing name\n"  unless $name;
-        warn "$filename missing thing\n" unless $thing;
-        next;
+         warn "$filename missing name\n"  unless $name;
+         warn "$filename missing thing\n" unless $thing;
+         next;
      }
 
+     next if $suppressed{$perlname};
 
      $thing =~ s/^perl pragma to //i;
      $thing = ucfirst($thing);
@@ -67,6 +94,17 @@ for (@MANIFEST) {
      } else {
           push @pragma, $title;
      }
+
+     # if we find a generated one via the MANIFEST, no need to add later.
+     delete $generated{$perlname};
+}
+while (my ($name,$desc) = each %generated) {
+    my $title = "=item $name\n\n$desc\n\n";
+    if ($name =~ /[A-Z]/) {
+        push @mod, $title;
+    } else {
+        push @pragma, $title;
+    }
 }
 
 print OUT <<'EOF';
@@ -1070,8 +1108,8 @@ the module after __END__ either using AutoSplit or by saying:
 Does your module pass the 'empty subclass' test? If you say
 C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
 to use SUBCLASS in exactly the same way as YOURCLASS.  For example,
-does your application still work if you change:  C<$obj = new YOURCLASS;>
-into: C<$obj = new SUBCLASS;> ?
+does your application still work if you change:  C<< $obj = YOURCLASS->new(); >>
+into: C<< $obj = SUBCLASS->new(); >> ?
 
 Avoid keeping any state information in your packages. It makes it
 difficult for multiple other packages to use yours. Keep state
@@ -1461,5 +1499,5 @@ 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.tmp): $!";
+close OUT      or warn "$0: failed to close OUT (perlmodlib.pod): $!";