Merge commit '6f142e342a4228640cb50a45e224f932679355bb' from hydra

[gnu-emacs-elpa] / packages / hydra / README.md

diff --git a/packages/hydra/README.md b/packages/hydra/README.md
index 24c8cf71fa3cbc4faa5c8757ff61a090c18fd437..79175bdc0fdc3a3a6b3f08a3aa210d9294eab7ec 100644 (file)
--- a/packages/hydra/README.md
+++ b/packages/hydra/README.md
@@ -4,6 +4,8 @@ This is a package for GNU Emacs that can be used to tie related
 commands into a family of short bindings with a common prefix - a
 Hydra.
 
+![hydra](http://oremacs.com/download/Hydra.png)
+
 Once you summon the Hydra through the prefixed binding (the body + any
 one head), all heads can be called in succession with only a short
 extension.
@@ -14,6 +16,8 @@ Hydra, will still serve his orignal purpose, calling his proper
 command.  This makes the Hydra very seamless, it's like a minor mode
 that disables itself auto-magically.
 
+## Simplified usage
+
 Here's how to quickly bind the examples bundled with Hydra:
 
 ```cl
@@ -23,6 +27,8 @@ Here's how to quickly bind the examples bundled with Hydra:
 (hydra-create "<f2>" hydra-example-text-scale)
 ```
 
+## Using Hydra for global bindings
+
 But it's much better to just take the examples as a template and write
 down everything explicitly:
 
@@ -51,7 +57,8 @@ it like this:
   ("l" text-scale-decrease "out")))
 ```
 
-If you like key chords so much that you don't want to touch the global map at all, you can e.g.:
+If you like key chords so much that you don't want to touch the global
+map at all, you can e.g.:
 
 ```
 (key-chord-define-global
@@ -68,9 +75,7 @@ You can also substitute `global-map` with any other keymap, like
 
 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
 
-![hydra](http://oremacs.com/download/Hydra.png)
-
-## Using Hydra to define bindings other than global ones
+## Using Hydra for major-mode or minor-mode bindings
 
 Here's an example:
 
@@ -104,3 +109,57 @@ can even add comments to the heads like this:
 
 With this, you'll see `zoom: [g]: in, [l]: out.` in your echo area,
 once the zoom Hydra becomes active.
+
+## Colorful Hydras
+
+Since version `0.5.0`, Hydra's heads all have a color associated with them:
+
+- *red* (default) means the calling this head will not vanquish the Hydra
+- *blue* means that the Hydra will be vanquished after calling this head
+
+In all the older examples, all heads are red by default. You can specify blue heads like this:
+
+```cl
+(global-set-key
+ (kbd "C-c C-v")
+ (defhydra toggle ()
+   "toggle"
+   ("a" abbrev-mode "abbrev" :color blue)
+   ("d" toggle-debug-on-error "debug" :color blue)
+   ("f" auto-fill-mode "fill" :color blue)
+   ("t" toggle-truncate-lines "truncate" :color blue)
+   ("w" whitespace-mode "whitespace" :color blue)
+   ("q" nil "cancel")))
+```
+
+Or, since the heads can inherit the color from the body, the following is equivalent:
+
+```cl
+(global-set-key
+ (kbd "C-c C-v")
+ (defhydra toggle (:color blue)
+   "toggle"
+   ("a" abbrev-mode "abbrev")
+   ("d" toggle-debug-on-error "debug")
+   ("f" auto-fill-mode "fill")
+   ("t" toggle-truncate-lines "truncate")
+   ("w" whitespace-mode "whitespace")
+   ("q" nil "cancel")))
+```
+
+The above Hydra is very similar to this code:
+
+```cl
+(global-set-key (kbd "C-c C-v t") 'toggle-truncate-lines)
+(global-set-key (kbd "C-c C-v f") 'auto-fill-mode)
+(global-set-key (kbd "C-c C-v a") 'abbrev-mode)
+```
+
+However, there are two important differences:
+
+- you get a hint like this right after <kbd>C-c C-v</kbd>:
+
+        toggle: [t]: truncate, [f]: fill, [a]: abbrev, [q]: cancel.
+
+- you can cancel <kbd>C-c C-v</kbd> with a command while executing that command, instead of e.g.
+getting an error `C-c C-v C-n is undefined` for <kbd>C-c C-v C-n</kbd>.