Heh. Maybe instead of propagating a duplicate bit of POD, you should pull the common 'dirty hack' code out of each module and put it into a common Utilities module. Then you could document it once (or even fix it once) and use it in all your other modules. Of course, this would require you to edit each of the existing modules, which may be what you're trying to avoid doing. :)

It doesn't really answer your question, but that is what I would do.

Alternatively you could use an embedded hyperlink (L<name>) to point at your external POD.

Unfortunately it is not possible to factor out the "dirty hack" because it is only "morally" the same (abusing a method for something it's not really meant for) but is actually different in practice from module to module.

You could maybe write your own POD formatter to handle a special-case L<> tag as an include.

L<:todo.pod:> #as example
[download]

Might be interpreted as "load todo.pod and include it at this 'link' location" by your formatter. It would be interesting to others as well, no doubt. In any case, you'd have to give some thought to it to be sure that other formatters would render things sanely.

Apart that if I had the time to do so probably I'd rather remove the dirty hacks in the first place, thus eliminating the need for this feature... that definitely seems to me a good idea!

Fine. here then. :) This, saved as pod2include.pl, should allow you to:

=for include todo.pod
[download]

And run

pod2include.pl yourscript.pl |pod2html --title "YourScript"
[download]

Or, in fact, pipe the output to anything that expects POD (not just pod2html). It's a rough hack, but hopefully helpful.

package main;
# Pod Include parser.

=head1 USAGE

    pod2include.pl <filename>

    <fn_switch> = a switch that must preceed the filename for the chil
+d
                  parser. use an empty string (e.g. '') if the parser
              doesn't require one.

=head1 POD CONVENTIONS

This formatter creates a .pod file based on the original input file, b
+ut with
"include" interpolations.  Any line that reads similar to

    =for include filename.pod

will cause the text in C<filename.pod> to be included at that point.  
+Other
formatters will simply skip the file.

The output of this formatter is POD printed to STDOUT.  This is suitab
+le  for
piping to (for example) pod2html.

=cut

use strict; use warnings;
use IO::File;

for (@ARGV) {
    my $source = $_;
    my $IN = IO::File->new($source,'<') or die ("Can't read $source: $
+!");
    my $SCRATCH = IO::File->new(">&STDOUT") or die ("Can't clone STDOU
+T: $!");

    my $p = Parser->new();
    $p->parse_from_filehandle($IN, $SCRATCH);

    $IN->close;
    $SCRATCH->close;
}


#=====================================================================
+=========
package Parser;
use base 'Pod::Parser';

sub preprocess_paragraph {
    my ($self, $content) = @_;
    
    my $text;
    
    if ($content =~ /^=for include (.*)/) {
        my $file = $1;
        $file =~ s/^\s+|\s+$//s;
        if ( -f $file ) {
            open my $SOURCE, '<', $file or die ("Can't source $file: $
+!");
            $text = join('',<$SOURCE>)."\n\n";
            close $SOURCE;
        }
        else {
            $text = "I<Can't find file '$file' during include>.\n\n";
        }
    }
    else {
        $text = Pod::Parser::preprocess_paragraph(@_);
    }
    
    return $text;
}
[download]

<-radiant.matrix->
A collection of thoughts and links from the minds of geeks
The Code that can be seen is not the true Code
I haven't found a problem yet that can't be solved by a well-placed trebuchet