From 1557b70f4527c166c5e933c1e2804d511b40dbb9 Mon Sep 17 00:00:00 2001 From: Kris Maglione Date: Fri, 17 Sep 2010 06:21:33 -0400 Subject: Major documentation updates and formatting fixes, and many, many other changes thanks to an MQ glitch, including: * Significant completion speed improvements * Significantly improve startup speed, in large part by lazily instantiating Options and Commands, lazily installing highlight stylesheets, etc. * Update logos and icons, fix atrocious about page * Fix Teledactyl * JavaScript completion now avoids accessing property values * Add Option#persist to define which options are saved with :mkp * Add new Dactyl component which holds add-on-specific configuration information and removes need for separate components for each dactyl host * Several fixes for latest nightlies * Significant code cleanup and many bug fixes --HG-- rename : muttator/AUTHORS => teledactyl/AUTHORS rename : muttator/Donors => teledactyl/Donors rename : muttator/Makefile => teledactyl/Makefile rename : muttator/NEWS => teledactyl/NEWS rename : muttator/TODO => teledactyl/TODO rename : muttator/chrome.manifest => teledactyl/chrome.manifest rename : muttator/components/commandline-handler.js => teledactyl/components/commandline-handler.js rename : muttator/components/protocols.js => teledactyl/components/protocols.js rename : muttator/content/addressbook.js => teledactyl/content/addressbook.js rename : muttator/content/compose/compose.js => teledactyl/content/compose/compose.js rename : muttator/content/compose/compose.xul => teledactyl/content/compose/compose.xul rename : muttator/content/compose/dactyl.dtd => teledactyl/content/compose/dactyl.dtd rename : muttator/content/compose/dactyl.xul => teledactyl/content/compose/dactyl.xul rename : muttator/content/config.js => teledactyl/content/config.js rename : muttator/content/dactyl.dtd => teledactyl/content/dactyl.dtd rename : muttator/content/logo.png => teledactyl/content/logo.png rename : muttator/content/mail.js => teledactyl/content/mail.js rename : muttator/content/muttator.xul => teledactyl/content/pentadactyl.xul rename : muttator/contrib/vim/Makefile => teledactyl/contrib/vim/Makefile rename : muttator/contrib/vim/ftdetect/muttator.vim => teledactyl/contrib/vim/ftdetect/muttator.vim rename : muttator/contrib/vim/mkvimball.txt => teledactyl/contrib/vim/mkvimball.txt rename : muttator/contrib/vim/syntax/muttator.vim => teledactyl/contrib/vim/syntax/muttator.vim rename : muttator/install.rdf => teledactyl/install.rdf rename : muttator/locale/en-US/Makefile => teledactyl/locale/en-US/Makefile rename : muttator/locale/en-US/all.xml => teledactyl/locale/en-US/all.xml rename : muttator/locale/en-US/autocommands.xml => teledactyl/locale/en-US/autocommands.xml rename : muttator/locale/en-US/gui.xml => teledactyl/locale/en-US/gui.xml rename : muttator/locale/en-US/intro.xml => teledactyl/locale/en-US/intro.xml rename : muttator/skin/icon.png => teledactyl/skin/icon.png --- common/locale/en-US/map.xml | 371 ++++++++++++++++++++++++++++---------------- 1 file changed, 236 insertions(+), 135 deletions(-) (limited to 'common/locale/en-US/map.xml') diff --git a/common/locale/en-US/map.xml b/common/locale/en-US/map.xml index fa6b0db1..091dec56 100644 --- a/common/locale/en-US/map.xml +++ b/common/locale/en-US/map.xml @@ -1,4 +1,4 @@ - + @@ -6,39 +6,71 @@ -

Key mappings, abbreviations, and user-defined commands

+ xmlns="&xmlns.dactyl;" + xmlns:html="&xmlns.html;"> +

Keyboard shortcuts and commands

+

+ &dactyl.appname; provides a number commands to change the + behavior of key presses. This can be mean anythong from + automatically substituting one key for another, to automatically + replacing one typed word for another, to launching a dialog or + running a command. +

+

Key mapping

- The key mapping commands can be used to either redefine the standard key - bindings or define new ones. A mapping consists of a key, or key-sequence, - which is translated to a string of characters. Example: + Key mappings are the most basic means &dactyl.appname; provides + for altering the actions of key presses. Each key mapping is + associated with a mode, such as insert, + normal, or + command-line, and only + has effect when that mode is active. Although each mode has a + full suite of internal mappings, they may be easily augmented, + altered, or removed with the :map command and its + variants. These commands, in essence, allow the user to quickly + substitute one sequence of key presses for another. + For instance,

