====== vim ======
''vim'' is not an editor with killerfeatures included, \\
but a killerfeature with an included editor.

===== modelines =====
Using ''modelines'', you can define per file settings inside the file itself. \\
Cause ''modelines'' are disabled per default, they have to be activated first:
  set modeline
The variable ''modelines'' defines how many lines from top (or bottom, respectively) of the file are expected to contain a modeline:
  set modelines=5
You can define ''modelines'' via two ways, although the old scool method is a little more compatible:
1. new school:
<file>
         [text]{white}{vi:|vim:|ex:}[white]{options}
 
 [text]          any text or empty
 {white}         at least one blank character (<Space> or <Tab>)
 {vi:|vim:|ex:}  the string "vi:", "vim:" or "ex:"
 [white]         optional white space
 {options}       a list of option settings, separated with white space or ':',
                 where each part between ':' is the argument for a ":set"
                 command
 
 Example: >
    vi:noai:sw=3 ts=6
</file>
2. old school:
<file>
         [text]{white}{vi:|vim:|ex:}[white]se[t] {options}:[text]
 
 [text]          any text or empty
 {white}         at least one blank character (<Space> or <Tab>)
 {vi:|vim:|ex:}  the string "vi:", "vim:" or "ex:"
 [white]         optional white space
 se[t]           the string "set " or "se " (note the space)
 {options}       a list of options, separated with white space, which is the
                 argument for a ":set" command
 :               a colon
 [text]          any text or empty
 
 Example: >
    /* vim: set ai tw=75: */
</file>

===== Helpful Settings =====
^ Variable ^ Abbrev ^ Type ^ Effect ^
| filetype | ft | String | defines the filetype, used for syntax highlighting |
| modeline | ? | Boolean | activates the interpretation of ''modelines'' |
| modelines | ? | Integer | holds the count of lines from top or bottom of the file to be searched for ''modelines'' |
| shiftwidth | sw | Integer | number of columns for auto indenting |
| tabstop | ts | Integer | number of columns for a tab **ATTENTION: this should match ''shiftwidth''** |
| textwidth | tw | Integer | specifies the maximum line length, longer lines will be broken after white space using <EOL> |
| linebreak | lbr | Boolean | wrap long lines, for displaying only (no changes are done to the file itself) |
| fileformat | ff | String | Set the format used when writing, e.g. ''set ff=unix\n:wq'' to convert a dos file to unix |

Using this line in the ''.vimrc'' file, the cursor is placed at the last known position in the file when opening:
  :au BufReadPost * if line("'\"") > 0 && line("'\"") <= line("$") | exe "normal g'\"" | endif

===== Commands To Know By Heart =====
^ Command ^ Effect ^
| <nowiki>^g</nowiki> | show file status information |
| ZZ | like '':wq'', but vim-specific |
^ copy'n'paste ^|
| yy | copy actual line to clipboard |
| p | paste **after** the cursor |
| P | paste **before** the cursor |
| "*p | Paste from "selection" clipboard (i.e., the regular clipboard) |
| "+p | Paste from "desktop" clipboard (i.e., what applications use to copy into or paste from) |
^ Changing Modes^|
| I | insert at beginning of line |
| A | insert at end of line |
| <nowiki>^v</nowiki> | visual block mode (selection of fields) |
^ Movement Commands ^|
| :<num> | goto line <num> |
| gg | goto first line |
| G | goto last line |
| z. | scroll actual line to the middle of the screen |
| z- | scroll actual line to the bottom of the screen |
| zRETURN | scroll actual line to the top of the screen |
| f<char> | place cursor to the next occurence of <char> in the line |
| F<char> | place cursor to the last occurence of  <char> in the line |
| { | place cursor to the beginning of the actual/last paragraph |
| } | place cursor to the end of the actual/next paragraph |
^ Searching ^|
| /<expr> | search forward for <expr> |
| ?<expr> | search backward for <expr> |
| * | search forward for the word under the cursor |
| # | search backward for the word under the cursor |
^ Windows ^|
| :sp [fname] | horizontally split window, open <fname> or actually opened file |
| :vsp [fname] | vertically split window, open <fname> or actually opened file |
| :to vsp [fname] | vertically split window, but occupy the full height |
| <nowiki>^ww</nowiki> | switch window focus |
| <nowiki>^w=</nowiki> | equal sizes of all windows |
| <nowiki>^wr</nowiki> | rotate windows |

| <nowiki>^wR</nowiki> | rotate windows (other direction) |
| <nowiki>^w_</nowiki> | maximize focused window |
^ Folding ^|
| zr | increase foldlevel by one |
| zR | set foldlevel to max (remove all foldings) |
| zm | decrease foldlevel by one |
| zM | set foldlevel to 0 (close all foldings) |
| zX | update folds, apply foldlevel |
| zx | update folds, apply foldlevel and do ''zv'' |
| zo | open fold under Cursor |
| zO | open all folds under Cursor recursively |
| zc | close fold under Cursor |
| zC | close all folds under Cursor recursively |
| zv | unfold just enough to show line in which Cursor is located |
^ Vim Help Context ^|
| <nowiki>:h <expr>^d</nowiki> | show help topics matching <expr> |
| <nowiki>^5</nowiki> | follow hyperlink  |
| <nowiki>^]</nowiki> | follow hyperlink |
| <nowiki>^t</wowiki> | go back |
| <nowiki>^o</nowiki> | go back |

