The Woodnotes Guide to Vim for Writers

Randall Wood (www.therandymon.com) August 4, 2009

Contents
1 Why Vim for Writers? 2 Gvim vs. Vim 3 Line Wrapping and Text Width 4 Files (Opening, Saving, etc.) 5 General Editing of Text 6 Getting Around with the Cursor 7 Scrolling 8 Bookmarks (Marks) 9 Selecting Text, Cutting and Pasting 10 Searching and Replacing 11 Using Ranges 12 Multiple Windows, Buffers, and Tabs 13 Inserting Special Characters 14 Dealing with DOS, Unix conversion problems 1 2 3 3 4 4 5 7 7 8 9 9 10 10 11

1 WHY VIM FOR WRITERS?

11 12 12 13

15 Spell Checking 16 Macros 17 Learning more about Vim 18 Acknowledgments, License, and Version History

List of Figures
1 2 3 4 5 6 7 8 9 10 11 Files (Opening, Saving, etc.) . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Editing Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . Basic Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Simple Search Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Scrolling Relative to Document . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5 6 6 6 7 7 8 9 10 11

Scrolling Relative to Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Visual Mode Selection Commands . . . . . . . . . . . . . . . . . . . . . . . . . Cutting and Pasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Some Common Digraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1 Why Vim for Writers?

Vim is well used and well liked by computer programmers and computer scientists, but many of its features make it a productive tool for writers and authors as well. Namely, you can navigate and work efciently using succinct, keystroke commands, it is highly customizable, makes efcient use of screen real estate, is fast and extremely efcient. Furthermore, many of us have taken the time to get to know Vim for other purposes, and are so impressed wed like to make use of it for our writing projects. However, this is not a manual on how to use or learn Vim. Many of these exist, and all of them are better than what I could produce. Rather, this manual is written for the writer who wants to use Vim as his primary text editor for the purpose of producing prose, novels, ction, a thesis, a treatise, or similar. If you already know how to use Vim, this Woodnotes manual will help you use Vim efciently as a writer or author. It is a

