Is there a way to re-use text in perlpod documentation? - perl

Question

I have a bunch of repeated text in my perlpod documentation. I could of course create a separate section and reference it, but I was wondering if there's a way to enter the text once somewhere and have it inserted in multiple places?
I don't think this is possible, but thought I'd ask to make sure I'm not missing anything.
Or - perhaps there's a better perl documentation technique?

Answer 1

As you've realised, Pod is (deliberately) a very simple markup language. It doesn't have any particularly complicated feature and one of the things it is missing is a way to embed text from another source.
I'd suggest moving the repeated text to its own section and linking to that section (using L<...>) whenever you want to reference that text.

Answer 2

While Pod markup is meant to be very basic, we don't have to literally type it all by hand.
Text for documentation can be processed like any other text in Perl, using its extensive set of tools, to create a string with pod-formatted text. That string can then be displayed using core Pod::Usage, via a file (that can be removed or kept), or directly by using core Pod::Simple.
Display the Pod string by writing a file
use warnings;
use strict;
use feature 'say';
use Path::Tiny; # convenience, to "spew" a file
my $man = shift;
show_pod() if $man;
say "done $$";
sub show_pod {
require Pod::Usage; Pod::Usage->import('pod2usage');
my $pod_text = make_pod();
my $pod_file = $0 =~ s/\.pl$/.pod/r;
path($pod_file)->spew($pod_text);
pod2usage( -verbose => 2, -input => $pod_file ); # exits by default
}
sub make_pod {
my $repeated = q(lotsa text that gets repeated);
my $doc_text = <<EOD;
=head1 NAME
$0 - demo perldoc
=head1 SYNOP...
Text that is also used elsewhere: $repeated...
=cut
EOD
return $doc_text;
}
The .pod file can be removed: add -exitval => 'NOEXIT' to pod2usage arguments so that it doesn't exit and then remove the file. Or, rather, keep it available for other tools and uses.
I've split the job into two subs as a hint, since it can be useful to be able to only write a .pod file, which can then also be used and viewed in other ways and formats.† This isn't needed to just show docs, and all Pod business can be done in one sub.
Dispaly the Pod string directly
If there is no desire to keep a .pod file around then we don't have to make it
sub show_pod { # The rest of the program same as above
my $pod_text = make_pod();
require Pod::Simple::Text;
Pod::Simple::Text->filter( \$pod_text ); # doesn't exit so add that
}
The ->filter call is a shortcut for creating an object, setting a filehandle, and processing the contents. See docs for a whole lot more.
Either of these approaches provides you with far more flexibility.
Also, while one can indeed solve the repeated text by referencing a separate section with that text, that of course doesn't allow us to use variables or do any Perl processing -- what is all available when you write a Pod string, which is then passed over to perlpod to dispaly.
Note   Use of .pod files affects perldoc. Thanks to #briandfoy for a comment.
For smaller documentation, that has no particular benefit of using separate .pod files, I recommend the second approach, as hinted in the answer. It only differs in how the docs text is organized in the file while still allowing one to process it as any text is normally processed with Perl.
For use cases where .pod files are of good value I still find it an acceptable trade-off but that is my call. Be aware that perldoc is affected and assess how much that matters in your project.
† I use a system like this in a large project, with .pod files in their directory. There is also a simple separate script for overall documentation management, that invokes individual programs with options to write/update their .pods, in HTML with CPAN's style-file, for the main web page. Any program can also simply display its docs in a desired format.