README.md in alf-0.9.2 vs README.md in alf-0.9.3

@@ -1,6 +1,6 @@
-# Alf - Relational Algebra at your fingertips (version 0.9.1)
+# Alf - Relational Algebra at your fingertips (version 0.9.3)
 
 ## Description
 
 ### What & Why
 
@@ -13,10 +13,15 @@
 ### Install
 
     % [sudo] gem install alf
     % alf --help
 
+### Bundler & Require 
+
+    # API is not considered stable enough for now, please use
+    gem "alf", "= 0.9.2"
+
 ### Links
     
 * {http://rubydoc.info/github/blambeau/alf/master/frames} (read this file there!)
 * {http://github.com/blambeau/alf} (source code)
 * {http://revision-zero.org} (author's blog)
@@ -29,22 +34,22 @@
 * Pragmatically, Alf aims at being a useful commandline executable for manipulating 
   relational-like data: database records, csv files, or **whatever can be interpreted 
   as (the physical encoding of) a relation**. See 'alf --help' for the list of 
   available commands and implemented relational operators.
   
-      % alf restrict suppliers -- "city == 'London'" | alf join cities 
+        % alf restrict suppliers -- "city == 'London'" | alf join cities 
   
 * Alf is also a 100% Ruby relational algebra implementation shipped with a simple 
   to use, powerful, functional DSL for compiling and evaluating relational queries. 
   Alf is not limited to simple scalar values, but admits values of arbitrary 
   complexity (under a few requirements about their implementation, see next 
   section). See 'alf --help' as well as .alf files in the examples directory 
   for syntactic examples.
   
-      Alf.lispy.evaluate { 
-        (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
-      }
+        Alf.lispy.evaluate { 
+          (join (restrict :suppliers, lambda{ city == 'London' }), :cities)
+        }
       
   In addition to this functional syntax, Alf comes bundled with an in-memory 
   Relation data structure that provides an object-oriented way of manipulating
   relations in simplest cases:
   
@@ -69,22 +74,22 @@
   enticed by features shown here to open that book, read it more deeply, and 
   implement new stuff around Date & Darwen's vision. Have a look at the result of 
   the following query for the kind of things that you'll never ever have in SQL 
   (see also 'alf help quota', 'alf help wrap', 'alf help group', ...):
   
-      % alf --text summarize supplies --by=sid -- total "sum(:qty)" -- which "group(:pid)"
+        % alf --text summarize supplies --by=sid -- total "sum(:qty)" -- which "group(:pid)"
   
 * Last, but not least, Alf is an attempt to help me test some research ideas and 
   communicate about them with people that already know (all or part) of the TTM 
   vision of relational theory. These people include members of the TTM mailing 
   list as well as other people implementing some of the TTM ideas (see 
   {https://github.com/dkubb/veritas Dan Kubb's Veritas project} for example). For 
   this reason, specific features and/or operators are mine, should be considered 
   'research work in progress', and used with care because not necessarily in 
   conformance with the TTM.
   
-      % alf --text quota supplies --by=sid --order=qty -- pos "count()"  
+        % alf --text quota supplies --by=sid --order=qty -- pos "count()"  
 
 ## Overview of relational theory
 
 We quickly recall relational theory in this section, as described in the TTM 
 book. Readers not familiar with Date and Darwen's vision of relational theory 
@@ -693,12 +698,11 @@
     
 An environment built that way will look for .rash and .alf files in the specified 
 folder and sub-folders. I'll of course strongly consider any contribution 
 implementing the Environment contract on top of SQL or NoSQL databases or anything 
 that can be useful to manipulate with relational algebra. Such contributions can 
-be added to the project directly, in the lib/alf/environment folder, for example. 
-A base template would look like:
+be added to the project directly. A base template would look like:
 
     class Foo < Alf::Environment
     
       #
       # You should at least implement the _dataset_ method that resolves a 
@@ -708,10 +712,13 @@
       def dataset(name)
       end
     
     end
 
+Read more about Environment's API so as to let your environment be recognized
+in shell (--env=...) on rubydoc.info
+
 ### Adding file decoders, aka Readers
 
 Environments should not be confused with Readers (see Reader class and its 
 subclasses). While the former resolve named datasets, the latter decode files 
 and/or other resources as tuple enumerables. Environments typically serve Reader
@@ -835,21 +842,28 @@
   sub-expressions used more than once in with expressions. 
 
 ### Versioning policy
 
 Alf respects {http://semver.org/ semantic versioning}, which means that it has
-a X.Y.Z version number and follows a few rules:
+a X.Y.Z version number and follows a few rules.
 
-- The public API is made of both the commandline tool as well as the Lispy 
-  dialect and will become stable with version 1.0.0 in a near future.
-- Backward compatible bug fixes will increase Z.  
-- New features and enhancements that do not break backward compatibility of the 
-  public API will increase the Y number.
-- Non backward compatible changes of the public API will increase the X number.
+- The public API is made of the commandline tool, the Lispy dialect and the 
+  Relation datastructure. This API will become stable with version 1.0.0 in a 
+  near future.
+- Currently, version 1.0.0 **has not been reached**. It means that **anything 
+  may change at any time**. Best effort will be done to upgrade Y when backward 
+  incompatible changes occur.
+- Once 1.0.0 will be reached, the following rules will be followed:
+  - Backward compatible bug fixes will increase Z.  
+  - New features and enhancements that do not break backward compatibility of 
+    the public API will increase the Y number.
+  - Non backward compatible changes of the public API will increase the X 
+    number.
 
-All classes and modules but the Alf module itself and the Lispy DSL are part of
-the private API and may change at any time. A best-effort strategy is followed
-to avoid breaking internals on tiny (Z) version increases. 
+All classes and modules but Alf module, the Lispy DSL and Alf::Relation are part 
+of the private API and may change at any time. A best-effort strategy is followed
+to avoid breaking internals on tiny (Z) version increases, especially extension
+points like Reader and Renderer. 
 
 ## Enjoy Alf!
 
 - No problem dude!