impodulate -- turn Perl-and-POD into all POD
% cat Foo.pm
use strict;
package Foo;
=head1 NAME
Foo -- woozle
=cut
sub fooify {
(rand() < .5) ? "Foo!" : "Bar!";
}
% impodulate Foo.pm > code_in_pod.pod
% cat code_in_pod.pod
=pod
. use strict;
. package Foo;
=head1 NAME
Foo -- woozle
. sub fooify {
. (rand() < .5) ? "Foo!" : "Bar!";
. }
% perldoc code_in_pod.pod
[...]
All the not-POD parts of Foo.pm have been turned into POD verbatim paragraphs in code_in_pod.pod.
This program is so you can look at Perl files, with the POD bits formatted as POD, but the Perl bits formatted as Perl.
Michael Schwern said he liked the feature of MacPerl's Shuck that allows you to see Perl files that way, and that gave me the idea to write this program.
-tnumber : Sets tab expansion to number spaces. Default is 8.
POD generated by impodulate might be invalid. Here's how to write POD-and-code that is valid when fed thru impodulate:
Make sure your file starts with:
=head1 NAME
Stuff -- thingy
=cut
... and then the usual stuff.
(Many POD formatters require the first POD section in a file to be a "=head1 NAME". If you manage this, then just edit the output of impodulate, to move the "=head1 NAME" to the top.)
And don't do this:
=head1 Stuff
This module does stuff:
=over
=cut
...code...
=item Thing
Thing with the stuff.
=cut
When run, the stuff in "...code..." ends up being a paragraph between "=over" and "=item", and that's unacceptable to many POD processors.
Copyright (c) 2001 Sean M. Burke. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
Sean M. Burke, sburke@cpan.org