docs: described lsp-mode configuration

Ubuntu · Ubuntu · commit 5ffd98df72d8 · 2022-07-28T20:51:48.000Z
diff --git a/docs/ides/configuring-emacs-tramp.md b/docs/ides/configuring-emacs-tramp.md
@@ -8,9 +8,9 @@ To connect to your workspace first run:
 coder config-ssh
 ```
 
-Then you can connect to your workspace by its name in the format: `coder.<name>`.
+Then you can connect to your workspace by its name in the format: `coder.<WORKSPACE NAME>`.
 
-In Emacs type `C-x d` and then input: `/-:coder.<name>:` and hit enter. This will open up Dired on the workspace's home directory.
+In Emacs type `C-x d` and then input: `/-:coder.<WORKSPACE NAME>:` and hit enter. This will open up Dired on the workspace's home directory.
 
 ### Using SSH
 By default Emacs TRAMP is setup to use SCP to access files on the Coder workspace instance. However you might want to use SSH if you have a jumpbox or some other complex network setup.
@@ -21,7 +21,7 @@ To do so set the following in your Emacs `init.el` file:
 (setq tramp-default-method "ssh")
 ```
 
-Then when you access the workspace instance via `/-:coder.<name>` Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term` mode the correct way to access the remote when directory tracking.
+Then when you access the workspace instance via `/-:coder.<WORKSPACE NAME>` Emacs will use SSH. Setting `tramp-default-method` will also tell `ansi-term` mode the correct way to access the remote when directory tracking.
 
 ## Directory Tracking
 ### `ansi-term`
@@ -72,3 +72,34 @@ To fix this:
 
 ### `eshell`
 The `eshell` mode will perform directory tracking by default, no additional configuration is needed.
+
+## Language Servers (Code Completion)
+If you use [`lsp-mode`](https://emacs-lsp.github.io/lsp-mode) for code intelligence and completion some additional configuration is required.
+
+In your Emacs `init.el` file you must register a LSP client and tell `lsp-mode` how to find it on the remote machine using the `lsp-register-client` function. For each LSP server you want to use in your workspace add the following:
+
+```lisp
+(lsp-register-client (make-lsp-client :new-connection (lsp-tramp-connection "<LSP SERVER BINARY>")
+              :major-modes '(<LANGUAGE MODE>)
+              :remote? t
+              :server-id 'coder.<WORKSPACE NAME>))
+```
+
+This tells `lsp-mode` to look for a language server binary named `<LSP SERVER BINARY>` for use in `<LANGUAGE MODE>` on a machine named `coder.<WORKSPACE NAME>`. Be sure to replace the values between angle brackets:
+
+- `<LSP SERVER BINARY>` : The name of the language server binary, without any path components. For example to use the Deno Javascript language server use the value `deno`.
+- `<LANGUAGE MODE>`: The name of the Emacs major mode for which the language server should be used. For example to enable the language server for Javascript development use the value `web-mode`.
+- `<WORKSPACE NAME>`: The name of your coder workspace.
+
+Calling the `lsp-register-client` function will tell `lsp-mode` the name of the LSP server binary. However this binary must be accessible via the path. If the language server binary is not in the path you must modify `tramp-remote-path` so that `lsp-mode` knows in what directories to look for the LSP server. To do this use TRAMP's connection profiles functionality. These connection profiles let you customize variables depending on what machine you are connected to. Add the following to your `init.el`:
+
+```lisp
+(connection-local-set-profile-variables 'remote-path-lsp-servers
+								 '((tramp-remote-path . ("<PATH TO ADD>" tramp-default-remote-path))))
+(connection-local-set-profiles '(:machine "coder.<WORKSPACE NAME>") 'remote-path-lsp-servers)
+```
+
+The `connection-local-set-profile-variables` function creates a new connection profile by the name `remote-path-lsp-servers`. The `connection-local-set-profiles` then indicates this `remote-path-lsp-servers` connection profile should be used when connecting to a server named `coder.<WORKSPACE NAME>`. Be sure to replace `<PATH TO ADD>` with the directory in which a LSP server is present.
+
+More details on configuring `lsp-mode` for TRAMP can be found [on the `lsp-mode` documentation](https://emacs-lsp.github.io/lsp-mode/page/remote/).
+The [TRAMP `tramp-remote-path` documentation](https://www.gnu.org/software/emacs/manual/html_node/tramp/Remote-programs.html#Remote-programs) contains more examples and details of connection profiles).
