more in depth readme

[krux02]

overhaul of the README file. Generally I worked on everything in the readme. But the important changes are the following:

• I made aware of some of the problems that are to be expected when using nimsuggest or electric indentation.
• I added a guide to prevent the known problems with nim-mode.
• There is a small introduction of the individual components that work together in nim-mode. I was certainly overwhelmed when I first saw all these mode names and I had no idea what they meant. I hope now it is a little less intimidating.

I don't expect you to merge this in right away, but at least let me know what you think about it.

fixes https://github.com/nim-lang/nim-mode/issues/37

[yuutayamada]

I don't want to include information which might change time by time like the known problem whereas we already have issue tracker. Also MELPA uses nim-mode.el's commentary section, so if you really aware people you should change there, again you need fix the document (readme and nim-mode.el's comment) when you fix the problem. I feel it's suck. I think your information is valuable, but it should be documented on wiki page, so you don't need to ask me for PR. Regarding nim-mode configuration, I feel it's redundant, but my brain is pretty biased by long term emacs use, so you might right. However, let me point out some stuff that you might not aware of:

1. eldoc mode is turned on by default (from Emacs 25.1), so I'm not sure why nim-mode needs to explain it. Also it's related to "3"
2. I think your configuration is wrong to turn the modes on. 0 means off. (you are using all config to 0)
3. users can use prog-mode-hook for globally used packages like flycheck, or company-mode. I feel odd watching those modes in nim-mode specific configuration.
4. I'm not targeting users who don't understand their config. I'd recommend spacemacs for easy configuration such people and they have more contributors compared to this almost solo project.
5. I might have more, but for now that's it.

[krux02]

The point for me is, I started using emacs with Nim. No emacs experience before. Emacs is incredibly intransparent. There is documentation scrattered around and it is kind of integrated into emacs, too, but it is hard to find the right documentation. The biggest problem I think is that the documentation is ordered depth first. It explains low level details liked navigation on text first, but it does a poor job at providing an overview of the individual components in emacs, and how they interact with each other.

I use emacs now for almost 3 years, almost exclusively for Nim development and I am now the official full time developer on Nim. I think am qualified enough to say what works in nim-mode and what does not work. And at the current state I have to say, nimsuggest causes more trouble than it solves problems, it is not worth to be enabled. It is hard to get configured correctly for non trivial projects and it causes emacs freezes and blocked input. Apart from nimsuggest, electric indentation is something that causes a lot of pain when editing Nim files. It is slow and already broke a lot of code from me. And since it is triggered automatically, when I fixed the code manually, it was instantly broken by electric indentation again. This caused huge pain. I simply want to warn new users about these struggles, so they won't have the same frustration as I did. And I want that people who might be interested in contributing and fixing bugs get a rough idea of the components in use.

The reason I turned off so many features in the example configuration is that these things caused problems for me in the past and it took at lot of time from me to figure out that these things were the reason.

Now to your complains

eldoc mode is turned on by default (from Emacs 25.1), so I'm not sure why nim-mode needs to explain it. Also it's related to "3"

As I said nimsuggest causes problems, and eldoc, enabled by default as you said, also enabled nimsuggest, including it's problems. So I thought I should warn about that.

I think your configuration is wrong to turn the modes on. 0 means off. (you are using all config to 0)

Turning the modes off is intentional. I don't think they are production ready for nim-mode. Turnning them off is important to spare the frustration. I made clear that user can also turn them on if they want to.

users can use prog-mode-hook for globally used packages like flycheck, or company-mode. I feel odd watching those modes in nim-mode specific configuration.

I am not sure if prog-mode-hook is the right place to do it. Since there is also global-company-mode and global-flycheck-mode.

I'm not targeting users who don't understand their config. I'd recommend spacemacs for easy configuration such people and they have more contributors compared to this almost solo project. I might have more, but for now that's it.

As the new developer of Nim, I can say, I want to target people who don't understand their config. I want to target people who start using emacs the first time programming Nim. It is important that the default works flawlessly out of the box without hickups. Good defaults are important.

If some of these informations will change over time, I will updated this readme. I use nim-mode dayly and I am very interested in the frontpage to have good and information about it. And you can be sure that I will have nimsuggest tested extensively before I declare it as read to use in nim-mode. At the current state I have to say it is not.

[yuutayamada]

It is hard to get configured correctly for non trivial projects and it causes emacs freezes and blocked input.

I'm not sure whether I understood what you are wring correctly. Are you taking about cofig.nims, emacs configuration, or nimsuggest side's configuration? or all nimsuggest stuff inclusive?

The reason I turned off so many features in the example configuration is that these things caused problems for me in the past and it took at lot of time from me to figure out that these things were the reason.

I guess now you can turn off nimsuggest stuff by commenting out "(add-hook 'nim-mode-hook 'nimsuggest-mode)"

Turning the modes off is intentional. I don't think they are production ready for nim-mode. Turnning them off is important to spare the frustration. I made clear that user can also turn them on if they want to.

Not metioning how to turn on is intentional?

I am not sure if prog-mode-hook is the right place to do it. Since there is also global-company-mode and global-flycheck-mode.

Yeah, I know those, but I just use prog-mode-hook. global-xxx is too global for me. (it activate unintetional buffer sometimes)

As the new developer of Nim, I can say, I want to target people who don't understand their config. I want to target people who start using emacs the first time programming Nim. It is important that the default works flawlessly out of the box without hickups. Good defaults are important.

I like good default too. My point being is that I can't afford the time to maitaining this repository just for README and nim-mode.el's Commentary section. Possibly nim's editor page as well. That's why I'm recomeending spacemacs. I'm sorry saying this, but I have social life and currently I have some family issue which I have to care more than OSS. I don't object if you take care those README, nim-mode's Commentary section and Nim's editor page though.

And you can be sure that I will have nimsuggest tested extensively before I declare it as read to use in nim-mode. At the current state I have to say it is not.

I was away from Nim for awhile, so I'm not sure current state. Is Nim not stable even in stable branch? It's not clear for me whether you are talking about devel branch or not. Probably same for other non Nim readers.

[yuutayamada]

Oops, I forgot saying congrats that you becoming full time contributor of Nim. Surely that's great news for me because you use Emacs! Hope you can fix nimsuggest related issue (I mean Nim's compiler side)