3 companion volume to the Woodnotes Guide to Emacs for Writers1, and covers the same information. Your rst task then, if you havent already done so, is to get to know Vim. I recommend the use of a good reference card to learn and remember the commands. There are many available; my personal favorite is the creation of Laurent Grgoire.2 This guide uses the same notation as Laurents reference card, so it would help to have it in front of you as you continue. The graphical vi-vim cheat sheet and tutorial3 is an excellent way to learn Vim and serves as a cheat sheet afterwards (they also have a Dvorak version!). And of course, Vims own tutorial (just type :vimtutor is effective, and should probably be the rst place you begin learning this powerful software.

2 Gvim vs. Vim

Vim has traditionally been a console application, but there is a graphical version called Gvim as well4 , which some prefer. With the exception of spell checking and the ability to choose among several color schemes, Im not aware of any great difference between the two. You can also use console Vim in a terminal window on your graphical desktop, which, in my opinion is the best of all worlds, since you can take advantage of the better font rendering and resolution while still making maximum use of your screen space (run the terminal window in full screen mode for the best results).

3 Line Wrapping and Text Width

Unless you choose otherwise, each line of text will extend off the screen with no wrapping. For authors, thats not convenient. So issue the command :set linebreak to wrap the text when it hits the screen edge. This is what other software calls soft wrapping in that it conveniently manages the text on screen but doesnt insert newlines or carriage returns in the le. For long text works, this is probably what you want. If however, you want for example, 80 character hardwrapped text (text formatted with a new line after 80 characters) like in the good old days, issue :set textwidth=80. If you A are writing, for example, a LTEX document in which your document is a source le, this latter method may be more useful over all. Using the former method, what Vim considers to be a line is actually what we would call a paragraph, and moving up by one line at a time (using j and k) actually moves the cursor up by one paragraph at a time. Using the latter method, moving up one line actually moves you up one line on the screen, which is convenient. Otherwise, use gj and gk to advance the cursor one screen line at a time.
1 http://therandymon.com/content/view/16/98/ 2 http://tnerual.eriogerg.free.fr 3 http://www.viemu.com/a_vi_vim_graphical_cheat_sheet_tutorial.html 4 G

because it is built with the GTK+ toolkit.

5 GENERAL EDITING OF TEXT

4 Files (Opening, Saving, etc.)

Use :e to begin editing a le and:w to write it to the disk. Watch out if you change the name of the le when saving: this is not "save as" but rather the command to save a le by the other name while you continue editing the rst. That is to say, if you are editing le Introduction" and issue a :w Temp a le called Temp will be saved to the disk which for an instant will be identical to Introduction. But as soon as you continue typing, your new edits will continue to be applied to the le Introduction. That makes this a good way to save temporary (working) les as you go. Use :saveas to save the working le under a new name and continue editing that new le. One neat Vim trick of perhaps limited use to authors is the ability to specify a list of les to edit when you call the program. If, from the command line, you enter vim ch1 ch2 ch3 Vim will allow you to edit each of the three les in succession. In that case, :wn will write the le, close it,and then open the next (:wN opens the previous.). You can use :rw f to write the range r to le f (for example, :*w dialogue will take the entire visually selected range and write it out to a le called dialogue. Working in the other direction, :r dialogue will take the contents of the le dialogue and insert it at the cursor. Finally, an easy way to go through the current le and select bits and pieces of it for use elsewhere is to write out, appending to the other le. For example, once youve selected something, ":w> >goodies will append that selected text to the le goodies. You can then open up the le goodies to clean it up. Command Edit (Open) Write (Save) Save as Append to le Key :e :w :saveas :w> > Figure 1: Files (Opening, Saving, etc.)

5 General Editing of Text

Here, too, an adequate mastery of a few common commands makes basic text entry a lot more efcient and allows you to make edits on the y without stopping to take your hands off the keyboard. They all require the control key, because these commands are expected to be entered while you are still in insert mode. The most important is control-w, which deletes the most recent word and permits you to keep typing. Similarly, control-r x inserts the contents of register x at the cursor.5 In command mode, use the following to speed up editing and in particular, to take advantage of commands that allow you to, with one keystroke, position the cursor, erase

5 Function Insert before, after cursor Insert at beginning, end of line Change text of motion m Change to end of line Delete text of motion m Delete to end of line Delete letter under, before cursor Change letter under cursor and keep typing Replace letter under cursor Open a new line below, above cursor Join this line to the next Key i, a I, A cm C dm D x,X s r o,O j

Figure 2: General Editing Commands text, and begin editing. A few examples will make the benet clear. As an author I frequently begin a sentence and then decide halfway through that I am not pleased with what I have begun to write. A simple c( instructs Vim to change (erase and prepare for replacement of) everything to the beginning of that sentence. I can just as easily type c7b to change the last 7 words. If Ive edited something mid-paragraph and am ready to now place the cursor at the end of the paragraph and keep writing, its as simple as typing a capital A. Its also quick to select some text using visual mode, press d to delete it, and continue. Note that where delete and insert commands are concerned, pressing the .key (the period) instructs Vim to repeat the last command. If you type dw (delete word) and then 3. the second command will delete 3 more words. Be careful! One last word about editing. Vim remembers up to 100 of your last commands6 This allows you a lot of exibility with the undo command. Press u in command mode to undo your last command, and keep pressing it until you are satised. Control-r works in the opposite direction, redoing what youve just undone.

6 Getting Around with the Cursor

6.1 Basic Movement
Vim will most impact your prociency by facilitating rapid movement of the cursor and navigation through your document without taking your hands from the keyboard. Your mastery and application of movement and scrolling commands are thus essential.
5 The fact that the text is inserted at the cursor is important. If you insert text in command mode using the put command (p or P) it is sometimes inserted on a new line, and you must then join the two lines with j. 6 This is congurable and can be much, much higher if you wish.

6 Direction Left, Right Down, Up Screen Line Down, Up Forward, Backward word sentence paragraph Beginning, End of Doc Key h, l j, k gj, gk Key w,b (,) {,} gg, G

6 GETTING AROUND WITH THE CURSOR

Figure 3: Basic Movement Note that if you are using soft wrapping, what Vim considers to be a line is actually what we would call a paragraph since to Vim, a line ends with a new line character. As such, moving up by one line at a time (using j and k) actually moves the cursor up by one paragraph at a time. In that case, use gj and gk to advance the cursor one screen line at a time. You can gain some time with prepending a numerical reference, so typing 3( will take you back 3 sentences, and 5} will advance the cursor 5 paragraphs. Vim is aware of what you have visible on the screen, and allows you to quickly jump around on that basis as follows: Position on Screen Top Line Middle Line Bottom Line line n from top, bottom of window Key H M L nH, nL

Figure 4: Advanced Movement

6.2 Navigation by Search

A very convenient way to get around is by searching for a word located at the position youd like to go to. Vim offers several mechanisms for searching, which gives you some exibility in your approach. Search Mechanism search forward (down) search backward (up) next, previous occurrence next, previous occurrence of character c just before next occurrence of character c next, previous occurrence of word under the cursor Key / ? n,N fc, Fc tc, Tc #,*

Figure 5: Simple Search Commands

7 The f and t commands are most useful for nding characters that appear infrequently in your document, like punctuation marks; as such, I dont use them frequently. But searching using the / and ? commands is a fast way to get around your document. You can type ? Dingleberry to be taken to the most recent use of that word in your document. Continue searching in that direction by pressing n (in this case, since were searching upwards, n will continue searching upwards) or N to search in the opposite direction (in this case, down). Use a prepended numeral to jump that many search results: ? fleabag and then 3n will search for the word eabag and take you to the 4th occurrence.

7 Scrolling
Vim will save you time by eliminating the need to take your hands off the keyboard in order to position the cursor by sliding those little scroll bars up and down with the mouse. Scrolling via the keyboard is immensely efcient.7 At a minimum, get used to the zz command, which will position the cursor and the line youre currently working on, in the center of the screen. Just dont confuse it with ZZ which is a shortcut for exit. Scroll Direction and Amount Line up, down Half page up, down Full page up, down Key control-E, control-Y control-u, control-d control-b, control-f

Figure 6: Scrolling Relative to Document Position Cursor on Screen At the top In the middle At the bottom Key zt zz zb

Figure 7: Scrolling Relative to Screen

8 Bookmarks (Marks)
Placing marks through your text is an interesting way of navigating, if you nd yourself navigating back to certain positions frequently. But its more important a tool as part of cutting and pasting. Type m plus a letter from a-z or A-Z to establish a mark, and then (thats the single quote, not the backtick) plus that letter to return the cursor to the position identied by that mark. By distinguishing between upper and lower case identiers, Vim provides you 52 individual marks, more than youll probably need. If you
7 Remember

forward/backward and up/down.

9 SELECTING TEXT, CUTTING AND PASTING

forget where they are, typing :marks at the Ex prompt will provide you a list of them, plus the rst couple of words at each mark to help you identify them.

9 Selecting Text, Cutting and Pasting

9.1 Visual Mode
There are easy ways and hard ways to select text, but they are both useful and worth getting to know. The easiest way is called Visual Mode. Trigger it by pressing v or V. A lower case v starts highlighting text one letter at a time; this is good when you want to edit part of a sentence. A capital V starts highlighting text one line at a time. When youve selected the text, hit d to delete it (or cut it, since it winds up in a buffer), or y to yank (copy) it. Then navigate to where you want and hit p to place (paste) it. Normally, the cursor remains at the top of what you have just pasted, which gives you a chance to scroll down through the next text. But if you want to paste and go, gp and gP paste and then reposition the cursor at the bottom of the next text. You can also use t and f to advance the cursor until a point just before or right on the letter you are searching for. I frequently start visual mode with v and then advance up to the rst comma and delete it. That looks like this: vf,d. That is, start visual mode, advance to the comma, delete. Otherwise, use the a key plus w, s, p to add a word, sentence, or paragraph. But I just as often use the regular motion commands, and they work ne. Command Start visually selecting by character, line Exchange cursor position with start of highlighting Start highlighting on previous visual area Add word, sentence, paragraph Key v, V o gv aw, as, ap

Figure 8: Visual Mode Selection Commands The more complicated way is to use the motion commands alone to select areas. For example, if you want to copy the entire sentence you just wrote, you could issue y( (that is, yank to the beginning of the sentence). Youll get no visual feedback for this operation, but the text will be yanked and ready to place elsewhere. As an author, though, this is a fast way to keep your hands on the keyboard. If you dont like what you just wrote, a simple d( will remove your last sentence, d5b will remove the last 5 words, dTZ will delete back until the last occurrence of a capital Z, and so on.

9.2 Using Named Registers

By using the multiple named registers, you can hang on to whatever you copy and yank. Select one using the quote () as follows: ad{ means delete into named register a all

9 the text back to the beginning of the paragraph. If you forget what youve stored in the registers, the Ex command :registers will show them all. Using both marks and registers in a single command means you mustnt mix up your and characters: the former is for marks and the latter for registers. So, ayb means Yank from the cursors position to mark b, and store it in register a. Finally, you can place the contents of any register with the put command (p). For example, hp will put the contents of register h under the cursor, beginning on a new line (a capital P will place it on a new line above the cursor). Command Cut/Delete Yank/Copy Put/Paste below, above cursor Key d y p,P

Figure 9: Cutting and Pasting

10 Searching and Replacing

Lets start with the most common one as an example. Suppose youve written a story and now you want to change one of the characters names from Larry to Moe. Its as simple as %s/Larry/Moe/g which says For the entire document, change all occurrences of Larry to Moe. The percent sign is the range identier that indicates the search should take place over the entire document. You cant use motion commands here, but you can use line numbers (which is not that useful for authors), so :0,.s/hoo/ha/g will replace hoo with ha from line 0 to the present line. You can also append c for conrm each replacement.

11 Using Ranges
In the Larry/Moe example above, the % tells the search command to search the entire document. But searching and replacing is one of the few times a writer might be interested in limiting the effect of a command to a certain range of lines rather than to the entire document. Use visual mode to select a certain part of your document, and then limiting the search and replace to that range with * instead of %. Figure 10 shows the other options at your disposal. Here are two examples: .,$s/German/French/g From the cursors current position to the end of the document, replace German by French. *s/Zune/iPod/gc Within the visual area, change all occurrences of Zune with iPod, and conrm each replacement.

10 Range Use , or ; to separate two line positions Current line Last line in le Entire le Visual area Mark t Key ,; . $ % * t

13 INSERTING SPECIAL CHARACTERS

Figure 10: Ranges

12 Multiple Windows, Buffers, and Tabs

You can split the current screen into two parts where both both buffers show the same document, just by issuing :split (:sp). The screen will be divided into an upper and lower half; this is useful for looking at multiple parts of a document simultaneously. Its just as easy though to divide the window into left and right halves, with :vsplit (:vspl). Change between views with control-w w and close every other view but the current one by issuing control-w o. Note that if you ever use the help system, the window splits, and you will need to quit the help system by issuing :q to get back to your document; of course you can leave the help window open, issue control-w w to go to the other view, and return to editing your document.

13 Inserting Special Characters

If you write in a language other than English, you will need to enter characters not necessarily on your keyboard: accented characters and letters in other scripts. Even if you use English, you might nd it occasionally necessary to enter special characters. Frankly, the easiest way to do this is by means of your desktop environment (Gnome, KDE on Linux).8 Vim is able to communicate with the desktop processes and receive whatever characters you send it. However, Vim has another mechanism of its own for producing special characters. In Vim they are called digraphs, two keystroke combinations that lead to the production of a single character, like a for and DG for the degree symbol (35 C). When, while editing, you need a special character, press control-k and then the two digit code for that letter. This incomplete table shows some of the digraphs you would use for text with diacritical marks common to European languages. Type :help digraphs for a complete list. As an example, if you want a c cedilla (), the comma key plus one other character is the way to produce it, so as youre typing in insert mode, type control-k then ,c. If you want a tilde n (), type control-k then ?n.
8 On KDE, open the control panel and under Regional/Accessibility Keyboard layout, enable Enable keyboard layouts. On Gnome, either add the Special Characters applet to a panel or enable the keyboard switcher.

11 Character Name Exclamation mark Apostrophe Greater-Than sign Question mark Hyphen-Minus Left parenthesis Full stop Colon Comma Underline Char ! > ? ( . : , _ Meaning Grave Acute accent Circumex accent Tilde Macron Breve Dot above Diaeresis Cedilla Underline

Figure 11: Some Common Digraphs

14 Dealing with DOS, Unix conversion problems

You will occasionally have to deal with conversion of a DOS le which appears in Vim with a M character at the end of each line. The simplest way to do so is to simply search for and replace them, as follows: %s/control-m//g. That is, to search for a M you search for control-M. You can just as easily search for carriage returns (\r) like this: %s/\r//g. If youre using Vim on a Windows machine, the opposite may occur, and youll nd J characters at the line ends and beginnings of a Unix le. Treat it the same way, searching and replacing. Both phenomena are caused by Vim failing to identify a text le as one format or another (usually because both types of line endings are present). The fileformat command is how you declare your intention; the next time you save the le the appropriate line endings will be used, and when you reopen it the strange characters should disappear. For example :set ff=unix.

15 Spell Checking
Vim took a big step forward with version 7, which introduced spell checking and thus made Vim a much more attractive system for writing long text works. To take advantage of the new functionality, begin by typing :set spell, which turns on the spell checker with the default language. Once the spell checker is running, the keystrokes [s and ]s move the cursor from error to error. With the cursor positioned over a misspelled word, the keystroke zg declares that this word is good and should henceforth be ignored; zw identies a good word as one that shouldve been identied as an error. Finally, z= will request a list of suggestions from the ispell program, which allows you to choose what you want. For Vim to be able to add these words to a custom dictionary, you must dene your spellle, and Vims useful approach to doing so is to permit you to dene and use as

12

17 LEARNING MORE ABOUT VIM

many spellles as youd like. As such, you can have one spelling list for acronyms you need for one type of le without contaminating another dictionary. For example, :set spellfile=.spellfile.sailing.add creates a custom wordlist where you can put all your arcane sailing acronyms, and then choose not to load that dictionary while working on your medical thesis. This is useful but not perfect I happen to think emacs has the advantage here and consequently prefer to exit vim and use the ispell program to spell check text les already written; the advantage is no highlighted text distracts you. However, as an editing tool, in-program spell checking can be a useful and productive feature.

16 Macros
The easiest way to deal with repetitive text is to assign it to a keyboard macro using the imap command. If you enter :imap br Best regards,, the effect will be to map the expression Best regards, to the key combinaton br. Try a couple of these so you are familiar with the possibilities. Choose something exotic like the double-comma combination I use here to avoid stumbling on those keys in regular text. Note that once youve dened a macro, the cursor will change when typing if you begin to enter those rst keys while it decides whether or not what youre typing triggers a macro. When you quit Vim, the macros will vanish. For a longer term solution, put the macros in a le and source it, as follows. Lets say you create a le called keystrokes.vim Stuff it with lines like imap br Best regards,. Then, from Vim, issue :source keystrokes.vim and the new functionality will be imported. The .vimrc le is sourced automatically upon starting up, so if you have macros (or other custom modications, for that matter) that you would like to have available all the time, edit the .vimrc le (even if you have to create it!) to do so.

17 Learning more about Vim

While running Vim, the :help command is a great resource, if you know the name of what youre looking for (for example, :help wrap), and not so helpful if you dont. For more general questions, tips, tricks, FAQs, and similar, Vims web site is particularly useful: www.vim.org. In particular, the vim tips wiki is a repository for all sorts of tricks. Once youve mastered the basics, have a look at what the Vim experts have contributed. At http://vim.wikia.com/wiki/Vim_documentation you can nd several other high quality sources of information. I highly recommend Steve Ouallines book Vi Improved Vim. Although it was written for version 5.7, it is still mostly up to date and covers a lot more than this Woodnotes Guide does! It is even available as PDF download.

13

18 Acknowledgments, License, and Version History

As usual, no man is an island. Thanks rst of all to Norman Kraft9 who read my Emacs for writers guide10 and suggested this document. Thanks as well to Laurent Grgoire11 for his fantastic Vim Reference Card, which helped get me started when I was learning Vim, and has been a lifesaver ever since. This document is published under the Creative Commons Attribution-NonCommercialShareAlike 2.5 license.12 Please send comments, criticisms, and corrections to me at the email address found at my website. Enjoy this guide: I enjoyed creating it. 18 July 2009: rst draft 4 August 2009: minor format and URL edits

9 http://zenwrites.com 10 http://therandymon.com/content/view/16/98/ 11 http://tnerual.eriogerg.free.fr 12 http://creativecommons.org/licenses/by-nc-sa/2.5/