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 files, use a variation of the boilerplate shown in the L section above. -For information about the POD format, see L. +=head1 POD FORMAT + +For general information about the POD format, see L. + +podwrapper.pl has a couple of extensions for including files: + +=over 4 + +=item C<__INCLUDE:F__> + +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__> + +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 +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 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: $!"; $_ = ; 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 () { $r .= " $_";