mlf176f2 pushed a commit to branch externals/ergoemacs-mode in repository elpa.
commit 25345889e53c7c1891e840844bd4ff7851004aea Author: Matthew L. Fidler <[email protected]> Date: Mon Jun 16 10:58:28 2014 -0500 Reduce Readme.md and add build status --- Readme.md | 433 +------------------------------------------------------------ 1 files changed, 2 insertions(+), 431 deletions(-) diff --git a/Readme.md b/Readme.md index 0d08f9a..91b937d 100644 --- a/Readme.md +++ b/Readme.md @@ -1,4 +1,4 @@ -# Ergoemacs Keybindings +# Ergoemacs Keybindings [](http://travis-ci.org/ergoemacs/ergoemacs-mode) Xah Lee, David Capello, and Matthew Fidler @@ -18,433 +18,4 @@ bundles many Emacs Lisp functions that are not in GNU Emacs by default. (ergoemacs-mode 1) -## Tips for adopting ErgoEmacs Keybindings -If you are a long time emacs user, you may find it painful to adopt -this setup. - -This difficulty is nothing special. It's the same difficulty when you -switching to dvorak after years of qwerty. Basically, it's about -changing muscle memory. - -### Where Did My Command Go? -The ergonomic-mode minor mode features the command -where-is-old-binding, with shortcut “Ctrl+h o”. This command asks you -to type a shortcut, and tells you which command it was bound in GNU -Emacs, and the new shortcut for it under ErgoEmacs?. - -### Shortcut To Open Cheatsheet -You can open a cheatsheet by pressing [Control+h] [']. On the first -run, this will create a svg and (possibly) create a png based on the -svg (if `ergoemacs-inkscape` points to the inkscape executable). Once -these are created, the cheatsheet will be opened displaying all the -keys based on your layout. -### Gradual Adoption for an Emacs User -Here's some tips that may help you adopt. -#### Level 1 -If you find it too painful to switch, don't use the whole package. Instead, start off with just the arrow key movements. - - (setq ergoemacs-theme "lvl1") - (ergoemacs-mode 1) - -Either put the above in your emacs init file (usually at “~/.emacs”), or customize ergoemacs-mode to set the theme to lvl1. - -With only the above change, you will increase your emacs productivity, especially if you are a touch typist. These single char cursor moving commands are the top 4 most frequently used emacs commands by statistics, roughly accounting for 43% of commands that have a shortcut. - - -Once you used the above for a couple of weeks, you may add more keys to adopt. - -#### Level 2 -Adding keys for moving around words and deleting words. - - (setq ergoemacs-theme "lvl2") - (ergoemacs-mode 1) - -#### Level 3 -Full ergoemacs keyset without the <menu> unchorded keys. - - (setq ergoemacs-theme "lvl3") - (ergoemacs-mode 1) - -#### Full Ergoemacs Keys~ -Try to use the full ergoemacs mode. - - (setq ergoemacs-theme nil) - (ergoemacs-mode 1) - -#### Guru -The guru theme takes away the arrow keys and page up/page down keys. - - (setq ergoemacs-theme "guru") - (ergoemacs-mode 1) - -#### Master -The Master theme takes away the backspace. This key is not -particularly ergonomic, and can cause possible pinky issues. -Changing this means that you may wish to try to get ergoemacs -bindings everywhere. - - (setq ergoemacs-theme "master") - (ergoemacs-mode 1) - -## Changing key layouts or adding themes -### Globally defined keys -These keys are defined on the global keymap and should be retained -regardless of the theme or layout used. However, these keys will -not show up on keyboard documentation generated by ergoemacs. -Additionally, these keys may be masked or remapped by other programs. -### Ergoemacs defined keys -These keys are defined in the ergoemacs-keymap. When the layout -changes by changing options, these keys are lost. However, you may -create your own theme to allow these keys to be saved. -#### Adding a ergonomic key -Ergonomic keys can be added by: - - (ergoemacs-key "M-a" 'execute-extended-command "Execute") - -This adds the Alt-a command to all keyboards based on the QWERTY -layout. This only applies to the currently selected keyboard theme. - -Note the last parameter is optional and allows Ergoemacs to document -that this is an "Execute" command when generating keyboard layout diagrams. -#### Adding a fixed key -Fixed keys can be added by: - - (ergoemacs-fixed-key "C-o" 'ido-find-file "Open File") - -This adds the fixed key to the currently selected emacs theme - -Note the last parameter is optional and allows Ergoemacs to document -that this is an "Open" command when generating keyboard layout diagrams. - -#### Adding an ergonomic key map with fixed mappings -When you want to add an ergonomic keymap with fixed mappings such as -the ergoprog theme you can add them as follows: - - (ergoemacs-key "M-m s" 'save-buffer "" t) - -This converts the QWERTY M-m keybinding and the fixed keybinding s to -save buffer - -#### Creating a keyboard theme -## Ergoemacs-mode and starter-kits like prelude, emacs live, etc -Ergoemacs-mode currently honors globally keys that are different from -the standard emacs keys. However, some starter kits, like prelude, -may compete for these keys. To make the ErgoEmacs keys dominate, -load the starter kit and then add the following to your startup - - (require 'ergoemacs-mode) - (ergoemacs-ignore-prev-global) ; Do not honor previously defined - ; global keys. - (ergoemacs-mode 1) - -## Ergoemacs interaction with specific modes -### -## Ergoemacs Keys System wide -### Bash -### Windows -In windows some of the ergoemacs keys are implemented system wide by -assuming apps follow the CUA-style keys like CTRL-f for find, CTRL-h -for replace. This also optionally implements: -- CapsLock as Menu in emacs -### Mac OS X -## Developer information -### Layouts -All the layouts in ergoemacs are easy to generate. To add your own -personal layout you just need to match the keybindings for your in a -layout variable from `ergoemacs-layout-XXX`. For the US and UK -layouts, the defining variable adds the layout: - -``` -(defvar ergoemacs-layout-us - '("" "`" "1" "2" "3" "4" "5" "6" "7" "8" "9" "0" "-" "=" "" - "" "" "q" "w" "e" "r" "t" "y" "u" "i" "o" "p" "[" "]" "\\" - "" "" "a" "s" "d" "f" "g" "h" "j" "k" "l" ";" "'" "" "" - "" "" "z" "x" "c" "v" "b" "n" "m" "," "." "/" "" "" "" - ;; Shifted - "" "~" "!" "@" "#" "$" "%" "^" "&" "*" "(" ")" "_" "+" "" - "" "" "Q" "W" "E" "R" "T" "Y" "U" "I" "O" "P" "{" "}" "|" - "" "" "A" "S" "D" "F" "G" "H" "J" "K" "L" ":" "\"" "" "" - "" "" "Z" "X" "C" "V" "B" "N" "M" "<" ">" "?" "" "" "") - "US Engilsh QWERTY Keyboard") - -(defvar ergoemacs-layout-gb - '("" "`" "1" "2" "3" "4" "5" "6" "7" "8" "9" "0" "-" "=" "" - "" "" "q" "w" "e" "r" "t" "y" "u" "i" "o" "p" "[" "]" "" - "" "" "a" "s" "d" "f" "g" "h" "j" "k" "l" ";" "'" "#" "" - "" "\\" "z" "x" "c" "v" "b" "n" "m" "," "." "/" "" "" "" - ;; Shifted - "" "¬" "!" "@" "#" "$" "%" "^" "&" "*" "(" ")" "_" "+" "" - "" "" "Q" "W" "E" "R" "T" "Y" "U" "I" "O" "P" "{" "}" "" - "" "" "A" "S" "D" "F" "G" "H" "J" "K" "L" ":" "@" "~" "" - "" "|" "Z" "X" "C" "V" "B" "N" "M" "<" ">" "?" "" "" "") - "UK QWERTY") -``` - -This lists the keyboard positions from left to right for the unshifted -and shifted states of he keyboard. After listing the keyboard -descriptions it provides a description of the layout which is used for -the customization variable `ergoemacs-keyboard-layout'. By simply -defining your layout before ergoemacs-mode is loaded, you add it to -the ergoemacs-keyboard-layout variable with its description. -### Customizing/Saving the variables -You can customize the ergoemacs keybindings by typing M-x -customize-group ergoemacs-mode - -### Extras -To generate keyboard binding diagrams and scripts that allow you to -use ergoemacs elsewhere, please type M-x ergoemacs-extra. These -scripts will be stored under the extras directory. - -Note that if you use an alternative layout on a QWERTY keyboard (such -as colemak), and use the portable colemak layout, to use ergoemacs -keys use the us layout not the colemak layout. However, if you -installed the colemak keyboard layout to your system, use the colemak -not the US layout theme. - -### Updating Ergoemacs for the latest version of emacs -To tell if a key was a globally defined emacs key, ergoemacs needs to -know what key was defined by emacs. This typically changes a little -for each emacs version. This is due to renamed functions, or -re-purposed keys. To update for the current version of emacs, you -can type - - (ergoemacs-warn-globally-changed-keys t) - -This is also done in the test suite. This can be accessed by -`ergoemacs-test` command. - -## Contributing to ErgoEmacs -ErgoEmacs is a collaborative project and we encourage contributions -from anyone and everyone. If you want to contribute in the way that -will help us most, we recommend fixing reported bugs and implementing -the feature ideas in [Issues](https://github.com/ergoemacs/ergoemacs-mode/issues). However, if you think of new features to -add, please suggest them too -- we might like your idea. - -### Coding Style and conventions -- Remove all trailing whitespace in all source and text files. - -- Use ?\s instead of ? in Lisp code for a space character. - -### Document your changes -Think carefully about whether your change requires updating the -documentation. - -## Experimental Ergoemacs -This section is experimental ergoemacs keybindings that are being -incorporated into ergoemacs. These are likely to change and are a -work in progress. - -### Banish Key Chords -#### Background -Key chords (like 【Ctrl+x】) is the bane of keyboarding. -There are 3 types of key shortcuts to invoke commands in software: - -1. Single key. Examples include: 【F1】, 【⇞ Page △】. -2. Key chord: 【⇧ Shift+a】, 【Ctrl+c】, 【Ctrl+⇧ Shift+z】, 【Alt+F4】. -3. Key sequence of single keys or chords. For example on Microsoft - Windows, 【F10 e c】 for copy, or 【Alt+Space c】 to close window. - -of these, in terms of efficiency and hand health (Repetitive Strain -Injury), the single key is the best. Key sequence of single keys is -second best. Key chord is the worst. - -Key chord is the most hard on hand health, but is also conceptually -the most convoluted. - -I [Xah Lee] remember in around 1991, when i first learned about key -chord on the Macintosh Classic. I thought, it's strange. You have to -hold ⌘ Cmd first, then press the key c, then, release c, then, release -⌘ Cmd. It must be in that specific order. - -A more natural way is either key sequence, or real chords. That is, -pressing several keys together but you don't have to worry about which -to hold or release first. Stenograph machines are like that. - -##### Whence Did Key Chord Came From? -I suppose, when computer keyboard came, sans levels and gears, but -habit stuck, and this evolved into “modifier” keys, with Bucky bits. - -Now, thinking about this, i think Microsoft must be a genius, when -they invented the key system on Windows, where Alt is used to invoke -menu, and all command can be called by a sequence of key strokes. This -is probably the best system given the PC keyboard. This system, lets -you invoke any command, yet has menu counter-part, so it's easy to see -a list of them and also grouped by category. (emacs's system of course -is much more extensive than that.) - -##### What Should a Keyboard Nerd Do with Key Chords? -BAN the them out of the universe. - -But, there isn't enough keys on keyboard. You only have 12 function -keys, plus some others such as ↖ Home, ↓. But there are 10 times more -commands in software. What to do? - -For majority of commands, you should use a key sequence of single -keys, instead. For example, 【F10 e c】. But Function keys are further -away. So, you could start with a easy key such as 【▤ Menu e c】, and -reassign most of your keys to key sequence. (you can make Caps Lock as -your start key, whichever key on YOUR keyboard is easy to press.) - -There are 26 letters in alphabet, plus 10 digits, so you have 36 key -choices for the key. (ignore punctuation keys for the moment) If each -of your command has 2 keys in a key sequence (not counting the -starting key), then you have 36 × 36 = 1296 possible keys for -commands. Quite enough! - -Still, some commands are not suitable for key sequence. For example, -moving cursor by word. You want to be able to hold down a key and have -the cursor keep moving. You can't do that with key sequences, because -you need to release the key and press again to invoke the command -again. Answer: use single key. Retort: But F keys are far away and -arrow keys are already used. Answer: key chord then. - -##### Principles on Efficient Use of Key Chords -Key chord should be used only for commands that need to be repeated -within a second (hold the key and let the command repeat). This -includes moving cursor, paging, switching tab/window. - -Key chord should use no more than one modifier. This saves your -hand. So, key chord such as emacs interactive replace 【Alt+⇧ Shift+%】 -or Mac's redo 【⌘ Cmd+⇧ Shift+z】 should not be allowed. - -more detail at Keyboard Shortcut Design: Repeatable vs Non-Repeatable -Commands and Keys - -If you survey commands in a editor, such as emacs, vast majority of -commands are the non-repeating type. The repeating type are probably -less than 5% of commands. Using 【Ctrl+‹letter/digit›】 key give you -about 36 spots. Adding Alt, you have 72 spots. And that's more than -enough for repeating commands. In practice, i estimate a programer -uses less than 30 repeating commands per day on average. -##### What About Sticky Keys? -I do not advocate the Sticky Keys feature for the handicapped. It's -not the same. Sticky Keys actually make things a worse, because it's a -hack over key chords. When you press a sequence of keys, it has to -guess whether you mean a sequence or chord (since emacs supports -both). The end result is that it's confusing to use, imprecise, and -slows you down. - -#### Keyboard Shortcut Design -This section discuss one criterion on the design of keyboard shortcut -system: Repeatable vs Non-Repeatable Commands and Keys. This -applicable in designing keybinding for emacs, vi, 3D modeling app, or -any app that has hundreds commands that needs to map to keys. -##### Repeatable and Non-Repeatable Commands -In my keyboarding research, there's a important discovery. Commands -can be classified into 2 types: -1. Repeatable commands. Commands that make sense to be repeated within - a second. i.e. moving cursor by char, word, page. Page up/down. Delete - by char, word. Expand selection, prev/next tab. You can hold down a - key or a key-chord to repeat the command many times. - -2. Non-repeat commands. This is vast majority. i.e. starting - find/replace, open file, close file, list buffers, call a shell - command or start shell, describe-function, keyword expansion or - completion, list-matching-lines, sort-lines, kill-buffer, - switch-to-buffer, ... - -##### Repeatable and Non-Repeatable Keys -The Repeatable Commands must have keys that can be held down. Here's -example of repeatable hotkeys: F8, t, ⇟ Page ▽, ↓, 【Ctrl+t】, -【Ctrl+Alt+8】, …. - -Non-repeatable hotkeys are basically keys that involves a sequence: -【Ctrl+x 2】, 【F8 F9】 - -So, when designing a shortcut system, one of the principle is for -repeatable commands be on repeatable keys, else it's a waste. (because -you only have a few precious easy key spots, yet you have one hundred -commands in common use.) - -In GNU Emacs's default keybinding, there are many such wastes. For -example, all 【Ctrl+‹number›】 and 【Alt+‹number›】 are bound to -digit-argument. The digit-argument is a non-repeat command, yet it -sits on 20 EASY repeatable keys. (but most damaging is that -digit-argument isn't a frequently needed command, with respect to all -commands and the relatively few easy-key-spots.) - -Another bad example is forward-page 【Ctrl+x ]】. forward-page is a -repeatable command, but it doesn't have a repeating key. Imagine, if -every time you need to ⇟ Page ▽ that you have to press 【Ctrl+x】 -first. You couldn't just hold it down. - -But remember, this “Repeatable and Non-Repeatable key” is only a -supporting criterion in keybinding design. It is not the most -important criterion. The single most important criterion in designing -a keyboard shortcut system is that most frequently used commands be -mapped to the most easy-to-press keys. - -#### Ergoemacs Key Chord Reduction -##### [Control+x] and [Control-c] reduction -For emacs, the most common prefixes are [Control-x] or [Control-c]. - -For QWERTY, an additional mapping of these keys have been made: -- A modified Control-x map has been assigned to Menu f: - - This map allows you to type the keys without a key chord - requirement. For example to switch buffers instead of - [Control+x] [b] you could type [Menu] [f] [b]. (Note that the [f] - key changes based on layout; For example using the colemak layout - you would type [Menu] [t] [b] to switch buffers). - - - This modified keymap changes the control-chorded keys to - alt-chorded keys since they are easier to reach, there is another - keymap that removes the control-chorded keys. Therefore to get - the buffer list, instead of having to type [Control-x] - [Control-b] you can type [Menu] [f] [Alt-b]. - - - The [Alt-] keychords in this modified keymap are changed to - [Control-] keys. For example, `repeat-complex-command` is mapped - from [Control-x] [Alt+:] to [Menu] [f] [Control-:]. As far as I - can tell this is the only [Control-x] [Alt] combination. - -- A modified unchorded Control-x map has assigned to QWERTY [Menu] - [r]. This map has changed the Control-x map as follows: - - - Chorded control keys are subset. Therefore only keys that have - the combination [Control-x] [Control-] are used. - - - Chorded key combinations are changed drop the chord. For example - the buffer list [Control-x] [Conrtol-b] is changed to [Menu] [r] - [b]. - - - Chorded key combinations that are single key are translated to - [Alt+] for example [Control+k] [a] is changed to [Menu] [r] [k] - [Alt+a] - - - Chorded key combinations that work with [Alt+] are translated to - [Control+]. For example [Control+k] [Alt+a] is changed to [Menu] - [r] [k] [Control+a]. I don't think there are currently any keys - bound to these types of key combinations. They are quite - difficult to press and remember. - -Similarly The Control-c keymap is rebound to [Menu] [j] for the -modified [Control-c] keymap and [Menu] [u] for the unchorded -[Control-c] keymap. This is also true of the [Control-h] keymap. -This is bound to [Menu] [h] for the normal Control-h keymap. It is -also bound to [Menu] [y] for the unchorded Control-h keymap. - - -##### Movement without key-chords -###### Method #1 -- <menu> Movement mode -One can enable movement without key-chords as follows: -- On QWERTY, press [Menu] [k] and then the movement key. This key is - repeatable. Therefore [Menu] [k] [k] [k] would move the cursor down - two lines. If this is followed by [i] this would have the cursor - move up a line. To exit the repeatable movement/delete keys press - [Menu]. This is similar to VIM's edit mode, with a toggle of the - [Menu] key. - - Shifted keys still are allowed. For example, page up can be - accomplished in QWERTY by [Shift+i]. - - Any command that enters the minibuffer also exits the repeatable - movement/deletion. - - Any undefined key in the keymap (like 1) would exit the mode and - insert the character -- To reduce the shifted key-chords, on QWERTY you can also press - [Menu] [i]. Therefore [Menu] [i] [i] is equivalent to one page - up. Followed by a [k] will be the page-down equivalent - - Again, [Menu] stops the movement mode and anything that enters - the minibuffer removes the movement mode. - - Any undefined key in the keymap (like 1) would exit the mode and - insert the character - - Shift and the key is the unshifted command. Therefore [Menu] [i] - [i] [Shift+k] would be Page Up followed by down one character. +More information is found at http://ergoemacs.github.io/ergoemacs-mode/ \ No newline at end of file
