=for include todo.pod

##</code><code>##

pod2include.pl yourscript.pl |pod2html --title "YourScript"

##</code><code>##

package main;
# Pod Include parser.

=head1 USAGE

	pod2include.pl <filename>

	<fn_switch> = a switch that must preceed the filename for the child
	              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, but 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 suitable  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 STDOUT: $!");

	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;
}