diff --git a/README.asciidoc b/README.asciidoc
index f83b75a6..3a1c8255 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -22,6 +22,7 @@ Kakoune dependencies are:
  * GCC >= 4.7
  * boost
  * ncurses
+ * bash (kak scripts use some bash specific features)
  * socat (used by kak scripts to write to kak control socket)
 
 To build, just type *make* in the src directory
@@ -340,6 +341,8 @@ Options are typed, their type can be
 
  * +int+: an integer number
  * +bool+: a boolean value, +yes/true+ or +no/false+
+ * +yesnoask+: similar to a boolean, but the additional
+   value +ask+ is supported.
  * +str+: a string, some freeform text
  * +regex+: as a string but the +set+ commands will complain
    if the entered text is not a valid regex.
@@ -408,6 +411,8 @@ Some options are built in kakoune, and can be used to control it's behaviour:
    (+word=all+) or only the current one (+word=buffer+)
  * +insert_hide_sel+ _bool_: hide the selection (except the last
    element) in insert mode
+ * +autoreload+ _yesnoask_: auto reload the buffers when an external
+   modification is detected.
 
 Insert mode completion
 ----------------------
@@ -495,9 +500,9 @@ to register a hook, use the hook command.
 :hook <scope> <hook_name> <filtering_regex> <commands>
 ------------------------------------------------------
 
-<scope> can be either global, buffer or window, the scope are hierarchical,
-meaning that a Window calling a hook will execute it's own, the buffer ones
-and the global ones.
+<scope> can be either global, buffer or window (or any of their prefixes),
+the scope are hierarchical, meaning that a Window calling a hook will
+execute it's own, the buffer ones and the global ones.
 
 <command> is a string containing the commands to execute when the hook is
 called.
@@ -541,6 +546,19 @@ existing hooks are:
 
 when not specified, the filtering text is an empty string.
 
+Key Mapping
+-----------
+
+You can redefine keys meaning using the map command
+
+------------------------------------------------------
+:map <scope> <mode> <key> <keys>
+------------------------------------------------------
+
+with +scope+ being one of +global, buffer or window+ (or any prefix),
+mode being +insert, normal, prompt or menu+ (or any prefix), +key+ being
+a single key name and +keys+ a list of keys.
+
 Color Aliases
 -------------
 
diff --git a/TODO b/TODO
index bafe0b5b..499856c6 100644
--- a/TODO
+++ b/TODO
@@ -97,3 +97,20 @@
   - 10,20g -> goto line 10, column 20
 
   - 1,2,3<a-space> remove selections 1, 2 and 3
+
+* add a mimetype option always set by 'file', and add hooks for
+  setting filetype depending on mimetype.
+
+* Make kakoune self-documenting
+
+  - Add doc strings to commands, display them in info boxes when entering command
+
+  - Add doc strings to options as well
+
+  - Generate documentation from Kakoune source
+
+    . Write asciidoc from internal documentation
+
+    . make doc compiles kakoune, and run doc generation:
+      +./kak -help commands > ../doc/commands.asciidoc+
+      with README.asciidoc including commands ?
diff --git a/doc/keymap b/doc/keymap
index 743758c1..e356c080 100644
--- a/doc/keymap
+++ b/doc/keymap
@@ -3,9 +3,9 @@
 ├┄┄CASE┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┨              ┃
 │  lower│ 1     │ 2     │ 3     │ 4     │ 5     │ 6     │ 7     │ 8     │ 9     │ 0     │       │       ┃              ┃
 ┢━━━━━━━┷━━━┱───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┴───┬───┺━━━┳━━━━━━━━━━┫
-┃ ↹         ┃ replay│     ᵐʷ│     ᵐʷ│       │     ᵐʳ│catyank│  redo │ INSERT│  above│ before│       │       ┃          ┃
-┃           ┠┄┄┄┄┄┄┄┤   next│   word├┄┄┄┄┄┄┄┤to char├┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄OPEN┄┄┼┄PASTE┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┨ ⏎        ┃
-┃           ┃ record│   word│    end│replace│       │  yank │  undo │ insert│  below│  after│obj beg│obj end┃          ┃
+┃ ↹         ┃ replay│     ᵐʷ│     ᵐʷ│       │     ᵐʳ│catyank│  redo │ INSERT│  above│ before│      ᵐ│      ᵐ┃          ┃
+┃           ┠┄┄┄┄┄┄┄┤   next│   word├┄┄┄┄┄┄┄┤to char├┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄OPEN┄┄┼┄PASTE┄┤ object│ object┃ ⏎        ┃
+┃           ┃ record│   word│    end│replace│       │  yank │  undo │ insert│  below│  after│  begin│    end┃          ┃
 ┣━━━━━━━━━━━┻━┱─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┴─┬─────┺━┓        ┃
 ┃ ⇬           ┃ APPEND│  split│       │     ᵐʳ│     ᵐᵍ│     ᵐˡ│      ᵐ│      ᵐ│     ᵐˡ│cmdline│       │   pipe┃        ┃
 ┃             ┠┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┤   find│  goto │       │       │       │       ├┄┄┄┄┄┄┄┤       ├┄┄┄┄┄┄┄┨        ┃