README.rdoc in rconf-0.9.18 vs README.rdoc in rconf-0.9.19

@@ -1,7 +1,9 @@
-= right_env
 
+= rconf
+
+
 == INTRODUCTION
 
 As RightScale systems evolve, developers are faced with having to maintain a
 quickly growing list of applications. Each application requires different tools
 for development and for deployment. Tools may include different versions of
@@ -9,52 +11,91 @@
 for each application is becoming increasingly complex and switching from one
 application to another for development in particular is quickly becoming
 close to impossible.
 
 rconf aims at addressing some of these difficulties by providing a uniform
-and consistent mechanism for applications developed at RightScale to 
+and consistent mechanism for applications developed at RightScale to
 declaratively specify the tools they depend on various platforms (linux, darwin
-and potentially windows). 
+and potentially windows).
 
 rconf uses a DSL close to Chef recipes for defining an application configuration.
 Each application must be equipped with a definition that must reside at the top
 level directory of the application and use the '.rconf' file extension. When run
 for the first time rconf sets up a .rvmrc file which gets invoked and sets up
 the environment each time the application directory gets 'cd-ed' into.
 
-Internally rconf relies on 'configurators' to configure the machine 
+Internally rconf relies on 'configurators' to configure the machine
 appropriately. There is one configurator per tool that needs configuration.
 Each configurator is dynamically instantiated by rconf as it reads the
 application configuration file. This makes for an extensible system where new
-configurator may be added to configure new tools that new applications may 
+configurator may be added to configure new tools that new applications may
 rely on.
 
+
 == REQUIREMENTS
 
-=== Running
+=== Linux and Mac OS X
 
-==== Linux and Mac OS X
-
 - ruby >= 1.8.6
 - curl
 - tar
 
-==== Windows
+=== Windows
 
 - ruby >= 1.8.6
 - Win32API gem
 
-=== Unit testing
 
-Install the following gems for testing:
-- rspec >= 2.0
-- flexmock
+== INSTALLING
 
-Then the build can be tested with
- 
-  rake spec
+There are two installation cases
 
+a) you've already got a working install of RVM
+b) blank system
+
+=== a) Installing when RVM is already present
+
+It should be as simple as:
+
+  gem install rconf
+
+and then moving to your repository and running:
+
+  rconf
+
+to let rconf prepare your environment for the repository.
+
+=== b) Installing on a blank system
+
+If your system fits the requirements listed above, installing rconf will
+require you to make a system install of rconf:
+
+  sudo gem install rconf
+
+then you can go to your repository and run
+
+  rconf
+
+If you do not have a x.rconf equipped directory and you want rconf to install rvm for
+you, you can create a file named dummy.rconf containing:
+
+  ruby do
+    version 'ruby-1.9.2-p290'
+    rubygems '1.8.10'
+  end
+
+and then run rconf against it:
+
+  rconf dummy.rconf
+
+=== rconf and existing .rvmrc files
+
+If you have pre-existing .rvmrc files and they don't play well with your
+.rconf configuration file, don't hesitate to delete them and run rconf.
+rconf will create a new, working, .rvmrc.
+
+
 == WRITING RCONF CONFIGURATION FILES
 
 rconf uses a ruby DSL for configuration files (.rconf). Each configurator is
 associated with a keyword. The configuration for a given configurator then
 lists each configurator setting it needs to set and the associated value as in:
@@ -68,35 +109,49 @@
 
   rconf --configurators
 
 The same configurator can appear multiple times in a configuration file.
 
-== EXTENDING RCONF WITH NEW CONFIGURATORS
 
-Writing a configurator consists of writing a ruby class which includes the 
+== DEVELOPING RCONF AND FOR RCONF
+
+=== Requirements
+
+Install the following gems for testing:
+- rspec >= 2.0
+- flexmock
+
+Then the build can be tested with
+
+  rake spec
+
+
+=== Extending rconf with new configurators
+
+Writing a configurator consists of writing a ruby class which includes the
 +RightConf::Configurator+ module and uses the class methods define there to
 register, provide a description and list its settings.
 
 The exact methods are:
 
 - +register+: Takes one argument which is the keyword associated with the configurator in configuration files.
 - +description+: Associates the description with the configurator used in the help.
 - +settings+: The value should be a hash where the keys are the settings names (ruby symbols) and the value is the setting description.
 - +validate_has_settings+: An array of settings names (symbols) for all settings that must be set for a configuration to be valid when using that configurator.
 
-The configurator class then needs to implement the +run+ method which gets 
+The configurator class then needs to implement the +run+ method which gets
 called whenever rconf executes a configuration section using the configurator.
 
 Alternatively the configurator class may implement +run_<platform>+ where
 +<platform>+ can take the values 'darwin', 'linux' or 'windows' if the
 implementation needs to be platform specific.
 
 The configurator can also provide distribution specific implementations by
-implementing +run_<platform>_<flavor>+ where +<flavor>+ depends on the 
+implementing +run_<platform>_<flavor>+ where +<flavor>+ depends on the
 platform and can take the values 'ubuntu', 'centos' etc. (linux).
 
-Finally the +run+ method can also be implemented using the full specification 
+Finally the +run+ method can also be implemented using the full specification
 for a platform including the release number (e.g. +run_linux_ubuntu_10_10+). In
-each case rconf will use the most specific implementation (so if both 
+each case rconf will use the most specific implementation (so if both
 +run_linux+ and +run_linux_ubuntu+ are provided and the configurator is
 running on Ubuntu then rconf will call the +run_linux_ubuntu+ implementation).