<%= 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 | 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 |:autowritefunctionality 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 noexpandtabA 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:yThe 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 | endfuncThe 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 |
77 |
78 | 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 |
95 |
96 | 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>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>(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()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/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\ -qYou 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/errThen 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\ -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>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.%:eNow, 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>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>If we create a new HTML file now this is what we see:
98 | 99 |
101 |
102 | 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 | endifTo 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.comThen 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>pI 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.xpmLet'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-pathFor example:
38 | 39 |:sign place 22 line=200 name=fixme file=/home/user/novel.txtThe 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>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>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>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>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 | commandFor example:
62 | 63 |:amenu icon=options.png ToolBar.OptionsHelp :help<cr>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 |
17 |
18 | 
30 |
31 | 
91 |
92 | 
98 |
--------------------------------------------------------------------------------
/text/12_other-uses/00.html:
--------------------------------------------------------------------------------
1 |