Improve keyboard shortcuts documentation (#1799)

* Improve keyboard shortcuts documentation * unnecessary "and" * remove example how to override "auto_complete_open_link"
sublimelsp · Jul 20, 2021 · 154b7c7 · 154b7c7
1 parent 677e6dc
commit 154b7c7
Show file tree

Hide file tree

Showing 2 changed files with 53 additions and 81 deletions.
diff --git a/docs/src/customization.md b/docs/src/customization.md
@@ -13,6 +13,59 @@ html {
 to `Packages/User/mdpopups.css`.
 See the [mdpopups documentation](http://facelessuser.github.io/sublime-markdown-popups/) for more details.
 
+## Keyboard shortcuts (key bindings)
+
+LSP's key bindings can be edited from the `Preferences: LSP Key Bindings` command from the Command Palette. Many of the default key bindings (visible in the left view) are disabled to avoid conflicts with default or user key bindings. To enable those, copy them to your user key bindings on the right, un-comment, and pick the key shortcut of your choice.
+
+If you want to customize the provided key bindings (or create new ones) and make them only be active when there is a language server with a specific [LSP capability](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize) (refer to the `ServerCapabilities` structure in that link) running, you can make use of the `lsp.session_with_capability` context. For example, the following example overrides `ctrl+r` to use LSP's symbol provider but only when the current view has a language server with the `documentSymbolProvider` capability and we're in a javascript or a typescript file:
+
+```js
+{
+    "command": "lsp_document_symbols",
+    "keys": [
+        "ctrl+r"
+    ],
+    "context": [
+        {
+            "key": "lsp.session_with_capability",
+            "operator": "equal",
+            "operand": "documentSymbolProvider"
+        },
+        {
+            "key": "selector",
+            "operator": "equal",
+            "operand": "source.ts, source.js"
+        }
+    ]
+},
+```
+
+But generally, you should not need to restrict your key bindings to specific scopes and just rely on checking the capability context.
+
+## Mouse map configuration
+
+If you want to bind some action to a mouse, open `Preferences / Browser Packages` from the main menu and create a sublime-mousemap file in the following location within the Packages folder:
+
+| Platform | Path |
+| -------- | ---- |
+| Windows  | `/User/Default (Windows).sublime-mousemap` |
+| Linux    | `/User/Default (Linux).sublime-mousemap` |
+| Mac      | `/User/Default (OSX).sublime-mousemap` |
+
+Here is an example mouse binding that triggers LSP's "go to symbol definition" command on pressing the <kbd>ctrl</kbd>+<kbd>left click</kbd>:
+
+```js
+[
+    {
+        "button": "button1",
+        "count": 1,
+        "modifiers": ["ctrl"],
+        "press_command": "drag_select",
+        "command": "lsp_symbol_definition",
+    }
+]
+```
+
 ## Color scheme customizations
 
 Some features use TextMate scopes to control the colors (underline, background or text color) of styled regions in a document or popup.

diff --git a/docs/src/features.md b/docs/src/features.md
@@ -66,43 +66,6 @@ You can include special variables in the `command_args` array that will be autom
 | `"$position"` or `"${position}"` | object | JSON object `{ 'line': int, 'character': int }` of the (topmost) cursor position, see [Position](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#position) |
 | `"$range"` or `"${range}"` | object | JSON object with `'start'` and `'end'` positions of the (topmost) selection, see [Range](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#range) |
 
-### Overriding keybindings
-
-LSP's keybindings can be edited from the `Preferences: LSP Keybindings` command from the command palette.
-There is a special context called `lsp.session_with_capability` that can check whether there is a language server active
-with the given [LSP capability](https://microsoft.github.io/language-server-protocol/specifications/specification-current/#initialize).
-Refer to the `ServerCapabilities` structure in that link.
-The following example overrides `ctrl+r` to use LSP's symbol provider when we're in a javascript or typescript view:
-
-```js
-{
-    "command": "lsp_document_symbols",
-    "keys": [
-        "ctrl+r"
-    ],
-    "context": [
-        {
-            "key": "lsp.session_with_capability",
-            "operator": "equal",
-            "operand": "documentSymbolProvider"
-        },
-        {
-            "key": "selector",
-            "operator": "equal",
-            "operand": "source.ts, source.js"
-        }
-    ]
-},
-```
-
-More useful keybindings (OS-X), edit Package Settings -> LSP -> Key Bindings
-```js
-  { "keys": ["f2"], "command": "lsp_symbol_rename" },
-  { "keys": ["f12"], "command": "lsp_symbol_definition" },
-  { "keys": ["super+option+r"], "command": "lsp_document_symbols" },
-  { "keys": ["super+option+h"], "command": "lsp_hover"}
-```
-
 ### Show autocomplete documentation
 
 Some completion items can have documentation associated with them.
@@ -111,47 +74,3 @@ Some completion items can have documentation associated with them.
 
 To show the documentation popup you can click the **More** link in the bottom of the autocomplete,
 or you can use the default sublime keybinding <kbd>F12</kbd> to trigger it.
-
-You can change the default keybinding by remapping the command as below:
-
-```js
-{
-    "command": "auto_complete_open_link",
-    "keys": ["f12"],
-    "context": [
-        {
-            "key": "auto_complete_visible",
-            "operator": "equal",
-            "operand": true
-        }
-    ]
-},
-```
-Note that <kbd>F12</kbd> may conflict with your Goto Definition keybinding. To avoid the conflict, make sure that you
-have a context which checks that the AC widget is not visible:
-```js
-{
-    "command": "lsp_symbol_definition",
-    "keys": [
-        "f12"
-    ],
-    "context": [
-        {
-            "key": "lsp.session_with_capability",
-            "operator": "equal",
-            "operand": "definitionProvider"
-        },
-        {
-            "key": "auto_complete_visible",
-            "operator": "equal",
-            "operand": false
-        }
-    ]
-},
-```
-There is an example of this in LSP's default keybindings.
-
-### Mouse map configuration
-
-See below link, but bind to `lsp_symbol_definition` command
-https://stackoverflow.com/questions/16235706/sublime-3-set-key-map-for-function-goto-definition