Refactor POD documentation

Question

I have some Perl scripts that do almost the same, so the usage documentation is almost similar. For example, prog1.pl could be:

use warnings;
use strict;
use Getopt::Long qw(GetOptions);
use Pod::Usage qw(pod2usage);

my $help;

GetOptions(help=>\$help);
pod2usage( -message => "", -verbose => 2, -output => \*STDERR ) if $help;

__END__

=head1 SYNOPSIS

prog [OPTIONS]

=head1 OPTIONS

=over 4

=item --help

Print this summary.

=back

=head1 DESCRIPTION

A program

Now prog2.pl is a similar script (not shown here). Let's say it has the same documentation for a set of options. For this dummy example, just say that the documentation for the help option is the same for both scripts. How can I refactor that documentation string (that is the string "Print this summary.") such that I do not have to repeat the same string in both prog1.pl and prog2.pl?

Answer 1

Here is a possible solution using Pod::Template. First create a file help.pod with:

=Template help

=item B<--help>

Print this summary.

=back

Then we include this in the program's usage POD documentation using:

use warnings;
use strict;
use Pod::Template;
use File::Spec::Functions qw(catfile);
use Getopt::Long qw(GetOptions);
BEGIN { $Pod::Usage::Formatter = 'Pod::Text::Termcap'; }
use Pod::Usage qw(pod2usage);
use IO::String;

my $parser = Pod::Template->new();
$parser->parse( template => $0 );

my $io = IO::String->new($parser->as_string);
my $help;

GetOptions(help=>\$help);
pod2usage( -message => "", -verbose => 2, -output => \*STDERR, -input => $io) if $help;


__END__

=Include help.pod as Help

=head1 SYNOPSIS

<prog> [OPTIONS]

=head1 OPTIONS

=over 4

=Insert Help->help

=head1 DESCRIPTION

A program

Answer 2

This link refers to two modules that can help you use templates for your POD documentation: Pod::Template and Pod::Weaver.

Generate the POD documentation from templates automatically, and give the filename of the generated POD file to pod2usage using -input option.