diff --git a/README.md b/README.md
index 5ba5104..9455363 100644
--- a/README.md
+++ b/README.md
@@ -3,20 +3,51 @@ hscript
 
 Parse and evalutate Haxe expressions.
 
-Usage :
+
+In some projects it's sometime useful to be able to interpret some code dynamically, without any recompile.
+
+Haxe script is a complete subset of the Haxe language.
+
+It is dynamically typed but allow all Haxe expressions apart from type (class,enum,typedef) declarations.
+
+Usage
+-----
 
 <pre>
-var expr = "var x = 4; 1 + 2 * x";
-var parser = new hscript.Parser();
-var ast = parser.parseString(expr);
-var interp = new hscript.Interp();
-trace(interp.execute(ast));
+	var expr = "var x = 4; 1 + 2 * x";
+	var parser = new hscript.Parser();
+	var ast = parser.parseString(expr);
+	var interp = new hscript.Interp();
+	trace(interp.execute(ast));
 </pre>
 
 In case of a parsing error an `hscript.Expr.Error` is thrown. You can use `parser.line` to know the line number.
 
 You can set some globaly accessible identifiers by using `interp.variables.set("name",value)`
 
+Example
+-------
+
+Here's a small example of Haxe Script usage :
+<pre>
+	var script = "
+		var sum = 0;
+		for( a in angles )
+			sum += Math.cos(a);
+		sum; 
+	";
+	var parser = new hscript.Parser();
+	var program = parser.parseString(script);
+	var interp = new hscript.Interp();
+	interp.variables.set("Math",Math); // share the Math class
+	interp.variables.set("angles",[0,1,2,3]); // set the angles list
+	trace( interp.execute(program) ); 
+</pre>
+
+This will calculate the sum of the cosines of the angles given as input.
+
+Haxe Script has not been really optimized, and it's not meant to be very fast. But it's entirely crossplatform since it's pure Haxe code (it doesn't use any platform-specific API).
+
 Advanced Usage
 --------------
 
@@ -31,3 +62,25 @@ You can use `parser.allowJSON` to allow JSON data.
 You can use `parser.allowTypes` to parse types for local vars, exceptions, function args and return types. Types are ignored by the interpreter.
 
 You can use `new hscript.Macro(pos).convert(ast)` to convert an hscript AST to a Haxe macros one.
+
+limitations
+-----------
+
+Compared to Haxe, limitations are :
+
+- no type declarations (classes, enums, typedefs) : only expressions
+- no switch construct
+- only one variable declaration is allowed in var
+- the parser supports optional types for var and function if allowTypes is set, but the interpreter ignore them
+- you can enable per-expression position tracking by compiling with -D hscriptPos 
+
+Install
+-------
+
+In order to install Haxe Script, use haxelib install hscript and compile your program with -lib hscript.
+
+There are only three files in hscript :
+
+  - hscript.Expr : contains enums declarations
+  - hscript.Parser : a small parser that turns a string into an expression structure (AST)
+  - hscript.Interp : a small interpreter that execute the AST and returns the latest evaluated value