Editor Configuration Documentation improvement

[nlander]

@hasufell @wz1000 As a follow up to discussion on the monthly hls contributers meeting today, I am attempting to lay out some of the issues I have had setting up hls for neovim and some thoughts I have on how the docs could be improved. Appologies if this is a bit longwinded; I am trying to be thorough in documenting my experience.

One idea that stands out to me is that the docs seem to assume that users know how to configure their editor of choice, which I don't think is always a reasonable assumption. In my case, I have previously only used neovim with an extremely minimal configuration and no plugins. I know nothing about lua and how to use it to configure neovim for more complex plugin configuration. As vim/neovim is an editor that can be associated with minimalism, I could imagine that I am not the only person who could find themselves wanting to use hls with neovim and not knowing how to use lua. I could also imagine someone new to haskell trying out more than one new thing at once, and not knowing anything about their editor of choice for the moment. In general I think it would be nice if for as many editors as possible we can include a minimal viable complete configuration for the editor, assuming that the user is coming in with no previous configuration. This should include anything that needs to be installed for the configuration to work (like lua, luarocks, dependency plugins, etc.).

For me specifically, here are the pain points I encountered while getting neovim set up, and the questions I still have. I chose to try haskell-tools.nvim first.

• I needed to upgrade my version of neovim, as the apt package is pretty far out of date. I ended up using the neovim plugin for asdf for this, which worked fine, except that for some reason ~/.asdf/shims didn't get added to my path when I installed asdf (this likely is related to the fact that I use fish shell).
• I determined that the dependency plugins, both optional and required, were best installed using luarocks, even though none of the READMEs for those plugins suggested luarocks as an install option. In the process of installing these plugins, I ended up installing lua a total of 3 times, also using asdf. This is because the different plugins support different versions of lua. I first installed the latest version, thinking that would be fine. I was pleased that installing lua with asdf also installed luarocks. Then I tried to install plenary.nvim and was told by luarocks that it only supports lua 5.1 through 5.3, but not 5.4. I then installed lua 5.3, reinstalled plenary.nvim, and attempted to install telescope.nvim. This time, luarocks informed me that telescope.nvim only supports lua 5.1. Finally, I installed lua 5.1.5, reinstalled plenary.nvim, reinstalled telescope.nvim, and installed nvim-dap.
• I had no trouble using cabal and stack to install the haskell executable dependencies for haskell-tools.nvim, hoogle, fast-tags, and haskell-debug-adapter. However, I do think that the neovim startup instructions should include the commands to clone these repos and install them using cabal and stack, because I think hls should be accessible to haskell newbies.
• Next I created the file ~/.config/nvim/ftplugin/haskell.lua and put the recommended quickstart configuration in. Then I attempted to open a haskell file in neovim and encountered a lua error. After a bit of digging I figured out that I needed to set the LUA_PATH environment variable with the location of plugin installations. Those proper installations are part of the output of the luarocks path command. Once I set that environment variable I was able to open neovim without encountering lua errors.
• Next I was faced with a cabal error preventing hls from starting. This turned out to be a bug in the latest version of cabal. I don't anticipate most users will encounter this sort of problem if they stick to the ghcup recommended version of cabal-install, which I was not.

• Now I was finally at the point where I could attempt to use some of the functionality of hls in neovim. So far I have successfully used gotoDefinition and not much else. I am not entirely clear on what all I did to get this working. I still have some questions about the configuration. First, from this line in the haskell-tools.nvim quickstart:

  For more LSP related keymaps, [see the nvim-lspconfig suggestions](https://github.com/neovim/nvim-lspconfig#suggested-configuration).

  it's not clear to me if haskell-tools.nvim reimplements those keymaps by default and the link is simply for reference, or if the user needs to add those keymaps to their config in addition to the haskell-tools.nvim quickstart. I currently have the second option in my config, so I installed nvim-lspconfig (again, not sure if this is redundant with haskell-tools.nvim) and the following is the contents of my ~/.config/nvim/ftplugin/haskell.lua:

  
  local ht = require('haskell-tools')
  local def_opts = { noremap = true, silent = true, }
  ht.start_or_attach {
  hls = {
  on_attach = function(client, bufnr)
    local opts = vim.tbl_extend('keep', def_opts, { buffer = bufnr, })
    -- haskell-language-server relies heavily on codeLenses,
    -- so auto-refresh (see advanced configuration) is enabled by default
    vim.keymap.set('n', '<space>ca', vim.lsp.codelens.run, opts)
    vim.keymap.set('n', '<space>hs', ht.hoogle.hoogle_signature, opts)
    vim.keymap.set('n', '<space>ea', ht.lsp.buf_eval_all, opts)
  
    --copied from https://github.com/neovim/nvim-lspconfig#suggested-configuration
    vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, opts)
    vim.keymap.set('n', 'gd', vim.lsp.buf.definition, opts)
    vim.keymap.set('n', 'K', vim.lsp.buf.hover, opts)
    vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, opts)
    vim.keymap.set('n', '<C-k>', vim.lsp.buf.signature_help, opts)
    vim.keymap.set('n', '<space>wa', vim.lsp.buf.add_workspace_folder, opts)
    vim.keymap.set('n', '<space>wr', vim.lsp.buf.remove_workspace_folder, opts)
    vim.keymap.set('n', '<space>wl', function()
      print(vim.inspect(vim.lsp.buf.list_workspace_folders()))
    end, opts)
    vim.keymap.set('n', '<space>D', vim.lsp.buf.type_definition, opts)
    vim.keymap.set('n', '<space>rn', vim.lsp.buf.rename, opts)
    vim.keymap.set({ 'n', 'v' }, '<space>ca', vim.lsp.buf.code_action, opts)
    vim.keymap.set('n', 'gr', vim.lsp.buf.references, opts)
    vim.keymap.set('n', '<space>f', function()
      vim.lsp.buf.format { async = true }
    end, opts)
  end,
  },
  }

