local-lib5/lib/perl5/Module/Install/ReadmeFromPod.pm

   1 package Module::Install::ReadmeFromPod;
   2
   3 use strict;
   4 use warnings;
   5 use base qw(Module::Install::Base);
   6 use vars qw($VERSION);
   7
   8 $VERSION = '0.06';
   9
  10 sub readme_from {
  11   my $self = shift;
  12   return unless $Module::Install::AUTHOR;
  13   my $file = shift || return;
  14   my $clean = shift;
  15   require Pod::Text;
  16   my $parser = Pod::Text->new();
  17   open README, '> README' or die "$!\n";
  18   $parser->output_fh( *README );
  19   $parser->parse_file( $file );
  20   return 1 unless $clean;
  21   $self->postamble(<<"END");
  22 distclean :: license_clean
  23
  24 license_clean:
  25 \t\$(RM_F) README
  26 END
  27   return 1;
  28 }
  29
  30 'Readme!';
  31
  32 __END__
  33
  34 =head1 NAME
  35
  36 Module::Install::ReadmeFromPod - A Module::Install extension to automatically convert POD to a README
  37
  38 =head1 SYNOPSIS
  39
  40   # In Makefile.PL
  41
  42   use inc::Module::Install;
  43   author 'Vestan Pants';
  44   license 'perl';
  45   readme_from 'lib/Some/Module.pm';
  46
  47 A C<README> file will be generated from the POD of the indicated module file.
  48
  49 =head1 DESCRIPTION
  50
  51 Module::Install::ReadmeFromPod is a L<Module::Install> extension that generates a C<README> file
  52 automatically from an indicated file containing POD, whenever the author runs C<Makefile.PL>.
  53
  54 =head1 COMMANDS
  55
  56 This plugin adds the following Module::Install command:
  57
  58 =over
  59
  60 =item C<readme_from>
  61
  62 Does nothing on the user-side. On the author-side it will generate a C<README> file using L<Pod::Text> from
  63 the POD in the file passed as a parameter.
  64
  65   readme_from 'lib/Some/Module.pm';
  66
  67 If a second parameter is set to a true value then the C<README> will be removed at C<make distclean>.
  68
  69   readme_from 'lib/Some/Module.pm' => 'clean';
  70
  71 =back
  72
  73 =head1 AUTHOR
  74
  75 Chris C<BinGOs> Williams
  76
  77 =head1 LICENSE
  78
  79 Copyright E<copy> Chris Williams
  80
  81 This module may be used, modified, and distributed under the same terms as Perl itself. Please see the license that came with your Perl distribution for details.
  82
  83 =head1 SEE ALSO
  84
  85 L<Module::Install>
  86
  87 L<Pod::Text>
  88
  89 =cut
  90