#!/usr/bin/perl
###########################################
# updreadme -- Update the README of a distribution.
# Mike Schilli, 2002 (m@perlmeister.com)
###########################################
use warnings;
use strict;

    # Can be obtained from http://perlmeister.com/scripts
use ModDevUtils;

our $CVSVERSION = '$Revision: 1.5 $';
our ($VERSION)  = ($CVSVERSION =~ /(\d+\.\d+)/);

ModDevUtils::update_readme();

__END__

=cut

=head1 NAME

    updreadme - Update the README file of a module distribution

=head1 DOWNLOAD

_SRC_HERE_

=head1 SYNOPSIS

    updreadme

=head1 DESCRIPTION

Called from the top directory of a module distribution, C<updreadme>
will find out what the main C<*.pm> file is, extract the C<$VERSION>
from it and create a C<README> file, consisting of a header
like

    ##########################################################
    Path::Module VERSION
    ##########################################################

and the result of a pod2text call on the top *.pm file.

It derives the value of VERSION in a somewhat cleaner way than 
C<ExtUtils::MakeMaker> does (which brute-force parses the module)
but makes some pretty wild assumptions:

=over 4

=item *

The C<*.pm> file defines I<one> package which contains a global C<$VERSION>
variable.

=item *

The C<*> part of C<*.pm> (the module's file name) equals the last part
of the defined package (e.g. if the package is C<Foo::Bar::Baz>, the
filename needs to be C<Baz.pm>. It is I<not> necessary that the file
is located under C<Foo/Bar>, it can as well reside in the current or
any subdirectory.

=item *

The module doesn't pull in another module which's last name part 
equals the name of the module. E.g. if the module is C<Foo::Bar::Baz>
and it pulls in C<Blurp::Yada::Baz> via C<use Blurp::Yada::Baz>, 
then we're hosed, because the algorithm will think that it needs
to fetch C<$Blurp::Yada::Baz::VERSION>.

=back

=head1 REQUIREMENTS

This script depends on the module C<ModDevUtils.pm>, which is freely
available from Mike's Script Archive at 

    http://perlmeister.com/scripts

Just download it, install it somewhere where perl can find it and
C<updreadme> will just work.

=head1 LEGALESE

Copyright 2002 by Mike Schilli, all rights reserved.
This program is free software, you can redistribute it and/or
modify it under the same terms as Perl itself.

=head1 AUTHOR

2002, Mike Schilli <m@perlmeister.com>