podwrapper: __INCLUDE:file.pod__ and __VERBATIM:file.txt__ in POD files.

The current method of adding multiple --insert or --verbatim
parameters to the podwrapper command is not very easy to use because
it involves modifying the Makefile.am in every place where this is
used, plus under po-docs/$language/Makefile.am.  It's better if the
POD file itself can do the inclusion.

This enhances support so that the special sequences

  __INCLUDE:file.pod__

or

  __VERBATIM:file.txt__

are treated as file inclusion.

The filename must be a plain file and is searched along a path
(supplied by the optional podwrapper --path parameter).  The purpose
of the path is to allow translations to happen more easily.  For
example we can include a particular POD fragment from common/options/
for the English version, but copy the translated file to
po-docs/$language/ for every translated version.

podwrapper.pl.in

@@ -62,7 +62,28 @@ output options are I<--man>, I<--html> and I<--text> (see below).
 In C<Makefile.am> files, use a variation of the boilerplate shown in
 the L</SYNOPSIS> section above.
 
-For information about the POD format, see L<perlpod(1)>.
+=head1 POD FORMAT
+
+For general information about the POD format, see L<perlpod(1)>.
+
+podwrapper.pl has a couple of extensions for including files:
+
+=over 4
+
+=item C<__INCLUDE:F<filename.pod>__>
+
+Include another POD file at the current position (this does not work
+recursively).
+
+The filename is found by searching first the current directory,
+then each I<--path> directory (if used).
+
+=item C<__VERBATIM:F<filename.txt>__>
+
+As above but the file is included as verbatim text, meaning it is
+prefixed by one space before being passed to POD processing.
+
+=back
 
 =head1 OPTIONS
 
@@ -135,6 +156,17 @@ of the input file.
 
 =cut
 
+my @paths;
+
+=item B<--path DIR>
+
+Set the path used for searching for included files (see L</POD FORMAT>
+above).  The current directory is always searched first so you don’t
+need to add that explicitly.  Multiple I<--path> parameters can be
+given, they are searched in order.
+
+=cut
+
 my $section;
 
 =item B<--section N>
@@ -221,6 +253,7 @@ GetOptions ("help|?" => \$help,
             "insert=s" => \@inserts,
             "man=s" => \$man,
             "name=s" => \$name,
+            "path=s" => \@paths,
             "section=s" => \$section,
             "strict-checks!" => \$strict_checks,
             "text=s" => \$text,
@@ -314,6 +347,10 @@ foreach (@inserts) {
         if $content eq $oldcontent;
 }
 
+# Perform INCLUDE directives.
+$content =~ s{__INCLUDE:([-a-z0-9_]+\.pod)__}
+             {read_whole_file ("$1", use_path => 1)}ge;
+
 # Turn external links to this man page into simple cross-section links.
 $content =~ s,\QL<$name($section)/\E,L</,g;
 
@@ -328,6 +365,10 @@ foreach (@verbatims) {
         if $content eq $oldcontent;
 }
 
+# Perform VERBATIM directives.
+$content =~ s{__VERBATIM:([-a-z0-9_]+\.txt)__}
+             {read_verbatim_file ("$1", use_path => 1)}ge;
+
 # There should be no =encoding line present in the content (we will add one).
 die "$progname: $input: =encoding must not be present in input\n"
     if $content =~ /^=encoding/m;
@@ -642,11 +683,27 @@ if ($text) {
     #print "$progname: wrote $text\n";
 }
 
+sub find_file
+{
+    my $input = shift;
+    my $use_path = shift;
+    local $_;
+
+    my @search_path = (".");
+    push (@search_path, @paths) if $use_path;
+    foreach (@search_path) {
+        return "$_/$input" if -f "$_/$input";
+    }
+    die "$progname: $input: cannot find input file on path"
+}
+
 sub read_whole_file
 {
     my $input = shift;
+    my %options = @_;
     local $/ = undef;
 
+    $input = find_file ($input, $options{use_path});
     open FILE, $input or die "$progname: $input: $!";
     $_ = <FILE>;
     close FILE;
@@ -656,8 +713,10 @@ sub read_whole_file
 sub read_verbatim_file
 {
     my $input = shift;
+    my %options = @_;
     my $r = "";
 
+    $input = find_file ($input, $options{use_path});
     open FILE, $input or die "$progname: $input: $!";
     while (<FILE>) {
         $r .= " $_";