From b8715bfee6fe11aa1a09397859b55a01bfe33ac7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= <mislav.marohnic@gmail.com>
Date: Thu, 13 Dec 2012 05:48:28 +0100
Subject: [PATCH 1/9] foundation for a help system where each command holds its
 own docs

Docs are comprised from "Usage", "Summary" and "Help" sections, where
"Help" can span multiple commented lines. If it is missing, "Summary" is
shown in its place.

References #204, references #206
---
 libexec/rbenv-commands |  2 +
 libexec/rbenv-help     | 84 ++++++++++++++++++++++++------------------
 libexec/rbenv-rehash   |  2 +
 libexec/rbenv-versions |  2 +
 libexec/rbenv-whence   |  4 +-
 libexec/rbenv-which    |  6 ++-
 6 files changed, 63 insertions(+), 37 deletions(-)

diff --git a/libexec/rbenv-commands b/libexec/rbenv-commands
index 297f8d99..67bc7fb9 100755
--- a/libexec/rbenv-commands
+++ b/libexec/rbenv-commands
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv commands [ --sh | --no-sh ]
+# Summary: List all rbenv commands
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index e1cbaf57..7a710512 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -2,6 +2,51 @@
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
+# content from single commented line marked with a word such as "Usage" or "Summary"
+extract_line() {
+  grep "^# ${1}:" "$2" | head -1 | cut -d ' ' -f3-
+}
+
+# content of multiple consecutive commented lines starting with a word such as "Help"
+extract_section() {
+  sed -En "/^# ${1}: /,/^[^#]/s/^# ?//p" "$2" | sed "1s/${1}: //"
+}
+
+# print aligned command names with help summary
+print_summary() {
+  if [ ! -h "$1" ]; then
+    local summary=$(extract_line Summary "$1")
+    if [ -n "$summary" ]; then
+      local name=$(basename "$1")
+      echo "${name#rbenv-}" | awk '{ printf "   %-14s   ", $1 }'
+      echo -n $summary
+      echo
+    else
+      return 1
+    fi
+  fi
+}
+
+print_help() {
+  local usage="$(extract_line Usage "$1")"
+  local halp="$(extract_section Help "$1")"
+  [ -z "$halp" ] && halp="$(extract_line Summary "$1")"
+
+  if [ -n "$usage" ]; then
+    echo usage: $usage
+    [ -n "$halp" ] && echo && echo "$halp"
+  else
+    echo "Sorry, this command isn't documented yet." >&2
+    return 1
+  fi
+}
+
+print_summaries() {
+  for command in $1; do
+    print_summary "$(command -v rbenv-"$command")"
+  done
+}
+
 print_set_version() {
   echo "<version> should be a string matching a Ruby version known by rbenv."
 
@@ -21,25 +66,11 @@ case "$1" in
 "") echo "usage: rbenv <command> [<args>]
 
 Some useful rbenv commands are:
-   commands      List all rbenv commands
-   rehash        Rehash rbenv shims (run this after installing binaries)
-   global        Set or show the global Ruby version
-   local         Set or show the local directory-specific Ruby version
-   shell         Set or show the shell-specific Ruby version
-   version       Show the current Ruby version
-   versions      List all Ruby versions known by rbenv
-   which         Show the full path for the given Ruby command
-   whence        List all Ruby versions with the given command
+$(print_summaries "commands rehash global local shell version versions which whence")
 
 See 'rbenv help <command>' for information on a specific command.
 For full documentation, see: https://github.com/sstephenson/rbenv#readme"
 ;;
-commands) echo "usage: rbenv commands
-       rbenv commands --sh
-       rbenv commands --no-sh
-
-List all rbenv commands."
-;;
 global) echo "usage: rbenv global <version>
 
 Sets the global Ruby version. You can override the global version at
@@ -71,29 +102,12 @@ project-specific versions and the global version.
 
 $(print_set_version)"
 ;;
-versions) echo "usage: rbenv versions
-       rbenv versions --bare
-
-Lists all Ruby versions known by rbenv."
-;;
-which) echo "usage: rbenv which <command>
-
-Displays the full path to the binary that rbenv will execute when you
-run the given command."
-;;
-whence) echo "usage: rbenv whence <command>
-
-Lists all Ruby versions with the given command installed."
-;;
 *)
   command_path="$(command -v "rbenv-$1" || true)"
   if [ -n "$command_path" ]; then
-    echo "Sorry, the \`$1' command isn't documented yet."
-    echo
-    echo "You can view the command's source here:"
-    echo "$command_path"
-    echo
+    print_help "$command_path"
   else
-    echo "rbenv: no such command \`$1'"
+    echo "rbenv: no such command \`$1'" >&2
+    exit 1
   fi
 esac
diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash
index eebc4d3c..13bd7938 100755
--- a/libexec/rbenv-rehash
+++ b/libexec/rbenv-rehash
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv rehash
+# Summary: Rehash rbenv shims (run this after installing binaries)
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions
index 346800a3..46b8a021 100755
--- a/libexec/rbenv-versions
+++ b/libexec/rbenv-versions
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv versions [--bare]
+# Summary: List all Ruby versions known by rbenv
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence
index 8a926877..5e49d527 100755
--- a/libexec/rbenv-whence
+++ b/libexec/rbenv-whence
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv whence [--path] COMMAND
+# Summary: List all Ruby versions with the given command installed
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -27,7 +29,7 @@ whence() {
 
 RBENV_COMMAND="$1"
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv whence [--path] COMMAND" >&2
+  rbenv-help whence | head -1 >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-which b/libexec/rbenv-which
index 204988b2..3cdddd01 100755
--- a/libexec/rbenv-which
+++ b/libexec/rbenv-which
@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Usage: rbenv which COMMAND
+# Summary: Display full path to a binary
+# Help: Displays the full path to the binary that rbenv will execute when you
+# run the given command.
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -44,7 +48,7 @@ RBENV_VERSION="$(rbenv-version-name)"
 RBENV_COMMAND="$1"
 
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv which COMMAND" >&2
+  rbenv-help which | head -1 >&2
   exit 1
 fi
 

From 4c19dc22d7b1f674058acb95d51bde417dc80a62 Mon Sep 17 00:00:00 2001
From: Sam Stephenson <sam@37signals.com>
Date: Sat, 29 Dec 2012 12:06:20 -0600
Subject: [PATCH 2/9] Improve syntax for inline documentation and allow for
 multi-line usage

---
 libexec/rbenv-commands |   5 +-
 libexec/rbenv-global   |  13 +++
 libexec/rbenv-help     | 195 ++++++++++++++++++++++-------------------
 libexec/rbenv-local    |  19 ++++
 libexec/rbenv-rehash   |   3 +-
 libexec/rbenv-sh-shell |  14 +++
 libexec/rbenv-version  |   2 +
 libexec/rbenv-versions |   3 +-
 libexec/rbenv-whence   |   3 +-
 libexec/rbenv-which    |  10 ++-
 10 files changed, 170 insertions(+), 97 deletions(-)

diff --git a/libexec/rbenv-commands b/libexec/rbenv-commands
index 67bc7fb9..58aab012 100755
--- a/libexec/rbenv-commands
+++ b/libexec/rbenv-commands
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv commands [ --sh | --no-sh ]
-# Summary: List all rbenv commands
+# Summary: List all available rbenv commands
+# Usage: rbenv commands [--sh|--no-sh]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-global b/libexec/rbenv-global
index 2f68f2ec..c003359b 100755
--- a/libexec/rbenv-global
+++ b/libexec/rbenv-global
@@ -1,4 +1,17 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the global Ruby version
+#
+# Usage: rbenv global <version>
+#
+# Sets the global Ruby version. You can override the global version at
+# any time by setting a directory-specific version with `rbenv local'
+# or by setting the `RBENV_VERSION' environment variable.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 7a710512..00eaab15 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -2,112 +2,129 @@
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
-# content from single commented line marked with a word such as "Usage" or "Summary"
-extract_line() {
-  grep "^# ${1}:" "$2" | head -1 | cut -d ' ' -f3-
+command_path() {
+  local command="$1"
+  command -v rbenv-"$command" || command -v rbenv-sh-"$command" || true
 }
 
-# content of multiple consecutive commented lines starting with a word such as "Help"
-extract_section() {
-  sed -En "/^# ${1}: /,/^[^#]/s/^# ?//p" "$2" | sed "1s/${1}: //"
+extract_initial_comment_block() {
+  sed -ne "
+    /^#/ !{
+      q
+    }
+
+    s/^#$/# /
+
+    /^# / {
+      s/^# //
+      p
+    }
+  "
 }
 
-# print aligned command names with help summary
-print_summary() {
-  if [ ! -h "$1" ]; then
-    local summary=$(extract_line Summary "$1")
-    if [ -n "$summary" ]; then
-      local name=$(basename "$1")
-      echo "${name#rbenv-}" | awk '{ printf "   %-14s   ", $1 }'
-      echo -n $summary
-      echo
-    else
-      return 1
-    fi
+collect_documentation() {
+  awk '
+    /^Summary:/ {
+      summary = substr($0, 10)
+      next
+    }
+
+    /^Usage:/ {
+      reading_usage = 1
+      usage = usage "\n" $0
+      next
+    }
+
+    /^( *$|       )/ && reading_usage {
+      usage = usage "\n" $0
+      next
+    }
+
+    /^([^ ]|$)/ {
+      reading_usage = 0
+      help = help "\n" $0
+    }
+
+    function escape(str) {
+      gsub(/[`\\$"]/, "\\\\&", str)
+      return str
+    }
+
+    function trim(str) {
+      gsub(/^\n*/, "", str)
+      gsub(/\n*$/, "", str)
+      return str
+    }
+
+    END {
+      if (usage || summary) {
+        print "summary=\"" escape(summary) "\""
+        print "usage=\"" escape(trim(usage)) "\""
+        print "help=\"" escape(trim(help)) "\""
+      }
+    }
+  '
+}
+
+documentation_for() {
+  local filename="$(command_path "$1")"
+  if [ -n "$filename" ]; then
+    extract_initial_comment_block < "$filename" | collect_documentation
   fi
 }
 
+print_summary() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+
+  if [ -n "$summary" ]; then
+    printf "   %-9s   %s\n" "$command" "$summary"
+  else
+    return 1
+  fi
+}
+
+print_summaries() {
+  for command; do
+    print_summary "$command"
+  done
+}
+
 print_help() {
-  local usage="$(extract_line Usage "$1")"
-  local halp="$(extract_section Help "$1")"
-  [ -z "$halp" ] && halp="$(extract_line Summary "$1")"
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -n "$help" ] || help="$summary"
 
   if [ -n "$usage" ]; then
-    echo usage: $usage
-    [ -n "$halp" ] && echo && echo "$halp"
+    echo "$usage"
+    if [ -n "$help" ]; then
+      echo
+      echo "$help"
+      echo
+    fi
   else
     echo "Sorry, this command isn't documented yet." >&2
     return 1
   fi
 }
 
-print_summaries() {
-  for command in $1; do
-    print_summary "$(command -v rbenv-"$command")"
-  done
-}
-
-print_set_version() {
-  echo "<version> should be a string matching a Ruby version known by rbenv."
-
-  local versions="$(rbenv-versions --bare)"
-  if [ -z "$versions" ]; then
-    echo "There are currently no Ruby versions installed for rbenv."
-  else
-    echo "The currently installed Ruby versions are:"
-    echo "$versions" | sed 's/^/  /'
-  fi
-
+if [ -z "$1" ]; then
+  rbenv---version
+  echo "Usage: rbenv <command> [<args>]"
   echo
-  echo "The special version string 'system' will use your default system Ruby."
-}
-
-case "$1" in
-"") echo "usage: rbenv <command> [<args>]
-
-Some useful rbenv commands are:
-$(print_summaries "commands rehash global local shell version versions which whence")
-
-See 'rbenv help <command>' for information on a specific command.
-For full documentation, see: https://github.com/sstephenson/rbenv#readme"
-;;
-global) echo "usage: rbenv global <version>
-
-Sets the global Ruby version. You can override the global version at
-any time by setting a directory-specific version with \`rbenv local'
-or by setting the RBENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-local) echo "usage: rbenv local <version>
-       rbenv local --unset
-
-Sets the local directory-specific Ruby version by writing the version
-name to a file named '.rbenv-version'.
-
-When you run a Ruby command, rbenv will look for an '.rbenv-version'
-file in the current directory and each parent directory. If no such
-file is found in the tree, rbenv will use the global Ruby version
-specified with \`rbenv global', or the version specified in the
-RBENV_VERSION environment variable.
-
-$(print_set_version)"
-;;
-shell) echo "usage: rbenv shell <version>
-       rbenv shell --unset
-
-Sets a shell-specific Ruby version by setting the 'RBENV_VERSION'
-environment variable in your shell. This version overrides both
-project-specific versions and the global version.
-
-$(print_set_version)"
-;;
-*)
-  command_path="$(command -v "rbenv-$1" || true)"
-  if [ -n "$command_path" ]; then
-    print_help "$command_path"
+  echo "Some useful rbenv commands are:"
+  print_summaries commands rehash global local shell version versions which whence
+  echo
+  echo "See \`rbenv help <command>' for information on a specific command."
+  echo "For full documentation, see: https://github.com/sstephenson/rbenv#readme"
+else
+  command="$1"
+  if [ -n "$(command_path "$command")" ]; then
+    print_help "$command"
   else
-    echo "rbenv: no such command \`$1'" >&2
+    echo "rbenv: no such command \`$command'" >&2
     exit 1
   fi
-esac
+fi
diff --git a/libexec/rbenv-local b/libexec/rbenv-local
index 9b102c5c..a0b3fe76 100755
--- a/libexec/rbenv-local
+++ b/libexec/rbenv-local
@@ -1,4 +1,23 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the local directory-specific Ruby version
+#
+# Usage: rbenv local <version>
+#        rbenv local --unset
+#
+# Sets the local directory-specific Ruby version by writing the version
+# name to a file named `.rbenv-version'.
+#
+# When you run a Ruby command, rbenv will look for an `.rbenv-version'
+# file in the current directory and each parent directory. If no such
+# file is found in the tree, rbenv will use the global Ruby version
+# specified with `rbenv global', or the version specified in the
+# RBENV_VERSION environment variable.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash
index 916323a3..0f147385 100755
--- a/libexec/rbenv-rehash
+++ b/libexec/rbenv-rehash
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv rehash
 # Summary: Rehash rbenv shims (run this after installing binaries)
+# Usage: rbenv rehash
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-sh-shell b/libexec/rbenv-sh-shell
index 34a0a354..d49eaa52 100755
--- a/libexec/rbenv-sh-shell
+++ b/libexec/rbenv-sh-shell
@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Set or show the shell-specific Ruby version
+#
+# Usage: rbenv shell <version>
+#        rbenv shell --unset
+#
+# Sets a shell-specific Ruby version by setting the `RBENV_VERSION'
+# environment variable in your shell. This version overrides both
+# project-specific versions and the global version.
+#
+# <version> should be a string matching a Ruby version known to rbenv.
+# The special version string `system' will use your default system Ruby.
+# Run `rbenv versions' for a list of available Ruby versions.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version b/libexec/rbenv-version
index 7251a4c9..82624ff1 100755
--- a/libexec/rbenv-version
+++ b/libexec/rbenv-version
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Summary: Show the current Ruby version
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions
index 46b8a021..3fcf1ef9 100755
--- a/libexec/rbenv-versions
+++ b/libexec/rbenv-versions
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv versions [--bare]
 # Summary: List all Ruby versions known by rbenv
+# Usage: rbenv versions [--bare]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence
index 5e49d527..5bb499b9 100755
--- a/libexec/rbenv-whence
+++ b/libexec/rbenv-whence
@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
-# Usage: rbenv whence [--path] COMMAND
 # Summary: List all Ruby versions with the given command installed
+# Usage: rbenv whence [--path] COMMAND
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-which b/libexec/rbenv-which
index 3cdddd01..6c62f5ca 100755
--- a/libexec/rbenv-which
+++ b/libexec/rbenv-which
@@ -1,8 +1,12 @@
 #!/usr/bin/env bash
-# Usage: rbenv which COMMAND
-# Summary: Display full path to a binary
-# Help: Displays the full path to the binary that rbenv will execute when you
+#
+# Summary: Display the full path to a binary
+#
+# Usage: rbenv which <command>
+#
+# Displays the full path to the binary that rbenv will execute when you
 # run the given command.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

From e2e474c59ddecadffa7c318ee2fe2f23d4cd25a5 Mon Sep 17 00:00:00 2001
From: Sam Stephenson <sam@37signals.com>
Date: Sat, 29 Dec 2012 12:12:47 -0600
Subject: [PATCH 3/9] Add `rbenv help --usage`

---
 libexec/rbenv-help   | 24 +++++++++++++++++++++---
 libexec/rbenv-whence |  2 +-
 libexec/rbenv-which  |  2 +-
 3 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 00eaab15..fd7f1816 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -110,9 +110,23 @@ print_help() {
   fi
 }
 
-if [ -z "$1" ]; then
-  rbenv---version
+print_usage() {
+  local command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -z "$usage" ] || echo "$usage"
+}
+
+unset usage
+if [ "$1" = "--usage" ]; then
+  usage="1"
+  shift
+fi
+
+if [ -z "$1" ] || [ "$1" == "rbenv" ]; then
+  [ -n "$usage" ] || rbenv---version
   echo "Usage: rbenv <command> [<args>]"
+  [ -z "$usage" ] || exit
   echo
   echo "Some useful rbenv commands are:"
   print_summaries commands rehash global local shell version versions which whence
@@ -122,7 +136,11 @@ if [ -z "$1" ]; then
 else
   command="$1"
   if [ -n "$(command_path "$command")" ]; then
-    print_help "$command"
+    if [ -n "$usage" ]; then
+      print_usage "$command"
+    else
+      print_help "$command"
+    fi
   else
     echo "rbenv: no such command \`$command'" >&2
     exit 1
diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence
index 5bb499b9..6c3486ca 100755
--- a/libexec/rbenv-whence
+++ b/libexec/rbenv-whence
@@ -30,7 +30,7 @@ whence() {
 
 RBENV_COMMAND="$1"
 if [ -z "$RBENV_COMMAND" ]; then
-  rbenv-help whence | head -1 >&2
+  rbenv-help --usage whence >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-which b/libexec/rbenv-which
index 6c62f5ca..7fa32a9f 100755
--- a/libexec/rbenv-which
+++ b/libexec/rbenv-which
@@ -52,7 +52,7 @@ RBENV_VERSION="$(rbenv-version-name)"
 RBENV_COMMAND="$1"
 
 if [ -z "$RBENV_COMMAND" ]; then
-  rbenv-help which | head -1 >&2
+  rbenv-help --usage which >&2
   exit 1
 fi
 

From 57df94573846567a5da0608acc916783c7813a24 Mon Sep 17 00:00:00 2001
From: Sam Stephenson <sam@37signals.com>
Date: Sat, 29 Dec 2012 12:19:06 -0600
Subject: [PATCH 4/9] Don't print version before help summary (bare `rbenv`
 already does this)

---
 libexec/rbenv-help | 1 -
 1 file changed, 1 deletion(-)

diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index fd7f1816..d43782c4 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -124,7 +124,6 @@ if [ "$1" = "--usage" ]; then
 fi
 
 if [ -z "$1" ] || [ "$1" == "rbenv" ]; then
-  [ -n "$usage" ] || rbenv---version
   echo "Usage: rbenv <command> [<args>]"
   [ -z "$usage" ] || exit
   echo

From 2b21e22e976ae905bb80585ccfe9a57e1dcc64de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= <mislav.marohnic@gmail.com>
Date: Sat, 29 Dec 2012 22:03:04 +0100
Subject: [PATCH 5/9] display help for commands that have Summary but not Usage

A command doesn't have to specify Usage docs if it doesn't accept any
arguments. The default usage for a command will be printed as:

    Usage: rbenv ${command}
---
 libexec/rbenv-help   | 8 ++++++--
 libexec/rbenv-rehash | 1 -
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index d43782c4..3bba20ad 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -97,8 +97,12 @@ print_help() {
   eval "$(documentation_for "$command")"
   [ -n "$help" ] || help="$summary"
 
-  if [ -n "$usage" ]; then
-    echo "$usage"
+  if [ -n "$usage" -o -n "$summary" ]; then
+    if [ -n "$usage" ]; then
+      echo "$usage"
+    else
+      echo "Usage: rbenv ${command}"
+    fi
     if [ -n "$help" ]; then
       echo
       echo "$help"
diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash
index 0f147385..a50819dd 100755
--- a/libexec/rbenv-rehash
+++ b/libexec/rbenv-rehash
@@ -1,6 +1,5 @@
 #!/usr/bin/env bash
 # Summary: Rehash rbenv shims (run this after installing binaries)
-# Usage: rbenv rehash
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

From 5cc6b0e3d3d9559b3134a42f02ac3ca3be752790 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= <mislav.marohnic@gmail.com>
Date: Sat, 29 Dec 2012 22:48:28 +0100
Subject: [PATCH 6/9] allow indented lines in help text

Before, lines of help that were indented were stripped away.
---
 libexec/rbenv-help | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 3bba20ad..8f90e2b5 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -40,7 +40,7 @@ collect_documentation() {
       next
     }
 
-    /^([^ ]|$)/ {
+    {
       reading_usage = 0
       help = help "\n" $0
     }

From 3436bddaea90ff8ee403530891f836b2719dbf7d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohnic=CC=81?= <mislav.marohnic@gmail.com>
Date: Sat, 29 Dec 2012 23:34:53 +0100
Subject: [PATCH 7/9] new-style documentation for most commands

---
 libexec/rbenv---version          |  9 +++++++++
 libexec/rbenv-completions        |  4 +++-
 libexec/rbenv-exec               | 16 +++++++++++++++-
 libexec/rbenv-help               | 12 ++++++++++++
 libexec/rbenv-hooks              |  5 ++++-
 libexec/rbenv-init               |  4 ++++
 libexec/rbenv-prefix             |  6 ++++++
 libexec/rbenv-root               |  1 +
 libexec/rbenv-shims              |  3 +++
 libexec/rbenv-version            |  5 ++++-
 libexec/rbenv-version-file       |  1 +
 libexec/rbenv-version-file-read  |  1 +
 libexec/rbenv-version-file-write |  4 +++-
 libexec/rbenv-version-name       |  1 +
 libexec/rbenv-version-origin     |  1 +
 libexec/rbenv-versions           |  4 +++-
 libexec/rbenv-whence             |  2 +-
 libexec/rbenv-which              |  2 +-
 18 files changed, 73 insertions(+), 8 deletions(-)

diff --git a/libexec/rbenv---version b/libexec/rbenv---version
index aa9b829d..7d65d41d 100755
--- a/libexec/rbenv---version
+++ b/libexec/rbenv---version
@@ -1,4 +1,13 @@
 #!/usr/bin/env bash
+# Summary: Display the version of rbenv
+#
+# Displays the current revision info of rbenv from git if available, or falls
+# back to the version of the last release.
+#
+# The format of the git revision is:
+#   ${version}-${num_commits}-g${git_sha}
+# where `num_commits` is the number of commits since `version` was tagged.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-completions b/libexec/rbenv-completions
index 4bc21a3c..d5cbac32 100755
--- a/libexec/rbenv-completions
+++ b/libexec/rbenv-completions
@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
+# Usage: rbenv completions COMMAND [arg1 arg2...]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
 COMMAND="$1"
 if [ -z "$COMMAND" ]; then
-  echo "usage: rbenv completions COMMAND [arg1 arg2...]" >&2
+  rbenv-help --usage completions >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-exec b/libexec/rbenv-exec
index 5c1aacd8..23b75d82 100755
--- a/libexec/rbenv-exec
+++ b/libexec/rbenv-exec
@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Run an executable with the right Ruby version
+#
+# Usage: rbenv exec COMMAND [arg1 arg2...]
+#
+# Runs an executable by first preparing PATH so that the selected Ruby version
+# is prepended to it.
+#
+# For example, doing:
+#   RBENV_VERSION=1.9.3-p327 rbenv exec bundle install
+#
+# has an effect is if this was done:
+#   PATH=~/.rbenv/versions/1.9.3-p327:"$PATH" bundle install
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -11,7 +25,7 @@ export RBENV_VERSION="$(rbenv-version-name)"
 RBENV_COMMAND="$1"
 
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv exec COMMAND [arg1 arg2...]" >&2
+  rbenv-help --usage exec >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 8f90e2b5..cdb37100 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -1,4 +1,16 @@
 #!/usr/bin/env bash
+#
+# Summary: Display help for a command
+#
+# Usage: rbenv help [--usage] COMMAND
+#
+# Parses and displays help contents from a command's source file.
+#
+# A command is considered documented if it starts with a comment block that has
+# at least one of the following sections: `Summary' and `Usage'. Usage
+# instructions can span multiple lines as long as subsequent lines are indented.
+# Everything else in the comment is considered to be regular help contents.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-hooks b/libexec/rbenv-hooks
index 47ee910a..3221c6ff 100755
--- a/libexec/rbenv-hooks
+++ b/libexec/rbenv-hooks
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List hook scripts for a rbenv command
+# Usage: rbenv hooks COMMAND
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -12,7 +15,7 @@ fi
 
 RBENV_COMMAND="$1"
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv hooks COMMAND" >&2
+  rbenv-help --usage hooks >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-init b/libexec/rbenv-init
index 16916cd5..6d53a23e 100755
--- a/libexec/rbenv-init
+++ b/libexec/rbenv-init
@@ -1,4 +1,8 @@
 #!/usr/bin/env bash
+# Summary: Configure shell environment for rbenv
+# Usage: rbenv init [SHELL]
+#        rbenv init - [--no-rehash] [SHELL]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-prefix b/libexec/rbenv-prefix
index 1762f23e..f68f1496 100755
--- a/libexec/rbenv-prefix
+++ b/libexec/rbenv-prefix
@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+# Summary: Display prefix for a Ruby version
+# Usage: rbenv prefix [<version>]
+#
+# Displays the directory where a Ruby version is installed. If no version is
+# given, it uses the currently selected version.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-root b/libexec/rbenv-root
index cf02c058..e632d9d1 100755
--- a/libexec/rbenv-root
+++ b/libexec/rbenv-root
@@ -1,2 +1,3 @@
 #!/usr/bin/env bash
+# Summary: Display rbenv directory where versions and shims are kept
 echo $RBENV_ROOT
diff --git a/libexec/rbenv-shims b/libexec/rbenv-shims
index 6691e60d..713ca5ab 100755
--- a/libexec/rbenv-shims
+++ b/libexec/rbenv-shims
@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List existing rbenv shims
+# Usage: rbenv shims [--short]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version b/libexec/rbenv-version
index 82624ff1..9ec7ac91 100755
--- a/libexec/rbenv-version
+++ b/libexec/rbenv-version
@@ -1,5 +1,8 @@
 #!/usr/bin/env bash
-# Summary: Show the current Ruby version
+# Summary: Show the current Ruby version and its origin
+#
+# Shows the current Ruby version and where it's set from. To obtain only the
+# version string, use `rbenv version-name'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-version-file b/libexec/rbenv-version-file
index e9451f42..1beea0f0 100755
--- a/libexec/rbenv-version-file
+++ b/libexec/rbenv-version-file
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Detect the file that sets the current rbenv version
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version-file-read b/libexec/rbenv-version-file-read
index d6027c4c..518bc477 100755
--- a/libexec/rbenv-version-file-read
+++ b/libexec/rbenv-version-file-read
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Usage: rbenv version-file-read FILE
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version-file-write b/libexec/rbenv-version-file-write
index def9465a..da6a1c9a 100755
--- a/libexec/rbenv-version-file-write
+++ b/libexec/rbenv-version-file-write
@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv version-file-write FILENAME VERSION
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -6,7 +8,7 @@ RBENV_VERSION_FILE="$1"
 RBENV_VERSION="$2"
 
 if [ -z "$RBENV_VERSION" ] || [ -z "$RBENV_VERSION_FILE" ]; then
-  echo "usage: rbenv version-file-write FILENAME VERSION" >&2
+  rbenv-help --usage version-file-write >&2
   exit 1
 fi
 
diff --git a/libexec/rbenv-version-name b/libexec/rbenv-version-name
index f65fa1d4..cd1d18fd 100755
--- a/libexec/rbenv-version-name
+++ b/libexec/rbenv-version-name
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Show the current Ruby version
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version-origin b/libexec/rbenv-version-origin
index 9b029b0c..ceef0f9d 100755
--- a/libexec/rbenv-version-origin
+++ b/libexec/rbenv-version-origin
@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Show where the current Ruby version is set from
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-versions b/libexec/rbenv-versions
index 3fcf1ef9..5bfa72e9 100755
--- a/libexec/rbenv-versions
+++ b/libexec/rbenv-versions
@@ -1,6 +1,8 @@
 #!/usr/bin/env bash
-# Summary: List all Ruby versions known by rbenv
+# Summary: List all Ruby versions available to rbenv
 # Usage: rbenv versions [--bare]
+#
+# Lists all Ruby versions found in `$RBENV_ROOT/versions/*'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-whence b/libexec/rbenv-whence
index 6c3486ca..822ae0e4 100755
--- a/libexec/rbenv-whence
+++ b/libexec/rbenv-whence
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: List all Ruby versions with the given command installed
+# Summary: List all Ruby versions that contain the given executable
 # Usage: rbenv whence [--path] COMMAND
 
 set -e
diff --git a/libexec/rbenv-which b/libexec/rbenv-which
index 7fa32a9f..fe8cc286 100755
--- a/libexec/rbenv-which
+++ b/libexec/rbenv-which
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# Summary: Display the full path to a binary
+# Summary: Display the full path to an executable
 #
 # Usage: rbenv which <command>
 #

From 19666f25986f27f9610570ac9000c68fd605aad1 Mon Sep 17 00:00:00 2001
From: Sam Stephenson <sam@37signals.com>
Date: Sat, 29 Dec 2012 21:50:38 -0600
Subject: [PATCH 8/9] Wrap documentation comments at 70 columns

---
 libexec/rbenv---version | 7 ++++---
 libexec/rbenv-exec      | 4 ++--
 libexec/rbenv-help      | 9 +++++----
 libexec/rbenv-prefix    | 4 ++--
 libexec/rbenv-version   | 4 ++--
 5 files changed, 15 insertions(+), 13 deletions(-)

diff --git a/libexec/rbenv---version b/libexec/rbenv---version
index 7d65d41d..c1313e45 100755
--- a/libexec/rbenv---version
+++ b/libexec/rbenv---version
@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
 # Summary: Display the version of rbenv
 #
-# Displays the current revision info of rbenv from git if available, or falls
-# back to the version of the last release.
+# Displays the current revision info of rbenv from git if available,
+# or falls back to the version of the last release.
 #
 # The format of the git revision is:
 #   ${version}-${num_commits}-g${git_sha}
-# where `num_commits` is the number of commits since `version` was tagged.
+# where `num_commits` is the number of commits since `version` was
+# tagged.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-exec b/libexec/rbenv-exec
index 23b75d82..60880704 100755
--- a/libexec/rbenv-exec
+++ b/libexec/rbenv-exec
@@ -4,8 +4,8 @@
 #
 # Usage: rbenv exec COMMAND [arg1 arg2...]
 #
-# Runs an executable by first preparing PATH so that the selected Ruby version
-# is prepended to it.
+# Runs an executable by first preparing PATH so that the selected Ruby
+# version is prepended to it.
 #
 # For example, doing:
 #   RBENV_VERSION=1.9.3-p327 rbenv exec bundle install
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index cdb37100..0c39b696 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -6,10 +6,11 @@
 #
 # Parses and displays help contents from a command's source file.
 #
-# A command is considered documented if it starts with a comment block that has
-# at least one of the following sections: `Summary' and `Usage'. Usage
-# instructions can span multiple lines as long as subsequent lines are indented.
-# Everything else in the comment is considered to be regular help contents.
+# A command is considered documented if it starts with a comment block
+# that has at least one of the following sections: `Summary' and
+# `Usage'. Usage instructions can span multiple lines as long as
+# subsequent lines are indented.  Everything else in the comment is
+# considered to be regular help contents.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-prefix b/libexec/rbenv-prefix
index f68f1496..0b16fd9e 100755
--- a/libexec/rbenv-prefix
+++ b/libexec/rbenv-prefix
@@ -2,8 +2,8 @@
 # Summary: Display prefix for a Ruby version
 # Usage: rbenv prefix [<version>]
 #
-# Displays the directory where a Ruby version is installed. If no version is
-# given, it uses the currently selected version.
+# Displays the directory where a Ruby version is installed. If no
+# version is given, it uses the currently selected version.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-version b/libexec/rbenv-version
index 9ec7ac91..40d15392 100755
--- a/libexec/rbenv-version
+++ b/libexec/rbenv-version
@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
 # Summary: Show the current Ruby version and its origin
 #
-# Shows the current Ruby version and where it's set from. To obtain only the
-# version string, use `rbenv version-name'.
+# Shows the current Ruby version and where it's set from. To obtain
+# only the version string, use `rbenv version-name'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x

From 37eca782cc828fa0d4470e300d1411964a2ca6ef Mon Sep 17 00:00:00 2001
From: Sam Stephenson <sam@37signals.com>
Date: Sat, 29 Dec 2012 22:05:04 -0600
Subject: [PATCH 9/9] Documentation tweaks

---
 libexec/rbenv---version          |  6 +++---
 libexec/rbenv-completions        |  2 +-
 libexec/rbenv-exec               | 14 +++++++-------
 libexec/rbenv-help               |  8 ++++----
 libexec/rbenv-init               |  5 ++---
 libexec/rbenv-prefix             |  3 ++-
 libexec/rbenv-rehash             |  2 +-
 libexec/rbenv-root               |  2 +-
 libexec/rbenv-version            |  5 +++--
 libexec/rbenv-version-file-read  |  2 +-
 libexec/rbenv-version-file-write |  2 +-
 libexec/rbenv-version-origin     |  2 +-
 12 files changed, 27 insertions(+), 26 deletions(-)

diff --git a/libexec/rbenv---version b/libexec/rbenv---version
index c1313e45..222ad004 100755
--- a/libexec/rbenv---version
+++ b/libexec/rbenv---version
@@ -1,11 +1,11 @@
 #!/usr/bin/env bash
 # Summary: Display the version of rbenv
 #
-# Displays the current revision info of rbenv from git if available,
-# or falls back to the version of the last release.
+# Displays the version number of this rbenv release, including the
+# current revision from git, if available.
 #
 # The format of the git revision is:
-#   ${version}-${num_commits}-g${git_sha}
+#   <version>-<num_commits>-<git_sha>
 # where `num_commits` is the number of commits since `version` was
 # tagged.
 
diff --git a/libexec/rbenv-completions b/libexec/rbenv-completions
index d5cbac32..2cc14e67 100755
--- a/libexec/rbenv-completions
+++ b/libexec/rbenv-completions
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv completions COMMAND [arg1 arg2...]
+# Usage: rbenv completions <command> [arg1 arg2...]
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-exec b/libexec/rbenv-exec
index 60880704..45dbbf80 100755
--- a/libexec/rbenv-exec
+++ b/libexec/rbenv-exec
@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 #
-# Summary: Run an executable with the right Ruby version
+# Summary: Run an executable with the selected Ruby version
 #
-# Usage: rbenv exec COMMAND [arg1 arg2...]
+# Usage: rbenv exec <command> [arg1 arg2...]
 #
 # Runs an executable by first preparing PATH so that the selected Ruby
-# version is prepended to it.
+# version's `bin' directory is at the front.
 #
-# For example, doing:
-#   RBENV_VERSION=1.9.3-p327 rbenv exec bundle install
+# For example, if the currently selected Ruby version is 1.9.3-p327:
+#   rbenv exec bundle install
 #
-# has an effect is if this was done:
-#   PATH=~/.rbenv/versions/1.9.3-p327:"$PATH" bundle install
+# is equivalent to:
+#   PATH="$RBENV_ROOT/versions/1.9.3-p327/bin:$PATH" bundle install
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-help b/libexec/rbenv-help
index 0c39b696..e42a123a 100755
--- a/libexec/rbenv-help
+++ b/libexec/rbenv-help
@@ -7,10 +7,10 @@
 # Parses and displays help contents from a command's source file.
 #
 # A command is considered documented if it starts with a comment block
-# that has at least one of the following sections: `Summary' and
-# `Usage'. Usage instructions can span multiple lines as long as
-# subsequent lines are indented.  Everything else in the comment is
-# considered to be regular help contents.
+# that has a `Summary:' or `Usage:' section. Usage instructions can
+# span multiple lines as long as subsequent lines are indented.
+# The remainder of the comment block is displayed as extended
+# documentation.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-init b/libexec/rbenv-init
index 6d53a23e..0ae9cf47 100755
--- a/libexec/rbenv-init
+++ b/libexec/rbenv-init
@@ -1,7 +1,6 @@
 #!/usr/bin/env bash
-# Summary: Configure shell environment for rbenv
-# Usage: rbenv init [SHELL]
-#        rbenv init - [--no-rehash] [SHELL]
+# Summary: Configure the shell environment for rbenv
+# Usage: eval "$(rbenv init - [--no-rehash] [<shell>])"
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-prefix b/libexec/rbenv-prefix
index 0b16fd9e..a0aebab2 100755
--- a/libexec/rbenv-prefix
+++ b/libexec/rbenv-prefix
@@ -3,7 +3,8 @@
 # Usage: rbenv prefix [<version>]
 #
 # Displays the directory where a Ruby version is installed. If no
-# version is given, it uses the currently selected version.
+# version is given, `rbenv prefix' displays the location of the
+# currently selected version.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-rehash b/libexec/rbenv-rehash
index a50819dd..aa924efe 100755
--- a/libexec/rbenv-rehash
+++ b/libexec/rbenv-rehash
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: Rehash rbenv shims (run this after installing binaries)
+# Summary: Rehash rbenv shims (run this after installing executables)
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-root b/libexec/rbenv-root
index e632d9d1..64fc90b8 100755
--- a/libexec/rbenv-root
+++ b/libexec/rbenv-root
@@ -1,3 +1,3 @@
 #!/usr/bin/env bash
-# Summary: Display rbenv directory where versions and shims are kept
+# Summary: Display the root directory where versions and shims are kept
 echo $RBENV_ROOT
diff --git a/libexec/rbenv-version b/libexec/rbenv-version
index 40d15392..d1fefcc5 100755
--- a/libexec/rbenv-version
+++ b/libexec/rbenv-version
@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 # Summary: Show the current Ruby version and its origin
 #
-# Shows the current Ruby version and where it's set from. To obtain
-# only the version string, use `rbenv version-name'.
+# Shows the currently selected Ruby version and how it was
+# selected. To obtain only the version string, use `rbenv
+# version-name'.
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-version-file-read b/libexec/rbenv-version-file-read
index 518bc477..69ec78b9 100755
--- a/libexec/rbenv-version-file-read
+++ b/libexec/rbenv-version-file-read
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv version-file-read FILE
+# Usage: rbenv version-file-read <file>
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
diff --git a/libexec/rbenv-version-file-write b/libexec/rbenv-version-file-write
index da6a1c9a..04a0febb 100755
--- a/libexec/rbenv-version-file-write
+++ b/libexec/rbenv-version-file-write
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Usage: rbenv version-file-write FILENAME VERSION
+# Usage: rbenv version-file-write <file> <version>
 
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
diff --git a/libexec/rbenv-version-origin b/libexec/rbenv-version-origin
index ceef0f9d..ae7abf9c 100755
--- a/libexec/rbenv-version-origin
+++ b/libexec/rbenv-version-origin
@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Summary: Show where the current Ruby version is set from
+# Summary: Explain how the current Ruby version is set
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x