Explain a bit more on how to configure language server in Eglot's manual

[Yuan Fu <casouri@gmail.com>]

Recently I was trying to use eglot with rust-analyzer and configure rust-analyzer. It turns out more confusing than it should be, and I think we can add a paragraph to eglot’s manual to help others like me.

LSP servers generally allow configuration through either LSP’s workspaceConfiguration protocol or their custom configuration file. For those who use workspaceConfiguration, it is common for the documentation to say something like this:

    This is the list of config options rust-analyzer supports:

    rust-analyzer.assist.emitMustUse (default: false) blah blah blah
    …

To pass this configuration to rust-analyzer through eglot, you need to set eglot-workspace-configuration to 

'(:rust-analyzer (:assist (:emitMustUse t)))

However, it is not obviously clear how to interpret “rust-analyzer.assist.emitMustUse”, not for someone inexperience with LSP, at least. (OTOH, the manual explains very clearly how to translate a JSON config to a plist, great job!)

I suggest we add a sentence or a paragraph to the eglot manual explaining that rust-analyzer.assist.emitMustUse translates to the JSON configuration

{
  "rust-analyzer": {
    "assist": {
      "emitMustUse": true
    }
  }
}

And the user should translate that to the plist format for eglot-workspace-configuration.

This is not something only rust-analyzer does. I surveyed a bunch of language servers, all the servers that support LSP’s workspaceConfiguration (typescript, rust, python, OCaml, Haskell, perl, Java) describe their configuration in the xxx.xx.xxx format. Because this is the format one can copy and paste into VSCode’s setting file.

We should probably also mention that the “root key” (the "rust-analyzer” part) isn’t always the name of the language server. Some server expects the language name rather than the server’s name, ie, haskell rather than haskell-language-server. Typescript expects “typescript” or “javascript”, perl, ocaml, java expects language names, python expects “pyls”, the name of the server.

Yuan