From 223859a33b07070d4aa1851d1caa8f344bd079c1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C5=A0t=C4=9Bp=C3=A1n=20N=C4=9Bmec?= <stepnem@gmail.com>
Date: Sat, 25 Sep 2010 02:18:17 +0200
Subject: [PATCH] Make the <k> tag mode-aware.

Previously there was no way to produce links to the appropriate mode-specific
binding of a key using the <k> tag (e.g., <Tab> in the documentation always
linked to the Normal-mode command, although its command-line functionality is
different).  This commit introduces a `mode' attribute to the <k> tag, making
the distinction possible.
---
 common/content/help.xsl           | 14 ++++++++++++++
 common/locale/en-US/cmdline.xml   | 23 +++++++++++++++++++++++
 common/locale/en-US/developer.xml |  7 ++++++-
 common/locale/en-US/index.xml     | 19 +++++++++++--------
 common/locale/en-US/options.xml   |  2 +-
 5 files changed, 55 insertions(+), 10 deletions(-)

diff --git a/common/content/help.xsl b/common/content/help.xsl
index 6f97fa5f..77d9c2e9 100644
--- a/common/content/help.xsl
+++ b/common/content/help.xsl
@@ -328,6 +328,20 @@
             </xsl:call-template>
         </span>
     </xsl:template>
+    <xsl:template match="dactyl:k[@mode]" mode="help-2">
+        <span dactyl:highlight="HelpKey">
+            <xsl:call-template name="linkify-tag">
+                <xsl:with-param name="contents" select="concat(@mode, '_', text())"/>
+            </xsl:call-template>
+        </span>
+    </xsl:template>
+    <xsl:template match="dactyl:k[@mode and @name]" mode="help-2">
+        <span dactyl:highlight="HelpKey">
+            <xsl:call-template name="linkify-tag">
+                <xsl:with-param name="contents" select="concat(@mode, '_', '&lt;', @name, '>', .)"/>
+            </xsl:call-template>
+        </span>
+    </xsl:template>
 
     <!-- HTML-ish elements {{{1 -->
 
diff --git a/common/locale/en-US/cmdline.xml b/common/locale/en-US/cmdline.xml
index 7be3bfc4..d8d502c5 100644
--- a/common/locale/en-US/cmdline.xml
+++ b/common/locale/en-US/cmdline.xml
@@ -140,6 +140,29 @@
 </item>
 
 
+<item>
+    <tags><![CDATA[c_<A-Tab>]]></tags>
+    <strut/>
+    <spec>&lt;A-Tab></spec>
+    <description>
+        <p>
+            Similar to <k name="Tab"/>, but the completion behavior is
+            specified by the <o>altwildmode</o> option.
+        </p>
+    </description>
+</item>
+
+
+<item>
+    <tags><![CDATA[c_<A-S-Tab>]]></tags>
+    <strut/>
+    <spec>&lt;A-S-Tab></spec>
+    <description>
+        <p>The <k name="S-Tab"/> equivalent for <o>altwildmode</o>.</p>
+    </description>
+</item>
+
+
 </document>
 
 <!-- vim:se sts=4 sw=4 et: -->
diff --git a/common/locale/en-US/developer.xml b/common/locale/en-US/developer.xml
index 522cfbf4..08cfec47 100644
--- a/common/locale/en-US/developer.xml
+++ b/common/locale/en-US/developer.xml
@@ -96,7 +96,12 @@
     <dt>ex</dt>         <dd>Link to an ex command. (HelpEx)</dd>
     <dt>k</dt>          <dd>Link to a key. (HelpKey)</dd>
     <dt>&tab;@name</dt> <dd>The name attribute to &lt;k>. When provided, &lt;<a>value</a>> is prepended to
-                            the element's contents, i.e., <em>&lt;k name="lt"/></em> becomes <em><k name="lt"/></em>.
+                            the element's contents, i.e., <em>&lt;k name="Tab"/></em> becomes <em><k name="Tab"/></em>.
+                        </dd>
+    <dt>&tab;@mode</dt> <dd>The mode attribute to &lt;k>. Some keys have different functions in different modes.
+                            You can use this attribute to specify which of the modes (other than Normal) a key pertains to.
+                            The &lt;<a>value</a>> is prepended to the element's contents, i.e., <em>&lt;k name="C-i" mode="i"/></em>
+                            becomes <em><k name="C-i" mode="i"/></em>, and <em>&lt;k mode="i">i&lt;/k></em> becomes <em><k mode="i">i</k></em>.
                         </dd>
     <dt>t</dt>          <dd>Links to an arbitrary help topic. (HelpTopic)</dd>
 </dl>
diff --git a/common/locale/en-US/index.xml b/common/locale/en-US/index.xml
index 4deb8613..8053e627 100644
--- a/common/locale/en-US/index.xml
+++ b/common/locale/en-US/index.xml
@@ -16,8 +16,9 @@ This file contains a list of all available commands, mappings and options.
 <h2 tag="insert-index">Insert mode</h2>
 
 <dl>
-    <dt><k name="C-i"/></dt> <dd>Launch the external editor</dd>
-    <dt><k name="C-]"/></dt> <dd>Expand an Insert-mode abbreviation</dd>
+    <dt><k mode="i">i</k></dt> <dd>Start Insert mode in text areas when <o>insertmode</o> is not set</dd>
+    <dt><k name="C-i" mode="i"/></dt> <dd>Launch the external editor</dd>
+    <dt><k name="C-]" mode="i"/></dt> <dd>Expand an Insert-mode abbreviation</dd>
 </dl>
 
 
@@ -199,24 +200,26 @@ This file contains a list of all available commands, mappings and options.
 <h2 tag="ex-edit-index">Command-line editing</h2>
 
 <dl>
-    <dt><k name="C-c"/></dt> <dd>Quit Command-line mode without executing</dd>
+    <dt><k name="C-c" mode="c"/></dt> <dd>Quit Command-line mode without executing</dd>
 </dl>
 
 
 <dl>
-    <dt><k name="C-]"/></dt> <dd>Expand a command-line abbreviation</dd>
+    <dt><k name="C-]" mode="c"/></dt> <dd>Expand a command-line abbreviation</dd>
 </dl>
 
 
 <dl>
-    <dt><k name="Up"/></dt> <dd>Recall the previous command line from the history list which matches the current command line</dd>
-    <dt><k name="Down"/></dt> <dd>Recall the next command line from the history list which matches the current command line</dd>
+    <dt><k name="Up" mode="c"/></dt> <dd>Recall the previous command line from the history list which matches the current command line</dd>
+    <dt><k name="Down" mode="c"/></dt> <dd>Recall the next command line from the history list which matches the current command line</dd>
 </dl>
 
 
 <dl>
-    <dt><k name="Tab"/></dt> <dd>Complete the word in front of the cursor according to the behavior specified in <o>wildmode</o></dd>
-    <dt><k name="S-Tab"/></dt> <dd>Complete the previous full match when <o>wildmode</o> contains "full"</dd>
+    <dt><k name="Tab" mode="c"/></dt> <dd>Complete the word in front of the cursor according to the behavior specified in <o>wildmode</o></dd>
+    <dt><k name="S-Tab" mode="c"/></dt> <dd>Complete the previous full match when <o>wildmode</o> contains "full"</dd>
+    <dt><k name="A-Tab" mode="c"/></dt> <dd>Complete the word in front of the cursor according to the behavior specified in <o>altwildmode</o></dd>
+    <dt><k name="A-S-Tab" mode="c"/></dt> <dd>Complete the previous full match when <o>altwildmode</o> contains "full"</dd>
 </dl>
 
 
diff --git a/common/locale/en-US/options.xml b/common/locale/en-US/options.xml
index 9e7b6b56..7afbf935 100644
--- a/common/locale/en-US/options.xml
+++ b/common/locale/en-US/options.xml
@@ -335,7 +335,7 @@
     <default>list:full</default>
     <description>
         <p>
-            Like <o>wildmode</o>, but when the <k name="Alt"/> key is pressed.
+            Like <o>wildmode</o>, but when the <k name="A-Tab"/> key is pressed.
         </p>
     </description>
 </item>