A pre-release of Pod::Readme is available on CPAN
Last month, I mentioned that I was rewriting Pod::Readme.
Basically, this is a module that allows you to generate a useful README file from a module's POD, besides a simple "pod2text lib/MyModule.pm > README". You can add sections of POD that are only included in the README, like installation prerequisites, and exclude bits that don't belong in the README, like the details of every method.
A pre-release has just been uploaded to CPAN. A short summary of the changes:
- It requires Perl v5.10 or newer, and uses Moose. (This will be rewritten to use Moo in a later release.)
- Instead of using a full POD parser, it implements a simple POD filter and passes that POD to other modules to convert it to text or other formats.
- It supports plugins. This version has plugins to include the module version, a requirements section, and the latest changes.
- Support for generating README files as markdown, POD or other formats has been added.
Feedback would be appreciated, as are patches in the git repository.
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.
Why the dependency on Moose and v5.10? The latter seems rather unnecessary, and the former poorly chosen (lots of dependencies, while using few of it's features: Moo sounds like it would be much more appropriate).
What limitations are there as a result of not using a full POD parser? Are there certain syntax elements that are not recognized, a depth limitation to nested elements, etc?
@leon I am in the process of changing it from Moose to Moo.
As for v5.10, I prefer using some of the features of v5.10 to simplify the code. If I get enough feedback from module authors asking for support of 5.8, I'll look into changing that. (Note: this module is intended for module authors, and shouldn't be necessary just to build a module.)
@ether: Bugs in previous versions were always due to limitations of different POD parsers, which is why I gave up on trying to use one. The current version only cares about =begin/=end and =for elements, really, though it doesn't support nested =begin elements (but is that even valid POD?)
I've thought about using Pod::Abstract instead, but had trouble getting that to work on my development machine.