bash Cookbook

Embedding Documentation in Shell Scripts

Problem

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.

Solution

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