Add docs on how to choose a formatter #432

googleson78 · 2020-09-25T21:27:56Z

No description provided.

fendor

Hi!
I have a few questions, I would not know how this documentation is helpful, or how I would actually write it, could you clarify a bit?

fendor · 2020-09-25T21:39:19Z

README.md

+{
+  ...
+  "haskell": {
+    ...
+    "formattingProvider": "fourmolu"
+    ...
+  }
+  ...
+}


What is this lsp configuration? I have never seen that one. What should be the name of this file?

I'm assuming it is a .json file that you point your lsp client to (e.g. in LanguageClient-neovim that seems to be g:LanguageClient_settingsPath)

Not sure if this is specific to LanguageClient-neovim? At least I have never seen such a configuration file for HLS itself. Others will have to clarify.

I assumed it is generic, because I couldn't find another way of choosing a formatter. How do you do so in your editor+client?

VSCode / VSCodium has a settings Tab where you can choose the formatter out of a dropbox menu

Ok makes sense, so this configuration's location is still editor dependent. We should make this clear and maybe refer to the documentation of the respective lsp-client.

I pushed some "clarification", is it ok?

I'm also not sure how good an idea being this specific as I was is, because while it's helpful for someone who has never used their respective LSP client before, it might get outdated and is in a way "redundant" information.

This is quite client-specific. For example, in lsp-haskell (the emacs mode), you configure these things with emacs defcustom variables. I think it's reasonable for the client to explain how configuration is done, since we can't specify it in a general way on the server side.

But there should still be some mention that you can put such a field into your client's configuration, whatever that may be. If it didn't exist in the changelog you would have to read through source code to learn about this.

Besides, there is already precedent for descriptions on how to configure different clients for use with HLS.

I don't think I'm the only one who found it took effort to find this out either:
https://twitter.com/seagreen__/status/1309967145221214209?s=20

fendor · 2020-09-25T21:39:21Z

README.md

