doc: slight improvements

1 files changed, 53 insertions, 48 deletions

diff --git a/doc/nvim-lsp-installer.txt b/doc/nvim-lsp-installer.txt
index fcb00c3d..358b8ba2 100644
--- a/doc/nvim-lsp-installer.txt
+++ b/doc/nvim-lsp-installer.txt
@@ -8,33 +8,41 @@ Author: William Boman
 INTRODUCTION                                *nvim-lsp-installer-introduction*
 
 Companion plugin for nvim-lspconfig (https://github.com/neovim/nvim-lspconfig)
-that allows you to seamlessly install LSP servers locally (inside `:echo stdpath("data")`).
+that allows you to seamlessly install LSP servers locally (inside `:echo
+stdpath("data")`).
 
-On top of just providing commands for installing & uninstalling LSP servers, it:
+On top of just providing commands for installing & uninstalling LSP servers,
+it:
 
 -   provides a graphical UI
--   optimized for blazing fast startup times
+-   is optimized for blazing fast startup times
+-   provides the ability to check for new server versions
 -   supports installing custom versions of LSP servers (for example
     `:LspInstall rust_analyzer@nightly`)
--   common install tasks are abstracted behind composable Lua APIs (has direct
-    integration with libuv via vim.loop)
--   minimum requirements are relaxed by attempting multiple different
+-   relaxes the minimum requirements by attempting multiple different
     utilities (for example, only one of `wget`, `curl`, or `Invoke-WebRequest`
     is required for HTTP requests)
--   full support for Windows
+-   allows you to install and setup servers without having to restart neovim
+-   hosts a suite of system tests for all supported servers
+-   has full support for Windows
 
-Requires neovim `>= 0.6.0` and nvim-lspconfig. The full requirements to
-install all servers are:
+Requires neovim `>= 0.6.0` and nvim-lspconfig. The _full requirements_ to
+install _all_ servers are:
 
--   For Unix systems: bash(1), git(1), curl(1) or wget(1), unzip(1), tar(1),
-    gzip(1)
--   For Windows systems: powershell, git, gzip, tar, and 7zip or peazip or
-    archiver or winzip
+-   For Unix systems: git(1), curl(1) or wget(1), unzip(1), tar(1), gzip(1)
+-   For Windows systems: powershell, git, tar, and 7zip or peazip or archiver
+    or winzip or WinRAR
 -   Node.js (LTS) & npm
 -   Python3 & pip3
--   go
--   javac
+-   go >= 1.17
+-   JDK
 -   Ruby & gem
+-   PHP & Composer
+-   dotnet
+-   pwsh
+-   Julia
+-   valac (and meson & ninja)
+-   rebar3
 
 To write a custom server installer, please refer to the docs at
 https://github.com/williamboman/nvim-lsp-installer/blob/main/CUSTOM_SERVERS.md.
@@ -42,22 +50,6 @@ https://github.com/williamboman/nvim-lsp-installer/blob/main/CUSTOM_SERVERS.md.
 ==============================================================================
 QUICK START                                   *nvim-lsp-installer-quickstart*
 
-nvim-lsp-installer installs server executables in a local directory that
-doesn't exist on PATH. In order for the neovim LSP client to be able to locate
-these executables, the full path to the executable needs to be provided when
-setting up a server. In lspconfig, this is provided via the `cmd` property in
-the table provided to the `.setup()` function, for example: >
-
-    lspconfig.sumneko_lua.setup { cmd = { "/path/to/lua-server" } }
-<
-
-The recommended way of setting up your installed servers is to do it directly
-through nvim-lsp-installer. By doing so, nvim-lsp-installer will make sure to
-inject any necessary properties before calling lspconfig's setup function for
-you. You may find a minimal example below. To see how you can override the
-default settings for a server, refer to the Wiki:
-https://github.com/williamboman/nvim-lsp-installer/wiki/Advanced-Configuration#overriding-the-default-lsp-server-options.
-
 To view the UI for nvim-lsp-installer, run: >
 
     :LspInstallInfo
@@ -90,10 +82,8 @@ available.
 
 Then, somewhere in your initialization script (see `:h init.lua`): >
 
-    local lsp_installer = require("nvim-lsp-installer")
-
-    -- Register a handler that will be called for all installed servers.
-    -- Alternatively, you may also register handlers on specific server instances instead (see example below).
+    -- Register a handler that will be called for each installed server when it's ready (i.e. when installation is finished
+    -- or if the server is already installed).
     lsp_installer.on_server_ready(function(server)
         local opts = {}
 
@@ -102,27 +92,42 @@ Then, somewhere in your initialization script (see `:h init.lua`): >
         --     opts.root_dir = function() ... end
         -- end
 
-        -- This setup() function is exactly the same as lspconfig's setup function.
+        -- This setup() function will take the provided server configuration and decorate it with the necessary properties
+        -- before passing it onwards to lspconfig.
         -- Refer to https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md
         server:setup(opts)
     end)
 <
 
+Make sure you don't also set up your servers via lspconfig (e.g. `require("lspconfig").clangd.setup {}`)!
+
 For more advanced use cases you may also interact with more APIs
-nvim-lsp-installer has to offer, for example the following (refer
-to `:help nvim-lsp-installer` for more docs): >
+nvim-lsp-installer has to offer, for example the following: >
 
-    local lsp_installer_servers = require'nvim-lsp-installer.servers'
+    local lsp_installer_servers = require('nvim-lsp-installer.servers')
 
-    local server_available, requested_server = lsp_installer_servers.get_server("rust_analyzer")
-    if server_available then
-        requested_server:on_ready(function ()
-            local opts = {}
-            requested_server:setup(opts)
-        end)
-        if not requested_server:is_installed() then
-             -- Queue the server to be installed
-            requested_server:install()
+    local servers = {
+        "rust_analyzer",
+        "clangd",
+        "pyright",
+    }
+
+    -- Loop through the servers listed above and set them up. If a server is
+    -- not already installed, install it.
+    for _, server_name in pairs(servers) do
+        local server_available, server = lsp_installer_servers.get_server(server_name)
+        if server_available then
+            server:on_ready(function ()
+                -- When this particular server is ready (i.e. when installation is finished or the server is already installed),
+                -- this function will be invoked. Make sure not to also use the "catch-all" lsp_installer.on_server_ready()
+                -- function to set up your servers, because by doing so you'd be setting up the same server twice.
+                local opts = {}
+                server:setup(opts)
+            end)
+            if not server:is_installed() then
+                -- Queue the server to be installed.
+                server:install()
+            end
         end
     end
 <