<%= comment %>
3 | 8 |Vim Recipes ‣ <%= title %>
2 |<%= comment %>
3 | 8 |Vim Recipes ‣ <%= section %> ‣ 2 | <%= title %>
3 | 8 | <%= body %> 9 | 14 | 15 | 18 | 24 | 25 | 26 | 27 | -------------------------------------------------------------------------------- /templates/syntax.css: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/templates/syntax.css -------------------------------------------------------------------------------- /templates/toc.html: -------------------------------------------------------------------------------- 1 |Vim Recipes ‣ Table of 2 | Contents
3 |You want to store your vimrc on a remote server, and have Vim use it 6 | automatically.
7 | 8 |For example, you regularly work on different computers and want to keep your 9 | configuration synchronised between them.
10 | 11 |Upload your vimrc to a server (such as a web server).
14 | 15 |You can start Vim with the -S flag, e.g. vim -S url.
16 | 17 |This is cumbersome, though. Easier is to use the following minimal 18 | vimrc on all of your machines:
19 | 20 |
21 | runtime plugin/netrwPlugin.vim
22 | silent source url
23 |
24 |
25 | This acts as a bootstrap config file. Vim loads your local vimrc 26 | first, activates the plugin needed to fetch files over the network 27 | (netrw), fetches the given URL, then 'sources' it as a set of Vim 28 | commands.
29 | 30 |Given how configurable Vim is, it's understandable that users want to use 39 | their handcrafted configuration regardless of what machine they use.
40 | 41 |The solution above is simple but does have some drawbacks. One is that every 42 | time you invoke Vim the remote vimrc is downloaded again. If you 43 | mainly use one Vim instance for long periods of time, perhaps using tabs to 44 | manage multiple files, this may not be a problem, but if you're regularly 45 | starting and quitting Vim instances, you may notice a lag in start-up time. 46 | Another drawback is that if you're working on a machine without Internet 47 | access, your configuration won't be loaded.
48 | 49 |One alternative is to periodically fetch your remote vimrc and save 50 | it as ~/.vimrc x-platform caveat. 51 | Unix/Linux users could do this with a wget url -O 52 | vimrc-path line in their crontab. This avoids the 53 | startup lag, and means that if you lose Internet access Vim will use the last 54 | vimrc it managed to download.
55 | 56 |Another is to keep your configuration in a version control system, such as 57 | Git, Subversion, Bazaar, then check out the repository on each machine you 58 | use. This is a more complete solution which allows you to synchronise all of 59 | your configuration files over multiple machines; not just Vim's. A VCS also 60 | makes it easier for multiple people to contribute to the configuration, which 61 | can be especially useful if you're working on a team.
62 | 63 |The Vim text editor is perhaps as famous for its learning curve as it is 5 | for its contributions to productivity. Vim isn't "intuitive" in the way other 6 | applications claim to be—you cannot use it by simply replicating the 7 | actions you perform with a word processor, by clicking on menu items aimlessly 8 | until you achieve your desired effect. But this is by design. The major 9 | strength of Vim is that it does things differently to magnificent 10 | effect. It permanently alters the way in which you regard text editors 11 | and software in general. And that is why, in 2009, I am putting the finishing 12 | touches to a free book about a text editor whose ancestry can be traced back 13 | to 1976.
14 | 15 |This book is written to be consulted when you're looking for a better way to 16 | perform a task. It does not replace Vim's excellent built-in documentation, 17 | but complements it by focussing on tasks rather than commands. It will always 18 | be incomplete by virtue of Vim having more features and extensions than I have 19 | years alive, but will hopefully still serve as an indispensable reference.
20 | 21 |In addition to being free, this book is open source. The files from which 22 | it is compiled are freely available, for you to examine and, hopefully, 23 | improve. In any case, I would enjoy hearing any feedback you have. Contact 24 | details are in the Contributing section, and you can e-mail me at the 25 | address below.
26 | 27 |Happy Viming!
28 | 29 |—Run Paint Run Run (runrun@runpaint.org), 2009, 31 | U.K.
32 |The following typographical conventions are used in this book:
5 | 6 |<Esc> - Indicates that the named key should be 9 | pressed.
10 | 11 |<Ctrl>-p - Keys joined with a 12 | - should be pressed simultaneously. In this example the 13 | <Ctrl> should be held down while the p key is 14 | pressed.
15 | 16 |gqap - The named characters should be entered in order while in 19 | Normal mode.
20 | 21 |:set spell - The command should be typed in 24 | Command-Line mode. (If you're in a different mode, press 25 | <Esc> before you type the command).
26 | 27 |:!command - As above, but command is a variable 28 | which should be substituted for its value.
29 | 30 |A fixed width font is used for filenames, code, and variable 33 | names.
34 |This book is released under a Creative Commons Attribution-Share Alike 3.0 5 | Unported License, and its complete text is available in a Git repository. All 6 | contributions are welcomed. Patches are preferred, but if you're not 7 | comfortable with Git you can use the issue tracker as described below.
8 | 9 |You may report typographical errors, factual mistakes, or unclear passages 12 | via the web-based issues tool at github.com/runpaint/vim-recipes/issues.
15 | 16 |You can send patches and bug reports to runrun@runpaint.org.
20 | 21 |The source for this book is available in a Git repository. If you have Git 24 | installed on your system you may clone the repository using the URL git://github.com/runpaint/vim-recipes.git. 26 | (For an introduction to Git see the Git 27 | Community Book).
28 | 29 |You'll probably want to do something like this:
30 | 31 |32 | $ git clone git://github.com/runpaint/vim-recipes.git 33 | Initialized empty Git repository in /tmp/vim-recipes/.git/ 34 | remote: Counting objects: 666, done. 35 | remote: Compressing objects: 100% (610/610), done. 36 | remote: Total 666 (delta 350), reused 0 (delta 0) 37 | Receiving objects: 100% (666/666), 407.52 KiB | 35 KiB/s, done. 38 | Resolving deltas: 100% (350/350), done. 39 | 40 | $ cd vim-recipes 41 | $ vim text/04_basics/09_configuring_vim.html 42 | $ git commit -a 43 |44 | 45 |
Then either send me a patch (runrun@runpaint.org), or post it to 46 | the issue tracker.
47 | 48 |Alternatively, if you already use GitHub, 49 | fork the repository, make 50 | your changes, then send me a pull request.
51 |This work is licensed under the Creative Commons Attribution-Share Alike 5 | 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ 7 | or send a letter to Creative Commons, 171 Second Street, Suite 300, San 8 | Francisco, California, 94105, USA.
9 |The cover photograph of Bram Moolenaar, 7 | the creator of Vim, was taken by Sebastian Bergmann and kindly 9 | released under a Creative Commons 11 | Attribution-Share Alike 2.0 Generic License. The original photograph can 12 | be viewed at Flickr.
14 | 15 |The Cascading Style Sheets used in the production of the book were derived 18 | significantly from the work of others. Mark 19 | Pilgrim's stylesheet from Dive 20 | Into Python 3 was the main inspiration. In conjunction, the CSS 21 | created by Håkon Wium Lie and 22 | Bert Bos for their book entitled 23 | Cascading Style 24 | Sheets: Designing for the Web, 3rd Edition, and graciously made 25 | available via A List 26 | Apart, was particularly helpful. Lastly, Nando Vieira's kitabu project 29 | offered ideas on how to tie it all together.
30 | 31 |The following people have kindly contributed ideas, corrections, and 34 | advice: Rizal Almashoor, Raúl Núñez de Arenas Coronado, Adam Blinkinsop, 35 | coderpunk, dm3, Kjetil Dynnamittt, Ihar Filipau, Michael Houghton, Javier 36 | Rojas, and others who I'm bound to have omitted. Thank you!
37 | 38 |You know that Vim has multiple modes of operation but aren't sure when to use 6 | which one.
7 | 8 |For practical purposes there are four modes:
11 | 12 |Vim's modal approach to editing can seem confusing, but it really is the key 30 | to understanding Vim.
31 | 32 |It's tempting to spend much of your time in Insert mode, and navigate with the arrow keys. However, this is 34 | slow and requires an awful lot of key presses.
35 | 36 |Normal mode is the default mode because it makes it so easy to move around the 37 | file to either edit existing text or position the cursor where you want to 38 | insert text.
39 | 40 |41 |49 | 50 |Use <Ctrl>+o in Insert mode to 42 | switch to Normal mode for one command, then return to Insert mode. For 43 | example, <Ctrl>+o gqas 44 | enters Normal mode, reformats the current sentence,For an 45 | explanation of gqas refer to the Selecting Text with Motions 47 | recipe. then returns you to Insert mode.
48 |
If you create a new file, and just want to type, by all means go straight 51 | into Insert mode and do so. All other times, though, stay in Normal mode.
52 | 53 |For example, you want to find a paragraph you've written previously, and 54 | reword it. In Normal mode you can either search for it (e.g. /Hobson 56 | argued), or simply page through the file (e.g. 57 | <Ctrl>+F to scroll downwards) to find 58 | it. Once there, you can move to the section you're interested in using either 59 | the basic movement 60 | commands or text objects. You can 61 | now use text objects again to select something and change it. For 62 | example caw deletes the current word and puts you into Insert mode 63 | to change it. Once you have done so, hit <Esc> again to 64 | return to Normal mode.
65 | -------------------------------------------------------------------------------- /text/04_basics/02_basic_navigation.html: -------------------------------------------------------------------------------- 1 |You want to move around inside a file.
6 | 7 |The traditional approach is to use the arrow keys to move up, down, left, 10 | and right. Vim supports that style of navigation but also offers a more 11 | efficient alternative:
12 | 13 |Key | Movement |
---|---|
h | Left |
l | Right |
k | Up a line |
j | Down a line |
0 | Start of line |
^ | First character of line |
$ | End of line |
It is tempting to rely on old habits for something as basic as moving 27 | around in a file. Once you're used to The Vim Way, however, you'll find 28 | yourself much more efficient. One reason for this is that these keys are all 29 | located on the main keyboard, so you don't need to stretch to the arrow keys, 30 | hence breaking your flow.
31 | 32 |Another benefit is that you can prefix these shortcuts with counts (as 33 | you can with many Vim commands) which specify how many times they should be 34 | executed. For instance, 2k moves up two lines.
35 | 36 |Once you've become used to these keys, take a look at motions and 37 | text objects in Selecting Text 38 | with Motions to make the humble combination of h, 39 | l, k, and j more powerful still.
40 | -------------------------------------------------------------------------------- /text/04_basics/04_saving_a_file.html: -------------------------------------------------------------------------------- 1 |You want to save the file you've been working on.
6 | 7 |After you've made changes to a file you typically want to save them. For 8 | example, if you've written up a turkey recipe to send to your daughter, you'd 9 | open Vim, type the recipe, save it to turkey-recipe.txt, then e-mail 10 | turkey-recipe.txt to your hungry child.
11 | 12 |The :up[date] command saves the current buffer if it has been 15 | modifiedThe more common command to save a file is 16 | :w, however this always saves the file, even if it hasn't been 17 | changed. :up preserves timestamps and saves needless disk 18 | access.. If your file doesn't have a name yet, you'll need to follow 19 | :up with a filename. This is conceptually similar to most word 20 | processors' Save function.
21 | 22 |To change the name of an existing file, use :saveas
23 | file. If file already exists and you want to
24 | overwrite it, use :saveas! file
. This is conceptually
25 | the same as most word processors' Save As function.
There are a number of situations where it can be useful to have Vim save 30 | your file for you automatically. One is when you're working with files in multiple buffers and cycling between them. By 32 | default, every time you switch to a buffer Vim prompts you to save the current 33 | one first. Another is when you execute an external command on the current 34 | file. The command is passed the file's name, so if your buffer contains 35 | unsaved changes, the command won't see them. The solution is to :set 36 | autowrite. This causes files to be automatically saved when you switch 37 | buffers and execute external commands. If you also want files automatically 38 | saved when you quit Vim, use :set autowriteall.
39 | 40 |41 |45 | 46 |The
44 |:autowrite
functionality is not related to some word 42 | processor's concept of auto-saving a file periodically in case of a crash. 43 | Vim does this automatically.
You can also "write" a specific portion of a file to a new filename. By 47 | prefixing the :up command with a line range only the specified 48 | lines are written to the named file. For example, :20,30up 20-30.txt 49 | saves lines twenty to thirty of the current buffer to a file named 50 | 20-30.txt. Alternatively, select a portion of a file visually then execute :up 52 | filename and the text you selected will be written to a file 53 | named filename. 54 | -------------------------------------------------------------------------------- /text/04_basics/05_quitting.html: -------------------------------------------------------------------------------- 1 |
You've finished using Vim and now you want to close the program.
6 | 7 |To save the changes in the current file then quit use :xThe more usual suggestion for saving then quiting is 11 | :wq. We use :x here because it only saves the file if it 12 | has been changed, thus preserving its timestamp and saving needless disk 13 | access.. In Normal mode you use ZZ.
14 | 15 |The way you quit Vim depends on what you want to quit (the whole program, 18 | or just the current window) and what you want to do with your unsaved 19 | changes.
20 | 21 |As mentioned above, if you're using a single window either :x or 22 | ZZ will save any unsaved changes, and exit Vim.
23 | 24 |To exit and discard your changes you use :q! (mnemonic: 25 | quit in a possibly dangerous (exclamatory) manner).
26 | 27 |You can also quit on the condition that there are no unsaved changes with 28 | :q; if you do need to save Vim warns you E37: No write since 29 | last change (add ! to override).
30 | 31 |If you're using multiple windows the above commands will act upon the 32 | current window. To quit all windows use :qa (mnemonic: quit 33 | all). Vim will prompt you to save any changes. To quit all windows 34 | without saving use :qa! (mnemonic: quit all in a 35 | possibly dangerous manner).
36 | -------------------------------------------------------------------------------- /text/04_basics/06_deleting_text.html: -------------------------------------------------------------------------------- 1 |You wish to remove some text from a file. For example, you've typed a 6 | paragraph which is no longer needed.
7 | 8 |In Normal mode, move your cursor over the character to banish and hit 11 | x (mnemonic: expunge). This deletes characters under and 12 | after the cursor; to delete characters before the cursor use X. 13 | This is fine for single characters, but to delete words and other text objects you can use 15 | dmotion. The difference, then, is that x 16 | deletes characters, whereas d deletes text described by a 17 | given motion.
18 | 19 |If you'd rather nuke entire lines at a time use dd. So, to 20 | delete the current line and the one following it: 2dd. Use a 21 | range prefix to delete the specified lines, e.g. :17,20d 22 | deletes lines seventeen through to twenty.
23 | 24 |A compromise is to delete the remainder of a line, which can be achieved 25 | with D. If your cursor was positioned after compromise in 26 | the above sentence, and you then hit D, the line would be changed 27 | to just A compromise.
28 | 29 |If you've selected a block of text visually, you can delete it all with 31 | x.
32 | 33 |Vim doesn't just delete text; it saves it to a register 36 | first. If you delete a small amount of text (less than a line), it's stored in 37 | a register named "-. Otherwise, it's stored in "0, whose 38 | existing contents are moved to "1, whose existing…right up to 39 | "9. This allows you easy access to previously deleted text inasmuch 40 | as you can recall, say, the 3rd most recently deleted line with 41 | "2p. Even more usefully, you can use :registers to view 42 | your recent deletions. The Undoing Mistakes 43 | recipe explains how to revert these deletions.
44 | -------------------------------------------------------------------------------- /text/04_basics/07_visually_selecting_text.html: -------------------------------------------------------------------------------- 1 |You want to interactively select some text by drawing a box around it, thus 6 | enabling you to perform a command that affects it. In other words, you want to 7 | select a text like you would in a GUI word processor using either the keyboard or, in 9 | Gvim, the mouse.
10 | 11 |To select text character by character change to Visual mode with 14 | v, then move the cursor as 15 | normal using the h,j,k,l keys. For 16 | example, to select the current character and the three that follow hit 17 | v, then 3l. To select the current paragraph: 18 | v, then ap.
19 | 20 |To select text by lines switch to Visual Line mode with 21 | V, then move upwards and downwards with k and 22 | j as normal. For example, to select the current line and the 2 23 | following it hit V, then 2j.
24 | 25 |To select text in vertical blocks, or 'columns' to the rest of us, you use 26 | Visual Block mode with 27 | <Ctrl>-vWindows® defines this 28 | shortcut for pasting text, so 29 | <Ctrl>-q exists as an alias.. For 30 | example, if you wanted to select the first two characters of the current line 31 | and the 20 following, you'd position your cursor on the first character of the 32 | first line you're interested in, hit <Ctrl>-v, move 33 | one character to the right (l), then move down 20 lines with 34 | 20j.
35 | 36 |If you want to switch selection mode mid-selection hit 37 | v, V, or 38 | <Ctrl>-v, as appropriate.
39 | 40 |As you get used to Vim's movement command, you'll have less of a need for 43 | the various visual modes. Regardless, they can still be convenient when you're 44 | making complex selections or aren't really sure what you're doing. ;-)
45 | 46 |Having selected text, o can be used to toggle the cursor between 47 | the beginning and end of the selection.
48 | 49 |The point of selecting text is to operate on it. Here are some common 50 | actions:
51 | 52 |You want to duplicate text from one place to another. For example, you may 6 | want to move the paragraph you've just typed above the previous one. Or maybe 7 | you want to copy some text from a web page into Vim.
8 | 9 |To copy/cut text from Vim you must first select it. You can do so visually, or provide a motion to the relevant 14 | command.
15 | 16 |Vim calls copying yanking, so to copy visually selected text 17 | use the y (mnemonic: yank) command. The syntax 18 | ymotion yanks the text defined by motion. For 19 | example, y2w would copy the current and following words. 20 | yy works on lines instead, so 4yy would copy the current 21 | line and the three following it. (Y is a synonym, thus saving you 22 | that extra keystroke ;-)).
23 | 24 |Cutting is much the same, only it uses d (mnemonic: 25 | delete) and dd, respectively. To cut the visually selected 26 | text, hit d. To cut the current line, dd. To cut the 27 | current word, dw.
28 | 29 |The text is now in one of Vim's registers. To paste the contents of 30 | a register into a file, position your cursor appropriately, then use the 31 | p (mnemonic: paste or put) key in Normal mode. 32 | p inserts text after the cursor. To insert the text before use 33 | P. As with many Vim commands, p and P can be 34 | prefixed with a repetition count, so 2p pastes the clipboard 35 | contents twice.
36 | 37 |To paste text from the system clipboard use 38 | Shift+Ins in Insert mode or "*p in 39 | Normal mode. Conversely, "+y yanks the current selection to the 40 | system clipboard.
41 | 42 |The solution above uses the concept of a single clipboard, much like some
45 | operating systems do. Vim can work this way, as you can see, but also supports
46 | 'named registers'. These are, effectively, multiple, independent clipboards.
47 | Registers are actually far more powerful than this;
48 | :help registers
for details. Registers are named with a
49 | " character followed by a single lowercase letter, e.g.
50 | "aAgain, this is a vast simplification..
To yank/delete/put using a named register, simply prefix the command with 53 | the register name. So, to yank the current line to register "b use 54 | "byy. To paste it use "bp.
55 | 56 |To view the contents of the registers (both user-set and Vim-set), issue 57 | the :registers command.
58 | 59 |When pasting text from external applications into a Vim instance Vim may 60 | clobber the text by attempting to be too clever. This happens when it cannot 61 | distinguish between entered text and pasted text. The most common symptom is 62 | that the pasted text is indented bizarrely.
63 | 64 |To fix this, consider using :set paste before you paste, then 65 | :set nopaste afterwards. Alternatively, use :set 66 | pastetoggle=key to map a key to toggle paste mode. With this 67 | setup on Linux, for example, users could paste with 68 | F11+Shift-Ins+F11.
69 | -------------------------------------------------------------------------------- /text/04_basics/09_configuring_vim.html: -------------------------------------------------------------------------------- 1 |You want your Vim preferences to persist over sessions.
6 | 7 |For example, you want Vim to show line numbers all the time. Displaying Line Numbers explains how, 9 | but when you restart Vim you find that your preferences have been 10 | forgotten.
11 | 12 |Throughout this book I will discuss how to configure Vim 15 | options using the :set option or :set 16 | option=value syntax. This works, but only for the 17 | current instance of Vim. If you specify these options in your vimrc 18 | file they'll be set permanently.
19 | 20 |21 |44 | 45 |Location of vimrc
22 | 23 |The default location of the vimrc file depends on your operating 24 | system. Identify your operating system, then note the corresponding path. 25 | All references in this book to vimrc refer to this path.
26 | 27 |Gvim reads vimrc then a gvimrc file located in the same 28 | place as vimrc. In this book vimrc and gvimrc are 29 | treated as synonyms.
30 | 31 |32 |
42 | 43 |- Unix/Linux
- 33 |
- $HOME/.vimrc
34 |- OS/2
35 |- $HOME/.vimrc or $VIM/.vimrc (or 36 | _vimrc)
37 |- MS-DOS and Windows
38 |- $HOME/_vimrc or $VIM/_vimrc
39 |- Amiga
40 |- s:.vimrc or $VIM/.vimrc
41 |
The vimrc is a simple plain text file. Open the filename specified 46 | in the sidebar and add one option per line using the 47 | option=value syntax (the ':' prefix is 48 | unnecessary). Indeed, this is the general principle for adding any 49 | Command-Line command in this book to your vimrc. For 50 | example:
51 | 52 |" Set the boolean number option to true
53 | set number
54 | " Set the textwidth option to '78'
55 | set textwidth=78
56 | " Set the expandtab option to false
57 | set noexpandtab
58 |
59 | A single quotation mark (") introduces comments. They are ignored 60 | by Vim, but particularly useful for remembering what all of your preferences 61 | mean.
62 | 63 |64 |68 | 69 |Even if you don't want to specify any options in vimrc you 65 | should still create it. On some systems Vim will act like the Vi editor in 66 | the absence of this file, which is unlikely to be what you want.
67 |
The vimrc locations given in the sidebar are used for user 72 | preferences; there are also system wide vimrc files. User preferences 73 | take precedence over system preferences. This means that if you change an 74 | option set in the system vimrc, your preferences will be respected. 75 | However, if the system vimrc sets an option differently from the Vim 76 | defaults, and you don't include it in your vimrc, the system 77 | preference will be used.
78 | 79 |The example vimrc above is very basic. They can also include 80 | functions, conditionals, and anything else Vim's scripting engine supports. 81 | For a simple example look at the usage of :autocmd in the Using Templates recipe.
83 | 84 |If your configuration becomes complex you may want to split it over 85 | multiple files. You can instruct Vim to include these files in your 86 | configuration by adding a source file line to 87 | vimrc for each config file. See Abbreviating Common 89 | Strings for an example.
90 | 91 |If you want a different configuration for a specific project you can :set 92 | exrc then include a .vimrc (or vimrc on DOS and MS 93 | Windows) in the project's directory. This takes precedence over your 94 | vimrc, and will be used when you edit files in that directory.
95 | 96 |109 | 110 |124 | -------------------------------------------------------------------------------- /text/04_basics/10_printing.html: -------------------------------------------------------------------------------- 1 |Debugging Configuration
111 | 112 |113 |
122 | 123 |- Start Vim without loading your vimrc: vim -u NORC. 114 | (Use -U for Gvim).
115 |- Start Vim with a different vimrc: vim -u 116 | file.
117 |- Start Vim in verbose mode: vim -V. (Describes each file being 118 | sourced).
119 |- Check the system wide vimrc to see whether its interacting 120 | badly with yours.
121 |
You want to print something from Vim.
6 | 7 |In GVim there's a Print entry on the File menu, and a printer 10 | icon on the toolbar. In Vim execute :hardcopy.
11 | 12 |:hardcopy converts the current file to Postscript and sends it to 15 | the default printer. You can specify that a different printer is used with 16 | :set 17 | pdev=printer. For example, :set pdev=usblp1.
18 | 19 |If you have a PDF printer 20 | installedLinux/Mac users can 21 | install the CUPS PDF package to get a PDF printer, e.g. on 22 | Debian/Ubuntu: apt-get install cups-pdf., you can use this 23 | technique to print a file to PDF. For example, assuming your PDF printer is 24 | called pdf:
25 | 26 |set pdev=pdf
27 | set printoptions=paper:A4,syntax:y,wrap:y
28 |
29 | The printoptions line is a comma separated list of values that 30 | affect how Vim formats the document before it sends it to the printer. A list 31 | of options is at :help popt.
32 | 33 |The paper option sets the paper size. It accepts values such as 34 | A3, letter, and legal.
35 | 36 |The syntax option determines whether the document is printed with syntax 37 | highlighting. By default it has the value a which means that Vim only 38 | uses highlighting for colour printers. A value of y forces 39 | highlighting.
40 | 41 |Lines are wrapped when wrap:y, which is the default. If 42 | wrap has the value n, long lines are truncated.
43 | 44 |Other useful options are header:0 to stop a header from being 45 | printed, number:y to number lines, duplex:off to print on 46 | only one side of the page.
47 | 48 |On Linux the lpr utility is used for printing. To use a different 49 | program add a stanza such as the following to your vimrc:
51 | 52 |set printexpr=PrintFile(v:fname_in)
53 | function PrintFile(fname)
54 | call system("a2ps " . a:fname)
55 | call delete(a:fname)
56 | return v:shell_error
57 | endfunc
58 |
59 | The above example specifies that the GNU Anything to Postscript 60 | (a2ps) utility is used for printing. a2ps can print two 61 | pages per physical page and custom headers, for example; see man a2ps 62 | for a complete list of features.
63 | -------------------------------------------------------------------------------- /text/04_basics/11_help.html: -------------------------------------------------------------------------------- 1 |You want help with Vim but don't know where to look. Or, you've found help 6 | but find the output of the online help confusing.
7 | 8 |Look up a topic in the online help with :help topic. 11 | Search it with the :helpgrep pattern command.
12 | 13 |14 |20 | 21 |When requesting help for a subject use 15 | <Ctrl>+d to auto complete what you've 16 | typed. For example, :help 17 | :h<Ctrl>+d shows a list of help 18 | topics for commands starting with :h.
19 |
The :help topic displays documentation for the tag named topic in the Vim 25 | documentation. The tags are named 26 | with the following convention:
27 | 28 |Type of Topic | Prepend | Example |
---|---|---|
Normal mode command | 32 |(nothing) | 33 |:help x | 34 |
Visual mode command | 37 |v | 38 |:help v_u | 39 |
Insert mode command | 42 |i | 43 |:help i_<Esc> | 44 |
Command-line command | 47 |: | 48 |:help :quit | 49 |
Command-line editing | 52 |c | 53 |:help c_<Del> | 54 |
Vim command argument | 57 |- | 58 |:help -r | 59 |
Option | 62 |' | 63 |:help 'textwidth' | 64 |
(The table above is excerpted from the Vim online help).
68 | 69 |The documentation itself also uses several conventions that may not be 70 | immediately obvious. For example, :help help displays the 71 | followingIf you're using a different colour scheme the 73 | colours may be different.:
74 | 75 |The strings in pink are synonymous tags for the current entry. For example, 79 | :help <F1> locates the same entry as :help help.
80 | 81 |The blue <Help> label indicates that in GVim the Help 82 | menu is the GUI equivalent of this command.
83 | 84 |The :h[elp] notation uses square brackets to indicate the optional 85 | portion of the command. Command-line commands can be shortened to the point 86 | that they are still unambiguous. In this case, :help can be shortened to 87 | :h or :hel.
88 | 89 |The green text ('helplang') indicates an option. It's also a 90 | hyperlink to an explanation of the option, so if your cursor is over it you 91 | can use <Ctrl>+] to follow it.
92 | 93 |The screenshot above identifies some further conventions to be aware 97 | of.
98 | 99 |The {pattern} notation describes a variable, i.e. it's a placeholder 100 | for text that you must supply.
101 | 102 |Again square brackets are denote optional text. In this example, 103 | [@xx] means that you can follow the pattern by a two-letter language 104 | code.
105 | 106 |Lastly, the light green text are also hyperlinks. For example, 107 | :cwindow links to documentation for that command.
108 | 109 |helpgrep takes a pattern and matches it against the locally 110 | installed documentation in much the same way as vimgrep did in Searching Over Multiple Files. If 112 | it finds any matches, it adds them to the quick fix listSee the Quick Fix List sidebar in Searching Over Multiple Files 115 | for more information, and jumps to the first one.
116 | 117 |118 |125 | 126 |Once you've followed a hyperlink (with 119 | <Ctrl>+]), you can return to your 120 | previous location with <Ctrl>+o. This 121 | works in a similar fashion to a web browser's Back button, so using 122 | this key combination n times will take you to the place you were 123 | at n links previously.
124 |
If you've installed a Vim addon, you'll need to run :helptags 127 | docs-path before helpgrep will see its 128 | documentation.
129 | -------------------------------------------------------------------------------- /text/05_editing/00.html: -------------------------------------------------------------------------------- 1 |You want to use whitespace (spaces or tabs) to indent lines from the left 6 | margin.
7 | 8 |For example, you may want to start your paragraphs with an indented first 9 | line. Or, if you're writing program source code, you may want to visually 10 | represent the structure of your program by using indentation to show 11 | nesting.
12 | 13 |To start a line indented, just press the tab key once for each level of 16 | indentation.
17 | 18 |To indent existing lines, highlight them visually and press > to 20 | indent or < to unindent.
21 | 22 |If you're in Insert or Replace mode you can use 23 | <Ctrl>-<Shift>-t to 24 | indent (mnemonic: tab), and 25 | <Ctrl>-<Shift>-d to 26 | unident (mnemonic: de-tab/indent).
27 | 28 |More powerful are motions 29 | combined with indent/unident commands. The syntax is 30 | >motion to indent the text described by 31 | motion, and <motion to unident 32 | it. For example, >ap indents the current paragraph. 33 |
34 | 35 |For many users, this solution will be sufficient. However, programmers 38 | regularly need more control over indentation because it's so important to 39 | their work.
40 | 41 |42 |46 | 47 |The :set list command makes literal tabs visible. It displays 43 | them as ^I, and uses a similar notation for other non-printable 44 | characters. The $ symbol is used to show the end of lines.
45 |
A contentious issue among programmers involves how the tab key should work. 48 | There are two main schools of thought:
49 | 50 |shiftwidth controls how many spaces are inserted when using the 64 | >>/<< technique 65 | described above, or the automatic indenting used with source code.
66 | 67 |softtabstop specifies how many columns Vim uses when 68 | Tab is hit in Insert mode. If it's less than 69 | tabstop, and Vim's not expanding tabs (:set 70 | noexpandtab), Vim indents with tabs, padding with spaces where 71 | necessary.
72 | 73 |(It can be seen, then, that you'll typically want to make 74 | softtabstop and shiftwidth equal, for reasons of 75 | consistency and sanity.)
76 | 77 |The boolean expandtab option replaces tabs with spaces if true; 78 | leaves them alone if false.
79 | 80 |These settings are not retroactive. To make an existing file honour your 81 | indentation preferences use the :retab! command.
82 | 83 |You've entered a command and want to repeat it without re-typing it.
6 | 7 |The period . repeats the last command entered in Normal 10 | mode. For example, dd deletes the current line; dd.. 11 | deletes the current line, then deletes the new current line, then deletes the 12 | new current line. In other words, it repeats the command twice.
13 | 14 |To repeat a command entered in Command mode hit 15 | :, then ↑ to 16 | scroll back through your command history. If you type the first few letters of 17 | the command before using ↑, the history will be limited 18 | appropriately.
19 | 20 |The period command helps automating repetitive tasks with the fewest
23 | keypresses. It lets you say do that again
, but in only one character.
24 |
If you know you want to execute a command n times, you can 27 | prefix it with the integer n. The above example rewritten in this 28 | way is 3dd.
29 | 30 |The second approach requires fewer keystrokes so is clearly preferable if 31 | you know in advance how many times you want to repeat a command. However, the 32 | period command lets you make that decision incrementally, after executing the 33 | command.
34 | 35 |You can combine these approaches by prefixing the period command with an
36 | integer to say do that n times again
:
37 | n.. Be aware that having done this, if you
38 | use the period command again it will repeat your previous repetitions, i.e.
39 | command, followed by
40 | n., followed by . will
41 | result in command being executed 2n + 1 times.
The discussion above assumes that the last command needs to be repeated 44 | exactly. Instead, you may wish to execute a different command on the same 45 | text. Jump to the line of the last change with the Normal mode 46 | command '., then make that change.
47 | -------------------------------------------------------------------------------- /text/05_editing/04_changing_the_case_of_text.html: -------------------------------------------------------------------------------- 1 |You want to change the case of a character or block of text. For example, 6 | you may want to change bob to Bob.
7 | 8 |As normal, these commands accept motions. For example:
27 | 28 |To convert a string to title case, i.e. initial capitals, you can
36 | use the following regular
37 | expression: s/\<\(\w\)\(\w*\)\>/\u\1\L\2/g
. Select the text you want to convert, hit
39 | :, then enter the regular expression. If you use this regularly,
40 | consider remapping a
41 | key to execute this command. For example:
nnoremap <F7> :s/\<\(\w\)\(\w*\)\>/\u\1\L\2/g<CR>
44 | vnoremap <F7> :s/\%V\(\w\)\(\w*\)\%V/\u\1\L\2/g<CR>
45 |
46 | Alternatively, you can install the titlecase 48 | plugin.
49 | -------------------------------------------------------------------------------- /text/05_editing/05_sorting_text.html: -------------------------------------------------------------------------------- 1 |You want to sort a selection of text or an entire whole file.
6 | 7 |For example, if you've made a list of your books with one title per line, 8 | you'd like to organise it alphabetically.
9 | 10 |Vim version 7 introduced a :sort command. So if you're using v7 13 | or later you can sort an entire file using :sort.
14 | 15 |16 |21 | 22 |You can find your Vim version number with the :version command. 17 | The first line of output contains the version number, e.g. VIM - Vi 18 | IMproved 7.2 (2008 Aug 9, compiled Mar 19 2009 15:27:51), which 19 | indicates version 7.2.
20 |
If you're using an older version of Vim you'll need an external sort 23 | utility. Linux/UNIX users should already have sort installed. You 24 | can sort the entire file by executing :!%sort, which filters the file 25 | through the external 26 | sort utility.
27 | 28 |To sort part of a file:
29 | 30 |Both methods above sort lines alphabetically. If you require a 40 | different type of sorting you need to pass options to the command.
41 | 42 |If you're using Vim 7+:
43 | 44 |For example, the following table describes how the set of data in the 63 | Original column is transformed for the given invocations of 64 | :sort.
65 | 66 |Original | 69 |:sort! | 70 |:sort in | 71 |:sort i /^./} | 72 |||||
---|---|---|---|---|---|---|---|
ant | 75 |1 | 76 |zebra | 77 |12 | 78 |ant | 79 |1 | 80 |zebra | 81 |12 | 82 |
Dog | 85 |7 | 86 |frog | 87 |11 | 88 |fish | 89 |6 | 90 |fish | 91 |6 | 92 |
cow | 95 |8 | 96 |fish | 97 |6 | 98 |Dog | 99 |7 | 100 |ant | 101 |1 | 102 |
fish | 105 |6 | 106 |cow | 107 |8 | 108 |cow | 109 |8 | 110 |Dog | 111 |7 | 112 |
frog | 115 |11 | 116 |ant | 117 |1 | 118 |frog | 119 |11 | 120 |cow | 121 |8 | 122 |
zebra | 125 |12 | 126 |Dog | 127 |7 | 128 |zebra | 129 |12 | 130 |frog | 131 |11 | 132 |
If you're using the external sort utility the options are 136 | similar. See man sort for the details. Common invocations are:
137 | 138 |You want to run a program from within Vim, possibly having it operate on the 6 | current file.
7 | 8 |For example, you want to view a list of the other files in your project by 9 | getting a listing of the current directory. Or you want to find mistakes in 10 | the essay you're working on by passing its filename to the diction 12 | utility.
13 | 14 |Invoke the program using the :!program syntax. For 17 | example, to view a directory listing on a POSIX system: :!ls.
18 | 19 |If you need to pass the current filename to the command as an argument, use 20 | the % wildcard. For example, executing :!wc % from 21 | aristotle-essay.txt executes wc aristotle-essay.txt.
22 | 23 |24 | 25 |44 | 45 |Filename Modifiers
26 | 27 |You can alter the filename represented by % by following the wildcard 28 | with a modifier. For example:
29 | 30 |31 |
42 | 43 |- %:p
32 |- Makes the filename a full path.
33 |- %:.
34 |- Makes the filename relative to the current directory.
35 |- %:t
36 |- Removes any directories before the actual file name. For 37 | example ~/work/foo.txt ⇒ foo.txt.
38 |- %:e
39 |- Removes everything except the filename extension. For 40 | example ~/work/foo.txt ⇒ txt.
41 |
The concept is that Vim suspends itself, asks your system to execute the 48 | command, shows you its output, then, once the user presses 49 | <Enter>, returns you to Vim.
50 | 51 |If you don't want to see the output of the command, you can execute it like 52 | this: :silent command. (To also hide any error output: 53 | :silent! command).
54 | 55 |You can use :redir > file if you want to save the 56 | output of a command to a file. You first execute, say, :redir > 57 | /tmp/output, then :!command. The output for 58 | command will be saved in the file /tmp/output, and 59 | displayed on the screen. (You can combine :silent command 60 | and :redir file to redirect a command's output to a file 61 | without seeing it on screen). To stop output redirection execute :redir 62 | END.
63 | 64 |You can use :r!command to execute command 65 | and read in its output to the current file. For example, if you're using a 66 | POSIX system, you can insert your kernel version with :r!uname 67 | -v.
68 | -------------------------------------------------------------------------------- /text/05_editing/07_managing_sessions.html: -------------------------------------------------------------------------------- 1 |Every time you work on a project you need to manually open all of the files 6 | it comprises, readjust the window size, etc. You'd like Vim to do all this 7 | automatically.
8 | 9 |Use sessions.
12 | 13 |To save a session: :mksession. Vim saves the session information 14 | as 'Session.vim' in the working directory; to specify your own filename 15 | execute :mksession file instead. To overwrite an existing 16 | session follow the command with an exclamation mark: :mksession!.
17 | 18 |To restore a session invoke Vim with the -S flag from the same 19 | directory you saved Session.vim in: vim -S. If you used a 20 | different filename for your session: vim -S file. If 21 | you're already inside Vim, you can load a session by sourcing the session 22 | file, e.g. :source Session.vim.
23 | 24 |Applications such as Mozilla Firefox use the concept of a global 27 | session file which is overwritten every time you use the program. To make Vim 28 | work this way you simply use a fixed name for the session variable. For 29 | example, you could save it to $VIMHOME/Session.vim. You could add a 30 | mapping something like this to your vimrc.
32 | 33 |nmap SQ <ESC>:mksession! ~/vim/Session.vim<CR>:wqa<CR>
34 |
35 | (SQ for Session Quit). To automatically restore 36 | this session when Vim is called without arguments add the following:
37 | 38 |function! RestoreSession()
39 | if argc() == 0 "vim called without arguments
40 | execute 'source ~/.vim/Session.vim'
41 | end
42 | endfunction
43 | autocmd VimEnter * call RestoreSession()
44 |
45 | You can extend this in arbitrary ways to suit your working environment. One 46 | approach is to only restore a session if it exists in the current file's 47 | directory. Another is to simply hardcode a list of directories whereby if they 48 | are the file's current directory or parent directory, their session file is 49 | used. This is useful for one-project-per-directory organisation.
50 | 51 |If you don't just want one global session file, as described above, a more 52 | granular approach is suggested below:
53 | 54 |nmap SSA :wa<CR>:mksession! ~/sessions/
55 | nmap SO :wa<CR>:so ~/sessions/
56 |
57 | Session Save As saves the open files and prefills the 58 | command line with the command to save the current session in a 59 | ~/sessions/ directory. All you need to do is enter a name and hit 60 | <Enter>.
61 | 62 |Session Open also saves the open files, then prefills the 63 | command line with the command to load a session file. Just type the name of 64 | the session you want to load and hit <Enter>.
65 | 66 |You can use <Tab> completion in both cases. For example, you 67 | could save a session with SSAwork<Enter>. Later, when you 68 | want to restore the session but can't recall its name, just hit 69 | SO<Tab> to cycle through the saved sessions.
70 | 71 |(Both mappings assume the ~/sessions/ directory already exists; 72 | create it if it doesn't).
73 | 74 |75 |81 | 82 | -------------------------------------------------------------------------------- /text/05_editing/08_formatting_with_an_external_program.html: -------------------------------------------------------------------------------- 1 |Yuri Klubakov's sessionman 77 | plugin provides a more 78 | polished approach for session management, subsuming the functionality 79 | described above.
80 |
You want to reformat text with a program other than Vim. For example, you 6 | want to use the W3C's 'tidy' 7 | utility to format HTML.
8 | 9 |Set the equalprg option to the name of the program you want 12 | to use, along with any arguments it should be passed. For example:
13 | 14 |:set equalprg=tidy\ -indent\ -q
15 |
16 | You can now select the text you want 17 | to format, then hit =. You can reformat the entire file with 18 | 1G=G.
19 | 20 |The formatter that you use depends on the type of content you are 23 | producing. Here are a couple of suggestions of programs to use for specific 24 | file types:
25 | 26 |If you want to format normal text using an external program, par 29 | is a popular choice. It can wrap, align, justify, and quote text in every 30 | conceivable way, and many more aside.
31 | 32 |Use HTML Tidy. You can 35 | specify options on the command line, as shown in the example above. If you 36 | want to specify a lot of options, put them into a config file, and point 37 | tidy to it: tidy 38 | --config file. At a minimum you probably want to use:
39 | 40 |:setlocal equalprg=tidy\ -utf8\ -indent\ -q\ -f\ /tmp/err
41 |
42 | Then you can reformat your file with 1G=G. One caveat is that 43 | this won't work correctly for reformatting a specific section of the file. You 44 | can use the --show-body-only true option if you want to be able to do 45 | this, but like many formatters of markup languages, Tidy doesn't perform as 46 | well on fragments because of lack of context.
47 | 48 |HTML Tidy can be used to format XML as well by passing it the 51 | -xml option. Alternatively, you can use xmllint:
52 | 53 |:set equalprg=xmllint\ --format\ -
54 |
--------------------------------------------------------------------------------
/text/05_editing/09_working_with_different_file_formats.html:
--------------------------------------------------------------------------------
1 | You're editing a file created on a different operating system, so need to 7 | change its line endings. Or, you wish to convert a file to use different line 8 | endings, perhaps because a tool expects them that way.
9 | 10 |Specify the desired file format with :set ff=format, 13 | where format is dos for Microsoft Windows/DOS files, 14 | unix for Unix/Linux, or mac for Apple Mac. As usual, you must 15 | then save the file to make the changes permanent: 16 | :up.
17 | 18 |Different operating systems have different notions of what constitutes a 21 | line in a text file. Specifically, they disagree on the control character that 22 | terminates a line. Unix/Linux uses a line feed (LF), Microsoft Windows uses a 23 | carriage return followed by a line feed (CRLF), and the Mac uses a carriage 24 | return (CR). This would be a matter of pedantry were it not for users of 25 | different operating systems sharing files.
26 | 27 |Luckily, Vim handles this situation transparently most of the time. When a 28 | file is loaded, its format is guessed, and &ff is set 29 | appropriately. If Vim guesses incorrectly, you can insist on a specific file 30 | format with :e ++ff=format, thus forcing the file to 31 | convert to the given format.
32 | 33 |The above assumes that a file's line endings are at least consistent. That 34 | is, each line ends with the same character(s). If your file is mangled (some 35 | lines ending with CR, some with LF, for example) you 36 | will likely see stray control characters such as ^J or ^M 37 | peppered throughout. This can be fixed with search and replace: :%s/\r//. 39 | Lastly, if you have some Mac line endings with dos/unix or 40 | Unix/Linux line endings with mac, use :%s/\r/\r/g.
41 | -------------------------------------------------------------------------------- /text/06_typing/00.html: -------------------------------------------------------------------------------- 1 |You want Vim to highlight misspelled words and suggest alternatives.
6 | 7 |To enable spell checking you first need to ensure that Vim knows which 10 | language you're typing in. If you execute :echo &spelllang you'll 11 | see the language code that Vim thinks applies. For instance en. To 12 | change this use :set spelllang=code. For example, I use 13 | :set spelllang=en_GB.UTF-8.
14 | 15 |If you're spell checking in American English, you should already have the 16 | dictionary installed. Otherwise, Vim should prompt you to download it. If 17 | you're not and it doesn't, see the Getting 18 | Dictionaries sidebar of Auto-Completing Text.
20 | 21 |To highlight spelling errors just execute :set spell. To remove the 22 | highlighting: :set nospell.
23 | 24 |Spelling errors are highlighted in one of four colours depending on the type 27 | of error:
28 | 29 |You can jump to the next spelling error after the cursor ]s and 38 | jump backwards with [s. Similarly, you can use ]S and 39 | [S to only jump between words not in the dictionary (i.e. rare, and 40 | region-specific misspellings are skipped).
41 | 42 |Once the spelling errors are highlighted, you presumably want to correct them. 43 | If you hit z= over a misspelled word you'll be presented with a list 44 | of suggested spellings. Enter the number corresponding to the correct 45 | spelling and hit <Enter>.
46 | 47 |If a correctly spelled word is highlighted as an error, you can add it to your 48 | personal dictionary with zg. This prevents it from being marked as 49 | an error in the future.
50 | 51 |Conversely, if an incorrectly spelled word isn't highlighted, you can add it 52 | to the bad word list with zw.
53 | -------------------------------------------------------------------------------- /text/06_typing/02_using_templates.html: -------------------------------------------------------------------------------- 1 |You create documents containing boilerplate text and would like to avoid 6 | typing it.
7 | 8 |For instance, you write HTML documents and don't want to type the standard 9 | preamble every time.
10 | 11 |Use templates and associate them with a file extension. When a new file is 14 | created with an extension for which a template is available, the template 15 | contents will be inserted.
16 | 17 |You must first create a skeleton document, e.g.:
18 | 19 |<?xml version="1.0" encoding="UTF-8"?>
20 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
21 | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
22 | <html xmlns="http://www.w3.org/1999/xhtml"
23 | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
24 | xsi:schemaLocation="http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd"
25 | xml:lang="en">
26 | <head>
27 | <title>Document Title</title>
28 | </head>
29 | <body></body>
30 | </html>
31 |
32 | Save this document in your Vim directory with the corresponding file 33 | extension, e.g. ~/.vim/skel/tmpl.html. (You may also want to make 34 | this file read only so you don't modify it by mistake).
35 | 36 |Add the following to your .vimrc:
37 | 38 |autocmd! BufNewFile * silent! 0r ~/.vim/skel/tmpl.%:e
39 |
40 | Now, every time you open a new file Vim checks ~/.vim/skel/ for a 41 | file whose name starts with tmpl. and ends with the extension of the 42 | file you're creating. It then reads the template file into your new file's 43 | buffer.
44 | 45 |For example, if you added the template above then invoked Vim with vim 46 | page.html, the XHTML above would be inserted into the 47 | page.html file automatically.
48 | 49 |Once you have created a document from a template you have to insert text at
52 | various predefined positions. For instance, for the XHTML template, you have
53 | to change the contents of <title>…</title>
,
54 | then start typing between the <body>…</body>
55 | tags. Navigating between these points in the document, which are the same
56 | every time you use the template, is cumbersome.
The traditional solution is to use placeholders. This involves including some 59 | notation in the template file that indicates where your input is required, 60 | then providing a method to jump between them.
61 | 62 |Here's the previous template with placeholders added:
63 | 64 |<?xml version="1.0" encoding="UTF-8"?>
65 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
66 | "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
67 | <html xmlns="http://www.w3.org/1999/xhtml"
68 | xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
69 | xsi:schemaLocation="http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd"
70 | xml:lang="en">
71 | <head>
72 | <title>%TITLE%</title>
73 | </head>
74 | <body>%BODY%</body>
75 | </html>
76 |
77 | The placeholder notation is arbitrary, but let's stick with 78 | %VARIABLE% for the sake of example. Now we need a way to jump between 79 | them, and <Ctrl>-p (menmonic: 80 | placeholder) seems reasonable. While we're at it, we'll define a 81 | function (LoadTemplate()) to replace the autocmd line we 82 | added earlier. Add the following to your vimrc:
83 | 84 |function! LoadTemplate()
85 | silent! 0r ~/.vim/skel/tmpl.%:e
86 | " Highlight %VAR% placeholders with the Todo colour group
87 | syn match Todo "%\u\+%" containedIn=ALL
88 | endfunction
89 | autocmd! BufNewFile * call LoadTemplate()
90 | "Jump between %VAR% placeholders in Normal mode with
91 | " <Ctrl-p>
92 | nnoremap <c-p> /%\u.\{-1,}%<cr>c/%/e<cr>
93 | "Jump between %VAR% placeholders in Insert mode with
94 | " <Ctrl-p>
95 | inoremap <c-p> <ESC>/%\u.\{-1,}%<cr>c/%/e<cr>
96 |
97 | If we create a new HTML file now this is what we see:
98 | 99 |See below for ways to automatically jump 103 | to the placeholders and for inserting smaller code fragments by using 104 | snippets.
105 | -------------------------------------------------------------------------------- /text/06_typing/03_undoing_mistakes.html: -------------------------------------------------------------------------------- 1 |You've made a mistake while editing and you'd like to revert it. Or, 6 | worse, you've made a mistake while reverting a mistake, and you'd like to 7 | revert that.
8 | 9 |For example, you've just deleted the paragraphs containing, subject to peer 10 | review, the cure for cancer. You'd kinda' like to retrieve it, and pretend the 11 | whole situation had never occurred.
12 | 13 |Use the undo feature. Hit u in Normal mode or :u in 16 | Command mode. You can undo all recent changes on the current line with 17 | U. To undo multiple times either repeat the command or prefix it with 18 | a digit indicating the number of times. For example, to undo the previous 19 | change and the one before that: uu.
20 | 21 |To redo a change that was undone use 22 | <Ctrl>+R or :redo.
23 | 24 |You can also jump backwards and forwards through your edits by time. To 25 | return to how your file looked 1 hour ago use :earlier 1h, then 26 | travel forward 20 minutes with :later 20m.
27 | 28 |The undo/redo behaviour described above should be familiar to most users as 31 | it mirrors that of many other applications. Vim, however, extends this concept 32 | into the idea of undo branches.
33 | 34 |Imagine you opened a new file and entered elephant. You then entered 35 | calf on a new line and hit u. This undid the addition of 36 | calf so now your file just contains the word elephant. Next you 37 | entered moose. If you hit u again you'd undo moose 38 | and get back to elephant. No matter how many times you do this you'd 39 | never get the calf back (which is unacceptable; elephant calves are 40 | particularly photogenic) because you made an edit after undoing (by adding 41 | moose).
42 | 43 |Undo branches to the rescue. Hit g- and your file will now 44 | contain elephant then calf. Here are the events represented 45 | diagramatically:
46 | 47 |Vim implicitly created an undo branch each time you hit u. The 50 | branch represents the state of the file before you undid. g- (and 51 | g+ to move forwards) moves between these branches.
52 | -------------------------------------------------------------------------------- /text/06_typing/04_auto-completing_text.html: -------------------------------------------------------------------------------- 1 |You want to be able to type the start of a word and then have Vim complete 6 | it. For example, you want to type multip, be offered suggestions for 7 | words that start that way, then pick one.
8 | 9 |To auto-complete a word Vim needs a list of possible words. An obvious 12 | source is the current file(s). If your file already contains the word 13 | multiplicand, then Vim can use it to auto-complete multip. 14 | Simply hit <Ctrl>+n after the p 15 | to complete the word. If multiple matches are found you'll be presented with a 16 | list from which to choose from.
17 | 18 |Another source of words is a dictionary. Get one, using the sidebar for 19 | reference, then point Vim to it with :set 20 | dictionary=file. Then add the dictionary to list of places 21 | Vim looks for words: :set complete+=k. The 'complete' 22 | options controls where Vim looks for possible matches.
23 | 24 |25 | 26 |36 | 37 |Getting Dictionaries
27 | 28 |If you specify your language with :set 29 | spelllang=lang-code, e.g. :set spelllang=it for 30 | Italian, Vim should automatically download the correct dictionary for 31 | you and set it up. If this doesn't work for you see :help spell and 32 | vim/runtime/spell/README.txt.
34 | 35 |
Auto-complete can also be used to lookup synonyms for the current word. Get 38 | a thesaurus file, then instruct Vim to use it with :set thesaurus=file, 39 | :set complete+=s.
40 | 41 |<Ctrl>-x 42 | <Ctrl>-f searches for the filename that 43 | starts with the text before the cursor. If one is found, it is inserted before 44 | the cursor. If multiple filenames are found, a drop down list is displayed to 45 | choose between them.
46 | 47 |48 |55 | 56 |Eric Van Dewoestine's SuperTab 50 | plugin lets you use the <Tab> key to auto-complete text. 51 | You select the type of completion that you want using 52 | :SuperTabHelp, then just hit <Tab> after a word 53 | to see a drop-down menu of completion choices.
54 |
Vim can use pretty much any word source imaginable. Consult :help 59 | ins-completion for more details.
60 | 61 |Vim version 7 and above supports Omni-Completion, which allows 62 | custom functions to generate possible completions dynamically. Even better, 63 | for programmers at least, is that some popular programming languages already 64 | have Omni-Completion functions which are enabled automatically. These typically 65 | allow context-sensitive completion of method names, objects, and reserved 66 | words. For example, using Ruby I can type an integer, a period, then invoke 67 | Omni-Completion to find that Fixnum objects support methods such as 68 | %, *, and +.
69 | 70 |Languages that don't have Omni-Complete functions available can use 71 | their syntax highlighting definitions to achieve a similar affect. The Vim 72 | documentation suggests adding the following stanza to your vimrc, after any :filetype 74 | command, to enable Omni-Completion using the best available method: 75 |
76 | 77 |if has("autocmd") && exists("+omnifunc")
78 | autocmd Filetype *
79 | \ if &omnifunc == "" |
80 | \ setlocal omnifunc=syntaxcomplete#Complete |
81 | \ endif
82 | endif
83 |
84 | To use Omni-Completion hit Ctrl+x 85 | Ctrl+o to be presented with a list of choices for 86 | the text behind the cursor.
87 | 88 |Apart from programming languages, Omni-Completion also works for HTML and 89 | CSS. For example, you can type <p cl, 90 | Ctrlx 91 | Ctrl+o, then be shown class=" 92 | CDATA, onclick=" Script, and ondblclick=" 93 | Script.
94 | -------------------------------------------------------------------------------- /text/06_typing/05_abbreviating_common_strings.html: -------------------------------------------------------------------------------- 1 |You regularly have to enter the same text, but don't want to.
6 | 7 |For instance, if you use Vim to write e-mail you may often mention the URL 8 | of your website. Instead of typing http://example.com/ every time, 9 | which is both annoying and error prone, you want to enter, say, myUrl 10 | and have it replaced with the address.
11 | 12 |Use Vim's abbreviations feature to map concise abbreviations to frequently 15 | entered text.
16 | 17 |To create the aforementioned abbreviation we use the :iabbrev 18 | command: :iabbrev myUrl http://example.com/. To use it, type the name 19 | of the abbreviation (myUrl in this case) and then hit 20 | <Space> or <Enter>. The name of the 21 | abbreviation is replaced with its payload.
22 | 23 |The syntax for defining abbreviations is :iabbrev name 24 | payload, where name is the text you want 25 | replaced, and payload is what it should be replaced with.
26 | 27 |The abbreviation feature is smart enough not to expand abbreviation names that 30 | occur as part of another word, but its telepathic functionality is suboptimal. 31 | Useful abbreviation names are easy to type, but will not appear in normal 32 | text. The convention I use is to prefix them with my, then uppercase 33 | the first letter. (If you use a programming language that prefers "camelCased" 34 | variable names, you may see clashes. Either stop using Java®, or disable 35 | abbreviations for the source code.)
36 | 37 |You can also abbreviate commands. For instance, if you wanted to type 38 | :docs instead of :help you could map one to the other with 39 | :cabbr docs help.
40 | 41 |I suggest keeping your abbreviations in an abbreviations file in 42 | $VIM. You can then source it from your vimrc. For example, you can create the 44 | file by running vim $VIM/abbreviations, then populate it with your 45 | abbreviations:
46 | 47 |iabbrev myUrl http://example.com/
48 | iabbrev myEmail user@example.com
49 |
50 | Then in vimrc just write source $VIM/abbreviations.
51 | -------------------------------------------------------------------------------- /text/06_typing/06_inserting_accentedforeign_characters.html: -------------------------------------------------------------------------------- 1 |You want to type characters which don't exist on your keyboard.
6 | 7 |For example, you want to type some words in another language, so need to 8 | insert accented characters. Or you want to type a symbol such as ±. 9 |
10 | 11 |If you haven't already, set up Vim to use UTF-8 by following the sidebar. 14 | It makes this process far easier.
15 | 16 |17 | 18 |34 | 35 |Enabling UTF-8 Support
19 | 20 |Vim uses the encoding specified by the user's environment. On Linux this 21 | is set with the $LANG variable. To override this use :set 22 | encoding=utf-8.
23 | 24 |If you're using Vim from a terminal your terminal software must also be 25 | configured to use UTF-8. Instructions for that are outside the scope of this 26 | recipe.
27 | 28 |When editing files their current encoding is maintained, so if you opened 29 | a file in ISO-8859-2, your changes would be written in that encoding. 30 | To force UTF-8 for all files use :set encoding=utf-8 31 | fileencodings=.
32 | 33 |
To insert an accented character you press 36 | <Ctrl>-K, the unadorned character, then 37 | another character indicating the accent type. This method can also be used to 38 | produce translations of characters in a given script.
39 | 40 |For example, to insert an e acute (the last letter in café) you hold 41 | down <Ctrl>-K, type e, then type 42 | an apostrophe (').
43 | 44 |The following table shows the different types of characters you can produce:
45 | 46 |Character | 49 |Meaning | 50 |
---|---|
! | 53 |Grave | 54 |
' | 57 |Acute accent | 58 |
> | 61 |Circumflex accent | 62 |
? | 65 |Tilde | 66 |
- | 68 |Macron | 69 |
( | 72 |Breve | 73 |
. | 76 |Dot above | 77 |
: | 80 |Diaeresis | 81 |
, | 84 |Cedilla | 85 |
_ | 88 |Underline | 89 |
/ | 92 |Stroke | 93 |
" | 96 |Double acute (Hungarumlaut) | 97 |
; | 100 |Ogonek | 101 |
< | 104 |Caron | 105 |
0 | 108 |Ring above | 109 |
2 | 112 |Hook | 113 |
9 | 116 |Horn | 117 |
= | 120 |Cyrillic | 121 |
* | 124 |Greek | 125 |
% | 128 |Greek/Cyrillic special | 129 |
+ | 131 |Smalls: Arabic, caps: Hebrew | 132 |
3 | 135 |Some Latin/Greek/Cyrillic | 136 |
4 | 139 |Bopomofo | 140 |
5 | 143 |Hiragana | 144 |
6 | 147 |Katakana | 148 |
This method of input is most suitable for occasionally typing unusual 154 | characters. For regular use, Vim supports most input methods. See :help 155 | keymap and :help termencoding for more details.
156 | 157 |Vim refers to printable, non-ASCII characters as digraphs. A list of 158 | digraphs available on your system can be obtained with the command 159 | :digraphs. The output may appear chaotic, but that's mainly because 160 | it's so dense. It lists, in columns, the character's internal name, the 161 | literal character, and the character code in decimal.
162 | 163 |You can also insert characters using their character code. If you're one of 164 | the slackers who haven't memorised the Unicode specification yet, you can use 165 | the :digraphs command, or any other reference, to lookup the code. 166 | Hit <Ctrl>-V, then type the code in 167 | either hexadecimal or decimal. Continuing the above example of producing 168 | é, you could enter either <Ctrl>-V 169 | xe9 or <Ctrl>-V 170 | 233.
171 | 172 |The internal name :digraphs lists corresponds with the shortcut 173 | table above. That is to say, the internal name for é is e'. 174 | Thus, we can generalise the <Ctrl>-K 175 | approach for any character we know the name of. For example, to produce the 176 | ± sign you hit 177 | <Ctrl>-K-+-.
178 | -------------------------------------------------------------------------------- /text/06_typing/07_opening_the_file_name_beneath_the_cursor.html: -------------------------------------------------------------------------------- 1 |You have a file name under your cursor and would like Vim to open it.
6 | 7 |For example, program source code often references other files from which it 8 | includes functionality. You want to quickly open such a file.
9 | 10 |Position your cursor over a file name then hit gf (mnemonic: 13 | go to file or get file) in Normal mode. For 14 | example, consider a file like the following:
15 | 16 |17 | Edit your ~/.vimrc by opening it with Vim, then... 18 |19 | 20 |
If your cursor was anywhere over ~/.vimrc, gf would try to 21 | open your Vim configuration file. (This assumes that you're using Linux where 22 | ~ is shorthand for the user's home directory).
23 | 24 |Vim doesn't care if the word under the cursor looks like a filename, 25 | so if your cursor was over the word your, instead, it would try to open a 26 | file named your in your path.
27 | 28 |Your path is a list of directories in which Vim searches for the named 29 | file. To see what it's currently set to execute :echo &path. The 30 | path is a comma-separated list of directories, some of which have special 31 | significance:
32 | 33 |I like gf to search recursively downwards from the current directory 48 | so I append ./** to my path like so: :set path+=./**.
49 | 50 |This feature has a surprising amount of uses for something so 53 | basic. I use it when:
54 | 55 |Vim also lets you follow URLs in this way, so you can gf on 69 | http://example.com/, to open the HTML in Vim, or 70 | sftp://example.com/README to connect to example.com via SFTP, 71 | fetch README, then open it for editing in Vim.
72 | 73 |By default gf opens the file in the same window. To open it in a 74 | new tab use 75 | <Ctrl>w+gf. To make this 76 | behaviour the default consider a key remap: 78 | :nnoremap gf <C-W>gf.
79 | 80 |If your filename is followed by a line number, e.g. foo.txt:10 you 81 | can jump to the given line with gF.
82 | 83 |If the filename you use gf on doesn't exist, Vim complains. I 84 | don't use gF so I have remapped it to create the given file: 85 | :nnoremap gF :view <cfile><cr>.
86 | -------------------------------------------------------------------------------- /text/06_typing/08_inserting_the_date.html: -------------------------------------------------------------------------------- 1 |You're typing a document and want to insert the current date.
6 | 7 |For example, you're composing a letter and want to include today's date at 8 | the top.
9 | 10 |Use !!date in Normal mode.
13 | 14 |The !!command syntax executes command and 17 | replaces the current line with the output.This is 18 | in fact an oversimplification. count!!command 19 | actually filters count lines through command and 20 | returns the result, but when count is omitted, it has the effect 21 | I've described. This is why the text on the current line is 22 | replaced with the date.. To control where the date is 23 | inserted see the following paragraphs.
24 | 25 |A similar same effect can be achieved with :r!date. The advantage 26 | is that it inserts the output of date on the next line, rather than 27 | replacing the current one.
28 | 29 |The solutions above assume that you have a date executable in your 30 | PATH, as all UNIX-based systems should. I understand that Windows 31 | users have to use !!date /t.
32 | 33 |Alternatively, you can call Vim's strftime() function, e.g. 34 | strftime("%c"). This will work on all systems which support the 35 | strftime system call, which I believe is the majority. You can map this function 37 | to a function key. For example, the following commands map 38 | <F7> to insert a date stamp after the cursor.
39 | 40 |:inoremap <F7> <C-R>=strftime("%c")<CR>
41 | :nnoremap <F7> "=strftime("%c")<CR>p
42 |
43 | I suggest the use of !!date because it doesn't waste a function 44 | key, and, personally, I find it more memorable. If you intend to insert dates 45 | regularly, by all means remap a key to do so.
46 | -------------------------------------------------------------------------------- /text/07_navigation/00.html: -------------------------------------------------------------------------------- 1 |You're editing a text file such an essay or e-mail, and want to exploit its 6 | structure to navigate it efficiently.
7 | 8 |In Normal mode you can use the following shortcuts:
11 | 12 |Key | 15 |Move To | 16 |
---|---|
{ | 19 |Beginning of current paragraph | 20 |
} | 23 |End of current paragraph | 24 |
( | 27 |Beginning of current sentence | 28 |
) | 31 |End of current sentence | 32 |
w | 35 |Beginning of next word | 36 |
b | 39 |Beginning of the previous word | 40 |
e | 43 |End of the word | 44 |
The shortcuts above all rely on the fact that plain text is often very 50 | structured. A document consists of paragraphs separated by newlines. 51 | Paragraphs contain one or more sentences which begin with capital letters and 52 | end with periods. Sentences are collections of words which are separated by 53 | spaces.
54 | 55 |After using one of these shortcuts you may want to return to where you were 56 | previously. This is particularly useful if you're writing one thing and are 57 | then reminded that you now have to change another: you use a shortcut to jump 58 | to the location of the change, then want to resume where you left of. You can 59 | use the g, (mnemonic: go back to where I paused (commas can be 60 | used to represent pauses…)) command. Each time you execute it you'll be 61 | taken back another step. To move in the other direction (towards more recent 62 | changes), use g;.
63 | 64 |All of these shortcuts can be combined. So, to move to the end of the previous 65 | word you type be. You can also prefix them with numbers to indicate 66 | how many times they should be executed: 3b moves to the beginning of 67 | the 3rd previous word.
68 | -------------------------------------------------------------------------------- /text/07_navigation/03_navigating_source_code.html: -------------------------------------------------------------------------------- 1 |You're editing the source code for a computer program, and want to navigate 6 | it efficiently.
7 | 8 |The commands below allow movement around source code in the context of
11 | typical constructs. For instance, % finds the end of the
12 | if
/elsif
/else
block, or a comment, your
13 | cursor is over, and moves you to the end of it.
Key | 18 |Move To | 19 |
---|---|
% | 22 |End of construct A construct is a bracket pair, an
23 | if /elsif /else block, or a comment.
24 | For example, if you hit % on
25 | an opening bracket you'd jump to the corresponding closing bracket. See
26 | :help % for more details. |
27 |
[[ | 30 |Backwards to the beginning of the current function. | 31 |
][ | 34 |Forwards to the beginning of the current function. | 35 |
]} | 38 |Beginning of the current block. | 39 |
[{ | 42 |End of the current block. | 43 |
}[ | 46 |Beginning of the current comment block. | 47 |
}] | 50 |End of the current comment block. | 51 |
gd | 54 |First usage of the current variable name Occurrences 55 | in comments are ignored.. (Mnemonic: go to 56 | definition). | 57 |
gD | 60 |Go to the first global gd looks for 61 | the definition closest to your current position, thus respecting the 62 | lexical scoping rules of many languages. gD starts searching 63 | from the first line of the file, so prefers variables with a global 64 | scope. usage of the current variable name. | 65 |
The shortcuts available for text files are 71 | supported for source code, too, so review them if you haven't already.
72 | 73 |There's a lot to remember here. Despite my best efforts, I suspect that the 74 | descriptions above are still confusing. To understand these shortcuts you 75 | really need to try them yourself. Open some source code written in your 76 | favourite language with Vim, make sure that syntax highlighting is on 77 | (:syntax on), and bounce back and forth between those braces.
78 | -------------------------------------------------------------------------------- /text/07_navigation/04_navigating_the_viewport.html: -------------------------------------------------------------------------------- 1 |You want to scroll through a document in screenfulls; not line by 6 | line.
7 | 8 |Command | Scroll To |
---|---|
H | Top of the screen. (Mnemonic: 13 | Home). |
L | Bottom of the screen. (Mnemonic: 15 | Lower). |
M | Middle of the screen. (Mnemonic: 17 | Middle). |
gg | Top of file. |
G | Bottom of file. |
If your file is longer than the height of your window, you'll need a way of 25 | scrolling the portion that appears on the screen.
26 | 27 |The area of the screen displaying a file is called the viewport. As we 28 | scroll down the document using j, the viewport updates to hide the line at 29 | the top, and show a new one at the bottom. Scrolling through a long document 30 | this way is inefficient and unhealthy for our fingers. Instead we can scroll 31 | one screenfull at a time, which severely reduces the amount of key presses 32 | involved.
33 | -------------------------------------------------------------------------------- /text/07_navigation/05_navigating_buffers.html: -------------------------------------------------------------------------------- 1 |You have multiple files open and want to navigate between them.
6 | 7 |Buffers allow you to have a collection of files open with only one 10 | displayed at a time. They are particularly useful for processing a set of 11 | files sequentially, whereby you operate on one file, then switch to the buffer 12 | containing the next. If you'd rather have the open files listed along the top 13 | of the screen, consider using tabs 14 | instead.
15 | 16 |Command | 19 |Result | 20 |
---|---|
:buffers | 23 |View the list of buffers along with their numbers. | 24 |
:ls | 27 ||
:files | 30 ||
:buffer N | 33 |Open buffer N. | 34 |
:bn[ext] | 37 |Go to the next buffer. (Menmonic: buffer next). | 38 |
:bp[revious] | 41 |Go to the previous buffer. (Mnemonic: buffer 42 | previous). | 43 |
:bf[irst] | 46 |Go to the first buffer. | 47 |
:bl[ast] | 50 |Go to the last buffer. | 51 |
:ba[ll] 54 | | Open all the buffers in the buffer list. (Mnemonic: buffer 55 | all, or have a ball, go crazy and open them all at once). | 56 |
To quickly navigate between buffers its common to map :bnext and/or 62 | :bprev to a key. For example map <F6> :bn<CR> lets you hit 63 | <F6> to cycle through the open buffers.
64 | 65 |You can also switch buffers very quickly by using :buffer (and its 66 | shortcut :b). It supports (partial) file matching thus if you have 67 | first.txt and second.txt loaded you can use :b fir (or even just 68 | :b f) to switch to first.txt.
69 | -------------------------------------------------------------------------------- /text/07_navigation/06_navigating_tabs.html: -------------------------------------------------------------------------------- 1 |You want to group your windows into multiple, logical groups.
6 | 7 |When you have a lot of open windows/buffers it can be tricky to navigate 8 | between them. Often it makes more sense to group them into logical 9 | tabs, so you can switch between them easier, and operate on them as a 10 | group.
11 | 12 |For example, if you were using Vim to edit a website, you may have your CSS 13 | files open in one tab, the HTML files in another, and a HTML reference guide 14 | in the third.
15 | 16 |Use tabs.
19 | 20 |Command | 23 |Action | 24 |
---|---|
:tabedit [file] | 27 |Open a new tab. If the optional file is supplied, that file is opened 28 | in the new tab. | 29 |
:tabclose | 32 |Close the current tab. | 33 |
:tabnext n | 36 |Go to next tab, or the nth | 37 |
ngt | 40 ||
:tabs | 43 |Show a list of the open tabs. | 44 |
:tabprevious n | 47 |Go to previous tab, or the nth | 48 |
ngT | 51 ||
:tabdo cmd | 54 |Executes cmd in each open tab, aborting on the first 55 | error. | 56 |
You can use Vim's tabs like those in Firefox® and Opera®, by 62 | opening one file in each tab, then switching between them. Vim enables you to 63 | extend this concept, however, by allowing multiple files to be opened in the 64 | same tab.
65 | 66 |When you open a tab, a tabline appears along the top of the screen, 67 | which lists the open tabs. In GVim you can switch to another tab, close 68 | existing tabs, and open new tabs, by clicking the tabline with the mouse.
69 | 70 |You can either cycle through open tabs using gt, or go directly 71 | to a specific tab by prefixing gt with its number. Tabs are 72 | numbered starting with 1, so to switch to the 3rd tab on the 73 | tabline, say, you'd use 3gt. If you have a lot of tabs, their 74 | numbers may not be obvious. In this case, use :tabs to find them.
75 | 76 |The power of tabs comes from executing commands on the windows they contain 77 | as a logical group. Continuing the above example, this would let you perform a 78 | search and replace all HTML files. For 79 | example, if you were in the HTML tab, you could say :tabdo 80 | s/<foo>/<bar>/g, and all of your HTML files would have 81 | their <foo>s replaced with <bar>s.
82 | -------------------------------------------------------------------------------- /text/07_navigation/07_manually_creating_folds.html: -------------------------------------------------------------------------------- 1 |You want to fold a file, then navigate it in outline mode.
6 | 7 |10 | 11 |18 | 19 |Enabling Folding
12 | 13 |Folding is very likely already enabled in your Vim. If not, 14 | check it has been compiled with the +folding option, 15 | and that foldenable is true, i.e. :set foldenable.
16 | 17 |
Use Vim's folding feature to treat a file hierarchically, 20 | expanding and collapsing its sections as necessary.
21 | 22 |Fold commands start with z. Vim's help makes the spurious case 23 | that this, kinda', if you squint, looks like a folded piece of 24 | paper.
25 | 26 |Command | Action |
---|---|
zf | Fold the selected text. |
zf#j | Create a fold from the cursor 30 | down # lines. |
zf/string | Create a fold from the 32 | cursor to string. |
zfaB | 35 |Fold the current block delimited by bracket BB can be any of ()[]{}<>. This feature 37 | understands nested blocks, too, so will usually do 38 | the right thing. | 39 |
For instance, zf4j creates a fold from the current line to the 43 | forth line down. Or, if you've selected 44 | text in 45 | Visual mode, then zf will fold the selection.
46 | 47 |How you use folds will depend very much on the type of file you are 50 | editing. They are particularly useful for long papers or essays, for 51 | instance, where you fold each section so as to navigate the document 52 | hierarchically. When editing program source code they can be used with 53 | function/method/class declarations.
54 | 55 |This recipe is entitled Manually Creating Folds, because there are 56 | other approaches to folding which are automatic. A particularly useful method, 57 | indentation folding, is described below. In addition, most programming 58 | languages support syntax folding. Try it out by opening some source 59 | code in Vim then executing :set foldmethod=syntax.
60 | 61 |62 | 63 |77 | 78 |Indentation Folding
64 | 65 |If you're working with structured, indented text you may prefer to use 66 | indentation folding.
67 | 68 |Enable it with :set foldmethod=indent. Folds are now 69 | automatically created for each level of indented text. (To indent simply 70 | start a line with a <Tab>Each 71 | shiftwidth of indent corresponds to one fold. See the Indenting Lines recipe for 73 | details. So, for example, zM folds all indented 74 | text.
75 | 76 |
To expand, collapse, and otherwise navigate folds see Navigating Folds.
80 | -------------------------------------------------------------------------------- /text/07_navigation/08_navigating_folds.html: -------------------------------------------------------------------------------- 1 |Your document contains folds and you want to use them for 6 | navigation. (To create folds see Manually Creating 8 | Folds).
9 | 10 |Command | 15 |Action | 16 |Mnemonic | 17 |
---|---|---|
zc | 20 |Close the current fold. | 21 |close fold | 22 |
zo | 25 |Open the current fold. | 26 |open fold | 27 |
zM | 30 |Close all folds. | 31 |fold More | 32 |
zr | 35 |Open one level of folds. | 36 |reduce folding | 37 |
zR | 40 |Open all folds. | 41 |Reduce folding | 42 |
zj | 45 |Move to the next fold. | 46 |j moves to the next line | 47 |
zk | 50 |Move to the previous fold. | 51 |k moves to the previous line | 52 |
zm | 55 |Close one level of folds. | 56 |Fold more | 57 |
zn | 60 |Disable folding. | 61 |no folds | 62 |
zN | 65 |Re-enable folding. | 66 |N is n toggled | 67 |
You can use zM to achieve a birds-eye view of the file, which 73 | can be useful when you're writing a long book and forget how the recipe you're 74 | currently writing relates to…
75 | 76 |Vim treats folds like individual lines, so j and k 77 | move over one fold at a time. Further, you can yank/deleteyank is Vim terminology for copying text to the clipboard; 79 | see Copying, Cutting, and 81 | Pasting. a fold as if it was a single line.
82 | 83 |By default, folds are forgotten when you edit another file. To save them 84 | use :mkview. Then, to restore them, use :loadview.
85 | 86 |The :set foldcolumn=W command, where W is a 87 | integer width less than 13, displays a column along the left-hand side of the 88 | screen with information about the folds in the current file. It indicates 89 | whether the corresponding line is an open or closed fold (with - or 90 | +, respectively).
91 | -------------------------------------------------------------------------------- /text/07_navigation/09_splitting_the_screen.html: -------------------------------------------------------------------------------- 1 |You want to view multiple files at one time. Or, you want to view different 6 | positions in the same file at the same time.
7 | 8 |For example, if you were editing source code in an unfamiliar programming 9 | language, you may want to have the documentation and source visible at the 10 | same time. Or, if you wanted to move text between multiple files, you could 11 | view the source and target file together.
12 | 13 |Use Vim's split screen feature to divide the screen into multiple panes, 16 | each of which can display a file.
17 | 18 |Command | 21 |Action | 22 |
---|---|
:split file | 25 |Splits the window horizontally. | 26 |
:vsplit file | 29 |Splits the window vertically. | 30 |
(If file is specified, that file is shown in the upper/left, as 34 | appropriate, pane; if not, both panes show the current file).
35 | 36 |To move between windows you use 37 | <Ctrl>-w (mnemonic: control 38 | window). To move in a specific direction, add the relevant movement key. So, to move upwards: 40 | <Ctrl>-w+k.
41 | 42 |To close the active window use :q, just as you would to close a 43 | window normally.
44 | 45 |You can reduce/enlarge the size of the current window with 46 | <Ctrl>-w+- and 47 | <Ctrl>-w++, respectively. To 48 | specify the size of a window when you open it, prefix the :split 49 | command with the desired height/width in lines. For example, to show 50 | README in a window of 5 lines high: :5 :split README.
51 | 52 |The default behaviour of both :split and :vsplit is to 55 | show the current file twice. This is more useful than it may first sound.
56 | 57 |When working with long documents it means that you can view the top and 58 | bottom of the file simultaneously. If you use folding you can use one window to 60 | display an outline of a document while editing a specific section in another. 61 | For example, when I'm working on reports I use :30 :vsplit to view 62 | the first and second level headings along the left of the screen, while 63 | editing the report in the main window.
64 | 65 |By default the windows will scroll independently of each other. If you 66 | :set scrollbind before you split the screen the windows scroll 67 | together.
68 | -------------------------------------------------------------------------------- /text/07_navigation/10_navigating_marks.html: -------------------------------------------------------------------------------- 1 |You want to bookmark specific points in a file so you can easily 6 | jump to them from elsewhere.
7 | 8 |Use Vim's marks feature. A mark is a character in the range 11 | a-zA-Z0-9. It's represented in the examples below as M.
12 | 13 |Command | 16 |Action | 17 |
---|---|
mM | 20 |Mark the current position as M. | 21 |
'M | 24 |Jump to the first character of the line containing M. | 25 |
`M | 28 |Jump to the position of mark M. | 29 |
Marks 0-9 are mainly for Vim's internal use, so ignore them. Marks 35 | a-z are only available in the current file, and are deleted when it is 36 | closed. Marks A-Z are available across multiple files. If your 37 | .viminfo file is available, as it usually will be, they persist 38 | across sessions.
39 | 40 |Marks have a multitude of uses. I use them often when I have a section of a 41 | file that I need to keep referring to: I mark that section with ma, 42 | jump to it with 'a, then return to where I was previously with 43 | ``. I use them almost implicitly when formatting and 44 | filtering text to define the text that I want to edit.
45 | 46 |The :marks command shows a list of marks you have set, which is 47 | useful for the kind of person who fully embraced the idea of marking anything 48 | and everything but was unable to remember the significance of all 52 marks he 49 | used.
50 | -------------------------------------------------------------------------------- /text/07_navigation/11_navigating_tags.html: -------------------------------------------------------------------------------- 1 |You're working on a project where you need to jump between occurrences of 6 | significant keywords, which are possibly spread across multiple files.
7 | 8 |For example, you're writing source code and want to be able to type a 9 | function name then quickly jump to where it was initially defined so you 10 | understand how it should be used. Then you want to return to where you 11 | were.
12 | 13 |Use tags. Tags are similar to index entries in a book: significant 16 | terms are linked to the key places that they occur.
17 | 18 |We will use a program called Exuberant Ctags to generate 20 | the tag list because it is compatible with popular programming languages such 21 | as C, C++, Java, Lisp, Perl, PHP, Python, and Ruby.
22 | 23 |After you have installed Ctags you can generate a tag list for the current 24 | directory (and its sub-directories) with ctags -R. To only consider 25 | files in the current directory use ctags *. This will generate a tag 26 | list for source code in most common languages.
27 | 28 |You can now open a source file from that directory and use the :tag 29 | tag command to jump to the definition of the tag. To look up 30 | the tag under the cursor use <Ctrl>+]. 31 | You can also auto-complete tag names by starting to type one then using 32 | <Tab> to cycle through the list of matching tags. To return 33 | to where you were before you jumped to a 34 | tag you use <Ctrl>+t.
35 | 36 |So far, we have only described tags in terms of program source code, but 39 | they are by no means limited to this domain. The Vim help system uses tags 40 | extensively to allow navigation. When you use :help term 41 | you're actually looking up a tag in the documentation tag file. When you 42 | position your cursor over a highlighted entry in a help file, you use 43 | <Ctrl>+] to follow it. This is all 44 | possible because as long as you have a way of identifying significant terms in 45 | a file, you can generate a tags list for it. For example, here's an excerpt 46 | from the tags documentation:
47 | 48 |49 | *tags-option* 50 | The 'tags' option is a list of file names. Each of these 51 | files is searched for the tag. This can be used to use a 52 | different tags file than the default file "tags". It can 53 | also be used to access a common tags file. 54 |55 | 56 |
The tags-option syntax is used for defining a tag. Elsewhere, the 57 | |tags-option| syntax is used for linking to a tag. You can use 58 | :helptags dir for generating a taglist for all 59 | *.txt files in the given directory which are marked up in this 60 | way.
61 | 62 |However you generate it, the tag list is a static file, so it must be 63 | regenerated when your files change significantly. In programming projects, it 64 | is typical to update the tags file during the build process. For example, the 65 | Makefile could execute ctags.
66 | 67 |Both invocations of ctags given above are very liberal in what 68 | they index. They search for all programming language source code in the 69 | specified directories, and incorporate all the tags found therein into a 70 | single tags file. To limit ctags to just Ruby source code, for 71 | example, you can use ctags *.rb. For more control over what files 72 | ctags considers, consult its documentation. On Linux: man 73 | ctags.
74 | 75 |Once you have generated the tags file Vim needs to be able to find it. By 76 | default it looks for a file named tags in the current directory, but 77 | for projects which span multiple directories this is not always suitable. You 78 | can specify the location of the tags file using :set 79 | tags=file. Specify multiple tag files by separating the 80 | paths with commas. Instruct Vim to search for a tags file recursively with 81 | :set tags=./tags;/.
82 | 83 |Using <Ctrl>+] to jump to a new tag 84 | takes you to a new buffer to show the results. If you'd rather see them in a 85 | new window use <Ctrl>+W+], 86 | or :stag 87 | tag.
88 | 89 |If you get dizzy after all this jumping around you can reacquaint yourself 90 | with where you've been by using the :tags command. This shows you 91 | which tags you've jumped to, and where you jumped to them from.
92 | -------------------------------------------------------------------------------- /text/07_navigation/12_bookmarking_lines_with_visible_markers.html: -------------------------------------------------------------------------------- 1 |You want to assign visible marks to the margins of certain lines.
7 | 8 |For example, you're using Vim as an IDE and want breakpoints to be clearly marked. Or, you 10 | want to label lines in need of editing with a question mark icon.
11 | 12 |Vim allows you to define a sign and then associate it with one or 15 | more lines of a file. It is displayed in the right-hand margin as a 16 | two-character string in the terminal, and an icon in Gvim.
17 | 18 |Before you use a sign you must define it. For example:
19 | 20 |:sign define fixme text=!! linehl=Todo texthl=Error icon=/path/to/todo.xpm
21 |
22 | Let's break this down. We name the sign fixme, which is how we'll 23 | refer to it later. We specify that in the terminal the sign should be 24 | displayed as !!, and that in the GUI the icon stored at 25 | /path/to/todo.xpm should be used instead. The linehl argument 26 | defines the highlight group used for the entire line the sign is attached to; 27 | texthl defines the highlight 28 | group for the sign itself.
29 | 30 |Now the sign is defined, presumably in vimrc, you can use it 32 | in any file. To attach the sign to a specific line you use:
33 | 34 |:sign place id line=line name=name
35 | file=file-path
36 |
37 | For example:
38 | 39 |:sign place 22 line=200 name=fixme file=/home/user/novel.txt
40 |
41 | The id is arbitrary, but must be unique and numeric. The 42 | name is the same name you used when you defined the sign. The value 43 | of the line argument is the number of the line on which the sign 44 | should be attached. The file argument is the full path (no 45 | expansion is done) to a currently loaded file to which the sign should be 46 | attached. So, in the above example, two exclamation marks are inserted in the 47 | margin of the 200th line of /home/user/novel.txt.
48 | 49 |You only need to define signs once, so that's easy enough, but the syntax 52 | for placing signs is particularly unwieldy. Let's look at some alternative 53 | approaches.
54 | 55 |You could place the following stanza in your vimrc so 56 | <F5> places the previously defined fixme sign on the 57 | current line of the current file:
58 | 59 |function! SignFixme()
60 | execute(":sign place ".line(".")." line=".line(".")." name=fixme file=".expand("%:p"))
61 | endfunction
62 | map <F5> :call SignFixme()<CR>
63 |
64 | Rather than placing signs manually, you may prefer to have them 65 | automatically placed on lines satisfying some criteria. The following stanza 66 | attaches the fixme sign to lines containing notes like TODO: check 67 | for race conditions. It operates on the current line or selection. So, 68 | you can select a range of lines, press <F6> then have your 69 | to-do list items flagged in the margin.
70 | 71 |function! SignLines() range
72 | let n = a:firstline
73 | execute(":sign define fixme text=!! texthl=Todo")
74 | while n <= a:lastline
75 | if getline(n) =~ '\(TODO\|FIXME\)'
76 | execute(":sign place ".n." line=".n." name=fixme file=".expand("%:p"))
77 | endif
78 | let n = n + 1
79 | endwhile
80 | endfunction
81 | map <F6> :call SignLines()<CR>
82 |
--------------------------------------------------------------------------------
/text/08_gui/00.html:
--------------------------------------------------------------------------------
1 | You want to display the text in a different font.
6 | 7 |For example, the current font isn't particularly readable, or is too large.
8 | 9 |Standard Vim uses the font from the terminal it is run under. Gvim, 12 | however, gives you full control over the font face and size.
13 | 14 |The command :set guifont font-name changes the current 15 | font to font-name. The font name can be followed by a size. There 16 | are, unfortunately, some platform-specific differences at this 17 | point…
18 | 19 |20 | 21 |53 | 54 |Specifying guifont in an Operating-System-Specific Manner
22 | 23 |Linux
24 | 25 |26 |
29 | 30 |- The font name and size are space separated.
27 |- Spaces and commas need to be backslash escaped.
28 |For example: :set guifont=Andale\ Mono\ 11.
31 | 32 |Mac
33 | 34 |35 |
39 | 40 |- The font name and size are colon separated.
36 |- The size is prefixed with a h.
37 |- Spaces and commas need to be backslash escaped.
38 |For example: :set guifont=Monaco:h11. 41 | 42 |
Windows
43 | 44 |45 |
49 | 50 |- The font name and size are colon separated.
46 |- The size is prefixed with a h.
47 |- Spaces in font names can be replaced with underscores (_).
48 |For example: :set guifont=Andale_Mono:h11.
51 | 52 |
To change the font you need to know its name. On most operating systems you 57 | can request a GUI font chooser with the command :set guifont=*. Linux 58 | users can also use the xlsfonts utility to see a list of available 59 | fonts.
60 | 61 |If the font you've specified can not be found, Vim complains. To avoid this 62 | you can specify multiple fonts in order of preference with a comma separated 63 | list. The first valid font is loaded. For example: :set 64 | guifont=Screen15,\ 7x13. This approach is particularly useful if you 65 | use your Vim configuration on multiple computers, or if you simply want it to 66 | be portable.
67 | -------------------------------------------------------------------------------- /text/08_gui/02_maximising_screen_space.html: -------------------------------------------------------------------------------- 1 |The toolbar, menubar, and other GUI artifacts take up too much of your 6 | screen; you want to hide them.
7 | 8 |Modify the guioptions variable. Gvim decides which elements of the 11 | GUI to display based on the value of guioptions. This is a series of 12 | letters, each of which refer to some specfic element. Some examples 13 | follow:
14 | 15 |So, to hide the menu bar, toolbar, and scrollbars you could use :set 28 | guioptions-=mTrlb. To display a hidden element use += instead, 29 | e.g. :set guioptions+=T.
30 | 31 |If you decide that you want to restore one or more of these elements you 34 | can simply execute :set guioptions+=m, for example. This can be 35 | cumbersome, however, as it requires you to remember the significance of each 36 | letter.
37 | 38 |The following stanza in your gvimrc 39 | assigns <F11> to toggle the display of extraneous GUI 40 | elements:
41 | 42 |function ToggleGUICruft()
43 | if &go==''
44 | exec('se go=mTrL')
45 | else
46 | exec('se go=')
47 | endif
48 | endfunction
49 | map <F11> <Esc>:call ToggleGUICruft()<cr>
50 |
--------------------------------------------------------------------------------
/text/08_gui/03_creating_menus_and_toolbar_buttons.html:
--------------------------------------------------------------------------------
1 | You want to add your own commands to Gvim's menus, or toolbar, for quick 6 | access.
7 | 8 |For example, you've written a function that automatically writes 9 | bestselling novels for you, but you're not willing to use it if you have to 10 | type its name every time; you want to invoke it by selecting a menu option. 11 |
12 | 13 |Use :set amenu menu command to map a menu 16 | item to a command. This is the GUI equivalent of :map.
18 | 19 |For example, :amenu Help.Op&ions :help options<cr> adds 20 | a new item called Options to the Help menu, which invokes 21 | :help options. The ampersand (&) signifies that the 22 | character it prefixes can be used as a keyboard shortcut, so in this case 23 | <Alt>+h+t selects this 24 | command.
25 | 26 |You're not restricted to adding items to existing menus; you can create a 29 | new top-level menu simply by specifying a name not currently in use. For 30 | example:
31 | 32 |:amenu <silent>&Vim.vim\.org :!xdg-open http://www.vim.org/<cr>
33 |
34 | will create a new top-level menu called Vim with the shortcut key 35 | V. It will contain one entry named vim.org (we escape the 36 | . because otherwise it would create a vim entry which in turn 37 | contain an org item). When invoked it will open the Vim website on 38 | systems adhering to the Free Desktop Specification. The 39 | <silent> prefix prevents the command from being echoed on the 40 | command-line.
41 | 42 |If you want to add a dashed separator line between menu items use a menu 43 | item named -SEP- and an empty command, e.g. :amenu Help.-SEP- 44 | :.
45 | 46 |To control where a top-level menu appears relative to its neighbours you 47 | need to prefix amenu with a numeric priority: the lower the number 48 | the further right the menu's position. For example, :5amenu First.first 49 | :echo 'first'<cr> creates a top-level menu named First 50 | that appears before all of the others.
51 | 52 |The same approach can be used to position menu items. For example, 53 | :amenu 9999.1 Help.first :echo 'first'<cr> adds a first 54 | item to the Help menu, which appears before the other items.
55 | 56 |You can also use :amenu to add a new toolbar icon:
57 | 58 |:amenu icon=image-path Toolbar.item-name
59 | command
60 |
61 | For example:
62 | 63 |:amenu icon=options.png ToolBar.OptionsHelp :help<cr>
64 |
65 | If the image-path consists only of a filename, as above, Vim prepends 66 | $VIMRUNTIME/bitmaps/ to it.
67 | -------------------------------------------------------------------------------- /text/09_searching/00.html: -------------------------------------------------------------------------------- 1 |You want to search the current file for an arbitrary word.
6 | 7 |Use /word to search forward in the file; 10 | ?word to search backward.
11 | 12 |You can use incremental (find-as-you-type) search by using the 15 | :set incsearch option. Having done so, your cursor will move to the 16 | first match as you enter your query. This enables you to receive feedback on 17 | the effectiveness of your query. Once satisfied with your query, press 18 | <Enter> to run it. If you were interested more in the erratic 19 | cursor movement than searching, pressing <Esc> will cancel 20 | the search and return to where you began.
21 | 22 |You're not limited to finding literal strings; word can also be 23 | a regular expression. For 24 | example /^[A-Z] searches for lines beginning with capital 25 | letters.
26 | 27 |To repeat your search use // or ??.
28 | 29 |After finding the first match using either of the above methods, you can 30 | press the n (mnemonic: next match) key to jump to the next 31 | match. To jump to the previous match, use N.
32 | -------------------------------------------------------------------------------- /text/09_searching/02_searching_over_multiple_files.html: -------------------------------------------------------------------------------- 1 |You want to search for a particular term in a collection of files. For 6 | example, you want to find the files in your project that mention Mr J. 7 | Random.
8 | 9 |Use the :vimgrep command: :vimgrep /pattern/ 12 | [flags] file0 file1 13 | fileN.
14 | 15 |In its simplest form, vimgrep takes a word to search for, and a 18 | list of files in which to do so. So, to search for grapes in 19 | shopping-list.txt you'd run :vimgrep /grapes/ 20 | shopping-list.txt.
21 | 22 |You can name as many files as you like, but you'll probably want to use 23 | shell globbing, see the sidebar for details, instead to specify groups 24 | of files. Searching for grapes in all *.txt files could be 25 | accomplished with: :vimgrep /grapes/ *.txt.
26 | 27 |28 | 29 |45 | 46 |Globbing
30 | 31 |A number of Vim commands support filename globbing. This is a way of 32 | selecting a group of files by specifying a pattern matching their names. For 33 | example, *.txt refers to all files in the current directory whose 34 | names end in .txt. The * is a wildcard and means 35 | anything.
36 | 37 |** recursively matches directories below the current one, so 38 | **/*.txt searches recursively downwards from the current directory 39 | for filenames ending in .txt.
40 | 41 |If your operating system supports additional globbing patterns, you can use 42 | these as well.
43 | 44 |
You're not restricted to searching on simple words, however. You can use 47 | any of Vim's regular expressions 48 | between the forward slashes. Searching /tmp/bar.txt and 49 | ~/foo.tex for lines starting with numbers: :vimgrep /^[0-9]/ 50 | /tmp/bar.txt ~/foo.tex.
51 | 52 |vimgrep jumps to the first match it finds. To jump to the next match 53 | use :cn; use :cN for the previous.
54 | 55 |56 |62 | 63 |If you use :grep instead of :vimgrep an external 57 | grep-like utility is used to perform the search. The program used 58 | is the value of &grepprg. A good choice is Andy Lester's ack which can be used with 60 | set grepprg=ack and set grepformat=%f:%l:%m.
61 |
The j flag inhibits the jumpiness (Ritalin for Vim); 64 | simply saving the search results to the quickfix list (see sidebar for 65 | details) and leaving your cursor where it was.
66 | 67 |The g flag controls how lines matching the pattern multiple times are 68 | handled. If not present (by default), only the first match of a line is shown; 69 | otherwise, every occurrence of the pattern is regarded as a separate match.
70 | 71 |The flags can be combined in either order.
72 | 73 |74 | 75 |Quick Fix List
76 | 77 |The quick fix list mentioned above is a Vim concept for creating a 78 | temporary index of positions in a file. vimgrep stores its results (a 79 | file name, a position within that file, and the matched text) in the quick fix 80 | list.
81 | 82 |To view the quick fix list (i.e. the results of the last search) use 83 | :cl[ist]. The results are numbered, so you can jump to a specific one with 84 | :cc number.
85 | 86 |For more information see :help quickfix.
87 | 88 | -------------------------------------------------------------------------------- /text/09_searching/03_searching_and_replacing.html: -------------------------------------------------------------------------------- 1 |Searching and Replacing
2 | 3 |Problem
4 | 5 |You want to replace all occurrences of one string with another.
6 | 7 |For example, imagine you were using Vim to write a novel wherein there was 8 | a protaganist named Curtis. You decide to change his name to 9 | Excalibur to give him more panache. You want Vim to make these changes 10 | with the least possible effort.
11 | 12 |Solution
13 | 14 |Execute :%s/target/replacement/g to replace 15 | all occurrences of target with replacement. For example: 16 | :%s/Curtis/Excalibur/g.
17 | 18 |Description
19 | 20 |The solution above replaces Curtis with Excalibur. The 21 | g flag at the end causes this operation to be performed 22 | globally, i.e. multiple times on each line, if necessary.
23 | 24 |The % prefix indicates that the replacement should occur over the 25 | entire file. Had you previously visually selected text to which you want to 26 | constrain the search/replace operation omit the %, e.g. 27 | :s/Curtis/Excalibur/g. Or, prefix the command with a range to 28 | contstrain it that way, e.g. 2,20s/Curtis/Excalibur/g performs the 29 | operation over lines two to twenty.
30 | 31 |The search string (Curtis in this example) doesn't have to be a 32 | literal string; it can be any Vim regular expression. The details of Vim's 33 | regular expressions are explained in the Creating Regular Expressions 35 | recipe, so I won't go into them here. Two tips, though:
36 | 37 |38 |
49 | -------------------------------------------------------------------------------- /text/09_searching/04_searching_for_the_word_beneath_the_cursor.html: -------------------------------------------------------------------------------- 1 |- Search for words - If you provide a literal string to replace, as above, 39 | Vim even replaces occurrences that form parts of other words. For example 40 | :%s/and/or/g would change supply and demand into supply 41 | or demor. To avoid this, surround the string with word boundary 42 | anchors (\<, \>). Thus, the above command 43 | could be rewritten as :%s/\<and\>/or/g.
44 |- Search case insensitively - If you want linux to match 45 | Linux, linux, and LiNuX you need to either add the 46 | i flag to the end of the replacement command, or, use :set 47 | ignorecase to enable this behaviour for all searches.
48 |Searching for the Word Beneath the 2 | Cursor
3 | 4 |Problem
5 | 6 |You want to search the current document for the word underneath your cursor. 7 | You'd rather not type it in again.
8 | 9 |Solution
10 | 11 |In Normal mode, place your cursor on or just in front of the word 12 | you wish to find, then press * (mnemonic: star search). This will 13 | jump to the next occurrence of the word in the current file. 14 | Alternatively, pressing # will find the previous 15 | occurrence.
16 | 17 |Discussion
18 | 19 |After finding the first match using either of the above methods, you can 20 | press the n (mnemonic: next match) key to jump to the next 21 | match. To jump to the previous match, use N.
22 | 23 |To search for words containing the current word, press g* 24 | or g#, as appropriate. For instance, if the current word is 25 | back, g* will jump to hunchback.
26 | -------------------------------------------------------------------------------- /text/09_searching/07_looking_up_docs_for_the_word_beneath_the_cursor.html: -------------------------------------------------------------------------------- 1 |Looking up Documentation for the Keyword Under the Cursor
2 | 3 |Problem
4 | 5 |You want to invoke an external command to lookup documentation for the 6 | keyword underneath the cursor. For example, Linux users may like to read the 7 | manual for the named command with the man utility.
8 | 9 |Solution
10 | 11 |Use :set keywordprg=program, then hit K while hovering 12 | over the word.
13 | 14 |Discussion
15 | 16 |This recipe calls the command specified with :set keywordprg, 17 | passing the current wordword is used in the sense of a 18 | string that looks like a word to Vim; it is not necessarily a valid word in 19 | your language. as an argument. Thus, if keywordprg = 20 | man, then hovering over the word ls and hitting K 21 | would display the documentation for Linux's ls command.
22 | 23 |When used with man, Vim translates a count for the K 24 | command into a section number. So 7K over glob invokes 25 | man 7 glob to display section 7 of the glob 26 | documentation.
27 | 28 |The Ruby programming language has a utility called ri that displays 29 | documentation about the given Ruby method. The Perl programming language has a 30 | similar command called perldoc. By setting keywordprg 31 | appropriately, you can make context-sensitive documentation lookup 32 | trivial.
33 | -------------------------------------------------------------------------------- /text/10_display/00.html: -------------------------------------------------------------------------------- 1 |Display
2 | -------------------------------------------------------------------------------- /text/10_display/01_working_with_long_lines.html: -------------------------------------------------------------------------------- 1 |Working with Long Lines
2 | 3 |Problem
4 | 5 |Your file contains lines which are too long to fit on the screen. You find 6 | it hard to edit and view.
7 | 8 |Solution
9 | 10 |The :set wrap command, which should be on by default, changes how 11 | long lines are displayed. Once they reach the right margin they are broken, 12 | and continued on the line below. (To disable this behaviour: :set 13 | nowrap).
14 | 15 |wrap only changes the way the lines are displayed, however; the 16 | file will not be changed. It inserts soft line breaks.
17 | 18 |This means that a file containing two particularly long lines may be 19 | represented by Vim as having 5 lines, for example, after wrapping. If you try 20 | to navigate this file using the basic movement 21 | commands j would move between the two logical lines, rather 22 | than the screen lines. The solution is to prefix the movement commands 23 | with g, so gj moves down one screen line.
24 | 25 |If using wrap, you can specify what point the line should be 26 | broken by executing :set linebreak. This uses the value of 27 | breakat to decide where to break the line. To change the characters 28 | used modify breakat.
29 | 30 |You can use :set textwidth=width to enforce a maximum 31 | line length, after which the text is broken with a "hard" line break. Vim 32 | breaks at white space, so lines may be shorter than width. To 33 | reformat existing text according to this preference either select them 34 | visually and hit gq or, in Normal mode, you can reformat the 35 | current paragraph with gqap.
36 | 37 |Discussion
38 | 39 |In general, you'll be better off using hard line breaks with 40 | textwidth. This removes the need to differentiate between logical lines 41 | and screen lines, and means that the file will display reasonably in any 42 | editor, even if it doesn't wrap long lines.
43 | 44 |Traditionally, text file lines are kept under 80 characters. This is 45 | mainly a holdover from the days of terminals whose displays were limited in 46 | this way, but is still customary in many programming languages and e-mail. To 47 | enforce this restriction just :set textwidth=80.
48 | 49 |There's another way to insert hard line breaks without specifying a maximum 50 | line length. It is called wrapmargin and wraps lines relative to the 51 | width of the terminal window. For example, :set wrapmargin=4 means 52 | that when a line is more than four characters away from the right-hand margin, 53 | it is broken. This approach is more flexible than textwidth, but has 54 | the disadvantage of producing files which will display poorly on smaller 55 | displays or when the screen is split between multiple files. Especially if 56 | you're sharing the files you produce with others, I suggest the use of 57 | textwidth instead.
58 | 59 |60 |64 | -------------------------------------------------------------------------------- /text/10_display/02_displaying_line_numbers.html: -------------------------------------------------------------------------------- 1 |textwidth takes precedence over wrapmargin. For 61 | wrapmargin to take effect textwidth must be zero, as it 62 | is by default.
63 |Displaying Line Numbers
2 | 3 |Problem
4 | 5 |You want to see each line's number alongside it. For example, if you’re 6 | writing a program, error messages frequently reference line numbers.
7 | 8 |Solution
9 | 10 |Use :set number to enable line numbering. If you're using a small 11 | monitor, you may want to disable them: :set nonumber.
12 | 13 |Discussion
14 | 15 |Even if you're not programming, line numbers can still be useful. For 16 | example, if you’re collaborating on a file with other people, they may mention 17 | specific lines, which you can then jump to with :number. 18 | If you’re wrapping long lines, the line 19 | number can be used to differentiate the beginning of the line from the point 20 | at which it has been wrapped.
21 | 22 |By default the number column is at least 4 characters wide, regardless of 23 | how many lines the file has. To change this minimum width use :set 24 | numberwidth=width.
25 | 26 |The line numbers are only displayed when you’re viewing the file with Vim; 27 | the actual file isn't modified. If you'd like it to be, and you have the 28 | cat command on your system, you can execute :%!cat -n %. 29 | This filters the entire file through cat and prepends the number to 30 | each line.
31 | 32 |Lastly, if you'd like to see the line numbers when you print the file 33 | without permanently changing its contents: :set 34 | printoptions=number:y.
35 | -------------------------------------------------------------------------------- /text/10_display/03_working_with_remote_files.html: -------------------------------------------------------------------------------- 1 |Working with Remote Files
2 | 3 |Problem
4 | 5 |You want to edit/view a file that is stored on another computer.
6 | 7 |For example, you might want to change a file on your website from your home 8 | computer. Or, you want to change the message of the day file on a 9 | server you administer.
10 | 11 |Solution
12 | 13 |To invoke Vim with a remote file use its URL as the argument to 14 | vim. For example: vim 15 | sftp://guest@example.com/file.txt.
16 | 17 |To work with remote files from within Vim, just use their URLs in place of 18 | a filename with normal editing commands.
19 | 20 |So, to to open a remote file for editing use :e URL. 21 | For example: :e ftp://user@example.com/README.
22 | 23 |To save to a remote file use :w URL. For example: 24 | :w scp://kci@jojo.example.com/etc/motd.
25 | 26 |Discussion
27 | 28 |Vim supports the following protocols: SCP, SFTP, RCP, HTTP (read-only), WebDAV, 33 | rsync (read-only), and fetch (read-only). However, it relies on 34 | external programs to do so. On Linux, most of these programs are available by 35 | default; on Windows, for example, only FTP is normally 37 | available. See :help netrw-externapp for more information.
38 | 39 |If the protocol requires authentication, you can supply the username as 40 | part of the URL, and then be prompted for the password interactively. This 41 | gets boring fast, however.
42 | 43 |If you're editing files via SSH or SCP consider setting up passwordless 45 | logins. The principle is explained in Password-less 47 | logins with OpenSSH for Debian Linux, but it is much for the same 48 | for other operating systems.
49 | 50 |If you're using FTP on Linux, you can store your credentials in 51 | ~/.netrc'. The file is formatted as 52 | follows:
53 | 54 |60 | 61 |machine {host name 1} 55 | login {username} 56 | password {password} 57 | 58 | machine {host name 2} 59 | ...
It should be made read-only for your user: chmod 600 ~/.netrc 62 | Windows explanation?. Now you can use URLs like 63 | ftp://example.org/README, and it will find your username and password 64 | automatically.
65 | 66 |67 |70 | -------------------------------------------------------------------------------- /text/10_display/04_changing_the_status_line.html: -------------------------------------------------------------------------------- 1 |⚠ FTP is an insecure protocol, so please don't use it unless you must. 68 | SSH/SFTP/SCP are all superior alternatives.
69 |Changing the Status Line
2 | 3 |Problem
4 | 5 |You don't like the way the status line looks or would prefer if it displayed 6 | different types of information.
7 | 8 |For example, you work with files created on different operating systems, so 9 | you'd like the file format (e.g. unix, MS-Windows, or 10 | mac) to be displayed along the bottom of the screen.
11 | 12 |Solution
13 | 14 |Use the :set statusline command along with a format string. The format 15 | string is the text you want displayed interspersed with variable names 16 | corresponding to the types of information you want included.
17 | 18 |19 |22 | 23 |By default Vim hides the status line. To show it: :set 20 | laststatus=2.
21 |For example, to display the file format you could use :set 24 | statusline=%{&ff}. You can surround this with arbitrary text, for example: 25 | :set statusline=format:\ %{&ff}.
26 | 27 |Here are some common variables the status line can display:
28 | 29 |30 |
41 | 42 |31 | Name Description 32 | b Value of byte under cursor. 33 | c Column number. 34 | l Line number. 35 | r Displays [RO] if file is read only. 36 | t File name (as opposed to file path) 38 | y File content type, e.g. [ruby] or 37 | [latex]. 40 | \&ff File format, e.g. unix, mac, 39 | dos. Variable names are prefixed with a percentage sign (%). Spaces, 43 | bars (|), and other special characters need to be backslash 44 | escaped.
45 | 46 |Here's a longer example:
47 | 48 |49 | 50 |:set statusline=%t\ %y\ format:\ %{&ff};\ [%c,%l]
Sample output: .vimrc [vim] format: unix [2,3].
51 | 52 |Discussion
53 | 54 |You may have noted that the syntax for displaying the file format was 55 | different from the other variables. The %{} syntax evaluates the 56 | expression contained within the braces and displays the result.
57 | 58 |For example, to display the name of the current colour scheme: 59 | %{g:colors_name} (example output: morning). Or the 60 | current language: %{v:lang} (example output: 61 | en_GB.UTF-8). Here we are simply displaying the value of Vim 62 | internal variables. (See :let for a list).
63 | 64 |The reason %{&ff} works is because ff is the Vim 65 | option for getting/setting the file format, and the & prefix is 66 | used for referring to options. The value of any option can be displayed in 67 | this way.
68 | 69 |You can even call a function in this way. For example, to show the last 70 | modification time of the current file:
71 | 72 |73 | 74 |\%{strftime(\"\%c\",getftime(expand(\"\%\%\")))}
Sample output: Fri 01 May 2009 19:26:07 BST
75 | -------------------------------------------------------------------------------- /text/10_display/05_redefining_highlight_groups.html: -------------------------------------------------------------------------------- 1 |Redefining Highlight Groups
2 | 3 |Problem
4 | 5 |You want to change the colours of specific elements of the display. For 6 | example, you want text to be white on a black background.
7 | 8 |Solution
9 | 10 |Use the :highight group definition command.
11 | 12 |A highlight group (group) is an element of the display 13 | whose colours can be customised. Some of the default highlight groups are:
14 | 15 |Is a list the right way to present this?
16 | 17 |18 |
27 | 28 |- Cursor
19 |- Character under the cursor.
20 |- ErrorMsg
21 |- Command line error messages.
22 |- Normal
23 |- Normal text.
24 |- Visual
25 |- Text selected under Visual mode.
26 |The definition is a list of key-value pairs. For example, the 29 | following sets the terminal foreground colour to black and 30 | the terminal background colour to yellow:
31 | 32 |33 | 34 |:highlight Normal ctermfg=black ctermbg=yellow
These are some common arguments:
35 | 36 |37 |
49 | 50 |- ctermfg
38 |- Terminal foreground colour.
39 |- ctermbg
40 |- Terminal background colour.
41 |- term
42 |- Terminal font style, e.g. bold, italic, 43 | underline.
44 |- guifg
45 |- GUI foreground colour.
46 |- guibg
47 |- GUI background colour.
48 |Apart from term, these arguments take a colour name or number as a 51 | value. Recognised colour names include black, brown, 52 | grey, blue, green, cyan, magenta, 53 | yellow, and white.
54 | 55 |The arguments that are not supplied retain their previous values. For 56 | example, :highlight Normal\ ctermbg=white changes the background 57 | colour to white, but keeps the previous foreground colour.
58 | 59 |Let's look at some examples:
60 | 61 |62 |
67 | 68 |- :highlight Visual term=bold - Text that has been selected using 63 | Visual mode is rendered in bold.
64 |- :highlight Comment ctermfg=grey ctermbg=white term=bold - 65 | Comments are rendered in bold, grey text.
66 |Discussion
69 | 70 |Normally you'll select a colour 71 | scheme, and not define highlighting groups at all. Occasionally, though, 72 | you want more control over colours or need to edit a syntax file. That's 73 | where the :highlight command comes in.
74 | 75 |Before you change highlight groups you may like to check their current 76 | values. You can do this with :highlight group. To view 77 | all current settings use :highlight.
78 | 79 |80 | 81 |95 | -------------------------------------------------------------------------------- /text/10_display/06_modifying_the_cursor.html: -------------------------------------------------------------------------------- 1 |Defining a Highlight Group
82 | 83 |You can define your own highlight group by using the :highlight 84 | command as described above with a group name of your choice. To select what is 85 | highlighted you use :match group 86 | /pattern/. For example:
87 | 88 |90 | 91 |:highlight Elephant ctermbg=grey ctermfg=white 89 | :match Elephant /\celephant/
This renders all occurrences of the word elephant, regardless of 92 | case due to the \c escape, in white on grey. 93 | 94 |
Modifying the Cursor
2 | 3 |Problem
4 | 5 |You want to make the cursor easier to see.
6 | 7 |For example, you're using visually “busy” syntax highlighting, 8 | and sometimes lose the cursor. Or, you're working with columnar data, and need 9 | the entire column that the cursor is over to be highlighted.
10 | 11 |Solution
12 | 13 |To change the cursor colour in Gvim redefine the Cursor highlighting 14 | groupThe Creating 15 | Highlight Groups recipe explains how to redefine highlight groups, but 16 | in standard Vim the terminal defines the cursor colour..
17 | 18 |Another approach is to highlight the line the cursor is on. You do this by 19 | executing :set cursorline. Again, to change the colours modify the 20 | CursorLine highlighting group.
21 | 22 |Similarly, you can highlight the current column the cursor is in with 23 | :set cursorcolumn. The highlight group is, predictably, called 24 | CursorColumn.
25 | 26 |If you want your terminal to resemble a sniper's sights, you can combine both 27 | line and column highlighting to create a cross-hair effect, as shown below.
28 | 29 |Discussion
30 | 31 |Gvim allows you to customise every conceivable aspect of the cursor display 32 | with the command :set guicursor. This allows you to change the 33 | cursor's appearance based on the mode (i.e. one colour for Insert mode, 34 | another for Normal), its height, and control whether it blinks… This is 35 | achieved by providing a format string as the value for 36 | guicursor. Here are some examples:
37 | 38 |39 |
47 | 48 |- n-c-v:ver50-ncvCursor - In Normal, Command, and Insert mode set 40 | the cursor to a vertical bar 50% of the current character's width. Highlight 41 | it with the ncvCursor group.
42 |- i:block-iCursor-blinkon0,v:block-vCursor - In Insert mode use a 43 | non-blinking block cursor highlighted with the iCursor highlighting 44 | group. In Visual mode also use a block cursor, but highlight it with 45 | vCursor.
46 |The above examples should be adaptable for your uses. For the gritty detail 49 | of the supported syntax look at :help guicursor.
50 | -------------------------------------------------------------------------------- /text/10_display/07_changing_the_window_title.html: -------------------------------------------------------------------------------- 1 |Changing the Window Title
2 | 3 |Problem
4 | 5 |You want to change the title of a Vim window to make it more 6 | descriptive.
7 | 8 |Solution
9 | 10 |Assign a value to the titlestring option, and set the 11 | title option. For example:
12 | 13 |14 | 15 |:set title titlestring=My\ Title
Discussion
16 | 17 |When working with multiple instances of Vim, it can be difficult to 18 | remember what task each window corresponds to. You can avoid this problem by 19 | customising each window's title. The window title can also function similarly 20 | to the status line, reminding the user 21 | about an important aspect of the current file.
22 | 23 |The default window title contains the current filename, followed by a 24 | character indicating the state of this file, followed by the name of its 25 | directoryTo be precise, the directory name is followed by a 26 | hyphen then the value of &v:servername, if set, otherwise 27 | just VIM.. The state character is one of the following:
28 | 29 |30 |
35 | 36 |- -
- File can't be modified
31 |- +
- File has been modified
32 |- =
- File is read-only
33 |- =+
- File is read-only and has been modified
34 |This is already quite a descriptive title, but we can customise it further 37 | using a format string, as described in the Changing the Status Line recipe. The Vim 39 | documentation (:help titlestring) gives the following example:
40 | 41 |43 | 44 |:auto BufEnter * let &titlestring = hostname() . "/" . 42 | expand("%:p")
Here the window title is reset when the user enters a new buffer. It 45 | contains the hostname, a forward slash, then the full path of the current 46 | fileFor an explanation of the %:p syntax see the Filename Modifiers section of the Executing External Commands 49 | recipe..
50 | 51 |Another example is to display the value of an environment variable in the 52 | window title along with the filename. For instance, Ruby on Rails developers 53 | could prefix the filename with the value of RAILS_ENV, which 54 | indicates whether the application is in development, production, staging, or 55 | testing mode:
56 | 57 |59 | 60 |let &titlestring=expand($RAILS_ENV) . ": " . 58 | expand("%:t")
One last trick is to embed the value of an external command in the window 61 | title using the %{system('command')} syntax. This could be 62 | used to display the name of the current branch, if using a version control 63 | system, or indicate whether the project's unit tests are passing or 64 | failing.
65 | -------------------------------------------------------------------------------- /text/11_extending/00.html: -------------------------------------------------------------------------------- 1 |Extending
2 | -------------------------------------------------------------------------------- /text/11_extending/01_creating_keyboard_shortcuts_with_key_mappings.html: -------------------------------------------------------------------------------- 1 |Creating Keyboard 2 | Shortcuts with Key Mappings
3 | 4 |Problem
5 | 6 |You'd like to execute a command, or series thereof, with a keyboard 7 | shortcut rather than continually type it in. Or, you'd like to change an 8 | existing keyboard shortcut so that it does something more useful.
9 | 10 |For example, you use the <Space> key to page down in other 11 | applications, and you'd like to do the same in Vim. Or, you regularly reformat 12 | paragraphs with gqap, but would prefer to simply hit 13 | Q.
14 | 15 |Solution
16 | 17 |Use key mappings. A map is simply a key combination followed by 18 | another key combination. When you enter the first key combination Vim acts as 19 | if you entered the second.
20 | 21 |For example, to remap <Space> to 22 | <PageDown> you execute :map <Space> 23 | <PageDown>. The map command creates a mapping for 24 | Normal, Visual, and Operator 25 | Pending mode; i.e. if you press <Space> in 26 | Insert mode this mapping, thankfully, has no effect.
27 | 28 |Mapping Q to gqap is similarly straight forward: 29 | :nmap Q gqap. Unlike map, :nmap only takes effect 30 | in Normal mode. We used nmap here because this mapping doesn't make 31 | sense in other modes: in Insert mode we want Q to insert a literal 32 | Q, and in Visual mode we want to reformat the selected text rather than 33 | the current paragraph. The Visual mode mapping is :vmap Q gq.
34 | 35 |The other main types of mapping commands are:
36 | 37 |38 |
45 | 46 |- :imap
39 |- Insert mode only.
40 |- :cmap
41 |- Command-line only.
42 |- :map
43 |- Normal, Visual, and Operator-pending.
44 |Discussion
47 | 48 |Keyboard mapping is yet another way to save valuable keystrokes. If you 49 | find yourself executing a command repeatedly create a mapping. It's also 50 | useful for creating more sensible aliases for existing keyboard shortcuts that 51 | you can never quite remember.
52 | 53 |It's generally recommended to map the function keys 54 | (<F1>-<F12>), as well as their shifted 55 | counterparts (e.g. <Shift>-<F3>) 56 | because they're not used by Vim<F1> 57 | is used for :help but pretty useless given that you'd 58 | normally use :help topic.. As long as you use a 59 | combination that doesn't interfere with the commands you do use, you're free 60 | to use whatever you want, though.
61 | 62 |Before you create a mapping you might like to check what, if anything, it's 63 | currently being used for. You can do this by executing :help 64 | key, e.g. :help <F1> will show that Vim maps 65 | it to :help. If you want to see the user-defined mappings (whether 66 | set by you or a plugin) call the :map command with no arguments. This 67 | works will the mode-specific map commands outlined above, too, so 68 | :imap will show Insert mode mappings.
69 | -------------------------------------------------------------------------------- /text/11_extending/02_changing_the_colour_scheme.html: -------------------------------------------------------------------------------- 1 |Changing the Colour Scheme
2 | 3 |Problem
4 | 5 |You don't like the colours Vim uses; you want to change them.
6 | 7 |For example, you've found a colour scheme you like better, so want to 8 | instruct Vim to use it. Or, you find that the current colour scheme makes text 9 | hard to read so want to find a more suitable one.
10 | 11 |Solution
12 | 13 |To browse existing colour schemes enter :colourscheme, then hit 14 | <Tab> to cycle through the installed schemes. If you find one 15 | that you like hit <Enter> to apply it.
16 | 17 |Discussion
18 | 19 |A colour scheme is a set of rules controlling how different elements of the 20 | interface appear. Vim is distributed with a selection of colour schemes, but 21 | you can also download new ones, as explained in the sidebar.
22 | 23 |24 |29 | 30 |The Vim 25 | Color Scheme Test is a a gallery of colour schemes along with their 26 | names. Browse through it to select a theme you like, then follow the 27 | instructions below to install it.
28 |31 |50 | 51 |Installing Colour Schemes
32 | 33 |34 |
49 |- Browse the available colour schemes at Vim.org 36 | and download any that you like.
37 |- Create a $VIM/colors, e.g. mkdir -p ~/.vim/colors on 38 | POSIX systems.
39 |- Copy the .vim file you downloaded in step one to the 40 | colors directory you just created.
41 |- Open vim then execute :colorscheme name, 42 | where name is that of the file you downloaded without the 43 | .vim extension.
44 |- If you want to use this colour scheme permanently add colorscheme 45 | name to your vimrc; otherwise repeat these steps 47 | with a different colour scheme.
48 |Before you change your color scheme you may like to make a note of what 52 | you're using at the moment. You can find the name of the current scheme with 53 | :echo 54 | g:colors_name.
55 | 56 |To change a specific aspect of a colour scheme you can redefine a highlight group.
58 | -------------------------------------------------------------------------------- /text/11_extending/03_creating_command-line_commands.html: -------------------------------------------------------------------------------- 1 |Creating Command-Line Commands
2 | 3 |Problem
4 | 5 |You want to create your own :command command.
6 | 7 |Solution
8 | 9 |Use the :command command like so::command name 10 | command, where name is the command you're 11 | creating and command the command name should execute. 12 | (name must start with an initial capital)
13 | 14 |For example, :command Ls !ls -all % lets you use :Ls to 15 | view the long listing for the current file on POSIX systems, thus 16 | showing the permissions, owner, group, etc.
17 | 18 |Discussion
19 | 20 |The command can be anything you could enter at the : 21 | prompt.
22 | 23 |You can modify how the command is defined by supplying :command with 24 | a list of arguments with the syntax :command arg1, 25 | arg2, … ,argN name 26 | command. These are not to be confused with arguments passed to 27 | the command, itself, however.
28 | 29 |To create a command that accepts arguments you use the syntax :command 30 | -nargs=spec name command, where 31 | spec is:
32 | 33 |34 |
43 | 44 |- 1
35 |- One argument.
36 |- *
37 |- Any number of arguments.
38 |- ?
39 |- Zero or one arguments.
40 |- +
41 |- One or more arguments.
42 |You reference the arguments in command with the 45 | <args> placeholder. The <q-args> quotes 46 | special characters in the argument. For example, you could use :command 47 | -nargs=1 Ci !cd %:h && git commit %:t -m <q-args> to 48 | quickly change to the directory containing the current file (%:h is 49 | the current pathname with the last component removed) and commit the current 50 | file (%:t is the last component of the current pathname) to a Git 51 | repository by typing :Ci message, without worrying about 52 | using quotation marks and the likeFor more robust integration 53 | with Git see the Integrating Vim with 54 | Git recipe.
55 | 56 |To create a command that accepts a count you use the 57 | -count=default argument, then reference the count in 58 | command as <count>.
59 | 60 |To create a command that accepts a range you use the 61 | -range=spec argument. If you don't supply a 62 | spec (i.e. -range), the range defaults to the current 63 | line. A spec of % means that the range defaults to the whole file. 64 | You can reference the range in the command with the placeholders 65 | <line1> and <line2> which denote the first 66 | and last line of the given range, respectively.
67 | -------------------------------------------------------------------------------- /text/11_extending/04_extending_vim_with_scripts_and_plugins.html: -------------------------------------------------------------------------------- 1 |Extending Vim with Scripts and 2 | Plugins
3 | 4 |Problem
5 | 6 |You want to add functionality to Vim, preferably without having to write it 7 | yourself.
8 | 9 |Solution
10 | 11 |Browse Vim Scripts to find a 12 | script that meets your needs. Its 'type' should be utility or 13 | ftplugin. Download the latest version to your computer. If the plugin 14 | comes with its own installation instructions, use those; otherwise, read 15 | on.
16 | 17 |If the file you've downloaded has a name ending with .vim you 18 | usually just need to save it in the right directory and then its ready to use. 19 | For scripts labelled utility, also known as global plugins, this 20 | directory is $VIMHOME/plugin; for those labeled ftplugin, also 21 | known as filetype plugins, the last component of this path is 22 | ftplugin instead. If this directory does not already exist you need to 23 | create it. The sidebar lists the locations of the plugin directories on 24 | various operating systems.
25 | 26 |If the file is compressed (ending with .zip or .tar.gz), 27 | try uncompressing it in the parent directory of the applicable plugin 28 | directory. For example, on Linux this is ~/.vim/.
29 | 30 |Now you should just be able to start Vim and have the plugin work.
31 | 32 |33 | 34 |55 | 56 |Plugin Directory Location
35 | 36 | Note: For filetype plugins, the last portion of 37 | these paths is ftplugin; not plugin. 38 | 39 |40 |
53 | 54 |- Unix
41 |- ~/.vim/plugin
42 |- PC and OS/2
43 |- $HOME/vimfiles/plugin or $VIM/vimfiles/plugin
44 |- Amiga
45 |- s:vimfiles/plugin
46 |- Macintosh
47 |- $VIM:vimfiles:plugin
48 |- Mac OS X
49 |- ~/.vim/plugin
50 |- RISC-OS
51 |- Choices:vimfiles.plugin
52 |Plugin Types
57 | 58 |Plugins can be either global or filetype-specific. Global plugins 59 | are loaded for every file you open; filetype-specific plugins are only loaded 60 | for certain filetypes.
61 | 62 |Discussion
63 | 64 |As complicated as the above instructions may sound, it's generally trivial 65 | to install a plugin. For example, on Linux to install the potwiki 67 | plugin:
68 | 69 |70 | $ mkdir -p ~/.vim/plugin 71 | $ wget 72 | http://www.vim.org/scripts/download_script.php?src_id=9316 -O 73 | ~/.vim/plugin/potwiki.vim 74 |75 | 76 |(If your plugin directory already exists, the first command is 77 | superfluous.)
78 | 79 |Vim 7 added support for a new plugin installation method called 80 | vimball. Vimballs make plugin installation and configuration easier, 81 | and are a slight improvement over the previous methods. They're not in wide 82 | use yet, but if you find a plugin distributed in this way (they have a 83 | *.vba extension), try following the steps below:
84 | 85 |86 |
91 | -------------------------------------------------------------------------------- /text/11_extending/05_integrating_vim_with_git.html: -------------------------------------------------------------------------------- 1 |- Download the *.vba file.
87 |- Open it with Vim, e.g. vim something.vba.
88 |- Use :VimballList to verify its contents.
89 |- Install it by sourcing: :source %.
90 |Integrating Vim with Git
2 | 3 |Problem
4 | 5 |You use the Git version control system with Vim and want shortcuts for 6 | common operations and syntax highlighting for git output.
7 | 8 |Solution
9 | 10 |Thanks to the work of Tim Pope and 11 | others, Vim ships with syntax highlighting support for Git output/templates. 12 | For example, after executing git commit -a, with Vim set as your 13 | default editor, you'll see 14 | 15 |
17 | 18 |
Vim can even help you write better commit messages. Git commit messages 19 | should typically have a 50-character or less summary as their first line, with 20 | a blank second line, then, optionally a long explanation, wrapped at about 72 21 | charactersFor an explanation 22 | of this convention see A Note About 23 | Git Commit Messages.. There's no need to remember this 24 | convention, however, because Vim warns you, visually, if you colour outside 25 | the lines. For example:
26 | 27 |30 | 31 |
In this example, the first line is too long, so the extraneous characters 32 | are coloured black. The second line should be blank, so it has a red 33 | background to indicate its contents are in error.
34 | 35 |motemen's git-vim plugin extends 38 | this support by adding shortcuts and commands for common Git operations.
39 | 40 |Install it by copying its files to your Vim directory. For example, on 41 | Linux:
42 | 43 |48 | 49 |mkdir -p ~/.vim 44 | cd /tmp 45 | git clone git://github.com/motemen/git-vim.git 46 | cp -r git-vim/{plugin,syntax} ~/.vim/ 47 | cd -
You now have access to commands such as :GitCommit, which will, 50 | split your window horizontally, loading the Git commit template into the upper 51 | pane. Once you have written your commit message and quit the buffer, your file 52 | will be committed. (This assumes, of course, that the current file is located 53 | in a Git working directory).
54 | 55 |56 |63 | 64 |Bob Hiestand's vcscommand 58 | plugin offers similar functionality to git-vim, but it also 59 | supports CVS, SVN, and SVK. This makes it especially suitable 61 | for situations where one uses multiple version control systems.
62 |Discussion
65 | 66 |Through a combination of editable history and particularly fast operation, 67 | Git invites regular commits. This is only feasible, however, if Git is tightly 68 | integrated into Vim, because otherwise version control will become a source of 69 | distraction that steals your focus and wastes your time.
70 | 71 |Vim's ability to execute external 72 | commands already makes using git reasonably straightforward. 73 | For instance, :!git add % would add the current file, while :!git 74 | log would temporarily suspend Vim to show you the commit log.
75 | 76 |The git-vim plugin expedites this process by providing Normal mode 77 | shortcuts. \gaThis example and those following 78 | assume that your Leader variable is set to the default of 79 | /; see :help leader for details. adds the current 80 | file, \gc commits it, etc.For a complete list of 81 | shortcuts offered by this plugin see its README.rdoc 82 | file.
83 | 84 |git-vim takes this integration further for commands like 85 | :GitBlame where the window is split vertically to show the author's 86 | name alongside the lines he was responsible for.
87 | 88 |91 | 92 |
This presentation is clearly superior to the output of :!git blame 93 | %, shown below, in that it employs syntax highlighting, allows inline 94 | editing, and hides extraneous output.
95 | 96 |98 | -------------------------------------------------------------------------------- /text/12_other-uses/00.html: -------------------------------------------------------------------------------- 1 |
Other Uses of Vim
2 | -------------------------------------------------------------------------------- /text/12_other-uses/01_browsing_directories.html: -------------------------------------------------------------------------------- 1 |Browsing Directories
2 | 3 |Problem
4 | 5 |You want to see the contents of a directory, perhaps so as to select a file 6 | to edit. For instance, if working on a project comprising multiple files you 7 | want to see a list of the files in a separate window.
8 | 9 |Solution
10 | 11 |Invoke Vim with a directory name as an argument, e.g. vim 12 | ~/projects/flying-pigs/. From within Vim use the :Ex 13 | (mnemonic: Explore) command. By default it shows the contents of the 14 | current file's directory, but you can provide a directory name if you wish. 15 | For example: :Ex ~/projects/flying-pigs. The directory is shown 16 | in a split screen if the current file has been modified.
17 | 18 |To force a directory listing in a split pane, so you can view a file and 19 | its directory listing at once, use :SexNo, 20 | that's not a joke; the concept is synonymous with Vim. Similarly, 21 | :Vex to browse in a vertical split, and :Tex to 22 | browse in a new tab.
23 | 24 |Discussion
25 | 26 |By default Vim lists every file contained in a directory. To get a more 27 | ls-style listing you can specify a hiding list with :let 28 | g:netrw_listhide='\^\..*'. (This is a comma-separated list of regular 29 | expressions). When you're browsing a directory files starting with a period 30 | will now be hidden. By Unix/Linux convention filenames which 31 | begin with a period are designated hidden. By default file browsers and 32 | other utilities ignore these files unless explicitly commanded not 33 | to. If you hit a once you'll invert the hiding list 34 | (showing only hidden files). If you hit a again you'll remove the 35 | hiding list, showing everything.
36 | 37 |To change how directory entries are sorted you can modify the 38 | g:netrw_sort_sequence variable. By default its value is, deep 39 | breath:
40 | 41 |42 | 43 |[\/]$,\.h$,\.c$,\.cpp$,*,\.o$,\.obj$,\.info$,\.swp$,\.bak$,\~$
The order of the patterns is the order of the sort. For instance, the first 44 | pattern matches directories, so they're shown first. The next pattern matches 45 | file names ending with *.h (C header files), so they're shown next. 46 | And so on. The * pattern matches everything not matched by the other 47 | patterns. You can change this pattern on-the-fly by hitting S while 48 | viewing a directory listing.
49 | 50 |You can change into a directory by selecting it and hitting 51 | Enter. The same thing works for files. If you'd rather open a file 52 | in a new buffer use p. P will open the file in a split 53 | screen.
54 | 55 |If you want to operate on the files you see read Using Vim as a File Manager.
57 | -------------------------------------------------------------------------------- /text/12_other-uses/02_using_vim_as_a_file_manager.html: -------------------------------------------------------------------------------- 1 |Using Vim as a File Manager
2 | 3 |Problem
4 | 5 |You want to use Vim to manage your file system in a similar way to 6 | Nautilus, Midnight Commander, or Windows Explorer.
7 | 8 |For example, you want to rename files matching a certain pattern. Or you 9 | want to compress the contents of a directory.
10 | 11 |Solution
12 | 13 |Browsing Directories explains the 14 | basics of working with directories in Vim, so read it first.
15 | 16 |17 | 18 |39 | 40 |Marking Files
19 | 20 |To operate on files you must first mark them (this does not have 21 | any relation to the marks 22 | feature).
23 | 24 |25 |
37 | 38 |- Mark the file under the cursor: mf (mnemonic: 26 | mark file).
27 |- Unmark the marked file under the cursor: mf.
28 |- Mark files matching a Vim regular expression: mr 29 | (mnemonic: mark with regular expression). You're then 30 | prompted for a pattern.
31 |- Unmark all files: mu (mnemonic: marks 32 | undo).
33 |- Visually mark files: 34 | <Shift>-v, then j and 35 | k to change the selection area.
36 |You can operate on a single file or a group of them. In the latter case, 41 | you need to select files by marking them, as explained in the sidebar. You can 42 | now perform various operations on these files such as:
43 | 44 |45 |
68 | 69 | 70 |- Deletion: hit D. You're prompted for each file you've 46 | selected. Answering a deletes them all without asking you any 47 | more.
48 |- Renaming: hit R. For each file you're prompted for its 49 | new name.
50 |- Copying/Moving: Hit mt (mnemonic: mark 51 | target) in the target directory. Change to the directory containing 52 | the source files, select them, then hit mc (mnemonic: marked 53 | copy) to copy or mm (mnemonic: marked 54 | move) to move.
55 |- Diff: To diff up 56 | to three marked files, use md (mnemonic: marked 57 | diff).
58 |- Printing: hit mp to print marked files (mnemonic: 59 | mark print).
60 |- Execute shell command: hit mx (mnemonic: 61 | marked execute). (See the discussion for examples).
62 |- Compress/Decompress: hit mz (mnemonic: marked 63 | gzip). (Other compression utilities can be used instead of 64 | gzip, but the Vim command remains the same).
65 |- Open in horizontal split: hit o (mnemonic: 66 | open).
67 |Discussion
71 | 72 |Vim can be used as a pretty well-featured file manager. In fact, given that 73 | it can be scripted, key mapped, and configured in concert with Vim, as well as 74 | seamlessly operate on remote directories, it is arguably better.
75 | 76 |Perhaps the most interesting command is mx. This allows you to 77 | pass the list of marked files to an external command. You're prompted for a 78 | command line, in which you can use the % wildcard. Vim then loops 79 | through the selected files and calls the command for each one, substituting 80 | % for the filename.
81 | 82 |For example, using a POSIX-compatible system, select three files 83 | (foo.txt, bar.txt, and glark) with mf. 84 | Hit mx and enter cat %>>foo-bar-glark. Vim will now 85 | execute:
86 | 87 |90 | 91 |cat foo.txt >>foo-bar-glark 88 | cat bar.txt >>foo-bar-glark 89 | cat glark >>foo-bar-glark
foo-bar-glark will now contain the contents of each file in turn.
92 | 93 |The mz command also bears further discussion. It toggles the 94 | state of the selected files between compressed and decompressed.
95 | 96 |If a file is uncompressed, Vim attempts to compress it. By default it uses 97 | gzip, but you can change this by modifying the 98 | g:netrw_compress variable. For example, to use Bzip2: :let 99 | g:netrw_compress=bzip2.
100 | 101 |For decompression Vim uses an extension-to-program mapping:
102 | 103 |104 |
109 | 110 |- .tar - tar -xf
105 |- .gz - gunzip
106 |- .bz2 - bunzip2
107 |- .zip - unzip
108 |For example, if a filename ends with .zip Vim decompresses it by 111 | calling unzip zip-file. To add support for another format 112 | use :let g:netrw_decompress[ext] = prog.
113 | -------------------------------------------------------------------------------- /text/12_other-uses/03_viewing_differences_between_files.html: -------------------------------------------------------------------------------- 1 |Viewing Differences Between Files
2 | 3 |Problem
4 | 5 |You have multiple versions of a file and want to see how they differ.
6 | 7 |For example, if you're working on a document with somebody else, you want 8 | to see the differences between their version and yours.
9 | 10 |Solution
11 | 12 |Vim calls this feature diff, as per UNIX convention. You diff 13 | a file.
14 | 15 |To diff from the command line invoke Vim as vimdiff, e.g. 16 | :vimdiff -o file1 file2. To diff from within Vim 17 | use :diffsplit file.
18 | 19 |The screen is split horizontally, and each file is shown in its own window. 20 | The differences between them are highlighted. By default, a line that exists 21 | in one file but not in another are coloured blue; the line in the other buffer 22 | that should have held this line is coloured green, and is called a 23 | filler line. When a line exists in both buffers it is coloured purple. 24 | If characters inside the line differ they are highlighted in red. Identical 25 | lines have no highlighting. Identical runs of lines are folded.
27 | 28 |To split the screen vertically use :vimdiff file1 29 | file2 or :vert diffsplit file1 30 | file2.
31 | 32 |Discussion
33 | 34 |Diffs are traditionally used in programming to compare an old and new 35 | version of source code to see what has changed. As suggested above, though, 36 | they're invaluable when collaborating on a file with somebody else. For 37 | example, you write a file named grant-proposal.txt, then e-mail it to 38 | somebody else for input. They make their changes and e-mail it back. You now 39 | have two files: grant-proposal.txt and 40 | grant-proposal.changes.txt. You use :vimdiff grant-proposal.txt 41 | grant-proposal.changes.txt to see your collaborator's suggestions.
42 | 43 |It's important to note, though, that diff only works with plain text files. 44 | It won't work correctly if you use proprietary, binary formats such as 45 | Microsoft Word's .doc. As a general rule, if Vim can view a file it 46 | can diff it.
47 | 48 |The windows diff feature splits your screen so each pane scrolls in 49 | concert with one other. This means that if you scroll to line 20 in the bottom 50 | pane, the top pane will automatically scroll to that point, too. This makes 51 | comparing long files easier, but you can disable it with :set 52 | noscrollbind.
53 | 54 |You can jump between the changes with [c to go to the previous 55 | change, and ]c for the next.
56 | -------------------------------------------------------------------------------- /text/99_post/99-foot.html: -------------------------------------------------------------------------------- 1 |