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

@@ -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
 

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

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
 

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
 

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
 

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