Rewriting Pod::Readme
Back in 2005, I wrote Pod::Readme. It languished a bit, and David Precious took over maintainership around 2010.
The core idea for this is that README files contain redundant information that is already in the POD, but not everything in the POD should be in the README (such as the details for individual method calls).
It's recommended in Task::Kensho but I'm not aware of many people using it. The few buildtool plugins that generate README files from POD seem to use plain POD-to-text modules.
So I've started re-writing it. My fork is on GitHub. My hope is to have something that module authors will want to use, and will use by default.
Some of the changes I'm working on:
- Using modern Perl (Moose) and requiring Perl 5.10 as a minimum.
- Plugins for inserting the module version, requirements and latest changes: there's a prototype in the git repo, but this will likely change.
- Possible other plugins might be to include the Travis-CI build status.
- Changing the core of it to filter POD rather than parse and translate it (maybe using Pod::Abstract). This will make it easier to generate README files in different formats (POD, Markdown, HTML) instead of just text.
- Configuration that says what sections to include/exclude, as an alternative to saying "=for readme stop" and "=for readme start" in the POD.
- Release separate plugin modules for Module::Install and Dist::Zilla that use it.
I'm open to ideas. So feedback would be appreciated.
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.
I've always taken the readme-from-pod route (which many people seem to do), but have recently been thinking that duplicating the information from the pod as a README file is fairly pointless.
Instead a smaller README file containing the distribution's abstract, links to the documentation on metacpan, and perhaps links to the repository and bug tracker might be a better idea.
The major reason I find for replicating my pod as my README.pod (`podselect lib/MyModule.pm > README.pod`) is that GitHub displays a README.pod on its front page. That is plenty worth the (autogenerated) replication in my mind.
I've been thinking about this too. I'm heading towards a README which has:
I've been thinking that at some point I'll write a DZ plugin to create that for me.
See Dist::Zilla plugins:
@neil Do it! I would use that too!
I see some great ideas here!
Something you might want to look at for inspiration is Mike Doherty's https://metacpan.org/pod/Dist::Zilla::Plugin::InstallGuide (which I use in my plugin bundle) that generates an INSTALL file that contains simple install instructions using various cpan clients (example: https://metacpan.org/source/ETHER/Crypt-Random-Source-0.10/INSTALL). Some of this information could be folded into a README, or the README could simply refer to this document.
One other thing, for Robert -- unless you're doing some really funky things with Moose, I'd suggest using Moo instead, as it is lighter weight and will run faster in a toolchain environment.
Thanks for the feedback.
@Ether: I've thought of using Moo, but I am using traits and MooseX::Object::Pluggable to load plugin-roles. I'm unsure how to do that using Moo.
There is a MooX::Role::Pluggable, which may serve your needs. But it's also not terribly difficult to write this bit of code manually, using Module::Pluggable.
A pre-release has been uploaded to CPAN. See the announcement.