Embedding documentation in shell script

A simple hack to embed Perl style POD documentation into shell scripts, so that these bash (or dash) scripts can carry their documentation with them, and updates are done at the same time the script is updated.

The trick is to have the Perl POD section in a bash "Here-Document", right after the null command (no-op) ":".

• Start with : <<=cut
• Write your POD-formatted man page
• That's it. Your POD ends with =cut, which has also been defined as the end of the shell Here-doc

Your script can then be processed with all the usual Perl tools like perldoc, or perl2html, and you can even generate real man pages with pod2man.

As an example, here is the podtest.sh script :

#!/bin/dash

echo This is a plain shell script
echo Followed by POD documentation

: <<'=cut'
=pod

=head1 NAME

   podtest.sh - Example shell script with embedded POD documentation

=head1 SYNOPSIS

   : <<=cut
   =pod
   Your POD documentation
   =cut

=head1 DESCRIPTION

This is a simple way to embed POD documentation into shell scripts.
The documentation can then be shown with C<perldoc scriptname="">,
or even converted to a manual page with C<pod2man>.

=head1 SEE ALSO

L<perlpod|pod::perlpod>, L<perlpodspec|pod::perlpodspec>

=head1 LICENSE

Such a wonderful and unusual idea is certainly protected by many patents...

Or maybe not...

=head1 AUTHOR

B<I> had this great idea...

No rights Reserved

=cut

To add this podtest.sh to your man pages:

pod2man podtest.sh >/usr/local/share/man/man1/podtest.sh.1

Use pod2html podtest.sh to have HTML output.