Vim migration guide: Initial version.

doc/VIMUSERS.org

@@ -0,0 +1,106 @@
+* Migrating from vim                                               :TOC_4_gh:
+ - [[#philosophy][Philosophy]]
+ - [[#basic-orientation][Basic orientation]]
+         - [[#terms][Terms]]
+             - [[#modes-vs-states][Modes vs. States]]
+             - [[#layers][Layers]]
+         - [[#keybinding-conventions][Keybinding conventions]]
+         - [[#running-commands][Running commands]]
+         - [[#buffer-and-window-management][Buffer and window management]]
+             - [[#buffers][Buffers]]
+             - [[#windows][Windows]]
+ - [[#customization][Customization]]
+
+* Philosophy
+ One misconception many vim users have is that Spacemacs is an Emacs /clone/ of
+ vim. Spacemacs does not seek to completely mimic the behavior of vim
+ everywhere, only when editing. You should not expect every vim command to be
+ available, although many are. You cannot use Vimscript to configure Spacemacs,
+ but who likes Vimscript anyway? Spacemacs is an attempt to improve on both vim
+ and Emacs using the superior modal editing of vim and the nicer configuration
+ language of Emacs.
+
+* Basic orientation
+*** Terms
+Spacemacs uses some different terminology than vim, which can cause confusion
+for new users. This section attempts to clear up any confusion.
+
+**** Modes vs. States
+In vim you have various editing modes like =insert mode= and =visual mode= to
+manipulate text. In Emacs, we have [[./DOCUMENTATION.md#states][states]]. These
+are equivalent to vim modes. For example, =evil-insert-state= is the same as
+=insert-mode= in vim.
+
+A =minor-mode= in Emacs is like a feature that is activated. For example,
+=aggresive-indent-mode= is a =minor-mode= that automatically indents code as you
+type. It is important to know that there can be many =minor-modes= activated in
+a buffer. Many Emacs packages work by providing a =minor-mode=. A =major-mode=
+determines the editing behavior of Emacs in the current buffer. There is
+generally a corresponding =major-mode= per filetype. An example of a
+=major-mode= is =python-mode=, which provides python specific settings in python
+files. There is only one =major-mode= per buffer.
+
+**** Layers
+Spacemacs has the concept of layers. Layers are similar to vim plugins. They
+provide new features to use in Spacemacs. However, layers are often comprised of
+several packages that integrate well with each other. For example, the =python=
+layer includes support for auto-completion, documentation look-up, tests, and
+much more by using several different packages. This keeps you from thinking
+about what packages to install, and instead worry about what features you want.
+More information on layers in the [[./VIMUSERS.md#customization][customization]]
+section and in the [[./DOCUMENTATION.md#configuration-layers][documentation]].
+
+*** Keybinding conventions
+Spacemacs uses =SPC= as its =<Leader>= key. This document
+will use =SPC= to refer to the =<Leader>= key. All
+keybindings are mnemonic and are organized under the =<Leader>= key.
+For example, the keybindings for language-specific commands are always under the
+SPC m prefix. A full list of conventions used in Spacemacs is [[./CONVENTIONS.md][here]]. Note that
+all keybindings can be changed.
+
+Spacemacs uses [[https://github.com/kai2nenobu/guide-key][guide-key]] to show available keybindings after a delay:
+
+#+CAPTION: Guide Key
+
+[[https://cloud.githubusercontent.com/assets/6396431/7556069/b8dbfcd4-f6fd-11e4-8bdc-31c19611e7f3.png]]
+
+*** Running commands
+Emacs commands can be run using ~SPC := ~. This will pop up
+a buffer using [[https://github.com/emacs-helm/helm][Helm]] which can be used to run any Emacs command. You can also run
+many ex commands using ~:= ~, just like vim.
+
+*** Buffer and window management
+Spacemacs provides several ways to manage buffers and windows. The keybindings
+are available under the ~SPC b= ~ prefix for buffers and the
+~SPC w= ~ prefix for windows.
+
+**** Buffers
+To create a buffer, type ~SPC b b= ~ and Spacemacs will
+create a buffer with the provided name. It will load the correct major-mode if a
+file extension is given. This same interface also allows you to search and
+select a buffer to switch to using fuzzy matching.
+
+To switch to the next/previous buffer, use ~SPC b n= ~ and
+~SPC b p= ~. By default Emacs creates a lot of buffers that
+most people will never need, like =*Messages*=. Spacemacs automatically ignores
+these when using these keybindings. More information can be found [[./DOCUMENTATION.md#special-buffers][here]]. The ex
+commands =bnext= and =bprevious= are also available.
+
+To kill (close) the current buffer use ~SPC b d= ~. The ex
+command =bdelete= also performs the same function. To search for a buffer to
+kill, use ~SPC b k= ~. This shows a list of buffers that you
+can filter using fuzzy matching and kill. To kill all buffers except the current
+buffer use ~SPC K= ~.
+
+**** Windows
+Windows are like splits in vim. A vertical split can be created using
+~SPC w /= ~ and =vsplit=. A horizontal split can be created
+using ~SPC w -= ~ and =split=. To navigate among windows,
+you can use ~SPC w h/j/k/l= ~. To move windows, the
+keybindings ~SPC w H/J/K/L= ~ are available.
+
+To kill a window use the keybinding ~SPC w c= ~. To kill a
+window that you are not in, use ~SPC w C~. This will prompt
+you to select a window to kill if there are more than three.
+
+* Customization