USR_02

*usr_02.txt*    For IdeaVIM version 0.12.0.  Last change: 2006 Nov 12

                     IdeaVIM USER MANUAL - by Rick Maddy

                            The first steps in IdeaVIM


This chapter provides just enough information to edit a file with IdeaVIM.  Not
well or fast, but you can edit.  Take some time to practice with these
commands, they form the base for what follows.

|02.1|  Running IdeaVIM for the First Time
|02.2|  Inserting text
|02.3|  Moving around
|02.4|  Deleting characters
|02.5|  Undo and Redo
|02.6|  Other editing commands
|02.7|  Getting out
|02.8|  Finding help

     Next chapter: |usr_03.txt|  Moving around
 Previous chapter: |usr_01.txt|  About the manuals
Table of contents: |usr_toc.txt|

*02.1*  Running IdeaVIM for the First Time

Since IdeaVIM runs within IDEA you run IdeaVIM by starting IDEA.

*02.2*  Inserting text

The IdeaVIM editor is a modal editor.  That means that the editor behaves
differently, depending on which mode you are in.  The two basic modes are
called Normal mode and Insert mode.  In Normal mode the characters you type
are commands.  In Insert mode the characters are inserted as text.
   Since you have just started IdeaVIM it will be in Normal mode.  To start Insert
mode you type the "i" command (i for Insert).  Then you can enter
the text.  It will be inserted into the file.  Do not worry if you make
mistakes; you can correct them later.  To enter the following programmer's
limerick, this is what you type:

        iA very intelligent turtle
        Found programming UNIX a hurdle

After typing "turtle" you press the <Enter> key to start a new line.  Finally
you press the <Esc> key to stop Insert mode and go back to Normal mode.  You
now have two lines of text in your editor:

        +---------------------------------------+
        |A very intelligent turtle              |
        |Found programming UNIX a hurdle        |
        |~                                      |
        |~                                      |
        |                                       |
        +---------------------------------------+


WHAT IS THE MODE?

To be able to see what mode you are in, type this command:

        :set showmode

You will notice that when typing the colon IdeaVIM moves the cursor to the last
line of the window.  That's where you type colon commands (commands that start
with a colon).  Finish this command by pressing the <Enter> key (all commands
that start with a colon are finished this way).
   Now, if you type the "i" command IdeaVIM will display VIM - INSERT in the
status bar.  This indicates you are in Insert mode.

        +---------------------------------------+
        |A very intelligent turtle              |
        |Found programming UNIX a hurdle        |
        |~                                      |
        |~                                      |
        |VIM - INSERT                           |
        +---------------------------------------+

If you press <Esc> to go back to Normal mode the last line will be made blank.


GETTING OUT OF TROUBLE

One of the problems for Vim novices is mode confusion, which is caused by
forgetting which mode you are in or by accidentally typing a command that
switches modes.  To get back to Normal mode, no matter what mode you are in,
press the <Esc> key.  Sometimes you have to press it twice.  If Vim beeps back
at you, you already are in Normal mode.

*02.3*  Moving around

After you return to Normal mode, you can move around by using these keys:

        h   left                                                *hjkl*
        j   down
        k   up
        l   right

At first, it may appear that these commands were chosen at random.  After all,
who ever heard of using l for right?  But actually, there is a very good
reason for these choices: Moving the cursor is the most common thing you do in
an editor, and these keys are on the home row of your right hand.  In other
words, these commands are placed where you can type them the fastest
(especially when you type with ten fingers).

        Note:
        You can also move the cursor by using the arrow keys.  If you do,
        however, you greatly slow down your editing because to press the arrow
        keys, you must move your hand from the text keys to the arrow keys.
        Considering that you might be doing it hundreds of times an hour, this
        can take a significant amount of time.
           Also, there are keyboards which do not have arrow keys, or which
        locate them in unusual places; therefore, knowing the use of the hjkl
        keys helps in those situations.

One way to remember these commands is that h is on the left, l is on the
right and j points down.  In a picture:

                       k
                   h     l
                     j

The best way to learn these commands is by using them.  Use the "i" command to
insert some more lines of text.  Then use the hjkl keys to move around and
insert a word somewhere.  Don't forget to press <Esc> to go back to Normal
mode.  The |vimtutor| is also a nice way to learn by doing.

For Japanse users, Hiroshi Iwatani suggested using this:

                        Komsomolsk
                            ^
                            |
           Huan Ho      <--- --->  Los Angeles
        (Yellow river)      |
                            v
                          Java (the island, not the programming language)

*02.4*  Deleting characters

