Merge pull request #292 from sstephenson/help

help system where each command holds its own docs

libexec/rbenv---version

@@ -1,4 +1,14 @@
 #!/usr/bin/env bash
+# Summary: Display the version of rbenv
+#
+# 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>-<git_sha>
+# where `num_commits` is the number of commits since `version` was
+# tagged.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-commands

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List all available rbenv commands
+# Usage: rbenv commands [--sh|--no-sh]
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

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
 

libexec/rbenv-exec

@@ -1,4 +1,18 @@
 #!/usr/bin/env bash
+#
+# Summary: Run an executable with the selected Ruby version
+#
+# Usage: rbenv exec <command> [arg1 arg2...]
+#
+# Runs an executable by first preparing PATH so that the selected Ruby
+# version's `bin' directory is at the front.
+#
+# For example, if the currently selected Ruby version is 1.9.3-p327:
+#   rbenv exec bundle install
+#
+# is equivalent to:
+#   PATH="$RBENV_ROOT/versions/1.9.3-p327/bin:$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
 

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
 

libexec/rbenv-help

@@ -1,99 +1,164 @@
 #!/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 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
 
-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
-
-  echo
-  echo "The special version string 'system' will use your default system Ruby."
+command_path() {
+  local command="$1"
+  command -v rbenv-"$command" || command -v rbenv-sh-"$command" || true
 }
 
-case "$1" in
-"") echo "usage: rbenv <command> [<args>]
+extract_initial_comment_block() {
+  sed -ne "
+    /^#/ !{
+      q
+    }
 
-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
+    s/^#$/# /
 
-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
+    /^# / {
+      s/^# //
+      p
+    }
+  "
+}
 
-List all rbenv commands."
-;;
-global) echo "usage: rbenv global <version>
+collect_documentation() {
+  awk '
+    /^Summary:/ {
+      summary = substr($0, 10)
+      next
+    }
 
-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.
+    /^Usage:/ {
+      reading_usage = 1
+      usage = usage "\n" $0
+      next
+    }
 
-$(print_set_version)"
-;;
-local) echo "usage: rbenv local <version>
-       rbenv local --unset
+    /^( *$|       )/ && reading_usage {
+      usage = usage "\n" $0
+      next
+    }
 
-Sets the local directory-specific Ruby version by writing the version
-name to a file named '.rbenv-version'.
+    {
+      reading_usage = 0
+      help = help "\n" $0
+    }
 
-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.
+    function escape(str) {
+      gsub(/[`\\$"]/, "\\\\&", str)
+      return str
+    }
 
-$(print_set_version)"
-;;
-shell) echo "usage: rbenv shell <version>
-       rbenv shell --unset
+    function trim(str) {
+      gsub(/^\n*/, "", str)
+      gsub(/\n*$/, "", str)
+      return str
+    }
 
-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.
+    END {
+      if (usage || summary) {
+        print "summary=\"" escape(summary) "\""
+        print "usage=\"" escape(trim(usage)) "\""
+        print "help=\"" escape(trim(help)) "\""
+      }
+    }
+  '
+}
 
-$(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
-  else
-    echo "rbenv: no such command \`$1'"
+documentation_for() {
+  local filename="$(command_path "$1")"
+  if [ -n "$filename" ]; then
+    extract_initial_comment_block < "$filename" | collect_documentation
   fi
-esac
+}
+
+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 command="$1"
+  local summary usage help
+  eval "$(documentation_for "$command")"
+  [ -n "$help" ] || help="$summary"
+
+  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"
+      echo
+    fi
+  else
+    echo "Sorry, this command isn't documented yet." >&2
+    return 1
+  fi
+}
+
+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
+  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
+  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
+    if [ -n "$usage" ]; then
+      print_usage "$command"
+    else
+      print_help "$command"
+    fi
+  else
+    echo "rbenv: no such command \`$command'" >&2
+    exit 1
+  fi
+fi

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
 

libexec/rbenv-init

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: Configure the shell environment for rbenv
+# Usage: eval "$(rbenv init - [--no-rehash] [<shell>])"
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

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
 

libexec/rbenv-prefix

@@ -1,4 +1,11 @@
 #!/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, `rbenv prefix' displays the location of the
+# currently selected version.
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-rehash

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Summary: Rehash rbenv shims (run this after installing executables)
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-root

@@ -1,2 +1,3 @@
 #!/usr/bin/env bash
+# Summary: Display the root directory where versions and shims are kept
 echo $RBENV_ROOT

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
 

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
 

libexec/rbenv-version

@@ -1,4 +1,10 @@
 #!/usr/bin/env bash
+# Summary: Show the current Ruby version and its origin
+#
+# 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
 

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
 

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
 

libexec/rbenv-version-file-write

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Usage: rbenv version-file-write <file> <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
 

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
 

libexec/rbenv-version-origin

@@ -1,4 +1,5 @@
 #!/usr/bin/env bash
+# Summary: Explain how the current Ruby version is set
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 

libexec/rbenv-versions

@@ -1,4 +1,9 @@
 #!/usr/bin/env bash
+# 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
 

libexec/rbenv-whence

@@ -1,4 +1,7 @@
 #!/usr/bin/env bash
+# Summary: List all Ruby versions that contain the given executable
+# Usage: rbenv whence [--path] COMMAND
+
 set -e
 [ -n "$RBENV_DEBUG" ] && set -x
 
@@ -27,7 +30,7 @@ whence() {
 
 RBENV_COMMAND="$1"
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv whence [--path] COMMAND" >&2
+  rbenv-help --usage whence >&2
   exit 1
 fi
 

libexec/rbenv-which

@@ -1,4 +1,12 @@
 #!/usr/bin/env bash
+#
+# Summary: Display the full path to an executable
+#
+# 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
 
@@ -44,7 +52,7 @@ RBENV_VERSION="$(rbenv-version-name)"
 RBENV_COMMAND="$1"
 
 if [ -z "$RBENV_COMMAND" ]; then
-  echo "usage: rbenv which COMMAND" >&2
+  rbenv-help --usage which >&2
   exit 1
 fi