@@ -253,6 +254,34 @@ If your desired ghc has been found, you use it to install haskell-language-serve
 ./cabal-hls-install data
 ```

+## HLS LSP Configuration
+
+haskell-language-server supports some forms of configuration.


For what editor? For all? Is that a HLS configuration I was not aware of?

Apparently so, I took this information from the changelog

jneira · 2020-09-26T22:13:39Z

@googleson78 i knew we had something related with the configuration in the repo but i did not remember it was a pr so i opened a issue that will be closed by this.
Thanks for improve the docs: i agree that is needed to have here a section about in the server itself, indepedently of docs in each editor/lsp client. As reference for all of them and to make clear how an user can change the behaviour of the server.

jneira · 2020-09-29T12:08:34Z

@fendor @michaelpj dont want to bother but do you think there are still some concrete change to do? maybe something like "the way to update the config varies per editor but... for example in vscode is done this way ..."?

michaelpj · 2020-09-29T13:28:22Z

I guess what I worry about is: say I change the name of a variable in lsp-haskell. Very good, I update the documentation there, but I forget that I also have to go and modify the haskell-language-server documentation. Let's not even think about the fact that people might be using different versions of lsp-haskell, so we can't give universally applicable configuration information.

So it seems fragile to me to give specific information about other projects when we have no guarantee about what version of those projects users will be using.

googleson78 · 2020-09-29T13:40:17Z

@michaelpj
In general I agree with you - this is why I originally wanted to only mention "this is what your final json lsp config should contain", because as far as I understand the name [haskell.]formattingProvider is determined by hls, so it shouldn't be an issue. (and because the "final json config" seems to be a universal thing among LSP clients)

I only added the more "detailed" descriptions because my original one seemed to cause confusion, even among experienced hls users.

They're also in the spirit of the editor setup examples that are present in the current README (they also have the same issues you described - upstream could change etcetc) of leaning towards user-friendliness at the cost of maintenance effort.

michaelpj · 2020-09-29T14:04:37Z

and because the "final json config" seems to be a universal thing among LSP clients

It's not, though. Certainly not for emacs clients. Selfishly, I expect this would lead to people opening lsp-haskell issues saying "where do I put the JSON config?".

I don't know. Maybe I'm just generalizing from myself too much, but I'd much rather see "For editor X, use Y, and see Y's documentation for setting it up (LINK)". I can click on links!

googleson78 · 2020-09-29T14:16:33Z

By "final", I mean that "in the end" (at the lowest level) in communication with the LSP server there is some json (if it's actually json??) value being sent, regardless of the surface format presented by the editor/lsp client.

I'm open to other suggestions to describe this in a client agnostic way ("you need to make your client send the haskell.formattingProvider value"), after which we can remove the client-specific descriptions and leave only links to their specific ways for configuration

michaelpj · 2020-09-29T14:31:00Z

By "final", I mean that "in the end" (at the lowest level) in communication with the LSP server there is some json (if it's actually json??) value being sent, regardless of the surface format presented by the editor/lsp client.

Yeah, but it's not the JSON that you see in your VSCode settings.

I'm open to other suggestions to describe this in a client agnostic way ("you need to make your client send the haskell.formattingProvider value")

The client-agnostic way is to describe the LSP protocol messages the client needs to send, which is not what the user wants to see ;)

googleson78 · 2020-09-29T14:51:36Z

Well.. it's exactly what I wanted to see, so I had some clue what I needed to look for in my LSP client (e.g. if it's not documented/present I can open an issue and ask how to do that there).

In any case, it seems that there needs to be some choice made wrt user friendliness vs maintenance burden here, and I'm not the one to make that choice.

jneira · 2020-09-29T20:53:28Z

Well, i think we agree in is good to include:

the server can be configured in the client in some way
one of the configuration settings is the formatter provider, and the actual list of possible values

So removing the reference to the concrete json would make it client agnostic enough?

googleson78 · 2020-10-02T07:02:18Z

I removed the json, but still retained a mention of what the key name is in raw json. If I were to remove that also and delete my knowledge of how to set it, I would still have no idea how to choose a formatting provider by looking at the README

jneira

LGTM in its actual phrasing.
//cc @fendor

jneira · 2020-10-02T07:25:13Z

@michaelpj maybe we could add a reference to the emacs way to change settings in a followup, if you think it would be helpful for emacs users

fendor

LGTM, thanks!

googleson78 added 2 commits September 26, 2020 00:26

Add documentation on choosing a formatter

3bed408

Cleanup trailing whitespace

d8f0d36

fendor requested changes Sep 25, 2020

View reviewed changes

Clarify where lsp settings are located

1b08736

googleson78 force-pushed the docs-formatters branch from 8fd856c to 1b08736 Compare September 26, 2020 10:35

googleson78 mentioned this pull request Sep 26, 2020

Document how hls can be configured #437

Closed

jneira linked an issue Sep 26, 2020 that may be closed by this pull request

Document how hls can be configured #437

Closed

Replace direct json with just a key name mention

d65e7d4

jneira approved these changes Oct 2, 2020

View reviewed changes

fendor approved these changes Oct 2, 2020

View reviewed changes

jneira merged commit d4d50a6 into haskell:master Oct 2, 2020

jneira mentioned this pull request Mar 30, 2021

QQ core dump #1639

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs on how to choose a formatter #432

Add docs on how to choose a formatter #432

googleson78 commented Sep 25, 2020

fendor left a comment •

edited

fendor Sep 25, 2020 •

edited

googleson78 Sep 25, 2020

fendor Sep 25, 2020

googleson78 Sep 26, 2020 •

edited

fendor Sep 26, 2020

fendor Sep 26, 2020

googleson78 Sep 26, 2020

michaelpj Sep 26, 2020

googleson78 Sep 26, 2020

googleson78 Sep 26, 2020

fendor Sep 25, 2020 •

edited

googleson78 Sep 25, 2020

jneira commented Sep 26, 2020

jneira commented Sep 29, 2020

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020 •

edited

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020 •

edited

jneira commented Sep 29, 2020

googleson78 commented Oct 2, 2020

jneira left a comment

jneira commented Oct 2, 2020

fendor left a comment

Add docs on how to choose a formatter #432

Add docs on how to choose a formatter #432

Conversation

googleson78 commented Sep 25, 2020

fendor left a comment • edited

Choose a reason for hiding this comment

fendor Sep 25, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

googleson78 Sep 26, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fendor Sep 25, 2020 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jneira commented Sep 26, 2020

jneira commented Sep 29, 2020

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020 • edited

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020

michaelpj commented Sep 29, 2020

googleson78 commented Sep 29, 2020 • edited

jneira commented Sep 29, 2020

googleson78 commented Oct 2, 2020

jneira left a comment

Choose a reason for hiding this comment

jneira commented Oct 2, 2020

fendor left a comment

Choose a reason for hiding this comment

fendor left a comment •

edited

fendor Sep 25, 2020 •

edited

googleson78 Sep 26, 2020 •

edited

fendor Sep 25, 2020 •

edited

googleson78 commented Sep 29, 2020 •

edited

googleson78 commented Sep 29, 2020 •

edited