.. @+leo-ver=5-thin
.. @+node:ekr.20100805165051.7172: * @file vimBindings.txt
.. @@language rest
.. @@tabwidth -4

.. @+at @rst-options
..  call_docutils=False
..  code_mode=False
..  generate_rst=True
..  http_server_support = False
..  show_organizer_nodes=True
..  show_headlines=True
..  show_leo_directives=True
..  stylesheet_path=..\doc
..  write_intermediate_file = True
..  verbose=True
.. @@c

.. @+all
.. @+node:TL.20080804095315.2: ** @rst html\vimBindings.html
###########################
Using Vim Bindings with Leo
###########################

This chapter describes Leo's vim-like bindings, including how to install them.

.. contents::
    :depth: 3
.. @+node:TL.20080804095315.4: *3* Installing vim bindings
Place a copy of the "@keys Vim bindings" node and its sub-nodes,
located in the leoSettings.leo file, under the "@settings" node
in the myLeoSettings.leo file

The same procedure is performed to update to a new version.

Note: Place any local customized key bindings in a separate
"@keys My Vi" node in the myLeoSettings.leo file to prevent
them from being overwritten when updating to a new version.
.. @+node:TL.20080804095315.5: *3* General commands
The following commands are always available.

State change commands::

    i           Change state to insert from command state
    Esc         Change state to command from insert state
    Ctrl-[      Same as ESC

Save/Exit/Quite commands::

    :e          Revert
    :w<return>  Save '.leo' file
    :wq<return> Save '.leo' file and quit Leo
    :q<return>  Quit Leo   (Leo will prompt if file not saved)
    ZZ          Save leo file and exit

Undo/Redo commands::

    u           Undo previous command
    Ctrl-r      Redo previous command


Search options::

    Ctrl-/      Prompt for option to change
                Options:
                    a   Search all nodes (also <cr> key)
                    h   Toggle headline search
                    b   Toggle body search
                    m   Toggle marking of nodes (specify sub-option)
                        f   Toggle marking of nodes with found text
                        c   Toggle marking of nodes with changed text
                            (only supported with 'Alt-/', 'Alt-p')
                    r   Toggle regex matches
                        ('/' key turns off regex. 'n' key uses regex if turned on)

    Note: Whether a search is limited to node's body or the node's sub-outline
          is determined by which pane has focus when search text specified.
          (See "Find text commands:" sub-sections in Outline/Body Pane sections)

Miscellaneous commands::

    Tab         Toggle focus between Outline and Body pane
    =           Simulate double-click on current node's icon box
    Alt-G       Go to specified line number (relative to external file)
    Ctrl-:      Enter Leo's command line
.. @+node:TL.20080804095315.6: *3* Body pane commands
Move cursor commands::

    h           Go back 1 character
       LtArrow  Mapped to "h" for convenience
    j           Go down 1 line
       DnArrow  Mapped to "j" for convenience
    k           Go up 1 line
       UpArrow  Mapped to "k" for convenience
    l           Go forward 1 character
       RtArrow  Mapped to "l" for convenience

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Goto beginning of current line
    ^           Go to 1st non-blank character on current line
    $           Goto end of current line

    %           Go to matching bracket

    (           Go to beginning of current sentence
    )           Go to beginning of next sentence
    {           Go to beginning of current paragraph
    }           Go to beginning of next paragraph

    gg          Go to the first line (Cursor at column 1)
    G           Go to the last line  (Cursor at column 1)

Mark commands::

    m<label>    Assign cursor location to a single character label
    `<label>    Go to location associated with label

      Note: Only character count is tracked. Any inserts or deletes will change mark.
          Mark's are not node specific; `<label> will go to location in current node.

Select commands::

    Ctrl-v      Toggle text select mode (Vim's "visual" mode)
       V        Mapped to 'Ctrl-v' for convenience (Should toggle line select)

Insert/substitute commands::

    a           Insert at cursor
    i           Mapped to "a" until "cursor on a character" supported
    A           Insert at end of line
    I           Insert at first non-space
    o           Open new line below current line
    O           Open new line above current line
    R           Overwrite text
    s           Substitute character (Delete character, enter insert state)
    S           Substitute line (Delete line, enter insert state)

Change commands::

    C           Change to end of line
    cc          Change all of current line
    cw          Change to end of word
    cb          Change to beginning of word
    c)          Delete to end of sentence
    c(          Delete to beginning of sentence
    c}          Delete to end of paragraph
    c{          Delete to beginning of paragraph
    c%          Change from current bracket type its matching bracket type
    ct<char>    Selects forward to <char> (follow with 'i' to change selection)
    cT<char>    Selects backward to <char> (follow with 'i' to change selection)
    c<cr>       Change selected text

Delete commands::

    x           Delete next character
    delete      Delete next character
    D           Delete to the end of the current line
    dd          Delete current line
    dw          Delete to end of word
    db          Delete to beginning of word
    d)          Delete to end of sentence
    d(          Delete to beginning of sentence
    d}          Delete to end of paragraph
    d{          Delete to start of paragraph
    d%          Delete from current bracket type to its apposing bracket
    dt<ch>      Delete to character (not limited to current line)
    d<cr>       Delete selected text

    J           Join next line to end of current line (deletes carriage return)

Yank text commands::

    Y           Yank to end of line
    yy          Yank line
    yw          Yank to beginning of next word
    yb          Yank to beginning of current word
    y)          Yank to end of sentence
    y(          Yank to beginning of sentence
    y}          Yank to end of paragraph
    y{          Yank to beginning of paragraph
    y%          Yank from current bracket type to its opposing bracket
    yt<char>    Select forward to <char>  (use 'y<cr>' to yank selection)
    yT<char>    Select backward to <char> (use 'y<cr>' to yank selection)
    y<cr>       Yank selected text (Vim uses 'y' in visual mode)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node's body text
    ?           Search backward within current node's body text
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" in General Commands section to change options.

Replace [and find next] commands::

    Commands using Paste buffer (clipboard)
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.
    Ctrl-p      Paste then find next match
                Note: Use 'pn' instead of 'Ctrl-p' in headlines (Leo limitation)
                      Command will continue to paste when match no longer found.

    Commands prompting for replace string
    Note: Scope and direction taken from last use of '/','?' or 'Ctrl-/'(scope only)
    Alt-/       Prompt for search & replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Indent/Unindent line commands::

    >>          Indent the current line
    >)          Indent to the end of sentence
    >(          Indent to the beginning of sentence
    >}          Indent to the end of paragraph
    >{          Indent to the beginning of paragraph
    >g          Indent to the start of buffer
    >G          Indent to the end of buffer

    <>          Unindent the current line
    <)          Unindent to the end of sentence
    <(          Unindent to the beginning of sentence
    <}          Unindent to the end of paragraph
    <{          Unindent to the beginning of paragraph
    <g          Unindent to the start of buffer
    <G          Unindent to the end of buffer

Format commands::

    gqap        Split long line into separate lines
    gwap        Split long line into separate lines
    gqq         Split long line into separate lines
    gww         Split long line into separate lines

    Note: 'gwap' and 'gww' should not move cursor but do.

Scroll commands::

    Ctrl-b      Scroll text up by pane's height
    Ctrl-f      Scroll text down by pane's height
       Ctrl-y   Mapped to Ctrl-b until scroll up one line is supported
       Ctrl-e   Mapped to Ctrl-f until scroll down one line is supported
       Ctrl-u   Mapped to Ctrl-b until scroll up half a pane height is supported
       Ctrl-d   Mapped to Ctrl-f until scroll down half a pane height is supported

Window commands::

    Ctrl-w s    Open another view into current node's body (Vim: Split window)
       Ctrl-w n Mapped to "Ctrl-w s" (Vim: New buffer in split window)
    Ctrl-w w    Switch to next view (Vim: Go to up/left window w/wrapping)
       Ctrl-w p Mapped to "Ctrl-w w" (Vim: Cycle through windows)
       Ctrl-w k Mapped to "Ctrl-w w" (Vim: Go to window above current window)
       Ctrl-w j Mapped to "Ctrl-w w" (Vim: Go to window below current window)
    Ctrl-w c    Close current view in body pane (Vim: Close current window)
       Ctrl-w q Mapped to "Ctrl-w c" (Vim: Quit current window)

Node commands::

    Go to another node while focus remains in the body pane.
    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level
       Ctrl-DnArrow    Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow    Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow    Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow    Mapped to "Ctrl-l" for convenience
.. @+node:TL.20080804095315.7: *3* Outline commands
The following commands are supported when in a headline's command mode.

State change commands::

    Ctrl-i      Change state to command from grayed state
    return      Change state to command from insert state
    Ctrl-]      Change state to grayed from command state

Cursor movement commands::

    h           Go to previous character
       LtArrow  Mapped to 'h' for convenience
    l           Go to next character
       RtArrow  Mapped to "l" for convenience

    Note: 'j' and 'k' will scroll the buffer contents up and down;
          leaving the focus in the outline pane.

    w           Go to beginning of next word
       W        Mapped to "w" until "stop after blank characters" supported
    b           Go to beginning of current/previous word
       B        Mapped to "b" until "stop at blank character" supported
    e           Go to end of current/next word
       E        Mapped to "e" until "stop at blank character" supported

    Note: Move by word commands stop at non-alpha characters

    |           Go to beginning of line
    ^           Go to beginning of line
    $           Go to end of line

    %           Go to matching bracket

Edit commands::

    x           Delete next character
    delete      Delete next character
    dd          kill-line

    s           Select current character

    v           Toggle text select mode (issue cursor movement commands)
    y<return>   Yank selected text

    C           Select to end of line (follow with 'i' to change text)
    cc          Delete line (follow with 'i' to change text)

    D           Select to end of line (follow with 'x' to delete text)
    dd          Delete line

    Y           Select to end of line (follow with 'y<return>' to yank text)
    yy          Select line (follow with 'y<return>' to yank text)

Find character commands::

    f           Find next occurrence of user specified character
    F           Find previous occurrence of user specified character

Find text commands::

    /           Search forward within current node and its subnodes
    n           Find next (same scope, same direction)
    N           Find next (same scope, other direction)

    Note: See "Search options" section above to change options using 'Ctrl-/'

Replace [and find next] commands::

    Commands that use Paste buffer (clipboard)
    Note: Paste-then-search command not possible in headlines (Use 'pn')
    P           Paste text before cursor.
    p           Mapped to "P" until character based cursor supported.

    Commands that prompt for the replace string
    Alt-/       Prompt for search & replace string
    Alt-p       Replace then search (use after Alt-/)
                Note: Works in headlines and body panes.
                      Doesn't paste unless last search found a match.

Node edit commands::

    o           Insert node after current node

    Ctrl-x      Delete current node
    Ctrl-c      Yank current node
    Ctrl-v      Paste current node

Node goto commands::

    G           Go to the outline's last node
    gg          Go to the outline's first node

    Ctrl-j      Go to next visible node
    Ctrl-k      Go to previous visible node
    Ctrl-h      Hide sub-nodes or, if hidden, go up 1 level
    Ctrl-l      Display sub-nodes or, if displayed, go down 1 level

       DnArrow  Mapped to "Ctrl-j" for convenience
       UpArrow  Mapped to "Ctrl-k" for convenience

       Ctrl-DnArrow Mapped to "Ctrl-j" for convenience
       Ctrl-UpArrow Mapped to "Ctrl-k" for convenience
       Ctrl-LtArrow Mapped to "Ctrl-h" for convenience
       Ctrl-RtArrow Mapped to "Ctrl-l" for convenience

Node move commands::

    Ctrl-Shift-k    Move node down
    Ctrl-Shift-h    Move node left
    Ctrl-Shift-l    Move node right
    Ctrl-Shift-j    Move node up

       Ctrl-Shift-DnArrow    Mapped to "Ctrl-Shift-k" for convenience
       Ctrl-Shift-LtArrow    Mapped to "Ctrl-Shift-h" for convenience
       Ctrl-Shift-RtArrow    Mapped to "Ctrl-Shift-l" for convenience
       Ctrl-Shift-UpArrow    Mapped to "Ctrl-Shift-j" for convenience

Node mark commands::

    m           Toggle node mark
    Ctrl-m      Go to next marked node
    Alt-m       Clear all marked nodes

Node clone commands::

    t           Clone the current node (transclude)
    Ctrl-t      Go to next clone of current node

Outline scroll commands::

   Ctrl-y       Scroll outline up one line
   Ctrl-e       scroll outline down one line
   Ctrl-u       Scroll outline up one half page
   Ctrl-d       scroll outline down one half page
   Ctrl-b       Scroll outline up one page
   Ctrl-f       scroll outline down one page

.. @+node:TL.20080804095315.8: *3* Commands not supported
Notable missing editing commands::

    t<char>     Move cursor to character before specified character
    r           Replace a single character with a single character
    0           Go to 1st column in current line (Use '|' instead)
    bksp        Move one character to the left
    ~           Toggle character's case
    .           Repeat last editing command
    ;           Repeat last cursor movement command
    <n><cmd>    Perform command 'n' number of times
    <cmd><n><object>    Perform the command on the n'th or up to the n'th object

Notable missing body pane commands::

    <num>G      Go to specified line number
    z<movement> Slide buffer to put current line at top/middle/bottom of pane
    '<command>  Go to line of last edit, jump, ...
    `<command>  Go to character of last edit, jump, ...
.. @+node:TL.20080804095315.9: *3* Avoiding changes to 'tag' files
If you use the open-with plugin to open node text in Vim and your Vim's "tag"
file refers to external files then there is a risk that a external file that is
initially displayed via the "tag" command" in Vim is accidentally edited and
saved from the external Vim editor while your Leo session still contains the
external file's original text that may later recreate the original external file
during a Leo save operation (overwriting the changes saved from the Vim editor).

To prevent this problem, modifications to external files can be avoided by using
Vim's "modeline" feature to disable editing of external files.

Vim's "modeline" feature scans each loaded buffer for text at the top or bottom
of the file containing " vim:" followed by a series of Vim options. The text is
usually embedded within a comment. The following example prevents modifications
to a buffer in a Python file::

    # vim:noma (A space is required between the '#' and "vim:noma")

If this line is placed in a separate Leo node at the top or bottom of the list
of nodes under a external file node (ex: @file) then any external file saved and
then later loaded into Vim will, by default, not be modifiable. If a derived
file does need to be edited then modifications can be re-enabled on a
file-by-file basis by issuing Vim's ":ma" command while viewing the derived
file.

The number of lines that Vim checks at the top and bottom of the buffer is
configurable. The following Vim command must be placed in the vimrc file to
allow for Leo's trailing sentinel lines::

    set modelines=8

Issue the ":help modeline" command within Vim for the more information about
modelines.
.. @-all
.. @-leo
