Beginnings of 'rvm help'

README

@@ -1,21 +1,58 @@
 
 Usage
 
-  rvm Action [Implementation] [Flags] [Options]
+  rvm [Flags] [Options] Action [Implementation[,Implementation[,...]]
+
+Flags
+
+  --head        - with update, updates rvm to git head version.
+  --rubygems    - with update, updates rubygems for selected ruby
+  --default     - with ruby select, sets a default ruby for new shells.
+  --debug       - Toggle debug mode on for very verbose output.
+  --trace       - Toggle trace mode on to see EVERYTHING rvm is doing.
+  --force       - Force install, removes old install & source before install.
+  --summary     - Used with rubydo to print out a summary of the commands run.
+  --jit         - Used with rubinius install to build with JIT
+  --latest      - with gemset --dump skips version strings for latest gem.
+  --gems        - with uninstall/remove removes gems with the interpreter.
+  --reconfigure - Force ./configure on install even if Makefile already exists.
+
+
+Options
+
+  -v|--version    - Emit rvm version loaded for current shell
+  -l|--level      - patch level to use with rvm use / install
+     --prefix     - path for all rvm files (~/.rvm/), with trailing slash!
+     --bin        - path for binaries to be placed (~/.rvm/bin/)
+     --source     - src directory to use (~/.rvm/src/)
+     --archives   - directory for downladed files (~/.rvm/archives/)
+  -S              - Specify a script file to attempt to load and run (rubydo)
+  -e              - Execute code from the command line.
+  -G|--gems       - root gem path to use
+  --patch         - With MRI Rubies you may specify one or more full paths to patches
+                    for multiple, specify comma separated:
+                    --patch /.../.../a.patch,/.../.../.../b.patch
+  -C|--configure  - custom configure options. If you need to pass several configure
+                    options then append them comma separated: -C --...,--...,--...
+  --nice          - process niceness (for slow computers, default 0)
+  --ree-options   - Options passed directly to ree's './installer' on the command line.
 
 Action
 
   * usage   - show this usage information
   version   - show the rvm version installed in rvm_path
   use       - setup current shell to use a specific ruby version
   reload    - reload rvm source itself (useful after changing rvm source)
-  implode   - removes rvm completely, i.e. everything in ~/.rvm
+  implode   - (seppuku) removes the rvm installation completely.
+              This means everything in $rvm_path (~/.rvm).
+              This does not touch your profiles, which is why
+              there is an if around the sourcing scripts/rvm.
   update    - upgrades rvm to the latest version.
               (If you experience bugs try this first with --head)
   reset     - remove current and stored default & system settings.
               (If you experience odd behavior try this second)
-  info      - show information for current ruby
-  debug     - show environment & configuration information for *current* ruby
+  info      - show the *current* environment information for current ruby
+  debug     - show info plus additional information for common issues
 
   install   - install one or many ruby versions
               See also: http://rvm.beginrescueend.com/rubies/installing/
@@ -43,50 +80,19 @@ Action
 
 Implementation
 
-  * ruby    - MRI/YARV Ruby (The Standard) {1.8.6,1.8.7,1.9.1,1.9.2...}
-  jruby     - JRuby {1.3.1,1.4.0}
-  rbx       - rubinius
-  ree       - ruby Enterprise Edition
-  macruby   - MacRuby (Mac OS X Only)
-  maglev    - GemStone Ruby
-  ironruby  - IronRuby
-  mput      - shyouhei(mput)'s github repository
+  * ruby    - MRI/YARV Ruby (The Gold Standard) {1.8.6,1.8.7,1.9.1,1.9.2...}
+  jruby     - JRuby, Ruby interpreter on the Java Virtual Machine.
+  rbx       - Rubinius
+  ree       - Ruby Enterprise Edition, MRI Ruby with several custom
+              patches for performance, stability, and memory.
+  macruby   - MacRuby, insanely fast, can make real apps (Mac OS X Only).
+  maglev    - GemStone Ruby, awesome persistent ruby object store.
+  ironruby  - IronRuby, NOT supported yet. Looking for volunteers to help.
+  mput      - shyouhei(mput)'s github repository, popular in Japan :)
   system    - use the system ruby (eg. pre-rvm state)
   default   - use rvm set default ruby and system if it hasn't been set.
               http://rvm.beginrescueend.com/rubies/default/
 
-Flags
-
-  --head        - with update, updates rvm to git head version.
-  --rubygems    - with update, updates rubygems for selected ruby
-  --default     - with ruby select, sets a default ruby for new shells.
-  --debug       - Toggle debug mode on for very verbose output.
-  --force       - Force install, removes old install & source before install.
-  --summary     - Used with rubydo to print out a summary of the commands run.
-  --jit         - Used with rubinius install to build with JIT
-  --latest      - with gemset --dump skips version strings for latest gem.
-  --gems        - with uninstall/remove removes gems with the interpreter.
-  --reconfigure - Force ./configure on install even if Makefile already exists.
-
-
-Options
-
-  -v|--version    - Emit rvm version loaded for current shell
-  -h|--help       - Emit this output and exit
-  -l|--level      - patch level to use with rvm use / install
-
-     --prefix     - path for all rvm files (~/.rvm/), with trailing slash!
-     --bin        - path for binaries to be placed (~/.rvm/bin/)
-     --source     - src directory to use (~/.rvm/src/)
-     --archives   - directory for downladed files (~/.rvm/archives/)
-  -S              - Specify a script file to attempt to load and run (rubydo)
-  -e              - Execute code from the command line.
-  -G|--gems       - root gem path to use
-  -C|--configure  - custom configure options, comma separated
-                    default: --enable-shared=true
-  --reconfigure   - Force installer to re-run configure if already run
-  --nice          - process niceness (for slow computers, default 0)
-  --ree-options   - Options passed directly to ree's './installer' on the command line.
 
 Resources:
 

help/alias

@@ -0,0 +1,46 @@
+Alias
+
+  RVM allows you to alias you rubies for your convience and pleasure.
+
+Usage
+  rvm [options] alias source destination
+
+  Source and Destination must be an RVM
+  ruby string representing an RVM installed ruby.
+
+  A gemset may be optionally included.
+
+Creating Aliases
+
+  First select a RVM ruby.
+
+    ∴ rvm alias create ree-1.8.7-p2010.01 php
+
+Using Aliases
+
+  Now that you have created an alias, you can use the alias in place of the longer rvm selector string.
+
+    ∴ rvm use php
+    ∴ ruby -v
+    ruby 1.8.7 (2009-12-24 patchlevel 248) [i686-darwin10.3.0], MBARI 0x6770, Ruby Enterprise Edition 2010.01
+
+If you use any aliases that are rather funny, please hop in #rvm and let us know :)
+
+Deleting Aliases
+
+  If you wish to delete an alias
+
+  ∴ rvm alias delete dotnet
+    Listing Aliases
+
+You can also list all current aliases
+
+  ∴ rvm alias list
+    php => ree-1.8.7-p2010.01
+    lisp => maglev-head
+    python => rbx-head
+
+Documentation:
+
+  http://rvm.beginrescueend.com/rubies/alias/
+

help/benchmark

@@ -0,0 +1,17 @@
+Benchmark
+
+If you have a bit of code that you would like to benchmark across several versions of ruby all at once you can now do this easily with RVM. Given:
+
+  ∴ cat increment.rb
+    y=0
+    1000.times do |x|
+      y = x + 1
+    end
+We can benchmark this code against multiple ruby versions very easily:
+
+  ∴ rvm 1.8.6,1.8.7,1.9.1,ree benchmark increment.rb
+
+
+Documentation:
+
+http://rvm.beginrescueend.com/set/benchmark/

help/debug

@@ -0,0 +1,8 @@
+Debug
+
+  TODO
+
+Documentation:
+
+  TODO
+

help/fetch

@@ -0,0 +1,5 @@
+Fetch
+
+Documentation:
+  TODO: For now see:
+  http://rvm.beginrescueend.com/rubies/installing/

scripts/cli

@@ -8,7 +8,7 @@ __rvm_parse_args() {
   while [[ $# -gt 0 ]] ; do
     rvm_token="$1" ; shift
     case "$rvm_token" in
-      fetch|version|srcdir|reset|debug|reload|implode|seppuku|update|monitor|notes|question|answer)
+      fetch|version|srcdir|reset|debug|reload|update|monitor|notes|implode|seppuku|question|answer)
         rvm_action=$rvm_token
       ;;
 
@@ -273,7 +273,12 @@ __rvm_parse_args() {
         rvm_ruby_string="$rvm_token"
       ;;
 
-      -h|--help|usage|help) rvm_action=help                     ;;
+      help)
+        rvm_action="$rvm_token"
+        rvm_ruby_args="$@"
+        rvm_parse_break=1
+      ;;
+      -h|--help|usage)      rvm_action=help                     ;;
       -G|--gems)            rvm_gems_path="$1"         ; shift  ;;
       --source)             rvm_src_path="$1"          ; shift  ;;
       --archives)           rvm_archives_path="$1"     ; shift  ;;
