Improve --help switch output for pacman contrib and pacman scripts

Unify the formatting of the --help switch for pacman utils, if it exists.
All of the pacman utils will now output help text using the following
format:

  util-name (pacman) v<pacman version>

  one line description of util's purpose

  Usage: util-name [options]

    -b, --bar      whatever --bar does
    -f, --foo      whatever --foo does
    -h, --help     display this help message

Reported-by: Karol Błażewicz <karol.blazewicz at gmail.com>
Signed-off-by: Jason St. John <jstjohn@purdue.edu>

14 files changed, 99 insertions, 54 deletions

diff --git a/contrib/bacman.sh.in b/contrib/bacman.sh.in
index 74a83bc9..a20c5e7e 100644
--- a/contrib/bacman.sh.in
+++ b/contrib/bacman.sh.in
@@ -37,9 +37,13 @@ m4_include(../scripts/library/output_format.sh)
 # User Friendliness
 #
 usage() {
-	echo "This program recreates a package using pacman's db and system files"
-	echo "Usage:   $myname [--nocolor] [--pacnew] <installed package name>"
-	echo "Example: $myname kernel26"
+	echo "${myname} (pacman) v${myver}"
+	echo
+	echo "Recreate a package using pacman's database and system files"
+	echo
+	echo "Usage: ${myname} [--nocolor] [--pacnew] <installed package name>"
+	echo
+	echo "Example: ${myname} linux-headers"
 }
 
 version() {
diff --git a/contrib/checkupdates.sh.in b/contrib/checkupdates.sh.in
index 48ceff94..413b78ac 100644
--- a/contrib/checkupdates.sh.in
+++ b/contrib/checkupdates.sh.in
@@ -18,10 +18,17 @@
 #   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #
 
+declare -r myname='checkupdates'
+declare -r myver='@PACKAGE_VERSION@'
+
 if (( $# > 0 )); then
-	echo "checkupdates: Safely print a list of pending updates."
-	echo "Use: checkupdates"
-	echo "Export the 'CHECKUPDATES_DB' variable to change the path of the temporary database."
+	echo "${myname} (pacman) v${myver}"
+	echo
+	echo "Safely print a list of pending updates"
+	echo
+	echo "Usage: ${myname}"
+	echo
+	echo 'Note: Export the "CHECKUPDATES_DB" variable to change the path of the temporary database.'
 	exit 0
 fi
 
diff --git a/contrib/paccache.sh.in b/contrib/paccache.sh.in
index 6b8df25e..10eab21e 100644
--- a/contrib/paccache.sh.in
+++ b/contrib/paccache.sh.in
@@ -152,27 +152,27 @@ summarize() {
 
 usage() {
 	cat <<EOF
-usage: $myname <operation> [options] [targets...]
+${myname} (pacman) v${myver}
 
-$myname is a flexible pacman cache cleaning utility, which has numerous
-options to help control how much, and what, is deleted from any directory
-containing pacman package tarballs.
+A flexible pacman cache cleaning utility.
+
+Usage: ${myname} <operation> [options] [targets...]
 
   Operations:
     -d, --dryrun          perform a dry run, only finding candidate packages.
-    -m, --move <dir>      move candidate packages to 'movedir'.
+    -m, --move <dir>      move candidate packages to "movedir".
     -r, --remove          remove candidate packages.
 
   Options:
-    -a, --arch <arch>     scan for 'arch' (default: all architectures).
-    -c, --cachedir <dir>  scan 'cachedir' for packages.
+    -a, --arch <arch>     scan for "arch" (default: all architectures).
+    -c, --cachedir <dir>  scan "cachedir" for packages.
                           (default: @localstatedir@/cache/pacman/pkg).
     -f, --force           apply force to mv(1) and rm(1) operations.
     -h, --help            display this help message and exit.
-    -i, --ignore <pkgs>   ignore 'pkgs', comma separated. Alternatively, specify
-                          '-' to read package names from stdin, newline
+    -i, --ignore <pkgs>   ignore "pkgs", comma-separated. Alternatively, specify
+                          "-" to read package names from stdin, newline-
                           delimited.
-    -k, --keep <num>      keep 'num' of each package in 'cachedir' (default: 3).
+    -k, --keep <num>      keep "num" of each package in "cachedir" (default: 3).
     --nocolor             remove color from output.
     -u, --uninstalled     target uninstalled packages.
     -v, --verbose         increase verbosity. specify up to 3 times.
diff --git a/contrib/pacdiff.sh.in b/contrib/pacdiff.sh.in
index 6e70feeb..1bad0e4b 100644
--- a/contrib/pacdiff.sh.in
+++ b/contrib/pacdiff.sh.in
@@ -33,20 +33,22 @@ m4_include(../scripts/library/output_format.sh)
 
 usage() {
 	cat <<EOF
-$myname is a simple pacnew/pacorig/pacsave updater.
+${myname} (pacman) v${myver}
+
+A simple program to merge or remove pacnew/pacorig/pacsave files.
 
 Usage: $myname [-l | -f | -p] [--nocolor]
 
 Search Options:     select one, default: pacmandb
   -l/--locate       scan using locate
   -f/--find         scan using find
-  -p/--pacmandb     scan active config files from pacman db
+  -p/--pacmandb     scan active config files from pacman database
 
 General Options:
   -o/--output       print files instead of merging them
   --nocolor         remove colors from output
 
-Enviroment Variables:
+Environment Variables:
   DIFFPROG          override the merge program: (default: vimdiff)
   DIFFSEARCHPATH    override the search path. (only when using find)
                     (default: /etc)
diff --git a/contrib/paclist.sh.in b/contrib/paclist.sh.in
index 7883e21b..319dcba9 100644
--- a/contrib/paclist.sh.in
+++ b/contrib/paclist.sh.in
@@ -31,9 +31,13 @@ if ! type gettext &>/dev/null; then
 fi
 
 usage() {
-	printf '%s - List all packages installed from a given repo\n' "$myname"
-	printf 'Usage:   %s <repo>\n' "$myname"
-	printf 'Example: %s testing\n' "$myname"
+	printf "%s (pacman) v%s\n" "${myname}" "myver"
+	echo
+	printf "List all packages installed from a given repository\n" "${myname}"
+	echo
+	printf "Usage: %s <repository>\n" "${myname}"
+	echo
+	printf "Example: %s testing\n" "${myname}"
 }
 
 version() {
diff --git a/contrib/paclog-pkglist.sh.in b/contrib/paclog-pkglist.sh.in
index 9b3abad4..aaa7586e 100644
--- a/contrib/paclog-pkglist.sh.in
+++ b/contrib/paclog-pkglist.sh.in
@@ -25,9 +25,15 @@ export TEXTDOMAINDIR='/usr/share/locale'
 declare logfile=${1:-@localstatedir@/log/pacman.log}
 
 usage() {
-	printf 'usage:   %s [pacman log]\n' "$myname"
-	printf 'example: %s @localstatedir@/log/pacman.log\n' "$myname"
-	printf '\ndefaults to: @localstatedir@/log/pacman.log\n'
+	printf "%s (pacman) v%s\n" "${myname}" "${myver}"
+	echo
+	echo "Parse a log file into a list of currently installed packages"
+	echo
+	printf "Usage: %s [path to pacman log]\n" "${myname}"
+	echo
+	printf "Example: %s @localstatedir@/log/pacman.log\n" "${myname}"
+	echo
+	printf 'Defaults to: @localstatedir@/log/pacman.log'
 }
 
 version() {
diff --git a/contrib/pacscripts.sh.in b/contrib/pacscripts.sh.in
index 62c4e35b..8453f9c8 100644
--- a/contrib/pacscripts.sh.in
+++ b/contrib/pacscripts.sh.in
@@ -46,16 +46,18 @@ error() {
 }
 
 usage() {
-	echo "This program prints out the {pre,post}_{install,remove,upgrade} scripts"
-	echo "of a given package."
-	echo "Usage: $myname pkgname|pkgfile"
+	echo "${myname} (pacman) v${myver}"
 	echo
-	echo " OPTIONS:"
+	echo "Prints the {pre,post}_{install,remove,upgrade} scripts of a given package."
+	echo
+	echo "Usage: ${myname} <pkgname|pkgfile>"
+	echo
+	echo " Options:"
 	echo "  -h, --help                 Print this help message"
 	echo "  -v, --version              Print program name and version"
 	echo
-	echo "Example: $myname gconf-editor"
-	echo "Example: $myname gconf-editor-2.24.1-1-x86_64.pkg.tar.gz"
+	echo "Example: ${myname} gconf-editor"
+	echo "Example: ${myname} gconf-editor-3.0.1-3-x86_64.pkg.tar.xz"
 }
 
 version() {
@@ -70,7 +72,7 @@ spacman() {
 	else
 		if ! type -p sudo; then
 			error "Cannot find the sudo binary! Is sudo installed?"
-			error "Otherwise try to run the program as root"
+			error "Otherwise, try to run the program as root"
 			exit 1
 		else
 			sudo pacman "$@"
diff --git a/contrib/pacsearch.in b/contrib/pacsearch.in
index b1db8abe..624f2010 100644
--- a/contrib/pacsearch.in
+++ b/contrib/pacsearch.in
@@ -28,8 +28,9 @@ my $myname = 'pacsearch';
 my $myver = '@PACKAGE_VERSION@';
 
 sub usage {
-	print "$myname - Add color and install information to a pacman -Ss search\n";
-	print "Usage:   $myname <pattern>\n";
+	print "$myname (pacman) v$myver\n\n";
+	print "Add color and install information to a 'pacman -Ss' search\n\n";
+	print "Usage: $myname <pattern>\n\n";
 	print "Example: $myname ^gnome\n";
 }
 
diff --git a/contrib/pacsysclean.sh.in b/contrib/pacsysclean.sh.in
index 37219ab5..36319215 100644
--- a/contrib/pacsysclean.sh.in
+++ b/contrib/pacsysclean.sh.in
@@ -8,9 +8,12 @@ declare -r myver='@PACKAGE_VERSION@'
 PACMAN_OPTS=
 
 usage() {
-	echo "$myname - Sort installed packages by increasing installed size."
+	echo "${myname} (pacman) v${myver}"
 	echo
-	echo "Usage: $myname [options]"
+	echo "Sort installed packages by increasing installed size. Useful for"
+	echo "system clean-up."
+	echo
+	echo "Usage: ${myname} [options]"
 	echo
 	echo "Options:"
 	echo "  -o <options>     Specify custom pacman query options (e.g., dt)"
@@ -22,7 +25,6 @@ version() {
 	echo 'Copyright (C) 2011 Eric Bélanger <snowmaniscool@gmail.com>'
 }
 
-
 if [ -n "$1" ]; then
 	case "$1" in
 		-o) PACMAN_OPTS="${2}" ;;
diff --git a/contrib/rankmirrors.sh.in b/contrib/rankmirrors.sh.in
index 82bf9ae0..0c4c7345 100644
--- a/contrib/rankmirrors.sh.in
+++ b/contrib/rankmirrors.sh.in
@@ -21,26 +21,31 @@
 # traps interrupt key to spit out pre-interrupt info
 trap finaloutput INT
 
+declare -r myname='rankmirrors'
+declare -r myver='@PACKAGE_VERSION@'
+
 usage() {
-	echo "Usage: rankmirrors [options] MIRRORFILE | URL"
+	echo "${myname} (pacman) v${myver}"
 	echo
 	echo "Ranks pacman mirrors by their connection and opening speed. Pacman mirror"
 	echo "files are located in @sysconfdir@/pacman.d/. It can also rank one mirror if the URL is"
 	echo "provided."
 	echo
+	echo "Usage: ${myname} [options] MIRRORFILE | URL"
+	echo
 	echo "Options:"
 	echo "  --version      show program's version number and exit"
 	echo "  -h, --help     show this help message and exit"
 	echo "  -n NUM         number of servers to output, 0 for all"
 	echo "  -t, --times    only output mirrors and their response times"
-	echo "  -u, --url      test a specific url"
+	echo "  -u, --url      test a specific URL"
 	echo "  -v, --verbose  be verbose in ouptut"
-	echo "  -r, --repo     specify a specific repo name instead of guessing"
+	echo "  -r, --repo     specify a repository name instead of guessing"
 	exit 0
 }
 
 version() {
-	echo "rankmirrors (pacman) @PACKAGE_VERSION@"
+	echo "${myname} (pacman) ${myver}"
 	echo "Copyright (c) 2009 Matthew Bruenig <matthewbruenig@gmail.com>."
 	echo
 	echo "This is free software; see the source for copying conditions."
diff --git a/contrib/updpkgsums.sh.in b/contrib/updpkgsums.sh.in
index 4d35357f..0f52db4c 100644
--- a/contrib/updpkgsums.sh.in
+++ b/contrib/updpkgsums.sh.in
@@ -23,12 +23,16 @@ declare -r myname='updpkgsums'
 declare -r myver='@PACKAGE_VERSION@'
 
 usage() {
-	printf 'usage: %s [buildfile]\n\n' "$myname"
-	printf '    -h, --help        display this help message and exit\n'
-	printf '    -V, --version     display version information and exit\n\n'
-	printf '%s will perform an in place update the checksums in the\n' "$myname"
-	printf 'path specified by [buildfile], defaulting to PKGBUILD in the current\n'
-	printf 'working directory.\n'
+	printf "%s (pacman) v%s\n" "${myname}" "${myver}"
+	echo
+	printf "%s will perform an in place update of the checksums in the\n" "${myname}"
+	echo "path specified by [build file], defaulting to PKGBUILD in the current"
+	echo "working directory."
+	echo
+	printf "Usage: %s [build file]\n" "${myname}"
+	echo
+	echo "    -h, --help        display this help message and exit"
+	echo "    -V, --version     display version information and exit"
 }
 
 version() {
@@ -43,7 +47,7 @@ esac
 
 buildfile=${1:-PKGBUILD}
 if [[ ! -f $buildfile ]]; then
-	printf '==> ERROR: %s not found or is not a file\n' "$buildfile"
+	printf "==> ERROR: %s not found or is not a file\n" "$buildfile"
 	exit 1
 fi
 
diff --git a/scripts/makepkg.sh.in b/scripts/makepkg.sh.in
index c1c09006..28e8e7a4 100644
--- a/scripts/makepkg.sh.in
+++ b/scripts/makepkg.sh.in
@@ -2483,6 +2483,8 @@ m4_include(library/parseopts.sh)
 usage() {
 	printf "makepkg (pacman) %s\n" "$makepkg_version"
 	echo
+	printf -- "$(gettext "Make packages compatible for use with pacman")\n"
+	echo
 	printf -- "$(gettext "Usage: %s [options]")\n" "$0"
 	echo
 	printf -- "$(gettext "Options:")\n"
diff --git a/scripts/pacman-db-upgrade.sh.in b/scripts/pacman-db-upgrade.sh.in
index a1630c52..2b39538e 100644
--- a/scripts/pacman-db-upgrade.sh.in
+++ b/scripts/pacman-db-upgrade.sh.in
@@ -33,8 +33,11 @@ USE_COLOR='y'
 m4_include(library/output_format.sh)
 
 usage() {
-	printf "pacman-db-upgrade (pacman) %s\n\n" "$myver"
-	printf -- "$(gettext "Usage: %s [--nocolor] [pacman_db_root]")\n\n" "$0"
+	printf "pacman-db-upgrade (pacman) %s\n" "${myver}"
+	echo
+	printf -- "$(gettext "Upgrade the local pacman database to a newer format")\n"
+	echo
+	printf -- "$(gettext "Usage: %s [--nocolor] [pacman_db_root]")\n" "$0"
 }
 
 version() {
diff --git a/scripts/pkgdelta.sh.in b/scripts/pkgdelta.sh.in
index 39046b87..cc1f9ac2 100644
--- a/scripts/pkgdelta.sh.in
+++ b/scripts/pkgdelta.sh.in
@@ -46,11 +46,14 @@ m4_include(library/output_format.sh)
 
 # print usage instructions
 usage() {
-	printf "pkgdelta (pacman) %s\n\n" "$myver"
+	printf "pkgdelta (pacman) %s\n" "${myver}"
+	echo
 	printf -- "$(gettext "Usage: pkgdelta [options] <package1> <package2>\n")"
+	echo
 	printf -- "$(gettext "\
-	pkgdelta will create a delta file between two packages.\n\
-This delta file can then be added to a database using repo-add.\n\n")"
+pkgdelta will create a delta file between two packages.\n\
+This delta file can then be added to a database using repo-add.\n")"
+	echo
 	printf -- "$(gettext "Example:  pkgdelta pacman-3.0.0.pkg.tar.gz pacman-3.0.1.pkg.tar.gz")\n"
 	echo
 	printf -- "$(gettext "Options:\n")"
@@ -61,7 +64,7 @@ This delta file can then be added to a database using repo-add.\n\n")"
 }
 
 version() {
-	printf "pkgdelta (pacman) %s\n\n" "$myver"
+	printf "pkgdelta (pacman) %s\n" "$myver"
 	printf -- "$(gettext "\
 Copyright (c) 2009 Xavier Chantry <shiningxc@gmail.com>.\n\n\
 This is free software; see the source for copying conditions.\n\