-:map :echo new Date().toDateString() + +:map :echo Date() +

- will echo the current date to the command line when is pressed. + causes “:echo Date()” to be typed out + whenever is pressed, thus echoing the full date + to the command-line. +

+ +

+ Standard key mapping commands are provided for the four most + common modes,

-:map-modes +
+
n
Normal mode: When browsing normally
+
v
Visual mode: When selecting text with the cursor keys
+
i
Insert mode: When interacting with text fields on a website
+
c
Command-line mode: When typing into the &dactyl.appname; command line
+

- Keys can be mapped in four distinct modes: + The ordinary :map and :noremap commands + add mappings for normal and visual mode. In order to map key + bindings in a different mode, any of the mapping commands may be + prefixed with one of the above letters. For instance, + :imap creates a new key mapping in insert mode, while + :cunmap removes a key mapping from command-line mode. + Although other modes do exist, their mappings may currently only + be altered via JavaScript.

-
    -
  • Normal mode: When browsing normally
    • -
  • Visual mode: When selecting text with the cursor keys
    • -
  • Insert mode: When interacting with text fields on a website
    • -
  • Command-line mode: When typing into the &dactyl.appname; command line
    • -
- - Mappings are NOT saved between sessions, make sure you put them in your - &dactyl.name;rc file! + It is important to note that mappings are not + automatically saved between sessions. In order to preserve them, + they must either be added to your &dactyl.name;rc or + saved via the :mk&dactyl.name;rc command.

Map commands

@@ -56,8 +88,16 @@ :cmap lhs rhs

- Map the key-sequence lhs to rhs for the applicable mode(s). The rhs is - remapped, allowing for nested and recursive mappings. + Map the key-sequence lhs to rhs for + the applicable mode(s). The keys of rhs respect + user-defined mappings, so the following will result in + an infinite loop, +

+ :map a b +:map b a +

+ In order to avoid this shortcoming, the + :noremap command may be used.

@@ -76,9 +116,14 @@ :cnoremap lhs rhs

- Map the key-sequence lhs to rhs for the applicable mode(s). No remapping of - the rhs is performed. + Map the key-sequence lhs to rhs for + the applicable mode(s). The keys in rhs do not + respect user-defined key mappings, so the following + effectively reverses the default meanings of the keys + d and D

+ :noremap d D +:noremap D d @@ -113,8 +158,7 @@ :cmapclear

- Remove all mappings for the applicable mode(s). All user-defined mappings are - cleared. + Remove all user-defined mappings for the applicable mode(s).

@@ -155,12 +199,12 @@ :map-<silent>

- When the first argument to one of the mapping commands is , - rhs is not echoed to the command line, nor, for that matter, anything - else until the command has completed. + When the first argument to one of the mapping commands is + , the keys in rhs are not shown in the + command line as they are generated. Nor, for that matter, is + anything else until the command has completed.

-

Below is an overview of which modes each map command applies to:

@@ -175,70 +219,110 @@ :cmap :cnoremap :cunmap :cmapclear – Command-line mode -

Key sequences

+

Key sequences

- For most keys, the key-sequence is the same as the character you see when you - type that key, however there are some exceptions which allow for a much larger - number of keys to be used in mappings. + Most keys in key sequences are represented simply by the + character that you see on the screen when you type them. + However, as a number of these characters have special meanings, + and a number of keys have no visual representation, a special + notation is required.

    -
  • , <, , \ allow a literal < or space character.
    • -
  • ', " and \ must be used to avoid escaping issues when mapping a quote or backslash.
  • - - - (for carriage return/enter) + The first argument to the :map commands must be + quoted if it contains spaces, + quotation marks or back-slashes. A space may additionally be + typed as .
    • -
  • (for a backspace)
    • +
  • + As special key names start with the < character, + a literal < must be typed as . +
    • +
  • + , , , + and represent the standard arrow keys. +
    • +
  • + , , + , , , + , and work as + expected. +
    • +
  • + or represent the carriage + return key. +
    • +
  • represents the backspace key.
  • through work as expected
    • +
  • + through represent keys on the + numeric keypad. +

- Most keyboards have some modifiers such as the control, alt or meta keys. In - order to create a mapping that uses these keys the correct prefix must be used - within the angle brackets. + In order to represent key presses using the Control, Alt, Meta, + or Shift keys, the following prefixes may be used,

    -
  1. : The control or ctrl key.
    2. -
  2. : The alt key.
    3. -
  3. : The meta key, windows key, or command key
    4. -
  4. : The shift key.
    5. +
  5. : The control or ctrl key.
    6. +
  6. : The alt key.
    7. +
  7. : The meta key, windows key, or command key
    8. +
  8. : The shift key.

