From 3b1fa61dfc7d26e456960331fe4fd663056656d6 Mon Sep 17 00:00:00 2001
From: mitchell <70453897+667e-11@users.noreply.github.com>
Date: Thu, 28 Jul 2011 21:14:57 -0400
Subject: Clarify role of keys.conf and keys.osx.conf;
 doc/manual/9_Preferences.md

---
 doc/manual/9_Preferences.md | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

(limited to 'doc/manual/9_Preferences.md')

diff --git a/doc/manual/9_Preferences.md b/doc/manual/9_Preferences.md
index fb09eb7d..8e6b0a48 100644
--- a/doc/manual/9_Preferences.md
+++ b/doc/manual/9_Preferences.md
@@ -82,17 +82,27 @@ The default set of key commands is located in `modules/textadept/keys.conf`
 could be overwritten when updating Textadept. Instead, make a copy in your
 `~/.textadept/` folder and modify that.
 
-You can also modify key commands from within your your `~/.textadept/init.lua`
-or from a file loaded by `~/.textadept/init.lua`. For example maybe you want
-`Alt+N` to create a new buffer instead of `Ctrl+N`:
+Key commands need to be defined manually for keychains or custom functions. You
+can do this in your `~/.textadept/init.lua` or from a file loaded by
+`~/.textadept/init.lua`. For example maybe you want `Ctrl+Shift+A, N` (`⌘⇧A, N`
+on Mac OSX) to create a new buffer instead of `Ctrl+N` (`⌘N`):
 
-    keys.an = new_buffer
+    keys.cA = {}
+    keys.cA.n = new_buffer
     keys.cn = nil
 
-If you choose to exclude loading the menu like in the example above, you will
-have to specify your own set of key commands! I happen to do this and keep a
-copy of `~/.textadept/modules/textadept/keys.lua` that is loaded by my
-`~/.textadept/init.lua`.
+Earlier versions of Textadept manually defined all key commands in
+`modules/textadept/keys.lua` (`keys.cn = new_buffer`, `keys.co = io.open_file`,
+etc.). Now the `menu` module does this automatically by reading the keys in the
+`keys.conf` or `keys.osx.conf` files mentioned earlier. Of course you can still
+use Lua to define commands as demonstrated above. In fact, if you choose to
+exclude loading the menu like in an earlier example above, you will have to
+specify your own set of key commands! (I happen to do this and keep a copy of
+`~/.textadept/modules/textadept/keys.lua` that is loaded by my
+`~/.textadept/init.lua`.) Please note that key commands are _not_ handled by the
+menu; they are still handled as they always have been. Therefore the keys shown
+in the menu could differ from the actual set of key commands if you use Lua to
+redefine them. Menu keys are shown purely for cosmetic, not functional reasons.
 
 ## Locale
 
-- 
cgit v1.2.3