[krux02]

It is hard to get configured correctly for non trivial projects and it causes emacs freezes and blocked input.

I'm not sure whether I understood what you are wring correctly. Are you taking about cofig.nims, emacs configuration, or nimsuggest side's configuration? or all nimsuggest stuff inclusive?

I mean all nimsuggest stuff inclusive and all grammar (smie) based functionality. I don't understand the smie files well enough to fix them, that is why I recommend to turn electric indentation off for nim. I think I said it in the readme, but I don't think it's practical to use electric indentation in languages such as Python and Nim with semantic whitespace. You certainly don't loose a lot when electric indentation is turned off in Nim, because a new line still gets a good default indentation level.

The reason I turned off so many features in the example configuration is that these things caused problems for me in the past and it took at lot of time from me to figure out that these things were the reason.

I guess now you can turn off nimsuggest stuff by commenting out "(add-hook 'nim-mode-hook 'nimsuggest-mode)"

As I said, turning off electric indentation mode is still recommended from my experience. This is turned on by default.

Turning the modes off is intentional. I don't think they are production ready for nim-mode. Turnning them off is important to spare the frustration. I made clear that user can also turn them on if they want to.

Not metioning how to turn on is intentional?

That is not intentional, I thought it is obvious to change a 0 to a 1 when you want to turn it on. But yes your are right abot that.

I am not sure if prog-mode-hook is the right place to do it. Since there is also global-company-mode and global-flycheck-mode.

Yeah, I know those, but I just use prog-mode-hook. global-xxx is too global for me. (it activate unintetional buffer sometimes)

I think both are valid choices.

As the new developer of Nim, I can say, I want to target people who don't understand their config. I want to target people who start using emacs the first time programming Nim. It is important that the default works flawlessly out of the box without hickups. Good defaults are important.

I like good default too. My point being is that I can't afford the time to maitaining this repository just for README and nim-mode.el's Commentary section. Possibly nim's editor page as well. That's why I'm recomeending spacemacs. I'm sorry saying this, but I have social life and currently I have some family issue which I have to care more than OSS. I don't object if you take care those README, nim-mode's Commentary section and Nim's editor page though.

And you can be sure that I will have nimsuggest tested extensively before I declare it as read to use in nim-mode. At the current state I have to say it is not.

I was away from Nim for awhile, so I'm not sure current state. Is Nim not stable even in stable branch? It's not clear for me whether you are talking about devel branch or not. Probably same for other non Nim readers.

No matter what branch of Nim you take, nimsuggest has problems. It does not work reliable. It crashes freezes or it could eat up a lot of ram. Nothing of those problems are handled in nimsuggest-mode, and I am not sure if they should be handled there.

Oops, I forgot saying congrats that you becoming full time contributor of Nim. Surely that's great news for me because you use Emacs! Hope you can fix nimsuggest related issue (I mean Nim's compiler side)

Thank you! I will do my best.

[yuutayamada]

I think you should mention electric-indent-chars. Emacs' default setting includes the RET key to activate auto-indentation when users type it. It was changed to current state on some emacs version. I prefer old behavior, but that's nothing I can do from nim-mode.

In nim-mode, there are two electric-indent chars : and space currently. the colon might need to be dead, but I think the space is still useful. Feel free to open issue if those char is bothering you. Also you have choice to change the electric chars by directory-local variable or file local variable.

[yuutayamada]

FYI, you can use C-j to insert newline even if electric-indent-mode

[krux02]

FYI, C-j runs the command electric-newline-and-maybe-indent (found in global-map), which is an interactive compiled Lisp function in ‘electric.el’.

[yuutayamada]

I know it changes behavior depending on the electric-indent-chars

[krux02]

• I think automatic code breaking on return is stupid.

• I think a workaround for nim-mode to use C-j as the non code breaking return is stupid.

• I think a return key, that doesn't break the code automatically when you press it is simple and elegant.

[yuutayamada]

Personally I'm your side, but the problem here (just for return key) is nim-mode should use same way as other major programming modes do like Haskell mode or Python mode.

[krux02]

I would like to inform you that I am about to merge this PR. Please note if you have any more major complaints.

[zedeus]

Can you add a small note about org-mode support? To avoid too much text you can link to the PR and include a code snippet that shows how to enable it

[krux02]

@zestyr good point, but that is not what this PR in particular is about. So I will do in in a later PR. If you want you can also make a PR for it.