From 4b7ef4a18d06d57510422f656650d6e67c68b5f6 Mon Sep 17 00:00:00 2001
From: Waldir Pimenta <waldyrious@gmail.com>
Date: Thu, 6 Oct 2016 11:19:06 +0100
Subject: [PATCH] vim: improve examples (#1105)

I tried to condense the most useful basic commands into this page without surpassing our length limit.
I also expanded the main description -- I wonder if there's a way to phrase it which could allow us to get rid of all the <Esc>s...

I combined copy/cut/paste into a single command, since it was important to allow space for a slightly more advanced command, (the find/replace example), which introduces some important vim concepts, such as command application ranges.
---
 pages/common/vim.md | 39 ++++++++++++++++++++-------------------
 1 file changed, 20 insertions(+), 19 deletions(-)

diff --git a/pages/common/vim.md b/pages/common/vim.md
index f4c6a63364..012caf7713 100644
--- a/pages/common/vim.md
+++ b/pages/common/vim.md
@@ -1,31 +1,32 @@
 # vim
 
-> Vi IMproved, a programmer's text editor.
+> Vi IMproved, a programmer's text editor, providing several modes for different kinds of text manipulation.
+> Pressing `i` enters edit mode; the normal mode (accessed via `<Esc>`) doesn't allow regular text editing.
 
-- Open a file with cursor at the given line number:
+- Open a file:
 
-`vim {{file}} +{{linenumber}}`
+`vim {{file}}`
 
-- Open multiple files at once, each file in its own tab page:
-
-`vim -p {{file1}} {{file2}} {{file3}}`
-
-- Open a file in read-only mode:
-
-`view {{file}}`
-
-- Enter normal text editing mode (insert mode):
+- Enter text editing mode (insert mode):
 
 `<Esc> i`
 
-- Search in file:
+- Copy ("yank") or cut ("delete") the current line (paste it with `P`):
 
-`/{{search_string}}<Enter>`
+`<Esc> {{yy|dd}}`
 
-- Save and Exit vim:
+- Undo the last operation:
+
+`<Esc> u`
+
+- Search for a pattern in the file (press `n` to go to the next result):
+
+`<Esc> /{{search_pattern}} <Enter>`
+
+- Perform a regex substitution in the whole file (from the start, `1`, to the end, `$`):
+
+`<Esc> :1,$s/{{pattern}}/{{replacement}}/g <Enter>`
+
+- Save (write) the file, and quit vim:
 
 `<Esc> :wq <Enter>`
-
-- Open interactive help:
-
-`<Esc> :help <Enter>`