-- Suggested keymaps that do not depend on haskell-language-server: local bufnr = vim.api.nvim_get_current_buf() -- set buffer = bufnr in ftplugin/haskell.lua local opts = { noremap = true, silent = true, buffer = bufnr }

-- Toggle a GHCi repl for the current package vim.keymap.set('n', 'rr', ht.repl.toggle, opts) -- Toggle a GHCi repl for the current buffer vim.keymap.set('n', 'rf', function() ht.repl.toggle(vim.api.nvim_buf_get_name(0)) end, def_opts) vim.keymap.set('n', 'rq', ht.repl.quit, opts)

-- Detect nvim-dap launch configurations -- (requires nvim-dap and haskell-debug-adapter) ht.dap.discover_configurations(bufnr)

- My current problem is that I really have no idea how to modify my config or see what my config is dynamically. Looking into lua a bit it seems that there isn't a nice general way to print a lua table, which seems to be the data structure of the configuration. Most relevant for the work I will be doing on goto definition, I would like to change what the default hls command so that I can use a custom script (@wz1000 helped me set up a custom script yesterday and I got it working for vscode but not neovim).

I think the current docs are likely fine for people who already use lua for configuration, so the upgrade to the docs I would suggest is having two sections under neovim. One would be basically what we have now, for people who already use a complex neovim configuration, and under it the more detailed instructions. Next I plan to make a pull request adding those more detailed instructions based on my experiences as documented above.

It would be great if every editor could have both of these options, but I don't know if I am prepared to flesh all of them out at this time. I understand if some people think this might be outside of the scope of what hls docs should provide, but I personally think that one of the main goals of an ide should be beginner friendliness. Towards this end I think excruciatingly detailed docs are a good idea.

[nlander]

I'm going to add more of my experiences trying out some hls features in neovim here. I'm hoping to learn enough about the correct way to use these features that I can add some documentation about them to #3620.

[nlander]

Neovim seems to be adding explicit versions of the non-explicit imports, but they are truncated and I don't seem to be able to move my cursor into them or scroll to the right to see the rest of the explicit imports.

[nlander]

Some things I'm noticing playing around with K for hover actions: It's working fine most places except I am getting a lua error when I press K on the closing parenthesis of the functions imported in an import statement. This is the error:

Error executing vim.schedule lua callback: .../lua/5.1.5/luarocks/share/lua/5.1/haskell-tools/util.lua:68: inva
lid pattern capture
stack traceback:
        [C]: in function 'match'
        .../lua/5.1.5/luarocks/share/lua/5.1/haskell-tools/util.lua:68: in function 'try_get_signature_from_mar
kdown'
        ...5.1.5/luarocks/share/lua/5.1/haskell-tools/lsp/hover.lua:119: in function 'handler'
        ...installs/neovim/0.9.0/share/nvim/runtime/lua/vim/lsp.lua:1394: in function ''
        vim/_editor.lua: in function <vim/_editor.lua:0>

I wonder if this is a bug I should report in the haskell-tools.nvim repo, or if it is something that can be fixed in my config.

The other thing I'm wondering is how to enter the hover actions without using the mouse. If I click into the box that comes up with my mouse, then I am able to navigate it as usual with jkhl, and pressing on one of the numbered options takes that action. Is there any way I can enter and exit the hover box without using the mouse? Not needing to use the mouse is a big part of why I like to use neovim, and it seems like the whole point of having the hover action bound to a key is also to avoid using the mouse.

[nlander]

I'm trying out gotoDefinition and gotoTypeDefinition. gotoDefinition seems to be working with the keybinding gd, but gotoTypeDefinition is not working with the keybinding <space>D. gotoTypeDefintion is working from the hover menu, however.

[nlander]

I closed the PR because after discussing with @wz1000 it seems that beginner-friendly setup instructions shouldn't use haskell-tools.nvim.

[michaelpj]

I could also imagine someone new to haskell trying out more than one new thing at once, and not knowing anything about their editor of choice for the moment.

I personally think that one of the main goals of an ide should be beginner friendliness. Towards this end I think excruciatingly detailed docs are a good idea.

Personally, I think our answer to that should be "use VSCode". It has the most plug-and-play setup, and I'm not sure we can realistically support detailed configuration for every editor and we have to rely on some user knowledge. Especially since Emacs and vim are configured in fully fledged programming languages, and have varied and frequently-changing configuration management systems...

For me specifically, here are the pain points I encountered while getting neovim set up

This is exactly why I don't think we can really support this. This is a big list of editor specific stuff which we are unlikely to be able to keep current or even verify. It probably varies by OS also!

[michaelpj]

We discussed this a bit in our meeting. HLS is a first port of call for many people getting started, so it would be nice to provide something for such people. If VSCode is the smoothest path, then we should have a prominent "Getting started" page that says something like "For a smooth setup, use GHCup and VSCode".

Maybe we can also provide these detailed instructions on a best-effort basis, but we should clearly mark them as such and warn that they may not work/be out of date.