diff --git a/README.md b/README.md
index 5a68222..3423c16 100644
--- a/README.md
+++ b/README.md
@@ -1,19 +1,59 @@
nim-csfml
=========
+#### Nim Bindings for [Simple and Fast Multimedia Library][sfml] (through [CSFML][]).
-This is a work in progress. See [examples](examples), [documentation][].
+**See [introduction](#introduction), [examples](examples), [documentation][].**
-- The files [src](src)/csfml\_\*\_gen.nim are [automatically generated](generate) from CSFML's header files. They provide the base CSFML API.
-- The files csfml_\*.nim build upon them, adding some compatibility with SFML API.
-- *csfml.nim* automatically imports *system*, *window* and *graphics*.
-- *audio* should be imported separately.
-- *network* is not implemented.
+The files [src](src)/csfml\_\*\_gen.nim are [automatically generated](generate) from CSFML's header files. They provide the base CSFML API. The files csfml_\*.nim build upon them, adding compatibility with SFML API.
+*csfml.nim* automatically imports *system*, *window* and *graphics*; *audio* should be imported separately; *network* is not implemented.
-*nim-csfml* has been tested with SFML 2.1 and CSFML 2.1 on Linux.
+*nim-csfml* currently supports CSFML 2.1 only, but it may be possible to generate it for older versions of CSFML. It has been tested on Linux 64-bit and Windows 7 with MinGW 32-bit.
+Support for SFML 2.2 will be added immediately after CSFML 2.2 is released.
-This library can be installed using [Nimble][].
+This library can be installed using [nimble][] install csfml
.
-[SFML][] and [CSFML][] must be installed to use *nim-csfml*.
+[CSFML][] 2.1, which requires [SFML][] **2.1**, must be installed to use it.
+On Windows you can just [download CSFML][csfml] and put the DLLs (which seem to be statically linked with SFML) in your project folder instead.
+
+*nim-csfml*'s version number (`x.y.z`): `x.y` corresponds to the supported CSFML version; `z` is for the project's own point releases.
+
+
+Introduction
+------------
+
+*nim-csfml* allows you to use [SFML][], which is a library made in C++. So most information and [tutorials][sfml-tutorials] for SFML revolve around C++. It is a good idea to get familiar with SFML itself first.
+
+The API attempts to be very similar to SFML's, but some general changes are present:
+
+- To construct an object (`sf::SomeType x(param)`), use a corresponding procedure (there are 2 variations):
+ - `var x = newSomeType(param)`, which means it is a `ref object`.
+ - Such objects have [destructors][nim-destructors] associated with them (no need to call `destroy` manually).
+ - Never create them using `new`.
+ - `var x = someType(param)`, which means it is an `object` (in CSFML it corresponds to a simple `struct`).
+ - `Vector2(i|f)`, `Vector3f` and `(Int|Float)Rect` should be created using special `vec2`, `vec3` and `rect` procs.
+ - Member functions, such as `loadFromFile`, that are used for initialization, are also represented as constructor procs described above.
+- Getter, setter functions are changed:
+ - `x.getSomeProperty()` and `x.isSomeProperty()` both become `x.someProperty`.
+ - `x.setSomeProperty(v)` becomes `x.someProperty = v`.
+- Some renames of members were necessary because of reserved words:
+ - `type`: `kind`, `object`: `obj`, `string`: `str`, `bind`: `bindGL`.
+- `enum` names were taken from CSFML, but changed to remove their common prefix to resemble SFML's values.
+ - Expect surprises in their naming. Use the [documentation][].
+ - `enum`s are all `pure`: use `EnumType.Value`.
+ - A few `enum`s are just represented as a list of constants, because they are not really enumerations.
+ - SFML sometimes uses `enum` values as bitmasks. You can combine them using the `|` (not `or`) operator defined for `BitMaskU32` in the *util* module.
+- Unicode is supported and easy to use (no need for `sf::String` or strange conversions):
+ - CSFML's functions can deal with locale-dependent C strings (which should not be used)...
+ - and UTF-32 sequences, which have been wrapped for convenient use with Nim's normal UTF-8 strings.
+- Type differences:
+ - Sadly, `cint` and `cfloat` will be present everywhere, so explicit conversions to/from Nim's normal types may be required.
+ - `unsigned int` is mapped as `cint`, etc., so you don't have to bother with unsigned conversions. This shouldn't cause problems, but it might.
+ - The *util* module contains some types that provide implicit conversions.
+ - For example `sfBool` which is defined as `int`, is mapped to the `IntBool` type with conversions to Nim's `bool`.
+- If you want to use some particular CSFML function but don't know what it maps to in *nim-csml*, you can just search for its name in the [documentation][].
+- Most of the [documentation][] is taken directly from CSFML, so don't be surprised if it talks in C/C++ terms.
+
+See [examples](examples) to learn more.
Acknowledgements
@@ -31,7 +71,9 @@ This library uses and is based on [SFML][] and [CSFML][].
[documentation]: http://blaxpirit.github.io/nim-csfml/
[sfml]: http://www.sfml-dev.org/ "Simple and Fast Multimedia Library"
[csfml]: http://www.sfml-dev.org/download/csfml/
+[sfml-tutorials]: http://www.sfml-dev.org/tutorials/
[nim]: http://nim-lang.org/
+[nim-destructors]: http://nim-lang.org/manual.html#destructors
[python]: http://python.org/
[nimble]: https://github.com/nim-lang/nimble
-[nimrod-sfml]: https://github.com/fowlmouth/nimrod-sfml
\ No newline at end of file
+[nimrod-sfml]: https://github.com/fowlmouth/nimrod-sfml
diff --git a/csfml.nimble b/csfml.nimble
index 8b9c782..58a1cb5 100644
--- a/csfml.nimble
+++ b/csfml.nimble
@@ -1,9 +1,9 @@
[Package]
name: "csfml"
-version: "0.1.0"
+version: "2.1.0"
author: "Oleh Prypin"
description: "Bindings for Simple and Fast Multimedia Library (through CSFML)"
license: "zlib"
srcDir: "src"
[Deps]
-requires: "nimrod > 0.10"
\ No newline at end of file
+requires: "nim >= 0.10.1"
\ No newline at end of file
diff --git a/generate/README.md b/generate/README.md
index c141ec0..c72ac6c 100644
--- a/generate/README.md
+++ b/generate/README.md
@@ -1,10 +1,10 @@
Run *generate.sh* on Linux to (re)create [src](../src)/csfml\_*\_gen.nim source files based on CSFML's header files.
-This automatic generator expects the header files to be in */usr/include/SFML*. It requires [Python][] 3.x and [pycparser][].
+This automatic generator expects the header files to be in */usr/include/SFML*. It requires [Python][] 3.3+ and [pycparser][].
-The generator's code is very messy...
+The generator's code is very messy, and there some specific replacements that make the word "automatic" a bit dishonest. Still, it should allow transitioning to new CSFML versions with little to no intervention.
[python]: http://python.org
-[pycparser]: https://pypi.python.org/pypi/pycparser
\ No newline at end of file
+[pycparser]: https://pypi.python.org/pypi/pycparser