Vim migration guide

[person808]

Following outline in #773

[person808]

This is nowhere near done. I will continue working on it. Are there any good links about spacemacs i should add to this?

[tuhdo]

I think you should convert it to Org, so later we can display it inside Spacemacs with Org which looks nicer than markdown, since Org is native to Emacs, similar to how Spacemacs change log is displayed. We can put a button below the Evil Tutor and Emacs Tutor buttons. Since Github can render Org, we should not have any problem displaying it on the web.

[person808]

I've never used org before :|. I'll finish it in markdown and convert it using pandoc.

[tuhdo]

Well it's a good chance to learn. Org is easy:

• Use * to denote heading level i.e. 2 means 2 level.
• *text* for bold text, /text/ for italic, _text_ for underline and =text= for boxed text.
• TAB to move to next header, S-TAB to go back.
• To quote a language (i.e. such language block has proper highlighting), use this code block:

#+begin_src language

#+end_src

You can replace language with emacs-lisp for proper Elisp highlighting. You can press C-c ' to open a separate buffer to edit code and C-c ' again to quit. And, you don't have to type everything: just type src then M-/ to let yasnippet takes care of it you.

Learning Org worth it, believe me. You can later use Org for more things, i.e. evaluate inline code, save internet links or local files or directory, or store magit commits to open later etc...

[person808]

@tuhdo There are a few problems with org. The table of contents links arent working on github. I'm using toc-org.

The links to documentation.md and conventions.md dont work in emacs.

There is no <kbd></kbd> tag in org. I'm leaving the markdown file until I can fix these issues

[tuhdo]

The link doesn't work because it keeps markdown format and not converted to Org. You should store the link directly in Emacs with org-store-link and insert the link with org-insert-link.

To insert with kbd tag, simply wrap it around =...=.

[tuhdo]

The correct link should look something like this:

[[file:helm-intro.org::*Command:%20%3Dhelm-color%3D][Command: =helm-color=]]

That is the output of using org-store-link on an Org heading then org-insert-link. You can use C-c C-o to open the link with cursor on the exact heading.

Here is another exampple of direct URL:

[[http://youtu.be/gP-zpA4WteM][Video Demo]]

You can have a look at the example README by @mkcode. Raw text

[TheBB]

Not a huge thing, but maybe you can avoid updating this PR every two minutes? It spams the gitter chat a lot. You can also force Travis to skip CI if you put [ci skip] somewhere in the commit messages.

[person808]

@TheBB Sorry about that. I've been using github to preview it in the browser. Totally forgot about gitter :)

[tuhdo]

Nice, some productivity key bindings:

• C-RET to create the next save level heading, so you don't have to move to the end of a heading just to manually insert *.
• M-RET to create the next heading according to current heading, i.e. if your current heading has TODO in it, M-RET also inserts TODO and a heading with the same level.
• Set org-use-speed-commands to t, so when you at the beginning of the line, Org automatically enter modal mode i.e. you can simply press n and p to move to next or previous heading. Press ? if you want to learn more.
• Use helm-org-in-buffer-heading to easily navigate to any heading, similar to helm-imenu.
• M-q to fill a paragraph.

[tuhdo]

You should also mention about the microstate. It seems like both Vim and non-Vim users are confused by it, since two people asked me yesterday that somehow Spacemacs changes "modes".

[person808]

@tuhdo Do you mean microstates in general or just the paste microstate?

[tuhdo]

The microstate in general.

[person808]

Added: microstates, .spacemacs, adding layers, and creating layers.

TODO: use-package, basic elisp

[tuhdo]

I think this is good enough. For Elisp, we better use existing resources. For example, we could put a link to this 15 minutes Elisp tutorial in Org.

Then we tell how to rebind keys.
Then how to use use-package.

[tuhdo]

Some key bindings for table:

• Press TAB and S-TAB to move between cells and make it adapt to text automatically.
• To align whole table, C-c C-c
• C-c - to create a separator below point.
• To insert new row, simply press RET.
• M-S-<right> to create a new column; M-S-<left> to delete a column.
• M-x org-table-create or C-c | to create a table of column x row.

[person808]

I was going to link to learnxinyminutes.com. Looks like it has the same tutorial :)

I'm only going to go over basic things like setting variables, keybindings, and maybe calling functions.

Edit: Decided not to do functions

[person808]

Is there anything else I should add?

[moesasji]

Overall reads like an excellent guide. Well done!

The only thing I think would be good to add is to specify the shortcut to open the config file when you discuss the .spacemacs file. Knowing that you can hit <SPC> f e d to open this file is helpful for a new user.

[TheBB]

It may be helpful to note that even though you can't run ex-commands with SPC :, you can run Emacs interactive commands with :.

The keybinding for kill-other-buffers is SPC b K, not SPC K.

Perhaps a minor point, but in my experience vim users tend to use v and s as mnemonics for window splits, and will feel more at home with the SPC w v/s bindings instead of SPC w / and SPC w -.

It may be a good idea to mention SPC <f1> under Help.

[person808]

@TheBB @moesasji Thanks for reviewing! I've updated to address your comments.

[person808]

@syl20bnr I think this is ready to be merged. Any further improvements can be made in future PRs

[trishume]

This is awesome! 👍

[trishume]

Reads well as a general overview tutorial though, even if you aren't coming from vim. Another thing that might be handy is a mapping for common vim plugins and functionality like @tuhdo gave in that one reddit thread (link is somewhere on gitter and /r/emacs history). That can be a later PR though.

[person808]

@trishume I added some parts of that answer that I think should be covered.

[mrmargolis]

This is really great, but one thing I noticed was that the section on sessions suggests desktop-mode. I think this is supposed to be desktop-save-mode? Also, this mode does not appear to play well with Spacemacs startup and has open incidents like #1265 and #1112

[trishume]

Is this ready to be merged? It is really good.

[person808]

@trishume Yup! Its ready.

[syl20bnr]

Excellent work ❤️ Thank you !
Should have merged this earlier!
Cherry-picked and amended with change log content into develop branch, you can safely delete your branch.