[scripts/module_log.pl] improve help

1 files changed, 51 insertions, 15 deletions

diff --git a/scripts/module_log.pl b/scripts/module_log.pl
index cf0d4981b..ff012afda 100755
--- a/scripts/module_log.pl
+++ b/scripts/module_log.pl
@@ -26,6 +26,52 @@ my $singleflags;
 
 if ( $flags->{help} or $singleflags->{h} ) { print help(); exit 0; }
 
+sub help {
+  return <<'EOF';
+module_log.pl
+
+USAGE:
+
+  module_log.pl Class::MOP::Class
+
+    # See Class::MOP::Class started in Class-MOP and moved to Moose
+    #
+    # NOTE: Due to a caveat in PAUSE with how indexing works, Modules may look
+    # like they're comming from weird places.
+    #
+    # this is usually due to somebody lexically hacking a foreign package like so:
+    #
+    #   { package Foo; blah blah blah }
+    #
+    # Unfortunately, PAUSE indexer sees that 'package Foo' and then deems this a place 'Foo' is defined.
+    #
+    # Usually that doesn't pose a problem, as the author who releases the containing package rarely has
+    # AUTHORITY permssion on the hacked package, so it doesn't get indexed. ( ie: HTTP::Request::Common )
+    #
+    # However, in the event the author has permissions to publish 'Foo', the indexer runs the risk
+    # of taking that tiny little package declaration as *the most recent version of that package*
+    # and is likely to try installing it.  ( ie: HTTP::Message )
+    #
+    # For the most part, the "indexed but not authorised" case is eliminated by the query,
+    # but we have to weed out some false matches client side due to a current API limitation.
+    #
+    # but you can turn this weeding off for diagnostic reasons with
+    #
+    # module_log.pl --notrim HTTP::Message
+    #
+    # PROTIP: Usually when people do this foreign hacking, they don't define a VERSION in the same context
+    # which thankfully gives you the ability to assume its not sourceable.
+    #
+    # Try this:
+    #
+    # module_log.pl --notrim HTTP::Request::Common
+    #
+    # and see all the hacking in Apache-TestRequest turn up =)
+    #
+
+EOF
+}
+
 # FILENAME: module_log.pl
 # CREATED: 25/10/11 12:15:51 by Kent Fredric (kentnl) <kentfredric@gmail.com>
 # ABSTRACT: Show the full history of a Module across distributions.
@@ -34,13 +80,15 @@ if ( $flags->{help} or $singleflags->{h} ) { print help(); exit 0; }
 #
 # module_log.pl Class::MOP
 #  # emits both Class-MOP and Moose history
+
+use Data::Dump qw( pp );
+
 my ($release) = shift(@ARGV);
 
-my $result = [ map { $_->{as_string} } metacpan->find_dist_simple( $release , {notrim=>1}) ];
+my $result = [ map { $_->{as_string} } metacpan->find_dist_simple( $release, $flags ) ];
 
-use Data::Dump qw( pp );
 use JSON qw( to_json );
-say to_json($result , { pretty => 1 } );
+say to_json( $result, { pretty => 1 } );
 1;
 
 sub pkg_for_module {
@@ -54,15 +102,3 @@ sub gen_dep {
 
 }
 
-sub help {
-  return <<'EOF';
-module_log.pl
-
-USAGE:
-
-  module_log.pl Class::MOP::Class
-
-    # See Class::MOP::Class started in Class-MOP and moved to Moose
-
-EOF
-}