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 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.

Labels: , , , , ,

6 Comments:

Anonymous Anonymous said...

Awesome! You are a life saver :-)

Many thanks indeed for this tip.

03 December, 2007 21:52  
Anonymous Anonymous said...

Huzzah! Great tip!

25 February, 2008 21:36  
Blogger Will said...

This is a great tip!

29 June, 2009 09:15  
Blogger sysprv said...

Clever :)

16 November, 2010 10:27  
Blogger Ani said...

Amazing! this is cool! :) started using right away ...

08 January, 2015 09:23  
Blogger sufferupagus said...

:<<'=cut' would be better if you don't want text inside `...` or $(...) to be executed when the script runs.

also this tip works for ksh/pdksh

25 January, 2017 05:40  

Post a Comment

<< Home