docs: clean-up readme

VSCodeVim · Aug 3, 2018 · 507c845 · 507c845
1 parent f12f833
commit 507c845
Showing 1 changed file with 62 additions and 85 deletions.
diff --git a/README.md b/README.md
@@ -41,41 +41,43 @@ VSCodeVim is a Vim emulator for [Visual Studio Code](https://code.visualstudio.c
 
 ## 💾 Installation
 
-VSCodeVim is automatically enabled following [installation](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) and the reloading of VSCode.
+VSCodeVim is automatically enabled following [installation](https://marketplace.visualstudio.com/items?itemName=vscodevim.vim) and reloading of VSCode.
 
 ### Vim Compatibility
 
-Vimscript is _not_ supported, so we are _not_ able to load your `.vimrc` or use `.vim` plugins. You have to replicate these using our [Settings](#settings) and [Emulated plugins](#emulated-plugins).
+Vimscript is _not_ supported, therefore we are _not_ able to load your `.vimrc` or use `.vim` plugins. You have to replicate these using our [Settings](#settings) and [Emulated plugins](#emulated-plugins).
 
 ### Mac Setup
 
-If key repeating isn't working for you, execute this in your Terminal, then restart VS Code.
+To enable key-repeating execute the following in your Terminal and restart VS Code.
 
 ```sh
-defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false         # For VS Code
-defaults write com.microsoft.VSCodeInsiders ApplePressAndHoldEnabled -bool false # For VS Code Insider
-defaults delete -g ApplePressAndHoldEnabled                                      # If necessary, reset global default
+$ defaults write com.microsoft.VSCode ApplePressAndHoldEnabled -bool false         # For VS Code
+$ defaults write com.microsoft.VSCodeInsiders ApplePressAndHoldEnabled -bool false # For VS Code Insider
+$ defaults delete -g ApplePressAndHoldEnabled                                      # If necessary, reset global default
 ```
 
-We also recommend going into _System Preferences -> Keyboard_ and increasing the Key Repeat and Delay Until Repeat settings to improve your speed.
+We also recommend increasing Key Repeat and Delay Until Repeat settings in _System Preferences -> Keyboard_.
 
 ### Windows Setup
 
-VSCodeVim will take over your control keys, just like real vim, so you get the _full_ vim experience. This behaviour can be adjusted with the [`useCtrlKeys`](#vimusectrlkeys) and [`handleKeys`](#vimhandlekeys) settings.
+Like real vim, VSCodeVim will take over your control keys. This behaviour can be adjusted with the [`useCtrlKeys`](#vimusectrlkeys) and [`handleKeys`](#vimhandlekeys) settings.
 
 ### Linux Setup
 
-If you have configured `vim.useSystemClipboard: "true"`, we rely on [clipboardy](https://github.com/sindresorhus/clipboardy) for cross-platform copy/paste operations. This library is dependent on `xsel`:
+If you have configured `vim.useSystemClipboard: "true"`, we rely on [clipboardy](https://github.com/sindresorhus/clipboardy) which is dependent on `xsel`:
 
 ```sh
 apt install xsel
 ```
 
 ## ⚙️ Settings
 
+The settings documented here are a subset of the supported settings; the full list is described in the `Contributions` tab in the extensions menu of VSCode.
+
 ### Quick Example
 
-Below is an example of a [settings.json](https://code.visualstudio.com/Docs/customization/userandworkspace) file for VSCode settings applicable to this extension:
+Below is an example of a [settings.json](https://code.visualstudio.com/Docs/customization/userandworkspace) file with settings relevant to VSCodeVim:
 
 ```json
 {
@@ -109,21 +111,18 @@ Below is an example of a [settings.json](https://code.visualstudio.com/Docs/cust
 }
 ```
 
-The following is a subset of the supported settings; the full list is described in the `Contributions` tab in the extensions menu of VSCode.
-
 ### VSCodeVim settings
 
 These settings are specific to VSCodeVim.
 
 #### `"vim.startInInsertMode"`
 
-- Have VSCodeVim start in Insert Mode rather than Normal Mode.
-- We would be remiss in our duties as Vim users not to say that you should really be staying in Normal mode as much as you can, but hey, who are we to stop you?
+- Start in Insert mode instead of Normal ModeHave VSCodeVim start in Insert Mode rather than Normal Mode.
+- Type: Boolean (Default: `false`)
 
 #### `"vim.overrideCopy"`
 
-- Override VSCode's copy command with our own, which works correctly with VSCodeVim.
-- If cmd-c or ctrl-c is giving you issues, set this to false and complain [here](https://github.com/Microsoft/vscode/issues/217).
+- Override VSCode's copy command with our own, which works correctly with VSCodeVim. If cmd-c/ctrl-c is giving you issues, set this to false and complain [here](https://github.com/Microsoft/vscode/issues/217).
 - Type: Boolean (Default: `true`)
 
 #### `"vim.useSystemClipboard"`
@@ -375,7 +374,7 @@ Custom remappings are defined on a per-mode basis.
     ]
 ```
 
-### Debugging Remappings
+#### Debugging Remappings
 
 1.  Are your configurations correct?
 
@@ -612,94 +611,72 @@ Once sneak is active, initiate motions using the following commands. For operato
 
 ### Input Method
 
-There are two ways you can configure input method, using [`im-select`](https://github.com/daipeihust/im-select), or your own program.(Support macOS and windows for now, linux will come soon)
-
-#### Use im-select
-
-1.  Install im-select
+Disable input method when exiting Insert Mode.
 
-Follow the [Installation Guide](https://github.com/daipeihust/im-select#installation) to install im-select according to your platform.
-
-2.  Find your default input method key
-
-For macOS:
-
-Switch your input method to English, and run following command in your terminal
-
-```shell
-/usr/local/bin/im-select
-```
+| Setting                                 | Description                                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `vim.autoSwitchInputMethod.enable`      | Boolean denoting whether autoSwitchInputMethod is on/off.                                        |
+| `vim.autoSwitchInputMethod.defaultIM`   | Default input method.                                                                            |
+| `vim.autoSwitchInputMethod.obtainIMCmd` | The full path to command to retrieve the current input method key.                               |
+| `vim.autoSwitchInputMethod.switchIMCmd` | The full path to command to switch input method, with `{im}` a placeholder for input method key. |
 
-My output is: `com.apple.keylayout.US`
+You can use any third-party program to switch input methods. We recommend [im-select](https://github.com/daipeihust/im-select), and the following will walkthrough installation and configuration for im-select.
 
-The main English input method key on macOS:
+1.  Install im-select
 
-| key                            | description |
-| ------------------------------ | ----------- |
-| com.apple.keylayout.US         | U.S.        |
-| com.apple.keylayout.ABC        | ABC         |
-| com.apple.keylayout.British    | British     |
-| com.apple.keylayout.Irish      | Irish       |
-| com.apple.keylayout.Australian | Australian  |
-| com.apple.keylayout.Dvorak     | Dvorak      |
-| com.apple.keylayout.Colemak    | Colemak     |
+    Follow the [installation guide](https://github.com/daipeihust/im-select#installation) to install im-select
 
-For windows:
+1.  Find your default input method key
 
-For most people, their default input method key is 1033, the locale ID of en_US. But if your default keyboard layout is not en_US, you can use im-select.exe to find out, the guide is [here](https://github.com/daipeihust/im-select#to-get-current-keyboard-locale). You can also find your locale ID in [this page](https://www.science.co.il/language/Locale-codes.php), the `LCID Decimal` column is the locale ID.
+    - MacOS:
 
-3.  Add configuration to your VScode setting
+      Switch your input method to English, and run the following in your terminal:
 
-```json
-"vim.autoSwitchInputMethod.enable": true,
-"vim.autoSwitchInputMethod.defaultIM": "com.apple.keylayout.US",
-"vim.autoSwitchInputMethod.obtainIMCmd": "/path/to/im-select",
-"vim.autoSwitchInputMethod.switchIMCmd": "/path/to/im-select {im}"
-```
+      ```shell
+      $ /usr/local/bin/im-select
+      ```
 
-- enable: true to turn this function on, false to turn this function off.
-- defaultIM: the input method key from step two, for most mac users is "com.apple.keylayout.US", for most windows users is "1033".
-- switchIMCmd: the command to switch input method, {im} is placeholder for input method key.
-- obtainIMCmd: the command to get current input method key.
+      the program will output your default input method (eg. `com.apple.keyload.US`). The table below is a list of common English key layouts for MacOS.
 
-**Example:**
+      | Key                            | Description |
+      | ------------------------------ | ----------- |
+      | com.apple.keylayout.US         | U.S.        |
+      | com.apple.keylayout.ABC        | ABC         |
+      | com.apple.keylayout.British    | British     |
+      | com.apple.keylayout.Irish      | Irish       |
+      | com.apple.keylayout.Australian | Australian  |
+      | com.apple.keylayout.Dvorak     | Dvorak      |
+      | com.apple.keylayout.Colemak    | Colemak     |
 
-- for macOS:
+    * Windows:
 
-If your default input method key is `com.apple.keylayout.US`, and `im-select` path is default path. The configuration is:
-
-```json
-"vim.autoSwitchInputMethod.enable": true,
-"vim.autoSwitchInputMethod.defaultIM": "com.apple.keylayout.US",
-"vim.autoSwitchInputMethod.obtainIMCmd": "/usr/local/bin/im-select",
-"vim.autoSwitchInputMethod.switchIMCmd": "/usr/local/bin/im-select {im}"
-```
+      For most people, their default input method key is 1033, the locale ID of en_US. But if your default keyboard layout is not en_US, you can use im-select.exe to find out, the guide is [here](https://github.com/daipeihust/im-select#to-get-current-keyboard-locale). You can also find your locale ID in [this page](https://www.science.co.il/language/Locale-codes.php), the `LCID Decimal` column is the locale ID.
 
-- for windows:
+1.  Configure `vim.autoSwitchInputMethod`.
 
-If your default input method key is `1033`(en_US), and your `im-select.exe` is in `bin` dir of D disk. The configuration is:
+    - MacOS:
 
-```json
-"vim.autoSwitchInputMethod.enable": true,
-"vim.autoSwitchInputMethod.defaultIM": "1033",
-"vim.autoSwitchInputMethod.obtainIMCmd": "D:\\bin\\im-select.exe",
-"vim.autoSwitchInputMethod.switchIMCmd": "D:\\bin\\im-select.exe {im}"
-```
+      Given default input method key of `com.apple.keylayout.US` and `im-select` saved to the default location. The configuration is:
 
-#### Use your own program
+      ```json
+      "vim.autoSwitchInputMethod.enable": true,
+      "vim.autoSwitchInputMethod.defaultIM": "com.apple.keylayout.US",
+      "vim.autoSwitchInputMethod.obtainIMCmd": "/usr/local/bin/im-select",
+      "vim.autoSwitchInputMethod.switchIMCmd": "/usr/local/bin/im-select {im}"
+      ```
 
-If you want to use third-party program to switch your input method, your should download it first. Then you should have following config:
+    - Windows:
 
-```json
-"vim.autoSwitchInputMethod.enable": true,
-"vim.autoSwitchInputMethod.defaultIM": "the default(english) input method key your program can recognize",
-"vim.autoSwitchInputMethod.obtainIMCmd": "/path/to/your/program",
-"vim.autoSwitchInputMethod.switchIMCmd": "/path/to/your/program {im}"
-```
+      Given default input method key of `1033`(en_US) and your `im-select.exe` is located at `D:/bin`. The configuration is:
 
-Note: If your program need options to switch IM or get IM, you should add the option to the config.
+      ```json
+      "vim.autoSwitchInputMethod.enable": true,
+      "vim.autoSwitchInputMethod.defaultIM": "1033",
+      "vim.autoSwitchInputMethod.obtainIMCmd": "D:\\bin\\im-select.exe",
+      "vim.autoSwitchInputMethod.switchIMCmd": "D:\\bin\\im-select.exe {im}"
+      ```
 
-For example, your program's usage is `program -s imKey` to switch input method, your `switchIMCmd` config should be "program -s {im}"
+If using an alternative program to switch input methods and it requires a command-line options to switch or get the input method, you should add the options to the configuration. For example, if your program's usage is `my-program -s imKey` to switch input method, your `vim.autoSwitchInputMethod.switchIMCmd` should be `/path/to/my-program -s {im}`.
 
 ## 🎩 VSCodeVim tricks!