Shell scripts writing
This document describes the best practices to write shell scripts.
Any shell script MUST define different messages levels to inform user about its usage. The best practice is to distinguish three types of messages:
the help string, very short, which may just be a basic reminder of the script synopsis like:
usage: script-name [--option1] [-opt2 =value] [argument1] [argument2] ...
This information should be all visible in a single screen (no pager or scrolling) and may be displayed in case of error or missing option. Its goal is to let the user know in one sight where he is doing wrong and how to correct his command.
the usage string, longer, which may develop the role of each option, its default value, the aliases defined and any information that may help the user to understand how to get the wanted result to work. As this information may be quite long, it is a good idea to open it with programs like
moreto use an internal pager.
the manual information, opened with the
manprogram, which may be the final, literal and complete usage information of the script, with all useful information about its options or arguments, some examples, some links to its sources or updates, a contact information and the way to inform about bugs.
These three informations levels may be accessed from the original script using evident
option or argument like, respectively,
man. The manual page could
follow its own rule as it will often be opened running
man my-manual ; so it is not
mandatory to let it accessible by a script option. In this case, the help or usage strings
MAY inform user about the existence of the manual page.
Copyleft (c) 2008-2014 Les Ateliers Pierrot - Paris, France - Some rights reserved.
Scripts are licensed under the GNU General Public License version 3.
Contents are licensed under the Creative Commons - Attribution - Share Alike - Unported - version 3.0 license.