gopls/doc: Update Sublime Text documentation to LSP-gopls

gopls/doc/subl.md

@@ -1,81 +1,90 @@
 # Sublime Text
 
-Use the [LSP] package. After installing it using Package Control, do the following:
+Setting up Sublime Text for Golang development.
 
-* Open the **Command Palette**
-* Find and run the command **LSP: Enable Language Server Globally**
-* Select the **gopls** item. Be careful not to select the similarly named *golsp* by mistake.
+## Installation
 
-Finally, you should familiarise yourself with the LSP package's *Settings* and *Key Bindings*. Find them under the menu item **Preferences > Package Settings > LSP**.
+Make sure Go is installed and available in your `PATH`. Follow the [Go documentation][golang-installation] to get Go up and running quickly.
+You can verify that Go is properly installed and available by typing `go help` in a terminal. The command should print a help text instead of an error message.
 
-## Examples
-Minimal global LSP settings, that assume **gopls** and **go** appear on the PATH seen by Sublime Text:<br>
-```
+Use [Package Control] to install the following packages:
+
+- [LSP] provides language server support in Sublime Text
+- [LSP-gopls] the helper package for gopls
+- (optionally) [Gomod] and [Golang Build] for `go.mod` file syntax highlighting and a Go build system
+
+gopls is automatically installed and activated when a `.go` file is opened.
+
+## Configuration
+
+Here are some ways to configure the package and the language server. See [the documentation][gopls-settings] for all available settings.
+
+### Global configuration
+- Configure the LSP package by navigating to `Preferences > Package Settings > LSP > Settings` or by executing the `Preferences: LSP Settings` command in the command palette.
+- Configure gopls by navigating to `Preferences > Package Settings > LSP > Servers > LSP-gopls` or by executing the `Preferences: LSP-gopls Settings` command in the command palette.
+
+### Project-specific configuration
+From the command palette run `Project: Edit Project` and add your settings in:
+
+```js
 {
-    "clients": {
-        "gopls": {
-             "enabled": true,
-         }
+  "settings": {
+    "LSP": {
+      "gopls": {
+        "settings": {
+          // Put your settings here
+        }
+      }
     }
+  }
 }
 ```
 
-Global LSP settings that supply a specific PATH for finding **gopls** and **go**, as well as some settings for Sublime LSP itself:
+### Formatting
+
+It is recommended to auto-format Go files using the language server when saving.
+This can be enabled either globally in the LSP settings (see above) or for the Go syntax only.
+
+To enable formatting for the Go syntax only, open a Go file and open the syntax-specific settings by navigating to `Preferences > Settings - Syntax Specific`.
+
+Add `"lsp_format_on_save": true` to the outermost curly braces:
+
+```js
+// These settings override both User and Default settings for the Go syntax
+{
+  "lsp_format_on_save": true,
+}
 ```
+
+### Custom gopls executable
+
+You can use a custom gopls executable by setting the path in the LSP-gopls settings (see above).
+```js
 {
-    "clients": {
-        "gopls": {
-            "enabled": true,
-            "env": {
-                "PATH": "/path/to/your/go/bin",
-            }
-        }
-    },
-    // Recommended by https://agniva.me/gopls/2021/01/02/setting-up-gopls-sublime.html
-    // except log_stderr mentioned there is no longer recognized.
-    "show_references_in_quick_panel": true,
-    "log_debug": true,
-    // These two are recommended by LSP-json as replacement for deprecated only_show_lsp_completions
-    "inhibit_snippet_completions": true,
-    "inhibit_word_completions": true,
- }
- ```
-
-LSP and gopls settings can also be adjusted on a per-project basis to override global settings.
+  "command": [
+    "path/to/custom/gopls"
+  ],
+}
 ```
+
+### Custom environment
+
+You can modify the environment variables that are presented to gopls by modifying the `env` setting in the LSP-gopls settings (see above).
+```js
 {
-    "folders": [
-        {
-            "path": "/path/to/a/folder/one"
-        },
-        {
-            // If you happen to be working on Go itself, this can be helpful; go-dev/bin should be on PATH.
-            "path": "/path/to/your/go-dev/src/cmd"
-        }
-     ],
-    "settings": {
-        "LSP": {
-            "gopls": {
-                // To use a specific version of gopls with Sublime Text LSP (e.g., to try new features in development)
-                "command": [
-                    "/path/to/your/go/bin/gopls"
-                ],
-                "env": {
-                    "PATH": "/path/to/your/go-dev/bin:/path/to/your/go/bin",
-                    "GOPATH": "",
-                },
-                "settings": {
-                    "experimentalWorkspaceModule": true
-                }
-            }
-        },
-        // This will apply for all languages in this project that have
-        // LSP servers, not just Go, however cannot enable just for Go.
-        "lsp_format_on_save": true,
-    }
+  "env": {
+    "PATH": "/path/to/your/go-dev/bin:/path/to/your/go/bin",
+    "GOPATH": "/path/to/your/gopath",
+    // add more environment variables here 
+  },
 }
 ```
 
-Usually changes to these settings are recognized after saving the project file, but it may sometimes be necessary to either restart the server(s) (**Tools > LSP > Restart Servers**) or quit and restart Sublime Text itself.
 
+[Package Control]: https://packagecontrol.io/installation
 [LSP]: https://packagecontrol.io/packages/LSP
+[LSP-gopls]: https://packagecontrol.io/packages/LSP-gopls
+[Gomod]: https://packagecontrol.io/packages/Gomod
+[Golang Build]: https://packagecontrol.io/packages/Golang%20Build 
+[golang-installation]: https://golang.org/doc/install
+[gopls-settings]: https://github.com/golang/tools/blob/master/gopls/doc/settings.md