├── LICENSE ├── LICENSE_FRAG ├── README.textile ├── Rakefile ├── STYLE ├── TODO ├── debian ├── changelog ├── compat ├── control ├── copyright ├── rules └── vimrecipes.doc-base ├── images ├── bram_moolenaar.jpg ├── git-blame.png ├── undo-branches.png ├── vim-git-blame.png ├── vim-git-commit-highlighting.png ├── vim-git-commit.png ├── vim-help-helpgrep.png ├── vim-help.png ├── vim-html-template.png ├── vim-outliner-body-text-closed.png ├── vim-outliner-body-text.png ├── vim-outliner-heading-collapsed.png ├── vim-outliner-level-2.png └── vim-outliner.png ├── js └── footnotes.js ├── original_images └── bram_moolenaar.jpg ├── sitemap_config.xml ├── templates ├── atom.atom ├── chapter.html ├── comment.html ├── main.css ├── page.html ├── pdf.css ├── recipe.html ├── syntax.css ├── toc.html └── web.css ├── text ├── .unsorted │ └── using_a_remote_configuration_file.html ├── 01_pre │ ├── 00-head.html │ ├── 01_introduction.html │ ├── 02_conventions.html │ ├── 03_contributing.html │ ├── 04_license.html │ └── 05_credits.html ├── 04_basics │ ├── 00.html │ ├── 01_choosing_the_right_mode.html │ ├── 02_basic_navigation.html │ ├── 03_opening_a_file.html │ ├── 04_saving_a_file.html │ ├── 05_quitting.html │ ├── 06_deleting_text.html │ ├── 07_visually_selecting_text.html │ ├── 08_copying_cutting_and_pasting.html │ ├── 09_configuring_vim.html │ ├── 10_printing.html │ └── 11_help.html ├── 05_editing │ ├── 00.html │ ├── 01_indenting_lines.html │ ├── 02_selecting_text_with_motions.html │ ├── 03_repeating_commands.html │ ├── 04_changing_the_case_of_text.html │ ├── 05_sorting_text.html │ ├── 06_executing_external_commands.html │ ├── 07_managing_sessions.html │ ├── 08_formatting_with_an_external_program.html │ └── 09_working_with_different_file_formats.html ├── 06_typing │ ├── 00.html │ ├── 01_spell_checking.html │ ├── 02_using_templates.html │ ├── 03_undoing_mistakes.html │ ├── 04_auto-completing_text.html │ ├── 05_abbreviating_common_strings.html │ ├── 06_inserting_accentedforeign_characters.html │ ├── 07_opening_the_file_name_beneath_the_cursor.html │ ├── 08_inserting_the_date.html │ └── 09_inserting_snippets.html ├── 07_navigation │ ├── 00.html │ ├── 02_navigating_text_files.html │ ├── 03_navigating_source_code.html │ ├── 04_navigating_the_viewport.html │ ├── 05_navigating_buffers.html │ ├── 06_navigating_tabs.html │ ├── 07_manually_creating_folds.html │ ├── 08_navigating_folds.html │ ├── 09_splitting_the_screen.html │ ├── 10_navigating_marks.html │ ├── 11_navigating_tags.html │ └── 12_bookmarking_lines_with_visible_markers.html ├── 08_gui │ ├── 00.html │ ├── 01_changing_the_font.html │ ├── 02_maximising_screen_space.html │ └── 03_creating_menus_and_toolbar_buttons.html ├── 09_searching │ ├── 00.html │ ├── 01_searching_for_any_word.html │ ├── 02_searching_over_multiple_files.html │ ├── 03_searching_and_replacing.html │ ├── 04_searching_for_the_word_beneath_the_cursor.html │ ├── 05_creating_regular_expressions.html │ └── 07_looking_up_docs_for_the_word_beneath_the_cursor.html ├── 10_display │ ├── 00.html │ ├── 01_working_with_long_lines.html │ ├── 02_displaying_line_numbers.html │ ├── 03_working_with_remote_files.html │ ├── 04_changing_the_status_line.html │ ├── 05_redefining_highlight_groups.html │ ├── 06_modifying_the_cursor.html │ └── 07_changing_the_window_title.html ├── 11_extending │ ├── 00.html │ ├── 01_creating_keyboard_shortcuts_with_key_mappings.html │ ├── 02_changing_the_colour_scheme.html │ ├── 03_creating_command-line_commands.html │ ├── 04_extending_vim_with_scripts_and_plugins.html │ └── 05_integrating_vim_with_git.html ├── 12_other-uses │ ├── 00.html │ ├── 01_browsing_directories.html │ ├── 02_using_vim_as_a_file_manager.html │ ├── 03_viewing_differences_between_files.html │ └── 04_outlining_a_document.html └── 99_post │ └── 99-foot.html └── www ├── .htaccess ├── google18c41b892eabf75d.html └── index.html /LICENSE_FRAG: -------------------------------------------------------------------------------- 1 | Creative Commons License
Vim Recipes by Run Paint Run Run is licensed under a Creative Commons Attribution-Share Alike 3.0 Unported License. 2 | -------------------------------------------------------------------------------- /README.textile: -------------------------------------------------------------------------------- 1 | h1. Vim Recipes 2 | 3 | "Vim Recipes":http://vim.runpaint.org/ is a free cookbook for the Vim text 4 | editor. The book is available in PDF or HTML format under a Creative Commons 5 | license. 6 | -------------------------------------------------------------------------------- /STYLE: -------------------------------------------------------------------------------- 1 | * Use blockquote for tips/warnings/callouts 2 | * Use hyphens to spearate words in IDs. 3 | * Specifying command-mode commands in the :w[rite] form. 4 | -------------------------------------------------------------------------------- /TODO: -------------------------------------------------------------------------------- 1 | * Box callouts? 2 | * Caption images 3 | * Note that arguments to :set should have spaces backslash escaped. 4 | * Note on bias toward POSIX systems... 5 | * Note vim is synonymous with gvim unless otherwise stated. 6 | * Move Editing: Searching and Replacing to Searching 7 | CONVENTIONS 8 | * :w[rite] style 9 | * Meaning of ! suffix 10 | RECOVERING FROM A CRASH 11 | * Write it. 12 | SAVING A FILE 13 | * Save All (http://vim.wikia.com/wiki/VimTip652) 14 | * 'backup' options: 15 | http://vim.wikia.com/wiki/Auto_save_files_when_focus_is_lost 16 | RANGES 17 | * Write? 18 | SEARCHING AND REPLACING 19 | * Tip: alternate delimiters for replace command. 20 | VISUALLY SELECTING TEXT 21 | * Unselect a selection. 22 | * Reselect previous selection. 23 | FORMATTING 24 | * Write recipe for `gq`? 25 | REGISTERS 26 | * Write 27 | COPYING, CUTTING, and PASTING 28 | * Screenshot of pasting text without executing `:set paste`. 29 | AUTO COMPLETING TEXT 30 | * The instructions for getting dictionaries are awful. Find out whether the 31 | automatic download feature works in general, and find alternative source for 32 | downloading thesauri. 33 | * Add screenshot of Omni-Complete in action. 34 | INDENTING LINES 35 | * autoindent 36 | * cindent 37 | * smartindent 38 | * smarttab 39 | DIFF 40 | * Screenshots 41 | COLOUR SCHEMES 42 | * Screenshots 43 | STATUS LINE 44 | * Screenshot 45 | PRINTING 46 | * Write? 47 | MAX. SCREEN SPACE 48 | * Screenshots 49 | ACCENTED CHARACTERS 50 | * If Prince supports it, add the examples column back into the table. 51 | 52 | Web Version 53 | * Add icon to callouts. 54 | * Add CC license fragment to recipe template. 55 | * Link PDF from recipes? 56 | * Gzip HTML. 57 | * Generate DevHelp version. 58 | -------------------------------------------------------------------------------- /debian/changelog: -------------------------------------------------------------------------------- 1 | vimrecipes (0.0.7) jaunty; urgency=low 2 | 3 | * Initial release. 4 | 5 | -- Run Paint Run Run Sat, 23 May 2009 20:51:48 +0100 6 | -------------------------------------------------------------------------------- /debian/compat: -------------------------------------------------------------------------------- 1 | 7 2 | -------------------------------------------------------------------------------- /debian/control: -------------------------------------------------------------------------------- 1 | Source: vimrecipes 2 | Section: doc 3 | Priority: optional 4 | XSBC-Original-Maintainer: Run Paint Run Run 5 | Maintainer: Ubuntu MOTU Developers 6 | Build-Depends: debhelper (>= 7), liberuby, ruby1.8, rake, libhpricot-ruby1.8 7 | Standards-Version: 3.8.0 8 | Homepage: http://vim.runpaint.org/ 9 | Vcs-Browser: http://github.com/runpaint/vimrecipes 10 | Vcs-Git: git://github.com/runpaint/vim-recipes.git 11 | 12 | Package: vimrecipes 13 | Architecture: all 14 | Description: Vim Recipes 15 | Free "cookbook" for the Vim text editor. Contains task-orientated descriptions 16 | of common features. 17 | -------------------------------------------------------------------------------- /debian/rules: -------------------------------------------------------------------------------- 1 | #!/usr/bin/make -f 2 | 3 | DATE=$(shell date +%Y%m%d) 4 | 5 | upstream: 6 | 7 | clean: 8 | dh_testdir 9 | dh_testroot 10 | rm -f build-stamp 11 | rake clobber 12 | dh_clean 13 | 14 | build: build-stamp 15 | build-stamp: 16 | dh_testdir 17 | 18 | rake deb 19 | 20 | touch build-stamp 21 | 22 | install: build 23 | dh_testdir 24 | dh_testroot 25 | dh_prep 26 | dh_installdirs 27 | 28 | cp -ra deb/* debian/vimrecipes 29 | 30 | binary: binary-indep 31 | 32 | binary-arch: 33 | 34 | binary-indep: build install 35 | dh_testdir 36 | dh_testroot 37 | dh_installchangelogs 38 | dh_installdocs 39 | dh_compress 40 | dh_fixperms 41 | dh_installdeb 42 | dh_gencontrol 43 | dh_md5sums 44 | dh_builddeb 45 | 46 | .PHONY: clean build install binary binary-arch binary-indep 47 | -------------------------------------------------------------------------------- /debian/vimrecipes.doc-base: -------------------------------------------------------------------------------- 1 | Document: vimrecipes 2 | Title: Vim Recipes 3 | Author: Run Paint Run Run 4 | Abstract: 5 | Free "cookbook" for the Vim text editor containing task-orientated 6 | discussions of common features. 7 | Section: Programming 8 | 9 | Format: HTML 10 | Index: /usr/share/doc/vimrecipes/html/index.html 11 | Files: /usr/share/doc/vimrecipes/html/* 12 | 13 | Format: PDF 14 | Index: /usr/share/doc/vimrecipes/vim-recipes.pdf.gz 15 | Files: /usr/share/doc/vimrecipes/vim-recipes.pdf.gz 16 | -------------------------------------------------------------------------------- /images/bram_moolenaar.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/bram_moolenaar.jpg -------------------------------------------------------------------------------- /images/git-blame.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/git-blame.png -------------------------------------------------------------------------------- /images/undo-branches.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/undo-branches.png -------------------------------------------------------------------------------- /images/vim-git-blame.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-git-blame.png -------------------------------------------------------------------------------- /images/vim-git-commit-highlighting.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-git-commit-highlighting.png -------------------------------------------------------------------------------- /images/vim-git-commit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-git-commit.png -------------------------------------------------------------------------------- /images/vim-help-helpgrep.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-help-helpgrep.png -------------------------------------------------------------------------------- /images/vim-help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-help.png -------------------------------------------------------------------------------- /images/vim-html-template.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-html-template.png -------------------------------------------------------------------------------- /images/vim-outliner-body-text-closed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-outliner-body-text-closed.png -------------------------------------------------------------------------------- /images/vim-outliner-body-text.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-outliner-body-text.png -------------------------------------------------------------------------------- /images/vim-outliner-heading-collapsed.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-outliner-heading-collapsed.png -------------------------------------------------------------------------------- /images/vim-outliner-level-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-outliner-level-2.png -------------------------------------------------------------------------------- /images/vim-outliner.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/images/vim-outliner.png -------------------------------------------------------------------------------- /js/footnotes.js: -------------------------------------------------------------------------------- 1 | /* Derived from http://www.brandspankingnew.net/specials/footnote.html */ 2 | window.onload=function() 3 | { 4 | var noteholder = document.getElementById('footnotes'); 5 | var spans = document.getElementsByTagName("span"); 6 | var notes = 0; 7 | 8 | for (i=0;i" + notes + ". " + spans[i].innerHTML + " "; 14 | spans[i].innerHTML = "" + notes + ""; 15 | spans[i].style.display = 'inline'; 16 | } 17 | } 18 | 19 | } 20 | 21 | -------------------------------------------------------------------------------- /original_images/bram_moolenaar.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/runpaint/vim-recipes/1563771179816cec6561ed3ae71cde2e3dec62c0/original_images/bram_moolenaar.jpg -------------------------------------------------------------------------------- /sitemap_config.xml: -------------------------------------------------------------------------------- 1 | 2 | 13 | 14 | 15 | 38 | 43 | 44 | 45 | 46 | 54 | 55 | 66 | 67 | 68 | 69 | 70 | 71 | 84 | 85 | 90 | 91 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | -------------------------------------------------------------------------------- /templates/atom.atom: -------------------------------------------------------------------------------- 1 | 2 | 4 | 5 | http://vim.runpaint.org/index.atom 6 | Vim Recipes 7 | A cookbook for the Vim text editor 8 | 9 | Run Paint Run Run 10 | runrun@runpaint.org 11 | http://runpaint.org/ 12 | 13 | <% require 'time' %> 14 | <%= updated.xmlschema %> 15 | 16 | 17 | 18 | <% 19 | toc.each do |entry| 20 | next unless entry[:type] == :recipe 21 | %> 22 | 23 | tag:vim.runpaint.org,2009:<%= entry[:id] %> 24 | 25 | <%= entry[:title] %> 26 | <%= entry[:time].xmlschema %> 27 |
28 | <%= entry[:body] %> 29 |
30 |
31 | <% end %> 32 |
33 | -------------------------------------------------------------------------------- /templates/chapter.html: -------------------------------------------------------------------------------- 1 |