===== Ranges =====
^ Example ^ Effect ^
| . | current line |
| 2,3 | all from line 2 till line 3 inclusively |
| <nowiki>^,$</nowiki> | all from beginning till end of file |
| +2,+3 | all from two lines after cursor till three lines after cursor |

===== Mappings =====
Mappings are a useful utility to define command aliases and little macros inside ''vim''.

==== Mapping Commands ====
      commands:                                 modes: ~
                                            Normal     Visual  Operator-pending ~
  :map   :noremap   :unmap   :mapclear        yes        yes        yes
  :nmap  :nnoremap  :nunmap  :nmapclear       yes         -          -
  :vmap  :vnoremap  :vunmap  :vmapclear        -         yes         -
  :omap  :onoremap  :ounmap  :omapclear        -          -         yes
  
                                            Insert  Command-line  Lang-Arg ~
  :map!  :noremap!  :unmap!  :mapclear!       yes        yes         -
  :imap  :inoremap  :iunmap  :imapclear       yes         -          -
  :cmap  :cnoremap  :cunmap  :cmapclear        -         yes         -
  :lmap  :lnoremap  :lunmap  :lmapclear       yes*       yes*       yes*
<sub>Excerpt from ''vim'' help context *map-modes*</sub>

==== Mapping Keycodes ====
The ''vim'' help context contains a list of codes for special keys:
  :help keycodes
==== Samples ====
Defining a mapping is as simple as:
  :imap try try {<Enter>} catch(Exception e) {<Enter><Enter>}<Esc>3ko
The effect can be tested in ''insert'' mode, typing ''try''.

Removal of the mapping defined above is done via:
  :iunmap try

===== cTags =====

Especially when debugging code, cTags are a wonderful tool when it comes to
manually tracing through the code flow. Creation of the tags-file is often as
simply as issuing a
  make tags
or
  ctags -R .
after that, one can jump to the definition of a code element by hitting ''^5''
or ''^[''. When the destination is not the expected one, it's helpful to check
alternative targets using '':ts'', then selecting an entry by entering the
corresponding number. Jump back using ''^t''.

==== ctags.vim ====

The script //ctags.vim// helps combining the power of cTags and vim. After
downloading it has to be placed inside one's plugin dir (e.g.
//~/.vim/plugin//).

For a quick start, the following two ex-commands have to be given to enable
the script's functionality:
<code>
:let g:ctags_statusline=1
:CTAGS
</code>
when everything was done right, the name of the function the cursor is
currently positioned at is printed in the status bar.

=== Seamless Integration in Vim ===

On my notebook, I've setup ''ctags.vim'' like so:
  * save the script as //~/.vim/plugin/ctags.vim//
  * create or edit the file //~/.vim/ftplugin/c.vim//:
<file>
let g:ctags_statusline=1
CTAGS
</file>
Now upon opening a file with suffix ''.c'', the plugin is automatically being
loaded and activated (leads to an error if no tags file was found, but nothing
fatal or disturbing).

===== Displaying Non-Printable Chars =====

Especially tabs and spaces are characters that can't be distinguished without
further help from vim. As this is often necessary (e.g. for a clean C Coding
Style), help is near:

Insert the following into your //.vimrc// to make the ''set list'' command
output more useful stuff:
<file>
" Show tabs, trailing spaces, long lines
"set list listchars=tab:>_,trail:_,extends:+ " ,eol:$
" disable it by default
set listchars=tab:>_,trail:_,extends:+ " ,eol:$
</file>

The code below adds some more invasive displaying. Not only because it's
enabled by default, but also because of the nice red colour. :-)
<file>
" show trailing spaces and spaces before tabs (this is better)
hi link localWhitespaceError Error

" match trailing spaces (being displayed right from the start)
"au Syntax * syn match localWhitespaceError /\s\+$/ display
" match trailing spaces, but not as soon as they are being typed
" au Syntax * syn match localWhitespaceError /\(\zs\%#\|\s\)\+$/ display
" same as above, but allow highlighting inside other syntax groups (comments for instance)
au Syntax * syn match localWhitespaceError /\(\zs\%#\|\s\)\+$/ display containedin=ALL

" show space before tab
au Syntax * syn match localWhitespaceError / \+\ze\t/ display containedin=ALL
</file>

===== Skeletons =====

Having skeletons (templates) when creating certain types of files is quite
easy thanks to vim's powerful scripting language:
<file>
au BufNewFile <pattern> 0r <path_to_skeleton>
</file>

For instance, having a skeleton for tex letters at //~/.vim/skel/letter.tex//:
<file>
au BufNewFile *.letter.tex 0r ~/.vim/skel/letter.tex
</file>
will insert the skeleton's content into every new file with name matching
"*.letter.tex".

===== Links =====

  * [[http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html|Graphical Cheat Sheet and tutorial]]
  * [[http://www.vim.org/scripts/script.php?script_id=610|ctags.vim script]]
  * [[http://vim.wikia.com/wiki/Accessing_the_system_clipboard|Accessing the System Clipboard]]
  * [[http://vim.wikia.com/wiki/VimTip188|Search Patterns]]
  * [[https://www.vim.org/scripts/script.php?script_id=1697|surround.vim script]]