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
- 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
perl2html, and you can even generate real man pages with
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
pod2html podtest.sh to have HTML output.