Vim Recipes <%= title %>

2 |

<%= title %>

3 |
    4 | <% recipes.each do |r| %> 5 |
  • <%= r[:title] %> 6 | <% end %> 7 |
      8 | -------------------------------------------------------------------------------- /templates/comment.html: -------------------------------------------------------------------------------- 1 |
      2 |

      <%= comment %>

      3 | 8 |
      9 | 10 | -------------------------------------------------------------------------------- /templates/page.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Vim Recipes: <%= title %> 6 | 7 | 9 | 10 | 11 |
      12 |
      13 | 14 |   15 |   16 | 17 |
      18 |
      19 | <%= content %> 20 | 25 | 31 | 32 | 33 | -------------------------------------------------------------------------------- /templates/recipe.html: -------------------------------------------------------------------------------- 1 |

      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 |

      Table of Contents

      4 |
        5 | <% 6 | @in_sec = false 7 | toc.each do |entry| 8 | if (entry[:type] == :section) 9 | if (@in_sec) 10 | %> 11 |
      12 | 13 | <% end 14 | %> 15 |
    • <%= entry[:title] %>

      16 | 23 | -------------------------------------------------------------------------------- /templates/web.css: -------------------------------------------------------------------------------- 1 | h1 { 2 | text-align: center; 3 | font-family:"Book Antiqua",Palatino,Georgia,serif; 4 | font-variant:small-caps; 5 | letter-spacing:-1px; 6 | font-size:xx-large; 7 | } 8 | h2,h3,h4 { 9 | margin-top: 0; 10 | padding-top: 0; 11 | } 12 | a {text-decoration:none;} 13 | a:link {color: steelblue; border-bottom: 1px dotted;} 14 | a:visited {color: darkorchid; border-bottom: 1px dotted; } 15 | a:hover {color: steelblue; border-bottom:1px solid;} 16 | table { 17 | margin-left: auto; 18 | margin-right: auto; 19 | } 20 | 21 | /* Initially we hide footnotes. A JavaScript function is then run to render 22 | * them at the bottom of the page, replacing their previous location with a 23 | * link to their new location. Having done this, the JavaScript sets span.fn 24 | * _display_ to 'inline', thus avoiding the footnotes initially appearing in 25 | * their original position prior to being moved. 26 | * 27 | * This is imperfect because it hides footnotes from users with CSS enabled 28 | * and JS disabled, but it will do for now. 29 | */ 30 | span.fn { 31 | display: none; 32 | } 33 | 34 | span.fn a:link { 35 | vertical-align: super; 36 | color: black; 37 | font-weight: bold; 38 | font-size: 100%; 39 | padding-left: 1px; 40 | border: none; 41 | } 42 | 43 | #footnotes { 44 | border-top: 1px solid #ccc; 45 | margin: 20px 0 20px 0; 46 | padding: 10px 0 0 0; 47 | } 48 | 49 | #footnotes div.footnote { 50 | margin: 0 0 5px 0; 51 | } 52 | 53 | @media screen, handheld { 54 | html { margin: 1em; font: 14px "Gill Sans", "Gill Sans MT", "DejaVu Sans", sans-serif; } 55 | h1 { margin-bottom: 0.5em } 56 | div.frontcover, div.backcover, div.halftitlepage, div.titlepage, div.imprint, 57 | div.dedication, div.foreword, div.toc, div.index { display: none } 58 | } 59 | /* previous/next navigation links */ 60 | 61 | .nav a{text-decoration:none;border:0;display:block} 62 | .nav a:first-child{float:left} 63 | .nav a:last-child{float:right} 64 | /*.nav span{font-size:1000%;line-height:1;margin:0;text-shadow:gainsboro 3px 3px 3px} */ 65 | p {margin: 1em 0} 66 | #disqus_thread { 67 | border-top: 1px solid #ccc; 68 | margin: 20px 0 20px 0; 69 | padding: 10px 0 0 0; 70 | } 71 | #formats a { 72 | text-size: larger; 73 | font-weight: bold; 74 | } 75 | div.comments > h2 { text-align: center } 76 | div.comments img { float: left; margin-right: 2%; border: none; } 77 | div.comments article { display: block; clear: both; margin-left: 5%; } 78 | div.comments article > p { border-left: 1px dashed black; padding-left: 1% } 79 | div.comments > p:last-child { text-align: center } 80 | -------------------------------------------------------------------------------- /text/.unsorted/using_a_remote_configuration_file.html: -------------------------------------------------------------------------------- 1 |

      Using a Remote Configuration Time

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      12 | 13 |

      Upload your vimrc to a server (such as a web server).

      14 | 15 |

      You can start Vim with the -S flag, e.g. vim -S url.

      16 | 17 |

      This is cumbersome, though. Easier is to use the following minimal 18 | vimrc on all of your machines:

      19 | 20 |
      
      21 | runtime plugin/netrwPlugin.vim
      22 | silent source url
      23 | 
      24 | 25 |

      This acts as a bootstrap config file. Vim loads your local vimrc 26 | first, activates the plugin needed to fetch files over the network 27 | (netrw), fetches the given URL, then 'sources' it as a set of Vim 28 | commands.

      29 | 30 |
      31 | Warning: You should only source vimrc files that you've 32 | vetted. They should not be hosted from a shared directory unless you implicitly 33 | trust all users with access to it. 34 |
      35 | 36 |

      Discussion

      37 | 38 |

      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 |
      64 | A search for Vim on GitHub.com will yield 65 | a large selection of Vim configurations kept in version control. You can use 66 | one as a base for your own configuration by "cloning" it to your local machine 67 | then making changes. Having done this, you may want to host the repository on 68 | GitHub, too, so it will be available when you work on a new machine. 69 |
      70 | -------------------------------------------------------------------------------- /text/01_pre/01_introduction.html: -------------------------------------------------------------------------------- 1 |
      2 |

      Introduction

      3 | 4 |

      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 |
      33 | -------------------------------------------------------------------------------- /text/01_pre/02_conventions.html: -------------------------------------------------------------------------------- 1 |
      2 |

      Conventions

      3 | 4 |

      The following typographical conventions are used in this book:

      5 | 6 |

      Key Presses

      7 | 8 |

      <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 |

      Normal Mode Commands

      17 | 18 |

      gqap - The named characters should be entered in order while in 19 | Normal mode.

      20 | 21 |

      Command-Line Commands

      22 | 23 |

      :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 |

      Monospaced Font

      31 | 32 |

      A fixed width font is used for filenames, code, and variable 33 | names.

      34 |
      35 | 36 | -------------------------------------------------------------------------------- /text/01_pre/03_contributing.html: -------------------------------------------------------------------------------- 1 |
      2 |

      Contributing

      3 | 4 |

      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 |

      Issue Tracker

      10 | 11 |

      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 |

      E-mail

      17 | 18 |

      You can send patches and bug reports to runrun@runpaint.org.

      20 | 21 |

      Patches

      22 | 23 |

      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 |
      52 | -------------------------------------------------------------------------------- /text/01_pre/04_license.html: -------------------------------------------------------------------------------- 1 |
      2 |

      License

      3 | 4 |

      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 |
      10 | -------------------------------------------------------------------------------- /text/01_pre/05_credits.html: -------------------------------------------------------------------------------- 1 |
      2 |

      Credits

      3 | 4 |

      Cover Image

      5 | 6 |

      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 |

      CSS

      16 | 17 |

      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 |

      Contributors

      32 | 33 |

      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 |
      39 | -------------------------------------------------------------------------------- /text/04_basics/00.html: -------------------------------------------------------------------------------- 1 |

      Basics

      2 | -------------------------------------------------------------------------------- /text/04_basics/01_choosing_the_right_mode.html: -------------------------------------------------------------------------------- 1 |

      Choosing the Right Mode

      2 | 3 |

      Problem

      4 | 5 |

      You know that Vim has multiple modes of operation but aren't sure when to use 6 | which one.

      7 | 8 |

      Solution

      9 | 10 |

      For practical purposes there are four modes:

      11 | 12 |
      13 |
      Insert mode
      14 |
      Use only for typing; not moving around or editing. Stay in 15 | this mode for as short a time as possible.
      16 |
      Normal mode
      17 |
      Use this for editing: moving around the file, changing 18 | text, and rearranging structure. Dip in and out of Insert mode when 19 | needed.
      20 |
      Visual mode
      21 |
      Use this for visually selecting 22 | text so that you can cut, copy, or format it.
      23 |
      Command-Line mode
      24 |
      Use this for entering commands, e.g. :set number
      25 |
      26 | 27 |

      Discussion

      28 | 29 |

      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 |

      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 |
      49 | 50 |

      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 |

      Basic Navigation

      2 | 3 |

      Problem

      4 | 5 |

      You want to move around inside a file.

      6 | 7 |

      Solution

      8 | 9 |

      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 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 |
      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
      23 | 24 |

      Discussion

      25 | 26 |

      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 |

      Saving a File

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      13 | 14 |

      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.

      26 | 27 |

      Discussion

      28 | 29 |

      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 |

      The :autowrite functionality is not related to some word 42 | processor's concept of auto-saving a file periodically in case of a crash. 43 | Vim does this automatically.

      44 |
      45 | 46 |

      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 |

      Quitting Vim

      2 | 3 |

      Problem

      4 | 5 |

      You've finished using Vim and now you want to close the program.

      6 | 7 |

      Solution

      8 | 9 |

      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 |

      Discussion

      16 | 17 |

      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 |

      Deleting Text

      2 | 3 |

      Problem

      4 | 5 |

      You wish to remove some text from a file. For example, you've typed a 6 | paragraph which is no longer needed.

      7 | 8 |

      Solution

      9 | 10 |

      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 |

      Discussion

      34 | 35 |

      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 |

      Visually Selecting Text

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      12 | 13 |

      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 |

      Discussion

      41 | 42 |

      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 | 57 | -------------------------------------------------------------------------------- /text/04_basics/08_copying_cutting_and_pasting.html: -------------------------------------------------------------------------------- 1 |

      Copying, Cutting, and Pasting

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      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 |

      Discussion

      43 | 44 |

      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..

      51 | 52 |

      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 |

      Configuring Vim

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      13 | 14 |

      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 |
      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 |
      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 |
      42 | 43 |
      44 | 45 |

      The vimrc is a simple plain text file. Open the filename specified 46 | in the sidebar and add one option per line using the 47 | option=value syntax (the ':' prefix is 48 | unnecessary). Indeed, this is the general principle for adding any 49 | Command-Line command in this book to your vimrc. For 50 | example:

      51 | 52 |
      " Set the boolean number option to true
       53 | set number
       54 | " Set the textwidth option to '78'
       55 | set textwidth=78
       56 | " Set the expandtab option to false
       57 | set noexpandtab
      58 | 59 |

      A single quotation mark (") introduces comments. They are ignored 60 | by Vim, but particularly useful for remembering what all of your preferences 61 | mean.

      62 | 63 |
      64 |

      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 |
      68 | 69 |

      Discussion

      70 | 71 |

      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 |
      97 | Warning: There's the potential for security problems when using 98 | exrc. If a vimrc was placed in your project directory 99 | without you knowing -- as a result of unpacking an archive, for example -- it 100 | could be used to execute arbitrary commands under your user account. For this 101 | reason it's strongly recommended that you use :set secure in 102 | conjunction with exrc. This prevents the directory-specific 103 | vimrc files from executing potentially dangerous commands. The Vim 104 | documentation suggests adding set secure as the last line in your 105 | vimrc. 106 |
      107 | 108 |
      109 | 110 |
      Debugging Configuration
      111 | 112 |
        113 |
      • 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 |
      122 | 123 |
      124 | -------------------------------------------------------------------------------- /text/04_basics/10_printing.html: -------------------------------------------------------------------------------- 1 |

      Printing

      2 | 3 |

      Problem

      4 | 5 |

      You want to print something from Vim.

      6 | 7 |

      Solution

      8 | 9 |

      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 |

      Discussion

      13 | 14 |

      :hardcopy converts the current file to Postscript and sends it to 15 | the default printer. You can specify that a different printer is used with 16 | :set 17 | pdev=printer. For example, :set pdev=usblp1.

      18 | 19 |

      If you have a PDF printer 20 | installedLinux/Mac users can 21 | install the CUPS PDF package to get a PDF printer, e.g. on 22 | Debian/Ubuntu: apt-get install cups-pdf., you can use this 23 | technique to print a file to PDF. For example, assuming your PDF printer is 24 | called pdf:

      25 | 26 |
      set pdev=pdf
      27 | set printoptions=paper:A4,syntax:y,wrap:y
      28 | 29 |

      The printoptions line is a comma separated list of values that 30 | affect how Vim formats the document before it sends it to the printer. A list 31 | of options is at :help popt.

      32 | 33 |

      The paper option sets the paper size. It accepts values such as 34 | A3, letter, and legal.

      35 | 36 |

      The syntax option determines whether the document is printed with syntax 37 | highlighting. By default it has the value a which means that Vim only 38 | uses highlighting for colour printers. A value of y forces 39 | highlighting.

      40 | 41 |

      Lines are wrapped when wrap:y, which is the default. If 42 | wrap has the value n, long lines are truncated.

      43 | 44 |

      Other useful options are header:0 to stop a header from being 45 | printed, number:y to number lines, duplex:off to print on 46 | only one side of the page.

      47 | 48 |

      On Linux the lpr utility is used for printing. To use a different 49 | program add a stanza such as the following to your vimrc:

      51 | 52 |
      set printexpr=PrintFile(v:fname_in)
      53 | function PrintFile(fname)
      54 |   call system("a2ps " . a:fname)
      55 |   call delete(a:fname)
      56 |   return v:shell_error
      57 | endfunc
      58 | 59 |

      The above example specifies that the GNU Anything to Postscript 60 | (a2ps) utility is used for printing. a2ps can print two 61 | pages per physical page and custom headers, for example; see man a2ps 62 | for a complete list of features.

      63 | -------------------------------------------------------------------------------- /text/04_basics/11_help.html: -------------------------------------------------------------------------------- 1 |

      Getting Help

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      9 | 10 |

      Look up a topic in the online help with :help topic. 11 | Search it with the :helpgrep pattern command.

      12 | 13 |
      14 |

      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 |
      20 | 21 |

      Discussion

      22 | 23 |

      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 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 |
      Type of TopicPrependExample
      Normal mode command(nothing):help x
      Visual mode commandv:help v_u
      Insert mode commandi:help i_<Esc>
      Command-line command::help :quit
      Command-line editingc:help c_<Del>
      Vim command argument-:help -r
      Option':help 'textwidth'
      66 | 67 |

      (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 | Screenshot of a portion of the output for `:help help` 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 | Screenshot of a portion of the output for `:help :helpgrep`. 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 |

      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 |
      125 | 126 |

      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 |

      Editing

      2 | -------------------------------------------------------------------------------- /text/05_editing/01_indenting_lines.html: -------------------------------------------------------------------------------- 1 |

      Indenting Lines

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      14 | 15 |

      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 |

      Description

      36 | 37 |

      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 |

      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 |
      46 | 47 |

      A contentious issue among programmers involves how the tab key should work. 48 | There are two main schools of thought:

      49 | 50 |
        51 |
      • Literal tabs - Each press of the tab key should insert a literal tab 52 | character (padding with spaces if necessary). To achieve this: :set 53 | tabstop=8 (the default), :set softtabstop=8, :set 54 | shiftwidth=8, and :set noexpandtab. Tabs are now eight 55 | columns wide; each indentation level is a single tab.
      • 56 |
      • Convert tabs to spaces - Each press of the tab key should insert a certain 57 | number of spaces. The settings you need are :set tabstop=8, 58 | :set shiftwidth=4, and :set expandtab. Tabs are now 59 | replaced with 4 spaces. Real tabs are displayed 8 character wide, spaced 60 | tabs 4 characters wide.
      • 61 |
      62 | 63 |

      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 |

      See Also

      84 | 85 | 91 | -------------------------------------------------------------------------------- /text/05_editing/03_repeating_commands.html: -------------------------------------------------------------------------------- 1 |

      Repeating Commands

      2 | 3 |

      Problem

      4 | 5 |

      You've entered a command and want to repeat it without re-typing it.

      6 | 7 |

      Solution

      8 | 9 |

      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 |

      Discussion

      21 | 22 |

      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 |

      25 | 26 |

      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.

      42 | 43 |

      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 |

      Changing the Case of Text

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      9 | 10 |
      11 |
      ~ 12 |
      Toggles the case of the current character in Normal mode, or the 13 | selection in Visual mode.
      14 |
      u
      15 |
      Lowercases highlighted text. (Note: This only works in Visual 16 | mode; otherwise u will undo your last change).
      17 |
      U 18 |
      Uppercases highlighted text. (Note: This only works in Visual 19 | mode; otherwise U will undo the changes made on the current 20 | line).
      21 |
      22 | 23 |

      Discussion

      24 | 25 |

      As normal, these commands accept motions. For example:

      27 | 28 |
      29 |
      VU
      30 |
      Uppercase current line.
      31 |
      guw
      32 |
      Lowercases current word.
      33 |
      34 | 35 |

      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:

      42 | 43 |
      nnoremap <F7> :s/\<\(\w\)\(\w*\)\>/\u\1\L\2/g<CR>
      44 | vnoremap <F7> :s/\%V\(\w\)\(\w*\)\%V/\u\1\L\2/g<CR>
      45 | 46 |

      Alternatively, you can install the titlecase 48 | plugin.

      49 | -------------------------------------------------------------------------------- /text/05_editing/05_sorting_text.html: -------------------------------------------------------------------------------- 1 |

      Sorting Text

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      11 | 12 |

      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 |

      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 |
      21 | 22 |

      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 |
        31 |
      1. Select the area you're interested in.
      2. 32 |
      3. Hit : and Vim will display :'<,'>' which refers 33 | to your selection.
      4. 34 |
      5. Type !sort (i.e. execute :'<,'>!sort).
      6. 35 |
      36 | 37 |

      Discussion

      38 | 39 |

      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 |
      45 |
      :sort!
      46 |
      Reverses the sort order, i.e. sorts in descending order: z-a, 100-0.
      47 |
      :sort flags
      48 |
      The sort command can be followed by a series of flags which can be combined in any order: 49 |
      50 |
      n
      51 |
      Sorts by the first decimal number in the line.
      52 |
      i
      53 |
      Ignores case while sorting.
      54 |
      u
      55 |
      Deletes duplicate lines (keeps unique lines).
      56 |
      57 |
      58 |
      :sort /pattern/
      59 |
      Ignore text matching pattern when sorting.
      60 |
      61 | 62 |

      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 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 |
      Original:sort!:sort in:sort i /^./}
      ant1zebra12ant1zebra12
      Dog7frog11fish6fish6
      cow8fish6Dog7ant1
      fish6cow8cow8Dog7
      frog11ant1frog11cow8
      zebra12Dog7zebra12frog11
      134 | 135 |

      If you're using the external sort utility the options are 136 | similar. See man sort for the details. Common invocations are:

      137 | 138 |
      139 |
      %!sort -u
      140 |
      Delete duplicate lines.
      141 |
      %!sort -f
      142 |
      Ignore case when sorting.
      143 |
      %!sort -r
      144 |
      Reverse sort order.
      145 |
      146 | -------------------------------------------------------------------------------- /text/05_editing/06_executing_external_commands.html: -------------------------------------------------------------------------------- 1 |

      Executing External Commands

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      15 | 16 |

      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 |
      Filename Modifiers
      26 | 27 |

      You can alter the filename represented by % by following the wildcard 28 | with a modifier. For example:

      29 | 30 |
      31 |
      %: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.txtfoo.txt.
      38 |
      %:e
      39 |
      Removes everything except the filename extension. For 40 | example ~/work/foo.txttxt.
      41 |
      42 | 43 |
      44 | 45 |

      Discussion

      46 | 47 |

      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 |

      Managing Sessions

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      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 |

      Discussion

      25 | 26 |

      Applications such as Mozilla Firefox use the concept of a global 27 | session file which is overwritten every time you use the program. To make Vim 28 | work this way you simply use a fixed name for the session variable. For 29 | example, you could save it to $VIMHOME/Session.vim. You could add a 30 | mapping something like this to your vimrc.

      32 | 33 |
      nmap SQ <ESC>:mksession! ~/vim/Session.vim<CR>:wqa<CR>
      34 | 35 |

      (SQ for Session Quit). To automatically restore 36 | this session when Vim is called without arguments add the following:

      37 | 38 |
      function! RestoreSession()
      39 |   if argc() == 0 "vim called without arguments
      40 |     execute 'source ~/.vim/Session.vim'
      41 |   end
      42 | endfunction
      43 | autocmd VimEnter * call RestoreSession()
      44 | 45 |

      You can extend this in arbitrary ways to suit your working environment. One 46 | approach is to only restore a session if it exists in the current file's 47 | directory. Another is to simply hardcode a list of directories whereby if they 48 | are the file's current directory or parent directory, their session file is 49 | used. This is useful for one-project-per-directory organisation.

      50 | 51 |

      If you don't just want one global session file, as described above, a more 52 | granular approach is suggested below:

      53 | 54 |
      nmap SSA :wa<CR>:mksession! ~/sessions/
      55 | nmap SO :wa<CR>:so ~/sessions/
      56 | 57 |

      Session Save As saves the open files and prefills the 58 | command line with the command to save the current session in a 59 | ~/sessions/ directory. All you need to do is enter a name and hit 60 | <Enter>.

      61 | 62 |

      Session Open also saves the open files, then prefills the 63 | command line with the command to load a session file. Just type the name of 64 | the session you want to load and hit <Enter>.

      65 | 66 |

      You can use <Tab> completion in both cases. For example, you 67 | could save a session with SSAwork<Enter>. Later, when you 68 | want to restore the session but can't recall its name, just hit 69 | SO<Tab> to cycle through the saved sessions.

      70 | 71 |

      (Both mappings assume the ~/sessions/ directory already exists; 72 | create it if it doesn't).

      73 | 74 |
      75 |

      Yuri Klubakov's sessionman 77 | plugin provides a more 78 | polished approach for session management, subsuming the functionality 79 | described above.

      80 |
      81 | 82 | -------------------------------------------------------------------------------- /text/05_editing/08_formatting_with_an_external_program.html: -------------------------------------------------------------------------------- 1 |

      Formatting with an External Program

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      Set the equalprg option to the name of the program you want 12 | to use, along with any arguments it should be passed. For example:

      13 | 14 |
      :set equalprg=tidy\ -indent\ -q
      15 | 16 |

      You can now select the text you want 17 | to format, then hit =. You can reformat the entire file with 18 | 1G=G.

      19 | 20 |

      Discussion

      21 | 22 |

      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 |
      Text
      27 | 28 |

      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 |
      HTML/XHTML
      33 | 34 |

      Use HTML Tidy. You can 35 | specify options on the command line, as shown in the example above. If you 36 | want to specify a lot of options, put them into a config file, and point 37 | tidy to it: tidy 38 | --config file. At a minimum you probably want to use:

      39 | 40 |
      :setlocal equalprg=tidy\ -utf8\ -indent\ -q\ -f\ /tmp/err
      41 | 42 |

      Then you can reformat your file with 1G=G. One caveat is that 43 | this won't work correctly for reformatting a specific section of the file. You 44 | can use the --show-body-only true option if you want to be able to do 45 | this, but like many formatters of markup languages, Tidy doesn't perform as 46 | well on fragments because of lack of context.

      47 | 48 |
      XML
      49 | 50 |

      HTML Tidy can be used to format XML as well by passing it the 51 | -xml option. Alternatively, you can use xmllint:

      52 | 53 |
      :set equalprg=xmllint\ --format\ -
      54 | -------------------------------------------------------------------------------- /text/05_editing/09_working_with_different_file_formats.html: -------------------------------------------------------------------------------- 1 |

      Working with Different File 2 | Formats

      3 | 4 |

      Problem

      5 | 6 |

      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 |

      Solution

      11 | 12 |

      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 |

      Discussion

      19 | 20 |

      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 |

      Typing

      2 | -------------------------------------------------------------------------------- /text/06_typing/01_spell_checking.html: -------------------------------------------------------------------------------- 1 |

      Spell Checking

      2 | 3 |

      Problem

      4 | 5 |

      You want Vim to highlight misspelled words and suggest alternatives.

      6 | 7 |

      Solution

      8 | 9 |

      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 |

      Discussion

      25 | 26 |

      Spelling errors are highlighted in one of four colours depending on the type 27 | of error:

      28 | 29 |
        30 |
      • Word is not in the dictionary.
      • 31 |
      • Word is in the dictionary but not capitalised.
      • 32 |
      • Word is classed as 'rare'.
      • 33 |
      • Word is spelled incorrectly for this region. For instance, 34 | color in British English.
      • 35 |
      36 | 37 |

      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 |

      Using Templates

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      12 | 13 |

      Use templates and associate them with a file extension. When a new file is 14 | created with an extension for which a template is available, the template 15 | contents will be inserted.

      16 | 17 |

      You must first create a skeleton document, e.g.:

      18 | 19 |
      <?xml version="1.0" encoding="UTF-8"?>
       20 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
       21 |     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
       22 | <html xmlns="http://www.w3.org/1999/xhtml"
       23 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       24 |     xsi:schemaLocation="http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd"
       25 |     xml:lang="en">
       26 |     <head>            
       27 |       <title>Document Title</title>
       28 |     </head>
       29 |     <body></body>
       30 | </html>
      31 | 32 |

      Save this document in your Vim directory with the corresponding file 33 | extension, e.g. ~/.vim/skel/tmpl.html. (You may also want to make 34 | this file read only so you don't modify it by mistake).

      35 | 36 |

      Add the following to your .vimrc:

      37 | 38 |
      autocmd! BufNewFile * silent! 0r ~/.vim/skel/tmpl.%:e
      39 | 40 |

      Now, every time you open a new file Vim checks ~/.vim/skel/ for a 41 | file whose name starts with tmpl. and ends with the extension of the 42 | file you're creating. It then reads the template file into your new file's 43 | buffer.

      44 | 45 |

      For example, if you added the template above then invoked Vim with vim 46 | page.html, the XHTML above would be inserted into the 47 | page.html file automatically.

      48 | 49 |

      Discussion

      50 | 51 |

      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.

      57 | 58 |

      The traditional solution is to use placeholders. This involves including some 59 | notation in the template file that indicates where your input is required, 60 | then providing a method to jump between them.

      61 | 62 |

      Here's the previous template with placeholders added:

      63 | 64 |
      <?xml version="1.0" encoding="UTF-8"?>
       65 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
       66 |     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
       67 | <html xmlns="http://www.w3.org/1999/xhtml"
       68 |     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       69 |     xsi:schemaLocation="http://www.w3.org/MarkUp/SCHEMA/xhtml11.xsd"
       70 |     xml:lang="en">
       71 |     <head>            
       72 |       <title>%TITLE%</title>
       73 |     </head>
       74 |     <body>%BODY%</body>
       75 | </html>
      76 | 77 |

      The placeholder notation is arbitrary, but let's stick with 78 | %VARIABLE% for the sake of example. Now we need a way to jump between 79 | them, and <Ctrl>-p (menmonic: 80 | placeholder) seems reasonable. While we're at it, we'll define a 81 | function (LoadTemplate()) to replace the autocmd line we 82 | added earlier. Add the following to your vimrc:

      83 | 84 |
      function! LoadTemplate()
       85 |   silent! 0r ~/.vim/skel/tmpl.%:e
       86 |   " Highlight %VAR% placeholders with the Todo colour group
       87 |   syn match Todo "%\u\+%" containedIn=ALL
       88 | endfunction
       89 | autocmd! BufNewFile * call LoadTemplate()
       90 | "Jump between %VAR% placeholders in Normal mode with
       91 | " <Ctrl-p>
       92 | nnoremap <c-p> /%\u.\{-1,}%<cr>c/%/e<cr>
       93 | "Jump between %VAR% placeholders in Insert mode with
       94 | " <Ctrl-p>
       95 | inoremap <c-p> <ESC>/%\u.\{-1,}%<cr>c/%/e<cr>
      96 | 97 |

      If we create a new HTML file now this is what we see:

      98 | 99 | Screenshot of GVim displaying a template for a HTML document. 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 |

      Undoing Mistakes

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      14 | 15 |

      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 |

      Discussion

      29 | 30 |

      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 |

      48 | 49 |

      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 |

      Auto-Completing Text

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      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 |
      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 |
      36 | 37 |

      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 |

      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 |
      55 | 56 |

      Discussion

      57 | 58 |

      Vim can use pretty much any word source imaginable. Consult :help 59 | ins-completion for more details.

      60 | 61 |

      Vim version 7 and above supports Omni-Completion, which allows 62 | custom functions to generate possible completions dynamically. Even better, 63 | for programmers at least, is that some popular programming languages already 64 | have Omni-Completion functions which are enabled automatically. These typically 65 | allow context-sensitive completion of method names, objects, and reserved 66 | words. For example, using Ruby I can type an integer, a period, then invoke 67 | Omni-Completion to find that Fixnum objects support methods such as 68 | %, *, and +.

      69 | 70 |

      Languages that don't have Omni-Complete functions available can use 71 | their syntax highlighting definitions to achieve a similar affect. The Vim 72 | documentation suggests adding the following stanza to your vimrc, after any :filetype 74 | command, to enable Omni-Completion using the best available method: 75 |

      76 | 77 |
      if has("autocmd") && exists("+omnifunc")            
      78 |   autocmd Filetype *
      79 |     \   if &omnifunc == "" |
      80 |     \     setlocal omnifunc=syntaxcomplete#Complete |
      81 |     \   endif
      82 | endif
      83 | 84 |

      To use Omni-Completion hit Ctrl+x 85 | Ctrl+o to be presented with a list of choices for 86 | the text behind the cursor.

      87 | 88 |

      Apart from programming languages, Omni-Completion also works for HTML and 89 | CSS. For example, you can type <p cl, 90 | Ctrlx 91 | Ctrl+o, then be shown class=" 92 | CDATA, onclick=" Script, and ondblclick=" 93 | Script.

      94 | -------------------------------------------------------------------------------- /text/06_typing/05_abbreviating_common_strings.html: -------------------------------------------------------------------------------- 1 |

      Abbreviating Common Strings

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      13 | 14 |

      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 |

      Discussion

      28 | 29 |

      The abbreviation feature is smart enough not to expand abbreviation names that 30 | occur as part of another word, but its telepathic functionality is suboptimal. 31 | Useful abbreviation names are easy to type, but will not appear in normal 32 | text. The convention I use is to prefix them with my, then uppercase 33 | the first letter. (If you use a programming language that prefers "camelCased" 34 | variable names, you may see clashes. Either stop using Java®, or disable 35 | abbreviations for the source code.)

      36 | 37 |

      You can also abbreviate commands. For instance, if you wanted to type 38 | :docs instead of :help you could map one to the other with 39 | :cabbr docs help.

      40 | 41 |

      I suggest keeping your abbreviations in an abbreviations file in 42 | $VIM. You can then source it from your vimrc. For example, you can create the 44 | file by running vim $VIM/abbreviations, then populate it with your 45 | abbreviations:

      46 | 47 |
      iabbrev myUrl http://example.com/
      48 | iabbrev myEmail user@example.com
      49 | 50 |

      Then in vimrc just write source $VIM/abbreviations.

      51 | -------------------------------------------------------------------------------- /text/06_typing/06_inserting_accentedforeign_characters.html: -------------------------------------------------------------------------------- 1 |

      Inserting Accented or "Foreign" Characters

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      12 | 13 |

      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 |
      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 |
      34 | 35 |

      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 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 |
      CharacterMeaning
      !Grave
      'Acute accent
      >Circumflex accent
      ?Tilde
      -Macron
      (Breve
      .Dot above
      :Diaeresis
      ,Cedilla
      _Underline
      /Stroke
      "Double acute (Hungarumlaut)
      ;Ogonek
      <Caron
      0Ring above
      2Hook
      9Horn
      =Cyrillic
      *Greek
      %Greek/Cyrillic special
      +Smalls: Arabic, caps: Hebrew
      3Some Latin/Greek/Cyrillic
      4Bopomofo
      5Hiragana
      6Katakana
      150 | 151 |

      Discussion

      152 | 153 |

      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 |

      Opening the File Name Beneath the Cursor

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      11 | 12 |

      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 |
      34 |
      .
      35 |
      The directory containing the current file.
      36 |
      ;
      37 |
      A path that ends with a semicolon is searched recursively, 38 | up the directory hierarchy. For example /usr/share/doc; means 39 | to first search in /usr/share/doc, then /usr/share/, then 40 | /usr/, then /.
      41 |
      *
      42 |
      A path that ends in an asterisk is searched 43 | recursively downwards. For example, /home/kate/* would 44 | search all of user kate's home directory.
      45 |
      46 | 47 |

      I like gf to search recursively downwards from the current directory 48 | so I append ./** to my path like so: :set path+=./**.

      49 | 50 |

      Discussion

      51 | 52 |

      This feature has a surprising amount of uses for something so 53 | basic. I use it when:

      54 | 55 |
        56 |
      • Log files are referenced in e-mail alerts.
      • 57 |
      • To open files referenced in my version control system's commit e-mails. 58 | TODO: link recipe: Vim with VCS, Vim for 59 | Email
      • 60 |
      • When outliningThe Indentation Folding sidebar in 61 | Manually Creating Folds describes 62 | one approach to outlining in Vim a project that consists of 63 | multiple files. Each level of outline links to the relevant file.
      • 64 |
      • To view source code for external modules when writing 65 | source code.
      • 66 |
      67 | 68 |

      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 |

      Inserting the Date

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      11 | 12 |

      Use !!date in Normal mode.

      13 | 14 |

      Discussion

      15 | 16 |

      The !!command syntax executes command and 17 | replaces the current line with the output.This is 18 | in fact an oversimplification. count!!command 19 | actually filters count lines through command and 20 | returns the result, but when count is omitted, it has the effect 21 | I've described. This is why the text on the current line is 22 | replaced with the date.. To control where the date is 23 | inserted see the following paragraphs.

      24 | 25 |

      A similar same effect can be achieved with :r!date. The advantage 26 | is that it inserts the output of date on the next line, rather than 27 | replacing the current one.

      28 | 29 |

      The solutions above assume that you have a date executable in your 30 | PATH, as all UNIX-based systems should. I understand that Windows 31 | users have to use !!date /t.

      32 | 33 |

      Alternatively, you can call Vim's strftime() function, e.g. 34 | strftime("%c"). This will work on all systems which support the 35 | strftime system call, which I believe is the majority. You can map this function 37 | to a function key. For example, the following commands map 38 | <F7> to insert a date stamp after the cursor.

      39 | 40 |
      :inoremap <F7> <C-R>=strftime("%c")<CR>
      41 | :nnoremap <F7> "=strftime("%c")<CR>p
      42 | 43 |

      I suggest the use of !!date because it doesn't waste a function 44 | key, and, personally, I find it more memorable. If you intend to insert dates 45 | regularly, by all means remap a key to do so.

      46 | -------------------------------------------------------------------------------- /text/07_navigation/00.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /text/07_navigation/02_navigating_text_files.html: -------------------------------------------------------------------------------- 1 | 2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      9 | 10 |

      In Normal mode you can use the following shortcuts:

      11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 |
      KeyMove To
      {Beginning of current paragraph
      }End of current paragraph
      (Beginning of current sentence
      )End of current sentence
      wBeginning of next word
      bBeginning of the previous word
      eEnd of the word
      46 | 47 |

      Discussion

      48 | 49 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      You're editing the source code for a computer program, and want to navigate 6 | it efficiently.

      7 | 8 |

      Solution

      9 | 10 |

      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.

      14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 57 | 58 | 59 | 60 | 65 | 66 |
      KeyMove To
      %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.
      [[Backwards to the beginning of the current function.
      ][Forwards to the beginning of the current function.
      ]}Beginning of the current block.
      [{End of the current block.
      }[Beginning of the current comment block.
      }]End of the current comment block.
      gdFirst usage of the current variable name Occurrences 55 | in comments are ignored.. (Mnemonic: go to 56 | definition).
      gDGo 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.
      67 | 68 |

      Discussion

      69 | 70 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      You want to scroll through a document in screenfulls; not line by 6 | line.

      7 | 8 |

      Solution

      9 | 10 | 11 | 12 | 14 | 16 | 18 | 19 | 20 |
      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.
      21 | 22 |

      Discussion

      23 | 24 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      You have multiple files open and want to navigate between them.

      6 | 7 |

      Solution

      8 | 9 |

      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 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 56 | 57 |
      CommandResult
      :buffersView the list of buffers along with their numbers.
      :ls
      :files
      :buffer NOpen buffer N.
      :bn[ext]Go to the next buffer. (Menmonic: buffer next).
      :bp[revious]Go to the previous buffer. (Mnemonic: buffer 42 | previous).
      :bf[irst]Go to the first buffer.
      :bl[ast]Go to the last buffer.
      :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).
      58 | 59 |

      Discussion

      60 | 61 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      17 | 18 |

      Use tabs.

      19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 56 | 57 |
      CommandAction
      :tabedit [file]Open a new tab. If the optional file is supplied, that file is opened 28 | in the new tab.
      :tabcloseClose the current tab.
      :tabnext nGo to next tab, or the nth
      ngt
      :tabsShow a list of the open tabs.
      :tabprevious nGo to previous tab, or the nth
      ngT
      :tabdo cmdExecutes cmd in each open tab, aborting on the first 55 | error.
      58 | 59 |

      Discussion

      60 | 61 |

      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 |

      Manually Creating Folds

      2 | 3 |

      Problem

      4 | 5 |

      You want to fold a file, then navigate it in outline mode.

      6 | 7 |

      Solution

      8 | 9 |
      10 | 11 |
      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 |
      18 | 19 |

      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 | 27 | 28 | 29 | 31 | 33 | 34 | 35 | 39 | 40 |
      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.
      zfaBFold 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.
      41 | 42 |

      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 |

      Discussion

      48 | 49 |

      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 |
      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 |
      77 | 78 |

      To expand, collapse, and otherwise navigate folds see Navigating Folds.

      80 | -------------------------------------------------------------------------------- /text/07_navigation/08_navigating_folds.html: -------------------------------------------------------------------------------- 1 | 2 | 3 |

      Problem

      4 | 5 |

      Your document contains folds and you want to use them for 6 | navigation. (To create folds see Manually Creating 8 | Folds).

      9 | 10 |

      Solution

      11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 |
      CommandActionMnemonic
      zcClose the current fold.close fold
      zoOpen the current fold.open fold
      zMClose all folds.fold More
      zrOpen one level of folds.reduce folding
      zROpen all folds.Reduce folding
      zjMove to the next fold.j moves to the next line
      zkMove to the previous fold.k moves to the previous line
      zmClose one level of folds.Fold more
      znDisable folding.no folds
      zNRe-enable folding.N is n toggled
      69 | 70 |

      Discussion

      71 | 72 |

      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 |

      Splitting the Screen

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      14 | 15 |

      Use Vim's split screen feature to divide the screen into multiple panes, 16 | each of which can display a file.

      17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 |
      CommandAction
      :split fileSplits the window horizontally.
      :vsplit fileSplits the window vertically.
      32 | 33 |

      (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 |

      Discussion

      53 | 54 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      You want to bookmark specific points in a file so you can easily 6 | jump to them from elsewhere.

      7 | 8 |

      Solution

      9 | 10 |

      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 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 |
      CommandAction
      mMMark the current position as M.
      'MJump to the first character of the line containing M.
      `MJump to the position of mark M.
      31 | 32 |

      Discussion

      33 | 34 |

      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 | 2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      14 | 15 |

      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 |

      Discussion

      37 | 38 |

      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 |

      Bookmarking Lines with Visible 2 | Markers (Signs)

      3 | 4 |

      Problem

      5 | 6 |

      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 |

      Solution

      13 | 14 |

      Vim allows you to define a sign and then associate it with one or 15 | more lines of a file. It is displayed in the right-hand margin as a 16 | two-character string in the terminal, and an icon in Gvim.

      17 | 18 |

      Before you use a sign you must define it. For example:

      19 | 20 |
      :sign define fixme text=!! linehl=Todo texthl=Error icon=/path/to/todo.xpm
      21 | 22 |

      Let's break this down. We name the sign fixme, which is how we'll 23 | refer to it later. We specify that in the terminal the sign should be 24 | displayed as !!, and that in the GUI the icon stored at 25 | /path/to/todo.xpm should be used instead. The linehl argument 26 | defines the highlight group used for the entire line the sign is attached to; 27 | texthl defines the highlight 28 | group for the sign itself.

      29 | 30 |

      Now the sign is defined, presumably in vimrc, you can use it 32 | in any file. To attach the sign to a specific line you use:

      33 | 34 |
      :sign place id line=line name=name
      35 | file=file-path
      36 | 37 |

      For example:

      38 | 39 |
      :sign place 22 line=200 name=fixme file=/home/user/novel.txt
      40 | 41 |

      The id is arbitrary, but must be unique and numeric. The 42 | name is the same name you used when you defined the sign. The value 43 | of the line argument is the number of the line on which the sign 44 | should be attached. The file argument is the full path (no 45 | expansion is done) to a currently loaded file to which the sign should be 46 | attached. So, in the above example, two exclamation marks are inserted in the 47 | margin of the 200th line of /home/user/novel.txt.

      48 | 49 |

      Discussion

      50 | 51 |

      You only need to define signs once, so that's easy enough, but the syntax 52 | for placing signs is particularly unwieldy. Let's look at some alternative 53 | approaches.

      54 | 55 |

      You could place the following stanza in your vimrc so 56 | <F5> places the previously defined fixme sign on the 57 | current line of the current file:

      58 | 59 |
      function! SignFixme()
      60 |   execute(":sign place ".line(".")." line=".line(".")." name=fixme file=".expand("%:p"))
      61 | endfunction
      62 | map <F5> :call SignFixme()<CR>
      63 | 64 |

      Rather than placing signs manually, you may prefer to have them 65 | automatically placed on lines satisfying some criteria. The following stanza 66 | attaches the fixme sign to lines containing notes like TODO: check 67 | for race conditions. It operates on the current line or selection. So, 68 | you can select a range of lines, press <F6> then have your 69 | to-do list items flagged in the margin.

      70 | 71 |
      function! SignLines() range
      72 |   let n = a:firstline
      73 |   execute(":sign define fixme text=!! texthl=Todo")
      74 |   while n <= a:lastline
      75 |     if getline(n) =~ '\(TODO\|FIXME\)'
      76 |       execute(":sign place ".n." line=".n." name=fixme file=".expand("%:p"))
      77 |     endif
      78 |     let n = n + 1
      79 |   endwhile  
      80 | endfunction
      81 | map <F6> :call SignLines()<CR>
      82 | -------------------------------------------------------------------------------- /text/08_gui/00.html: -------------------------------------------------------------------------------- 1 |

      GUI (GVim)

      2 | -------------------------------------------------------------------------------- /text/08_gui/01_changing_the_font.html: -------------------------------------------------------------------------------- 1 |

      Changing the Font

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      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 |
      Specifying guifont in an Operating-System-Specific Manner
      22 | 23 |
      Linux
      24 | 25 |
        26 |
      • The font name and size are space separated.
      • 27 |
      • Spaces and commas need to be backslash escaped.
      • 28 |
      29 | 30 |

      For example: :set guifont=Andale\ Mono\ 11.

      31 | 32 |
      Mac
      33 | 34 |
        35 |
      • 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 |
      39 | 40 |

      For example: :set guifont=Monaco:h11. 41 | 42 |

      Windows
      43 | 44 |
        45 |
      • 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 |
      49 | 50 |

      For example: :set guifont=Andale_Mono:h11.

      51 | 52 |
      53 | 54 |

      Discussion

      55 | 56 |

      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 |

      Maximising Screen Space

      2 | 3 |

      Problem

      4 | 5 |

      The toolbar, menubar, and other GUI artifacts take up too much of your 6 | screen; you want to hide them.

      7 | 8 |

      Solution

      9 | 10 |

      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 |
        16 |
      • m - Display a menu bar.
      • 17 |
      • T - Display a toolbar.
      • 18 |
      • r - Always display the right-hand scrollbar.
      • 19 |
      • R - Display the right-hand scrollbar if the window is 20 | split vertically.
      • 21 |
      • l - Always display left-hand scrollbar.
      • 22 |
      • L - Display the left-hand scrollbar if the window is 23 | split vertically.
      • 24 |
      • b - Display the horizontal scrollbar.
      • 25 |
      26 | 27 |

      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 |

      Discussion

      32 | 33 |

      If you decide that you want to restore one or more of these elements you 34 | can simply execute :set guioptions+=m, for example. This can be 35 | cumbersome, however, as it requires you to remember the significance of each 36 | letter.

      37 | 38 |

      The following stanza in your gvimrc 39 | assigns <F11> to toggle the display of extraneous GUI 40 | elements:

      41 | 42 |
      function ToggleGUICruft()
      43 |   if &go==''
      44 |     exec('se go=mTrL')
      45 |   else
      46 |     exec('se go=')
      47 |   endif
      48 | endfunction
      49 | map <F11> <Esc>:call ToggleGUICruft()<cr>
      50 | -------------------------------------------------------------------------------- /text/08_gui/03_creating_menus_and_toolbar_buttons.html: -------------------------------------------------------------------------------- 1 |

      Creating Menus and Toolbar Buttons

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      14 | 15 |

      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 |

      Discussion

      27 | 28 |

      You're not restricted to adding items to existing menus; you can create a 29 | new top-level menu simply by specifying a name not currently in use. For 30 | example:

      31 | 32 |
      :amenu <silent>&Vim.vim\.org :!xdg-open http://www.vim.org/<cr>
      33 | 34 |

      will create a new top-level menu called Vim with the shortcut key 35 | V. It will contain one entry named vim.org (we escape the 36 | . because otherwise it would create a vim entry which in turn 37 | contain an org item). When invoked it will open the Vim website on 38 | systems adhering to the Free Desktop Specification. The 39 | <silent> prefix prevents the command from being echoed on the 40 | command-line.

      41 | 42 |

      If you want to add a dashed separator line between menu items use a menu 43 | item named -SEP- and an empty command, e.g. :amenu Help.-SEP- 44 | :.

      45 | 46 |

      To control where a top-level menu appears relative to its neighbours you 47 | need to prefix amenu with a numeric priority: the lower the number 48 | the further right the menu's position. For example, :5amenu First.first 49 | :echo 'first'<cr> creates a top-level menu named First 50 | that appears before all of the others.

      51 | 52 |

      The same approach can be used to position menu items. For example, 53 | :amenu 9999.1 Help.first :echo 'first'<cr> adds a first 54 | item to the Help menu, which appears before the other items.

      55 | 56 |

      You can also use :amenu to add a new toolbar icon:

      57 | 58 |
      :amenu icon=image-path Toolbar.item-name
      59 | command
      60 | 61 |

      For example:

      62 | 63 |
      :amenu icon=options.png ToolBar.OptionsHelp :help<cr>
      64 | 65 |

      If the image-path consists only of a filename, as above, Vim prepends 66 | $VIMRUNTIME/bitmaps/ to it.

      67 | -------------------------------------------------------------------------------- /text/09_searching/00.html: -------------------------------------------------------------------------------- 1 |

      Searching

      2 | -------------------------------------------------------------------------------- /text/09_searching/01_searching_for_any_word.html: -------------------------------------------------------------------------------- 1 |

      Searching for any Word

      2 | 3 |

      Problem

      4 | 5 |

      You want to search the current file for an arbitrary word.

      6 | 7 |

      Solution

      8 | 9 |

      Use /word to search forward in the file; 10 | ?word to search backward.

      11 | 12 |

      Discussion

      13 | 14 |

      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 |

      Searching Over Multiple Files

      2 | 3 |

      Problem

      4 | 5 |

      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 |

      Solution

      10 | 11 |

      Use the :vimgrep command: :vimgrep /pattern/ 12 | [flags] file0 file1 13 | fileN.

      14 | 15 |

      Discussion

      16 | 17 |

      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 |
      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 |
      45 | 46 |

      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 |

      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 |
      62 | 63 |

      The j flag inhibits the jumpiness (Ritalin for Vim); 64 | simply saving the search results to the quickfix list (see sidebar for 65 | details) and leaving your cursor where it was.

      66 | 67 |

      The g flag controls how lines matching the pattern multiple times are 68 | handled. If not present (by default), only the first match of a line is shown; 69 | otherwise, every occurrence of the pattern is regarded as a separate match.

      70 | 71 |

      The flags can be combined in either order.

      72 | 73 |
      74 | 75 |
      Quick Fix List
      76 | 77 |

      The quick fix list mentioned above is a Vim concept for creating a 78 | temporary index of positions in a file. vimgrep stores its results (a 79 | file name, a position within that file, and the matched text) in the quick fix 80 | list.

      81 | 82 |

      To view the quick fix list (i.e. the results of the last search) use 83 | :cl[ist]. The results are numbered, so you can jump to a specific one with 84 | :cc number.

      85 | 86 |

      For more information see :help quickfix.

      87 | 88 | -------------------------------------------------------------------------------- /text/09_searching/03_searching_and_replacing.html: -------------------------------------------------------------------------------- 1 |

      Searching and Replacing

      2 | 3 |

      Problem

      4 | 5 |

      You want to replace all occurrences of one string with another.

      6 | 7 |

      For example, imagine you were using Vim to write a novel wherein there was 8 | a protaganist named Curtis. You decide to change his name to 9 | Excalibur to give him more panache. You want Vim to make these changes 10 | with the least possible effort.

      11 | 12 |

      Solution

      13 | 14 |

      Execute :%s/target/replacement/g to replace 15 | all occurrences of target with replacement. For example: 16 | :%s/Curtis/Excalibur/g.

      17 | 18 |

      Description

      19 | 20 |

      The solution above replaces Curtis with Excalibur. The 21 | g flag at the end causes this operation to be performed 22 | globally, i.e. multiple times on each line, if necessary.

      23 | 24 |

      The % prefix indicates that the replacement should occur over the 25 | entire file. Had you previously visually selected text to which you want to 26 | constrain the search/replace operation omit the %, e.g. 27 | :s/Curtis/Excalibur/g. Or, prefix the command with a range to 28 | contstrain it that way, e.g. 2,20s/Curtis/Excalibur/g performs the 29 | operation over lines two to twenty.

      30 | 31 |

      The search string (Curtis in this example) doesn't have to be a 32 | literal string; it can be any Vim regular expression. The details of Vim's 33 | regular expressions are explained in the Creating Regular Expressions 35 | recipe, so I won't go into them here. Two tips, though:

      36 | 37 |
        38 |
      • Search for words - If you provide a literal string to replace, as above, 39 | Vim even replaces occurrences that form parts of other words. For example 40 | :%s/and/or/g would change supply and demand into supply 41 | or demor. To avoid this, surround the string with word boundary 42 | anchors (\<, \>). Thus, the above command 43 | could be rewritten as :%s/\<and\>/or/g.
      • 44 |
      • Search case insensitively - If you want linux to match 45 | Linux, linux, and LiNuX you need to either add the 46 | i flag to the end of the replacement command, or, use :set 47 | ignorecase to enable this behaviour for all searches.
      • 48 |
      49 | -------------------------------------------------------------------------------- /text/09_searching/04_searching_for_the_word_beneath_the_cursor.html: -------------------------------------------------------------------------------- 1 |

      Searching for the Word Beneath the 2 | Cursor

      3 | 4 |

      Problem

      5 | 6 |

      You want to search the current document for the word underneath your cursor. 7 | You'd rather not type it in again.

      8 | 9 |

      Solution

      10 | 11 |

      In Normal mode, place your cursor on or just in front of the word 12 | you wish to find, then press * (mnemonic: star search). This will 13 | jump to the next occurrence of the word in the current file. 14 | Alternatively, pressing # will find the previous 15 | occurrence.

      16 | 17 |

      Discussion

      18 | 19 |

      After finding the first match using either of the above methods, you can 20 | press the n (mnemonic: next match) key to jump to the next 21 | match. To jump to the previous match, use N.

      22 | 23 |

      To search for words containing the current word, press g* 24 | or g#, as appropriate. For instance, if the current word is 25 | back, g* will jump to hunchback.

      26 | -------------------------------------------------------------------------------- /text/09_searching/07_looking_up_docs_for_the_word_beneath_the_cursor.html: -------------------------------------------------------------------------------- 1 |

      Looking up Documentation for the Keyword Under the Cursor

      2 | 3 |

      Problem

      4 | 5 |

      You want to invoke an external command to lookup documentation for the 6 | keyword underneath the cursor. For example, Linux users may like to read the 7 | manual for the named command with the man utility.

      8 | 9 |

      Solution

      10 | 11 |

      Use :set keywordprg=program, then hit K while hovering 12 | over the word.

      13 | 14 |

      Discussion

      15 | 16 |

      This recipe calls the command specified with :set keywordprg, 17 | passing the current wordword is used in the sense of a 18 | string that looks like a word to Vim; it is not necessarily a valid word in 19 | your language. as an argument. Thus, if keywordprg = 20 | man, then hovering over the word ls and hitting K 21 | would display the documentation for Linux's ls command.

      22 | 23 |

      When used with man, Vim translates a count for the K 24 | command into a section number. So 7K over glob invokes 25 | man 7 glob to display section 7 of the glob 26 | documentation.

      27 | 28 |

      The Ruby programming language has a utility called ri that displays 29 | documentation about the given Ruby method. The Perl programming language has a 30 | similar command called perldoc. By setting keywordprg 31 | appropriately, you can make context-sensitive documentation lookup 32 | trivial.

      33 | -------------------------------------------------------------------------------- /text/10_display/00.html: -------------------------------------------------------------------------------- 1 |

      Display

      2 | -------------------------------------------------------------------------------- /text/10_display/01_working_with_long_lines.html: -------------------------------------------------------------------------------- 1 |

      Working with Long Lines

      2 | 3 |

      Problem

      4 | 5 |

      Your file contains lines which are too long to fit on the screen. You find 6 | it hard to edit and view.

      7 | 8 |

      Solution

      9 | 10 |

      The :set wrap command, which should be on by default, changes how 11 | long lines are displayed. Once they reach the right margin they are broken, 12 | and continued on the line below. (To disable this behaviour: :set 13 | nowrap).

      14 | 15 |

      wrap only changes the way the lines are displayed, however; the 16 | file will not be changed. It inserts soft line breaks.

      17 | 18 |

      This means that a file containing two particularly long lines may be 19 | represented by Vim as having 5 lines, for example, after wrapping. If you try 20 | to navigate this file using the basic movement 21 | commands j would move between the two logical lines, rather 22 | than the screen lines. The solution is to prefix the movement commands 23 | with g, so gj moves down one screen line.

      24 | 25 |

      If using wrap, you can specify what point the line should be 26 | broken by executing :set linebreak. This uses the value of 27 | breakat to decide where to break the line. To change the characters 28 | used modify breakat.

      29 | 30 |

      You can use :set textwidth=width to enforce a maximum 31 | line length, after which the text is broken with a "hard" line break. Vim 32 | breaks at white space, so lines may be shorter than width. To 33 | reformat existing text according to this preference either select them 34 | visually and hit gq or, in Normal mode, you can reformat the 35 | current paragraph with gqap.

      36 | 37 |

      Discussion

      38 | 39 |

      In general, you'll be better off using hard line breaks with 40 | textwidth. This removes the need to differentiate between logical lines 41 | and screen lines, and means that the file will display reasonably in any 42 | editor, even if it doesn't wrap long lines.

      43 | 44 |

      Traditionally, text file lines are kept under 80 characters. This is 45 | mainly a holdover from the days of terminals whose displays were limited in 46 | this way, but is still customary in many programming languages and e-mail. To 47 | enforce this restriction just :set textwidth=80.

      48 | 49 |

      There's another way to insert hard line breaks without specifying a maximum 50 | line length. It is called wrapmargin and wraps lines relative to the 51 | width of the terminal window. For example, :set wrapmargin=4 means 52 | that when a line is more than four characters away from the right-hand margin, 53 | it is broken. This approach is more flexible than textwidth, but has 54 | the disadvantage of producing files which will display poorly on smaller 55 | displays or when the screen is split between multiple files. Especially if 56 | you're sharing the files you produce with others, I suggest the use of 57 | textwidth instead.

      58 | 59 |
      60 |

      textwidth takes precedence over wrapmargin. For 61 | wrapmargin to take effect textwidth must be zero, as it 62 | is by default.

      63 |
      64 | -------------------------------------------------------------------------------- /text/10_display/02_displaying_line_numbers.html: -------------------------------------------------------------------------------- 1 |

      Displaying Line Numbers

      2 | 3 |

      Problem

      4 | 5 |

      You want to see each line's number alongside it. For example, if you’re 6 | writing a program, error messages frequently reference line numbers.

      7 | 8 |

      Solution

      9 | 10 |

      Use :set number to enable line numbering. If you're using a small 11 | monitor, you may want to disable them: :set nonumber.

      12 | 13 |

      Discussion

      14 | 15 |

      Even if you're not programming, line numbers can still be useful. For 16 | example, if you’re collaborating on a file with other people, they may mention 17 | specific lines, which you can then jump to with :number. 18 | If you’re wrapping long lines, the line 19 | number can be used to differentiate the beginning of the line from the point 20 | at which it has been wrapped.

      21 | 22 |

      By default the number column is at least 4 characters wide, regardless of 23 | how many lines the file has. To change this minimum width use :set 24 | numberwidth=width.

      25 | 26 |

      The line numbers are only displayed when you’re viewing the file with Vim; 27 | the actual file isn't modified. If you'd like it to be, and you have the 28 | cat command on your system, you can execute :%!cat -n %. 29 | This filters the entire file through cat and prepends the number to 30 | each line.

      31 | 32 |

      Lastly, if you'd like to see the line numbers when you print the file 33 | without permanently changing its contents: :set 34 | printoptions=number:y.

      35 | -------------------------------------------------------------------------------- /text/10_display/03_working_with_remote_files.html: -------------------------------------------------------------------------------- 1 |

      Working with Remote Files

      2 | 3 |

      Problem

      4 | 5 |

      You want to edit/view a file that is stored on another computer.

      6 | 7 |

      For example, you might want to change a file on your website from your home 8 | computer. Or, you want to change the message of the day file on a 9 | server you administer.

      10 | 11 |

      Solution

      12 | 13 |

      To invoke Vim with a remote file use its URL as the argument to 14 | vim. For example: vim 15 | sftp://guest@example.com/file.txt.

      16 | 17 |

      To work with remote files from within Vim, just use their URLs in place of 18 | a filename with normal editing commands.

      19 | 20 |

      So, to to open a remote file for editing use :e URL. 21 | For example: :e ftp://user@example.com/README.

      22 | 23 |

      To save to a remote file use :w URL. For example: 24 | :w scp://kci@jojo.example.com/etc/motd.

      25 | 26 |

      Discussion

      27 | 28 |

      Vim supports the following protocols: SCP, SFTP, RCP, HTTP (read-only), WebDAV, 33 | rsync (read-only), and fetch (read-only). However, it relies on 34 | external programs to do so. On Linux, most of these programs are available by 35 | default; on Windows, for example, only FTP is normally 37 | available. See :help netrw-externapp for more information.

      38 | 39 |

      If the protocol requires authentication, you can supply the username as 40 | part of the URL, and then be prompted for the password interactively. This 41 | gets boring fast, however.

      42 | 43 |

      If you're editing files via SSH or SCP consider setting up passwordless 45 | logins. The principle is explained in Password-less 47 | logins with OpenSSH for Debian Linux, but it is much for the same 48 | for other operating systems.

      49 | 50 |

      If you're using FTP on Linux, you can store your credentials in 51 | ~/.netrc'. The file is formatted as 52 | follows:

      53 | 54 |
      machine {host name 1}
      55 |          login {username}
      56 |          password {password}
      57 | 
      58 |  machine {host name 2}
      59 | ...
      60 | 61 |

      It should be made read-only for your user: chmod 600 ~/.netrc 62 | Windows explanation?. Now you can use URLs like 63 | ftp://example.org/README, and it will find your username and password 64 | automatically.

      65 | 66 |
      67 |

      ⚠ FTP is an insecure protocol, so please don't use it unless you must. 68 | SSH/SFTP/SCP are all superior alternatives.

      69 |
      70 | -------------------------------------------------------------------------------- /text/10_display/04_changing_the_status_line.html: -------------------------------------------------------------------------------- 1 |

      Changing the Status Line

      2 | 3 |

      Problem

      4 | 5 |

      You don't like the way the status line looks or would prefer if it displayed 6 | different types of information.

      7 | 8 |

      For example, you work with files created on different operating systems, so 9 | you'd like the file format (e.g. unix, MS-Windows, or 10 | mac) to be displayed along the bottom of the screen.

      11 | 12 |

      Solution

      13 | 14 |

      Use the :set statusline command along with a format string. The format 15 | string is the text you want displayed interspersed with variable names 16 | corresponding to the types of information you want included.

      17 | 18 |
      19 |

      By default Vim hides the status line. To show it: :set 20 | laststatus=2.

      21 |
      22 | 23 |

      For example, to display the file format you could use :set 24 | statusline=%{&ff}. You can surround this with arbitrary text, for example: 25 | :set statusline=format:\ %{&ff}.

      26 | 27 |

      Here are some common variables the status line can display:

      28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 38 | 40 |
      Name Description
      bValue of byte under cursor.
      cColumn number.
      lLine number.
      rDisplays [RO] if file is read only.
      tFile name (as opposed to file path)
      yFile content type, e.g. [ruby] or 37 | [latex].
      \&ffFile format, e.g. unix, mac, 39 | dos.
      41 | 42 |

      Variable names are prefixed with a percentage sign (%). Spaces, 43 | bars (|), and other special characters need to be backslash 44 | escaped.

      45 | 46 |

      Here's a longer example:

      47 | 48 |
      :set statusline=%t\ %y\ format:\ %{&ff};\ [%c,%l]
      49 | 50 |

      Sample output: .vimrc [vim] format: unix [2,3].

      51 | 52 |

      Discussion

      53 | 54 |

      You may have noted that the syntax for displaying the file format was 55 | different from the other variables. The %{} syntax evaluates the 56 | expression contained within the braces and displays the result.

      57 | 58 |

      For example, to display the name of the current colour scheme: 59 | %{g:colors_name} (example output: morning). Or the 60 | current language: %{v:lang} (example output: 61 | en_GB.UTF-8). Here we are simply displaying the value of Vim 62 | internal variables. (See :let for a list).

      63 | 64 |

      The reason %{&ff} works is because ff is the Vim 65 | option for getting/setting the file format, and the & prefix is 66 | used for referring to options. The value of any option can be displayed in 67 | this way.

      68 | 69 |

      You can even call a function in this way. For example, to show the last 70 | modification time of the current file:

      71 | 72 |
      \%{strftime(\"\%c\",getftime(expand(\"\%\%\")))}
      73 | 74 |

      Sample output: Fri 01 May 2009 19:26:07 BST

      75 | -------------------------------------------------------------------------------- /text/10_display/05_redefining_highlight_groups.html: -------------------------------------------------------------------------------- 1 |

      Redefining Highlight Groups

      2 | 3 |

      Problem

      4 | 5 |

      You want to change the colours of specific elements of the display. For 6 | example, you want text to be white on a black background.

      7 | 8 |

      Solution

      9 | 10 |

      Use the :highight group definition command.

      11 | 12 |

      A highlight group (group) is an element of the display 13 | whose colours can be customised. Some of the default highlight groups are:

      14 | 15 |

      Is a list the right way to present this?

      16 | 17 |
      18 |
      Cursor
      19 |
      Character under the cursor.
      20 |
      ErrorMsg
      21 |
      Command line error messages.
      22 |
      Normal
      23 |
      Normal text.
      24 |
      Visual
      25 |
      Text selected under Visual mode.
      26 |
      27 | 28 |

      The definition is a list of key-value pairs. For example, the 29 | following sets the terminal foreground colour to black and 30 | the terminal background colour to yellow:

      31 | 32 |
      :highlight Normal ctermfg=black ctermbg=yellow
      33 | 34 |

      These are some common arguments:

      35 | 36 |
      37 |
      ctermfg
      38 |
      Terminal foreground colour.
      39 |
      ctermbg
      40 |
      Terminal background colour.
      41 |
      term
      42 |
      Terminal font style, e.g. bold, italic, 43 | underline.
      44 |
      guifg
      45 |
      GUI foreground colour.
      46 |
      guibg
      47 |
      GUI background colour.
      48 |
      49 | 50 |

      Apart from term, these arguments take a colour name or number as a 51 | value. Recognised colour names include black, brown, 52 | grey, blue, green, cyan, magenta, 53 | yellow, and white.

      54 | 55 |

      The arguments that are not supplied retain their previous values. For 56 | example, :highlight Normal\ ctermbg=white changes the background 57 | colour to white, but keeps the previous foreground colour.

      58 | 59 |

      Let's look at some examples:

      60 | 61 |
        62 |
      • :highlight Visual term=bold - Text that has been selected using 63 | Visual mode is rendered in bold.
      • 64 |
      • :highlight Comment ctermfg=grey ctermbg=white term=bold - 65 | Comments are rendered in bold, grey text.
      • 66 |
      67 | 68 |

      Discussion

      69 | 70 |

      Normally you'll select a colour 71 | scheme, and not define highlighting groups at all. Occasionally, though, 72 | you want more control over colours or need to edit a syntax file. That's 73 | where the :highlight command comes in.

      74 | 75 |

      Before you change highlight groups you may like to check their current 76 | values. You can do this with :highlight group. To view 77 | all current settings use :highlight.

      78 | 79 |
      80 | 81 |
      Defining a Highlight Group
      82 | 83 |

      You can define your own highlight group by using the :highlight 84 | command as described above with a group name of your choice. To select what is 85 | highlighted you use :match group 86 | /pattern/. For example:

      87 | 88 |
      :highlight Elephant ctermbg=grey ctermfg=white
      89 |   :match Elephant /\celephant/
      90 | 91 |

      This renders all occurrences of the word elephant, regardless of 92 | case due to the \c escape, in white on grey. 93 | 94 |

      95 | -------------------------------------------------------------------------------- /text/10_display/06_modifying_the_cursor.html: -------------------------------------------------------------------------------- 1 |

      Modifying the Cursor

      2 | 3 |

      Problem

      4 | 5 |

      You want to make the cursor easier to see.

      6 | 7 |

      For example, you're using visually “busy” syntax highlighting, 8 | and sometimes lose the cursor. Or, you're working with columnar data, and need 9 | the entire column that the cursor is over to be highlighted.

      10 | 11 |

      Solution

      12 | 13 |

      To change the cursor colour in Gvim redefine the Cursor highlighting 14 | groupThe Creating 15 | Highlight Groups recipe explains how to redefine highlight groups, but 16 | in standard Vim the terminal defines the cursor colour..

      17 | 18 |

      Another approach is to highlight the line the cursor is on. You do this by 19 | executing :set cursorline. Again, to change the colours modify the 20 | CursorLine highlighting group.

      21 | 22 |

      Similarly, you can highlight the current column the cursor is in with 23 | :set cursorcolumn. The highlight group is, predictably, called 24 | CursorColumn.

      25 | 26 |

      If you want your terminal to resemble a sniper's sights, you can combine both 27 | line and column highlighting to create a cross-hair effect, as shown below.

      28 | 29 |

      Discussion

      30 | 31 |

      Gvim allows you to customise every conceivable aspect of the cursor display 32 | with the command :set guicursor. This allows you to change the 33 | cursor's appearance based on the mode (i.e. one colour for Insert mode, 34 | another for Normal), its height, and control whether it blinks… This is 35 | achieved by providing a format string as the value for 36 | guicursor. Here are some examples:

      37 | 38 |
        39 |
      • n-c-v:ver50-ncvCursor - In Normal, Command, and Insert mode set 40 | the cursor to a vertical bar 50% of the current character's width. Highlight 41 | it with the ncvCursor group.
      • 42 |
      • i:block-iCursor-blinkon0,v:block-vCursor - In Insert mode use a 43 | non-blinking block cursor highlighted with the iCursor highlighting 44 | group. In Visual mode also use a block cursor, but highlight it with 45 | vCursor.
      • 46 |
      47 | 48 |

      The above examples should be adaptable for your uses. For the gritty detail 49 | of the supported syntax look at :help guicursor.

      50 | -------------------------------------------------------------------------------- /text/10_display/07_changing_the_window_title.html: -------------------------------------------------------------------------------- 1 |

      Changing the Window Title

      2 | 3 |

      Problem

      4 | 5 |

      You want to change the title of a Vim window to make it more 6 | descriptive.

      7 | 8 |

      Solution

      9 | 10 |

      Assign a value to the titlestring option, and set the 11 | title option. For example:

      12 | 13 |
      :set title titlestring=My\ Title
      14 | 15 |

      Discussion

      16 | 17 |

      When working with multiple instances of Vim, it can be difficult to 18 | remember what task each window corresponds to. You can avoid this problem by 19 | customising each window's title. The window title can also function similarly 20 | to the status line, reminding the user 21 | about an important aspect of the current file.

      22 | 23 |

      The default window title contains the current filename, followed by a 24 | character indicating the state of this file, followed by the name of its 25 | directoryTo be precise, the directory name is followed by a 26 | hyphen then the value of &v:servername, if set, otherwise 27 | just VIM.. The state character is one of the following:

      28 | 29 |
      30 |
      -
      File can't be modified
      31 |
      +
      File has been modified
      32 |
      =
      File is read-only
      33 |
      =+
      File is read-only and has been modified
      34 |
      35 | 36 |

      This is already quite a descriptive title, but we can customise it further 37 | using a format string, as described in the Changing the Status Line recipe. The Vim 39 | documentation (:help titlestring) gives the following example:

      40 | 41 |
      :auto BufEnter * let &titlestring = hostname() . "/" .
      42 | expand("%:p")
      43 | 44 |

      Here the window title is reset when the user enters a new buffer. It 45 | contains the hostname, a forward slash, then the full path of the current 46 | fileFor an explanation of the %:p syntax see the Filename Modifiers section of the Executing External Commands 49 | recipe..

      50 | 51 |

      Another example is to display the value of an environment variable in the 52 | window title along with the filename. For instance, Ruby on Rails developers 53 | could prefix the filename with the value of RAILS_ENV, which 54 | indicates whether the application is in development, production, staging, or 55 | testing mode:

      56 | 57 |
      let &titlestring=expand($RAILS_ENV) . ": " .
      58 | expand("%:t")
      59 | 60 |

      One last trick is to embed the value of an external command in the window 61 | title using the %{system('command')} syntax. This could be 62 | used to display the name of the current branch, if using a version control 63 | system, or indicate whether the project's unit tests are passing or 64 | failing.

      65 | -------------------------------------------------------------------------------- /text/11_extending/00.html: -------------------------------------------------------------------------------- 1 |

      Extending

      2 | -------------------------------------------------------------------------------- /text/11_extending/01_creating_keyboard_shortcuts_with_key_mappings.html: -------------------------------------------------------------------------------- 1 |

      Creating Keyboard 2 | Shortcuts with Key Mappings

      3 | 4 |

      Problem

      5 | 6 |

      You'd like to execute a command, or series thereof, with a keyboard 7 | shortcut rather than continually type it in. Or, you'd like to change an 8 | existing keyboard shortcut so that it does something more useful.

      9 | 10 |

      For example, you use the <Space> key to page down in other 11 | applications, and you'd like to do the same in Vim. Or, you regularly reformat 12 | paragraphs with gqap, but would prefer to simply hit 13 | Q.

      14 | 15 |

      Solution

      16 | 17 |

      Use key mappings. A map is simply a key combination followed by 18 | another key combination. When you enter the first key combination Vim acts as 19 | if you entered the second.

      20 | 21 |

      For example, to remap <Space> to 22 | <PageDown> you execute :map <Space> 23 | <PageDown>. The map command creates a mapping for 24 | Normal, Visual, and Operator 25 | Pending mode; i.e. if you press <Space> in 26 | Insert mode this mapping, thankfully, has no effect.

      27 | 28 |

      Mapping Q to gqap is similarly straight forward: 29 | :nmap Q gqap. Unlike map, :nmap only takes effect 30 | in Normal mode. We used nmap here because this mapping doesn't make 31 | sense in other modes: in Insert mode we want Q to insert a literal 32 | Q, and in Visual mode we want to reformat the selected text rather than 33 | the current paragraph. The Visual mode mapping is :vmap Q gq.

      34 | 35 |

      The other main types of mapping commands are:

      36 | 37 |
      38 |
      :imap
      39 |
      Insert mode only.
      40 |
      :cmap
      41 |
      Command-line only.
      42 |
      :map
      43 |
      Normal, Visual, and Operator-pending.
      44 |
      45 | 46 |

      Discussion

      47 | 48 |

      Keyboard mapping is yet another way to save valuable keystrokes. If you 49 | find yourself executing a command repeatedly create a mapping. It's also 50 | useful for creating more sensible aliases for existing keyboard shortcuts that 51 | you can never quite remember.

      52 | 53 |

      It's generally recommended to map the function keys 54 | (<F1>-<F12>), as well as their shifted 55 | counterparts (e.g. <Shift>-<F3>) 56 | because they're not used by Vim<F1> 57 | is used for :help but pretty useless given that you'd 58 | normally use :help topic.. As long as you use a 59 | combination that doesn't interfere with the commands you do use, you're free 60 | to use whatever you want, though.

      61 | 62 |

      Before you create a mapping you might like to check what, if anything, it's 63 | currently being used for. You can do this by executing :help 64 | key, e.g. :help <F1> will show that Vim maps 65 | it to :help. If you want to see the user-defined mappings (whether 66 | set by you or a plugin) call the :map command with no arguments. This 67 | works will the mode-specific map commands outlined above, too, so 68 | :imap will show Insert mode mappings.

      69 | -------------------------------------------------------------------------------- /text/11_extending/02_changing_the_colour_scheme.html: -------------------------------------------------------------------------------- 1 |

      Changing the Colour Scheme

      2 | 3 |

      Problem

      4 | 5 |

      You don't like the colours Vim uses; you want to change them.

      6 | 7 |

      For example, you've found a colour scheme you like better, so want to 8 | instruct Vim to use it. Or, you find that the current colour scheme makes text 9 | hard to read so want to find a more suitable one.

      10 | 11 |

      Solution

      12 | 13 |

      To browse existing colour schemes enter :colourscheme, then hit 14 | <Tab> to cycle through the installed schemes. If you find one 15 | that you like hit <Enter> to apply it.

      16 | 17 |

      Discussion

      18 | 19 |

      A colour scheme is a set of rules controlling how different elements of the 20 | interface appear. Vim is distributed with a selection of colour schemes, but 21 | you can also download new ones, as explained in the sidebar.

      22 | 23 |
      24 |

      The Vim 25 | Color Scheme Test is a a gallery of colour schemes along with their 26 | names. Browse through it to select a theme you like, then follow the 27 | instructions below to install it.

      28 |
      29 | 30 |
      31 |
      Installing Colour Schemes
      32 | 33 |
        34 |
      1. Browse the available colour schemes at Vim.org 36 | and download any that you like.
      2. 37 |
      3. Create a $VIM/colors, e.g. mkdir -p ~/.vim/colors on 38 | POSIX systems.
      4. 39 |
      5. Copy the .vim file you downloaded in step one to the 40 | colors directory you just created.
      6. 41 |
      7. Open vim then execute :colorscheme name, 42 | where name is that of the file you downloaded without the 43 | .vim extension.
      8. 44 |
      9. If you want to use this colour scheme permanently add colorscheme 45 | name to your vimrc; otherwise repeat these steps 47 | with a different colour scheme.
      10. 48 |
      49 |
      50 | 51 |

      Before you change your color scheme you may like to make a note of what 52 | you're using at the moment. You can find the name of the current scheme with 53 | :echo 54 | g:colors_name.

      55 | 56 |

      To change a specific aspect of a colour scheme you can redefine a highlight group.

      58 | -------------------------------------------------------------------------------- /text/11_extending/03_creating_command-line_commands.html: -------------------------------------------------------------------------------- 1 |

      Creating Command-Line Commands

      2 | 3 |

      Problem

      4 | 5 |

      You want to create your own :command command.

      6 | 7 |

      Solution

      8 | 9 |

      Use the :command command like so::command name 10 | command, where name is the command you're 11 | creating and command the command name should execute. 12 | (name must start with an initial capital)

      13 | 14 |

      For example, :command Ls !ls -all % lets you use :Ls to 15 | view the long listing for the current file on POSIX systems, thus 16 | showing the permissions, owner, group, etc.

      17 | 18 |

      Discussion

      19 | 20 |

      The command can be anything you could enter at the : 21 | prompt.

      22 | 23 |

      You can modify how the command is defined by supplying :command with 24 | a list of arguments with the syntax :command arg1, 25 | arg2, … ,argN name 26 | command. These are not to be confused with arguments passed to 27 | the command, itself, however.

      28 | 29 |

      To create a command that accepts arguments you use the syntax :command 30 | -nargs=spec name command, where 31 | spec is:

      32 | 33 |
      34 |
      1
      35 |
      One argument.
      36 |
      *
      37 |
      Any number of arguments.
      38 |
      ?
      39 |
      Zero or one arguments.
      40 |
      +
      41 |
      One or more arguments.
      42 |
      43 | 44 |

      You reference the arguments in command with the 45 | <args> placeholder. The <q-args> quotes 46 | special characters in the argument. For example, you could use :command 47 | -nargs=1 Ci !cd %:h && git commit %:t -m <q-args> to 48 | quickly change to the directory containing the current file (%:h is 49 | the current pathname with the last component removed) and commit the current 50 | file (%:t is the last component of the current pathname) to a Git 51 | repository by typing :Ci message, without worrying about 52 | using quotation marks and the likeFor more robust integration 53 | with Git see the Integrating Vim with 54 | Git recipe.

      55 | 56 |

      To create a command that accepts a count you use the 57 | -count=default argument, then reference the count in 58 | command as <count>.

      59 | 60 |

      To create a command that accepts a range you use the 61 | -range=spec argument. If you don't supply a 62 | spec (i.e. -range), the range defaults to the current 63 | line. A spec of % means that the range defaults to the whole file. 64 | You can reference the range in the command with the placeholders 65 | <line1> and <line2> which denote the first 66 | and last line of the given range, respectively.

      67 | -------------------------------------------------------------------------------- /text/11_extending/04_extending_vim_with_scripts_and_plugins.html: -------------------------------------------------------------------------------- 1 |

      Extending Vim with Scripts and 2 | Plugins

      3 | 4 |

      Problem

      5 | 6 |

      You want to add functionality to Vim, preferably without having to write it 7 | yourself.

      8 | 9 |

      Solution

      10 | 11 |

      Browse Vim Scripts to find a 12 | script that meets your needs. Its 'type' should be utility or 13 | ftplugin. Download the latest version to your computer. If the plugin 14 | comes with its own installation instructions, use those; otherwise, read 15 | on.

      16 | 17 |

      If the file you've downloaded has a name ending with .vim you 18 | usually just need to save it in the right directory and then its ready to use. 19 | For scripts labelled utility, also known as global plugins, this 20 | directory is $VIMHOME/plugin; for those labeled ftplugin, also 21 | known as filetype plugins, the last component of this path is 22 | ftplugin instead. If this directory does not already exist you need to 23 | create it. The sidebar lists the locations of the plugin directories on 24 | various operating systems.

      25 | 26 |

      If the file is compressed (ending with .zip or .tar.gz), 27 | try uncompressing it in the parent directory of the applicable plugin 28 | directory. For example, on Linux this is ~/.vim/.

      29 | 30 |

      Now you should just be able to start Vim and have the plugin work.

      31 | 32 |
      33 | 34 |
      Plugin Directory Location
      35 | 36 | Note: For filetype plugins, the last portion of 37 | these paths is ftplugin; not plugin. 38 | 39 |
      40 |
      Unix
      41 |
      ~/.vim/plugin
      42 |
      PC and OS/2
      43 |
      $HOME/vimfiles/plugin or $VIM/vimfiles/plugin
      44 |
      Amiga
      45 |
      s:vimfiles/plugin
      46 |
      Macintosh
      47 |
      $VIM:vimfiles:plugin
      48 |
      Mac OS X
      49 |
      ~/.vim/plugin
      50 |
      RISC-OS
      51 |
      Choices:vimfiles.plugin
      52 |
      53 | 54 |
      55 | 56 |
      Plugin Types
      57 | 58 |

      Plugins can be either global or filetype-specific. Global plugins 59 | are loaded for every file you open; filetype-specific plugins are only loaded 60 | for certain filetypes.

      61 | 62 |

      Discussion

      63 | 64 |

      As complicated as the above instructions may sound, it's generally trivial 65 | to install a plugin. For example, on Linux to install the potwiki 67 | plugin:

      68 | 69 |
      70 | $ mkdir -p ~/.vim/plugin 
      71 | $ wget
      72 | http://www.vim.org/scripts/download_script.php?src_id=9316 -O
      73 | ~/.vim/plugin/potwiki.vim
      74 | 
      75 | 76 |

      (If your plugin directory already exists, the first command is 77 | superfluous.)

      78 | 79 |

      Vim 7 added support for a new plugin installation method called 80 | vimball. Vimballs make plugin installation and configuration easier, 81 | and are a slight improvement over the previous methods. They're not in wide 82 | use yet, but if you find a plugin distributed in this way (they have a 83 | *.vba extension), try following the steps below:

      84 | 85 |
        86 |
      1. Download the *.vba file.
      2. 87 |
      3. Open it with Vim, e.g. vim something.vba.
      4. 88 |
      5. Use :VimballList to verify its contents.
      6. 89 |
      7. Install it by sourcing: :source %.
      8. 90 |
      91 | -------------------------------------------------------------------------------- /text/11_extending/05_integrating_vim_with_git.html: -------------------------------------------------------------------------------- 1 |

      Integrating Vim with Git

      2 | 3 |

      Problem

      4 | 5 |

      You use the Git version control system with Vim and want shortcuts for 6 | common operations and syntax highlighting for git output.

      7 | 8 |

      Solution

      9 | 10 |

      Thanks to the work of Tim Pope and 11 | others, Vim ships with syntax highlighting support for Git output/templates. 12 | For example, after executing git commit -a, with Vim set as your 13 | default editor, you'll see 14 | 15 | Screenshot of Vim syntax highlighting for Git commit messages 17 | 18 |

      Vim can even help you write better commit messages. Git commit messages 19 | should typically have a 50-character or less summary as their first line, with 20 | a blank second line, then, optionally a long explanation, wrapped at about 72 21 | charactersFor an explanation 22 | of this convention see A Note About 23 | Git Commit Messages.. There's no need to remember this 24 | convention, however, because Vim warns you, visually, if you colour outside 25 | the lines. For example:

      26 | 27 | Screenshot of Vim syntax highlighting for badly formatted Git commit
29 |      messages 30 | 31 |

      In this example, the first line is too long, so the extraneous characters 32 | are coloured black. The second line should be blank, so it has a red 33 | background to indicate its contents are in error.

      34 | 35 |

      motemen's git-vim plugin extends 38 | this support by adding shortcuts and commands for common Git operations.

      39 | 40 |

      Install it by copying its files to your Vim directory. For example, on 41 | Linux:

      42 | 43 |
      mkdir -p ~/.vim
      44 | cd /tmp
      45 | git clone git://github.com/motemen/git-vim.git
      46 | cp -r git-vim/{plugin,syntax} ~/.vim/
      47 | cd -
      48 | 49 |

      You now have access to commands such as :GitCommit, which will, 50 | split your window horizontally, loading the Git commit template into the upper 51 | pane. Once you have written your commit message and quit the buffer, your file 52 | will be committed. (This assumes, of course, that the current file is located 53 | in a Git working directory).

      54 | 55 |
      56 |

      Bob Hiestand's vcscommand 58 | plugin offers similar functionality to git-vim, but it also 59 | supports CVS, SVN, and SVK. This makes it especially suitable 61 | for situations where one uses multiple version control systems.

      62 |
      63 | 64 |

      Discussion

      65 | 66 |

      Through a combination of editable history and particularly fast operation, 67 | Git invites regular commits. This is only feasible, however, if Git is tightly 68 | integrated into Vim, because otherwise version control will become a source of 69 | distraction that steals your focus and wastes your time.

      70 | 71 |

      Vim's ability to execute external 72 | commands already makes using git reasonably straightforward. 73 | For instance, :!git add % would add the current file, while :!git 74 | log would temporarily suspend Vim to show you the commit log.

      75 | 76 |

      The git-vim plugin expedites this process by providing Normal mode 77 | shortcuts. \gaThis example and those following 78 | assume that your Leader variable is set to the default of 79 | /; see :help leader for details. adds the current 80 | file, \gc commits it, etc.For a complete list of 81 | shortcuts offered by this plugin see its README.rdoc 82 | file.

      83 | 84 |

      git-vim takes this integration further for commands like 85 | :GitBlame where the window is split vertically to show the author's 86 | name alongside the lines he was responsible for.

      87 | 88 | Screenshot of Vim with the git-vim plugin showing Git 'blame' output
90 |      alongside the file. 91 | 92 |

      This presentation is clearly superior to the output of :!git blame 93 | %, shown below, in that it employs syntax highlighting, allows inline 94 | editing, and hides extraneous output.

      95 | 96 | Screenshot of the output of `git blame`. 98 | -------------------------------------------------------------------------------- /text/12_other-uses/00.html: -------------------------------------------------------------------------------- 1 |

      Other Uses of Vim

      2 | -------------------------------------------------------------------------------- /text/12_other-uses/01_browsing_directories.html: -------------------------------------------------------------------------------- 1 |

      Browsing Directories

      2 | 3 |

      Problem

      4 | 5 |

      You want to see the contents of a directory, perhaps so as to select a file 6 | to edit. For instance, if working on a project comprising multiple files you 7 | want to see a list of the files in a separate window.

      8 | 9 |

      Solution

      10 | 11 |

      Invoke Vim with a directory name as an argument, e.g. vim 12 | ~/projects/flying-pigs/. From within Vim use the :Ex 13 | (mnemonic: Explore) command. By default it shows the contents of the 14 | current file's directory, but you can provide a directory name if you wish. 15 | For example: :Ex ~/projects/flying-pigs. The directory is shown 16 | in a split screen if the current file has been modified.

      17 | 18 |

      To force a directory listing in a split pane, so you can view a file and 19 | its directory listing at once, use :SexNo, 20 | that's not a joke; the concept is synonymous with Vim. Similarly, 21 | :Vex to browse in a vertical split, and :Tex to 22 | browse in a new tab.

      23 | 24 |

      Discussion

      25 | 26 |

      By default Vim lists every file contained in a directory. To get a more 27 | ls-style listing you can specify a hiding list with :let 28 | g:netrw_listhide='\^\..*'. (This is a comma-separated list of regular 29 | expressions). When you're browsing a directory files starting with a period 30 | will now be hidden. By Unix/Linux convention filenames which 31 | begin with a period are designated hidden. By default file browsers and 32 | other utilities ignore these files unless explicitly commanded not 33 | to. If you hit a once you'll invert the hiding list 34 | (showing only hidden files). If you hit a again you'll remove the 35 | hiding list, showing everything.

      36 | 37 |

      To change how directory entries are sorted you can modify the 38 | g:netrw_sort_sequence variable. By default its value is, deep 39 | breath:

      40 | 41 |
      [\/]$,\.h$,\.c$,\.cpp$,*,\.o$,\.obj$,\.info$,\.swp$,\.bak$,\~$
      42 | 43 |

      The order of the patterns is the order of the sort. For instance, the first 44 | pattern matches directories, so they're shown first. The next pattern matches 45 | file names ending with *.h (C header files), so they're shown next. 46 | And so on. The * pattern matches everything not matched by the other 47 | patterns. You can change this pattern on-the-fly by hitting S while 48 | viewing a directory listing.

      49 | 50 |

      You can change into a directory by selecting it and hitting 51 | Enter. The same thing works for files. If you'd rather open a file 52 | in a new buffer use p. P will open the file in a split 53 | screen.

      54 | 55 |

      If you want to operate on the files you see read Using Vim as a File Manager.

      57 | -------------------------------------------------------------------------------- /text/12_other-uses/02_using_vim_as_a_file_manager.html: -------------------------------------------------------------------------------- 1 |

      Using Vim as a File Manager

      2 | 3 |

      Problem

      4 | 5 |

      You want to use Vim to manage your file system in a similar way to 6 | Nautilus, Midnight Commander, or Windows Explorer.

      7 | 8 |

      For example, you want to rename files matching a certain pattern. Or you 9 | want to compress the contents of a directory.

      10 | 11 |

      Solution

      12 | 13 |

      Browsing Directories explains the 14 | basics of working with directories in Vim, so read it first.

      15 | 16 |
      17 | 18 |
      Marking Files
      19 | 20 |

      To operate on files you must first mark them (this does not have 21 | any relation to the marks 22 | feature).

      23 | 24 |
        25 |
      • Mark the file under the cursor: mf (mnemonic: 26 | mark file).
      • 27 |
      • Unmark the marked file under the cursor: mf.
      • 28 |
      • Mark files matching a Vim regular expression: mr 29 | (mnemonic: mark with regular expression). You're then 30 | prompted for a pattern.
      • 31 |
      • Unmark all files: mu (mnemonic: marks 32 | undo).
      • 33 |
      • Visually mark files: 34 | <Shift>-v, then j and 35 | k to change the selection area.
      • 36 |
      37 | 38 |
      39 | 40 |

      You can operate on a single file or a group of them. In the latter case, 41 | you need to select files by marking them, as explained in the sidebar. You can 42 | now perform various operations on these files such as:

      43 | 44 |
        45 |
      • Deletion: hit D. You're prompted for each file you've 46 | selected. Answering a deletes them all without asking you any 47 | more.
      • 48 |
      • Renaming: hit R. For each file you're prompted for its 49 | new name.
      • 50 |
      • Copying/Moving: Hit mt (mnemonic: mark 51 | target) in the target directory. Change to the directory containing 52 | the source files, select them, then hit mc (mnemonic: marked 53 | copy) to copy or mm (mnemonic: marked 54 | move) to move.
      • 55 |
      • Diff: To diff up 56 | to three marked files, use md (mnemonic: marked 57 | diff).
      • 58 |
      • Printing: hit mp to print marked files (mnemonic: 59 | mark print).
      • 60 |
      • Execute shell command: hit mx (mnemonic: 61 | marked execute). (See the discussion for examples).
      • 62 |
      • Compress/Decompress: hit mz (mnemonic: marked 63 | gzip). (Other compression utilities can be used instead of 64 | gzip, but the Vim command remains the same).
      • 65 |
      • Open in horizontal split: hit o (mnemonic: 66 | open).
      • 67 |
      68 | 69 | 70 |

      Discussion

      71 | 72 |

      Vim can be used as a pretty well-featured file manager. In fact, given that 73 | it can be scripted, key mapped, and configured in concert with Vim, as well as 74 | seamlessly operate on remote directories, it is arguably better.

      75 | 76 |

      Perhaps the most interesting command is mx. This allows you to 77 | pass the list of marked files to an external command. You're prompted for a 78 | command line, in which you can use the % wildcard. Vim then loops 79 | through the selected files and calls the command for each one, substituting 80 | % for the filename.

      81 | 82 |

      For example, using a POSIX-compatible system, select three files 83 | (foo.txt, bar.txt, and glark) with mf. 84 | Hit mx and enter cat %>>foo-bar-glark. Vim will now 85 | execute:

      86 | 87 |
      cat foo.txt >>foo-bar-glark
       88 | cat bar.txt >>foo-bar-glark
       89 | cat glark >>foo-bar-glark
      90 | 91 |

      foo-bar-glark will now contain the contents of each file in turn.

      92 | 93 |

      The mz command also bears further discussion. It toggles the 94 | state of the selected files between compressed and decompressed.

      95 | 96 |

      If a file is uncompressed, Vim attempts to compress it. By default it uses 97 | gzip, but you can change this by modifying the 98 | g:netrw_compress variable. For example, to use Bzip2: :let 99 | g:netrw_compress=bzip2.

      100 | 101 |

      For decompression Vim uses an extension-to-program mapping:

      102 | 103 |
        104 |
      • .tar - tar -xf
      • 105 |
      • .gz - gunzip
      • 106 |
      • .bz2 - bunzip2
      • 107 |
      • .zip - unzip
      • 108 |
      109 | 110 |

      For example, if a filename ends with .zip Vim decompresses it by 111 | calling unzip zip-file. To add support for another format 112 | use :let g:netrw_decompress[ext] = prog.

      113 | -------------------------------------------------------------------------------- /text/12_other-uses/03_viewing_differences_between_files.html: -------------------------------------------------------------------------------- 1 |

      Viewing Differences Between Files

      2 | 3 |

      Problem

      4 | 5 |

      You have multiple versions of a file and want to see how they differ.

      6 | 7 |

      For example, if you're working on a document with somebody else, you want 8 | to see the differences between their version and yours.

      9 | 10 |

      Solution

      11 | 12 |

      Vim calls this feature diff, as per UNIX convention. You diff 13 | a file.

      14 | 15 |

      To diff from the command line invoke Vim as vimdiff, e.g. 16 | :vimdiff -o file1 file2. To diff from within Vim 17 | use :diffsplit file.

      18 | 19 |

      The screen is split horizontally, and each file is shown in its own window. 20 | The differences between them are highlighted. By default, a line that exists 21 | in one file but not in another are coloured blue; the line in the other buffer 22 | that should have held this line is coloured green, and is called a 23 | filler line. When a line exists in both buffers it is coloured purple. 24 | If characters inside the line differ they are highlighted in red. Identical 25 | lines have no highlighting. Identical runs of lines are folded.

      27 | 28 |

      To split the screen vertically use :vimdiff file1 29 | file2 or :vert diffsplit file1 30 | file2.

      31 | 32 |

      Discussion

      33 | 34 |

      Diffs are traditionally used in programming to compare an old and new 35 | version of source code to see what has changed. As suggested above, though, 36 | they're invaluable when collaborating on a file with somebody else. For 37 | example, you write a file named grant-proposal.txt, then e-mail it to 38 | somebody else for input. They make their changes and e-mail it back. You now 39 | have two files: grant-proposal.txt and 40 | grant-proposal.changes.txt. You use :vimdiff grant-proposal.txt 41 | grant-proposal.changes.txt to see your collaborator's suggestions.

      42 | 43 |

      It's important to note, though, that diff only works with plain text files. 44 | It won't work correctly if you use proprietary, binary formats such as 45 | Microsoft Word's .doc. As a general rule, if Vim can view a file it 46 | can diff it.

      47 | 48 |

      The windows diff feature splits your screen so each pane scrolls in 49 | concert with one other. This means that if you scroll to line 20 in the bottom 50 | pane, the top pane will automatically scroll to that point, too. This makes 51 | comparing long files easier, but you can disable it with :set 52 | noscrollbind.

      53 | 54 |

      You can jump between the changes with [c to go to the previous 55 | change, and ]c for the next.

      56 | -------------------------------------------------------------------------------- /text/99_post/99-foot.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /www/.htaccess: -------------------------------------------------------------------------------- 1 | AddDefaultCharset UTF-8 2 | Options +MultiViews 3 | AddEncoding x-gzip .gz 4 | DirectoryIndex index 5 | # See commit 1cf0c51fc339c8f755ec3afa234f2e88bfdafdc1 6 | RedirectPermanent /searching/searching-vim-documentation/ http://vim.runpaint.org/basics/help/ 7 | -------------------------------------------------------------------------------- /www/google18c41b892eabf75d.html: -------------------------------------------------------------------------------- 1 | google-site-verification: google18c41b892eabf75d.html -------------------------------------------------------------------------------- /www/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 7 | Vim Recipes - Free cookbook for the Vim text editor 8 | 9 | 10 |

      Vim Recipes

      11 |

      Vim Recipes is a free cookbook for Vim, 12 | the popular text editor. It’s available in:

      13 |
        14 |
      • PDF 17 | format (good for printing or downloading).
      • 18 |
      • HTML format (good for reading on-line).
      • 19 |
      • Bziped Tarball format (good for downloading on Linux/Mac).
      • 22 |
      • Zip format (good for downloading on Windows).
      • 25 |
      26 |
      27 |
      29 | 30 |   31 |   32 | 33 |
      34 |
      35 |

      You can subscribe to the Atom feed, or follow 36 | @vimrecipes on Twitter, to be notified of new recipes.

      38 |

      Please report any problems, typos, and suggestions via the issue tracker or 40 | e-mail to runrun@runpaint.org.

      42 |

      The latest source for the book is available from GitHub.

      44 | 49 | 55 | 56 | 57 | --------------------------------------------------------------------------------