Looking for a clever way to display purpose and usage information to the caller of your shell script? What I describe here is a way to use the documentation that may already be there for just this purpose.
A good programmer puts some effort in good documentation of the software. Scripts should be no exception. So, you start your shell scripts with a couple of comment lines to describe the purpose of the script. You also document any parameters and exit values. Excellent.
Learn how to use this very description at the start of you shell script to display usage information to the user. You might do this when required parameters are missing, or if there is any error in the parameters provided.
Provide a kind of display_help() Function
Every program must verify the parameters received. Every program should display some usage information, if there are any errors in parameters. Call a routine, e.g. display_help(), from any places where you want to display such information. Using a shell here document, we write this function right at the beginning of the script, and make use of the description that might already be there. Those code lines at the beginning are documentation for the programmer looking at the source code, as well as documentation shown to the user. No duplication of text. You still need to keep it up to date, though.
Download link at the bottom of this article.
Start the Script with the Definition of the display_help Function
Firstly, at the very start of your script, just after the She-Bang line (#!/bin/sh in the example below) define your display_help() function as follows:
#!/bin/sh
display_help() { cat << "end-of-help-text"This code defines a shell function called display_help. The input to the first command, cat, is a here document (also heredoc, see https://www.gnu.org/software/bash/manual/bash.html#Here-Documents). The shell will read input from the current source and send each line to the standard input of the command (cat). This is done until a line containing only the heredoc delimiter, end-of-help-text in this example, (with no trailing blanks) is seen. Note that the delimiter must be quoted. Otherwise parameter expansion, command substitution, etc would be applied to the lines. Not what you want in this case.
Insert the Help Text
Next, write the program's description and usage information as a sequence of lines. Keep in mind that the lines will be shown to the user when the display_help function is called from the script, e.g. after a parameter error. Make sure it has all the information the user of the script needs. Start with a short description of the program, then add information about parameters, if any, and their format and value range. Add information about exit conditions, and exit values.
The lines are the body of a here-document, so there is no need to write them as shell comment. The dashed lines in the example below are just for illustration purposes.
/*--- Start of help text ------------------------------------------------------
here goes your description.
add as many line as you need
use empty lines to structure the help text
--- End of help text --------------------------------------------------------*/
Next, end the here-document. It ends when the shell reads a line with noting but the delimiter on it (and no trainling spaces). Note that the delimiter has to be written without quotes on this line.
Terminate the function definition on a line by itself, following the termination of the here-document. You may want to add some comment inbetween thos lines to remember yourself, or someone else, about the purpose of the funny end-of-help-text line.
end-of-help-text
# DO NOT CHANGE the previous, this and the next 2 lines marking the
# end of the "show_help" function
} # End of function "display_help" Include a Call to display_help at Appropriate Places
Finally, include a call to your display_help function at appropriate places, such as after parameter checking if one or more errors have been detected.
if test -z "$1"
then
echo "Error: Parameter 1 is missing."
display_help
exit 1
fi
You will never again have a description that does no longer match the text displayed by the help routine.
Download a fully working, minimal sample here: shell-display-help-sample.txt