diff --git a/README.textile b/README.textile
index 99067b1..adc0432 100644
--- a/README.textile
+++ b/README.textile
@@ -9,25 +9,37 @@ h1. Documentation
 <pre class="lua">
 local v = require 'semver'
 
--- accepts integers and numbers
+-- two ways of creating it: with separate parameters, or with one string
 v1 = v(1,0,0)
 v2_5_1 = v('2.5.1')
 
+-- When using one string one can skip the parenthesis:
+v2_5_1 = v'2.5.1' -- valid in Lua
+
 -- major, minor and patch attributes
 v2_5_1.major -- 2
 v2_5_1.minor -- 5
 v2_5_1.patch -- 1
 
--- also accepts prerelease/build parameters:
-a = v(1,0,0,'-alpha')
+-- prereleases:
+a = v(1,0,0,'alpha')
 a.prerelease -- 'alpha'
+b = v('1.0.0-beta')
+b.prerelease -- 'beta'
 
-b = v'0.9.5+no.extensions.22'
-b.build -- 'no.extensions.22'
+-- builds
+c = v(1,0,0,nil,'build-1')
+c.build -- 'build-1'
+
+d = v('0.9.5+no.extensions.22')
+d.build -- 'no.extensions.22'
 
 -- comparison & sorting
-v'1.2.3' == v(1,2,3) -- true
-v'1.2.3' < v(4,5,6)  -- true
+v'1.2.3' == v(1,2,3)         -- true
+v'1.2.3' < v(4,5,6)          -- true
+v'1.2.3-alpha' < v'1.2.3'    -- true
+v'1.2.3' < v'1.2.3-build.1'  -- true
+-- (see the "notes" section for more informaion about version comparison)
 
 -- "pessimistic upgrade" operator: ^
 -- a ^ b returns true if it's safe to update from a to b
@@ -35,7 +47,7 @@ v'2.0.1' ^ v'2.5.1' -- true - it's safe to upgrade from 2.0.1 to 2.5.1
 v'1.0.0' ^ v'2.0.0' -- false - 2.0.0 is not supposed to be backwards-compatible
 v'2.5.1' ^ v'2.0.1' -- false - 2.5.1 is more modern than 2.0.1.
 
--- bumping
+-- getting newer versions
 v(1,0,0):nextPatch() -- v1.0.1
 v(1,2,3):nextMinor() -- v1.3.0 . Notice the patch resets to 0
 v(1,2,3):nextMajor() -- v2.0.0 . Minor and patch are reset to 0
@@ -49,12 +61,24 @@ Just copy the semver.lua file wherever you want it (for example on a lib/ folder
 
 <pre>local v = require 'semver'</pre>
 
-Using @v@ allows for the following nice syntax: @v'1.2.3'@.
+Using @v@ allows for the nice string syntax: @v'1.2.3-alpha'@.
 
 The @package.path@ variable must be configured so that the folder in which middleclass.lua is copied is available, of course.
 
 Please make sure that you read the license, too (for your convenience it's now included at the beginning of the semver.lua file).
 
+h1. Notes about version comparison
+
+Version comparison is done according to the specs:
+
+Major, minor, and patch versions are always compared numerically.
+
+Pre-release and build version precedence MUST be determined by comparing each dot-separated identifier as follows:
+
+* Identifiers consisting of only digits are compared numerically
+* Identifiers with letters or dashes are compared lexically in ASCII sort order.
+* Numeric identifiers always have lower precedence than non-numeric identifiers
+
 h1. Specs
 
 This project uses "telescope":https://github.com/norman/telescope for its specs. If you want to run the specs, you will have to install telescope first. Then just execute the following from the root inspect folder: