vimrc.txt

*vimrc.txt* Vim configuration as a self-bootstrapping plugin.
*rxrc/vimrc*

                                _                    ~
                         __   _(_)_ __ ___  _ __ ___ ~
                         \ \ / / | '_ ` _ \| '__/ __|~
                          \ V /| | | | | | | | | (__ ~
                           \_/ |_|_| |_| |_|_|  \___|~


==============================================================================
CONTENTS                                                      *vimrc-contents*

    1.Intro....................................|vimrc-intro|
        1.1.Structure..........................|vimrc-structure|
    2.Plugin settings..........................|vimrc-plugin-settings|
        2.1.Autocompletion settings............|vimrc-autocompletion-settings|
        2.2.Unite settings.....................|vimrc-unite-settings|
        2.3.vimfiler settings..................|vimrc-vimfiler-settings|
    3.Mappings.................................|vimrc-mappings|
        3.1.Nonstandard Vim mappings...........|vimrc-nonstandard-mappings|
        3.2.Plugin specific mappings...........|vimrc-plugin-mappings|
    i.About....................................|vimrc-about|
    ii.License.................................|vimrc-license|
    iii.Warranty...............................|vimrc-warranty|

==============================================================================
1. Intro                                                         *vimrc-intro*

This configuration system works as a meta-plugin:
all desired Vim plugins are loaded from *plugins.vim* using vim-plug.
Overall configuration then follows a normal plugin structure.

This document concerns the methodology behind my specific Vim environment.
For installation instructions and development information, see

    https://github.com/rxrc/vimrc

------------------------------------------------------------------------------
1.1 Structure                                                *vimrc-structure*

All plugins are loaded in `plugins.vim` using vim-plug.
Some plugin settings must be set at plugin initialization.
Those settings are located at the bottom of `plugins.vim`.

All other settings are split into individual files organized
either by function or plugin.

Standard Vim configuration is contained directly under `plugin`.
Plugin specific configuration is contained in a correspondingly
named `.vim` file in some (possible nested) directly under `plugin`.
Settings are grouped by plugin, or possibly by the function
of several interrelated plugins.

The `plugin/mappings` directory is reserved for mappings.
The `plugin/autocompletion` directory contains file type specific
autocompletion configuration.

Use of `autocmd` within `augroup` is preferred over `ftplugin`
in order to group related configuration by plugin instead of file type.

==============================================================================
2. Plugin settings                                     *vimrc-plugin-settings*

This section provides an overview of plugin specific configuration choices.

A general feature and usage overview is given below.
Plugins with more involved configurations are given their own subsection.

TODO: Fill in.

------------------------------------------------------------------------------
2.1 Autocompletion settings                    *vimrc-autocompletion-settings*

Autocompletion is handled by neocomplete and neosnippet.
File type specific settings are defined under `plugin/autocompletion`.

Note: the following mappings are not listed under |vimrc-mappings|.

    - <C-Space> starts manual completion.
    - <Tab> navigates down completion popup.
    - <C-J> and <C-K> navigate the popup in either direction.
    - <C-L> inserts and then navigates snippets.
    - <CR> closes the popup (keep completion).
    - <C-W> smart-closes the popup (cancel completion).

------------------------------------------------------------------------------
2.2 Unite settings                                      *vimrc-unite-settings*

Note: the following mappings are not listed under |vimrc-mappings|.

TODO: Fill in.

------------------------------------------------------------------------------
2.3 vimfiler settings                                *vimrc-vimfiler-settings*

Note: the following mappings are not listed under |vimrc-mappings|.

TODO: Fill in.

==============================================================================
3. Mappings                                                   *vimrc-mappings*

With minor exceptions, all mappings are defined in individual `.vim` files
under `plugin/mappings`.

Conventionally, plugin specific mappings go in a file named after
the corresponding plugin, e.g., `fzf.vim`.
Alternatively, mappings spanning several interrelated plugs may be
grouped under a single file, e.g., `autocompletion.vim` contains mappings
for neocomplete, neosnippet, etc.

The special file `editor.vim` is reserved for standard Vim mappings.

The remainder of this section documents mappings created or modified
by this plugin. For behavior, refer to either Vim's or
the corresponding plugin's documentation.

A general overview is given below, while a complete reference
of all mappings is given in the following subsections.

Note: my keyboard maps `CapsLock` to `RCtrl` and `RCtrl` to `Esc`.

A mapping that depends on a plugin will contain the [Plugin Name]
in square brackets.

Critically different mappings
    - <Leader> is set to <Space> and <LocalLeader> is \.
    - Enter (or <Esc>) leaves insert mode.
    - Use <C-CR> or <S-CR> to insert a newline (split the line)
      in normal or insert mode.
    - Enter opens command-line mode from normal or visual mode.
    - <S-Esc> toggles the command-line window in normal or visual mode.
    - U is mapped to redo and <C-R> is mapped to the original U key.
    - q and Q provide single key mappings for ge and gE.
    - <Leader>q is mapped to q (since q is now mapped to ge).
    - ; is the [EasyClip] substitution operator.
    - ` and ' are swapped.
    - & is remapped to reuse flags (synonym for `:&&`).
    - [Sneak] takes over s and S.
    - [EasyClip] takes over m and M (<Leader>' is mapped to M).
    - Marks are handled by [Signature] with <Leader>;.
      Use <Leader>;; to toggle marks.
    - Autocompletion with [neocomplete] and [neosnippet]:
      see |vimrc-autocompletion-settings|.

Shortcuts for common functions
    - <C-H>, <C-J>, <C-K>, and <C-L> move between splits,
      move the cursor, scroll through history, and navigate popups.
      They serve as general alternatives to the arrow keys when possible.
      [Vim Tmux Navigator] implements split navigation.
    - Double tap <Leader> to toggle folds.
    - <Leader>x is an easier to input shortcut for gx.
    - <Leader>o clears the highlighting until next search.
    - <Leader>= inserts from the expression register.
    - <Leader>p and <Leader>P paste from the system clipboard.
    - <Leader>c{motion} yanks to the system clipboard,
      <Leader>C yanks to end of line to the system clipboard,
      and <Leader>cc yanks the current line to the system clipboard.
    - <Leader>m{motion} deletes and yanks to the system clipboard,
      <Leader>M deletes and yanks to end of line to the system clipboard,
      and <Leader>mm deletes and yanks the current line to the system clipboard.
    - <Leader>:, <Leader>/, and <Leader>? open the corresponding
      command-line or search window.
    - [EasyClip] M is mapped to m$.
    - [Commentary]: toggle commenting with \\.
    - [Emmet] leader is <C-E> and expander is <C-O>.

Shortcuts for windows, tabs, and splits
    - <Leader>{hjkl} splits the window.
    - <Leader>{HJKL} splits the frame.
    - <Leader><Tab> opens a new tab and <Leader><S-Tab> closes the tab.
    - <Leader>, and <Leader>. cycle through tabs.

Shortcuts for buffer manipulation
    - <Leader><CR> is a synonym for `:quit` and <Leader>Q for `:quit!`.
    - <C-Q> is a synonym for `:quitall`.
    - <Leader>n is a synonym for `:enew`.
    - <Leader>E is a synonym for `:edit!`.
    - <Leader>s and <Leader>S are synonyms for `:update` and `:write!`.
    - [Bbye]: close and force close buffers with <Leader>w and <Leader>W.

Interfaces
    - [Ag]: <Leader>A will search with `:Ag`.
    - [Autoformat]: <Leader>+ will run `:Autoformat`.
    - [Unite] buffers are mapped to <Leader>{abey}.
      See also |vimrc-unite-settings|.
    - [fzf] functions all begin with <Leader>f.
    - [fugitive] functions all begin with <Leader>g.
    - [vimfiler]: open and focus with <Leader>i and toggle with <Leader>I.
      See also |vimrc-vimfiler-settings|.
    - [Undotree]: open and focus with <Leader>u and toggle with <Leader>U.
    - [Tagbar]: open and focus with <Leader>t and toggle with <Leader>T.
    - For some file types, d and D will provide an interface to
      documentation lookup.
      Mapped for [ri] and [fireplace].

Toggles
    - coa toggles [Rainbow Parentheses].
    - cof toggles [EasyClip] paste formatting.
    - com toggles the colorcolumn display.
    - cop toggles the <Leader>p, <Leader>P, and <Leader>c
      mappings between using the `+` (default) and `*` registers.
    - coz toggles [Unicode] name or glyph completion.

------------------------------------------------------------------------------
3.1 Nonstandard Vim mappings                      *vimrc-nonstandard-mappings*

This section lists any standard Vim mappings which this plugin remaps,
and any new mappings to existing Vim functions.
All mappings are nonrecursive unless otherwise noted.

                                                        *com*
com                     Toggle system clipboard mappings between using
                        the + and * registers. See |<Leader>p|, |<Leader>P|,
                        and |<Leader>c|.

                                                        *cop*
cop                     Toggle display of colorcolumn.

                                                        *q*
q                       Mapped to the motion ge (recursive).

                                                        *Q*
Q                       Mapped to the motion gE (recursive).

                                                        *U*
U                       Mapped to <C-R> (redo).

                                                        *`*
`                       Mapped to ' (` is swapped with ').

                                                        *'*
'                       Mapped to ` (` is swapped with ').

                                                        *&*
