How (if at all) can I use Perl POD documentation in a shell script?

Question

I wonder: In Perl POD is recognized partially by the Perl parser, and there is the __END__ keyword to stop Perl parsing. If I want to write POD in a shell script (maybe at the end of the script), can that be done, and if so: How?

Answer 1

A dummy here document can be used in the shell to make it ignore the POD contents, while perldoc will be able to find it. Like this:

#!/bin/bash
#... usual shell commands here ...
echo "Hello, world"
# POD starts here
: <<'__POD__'
=pod

=head1 NAME

The hello-world program...
Blabla..

=cut

__POD__

Doing a sh podtest runs the script. Doing a perldoc podtest shows the doc. Newer versions of perldoc (like 3.28) may require option -F to find the POD.