add emacs configuration example

[freckletonj]

I love HLS, I love wingman, and struggled to figure out how to configure it. Here's an example that I think will help emacsers along their way.

[jneira]

thanks for improving docs, I asked a revision from @michaelpj and @Ailrun, maintainers and Emacs users iirc

[Ailrun]

Thanks for the update! Here's my two cents.

[Anton-Latukha]

Ok, 2 Emacs-related maintainers made reviews, all get addressed.

I'm as an Emacs poweruser satisfied with the result. Merging...

[michaelpj]

This is in conflict with the previous clause, which says that lsp-haskell provides customization options... and then you give an example of how to bypass them! I still really think this should be in the lsp-haskell readme if anywhere. Better to keep the Emacs docs with the Emacs package.

[Ailrun]

FYI, Michael means this repository: https://github.com/emacs-lsp/lsp-haskell/

[freckletonj]

@michaelpj I see what you're saying and personally agree that it should be in lsp-haskell (though, in addition to being in HLS's docs). If there's a way to configure lsp-haskell better than lsp--set-configuration, I think that would be relevant to have in HLS's docs instead of (or in addition to) what I suggested.

I haven't had time to dig through lsp-haskell's source, but, that's kind of my point that, if configuration requires 1+ hours of finding which library to configure, and then read the source to determine what needs to be configured, and how, well, imho that makes it good fodder for an example, and lsp--set-configuration was the best I could personally come up with.

Could you suggest a better alternative (IE the proper way to configure lsp-haskell), or point me to documentation? I see now that lsp-haskell does mention (customize-group 'lsp-haskell), but that doesn't have the tactics config in it. I'm happy to submit a new PR here. Or would you prefer to not even document this in HLS at all?

[michaelpj]

I see now that lsp-haskell does mention (customize-group 'lsp-haskell), but that doesn't have the tactics config in it

Alright, there we go. That's a bug. Which I have been procrastinating on fixing for a while, but you pushed me over the edge ;) emacs-lsp/lsp-haskell#144 .

Could you suggest a better alternative (IE the proper way to configure lsp-haskell), or point me to documentation?

Could you rather help me figure out what route you took in looking for information so we can make the right route clearer? Evidently you didn't find the bit in the lsp-haskell readme that you needed and I'd like to understand why!

The route I was hoping people would take is:

• HLS configuration doc
• lsp-haskell readme (since the configuration doc tells you to go there)
• "Emacs configuration" section of lsp-haskell readme, which talks about the customization options

I think that would be relevant to have in HLS's docs instead of (or in addition to) what I suggested.

Perhaps I'm being overly dogmatic, but I would really prefer to keep the Emacs documentation next to the Emacs package, we're much more likely to keep it up-to-date that way!

---

Also, I would definitely appreciate a PR to the lsp-haskell readme with your workaround for configuring settings that aren't exposed. That's a very useful trick for when we haven't got an option for something yet!

[freckletonj]

understood, I'll close this PR then, and offer this one in its place: emacs-lsp/lsp-haskell#146

what route you took in looking for information

My expectations were to find these answers first in HLS's readme or some adjacent markdown file, second in HLS's docs, third in... probably lsp-mode was third, fourth was lsp-haskell, I missed the customize-group comment in lsp-haskell's readme (it was in the configuration heading, but a lot of that heading was just installation pointers so I just missed it toward the end, and it wouldn't have helped since it had fallen out of parity with HLS (thanks for your new pr btw!). I was looking for a table of configuration options and explanations to catch my eye, which I guess I'm used to seeing), so, I probably poked at lsp-ui next, then I hunted through github issues of various projects via search engine until I stumbled across someone configuring a python project using the same technique I show here, and extrapolated that the proper configuration key paths would align with those in the docs, which, still took some fiddling to get right.

I'm super grateful for all you guys have done though, so, massive thanks and sorry I submitted this PR in the wrong place. And sorry for that really long run on sentence with nested parens :D

[jneira]

@freckeltonj Don't worry and thanks again for the patch wherever is finally merged
And for explain your path looking for info, that pov is invaluable for helping improve docs

[Anton-Latukha]

@freckletonj, I know how that is. Docs are indeed frequently hard to merge. Besides Wadler's Law, community project docs workflow & design essentially should be built on the initial "the essence of wiki" principles (there are 4 cornerstone principles, which got forgotten & even ungoogleable, ironically he put those open principles into the private book), but projects frequently use code review & source code workflow for them. (I in no way appeal "to authority" there, it is mine conclusions from experience put in concise public-available terms).

[freckletonj]

I love the wiki idea. Actually, my favorite all-time documentation is kinda similar, have you ever seen ClojureDocs? I seriously think haskell would benefit from this format.

[Anton-Latukha]

Heard good stuff about ClosureDocs.

Essentially made alike documentation approach for myself to learn Haskell.

Something like ClosureDocs may start/be tried in near time. Especially after the new base. But HaskellWiki is already there & so as GHC wiki. Back in the day there was an idea/try to migrate Hackage package docs into HaskellWiki, so every package had an article there. As put "a wiki that needs to invent its own HTML for markup is a failed design", which is one of the things why people are not enthusiastic about writing in MediaWikis (& so to HaskellWiki also). & Hoogle is there. So basically seems like if a couple of people would not spearhead the agenda for several years & manage to connect enough pieces together - likely the situation would stay a cluster ***.

Haskell does not have good basic tutorial-level open learning materials for newcomers. & there is a wide range of topics to cover.

But overall I consider the situation not ideal, but not that bad either, it is bearable.

---

It is easier to give users the ability to change docs. & sit & review changes done by users in the last week/month (even team-sporadically/chaotically) & improve changes even more, than for 4 people to review 1 paragraph of documentation.

Devs anyway never (to be safe - almost never) change manual docs in the same PR they change code, even because code review changes would change the doc updates.

---

Just to be clear, the power of wikis I mention, is in these:

That is what I mean by "cornerstone wiki design principles".

All ideas basically converge on having an easily editable community Zettelkasten. MediaWiki (Wikipedia-related wikis) are a bad example due to formatting. All wikis also should be interlinked & preview articles of one another. MediaWikis have those integration abilities.

I've seen several contemporary innovative approaches to docs - they all converge to have community Zettelkastens. Even back in the day, Oxford English dictionary was created through that community process (& now if to squint GitHub powers open source and can be seen as one).