4:26 a.m.
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