Split a .pm into a .pod and a .pm
I searched on CPAN but was unable to find a way to split a .pm into a .pod and a .pm, so I made this script:
https://www.lemoda.net/perl/split-pod-from-pm/index.html
It's proved quite handy so far. Recently I took over maintenance of an old module called Net::IPv6Addr as part of the CPAN day. Today I upgraded the documentation a little so that the synopsis example is machine readable:
https://metacpan.org/source/BKB/Net-IPv6Addr-0.7/examples/synopsis.pl
https://metacpan.org/pod/Net::IPv6Addr#SYNOPSIS
Since most people probably don't read the documentation beyond the synopsis, I think it's important to make sure that the code example in the synopsis actually works. There are quite a few modules on CPAN where the synopsis code doesn't work. In the case of Net::IPv6Addr, I even have a test that the synopsis example works:
https://github.com/benkasminbullock/net-ipv6addr/blob/master/t/synopsis.t
https://metacpan.org/source/BKB/Net-IPv6Addr-0.7/t/synopsis.t
Anyway the script above was able to successfully split the .pm file into .pod and .pm such that the tests continued to pass without even needing to edit the output .pm file:
It is surprisingly easy to do that, although the script is likely to break for some cases I haven't thought of yet. In this case, the original author of Net::IPv6Addr had used "=pod" to indicate the start of the documentation, which wasn't in my script until today.
Perl user since about 2006, I have also released some CPAN modules.
`perldoc -u` does half the job.
At the begin of line: = followed by letter a-f, then it is pod. There are much more keywords then in your script. To increase compiletime write pod after __END__ compiler stops reading file at this label.
For giggles, there are two modules of mine that also deal with that kind of stuff:
Test::Pod::Snippets -- which turn code in the SYNOPSIS, and potentially elsewhere in the documentation -- into tests.
Dist::Zilla::Plugin::CoalescePod -- merges related .pm and .pod files together when building the dist.