diff --git a/README b/README
index 1c4bd74..bf99296 100644
--- a/README
+++ b/README
@@ -1,25 +1,129 @@
-JSMN - Minimalistic JSON parser library
-=======================================
 
-jsmn (pronounced right as `jasmine`) is a simple and clean library for parsing
-JSON (JavaScript Object Notation) data format.
+JSMN
+====
 
-You can find more information on JSON at http://www.json.org/
+jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C.  It can be
+easily integrated into resource-limited or embedded projects.
+
+You can find more information on JSON at (http://www.json.org/)
 
 Philosophy
-==========
+----------
+
+Most JSON parsers offer you a bunch of functions to load JSON data, parse it
+and extract any value by its name. jsmn proves that checking the correctness of
+every JSON packet or allocating temporary objects to store parsed JSON fields
+is an overkill. 
 
-jsmn will never be large and complex. This means it will never have extra
-features or any bloated dependencies, besides libc.
-It will always be suitable for embedded systems and other resource-limited
-systems. It will always have clear API.
+JSON format itself is extremely simple, so why should we complicate it?
+
+jsmn is designed to be	**robust** (it should work fine even with erroneous
+data), **fast** (it should parse data on the fly), **portable** (no unneeded
+dependencies or non-standard C extensions). An of course, **simplicity** is a
+key feature - simple code style, simple algorithm, simple integration.
 
 Features
-========
+--------
+
+* compatible with C89
+* no dependencies (even libc!)
+* about 200 lines of code
+* extremely small code footprint
+* no dynamic memory allocation
+* incremental single-pass parsing
+* library code is covered with unit-tests
+
+Design
+------
+
+The rudimentary jsmn object is a **token**.
+
+When parsing is done, token objects contain start and end positions of JSON
+token inside the JSON data block. You can just copy a corresponding range of
+bytes and get token value. 
+
+Another propetry of token is token type. It describes the type of the
+corresponding JSON object. 
+
+jsmn supports the following token types:
+
+* Object - a container of key-value pairs, e.g.:
+	`{ "foo":"bar", "x":0.3 }`
+* Array - a sequence of values, e.g.:
+	`[ 1, 2, 3 ]`
+* String - a quoted sequence of chars, e.g.: `"foo"`
+* Primitive - a number, a boolean (`true`, `false`) or `null`
+
+jsmn doesn't handle specific JSON data types. It just points to the token
+boundaries - you should parse single data fields by your own if you need this.
+
+Get sources
+-----------
+
+Clone the repository (you should have mercurial installed):
+
+	$ hg clone http://bitbucket.org/zserge/jsmn jsmn
+
+Repository layout it simple: jsmn.c and jsmn.h are library files; demo.c is an
+example of how to use jsmn (it is also used in unit testing); test.sh is a test
+script. You will also find README, LICENSE and Makefile files inside.
+
+API
+---
+
+Token types are described by `jsontype_t`:
+
+	typedef enum {
+		JSON_OBJECT,
+		JSON_ARRAY,
+		JSON_STRING,
+		JSON_PRIMITIVE
+	} jsontype_t;
+
+**Note:** primitive tokens are not divided into numbers, booleans and null,
+because one can easily tell the type using the first character:
+
+* <code>'t', 'f'</code> - boolean 
+* <code>'n'</code> - null
+* <code>'-', '0'..'9'</code> - number
+
+Tokens are described with `jsontok_t`:
+
+	typedef struct {
+		jsontype_t type;
+		int start;
+		int end;
+	} jsontok_t;
+
+**Note:** string tokens point to the first character after
+the opening quote and the previous symbol before final quote. This was made 
+to simplify string extraction from JSON data.
+
+All job is done by `jsmn_parser` object. You can initialize a new parser using:
+
+	struct jsmn_parser parser;
+	jsmntok_t tokens[10];
+	
+	jsmn_init_parser(&parser, js, &tokens, 10);
+
+This will create a parser, that can parse up to 10 JSON tokens from `js` string.
+
+Later, you can use `jsmn_parse(&parser)` function to process JSON string with the parser.
+It something goes wrong, you will return an error. Error will be one of these:
+
+* `JSON_SUCCESS` - everything went fine. String was parsed
+* `JSON_ERROR_INVAL` - bad token, JSON string is corrupted
+* `JSON_ERROR_NOMEM` - not enough tokens, JSON string is too large
+* `JSON_ERROR_PART` - JSON string is too short, it doesn't contain the whole JSON data
+
+If you get `JSON_ERROR_NOMEM`, you can allocate more tokens and call `jsmn_parse` once more.
+If you read json data from the stream, you can call jsmn_parse and check if
+return value is `JSON_ERROR_PART` to see if you have reached the end of JSON
+data.
+
+Other info
+----------
 
-o Just 200 lines of code
-o Full C89 compatibility
-o No memory allocation inside the library code
-o A single pass is required to parse JSON data
-o MIT license (you can include this code into your proprietary software)
+This software is distributed under [MIT license](http://www.opensource.org/licenses/mit-license.php),
+ so feel free to integrate it in your commercial products.