&                       Synonym for `:&&`.

                                                        *<CR>*
<CR>                    Exit insert mode via <Esc>. In normal
                        or visual mode, open command-line mode.
                        Otherwise this still behaves like <CR>.
                        While the command-line and search windows are open,
                        this still executes the selected command or search:
                        Use <Leader>: to open command-line mode
                        from these windows.

                                                        *<S-CR>*
<S-CR>                  Insert a newline in normal or insert mode.

                                                        *<S-Esc>*
<S-Esc>                 In normal or visual mode, toggle opening
                        and closing the command-line window.

                                                        *<C-H>*
<C-H>                   In insert mode and command-line mode,
                        move cursor one character right.

                                                        *<C-J>*
<C-J>                   In command-line mode, navigate history down.

                                                        *<C-K>*
<C-K>                   In command-line mode, navigate history up.

                                                        *<C-L>*
<C-L>                   In insert mode and command-line mode,
                        move cursor one character right.

                                                        *<C-Q>*
<C-Q>                   Synonym for `:quitall`.

                                                        *<C-R>*
<C-R>                   Mapped to U.

                                                        *<Leader>c*
                                                        *<Leader>C*
                                                        *<Leader>cc*
<Leader>cc       or     Same as y, but use the system register +.
<Leader>C        or     <Leader>cc yanks the current line.
<Leader>c{motion}       <Leader>C yanks to the end of line.
                        Can toggle between + and * registers using |cop|.

                                                        *<Leader>q*
                                                        *<Leader>E*
