README.rdoc in rconf-0.5.9 vs README.rdoc in rconf-0.6.1

@@ -8,49 +8,95 @@
 ruby, rubygems, bundler etc. Being able to setup an environment appropriately
 for each application is becoming increasingly complex and switching from one
 application to another for development in particular is quickly becoming
 close to impossible.
 
-RightEnv aims at addressing some of these difficulties by providing a uniform
+rconf aims at addressing some of these difficulties by providing a uniform
 and consistent mechanism for applications developed at RightScale to 
-declaratively specify the tools they depend on in various systems (development,
-test, staging, production) and platforms (linux, darwin and windows). RightEnv
-uses a DSL close to Chef recipes for defining an application configuration.
+declaratively specify the tools they depend on various platforms (linux, darwin
+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 must be named "<application>.re" (where
-"<application>" should be subsituted with the name of the application.
-Configuring the system to run the application then merely consists of running
-the "script/bootstrap_environment" script provided in the "script" directory
-("script/bootstrap_environment.bat" on windows).
+level directory of the application and use the '.rc' 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 RightEnv 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 RightEnv as it reads the
+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 
-rely on. For a list of available configurators run "script/configurator --list".
+rely on.
 
 == REQUIREMENTS
 
 === Running
 
-- Linux and MAc OS X
+==== Linux and Mac OS X
 
- - ruby >= 1.8.6
- - curl
- - tar
+- ruby >= 1.8.6
+- curl
+- tar
 
-- Windows
+==== Windows
 
- - ruby >= 1.8.6
- - Win32API gem
+- ruby >= 1.8.6
+- Win32API gem
 
 === Unit testing
 
 Install the following gems for testing:
 - rspec >= 2.0
 - flexmock
 
 Then the build can be tested with
  
   rake spec
+
+== WRITING RCONF CONFIGURATION FILES
+
+rconf uses a ruby DSL for configuration files (.rc). 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:
+
+  ruby do
+    version 'ruby-1.9.2-p136'
+  end
+
+The configuration file consists of a sequence of these configurator sections
+executed in order. For a complete list of available configurators run:
+
+  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 
++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 
+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 
+platform and can take the values 'ubuntu', 'centos' etc. (linux).
+
+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 
++run_linux+ and +run_linux_ubuntu+ are provided and the configurator is
+running on Ubuntu then rconf will call the +run_linux_ubuntu+ implementation).