Pod::Readme v1.0.2 released
I released a new version of Pod::Readme yesterday. It's a module for "Intelligently generate a README file from POD" by using POD =begin/=end and =for commands to control what parts of a module's POD are included/excluded in the README. For example, you don't need the details of method calls in the README, nor do you need installation instructions in the module's man page.
This is a major rewrite using "modern Perl" that supports the following features:
- Generating a README in various formats such as plaintext, POD, markdown, HTML;
- Support for plugins to add new features.
- Support for (via plugins) inserting the module version, recent changes and prerequisites in the README.
It should still work with existing software that uses it, such as Module::Build.
The next steps will be to write modules to integrate this with other release tools, such as Module::Install or Dist::Zilla.
Feedback as always would be appreciated. The module is on GitHub.
Thanks to everyone who commented on previous blog posts about this, and to CPAN Testers for test reports on previous dev releases.
I was born on the Moon but kidnapped by astronauts and raised in the suburbs of Grumman. Eventually, I drifted along the Gulf Stream to Northern Europe.
Blogs about Perl, Puppet, Linux, programming, and whatever etc.
Integration with Pod::Weaver would be nice -- as that is an existing framework for allowing one to parse and mutate existing pod documents.
I could see Pod::Readme being useful for inserting content that is only useful in a README, rather than in a module's main documentation -- e.g. badges such as:
=begin html
=end html
Regarding dzil support, I think you should patch existing plugins, e.g. Dist::Zilla::Plugin::ReadmeAnyFromPod, instead of writing new ones, so as to make integration with existing distribution build systems much faster.
On an unrelated note to the post (but somewhat related to Ether's comment), is there a Pod::Weaver plugin to let me insert images more easily/conveniently? I've tried manually inserting "=begin HTML" "=end HTML", but Pod::Weaver will sometimes misplace the images to another =head1 section.
Example: https://metacpan.org/pod/release/PERLANCAR/Progress-Any-0.18/lib/Progress/Any.pm (the images should be in the Description section). Compare with the source: https://github.com/perlancar/perl-Progress-Any/blob/master/lib/Progress/Any.pm