- These prefixes can be combined however you see fit, though you should note that - within angle brackets all alphabetic characters are read as lowercase. In order - to force them to be uppercase, you must specify the S- prefix as well. - Additionally, you should never use the S- prefix with a number or piece of - punctuation, even if you require a shift to type that character; doing so will - give you a mapping that cannot be typed. With non-character keys, tab and - space, the S- modifier works just like C- A- and M-. Some examples may clarify - the situation: + These prefixes can be combined however you see fit, though you + should note that within angle brackets all alphabetic characters + are read as lowercase. Uppercase characters can only be + specified with the S- modifier. The following key + sequences are interperated as described,

-
    -
  1. xc: type x, and then type c
    2. -
  2. c: hold control and type x, then type c without control
    3. -
  3. : type 2 while holding control
    4. -
  4. : type @ while holding control
    5. -
  5. : press space while holding shift
    6. -
  6. : press j while holding control and alt
    7. -
  7. : exactly the same as above
    8. -
  8. : press J while holding control and alt
    9. -
+
+
xc
+
Type the ‘X’ key followed by the ‘C’ key
+ +
c
+
+ Type the ‘X’ key while holding the ‘Control’ key, followed + by the ‘C’ key. +
+ +
+
Type the ‘2’ while holding the ‘Control’ key.
+ +
+
Type the ‘2’ key @ while holding the ‘Control’ key.
+ +
+
Press the space bar while holding the ‘Shift’ key.
+ +
+
Type the ‘J’ key while while holding both the ‘Control’ and ‘Alt’ keys.
+ +
+
Exactly the same as above.
+ +
+
Type the ‘J’ key while while holding both the ‘Control’, ‘Alt’, and ‘Shift’ keys.
+

Special characters

]]> + <Nop>

- Do nothing. This command is useful for disabling a specific mapping. - :map will prevent from doing anything. + Do nothing. This pseudo-key is useful for disabling a + specific builtin mapping. For example, + :map will prevent + from doing anything.

@@ -246,6 +330,7 @@ map_return]]> + <CR>

@@ -258,20 +343,21 @@ - mapleader]]> + mapleader \]]> + <Leader>

- Expands to the value of the "mapleader" variable in key mapping. If - "mapleader" is unset or empty then \ is used. Example: + Expands to the value of the ‘mapleader’ variable in key mapping. If + ‘mapleader’ is unset or empty then ‘\’ is used. For example, by default,

- :map h :echo Hello + :map h :echo Hello

works like

- :map \h :echo Hello + :map \h :echo Hello

but after

- let mapleader = , + :let mapleader = ,

it works like

- :map ,h :echo Hello + :map ,h :echo Hello @@ -279,27 +365,27 @@

Abbreviations

- &dactyl.appname; can automatically replace words identified as abbreviations, - which may be used to save typing or to correct commonly misspelled - words. An abbreviation can be one of three types that are defined by the - types of constituent characters. Whitespace and quotes are non-keyword - types, and all other characters are keyword types. + In addition to basic mappings, &dactyl.appname; can also + automatically replace whole words after they've been typed. + These shortcuts are known as abbreviations, and are most often + useful for correcting spelling of commonly mistyped words, as + well as shortening the typing of oft-typed but long words or + phrases. There are three basic types of abbreviations, defined + by the types of characters they contain,

-
    -
  1. A "full-id" abbreviation consists entirely of keyword characters (e.g., "teh", "msoft").
    2. -
  2. An "end-id" abbreviation ends in keyword character but otherwise contains all non-keyword characters (e.g., "'i").
    3. -
  3. A "non-id" abbreviation ends in a non-keyword character but otherwise contains any non-whitespace character (e.g., "def'").
    4. -
- -

- Strings that cannot be abbreviations include "a'b" and "a b". -