@@ -401,12 +406,13 @@ rvm() {
     reset)           __rvm_reset             ; result=$? ;;
     update)          __rvm_update            ; result=$? ;;
     reboot)          __rvm_reboot            ; result=$? ;;
-    usage|help)      __rvm_usage             ; result=$? ;;
+    usage)           __rvm_usage             ; result=$? ;;
     benchmark)       __rvm_benchmark         ; result=$? ;;
     inspect)         __rvm_inspect           ; result=$? ;;
     implode|seppuku) __rvm_implode           ; result=$? ;;
     docs)            $rvm_scripts_path/docs  ; result=$? ;;
     alias)           $rvm_scripts_path/alias ; result=$? ;;
+    help)            $rvm_scripts_path/help $rvm_ruby_args ; result=$? ;;
 
     answer) __rvm_Answer_to_the_Ultimate_Question_of_Life_the_Universe_and_Everything ; result=42 ;;
     question) __rvm_ultimate_question ; result=42 ;;

scripts/help

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+source $rvm_scripts_path/initialize
+
+if [[ ! -z "$rvm_trace_flag" ]] ; then set -x ; export rvm_trace_flag ; fi
+
+trap "if [[ -d $rvm_tmp_path/ ]] && [[ -s $rvm_tmp_path/$$ ]] ; then rm -f $rvm_tmp_path/$$ > /dev/null 2>&1 ; fi ; exit" 0 1 2 3 15
+
+rvm_help_path="${rvm_help_path:-"$rvm_path/help"}"
+
+command="$(echo $* | awk '{print $1}')"
+action="$(echo $* | awk '{print $2}')"
+# Reserved for future use:
+args=$(echo "$*" | awk '{$1=""; $2="" ; print}' | sed -e 's/^[[:space:]]*//' -e 's/[[:space:]]*$//')
+
+if [[ ! -z "$command" ]] && [[ -s "${rvm_help_path}/${command}" ]] ; then
+  if [[ ! -z "$action" ]] && [[ -s "${rvm_help_path}/${command}/${action}" ]] ; then
+    cat "${rvm_help_path}/${command}/${action}" | ${PAGER:-less}
+  else
+    cat "${rvm_help_path}/${command}" | ${PAGER:-less}
+  fi
+else
+  cat "${rvm_path:-$HOME/.rvm}/README" | ${PAGER:-less}
+  $rvm_scripts_path/log "info" "\nFor help with a specific command:\n $(builtin cd "${rvm_help_path}" ; \ls)"
+fi
+
+$rvm_scripts_path/log "info" "\nFor additional information please visit RVM's documentation website:\n    http://rvm.beginrescueend.com/\n"
+
+exit $?

scripts/install

@@ -113,7 +113,7 @@ done
 #
 # Scripts
 #
-for dir_name in config scripts examples lib hooks ; do
+for dir_name in config scripts examples lib hooks help ; do
   spinner
   mkdir -p "$rvm_path/$dir_name"
   if [[ -d "$source_path/$dir_name" ]] ; then