Embedding Documentation in Shell Scripts


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,

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

=head1 NAME

MY~PROGRAM--One line description here



=head1 OPTIONS

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


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





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

Get bash Cookbook now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.