<Leader>E               Synonym for `:edit!`.

                                                        *<Leader>h* *<Leader>j*
                                                        *<Leader>k* *<Leader>l*
<Leader>{hjkl}          Split the window in corresponding direction.

                                                        *<Leader>H* *<Leader>J*
                                                        *<Leader>K* *<Leader>L*
<Leader>{HJKL}          Split the frame in corresponding direction.

                                                        *<Leader>m*
                                                        *<Leader>M*
                                                        *<Leader>mm*
<Leader>mm       or     Same as m, but move to the system register +.
<Leader>M        or     <Leader>mm moves the current line.
<Leader>m{motion}       <Leader>M moves to the end of line.
                        Can toggle between + and * registers using |cop|.

                                                        *<Leader>n*
<Leader>n               Synonym for `:enew`.

                                                        *<Leader>o*
<Leader>o               Synonym for `:nohlsearch`.

                                                        *<Leader>p* *<Leader>P*
<Leader>{pP}            Same as p and P, but use the system register +.
                        Can toggle between + and * registers using |cop|.

                                                        *<Leader>q*
<Leader>q               Mapped to q.

                                                        *<Leader>Q*
<Leader>Q               Synonym for `:quit!`.

                                                        *<Leader>s*
<Leader>s               Synonym for `:update`.

                                                        *<Leader>S*
<Leader>S               Synonym for `:write!`.

                                                        *<Leader>x*
<Leader>x               Mapped to gx.

                                                        *<Leader>'*
<Leader>'               Mapped to M.

                                                        *<Leader>,*
<Leader>,               Mapped to gT.

                                                        *<Leader>.*
<Leader>.               Mapped to gt.

                                                        *<Leader>:*
