The power of literate programming is not that the code and documentation coexist in a file, it's actually that you can structure the file in the most natural way for documentation and then tangle the code from that.
1. Designate that the script is POSIX shell
#!/bin/sh
2. Set reasonable default options
2.1. Exit early
When this option is on, when any command fails (for any of the reasons listed in 2.8.1 Consequences of Shell Errors or by returning an exit status greater than zero), the shell immediately shall exit, as if by executing the exit special built-in utility with no arguments
set -e
2.2. Disable pathname expansion
The shell shall disable pathname expansion.
set -f
2.3. Warn about unset variables
When the shell tries to expand, in a parameter expansion or an arithmetic expansion, an unset parameter other than the '@' and '*' special parameters, it shall write a message to standard error and the expansion shall fail with the consequences specified in 2.8.1 Consequences of Shell Errors.
set -u
3. Add usage
Wrap the messaging in a function so that the caller can control the exit.
usage() { cat <<EOF Justify the expense of a .sh domain by presenting my site as a POSIX shell script. I guess it may as well list the pages. Usage: ./jdb.sh Examples: ./jdb.sh EOF }
4. Support the --help option
Surely this is the most common mechanism of command line tool discovery.
case "$1" in -h|--help) usage exit 0 ;; *) printf "Unknown option: %s\n" "$1" >&2 usage exit 1 ;; esac
5. Check for required arguments
There are none yet.
if [ "$#" -ne 0 ]; then fi
6. List all the HTML pages
set +f ls -1 ./**/*.html ./*.html | sort set -f
7. Convert paths to HTML
(progn (princ "<ul>\n") (dolist (line (split-string data "\n")) (cond ((equal line "") nil) ((equal line "./index.html") nil) (t (princ (format "<li><a href=\"%s\">%s</a></li>\n" line line))))) (princ "</ul>\n"))