[elpa] master 7f4c835 11/28: README.md: finish up the rules

[Oleh Krehel]

branch: master
commit 7f4c83529496999d159e1978fef353db27e1ae4d
Author: Oleh Krehel <address@hidden>
Commit: Oleh Krehel <address@hidden>

    README.md: finish up the rules
---
 README.md |   71 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 files changed, 68 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 47ed9cc..e871643 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ Once you summon the Hydra through the prefixed binding (the 
body + any one head)
 called in succession with only a short extension.
 
 The Hydra is vanquished once Hercules, any binding that isn't the Hydra's 
head, arrives.  Note that
-Hercules, besides vanquishing the Hydra, will still serve his orignal purpose, 
calling his proper
+Hercules, besides vanquishing the Hydra, will still serve his original 
purpose, calling his proper
 command.  This makes the Hydra very seamless, it's like a minor mode that 
disables itself
 auto-magically.
 
@@ -34,7 +34,7 @@ With this simple code, you can:
 
 For any Hydra:
 
-- `digit-argment` can be called with <kbd>0</kbd>-<kbd>9</kbd>.
+- `digit-argument` can be called with <kbd>0</kbd>-<kbd>9</kbd>.
 - `negative-argument` can be called with <kbd>-</kbd>.
 - `universal-argument` can be called with <kbd>C-u</kbd>.
 
@@ -246,6 +246,59 @@ You can specify code that will be called before each head, 
and after the body. F
 Thanks to `:pre`, each time any head is called, the cursor color is changed.
 And when the hydra quits, the cursor color will be made black again with 
`:post`.
 
+#### `:exit`
+
+The `:exit` key is inherited by every head (they can override it) and 
influences what will happen
+after executing head's command:
+
+- `:exit nil` (the default) means that the hydra state will continue - you'll 
still see the hint and be able to use short bindings.
+- `:exit t` means that the hydra state will stop.
+
+#### `:foreign-keys`
+
+The `:foreign-keys` key belongs to the body and decides what to do when a key 
is pressed that doesn't
+belong to any head:
+
+- `:foreign-keys nil` (the default) means that the hydra state will stop and 
the foreign key will
+do whatever it was supposed to do if there was no hydra state.
+- `:foreign-keys warn` will not stop the hydra state, but instead will issue a 
warning without
+running the foreign key.
+- `:foreign-keys run` will not stop the hydra state, and try to run the 
foreign key.
+
+#### `:color`
+
+The `:color` key is a shortcut. It aggregates `:exit` and `:foreign-keys` key 
in the following way:
+
+    | color    | toggle                     |
+    |----------+----------------------------|
+    | red      |                            |
+    | blue     | :exit t                    |
+    | amaranth | :foreign-keys warn         |
+    | teal     | :foreign-keys warn :exit t |
+    | pink     | :foreign-keys run          |
+
+It's also a trick to make you instantly aware of the current hydra keys that 
you're about to press:
+the keys will be highlighted with the appropriate color.
+
+#### `:timeout`
+
+The `:timeout` key starts a timer for the corresponding amount of seconds that 
disables the hydra.
+Calling any head will refresh the timer.
+
+#### `:hint`
+
+The `:hint` key will be inherited by each head. Each head is allowed to 
override it, of course.
+One value that makes sense is `:hint nil`. See below for an explanation of 
head hint.
+
+#### `:bind`
+
+The `:bind` key provides a lambda to be used to bind each head.  This is quite 
advanced and rarely
+used, you're not likely to need it.  But if you would like to bind your heads 
with e.g. `bind-key`
+instead of `define-key` you can use this option.
+
+The `:bind` key can be overridden by each head. This is useful if you want to 
have a few heads that
+are not bound outside the hydra.
+
 ### `awesome-head-1`
 
 Each head looks like this:
@@ -254,13 +307,17 @@ Each head looks like this:
 (head-binding head-command head-hint head-plist)
 ```
 
-For a head `("g" text-scale-increase "in")`:
+For the head `("g" text-scale-increase "in")`:
 
 - `head-binding` is `"g"`.
 - `head-command` is `text-scale-increase`.
 - `head-hint` is `"in"`.
 - `head-plist` is `nil`.
 
+#### `head-binding`
+
+The `head-binding` is a string that can be passed to `kbd`.
+
 #### `head-command`
 
 The `head-command` can be:
@@ -306,3 +363,11 @@ Press _g_ to zoom in.
   ("g" text-scale-increase nil)
   ("l" text-scale-decrease "out"))
 ```
+
+#### `head-plist`
+
+Here's a list of body keys that can be overridden in each head:
+
+- `:exit`
+- `:color`
+- `:bind`