I'm rather tired of manually editing README files before each release, and do not like using a straight pod2text either, since it contains a lot of superfluous information.>
So I'm thinking about writing a module which parses the POD, automatically includes the non-core requirements and installation instructions, but recognizes special commands on what to include/exclude.
I would like to use POD syntax in a way that deviates from the standard a wee bit:
=begin readme include in README as POD =begin readme pod same as above =begin readme plain include in README as plaintext
=for readme commands commands for the README parser, some examples:
=for readme stop stop including POD in readme =for readme continue continue including readme
=for readme include plain file =for readme include pod file include a plaintext or pod file
=for readme include plain file mark =for readme include pod file mark include a text file until "mark" occurs?
=for readme requirements insert a =head1 REQUIREMENTS section which parses the META.yml for non-core requirements
=for readme install inserts a =head1 INSTALLATION section which can tell if there's Makefile.PL, Build.PL or both; also parses the build_requires section of META.yml and notes these
I'm still thinking about the include file semantics. I like to include changes since the last version in my READMEs and the simplest way to do that is to include a file until some string occurs (so I could put a mark between each version).
(I would add a =for readme history command, but I don't think anyone has a standardised revision file scheme.)
Anyhow, comments would be appreciated!
I think it would be more generally usefull if it were automatic. You can easily subclass Pod::Text to grab just sections you are interested in. You can use ExtUtils::Manifest to read the manifest. Then for each module file, use Module::Info to get dependencies. (See Devel::Required for another approach that unfortunately only works with MakeMaker.)
I'm not sure the primary method of generating it should be POD markup. It's too much work ;)
Randy.
