Vim migration guide: Initial version.

doc/VIMUSERS.org

@@ -0,0 +1,234 @@
+* Migrating from vim                                               :TOC_4_gh:
+ - [[#purpose-of-this-document][Purpose of this document]]
+ - [[#philosophy][Philosophy]]
+ - [[#basic-orientation][Basic orientation]]
+         - [[#terms][Terms]]
+             - [[#modes-vs-states][Modes vs. States]]
+             - [[#layers][Layers]]
+             - [[#micro-states][Micro-states]]
+         - [[#keybinding-conventions][Keybinding conventions]]
+         - [[#running-commands][Running commands]]
+         - [[#buffer-and-window-management][Buffer and window management]]
+             - [[#buffers][Buffers]]
+             - [[#windows][Windows]]
+         - [[#files][Files]]
+         - [[#the-help-system][The Help System]]
+ - [[#customization][Customization]]
+     - [[#the-spacemacs-file][The .spacemacs file]]
+     - [[#activating-a-layer][Activating a Layer]]
+     - [[#creating-a-layer][Creating a Layer]]
+
+* Purpose of this document
+This document is intended to supplement the Spacemacs documentation by bridging
+the gap between vim and Spacemacs. While some information may be duplicated,
+this does not replace the Spacemacs documentation. It is recommended that you
+read both files to fully understand Spacemacs.
+
+[[file:DOCUMENTATION.md][Spacemacs Documentation]]
+
+* 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? It is important to understand that 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]].
+
+**** Micro-states
+Spacemacs provides a special functionality called micro-states. Micro-states
+allow similar commands to be run in succession without repeatedly pressing the
+=leader= key. Micro-states are usually triggered by using a keybinding with the
+following pattern: =Leader group .= where group is the category the micro-state
+falls under. When in a micro-state you will see documentation at the bottom of
+your window. To exit a micro-state press =q=.
+
+#+CAPTION: Microstate Documentation Window
+
+[[https://cloud.githubusercontent.com/assets/6396431/7580784/d4716352-f816-11e4-896d-ffcb71220151.png]]
+
+*** 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 in 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 <buffer name>= 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.
+
+*** Files
+All file commands in Spacemacs are available under the =SPC f= prefix.
+Pressing =SPC f f= opens a buffer to search for files in the current directory.
+The keybinding =SPC f r= allows you to search through recent files for one to
+open. The vim ex command =e= is also available to edit files. Saving a file is
+done with the =SPC f s= keybinding or the ex commands =w= or =x=.
+
+*** The Help System
+Emacs has an extensive help system. All keybindings under the =SPC h d= prefix
+allow convenient access to the help system. The most important of these
+keybindings are =SPC h d f=, =SPC h d k=, and =SPC h d v=. =SPC h d f= runs
+=describe-function=, which shows you the documentation of any function in
+Spacemacs. =SPC h d k= runs =describe-key=, which prompts you for a keybinding
+and displays what the keybinding does. =SPC h d v= runs =describe-variable=,
+which shows you the documentation for a variable and its current value.
+Whenever, you see weird behavior or want to know what something does, these
+functions are the first thing you should refer to.
+
+* Customization
+** The .spacemacs file
+When you first start spacemacs, you will be prompted to choose an editing style.
+If you are reading this, you likely want to choose the vim style. A =.spacemacs=
+file will be created with the appropriate style selected. Most trivial
+configuration will go in this file.
+
+** Activating a Layer
+As said in the terms section, layers provide an easy way to add features.
+Activating a layer is done in the =.spacemacs= file. In the file search for the
+=dotspacemacs-configuration-layers= variable. By default, it should look like
+this:
+
+#+begin_src emacs-lisp
+  (defun dotspacemacs/layers ()
+    (setq-default
+     ;; ...
+     dotspacemacs-configuration-layers '(;; auto-completion
+                                         ;; better-defaults
+                                         emacs-lisp
+                                         ;; (git :variables
+                                         ;;      git-gutter-use-fringe t)
+                                         ;; markdown
+                                         ;; org
+                                         ;; syntax-checking)))
+#+end_src
+
+You can uncomment these suggested layers by deleting the semi-colons for a nice
+out-of-the-box experience. To add a layer, add its name to the list and restart
+Emacs or press =SPC f e R=. To view all layers and their documentation use
+=SPC f e h=.
+
+** Creating a Layer
+To group configuration or when configuration doesn't fit well in your
+=.spacemacs= file, you can create a configuration layer. Spacemacs provides a
+builtin command to generate the layer boilerplate: =SPC : configuration-layer/create-layer=.
+This generates a folder that looks like this:
+
+#+BEGIN_EXAMPLE
+    [layer-name]
+      |__ [extensions]*
+      | |__ [example-mode-1]
+      | |     ...
+      | |__ [example-mode-n]
+      |__ config.el*
+      |__ extensions.el
+      |__ funcs.el*
+      |__ keybindings.el*
+      |__ packages.el
+
+    [] = directory
+    *not created by the command
+#+END_EXAMPLE
+
+The =packages.el= file contains a list of packages that you can install in the
+variable =<layer-name>-packages=. Any package that is available on the [[http:melpa.org][MELPA]]
+repository can be added to the list. You can also exclude packages by adding
+them to =<layer-name>-excluded-packages=. Each package requires a function to
+initialize it. The function /must/ be named with this pattern:
+=<layer-name>/init-<package-name>=. This function contains configuration for the
+package. It would look like this:
+
+#+begin_src emacs-lisp
+  (setq layer-name-packages '(example-package))
+  (defun layer-name/init-example-package ()
+    ;; Configuration for example-package goes here)
+#+end_src
+
+If something is not available on MELPA, you must use an extension. Extension
+configuration is done in the =extensions.el= file. Each extension must be placed
+in its own folder inside the =extensions= folder. Extensions can be declared
+using the =<layer-name>-<pre/post>-extensions= variables. =pre= extensions are
+loaded before the packages and =post= extensions are loaded after. The name of
+the extension is the name of the folder it is in. Using the above example
+structure, the extensions would be activated like so:
+
+#+begin_src emacs-lisp
+  (setq layer-name-pre-extensions '())
+  (setq layer-name-post-extensions '(example-mode-1 example-mode-n))
+#+end_src
+
+Notice the matching folder and extension names.
+
+Extensions also require an =init= function to be used. They use the same naming
+pattern as packages.
+
+Make sure you [[*Activating%20a%20Layer][add]] your layer to your =.dotspacemacs= file.