To delete a character, move the cursor over it and type "x".  (This is a
throwback to the old days of the typewriter, when you deleted things by typing
xxxx over them.)  Move the cursor to the beginning of the first line, for
example, and type xxxxxxx (seven x's) to delete "A very ".  The result should
look like this:

        +---------------------------------------+
        |intelligent turtle                     |
        |Found programming UNIX a hurdle        |
        |~                                      |
        |~                                      |
        |                                       |
        +---------------------------------------+

Now you can insert new text, for example by typing:

        iA young <Esc>

This begins an insert (the i), inserts the words "A young", and then exits
insert mode (the final <Esc>).  The result:

        +---------------------------------------+
        |A young intelligent turtle             |
        |Found programming UNIX a hurdle        |
        |~                                      |
        |~                                      |
        |                                       |
        +---------------------------------------+


DELETING A LINE

To delete a whole line use the "dd" command.  The following line will
then move up to fill the gap:

        +---------------------------------------+
        |Found programming UNIX a hurdle        |
        |~                                      |
        |~                                      |
        |~                                      |
        |                                       |
        +---------------------------------------+


DELETING A LINE BREAK

In Vim you can join two lines together, which means that the line break
between them is deleted.  The "J" command does this.
   Take these two lines:

        A young intelligent 
        turtle 

Move the cursor to the first line and press "J":

        A young intelligent turtle 

*02.5*  Undo and Redo

Suppose you delete too much.  Well, you can type it in again, but an easier
way exists.  The "u" command undoes the last edit.  Take a look at this in
action: After using "dd" to delete the first line, "u" brings it back.
   Another one: Move the cursor to the A in the first line:

        A young intelligent turtle 

Now type xxxxxxx to delete "A young".  The result is as follows:

         intelligent turtle 

Type "u" to undo the last delete.  That delete removed the g, so the undo
restores the character.

        g intelligent turtle 

The next u command restores the next-to-last character deleted:

        ng intelligent turtle 

The next u command gives you the u, and so on:

        ung intelligent turtle 
        oung intelligent turtle 
        young intelligent turtle 
         young intelligent turtle 
        A young intelligent turtle 

        Note:
        If you type "u" twice, and the result is that you get the same text
        back, you have Vim configured to work Vi compatible.  Look here to fix
        this: |not-compatible|.
           This text assumes you work "The Vim Way".  You might prefer to use
        the good old Vi way, but you will have to watch out for small
        differences in the text then.


REDO

If you undo too many times, you can press CTRL-R (redo) to reverse the
preceding command.  In other words, it undoes the undo.  To see this in
action, press CTRL-R twice.  The character A and the space after it disappear:

        young intelligent turtle 

*02.6*  Other editing commands

IdeaVIM has a large number of commands to change the text.  See |Q_in| and below.
Here are a few often used ones.


APPENDING

The "i" command inserts a character before the character under the cursor.
That works fine; but what happens if you want to add stuff to the end of the
line?  For that you need to insert text after the cursor.  This is done with
the "a" (append) command.
   For example, to change the line

        and that's not saying much for the turtle. 
to
        and that's not saying much for the turtle!!! 

move the cursor over to the dot at the end of the line. Then type "x" to
delete the period.  The cursor is now positioned at the end of the line on the
e in turtle.  Now type

        a!!!<Esc>

to append three exclamation points after the e in turtle:

        and that's not saying much for the turtle!!! 


OPENING UP A NEW LINE

The "o" command creates a new, empty line below the cursor and puts Vim in
Insert mode.  Then you can type the text for the new line.
   Suppose the cursor is somewhere in the first of these two lines:

        A very intelligent turtle 
        Found programming UNIX a hurdle 

If you now use the "o" command and type new text:

        oThat liked using Vim<Esc>

The result is:

        A very intelligent turtle 
        That liked using Vim 
        Found programming UNIX a hurdle 

The "O" command (uppercase) opens a line above the cursor.


USING A COUNT

Suppose you want to move up nine lines.  You can type "kkkkkkkkk" or you can
enter the command "9k".  In fact, you can precede many commands with a number.
Earlier in this chapter, for instance, you added three exclamation points to
the end of a line by typing "a!!!<Esc>".  Another way to do this is to use the
command "3a!<Esc>".  The count of 3 tells the command that follows to triple
its effect.  Similarly, to delete three characters, use the command "3x".  The
count always comes before the command it applies to.

*02.7*  Getting out

This information does not apply to IdeaVIM.

*02.8*  Finding help

Everything you always wanted to know can be found in the IdeaVIM help files.
Don't be afraid to ask!
   To get generic help use this command:

        :help

You could also use the first function key <F1>.  If your keyboard has a <Help>
key it might work as well.
   If you don't supply a subject, ":help" displays the general help window.

As you read the help text, you will notice some text enclosed in vertical bars
(for example, |help|).  This indicates a hyperlink.  If you position the mouse
cursor anywhere between the bars and click the left mouse button, the help
system takes you to the indicated subject. (For reasons not discussed here,
the Vim terminology for a hyperlink is tag.  So left-click jumps to the location
of the tag given by the word under the cursor.)
   After a few jumps, you might want to go back. Mouse click on the < button to
go back to the preceding position. Mouse click on the > button to go forward
again.
   At the top of the help screen, there is the notation *help.txt*.  This name
between "*" characters is used by the help system to define a tag (hyperlink
destination).

To get help on a given subject, use the following command:

        :help {subject}

To get help on the "x" command, for example, enter the following:

        :help x

To find out how to delete text, use this command:

        :help deleting

To get a complete index of all Vim commands, use the following command:

        :help index

When you need to get help for a control character command (for example,
CTRL-A), you need to spell it with the prefix "CTRL-".

        :help CTRL-A

The IdeaVIM editor has many different modes.  By default, the help system displays
the normal-mode commands.  For example, the following command displays help
for the normal-mode CTRL-H command:

        :help CTRL-H

To identify other modes, use a mode prefix.  If you want the help for the
insert-mode version of a command, use "i_".  For CTRL-H this gives you the
following command:

        :help i_CTRL-H

The IdeaVIM editor has a number of options that enable you to configure and
customize the editor.  If you want help for an option, you need to enclose it
in single quotation marks.  To find out what the 'number' option does, for
example, use the following command:

        :help 'number'

The table with all mode prefixes can be found here: |help-context|.

Special keys are enclosed in angle brackets. To find help on the up-arrow key
in Insert mode, for instance, use this command:

        :help i_<Up>

If you see an error message that you don't understand, for example:

        E37: No write since last change (use ! to override) 

You can use the error ID at the start to find help about it:

        :help E37

Next chapter: |usr_03.txt|  Moving around

Copyright: see |manual-copyright|