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 | 61 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/podwrapper.pl.in b/podwrapper.pl.in index 30b0ea7c2..f12a173f2 100755 --- a/podwrapper.pl.in +++ b/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 .= " $_"; -- 2.23.0