On Tue, Aug 28, 2001 at 09:19:08PM +0100, [EMAIL PROTECTED] wrote:
> To portably run:
>
> pod2text lib/Some/Module.pm >README
Don't use pod2text, use Pod::Text.
use Pod::Text;
my $parser = $formatter->new;
$parser->parse_from_file ($module, 'README');
that's all any modern pod2text does.
You can just stick that into your Makefile.PL and it's servicable.
Getting it to automatically update as part of 'make' is a little
harder. I'd suggest you look at how the POD2MAN and POD2HTML targets
is generated in the various ExtUtils::MM_* modules. (Good fucking
luck).
I have an old mod2readme thing that did something like this, but with
a bit more intellegence. I've attached the latest copy. It's pretty
old, but you might be able to draw inspiration.
It generates a simple INSTALL document (What is this? How do I
install it?) It also semi-intellegently looked for module
prerequisites and what external utilities you need (like a C compiler
if there's XS).
It also snipped the NAME, SYNOPSIS, DESCRIPTION, AUTHOR, LICENSE and
COPYRIGHT sections out using Pod::Select and generated a README file.
Text::Metaphone's INSTALL and README docs are generated using it.
--
Michael G. Schwern <[EMAIL PROTECTED]> http://www.pobox.com/~schwern/
Perl6 Quality Assurance <[EMAIL PROTECTED]> Kwalitee Is Job One
HA HA HA You're all so ridiculous! But thanks for the money!
#!/usr/bin/perl -w
package mod2readme;
require 5;
use strict;
use Pod::Select;
use Getopt::Long;
use Cwd;
use File::Copy;
use vars qw($VERSION);
$VERSION = 0.01;
use subs qw(getMakefileInfo readMANIFEST);
# Set optional behavior.
use vars qw($Valiant $Force $Verbose %Module %MakefilePL);
GetOptions( 'valiant' => \$Valiant,
'n=s' => \$Module{NAME},
'f' => \$Force,
'v' => \$Verbose,
'verbose' => \$Verbose,
);
# Figure out our directory.
$Module{dir} = shift;
if ( defined $Module{dir} ) {
chdir($Module{dir}) || die "Can't find $Module{dir}";
} else {
$Module{dir} = cwd;
}
# Get module info from Makefile.PL
%MakefilePL = getMakefileInfo;
foreach (keys %MakefilePL) {
$Module{$_} = $MakefilePL{$_} unless defined $Module{$_};
}
# Figure out where the POD's at.
($Module{File}) = $Module{NAME} =~ m/([^:]+)$/;
$Module{File} .= '.pm';
unless( -e $Module{File} ) {
$Module{File} = $Module{NAME};
$Module{File} =~ s|::|/|g;
$Module{File} .= '.pm';
$Module{File} = 'lib/'.$Module{File};
}
($Module{Pod}) = grep /^$Module{NAME}.pod/i, readMANIFEST; # look for .pod
$Module{Pod} = $Module{File} unless defined $Module{Pod};
# Make sure we have minimal information.
die "Can't figure out the module name!\n" unless defined $Module{NAME};
die "Can't figure out where to get our POD!\n" unless defined $Module{Pod};
# Create the README & INSTALL
for my $file (qw(README INSTALL)) {
print STDERR "Creating the $file.\n" if $Verbose;
die "$file already exists! Cowardly refusing to continue.\n"
if !$Force && -e $file;
no strict 'refs';
open($file, ">$file") || die "Can't create $file";
select((select($file), $|=1)[0]); # unbuffer
}
# Grab the name, synopsis, description, author, license and/or copyright
# from the pod code and make that the beginning of the readme.
podselect({-output => \*README,
-sections => [qw(NAME SYNOPSIS DESCRIPTION AUTHOR),
"(?i:^LICENSE)", "(?i:^COPYRIGHT)"],
},
$Module{Pod}
);
# Changes? Yeah, right.
print INSTALL <<"INSTALL-DEFAULT";
WHAT IS THIS?
This is $Module{NAME}, a perl module. Please see the README that comes with
this distribution.
HOW DO I INSTALL IT?
To install this module, cd to the directory that contains this README
file and type the following:
perl Makefile.PL
make
make test
make install
To install this module into a specific directory, do:
perl Makefile.PL PREFIX=/name/of/the/directory
...the rest is the same...
Please also read the perlmodinstall man page, if available.
INSTALL-DEFAULT
# Look for XS files.
# I should probably use file(1) where available for this instead.
use vars qw(%ExtUtils);
XS: foreach (readMANIFEST) {
/\.xs$/ && do { $ExtUtils{XS}++; next
XS };
/\.(?:c|h)$/ && do { $ExtUtils{C}++; next XS };
/\.y$/ && do { $ExtUtils{yacc}++; next
XS };
/\.(?:c\+\+|cc|cxx|cpp|C)$/
&& do { $ExtUtils{'C++'}++; next XS };
/\.m$/ && do { $ExtUtils{'Objective C'}++;
next XS };
/\.java$/ && do { $ExtUtils{Java}++; next
XS };
/\.tcl$/ && do { $ExtUtils{TCL}++; next
XS };
/\.(?:asm|s|S)$/ && do { $ExtUtils{Assembly}++; next
XS };
/\.py$/ && do { $ExtUtils{python}++; next
XS };
/\.([ck]?)sh$/ && do { local $^W = 0; # $1 is probably undef.
$ExtUtils{"$1sh"}++;
next XS };
/\.bat$/ && do { $ExtUtils{'DOS Batch'}++; next
XS };
/\.i$/ && do { $ExtUtils{SWIG}++; next
XS };
/\.l$/ && do { $ExtUtils{lex}++; next
XS };
}
if( keys %ExtUtils ) {
print STDERR "Looks like you need...\n" if $Verbose;
print INSTALL "WHAT EXTRAS DO I NEED?\n\n";
foreach (keys %ExtUtils) {
print STDERR "\t$_\n" if $Verbose;
print INSTALL "\t$_\n";
}
print INSTALL "\n";
}
# Miminal perl version finder... I'll put this here later.
# Add the prereq modules to the INSTALL docs.
if ( defined $Module{PREREQ_PM} ) {
print INSTALL "WHAT MODULES DO I NEED?\n\n";
print STDERR "Looks like you need the following prerequisite modules...\n"
if $Verbose;
while (my($mod, $ver) = each %{$Module{PREREQ_PM}}) {
print STDERR "\t$mod - $ver\n" if $Verbose;
print INSTALL "\t$mod";
print INSTALL "\t$ver" if $ver != 0;
print INSTALL "\n";
}
}
# Append the README to the INSTALL.
copy('INSTALL', \*README) ||
die "Can't append the INSTALL file to the README!";
# Routine to glean information from Makefile.PL
# Currently very weak. Should use B.
sub getMakefileInfo {
local *MPL;
open(MPL, 'Makefile.PL') || die "Can't open your Makefile.PL: $!\n";
my $writemf_sub;
while(<MPL>) {
$writemf_sub .= $_ if /^\s*WriteMakefile\s*\(/ .. /^\s*\);\s*$/;
}
# Convert to a list and eval.
$writemf_sub =~ s/^\s*WriteMakefile//;
return eval $writemf_sub;
}
# Routine to read the MANIFEST. Does caching.
use vars qw(@MANIFEST);
sub readMANIFEST {
local *MANIFEST;
unless (@MANIFEST) {
open(MANIFEST, 'MANIFEST') || die "Can't open your MANIFEST: $!\n";
@MANIFEST = <MANIFEST>;
chomp @MANIFEST;
}
return @MANIFEST;
}
__END__
=pod
=head1 NAME
mod2readme - creates basic README and INSTALL docs based on your module
=head1 SYNOPSIS
mod2readme
mod2readme -fv -n Module::Name --valiant <module dir>
=head1 DESCRIPTION
Gleaning information from your module, B<mod2readme> creates a simple
README and INSTALL docs based upon the available POD, Makefile and
MANIFEST. It is intented to be used with a module based on a h2xs
generated template.
Its purpose in life is to remove some of the tedium of writing README
and INSTALL docs which are are basically cut & pastes from your POD.
It also helps keep those docs up to date as your module changes and
grows. The README files are intended for modules which are to be
distributed to CPAN.
=head1 OPTIONS
-n Module::Name Name of the module, otherwise mod2readme will guess.
--valiant Attempt some things which might not work.
-f Blow away anything in its path, stop for nothing.
-v, --verbose Pontificate loudly upon the step being taken.
=head1 HOW IT WORKS
=head2 README Generation
Aside from looking at the CPAN docs site
I<(http://theory.uwinnipeg.ca/CPAN/)> the README file is a CPAN
shoppers only way of knowing something about your module short of
actually downloading & unpacking the module. (In case you didn't
realize, CPAN extracts the README file from your module and offers it
as a seperate file. You CPAN shell users can just do "readme
Module::Name") As such, it should contain some basic information about
what your module is, how its used, who wrote it, and what's needed to
install it.
On that theory, B<mod2readme> generates its README file from the
following information...
Given a module "Module::Foo", B<mod2readme> will first look for
Foo.pod, then Foo.pm for its documentation. It wall also make use of
MANIFEST and Makefile.PL.
=over 4
=item Basic purpose and use
The NAME, SYNOPSIS, and DESCRIPTION pod fields fields are pulled from
the docs and used to create the first part of the README file covering
basic module purpose and use.
=item Author and Copyright
AUTHOR and either COPYRIGHT, LICENSE or something looking like one of
those will be used from the docs and placed next.
=item Installation
The INSTALL file (generated seperately, see L<INSTALL Generation>)
will pretty much be appended to the end of the README.
=item Changes
B<mod2readme> will make a I<valiant> attempt at parsing out your
Changes file looking for the most recent changes (or the one
corresponding to the current version.) This probably won't work.
=back
=head2 INSTALL Generation
Its always a nice thing to know what else you'll need before you
install a module.
=over 4
=item Basic Installation
B<mod2readme> will then create basic INSTALL documenation (taken from
INSTALL.default.tmpl) on the installation of a basic module. (perl
Makefile.PL; make test; etc...).
=item Extra needed utilities
It will also do a little snooping around in the MANIFEST looking for
XS files indicating you will be needing a C compiler, or other special
external utilities (yacc, C++, etc...) and give this information in
the INSTALL.
=item Minimum Perl version
B<mod2readme> will strive mightily to figure out the minimum perl
version that your program requires. This usually amounts to looking
for "require #" in your code. This is something that will frequently
not work.
=item Prequisite modules
A listing of necessary modules and minimal versions will be added to
the INSTALL docs by looking through Makefile.PL for a PREREQ hash.
=back
=head1 AUTHOR
Michael G Schwern <[EMAIL PROTECTED]>
=head1 COPYRIGHT
etc...
=cut
