Merge commit 'e342c330807fdd09adba974611122d1c95bdf07d' from hydra

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

diff --git a/packages/hydra/README.md b/packages/hydra/README.md
index c7c1dff6f2973fb9e13546e9f4e6130c51b3532a..70b31bf073f68390d52e0088e28a154dec261ec6 100644 (file)
--- a/packages/hydra/README.md
+++ b/packages/hydra/README.md
@@ -50,6 +50,9 @@ that disables itself auto-magically.
   ("l" hydra-move-splitter-right))
 ```
 
+### Community wiki
+A few useful hydras are aggregated in projects [community wiki](https://github.com/abo-abo/hydra/wiki/Hydras%20by%20Topic). Feel free to add your own or edit existing ones.
+
 ## Using the functions generated by `defhydra`
 
 With the example above, you can e.g.:
@@ -266,3 +269,41 @@ to a head. This sexp will be wrapped in an interactive lambda. Here's an example
    ("q" nil "cancel"))
 (global-set-key (kbd "C-c r") 'hydra-launcher/body)
 ```
+
+## Define Hydra heads that don't show up in the hint at all
+
+This can be done by setting the head's hint explicitly to `nil`, instead of the usual string.
+
+## Use a dedicated window for Hydra hints
+
+Since version `0.10.0`, setting `hydra-lv` to `t` (the default setting) will make it use a dedicated
+window right above the Echo Area for hints. This has the advantage that you can immediately see
+any `message` output from the functions that you call, since Hydra no longer uses `message` to display
+the hint. You can still have the old behavior by setting `hydra-lv` to `nil`.
+
+## Color table
+
+
+    | Body Color | Head Inherited | Executing NON-HEADS   | Executing HEADS |
+    |------------+----------------+-----------------------+-----------------|
+    | amaranth   | red            | Disallow and Continue | Continue        |
+    | teal       | blue           | Disallow and Continue | Quit            |
+    | pink       | red            | Allow and Continue    | Continue        |
+    | red        | red            | Allow and Quit        | Continue        |
+    | blue       | blue           | Allow and Quit        | Quit            |
+
+## Color to toggle correspondence
+
+By popular demand, an alternative syntax has been implemented that translates to colors without
+using them in the syntax. `:exit` can be used both in body (heads will inherit) and in heads
+(possible to override body). `:exit` is nil by default, corresponding to `red` head; you don't need
+to set it explicitly to nil.  `:foreign-keys` can be used only in body and can be either nil (default),
+`warn` or `run`.
+
+    | color    | toggle                     |
+    |----------+----------------------------|
+    | red      |                            |
+    | blue     | :exit t                    |
+    | amaranth | :foreign-keys warn         |
+    | teal     | :foreign-keys warn :exit t |
+    | pink     | :foreign-keys run          |