summaryrefslogtreecommitdiff
path: root/runtime/doc/usr_02.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_02.txt')
-rw-r--r--runtime/doc/usr_02.txt504
1 files changed, 504 insertions, 0 deletions
diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt
new file mode 100644
index 000000000..7d3206b66
--- /dev/null
+++ b/runtime/doc/usr_02.txt
@@ -0,0 +1,504 @@
+*usr_02.txt* For Vim version 7.0aa. Last change: 2004 Jun 08
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ The first steps in Vim
+
+
+This chapter provides just enough information to edit a file with Vim. 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 Vim 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 Vim for the First Time
+
+To start Vim, enter this command: >
+
+ gvim file.txt
+
+In UNIX you can type this at any command prompt. If you are running Microsoft
+Windows, open an MS-DOS prompt window and enter the command.
+ In either case, Vim starts editing a file called file.txt. Because this
+is a new file, you get a blank window. This is what your screen will look
+like:
+
+ +---------------------------------------+
+ |# |
+ |~ |
+ |~ |
+ |~ |
+ |~ |
+ |"file.txt" [New file] |
+ +---------------------------------------+
+ ('#" is the cursor position.)
+
+The tilde (~) lines indicate lines not in the file. In other words, when Vim
+runs out of file to display, it displays tilde lines. At the bottom of the
+screen, a message line indicates the file is named file.txt and shows that you
+are creating a new file. The message information is temporary and other
+information overwrites it.
+
+
+THE VIM COMMAND
+
+The gvim command causes the editor to create a new window for editing. If you
+use this command: >
+
+ vim file.txt
+
+the editing occurs inside your command window. In other words, if you are
+running inside an xterm, the editor uses your xterm window. If you are using
+an MS-DOS command prompt window under Microsoft Windows, the editing occurs
+inside this window. The text in the window will look the same for both
+versions, but with gvim you have extra features, like a menu bar. More about
+that later.
+
+==============================================================================
+*02.2* Inserting text
+
+The Vim 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 Vim 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 Vim window:
+
+ +---------------------------------------+
+ |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 Vim 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 Vim will display --INSERT-- at the bottom
+of the window. This indicates you are in Insert mode.
+
+ +---------------------------------------+
+ |A very intelligent turtle |
+ |Found programming UNIX a hurdle |
+ |~ |
+ |~ |
+ |-- 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 Japanese 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 ~
+
+There's a special version of the undo command, the "U" (undo line) command.
+The undo line command undoes all the changes made on the last line that was
+edited. Typing this command twice cancels the preceding "U".
+
+ A very intelligent turtle ~
+ xxxx Delete very
+
+ A intelligent turtle ~
+ xxxxxx Delete turtle
+
+ A intelligent ~
+ Restore line with "U"
+ A very intelligent turtle ~
+ Undo "U" with "u"
+ A intelligent ~
+
+The "U" command is a change by itself, which the "u" command undoes and CTRL-R
+redoes. This might be a bit confusing. Don't worry, with "u" and CTRL-R you
+can go to any of the situations you had.
+
+==============================================================================
+*02.6* Other editing commands
+
+Vim 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
+
+To exit, use the "ZZ" command. This command writes the file and exits.
+
+ Note:
+ Unlike many other editors, Vim does not automatically make a backup
+ file. If you type "ZZ", your changes are committed and there's no
+ turning back. You can configure the Vim editor to produce backup
+ files, see |07.4|.
+
+
+DISCARDING CHANGES
+
+Sometimes you will make a sequence of changes and suddenly realize you were
+better off before you started. Not to worry; Vim has a
+quit-and-throw-things-away command. It is: >
+
+ :q!
+
+Don't forget to press <Enter> to finish the command.
+
+For those of you interested in the details, the three parts of this command
+are the colon (:), which enters Command-line mode; the q command, which tells
+the editor to quit; and the override command modifier (!).
+ The override command modifier is needed because Vim is reluctant to throw
+away changes. If you were to just type ":q", Vim would display an error
+message and refuse to exit:
+
+ E37: No write since last change (use ! to override) ~
+
+By specifying the override, you are in effect telling Vim, "I know that what
+I'm doing looks stupid, but I'm a big boy and really want to do this."
+
+If you want to continue editing with Vim: The ":e!" command reloads the
+original version of the file.
+
+==============================================================================
+*02.8* Finding help
+
+Everything you always wanted to know can be found in the Vim 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.
+The creators of Vim did something very clever (or very lazy) with the help
+system: They made the help window a normal editing window. You can use all
+the normal Vim commands to move through the help information. Therefore h, j,
+k, and l move left, down, up and right.
+ To get out of the help window, use the same command you use to get out of
+the editor: "ZZ". This will only close the help window, not exit Vim.
+
+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
+cursor anywhere between the bars and press CTRL-] (jump to tag), the help
+system takes you to the indicated subject. (For reasons not discussed here,
+the Vim terminology for a hyperlink is tag. So CTRL-] jumps to the location
+of the tag given by the word under the cursor.)
+ After a few jumps, you might want to go back. CTRL-T (pop tag) takes you
+back to the preceding position. CTRL-O (jump to older position) also works
+nicely here.
+ 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).
+ See |29.1| for details about using tags.
+
+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 Vim 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
+
+When you start the Vim editor, you can use several command-line arguments.
+These all begin with a dash (-). To find what the -t argument does, for
+example, use the command: >
+
+ :help -t
+
+The Vim 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| vim:tw=78:ts=8:ft=help:norl: