You want a simple way to provide formatted end-user documentation (e.g., man or html pages) for your script. You want to keep both code and documentation markup in the same file to simplify updates, distribution, and revision control.

Embed documentation in the script using the “do nothing” built-in (a colon) and a here-document:

#!/usr/bin/env bash
# cookbook filename: embedded_documentation

echo 'Shell script code goes here'

# Use a : NOOP and here document to embed documentation,
: <<'END_OF_DOCS'

Embedded documentation such as Perl's Plain Old Documentation (POD),
or even plain text here.

Any accurate documentation is better than none at all.

Sample documentation in Perl's Plain Old Documentation (POD) format adapted from
CODE/ch07/Ch07.001_Best_Ex7.1 and 7.2 in the Perl Best Practices example tarball
"PBP_code.tar.gz".

=head1 NAME

MY~PROGRAM--One line description here

=head1 SYNOPSIS

  MY~PROGRAM [OPTIONS] <file>

=head1 OPTIONS

  -h = This usage.
  -v = Be verbose.
  -V = Show version, copyright and license information.


=head1 DESCRIPTION

A full description of the application and its features.
May include numerous subsections (i.e. =head2, =head3, etc.)


[...]


=head1 LICENSE AND COPYRIGHT

=cut

END_OF_DOCS

Then to extract and use that POD documentation, try these commands.

# To read on-screen, automatically paginated
$ perldoc myscript



# Just the "usage" sections
$ pod2usage myscript



# Create an HTML version
$ pod2html myscript > myscript.html



# Create a man page
$ pod2man myscript > myscript.1

Any plain text documentation or mark-up can be used this way, either interspersed throughout the code or better yet collected at the end of the script. Since computer systems that have bash will probably also have Perl, its Plain Old Documentation (POD) may be a good choice. Perl usually comes with pod2* programs to convert POD to HTML, LaTeX, man, text, and usage files.

Damian Conway’s Perl Best Practices (O’Reilly) has some excellent library module and application documentation templates that could be easily translated into any documentation format including plain text. In that book, see CODE/ch07/Ch07.001_Best_Ex7.1 and 7.2 in the examples tarball (http://examples.oreilly.com/perlbp/PBP_code.tar.gz).

If you keep all of your embedded documentation at the very bottom of the script, you could also add an exit 0 right before the documentation begins. That will simply exit the script rather than force the shell to parse each line looking for the end of the here-document, so it will be a little faster. You need to be careful not override a previous exit code from a command that failed, so consider using set -e. And do not use this trick if you intersperse code and embedded documentation in the body of the script.