vim_notes.txt

Things to try to use
=====================

Use character searches and text objects more.
Use [[ and ]] more.
Use marks and macros more.
Use the command window for searches and substitutions.
Use the gd command more.
Use tags.
Use c-j and c-k in fuzzyfinder.

Plugins
=======
I should consider flake8, Gundo, Subvert, YankRing, SnipMate, Ack, Tagslist
I need to learn more about fuzzyfinder's tags.

Less likely: Abolish and LustyJuggler. I should also think about using pathogen
to manage my packages.

Special-purpose: ropevim might have advantages. There are verious latex
packages. latex-suite is the standard 'big' one. Smaller ones include tex-pdf
(which only does compile, but apparently does it very nicely), tex9, and
latex-box



NOTES
=====

To change a package name or something like that in a whole codebase, try this:
    vim (or :e) **/*.py
    :argdo %s/(oldname)/(newname)/gc
    :wa [you need to write all buffers, not just the open one]
Note: you can also use :bufdo instead of :argdo.

# Go into insert mode.
i I a A r s c_ cc C o O

# edits
# Most of these accept visual mode selections, movement commands (in
# which case they go from cursor to target) or text objects.
y_ d_ Y* D yy dd p P x X J
> < gq gU (all of these take text objects or movements)
remember that c-t and c-d are insert equivs of >> and <<
u and c-r. Remember there *is* an undo tree if you need it, even if
           I'm not sure how to use it. The Gundo plugin can help.
:set paste and :set nopaste are important when using the middle mouse
    button or when using the terminal's paste while in insert mode.

# practical directory issues
----------------------------
:cd %:h changes to the current directory
:cd - changes to the previous directory
This is really good with latex: map something to do these commands
     :cd %:h
     :!pdflatex %:t (or %:p) --interaction=nonstopmode
     :cd -
  ...which would allow me to compile a .tex file in its current directory
  (which is almost always what I want to do) without changing my working
  directoy.
Note:
   the solution as given works, but isn't very good if there are compile
   errors. The 'right' solution is to replace the !pdflatex call with
   an appropriate built-in vim call so that the errors will go to the quick
   fix window. But my guess is, to handle the directory issue, I need to
   bracket that call (\ll is supposed to work with vim-latex) with the
   directory commands.
Also, I think this might work when working on test files, if I can find the
right commands (this doesn't work, but is the general idea):
    :!gnome-terminal -e ipython -c %run %:p

# text objects
:help text-objects
------------------
iw aw iW aW is as ip ap
i" a" i( a(   ...   here `(` is literal, not a `sentence` as in the movement
                    commands (/)

# movements
e E w W b B
% ( ) { } [[ ]]    ... in python, the most useful are %, { & }, and [[ & ]]
                       For reasons that aren't clear, [[ and ]] don't seem
                       to work when used with commands like d or zf.
[( ]) [{ ]}        ... in a brace-delimited language, [{ and ]} are impt.
+ - h j k l $ ^
t_ T_ f_ F_ ; ,
/___ ?___ n N * #
gg, G g(num)
gd    ...    go to local declaration of a variable (so cool!)

# scrolling: with cursor mvmnt, screen only, screen only by line, cursor only
c-f c-b c-u c-d 
zt zz zb
c-e c-y
H M L

# marks
:help marks
-----------
`(mark), '(mark) for mark or beginning of line with mark... 
`` '' for prev
m(a-z): set a local mark, only valid in this file
m(A-Z): set a global mark over all files in the vim session
'_ and `_ are movement commands. They can be used with, e.g., d y c gq > etc.
Setting a mark at one end of some block, navigating to the other end, and and
then doing (edit_command)(` or ')(mark letter).
:marks lists all marks (probably only global ones and those in the current 
                        file, that is, I assume it depends on context.)
:marks AaB lists marks A, B, and a only.
[' and ]' let you page through all lowercase marks in file
[` and ]` let you page through all uppercase marks in file
see :help delmarks for deleting marks.
----
There are several special marks other than previous. I need to read about them
in Practical Vim.


# registers (sometimes called buffers, esp in non-vim vi)
:help registers
---------------
:reg to see all registers
"(a-z) to access a register. 
specials: "" and "1 most recent deletion/yank "2 - "9 count back older 
          deletions/yanks. "0 is the most recent yank.
          "+ is the system clipboard. "% is the file name. ": is most recent
          ex command. ". is the most recent edit. "_ is the black hole, mostly
          useful if you want to delete without clobbering the current "".
          "= is best illustrated by example: "=5*5p pastes 25 after the cursor.
(register)(yank or delete command) will store something in the register.
q(register) will begin a macro, that is, all keystrokes go into the register
            until you hit q again.
(register)(p or P) will paste.
    Note: p/P's behavior depends on whether a register is full- or partial- 
          line. I'm still unclear on precisely what determines this, but I 
          do know that yy, dd, or anything on a Shift-v selection
          generate line register.
@(register) executes a register. @@ will re-execute the most recent macro.
C-r will insert the contents of a register in insert mode.
---
Note that there are 2 mostly distinct use cases, text and macros. So typically,
    we would use [y/d and p/P/C-r], or [q and @], and not mix them. Also note
    that the syntax differs: the register precedes text stuff (except C-r)
    but comes after q and @.
A-Z refer to the same registers. The difference is that if you copy or record
    a macro with a capital register, vim appends rather than replaces.

# basic ex commands
:w :e :x :=
(range)m(lineno)    and   (range)t(line)   will [Move] or [copy To]
If you want to use buffers for ex copy/paste command, you can:
    (linerange)ya x     ...   yanks to buffer x
    (lineno)pu x        ...   puts (pastes) buffer x after line (linenu)
:(range)s/pattern/replacement/[gc]
:g/pattern/(command)  ... search for pattern to get a line range, then
                          run (command) on that line range, e.g.,
                          -g/def/nu gives line numbers of lines with 'def'.
                          -g/patt/s/old/new would sub (the first case of) old 
                           for new on every line containing patt.
:(lineno)r (filename)   ...  reads in a file after (lineno) of current buffer.
`|` is the command concatenator (it behaves like ; in shell, NOT like |)


# line numbers/ranges
Basic line ranges look like 23,56
For any command that takes a range or number, a blank means current line.
    In a line range, leaving one side of the `,` blank also means current line.
Special line symbols include . for current line, $ for last line, 0 for the
    beginning of file (1 works just as well some of the time, but you need 0
    if you want to paste something in front of line 1). `%` means `0,$`.
Relative lines are given by +(num) and -(num), they are relative to current 
    line. + and - by themselves mean +1 and -1. Remember that you can omit
    the `.` if that is one side of your line range.


# Shell commands
! escapes to the shell, :sh opens a shell *but* be aware they don't read 
    bashrc so aliases aren't available.
the ConqueTerm plugin fixes this, although it still isn't the greatest shell,
    and the color interaction is a problem (that might be fixable)
Generally it's preferable to use built-in commands like :make if you can.
    If theres no built-in and you use a shell command regularly, it might be
    worth creating a custom vim command to call it.
Keep in mind that many shell tools, like git, have vim plugins like Fugitive
    available so you can interact with them.
Shell tools can be used inside vim for text purpose, in (loosely) two ways:
    - Reading text in: example is :r(lineno) !date, which reads in the date
      after the line given (by default, the current line). In this case,
      the tool's stdin is determined by your call, but stdout is dumped in
      the current buffer after the indicated line.
    - Altering text: (linerange)!sort, for example, would treat the lines
      in the linerange as stdin, and would replace that block with the output
      of sort in the current buffer.
    - This is likely to be error-prone, but you can undo any mistakes. If I
      learn sed and awk well, there's some chance that I could find these
      features handy. Hypothetically I could also write custom python code
      and then use this, although presumably using vim-python would be better.


# Folding
:help folding  ... also, there's a vimcast on folding
-----------------------------------------------------
If you execute a command like dd or >> on a fold, all linea are affected.
methods include manual, indent, expr, syntax, marker
   to change, :set foldmethod=(method)
   you might need to do :set foldenable
   Here I discuss only manual, since most commands are the same.
to make a fold, do (count)zF or zf(motion/text object) or do it from visual.
zj zk ]z [z : go to next or prev fold, go to top/bottom of current fold
zc zo za zd : open, close, toggle, or delete one fold
zC zO zA zD : open, close, toggle, or delete folds recursively
zr zm zR zM : decreMent or incRement the fold level by 1 or to the min/max
zE zi : eliminate all folds, toggle foldenable
zN zn : these affect foldenable, but I'm not sure how they work.


# Indentation and Syntax
LTVVE is not very useful, and the help pages would be good only if I had the 
big picture. I need to read a blog on this to really get it.


# Completion
:help completion
----------------
In insert mode, C-x enters completion mode. When there, do
C-l C-n for line or keywork completionbased on current session
C-k C-t C-s for dictionary thesaurus or spelling correction
C-i C-] C-f for included files, tags, and filenames
C-u C-o for user-defined or omni
C-v for Vim command completion (use this in ex mode)
C-d for C macro completion (really only useful in C)


# Tags
:help tags
----------
:ta :ts :tj :pta :pts :ptj :sta :sts :stj
:tp and :tn will cycle through matches if you called :ta and got wrong one.
:tags has 2 meanings: command to look at stack, and the environment variable
                      saying where to look for tags files.
                      (e.g., :set tags=file/path/one,path2)
C-] or g<LeftMouse> and C-t work in vi mode


# windows and tabs
:sp :vs
C-w plus... o, c, h, j, k, l, t, b, =, >, <, +, - 
(Using the mouse for resizing and window switching is not a bad idea).
:tabnew :tabn :tabp :tabc
:tabm :tabm0 :tabm (nu) move a tab to end, start, (number)th.
C-Pgup and C-pgdn work in place of :tabn and :tabp


# buffers and the jump list
:ls :bu (number) :bd :BD :bw :BW :bn :bp
Special buffers:
    command line window (q: q/ and q? take you here)
    quickfix command errors (:cwindow)
    quickfix locations (:lwindwo)
    help buffers (:help [topic])
    previw window (closed by :pc)


# quickfix (c) and location (l) windows
The quickfix window is used by vim's integration with make, pyflakes, flake8,
and some others. It is tied to individual buffers. The location window has 
parallel commands, but I'm not sure what it is used for. Vimgrep also uses this
(there's a vimcast on it) but I haven't figured it out yet.
:help quickfix
------------
:cw :lw :ccl :lcl     ... open and close quickfix and location windows.
:cn :lne :cp :lp      ... previous and next error/location
:col :cnew :lol :lnew ... go to older or newer error. Not sure what this means.
<CR> C-w <Cr>         ... goto error/location (with new window if C-w)


# Patterns
:help pattern.txt
LTVAVE pp 71-81 have vi rules, pp 169-170 have vim rules
LTVAVE pp 81-94 has examples
http://vimregex.com/ has a chapter-length discussion
# search patterns
[xyz] matches x, y, or z
[[:alpha:][:digit:]] and [[:alnum:]] will both match alphanumeric
[[:lower:][:upper:]] will match any letter
[[:graph:]] matches any printable character (non-whitespace)
. matches any character
^, & force the following/preceding symbol to be at the start/end of a line
\<, \> force the following/preceding symbol to be at the start/end of a word
* after any character or matcher matches any number of repeats (so
    `.*` behaves like the shell's `*`
~ refers to the last-used search pattern.
Note that [] are special, but (), <>, and {} are not (by default)
# vim only symbols not available in vi
\s matches whitespace (it's like [[:blank:]])
\S matches all others (it's like [[:graph:]])
\r matches carriage returns for multi-line edits
\| does alternations, like /bid\|ask
* can be applied to something between `\(` and `\)`
\{3} is like * except it matches exactly 3 (no \ is needed before the })
\{3,7} would match anything between 3 and 7 matches of prev symbol
# search or replacement patterns
\ : leader for some special symbols, escapes all others
\1, \2, ..., \9 : matches place-held patterns (see `\(` and `\)`).
    so you can use these in the search pattern if you want to look for where 
    the same pattern occcurs in 2 spots in a line, and you can also use them 
    in replacements.
# replacement patterns
\u and \l : the following letter will be upper/lower cased (useful in 
    combo with `\1`, etc)
\U and \L, \e or \E: upper or lower case everything until the \e or \E.
    If there is no \e or \E, it upper or lower cases to the end.
& matches the entire search pattern
# very magic and very no magic
\v makes it unneceassary to put the \ in front of non-letter and non-number
    special symbols (but you do now need a \ to escape them). This behavior
    is more typical of regexp engines, e.g. the Python engine.
\V makes it so any special character has to be escaped except for \ itself
    and either / (if searching forward) or ? (if backward). All others are
    taken literally.