<Leader>:               Mapped to q:.

                                                        *<Leader>/*
<Leader>/               Mapped to q/.

                                                        *<Leader>?*
<Leader>?               Mapped to q?.

                                                        *<Leader>=*
<Leader>=               Synonym for `:put` `=`

                                                        *<Leader><CR>*
<Leader><CR>            Synonym for `:quit`.

                                                        *<Leader><Leader>*
<Leader><Leader>        Mapped to za.

                                                        *<Leader><Tab>*
<Leader><Tab>           Open a new tab.

                                                        *<Leader><S-Tab>*
<Leader><S-Tab>         Close the current tab.

------------------------------------------------------------------------------
3.2 Plugin specific mappings                           *vimrc-plugin-mappings*

This section lists mappings to plugin specific functions,
and modifications to a plugin's normal provided mappings.

Each mapping's dependent plugin is prefixed
by the [Plugin Name] in square brackets.

                                                        *coa*
coa                     [Rainbow Parentheses] Synonym for `:RainbowToggle`.

                                                        *cof*
cof                     [EasyClip] Toggle paste formatting.

                                                        *coz*
coz                     [Unicode] Toggle unicode name or glyph completion.

                                                        *M*
M                       [EasyClip] Mapped to m$ (move text until end of line).

                                                        *;* *;;* *;s*
;               or      [EasyClip] Substitution operator.
;{;s}

                                                        *\\*
\\                      [Commentary] Mapped to gcc.

                                                        *<C-E>*
<C-E>                   [Emmet] In insert mode, emmet leader key.

                                                        *<C-O>*
<C-O>                   [Emmet] In insert mode, Emmet expander key.

                                                        *<Leader>a* *<Leader>b*
                                                        *<Leader>e* *<Leader>y*
<Leader>{abey}          [Unite] Open a Unite.vim buffer: [a]g (grep)
                                [b]uffers, fil[e]s, or [y]anks.

                                                        *<Leader>A*
<Leader>A               [Ag] Prompt to search with `:Ag`.

                                                        *<Leader>+*
<Leader>+               [Autoformat] Synonym for `:Autoformat`.

                                                        *<Leader>d* *<Leader>D*
<Leader>{dD}            [ri] Prompt to search for documentation:
                             result window split horizontally (d)
                             or vertically (D).

                        [fireplace] Prompt to lookup documentation with
                                    `:Doc` or `:FindDoc`.

                                                        *<Leader>f*
<Leader>f{acdefhjklmqstv/} or
<Leader>f<Space>        [fzf] Open a fzf search, e.g.,
                              <Leader>ff is a synonym for `:FzfFiles`.
                              Use <Leader>fm to lookup the other mappings.

                                                        *<Leader>g*
<Leader>g{abcdeghjklmrsw}
                        [fugitive] Synonyms for git wrapper commands..
                                   Use <Leader>fm to lookup the mappings.

                                                        *<Leader>t* *<Leader>T*
<Leader>{tT}            [Tagbar] Focus Tagbar panel with t, toggle with T.

                                                        *<Leader>u* *<Leader>U*
<Leader>{uU}            [undotree] Focus undotree panel with u, toggle with U.

                                                        *<Leader>w* *<Leader>W*
<Leader>{wW}            [Bbye] Close the buffer but not the window:
                               w is a synonym for `:Bdelete` and
                               W is a synonym for `:Bdelete!`.

                                                        *<Leader>;*
                                                        *<Leader>;;*
<Leader>;{signature-mapping} or
<Leader>;;              [Signature] <Leader>; is the signature leader.
                                    <Leader>;; will toggle marks (<Leader>;.).

==============================================================================
i. About                                                         *vimrc-about*

This plugin is authored by Evan Sosenko:

    https://evansosenko.com

Find the source and latest version at

    https://github.com/rxrc/vimrc

==============================================================================
ii. License                                                    *vimrc-license*

This Vim configuration is licensed under the MIT license.

    https://github.com/rxrc/vimrc/blob/master/LICENSE.txt.

==============================================================================
iii. Warranty                                                 *vimrc-warranty*

This software is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantibility and fitness for a particular
purpose.

 vim:tw=78:sw=4:ft=help:norl: