From 873978daa1954083916abab9c169e56776a0cb1e Mon Sep 17 00:00:00 2001
From: John Foerch <jjfoerch@earthlink.net>
Date: Fri, 5 Feb 2010 19:03:23 -0500
Subject: [PATCH] issue139: C-h suffix for key combos

Added command describe-active-bindings and keymap sequence_help_keymap,
and supporting code in input.js and help.js to support the feature of
being able to hit C-h in the middle of a key sequence to get a help buffer
describing the active keymaps.
---
 modules/bindings/default/global.js |  4 ++++
 modules/help.js                    | 40 ++++++++++++++++++++++++++++++++------
 modules/input.js                   |  6 +++++-
 3 files changed, 43 insertions(+), 7 deletions(-)

diff --git a/modules/bindings/default/global.js b/modules/bindings/default/global.js
index 3e3cd00..02f3db8 100644
--- a/modules/bindings/default/global.js
+++ b/modules/bindings/default/global.js
@@ -25,6 +25,10 @@ define_key(default_help_keymap, "w", "where-is");
 define_key(default_base_keymap, "C-h", default_help_keymap);
 
 
+define_keymap("sequence_help_keymap");
+define_key(sequence_help_keymap, "C-h", "describe-active-bindings");
+
+
 /**
  * Note: Most buffer keymaps should set this as the parent.
  */
diff --git a/modules/help.js b/modules/help.js
index cd231ef..8466b7b 100644
--- a/modules/help.js
+++ b/modules/help.js
@@ -230,9 +230,15 @@ describe_bindings_buffer.prototype = {
 };
 
 
-function describe_bindings (buffer, target) {
+function describe_bindings (buffer, target, keymaps, prefix) {
     var list = [];
-    var keymaps = get_current_keymaps(buffer.window);
+    if (! keymaps)
+        keymaps = get_current_keymaps(buffer.window);
+    if (prefix)
+        prefix = format_binding_sequence(
+            prefix.map(function (x) { return {key:x}; }))+" ";
+    else
+        prefix = "";
     for_each_key_binding(keymaps, function (binding_stack) {
             var last = binding_stack[binding_stack.length - 1];
             if (last.command == null && !last.fallthrough)
@@ -247,7 +253,7 @@ function describe_bindings (buffer, target) {
                     bound_in = bound_in.bound_in;
                 }
             }
-            var bind = {seq: format_binding_sequence(binding_stack),
+            var bind = {seq: prefix+format_binding_sequence(binding_stack),
                         fallthrough: last.fallthrough,
                         command: last.command,
                         bound_in: bound_in.name,
@@ -266,9 +272,31 @@ function describe_bindings_new_buffer (I) {
 function describe_bindings_new_window (I) {
     describe_bindings(I.buffer, OPEN_NEW_WINDOW);
 }
-interactive("describe-bindings", null,
-            alternates(describe_bindings_new_buffer, describe_bindings_new_window));
-
+interactive("describe-bindings",
+    "Show a help buffer describing the bindings in the context keymaps, "+
+    "meaning the top-level keymaps according to the focus context in the "+
+    "current buffer.",
+    alternates(describe_bindings_new_buffer,
+               describe_bindings_new_window));
+
+function describe_active_bindings_new_buffer (I) {
+    describe_bindings(I.buffer, OPEN_NEW_BUFFER,
+                      I.keymaps || get_current_keymaps(I.buffer.window),
+                      I.key_sequence.slice(0, -1));
+}
+function describe_active_bindings_new_window (I) {
+    describe_bindings(I.buffer, OPEN_NEW_WINDOW,
+                      I.keymaps || get_current_keymaps(I.buffer.window),
+                      I.key_sequence.slice(0, -1));
+}
+interactive("describe-active-bindings",
+    "Show a help buffer describing the bindings in the active keymaps, "+
+    "meaning the keymaps in the middle of an ongoing key sequence.  This "+
+    "command is intended to be called via `sequence_help_keymap'.  For "+
+    "that reason, `describe-active-bindings' does not consume and prefix "+
+    "commands like `universal-argument', as doing so would lead to "+
+    "ambiguities with respect to the intent of the user.",
+    describe_active_bindings_new_buffer);
 
 
 /*
diff --git a/modules/input.js b/modules/input.js
index 49bceee..a50a293 100644
--- a/modules/input.js
+++ b/modules/input.js
@@ -172,13 +172,17 @@ sequence:
                 I.combo = combo;
                 I.event = clone;
 
+                // make active keymaps visible to commands
+                I.keymaps = keymaps;
+
                 if (keypress_hook.run(window, I, event))
                     break;
 
                 var overlay_keymap = I.overlay_keymap;
 
                 var binding = (overlay_keymap && keymap_lookup([overlay_keymap], combo, event)) ||
-                    keymap_lookup(keymaps, combo, event);
+                    keymap_lookup(keymaps, combo, event) ||
+                    keymap_lookup([sequence_help_keymap], combo, event);
 
                 // kill event for any unbound key, or any bound key which
                 // is not marked fallthrough
-- 
2.11.4.GIT