Module::Install::ReadmeFromPod - A Module::Install extension to automatically convert POD to a README
# In Makefile.PL use inc::Module::Install; author 'Vestan Pants'; license 'perl'; readme_from 'lib/Some/Module.pm'; readme_from 'lib/Some/Module.pm', { clean => 1, format => 'htm', output_file => 'SomeModule.html' };
A README file will be generated from the POD of the indicated module file.
README
Note that the author will need to make sure Module::Install::ReadmeFromPod is installed before running the Makefile.PL. (The extension will be bundled into the user-side distribution).
Module::Install::ReadmeFromPod
Makefile.PL
Module::Install::ReadmeFromPod is a Module::Install extension that generates a README file automatically from an indicated file containing POD, whenever the author runs Makefile.PL. Several output formats are supported: plain-text, HTML, PDF or manpage.
This plugin adds the following Module::Install command:
readme_from
Does nothing on the user-side. On the author-side it will generate a README file.
readme_from 'lib/Some/Module.pm';
If a second parameter is set to a true value then the README will be removed at make distclean.
make distclean
readme_from 'lib/Some/Module.pm', 1;
A third parameter can be used to determine the format of the README file.
readme_from 'lib/Some/Module.pm', 1, 'htm';
Valid formats for this third parameter are:
Produce a plain-text README file using Pod::Text. The 'txt' format is the default.
Produce an HTML README.htm file using Pod::Html.
README.htm
Produce a README.1 manpage using Pod::Man.
README.1
Produce a PDF README.pdf file with App::pod2pdf if this module is installed.
README.pdf
A fourth parameter can be used to supply an output filename.
readme_from 'lib/Some/Module.pm', 0, 'pdf', 'SomeModule.pdf';
Finally, you can pass additional arguments to the POD formatter that handles the requested format.
my @options = ( 'release' => 1.03, 'section' => 8 ); # options for Pod::Man readme_from 'lib/Some/Module.pm', 1, 'man', undef, @options;
But instead of passing this long list of optional arguments to readme_from, you should probably pass these arguments as a named hashref for clarity.
my @options = ( 'release' => 1.03, 'section' => 8 ); readme_from 'lib/Some/Module.pm', {clean => 1, format => 'man', output_file => undef, options => @options};
If you use the all_from command, readme_from will default to that value.
all_from
all_from 'lib/Some/Module.pm'; readme_from; # Create README from lib/Some/Module.pm readme_from '','clean'; # Put a empty string before 'clean'
Chris BinGOs Williams
BinGOs
Copyright © Chris Williams
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.
Module::Install
Pod::Text
Pod::Html
Pod::Man
App::pod2pdf
To install Module::Install::ReadmeFromPod, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Module::Install::ReadmeFromPod
CPAN shell
perl -MCPAN -e shell install Module::Install::ReadmeFromPod
For more information on module installation, please visit the detailed CPAN module installation guide.