+
    +
  • ‘full-id’ abbreviations consist entirely of keyword characters (e.g., ‘teh’, ‘msoft’).
    • +
  • ‘end-id’ abbreviations end in keyword character but otherwise contains all non-keyword characters (e.g., ‘'i’).
    • +
  • ‘non-id’ abbreviations end in a non-keyword character but otherwise contains any non-whitespace character (e.g., ‘def'’).
    • +
  • Strings which fit none of the above patterns can not be defined as abbreviations (e.g., ‘a'b’ and ‘a b’).
    • +

- An abbreviation is recognized when a space, quote character, or - is typed after the abbreviation. There are no default - abbreviations, and abbreviations are never recursive. + For the purposes of abbreviations, keyword characters include + all non-whitespace characters except for single or double + quotation marks. Abbreviations are expanded as soon as any + non-keyword character, or the key , is typed.

@@ -309,9 +395,10 @@ :abbreviate

- Abbreviate a key sequence. Abbreviate lhs to rhs. If only lhs is given, - list all abbreviations that start with lhs. If no arguments are given, - list all abbreviations. + Abbreviate lhs to rhs. If only lhs + is given, list all abbreviations that start with + lhs. If no arguments are given, list all + abbreviations.

@@ -324,8 +411,9 @@ :cabbrev

- Abbreviate a key sequence for Command-line mode. Same as :abbreviate, - but for Command-line mode only. + Abbreviate a key sequence for Command-line mode. Same as + :abbreviate, but for + command-line mode only.

@@ -338,8 +426,8 @@ :iabbrev

- Abbreviate a key sequence for Insert mode. Same as :abbreviate but - for Insert mode only. + Abbreviate a key sequence for Insert mode. Same as + :abbreviate, but for insert mode only.

@@ -359,8 +447,9 @@ :cunabbrev lhs

- Remove an abbreviation for Command-line mode. Same as :unabbreviate, - but for Command-line mode only. + Remove an abbreviation for Command-line mode. Same as + :unabbreviate, but for + command-line mode only.

@@ -371,8 +460,9 @@ :iunabbrev lhs

- Remove an abbreviation for Insert mode. Same as :unabbreviate but for - Insert mode only. + Remove an abbreviation for Insert mode. Same as + :unabbreviate but for Insert mode + only.

@@ -381,7 +471,7 @@ :abc :abclear :abclear - +

Remove all abbreviations.

 @@ -390,8 +480,8 @@ :cabc :cabclear :cabclear - -

Remove all abbreviations for Command-line mode.

+ +

Remove all abbreviations for command-line mode.

 @@ -399,7 +489,7 @@ :iabc :iabclear :iabclear - +

Remove all abbreviations for Insert mode.

 @@ -407,10 +497,21 @@

User-defined commands

+

+ Defining new commands is perhaps the most straightforward way of + repeating commonly used actions. User-defined commands may be + entered from the command-line or scripts exactly like standard + commands, and may similarly accept arguments, options, counts, + and !s, as well as provide command-line completion. + These commands may be defined as either ordinary, + macro-interpolated Ex commands, or otherwise as plain + JavaScript statements. +

+ :com :command :command - +

List all user-defined commands.

 @@ -428,22 +529,34 @@ :command! attr… cmd rep

- Define a new user command. The name of the command is cmd and its replacement - text is rep. The command's attributes are attr. If a command with this name - already exists an error is reported unless ! is specified, in which case the - command is redefined. Unlike Vim, the command may start with a lowercase - letter. + Define a new user command. The name of the command is + cmd and its replacement text is rep. If a + command with this name already exists, an error is + reported unless ! is specified, in which case + the command is redefined. Unlike Vim, the command may + start with a lowercase letter.

- The command's behavior can be specified by providing attributes when the - command is defined. + The new command is usually defined by a string to be + executed as an Ex command. In this case, before + execution, strings of the form + <var> are interpolated + as described below, in order to insert arguments, + options, and the like. If the -javascript (short + name -js) flag is present, the command is + executed as JavaScript, and the arguments are present as + variables in its scope instead, and no interpolation is + performed.

-

- Argument handling +

+ The command's behavior can be altered by providing + attributes when the command is defined.

+

Argument handling

+

By default user commands accept no arguments. This can be changed by specifying the -nargs attribute. @@ -459,9 +572,7 @@

-nargs=+
One or more arguments are allowed
-

- Argument completion -

+

Argument completion

Completion for arguments to user defined commands is not available by default. @@ -496,9 +607,7 @@

custom,func
custom completion, provided by func
-

- Custom completion -

+

Custom completion

Custom completion can be provided by specifying the custom,func argument to @@ -516,9 +625,7 @@ -

- Count handling -

+

Count handling

By default user commands do not accept a count. Use the -count attribute if @@ -526,9 +633,7 @@ available for expansion as <count> in the argument.

-

- Special cases -

+

Special cases

By default a user command does not have a special version, i.e. a version @@ -536,18 +641,14 @@ and <bang> will be available in the argument.

-

- Command description -

+

Command description

The command's description text can be set with -description. Otherwise it will default to "User-defined command".

-

- Replacement text -

+

Replacement text

The replacement text rep is scanned for escape sequences and these are @@ -580,7 +681,7 @@ :comc :comclear :comclear - +

Delete all user-defined commands.

 -- cgit v1.2.3