Thursday, August 16, 2007

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 script :


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

: <<'=cut'

=head1 NAME - Example shell script with embedded POD documentation


   : <<=cut
   Your POD documentation


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


To add this to your man pages:

pod2man >/usr/local/share/man/man1/

Use pod2html to have HTML output.

Labels: , , , , ,