vim-patch:0c0734d527a1

Update runtime files
https://github.com/vim/vim/commit/0c0734d527a132edfb4089be48486586424b3f41

Omit rand(), srand() documentation.
Patch v8.1.2342 is not ported yet.

8 files changed, 115 insertions, 106 deletions

diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 7803d48700..3edd4864a1 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -944,7 +944,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 		    (mostly used in |Normal-mode| or |Cmdline-mode|).
 	esc	    hitting <Esc> in |Normal-mode|.
 	ex	    In |Visual-mode|, hitting |Q| results in an error.
-	hangul	    Error occurred when using hangul input.
+	hangul	    Ignored.
 	insertmode  Pressing <Esc> in 'insertmode'.
 	lang	    Calling the beep module for Lua/Mzscheme/TCL.
 	mess	    No output available for |g<|.
@@ -5288,12 +5288,11 @@ A jump table for the options with a short description can be found at |Q_op|.
 	of this option).
 	The default is ">".  For Unix, if the 'shell' option is "csh" or
 	"tcsh" during initializations, the default becomes ">&".  If the
-	'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh",
-	"zsh-beta","bash" or "fish", the default becomes ">%s 2>&1".  This
-	means that stderr is also included.  For Win32, the Unix checks are
-	done and additionally "cmd" is checked for, which makes the default
-	">%s 2>&1".  Also, the same names with ".exe" appended are checked
-	for.
+	'shell' option is "sh", "ksh", "mksh", "pdksh", "zsh", "zsh-beta",
+	"bash" or "fish", the default becomes ">%s 2>&1".  This means that
+	stderr is also included.  For Win32, the Unix checks are done and
+	additionally "cmd" is checked for, which makes the default ">%s 2>&1".
+	Also, the same names with ".exe" appended are checked for.
 	The initialization of this option is done after reading the vimrc
 	and the other initializations, so that when the 'shell' option is set
 	there, the 'shellredir' option changes automatically unless it was
@@ -5898,7 +5897,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	a S   Argument list status as in default title.  ({current} of {max})
 	      Empty if the argument file count is zero or one.
 	{ NF  Evaluate expression between '%{' and '}' and substitute result.
-	      Note that there is no '%' before the closing '}'.
+	      Note that there is no '%' before the closing '}'.  The
+	      expression cannot contain a '}' character, call a function to
+	      work around that.  See |stl-%{| below.
 	( -   Start of item group.  Can be used for setting the width and
 	      alignment of a section.  Must be followed by %) somewhere.
 	) -   End of item group.  No width fields allowed.
@@ -5961,13 +5962,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 		:set statusline=...%(\ [%M%R%H]%)...
 <	Beware that an expression is evaluated each and every time the status
 	line is displayed.
-					*g:actual_curbuf* *g:actual_curwin*
-	The current buffer and current window will be set temporarily to that
-	of the window (and buffer) whose statusline is currently being drawn.
-	The expression will evaluate in this context.  The variable
-	"g:actual_curbuf" is set to the `bufnr()` number of the real current
-	buffer and "g:actual_curwin" to the |window-ID| of the real current
-	window.  These values are strings.
+				*stl-%{* *g:actual_curbuf* *g:actual_curwin*
+	While evaluationg %{} the current buffer and current window will be
+	set temporarily to that of the window (and buffer) whose statusline is
+	currently being drawn.  The expression will evaluate in this context.
+	The variable "g:actual_curbuf" is set to the `bufnr()` number of the
+	real current buffer and "g:actual_curwin" to the |window-ID| of the
+	real current window.  These values are strings.
 
 	The 'statusline' option will be evaluated in the |sandbox| if set from
 	a modeline, see |sandbox-option|.
@@ -7050,6 +7051,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	fail (and make sure not to exit Vim until the write was successful).
 	See |backup-table| for another explanation.
 	When the 'backupskip' pattern matches, a backup is not made anyway.
+	Depending on 'backupcopy' the backup is a new file or the original
+	file renamed (and a new file is written).
 
 						*'writedelay'* *'wd'*
 'writedelay' 'wd'	number	(default 0)
diff --git a/runtime/doc/sign.txt b/runtime/doc/sign.txt
index 1f9de19fc7..563f14f4c8 100644
--- a/runtime/doc/sign.txt
+++ b/runtime/doc/sign.txt
@@ -366,7 +366,7 @@ sign_define({list})
 
 		The one argument {list} can be used to define a list of signs.
 		Each list item is a dictionary with the above items in {dict}
-		and a 'name' item for the sign name.
+		and a "name" item for the sign name.
 
 		Returns 0 on success and -1 on failure.  When the one argument
 		{list} is used, then returns a List of values one for each
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index 87a02af263..1e938fc8a0 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -2739,10 +2739,10 @@ To set a user-defined list of code block syntax highlighting: >
 To assign multiple code block types to a single syntax, define
 `rst_syntax_code_list` as a mapping: >
 	let rst_syntax_code_list = {
-		\ 'cpp' = ['cpp', 'c++'],
-                \ 'bash' = ['bash', 'sh'],
+		\ 'cpp': ['cpp', 'c++'],
+		\ 'bash': ['bash', 'sh'],
 		...
-	}
+	\ }
 
 To use color highlighting for emphasis text: >
 	let rst_use_emphasis_colors = 1
diff --git a/runtime/doc/usr_01.txt b/runtime/doc/usr_01.txt
index 3deaf181e5..52fbf06ec4 100644
--- a/runtime/doc/usr_01.txt
+++ b/runtime/doc/usr_01.txt
@@ -41,11 +41,11 @@ the commands and options used for it.  Use these two commands:
 	Press  CTRL-O  to jump back (repeat to go further back).
 
 Many links are in vertical bars, like this: |bars|.  The bars themselves may
-be hidden or invisible, see below.  An option name, like 'number', a command
+be hidden or invisible; see below.  An option name, like 'number', a command
 in double quotes like ":write" and any other word can also be used as a link.
 Try it out: Move the cursor to  CTRL-]  and press CTRL-] on it.
 
-Other subjects can be found with the ":help" command, see |help.txt|.
+Other subjects can be found with the ":help" command; see |help.txt|.
 
 The bars and stars are usually hidden with the |conceal| feature.  They also
 use |hl-Ignore|, using the same color for the text as the background.  You can
@@ -69,7 +69,7 @@ For more info see |vimrc|.
 *01.3*	Using the Vim tutor			         *tutor* *vimtutor*
 
 Instead of reading the text (boring!) you can use :Tutor to learn your first
-Vim commands.  This is a 30 minute tutorial that teaches the most basic Vim
+Vim commands.  This is a 30-minute tutorial that teaches the most basic Vim
 functionality hands-on.
 
 To start the tutorial, execute >
diff --git a/runtime/doc/usr_02.txt b/runtime/doc/usr_02.txt
index c8fd7c3e35..125a281943 100644
--- a/runtime/doc/usr_02.txt
+++ b/runtime/doc/usr_02.txt
@@ -253,11 +253,11 @@ restores the character.
 
 	g intelligent turtle ~
 
-The next u command restores the next-to-last character deleted:
+The next "u" command restores the next-to-last character deleted:
 
 	ng intelligent turtle ~
 
-The next u command gives you the u, and so on:
+The next "u" command gives you the u, and so on:
 
 	ung intelligent turtle ~
 	oung intelligent turtle ~
@@ -364,7 +364,7 @@ To exit, use the "ZZ" command.  This command writes the file and exits.
 	Unlike many other editors, Vim does not automatically make a backup
 	file.  If you type "ZZ", your changes are committed and there's no
 	turning back.  You can configure the Vim editor to produce backup
-	files, see |07.4|.
+	files; see |07.4|.
 
 
 DISCARDING CHANGES
@@ -387,7 +387,7 @@ message and refuse to exit:
 	E37: No write since last change (use ! to override) ~
 
 By specifying the override, you are in effect telling Vim, "I know that what
-I'm doing looks stupid, but I'm a big boy and really want to do this."
+I'm doing looks stupid, but I really want to do this."
 
 If you want to continue editing with Vim: The ":e!" command reloads the
 original version of the file.
@@ -540,7 +540,7 @@ Summary: 					*help-summary*  >
    command argument %: >
    	:help c_%
 
-8) Ex-commands always start with ":", so to go to the :s command help: >
+8) Ex-commands always start with ":", so to go to the ":s" command help: >
 	:help :s
 
 9) Commands specifically for debugging start with ">".  To go to the help
@@ -550,22 +550,23 @@ Summary: 					*help-summary*  >
 10) Key combinations.  They usually start with a single letter indicating
     the mode for which they can be used.  E.g.: >
    	:help i_CTRL-X
-<    takes you to the family of Ctrl-X commands for insert mode which can be
-    used to auto complete different things.  Note, that certain keys will
+<    takes you to the family of CTRL-X commands for insert mode which can be
+    used to auto-complete different things.  Note, that certain keys will
     always be written the same, e.g. Control will always be CTRL.
     For normal mode commands there is no prefix and the topic is available at
     :h CTRL-<Letter>. E.g.  >
    	:help CTRL-W
 <    In contrast >
 	:help c_CTRL-R
-<    will describe what the Ctrl-R does when entering commands in the Command
+<    will describe what the CTRL-R does when entering commands in the Command
     line and >
-   	:help v_Ctrl-A
+   	:help v_CTRL-A
 <    talks about incrementing numbers in visual mode and >
 	:help g_CTRL-A
-<    talks about the g<C-A> command (e.g. you have to press "g" then <Ctrl-A>).
-    Here the "g" stand for the normal command "g" which always expects a second
-    key before doing something similar to the commands starting with "z"
+<    talks about the "g<C-A>" command (e.g. you have to press "g" then
+    <CTRL-A>).  Here the "g" stand for the normal command "g" which always
+    expects a second key before doing something similar to the commands
+    starting with "z"
 
 11) Regexp items always start with /.  So to get help for the "\+" quantifier
     in Vim regexes: >
@@ -636,15 +637,16 @@ Summary: 					*help-summary*  >
 <    Also if you want to access a certain chapter in the help, the chapter
     number can be accessed directly like this: >
     	:help 10.1
-<    goes to chapter 10.1 in |usr_10.txt| and talks about recording macros.
+<    which goes to chapter 10.1 in |usr_10.txt| and talks about recording
+    macros.
 
 19) Highlighting groups.  Always start with hl-groupname.  E.g. >
     	:help hl-WarningMsg
 <    talks about the WarningMsg highlighting group.
 
-20) Syntax highlighting is namespaced to :syn-topic e.g. >
+20) Syntax highlighting is namespaced to :syn-topic.  E.g. >
 	:help :syn-conceal
-<    talks about the conceal argument for the :syn command.
+<    talks about the conceal argument for the ":syn" command.
 
 21) Quickfix commands usually start with :c while location list commands
     usually start with :l
@@ -677,7 +679,7 @@ Summary: 					*help-summary*  >
 <    takes you exactly to the description of the swap error message and >
 	:help W10
 <    talks about the warning "Changing a readonly file".
-    Sometimes however, those error codes are not described, but rather are
+    Sometimes, however, those error codes are not described, but rather are
     listed at the Vim command that usually causes this.  So: >
     	:help E128
 <    takes you to the |:function| command
diff --git a/runtime/doc/usr_03.txt b/runtime/doc/usr_03.txt
index 2649534900..c8d1e996ae 100644
--- a/runtime/doc/usr_03.txt
+++ b/runtime/doc/usr_03.txt
@@ -81,8 +81,8 @@ The "$" command moves the cursor to the end of a line.  If your keyboard has
 an <End> key it will do the same thing.
 
 The "^" command moves to the first non-blank character of the line.  The "0"
-command (zero) moves to the very first character of the line.  The <Home> key
-does the same thing.  In a picture:
+command (zero) moves to the very first character of the line, and the <Home>
+key does the same thing.  In a picture:
 
 		  ^
 	     <------------
@@ -222,7 +222,8 @@ you can see?  This figure shows the three commands you can use:
 		L -->	| text sample text	    |
 			+---------------------------+
 
-Hints: "H" stands for Home, "M" for Middle and "L" for Last.
+Hints: "H" stands for Home, "M" for Middle and "L" for Last.  Alternatively,
+"H" for high, "M" for Middle and "L" for low.
 
 ==============================================================================
 *03.6*	Telling where you are
@@ -299,22 +300,22 @@ To scroll one line at a time use CTRL-E (scroll up) and CTRL-Y (scroll down).
 Think of CTRL-E to give you one line Extra.  (If you use MS-Windows compatible
 key mappings CTRL-Y will redo a change instead of scroll.)
 
-To scroll forward by a whole screen (except for two lines) use CTRL-F.  The
-other way is backward, CTRL-B is the command to use.  Fortunately CTRL-F is
-Forward and CTRL-B is Backward, that's easy to remember.
+To scroll forward by a whole screen (except for two lines) use CTRL-F.  To
+scroll backwards, use CTRL-B.  These should be easy to remember: F for
+Forwards and B for Backwards.
 
 A common issue is that after moving down many lines with "j" your cursor is at
 the bottom of the screen.  You would like to see the context of the line with
 the cursor.  That's done with the "zz" command.
 
 	+------------------+		 +------------------+
-	| some text	   |		 | some text	    |
-	| some text	   |		 | some text	    |
-	| some text	   |		 | some text	    |
-	| some text	   |   zz  -->	 | line with cursor |
-	| some text	   |		 | some text	    |
-	| some text	   |		 | some text	    |
-	| line with cursor |		 | some text	    |
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |		 | earlier text	    |
+	| earlier text	   |   zz  -->	 | line with cursor |
+	| earlier text	   |		 | later text	    |
+	| earlier text	   |		 | later text	    |
+	| line with cursor |		 | later text	    |
 	+------------------+		 +------------------+
 
 The "zt" command puts the cursor line at the top, "zb" at the bottom.  There
@@ -354,7 +355,7 @@ The "?" command works like "/" but searches backwards: >
 
 The "N" command repeats the last search the opposite direction.  Thus using
 "N" after a "/" command searches backwards, using "N" after "?" searches
-forward.
+forwards.
 
 
 IGNORING CASE
@@ -458,8 +459,8 @@ essential ones:
 	:set nowrapscan
 
 This stops the search at the end of the file.  Or, when you are searching
-backwards, at the start of the file.  The 'wrapscan' option is on by default,
-thus searching wraps around the end of the file.
+backwards, it stops the search at the start of the file.  The 'wrapscan'
+option is on by default, thus searching wraps around the end of the file.
 >
 	:set noincsearch
 
@@ -481,7 +482,8 @@ Vim.  Example: >
 	Go:set hlsearch<Esc>
 
 "G" moves to the end of the file.  "o" starts a new line, where you type the
-":set" command.  You end insert mode with <Esc>.  Then write the file: >
+":set" command.  You end insert mode with <Esc>.  Then write and close the
+file: >
 
 	ZZ
 
@@ -495,8 +497,8 @@ Regular expressions are an extremely powerful and compact way to specify a
 search pattern.  Unfortunately, this power comes at a price, because regular
 expressions are a bit tricky to specify.
    In this section we mention only a few essential ones.  More about search
-patterns and commands in chapter 27 |usr_27.txt|.  You can find the full
-explanation here: |pattern|.
+patterns and commands can be found in chapter 27 |usr_27.txt|.  You can find
+the full explanation here: |pattern|.
 
 
 BEGINNING AND END OF A LINE
@@ -522,9 +524,9 @@ And with "/^the" we find this one:
 	the solder holding one of the chips melted and the ~
 	xxx
 
-You can try searching with "/^the$", it will only match a single line
-consisting of "the".  White space does matter here, thus if a line contains a
-space after the word, like "the ", the pattern will not match.
+You can try searching with "/^the$"; it will only match a single line
+consisting entirely of "the".  White space does matter here, thus if a line
+contains a space after the word, like "the ", the pattern will not match.
 
 
 MATCHING ANY SINGLE CHARACTER
@@ -559,20 +561,20 @@ where you came from, use this command: >
 
 This ` is a backtick or open single-quote character.
    If you use the same command a second time you will jump back again.  That's
-because the ` command is a jump itself, and the position from before this jump
-is remembered.
+because the "`" command is a jump itself, and the position from before this
+jump is remembered.
 
 Generally, every time you do a command that can move the cursor further than
 within the same line, this is called a jump.  This includes the search
 commands "/" and "n" (it doesn't matter how far away the match is).  But not
 the character searches with "fx" and "tx" or the word movements "w" and "e".
-   Also, "j" and "k" are not considered to be a jump.  Even when you use a
+   Also, "j" and "k" are not considered to be a jump, even when you use a
 count to make them move the cursor quite a long way away.
 
-The `` command jumps back and forth, between two points.  The CTRL-O command
+The "``" command jumps back and forth, between two points.  The CTRL-O command
 jumps to older positions (Hint: O for older).  CTRL-I then jumps back to newer
-positions (Hint: I is just next to O on the keyboard).  Consider this sequence
-of commands: >
+positions (Hint: for many common keyboard layouts, I is just next to O).
+Consider this sequence of commands: >
 
 	33G
 	/^The
@@ -610,9 +612,9 @@ Thus to move to the a mark:
 >
 	`a
 
-The command 'mark (single quotation mark, or apostrophe) moves you to the
-beginning of the line containing the mark.  This differs from the `mark
-command, which moves you to marked column.
+The command "'mark" (single quotation mark, or apostrophe) moves you to the
+beginning of the line containing the mark.  This differs from the "`mark"
+command, which also moves you to the marked column.
 
 The marks can be very useful when working on two related parts in a file.
 Suppose you have some text near the start of the file you need to look at,
diff --git a/runtime/doc/usr_04.txt b/runtime/doc/usr_04.txt
index a327a09a71..23270e3154 100644
--- a/runtime/doc/usr_04.txt
+++ b/runtime/doc/usr_04.txt
@@ -33,7 +33,7 @@ using a count: "4x" deletes four characters.
 move word command.  In fact, the "d" command may be followed by any motion
 command, and it deletes from the current location to the place where the
 cursor winds up.
-   The "4w" command, for example, moves the cursor over four words.  The d4w
+   The "4w" command, for example, moves the cursor over four words.  The "d4w"
 command deletes four words.
 
 	To err is human. To really foul up you need a computer. ~
@@ -91,14 +91,14 @@ This "c2wbe<Esc>" contains these bits:
 	be	insert this text
 	<Esc>	back to Normal mode
 
-If you have paid attention, you will have noticed something strange: The space
-before "human" isn't deleted.  There is a saying that for every problem there
-is an answer that is simple, clear, and wrong.  That is the case with the
-example used here for the "cw" command.  The c operator works just like the
-d operator, with one exception: "cw".  It actually works like "ce", change to
-end of word.  Thus the space after the word isn't included.  This is an
-exception that dates back to the old Vi.  Since many people are used to it
-now, the inconsistency has remained in Vim.
+You will have noticed something strange: The space before "human" isn't
+deleted.  There is a saying that for every problem there is an answer that is
+simple, clear, and wrong.  That is the case with the example used here for the
+"cw" command.  The c operator works just like the d operator, with one
+exception: "cw".  It actually works like "ce", change to end of word.  Thus
+the space after the word isn't included.  This is an exception that dates back
+to the old Vi.  Since many people are used to it now, the inconsistency has
+remained in Vim.
 
 
 MORE CHANGES
@@ -114,7 +114,7 @@ Insert mode and append new text.
 SHORTCUTS
 
 Some operator-motion commands are used so often that they have been given a
-single letter command:
+single-letter command:
 
 	x  stands for  dl  (delete character under the cursor)
 	X  stands for  dh  (delete character left of the cursor)
@@ -138,6 +138,7 @@ REPLACING WITH ONE CHARACTER
 The "r" command is not an operator.  It waits for you to type a character, and
 will replace the character under the cursor with it.  You could do the same
 with "cl" or with the "s" command, but with "r" you don't have to press <Esc>
+to get back out of insert mode.
 
 	there is somerhing grong here ~
 	rT	     rt    rw
@@ -164,7 +165,7 @@ The "." command is one of the most simple yet powerful commands in Vim.  It
 repeats the last change.  For instance, suppose you are editing an HTML file
 and want to delete all the <B> tags.  You position the cursor on the first <
 and delete the <B> with the command "df>".  You then go to the < of the next
-</B> and kill it using the "." command.  The "." command executes the last
+</B> and delete it using the "." command.  The "." command executes the last
 change command (in this case, "df>").  To delete another tag, position the
 cursor on the < and use the "." command.
 
@@ -176,8 +177,8 @@ cursor on the < and use the "." command.
 	f<   find next <		       ------------->
 	.    repeat df>					    -->
 
-The "." command works for all changes you make, except for the "u" (undo),
-CTRL-R (redo) and commands that start with a colon (:).
+The "." command works for all changes you make, except for "u" (undo), CTRL-R
+(redo) and commands that start with a colon (:).
 
 Another example: You want to change the word "four" to "five".  It appears
 several times in your text.  You can do this quickly with this sequence of
@@ -269,8 +270,8 @@ where they open a new line below or above the cursor.
 ==============================================================================
 *04.5*	Moving text
 
-When you delete something with the "d", "x", or another command, the text is
-saved.  You can paste it back by using the p command.  (The Vim name for
+When you delete something with "d", "x", or another command, the text is
+saved.  You can paste it back by using the "p" command.  (The Vim name for
 this is put).
    Take a look at how this works.  First you will delete an entire line, by
 putting the cursor on the line you want to delete and typing "dd".  Now you
@@ -362,11 +363,11 @@ Use "y$" to yank to the end of the line.
 
 If you are using the GUI version of Vim (gvim), you can find the "Copy" item
 in the "Edit" menu.  First select some text with Visual mode, then use the
-Edit/Copy menu.  The selected text is now copied to the clipboard.  You can
-paste the text in other programs.  In Vim itself too.
+Edit/Copy menu item.  The selected text is now copied to the clipboard.  You
+can paste the text in other programs.  In Vim itself too.
 
 If you have copied text to the clipboard in another application, you can paste
-it in Vim with the Edit/Paste menu.  This works in Normal mode and Insert
+it in Vim with the Edit/Paste menu item.  This works in Normal mode and Insert
 mode.  In Visual mode the selected text is replaced with the pasted text.
 
 The "Cut" menu item deletes the text before it's put on the clipboard.  The
@@ -385,7 +386,7 @@ To put text from the clipboard back into the text: >
 	"*p
 
 This only works on versions of Vim that include clipboard support.  More about
-the clipboard in section |09.3| and here: |clipboard|.
+the clipboard can be found in section |09.3| and here: |clipboard|.
 
 ==============================================================================
 *04.8*	Text objects
@@ -401,8 +402,8 @@ to do this: "daw".
 
 The "d" of "daw" is the delete operator.  "aw" is a text object.  Hint: "aw"
 stands for "A Word".  Thus "daw" is "Delete A Word".  To be precise, the white
-space after the word is also deleted (the white space before the word at the
-end of the line).
+space after the word is also deleted (or the white space before the word if at
+the end of the line).
 
 Using text objects is the third way to make changes in Vim.  We already had
 operator-motion and Visual mode.  Now we add operator-text object.
@@ -429,11 +430,11 @@ sentence "Another line.":
 	some text. ~
 
 "cis" consists of the "c" (change) operator and the "is" text object.  This
-stands for "Inner Sentence".  There is also the "as" (a sentence) object.  The
-difference is that "as" includes the white space after the sentence and "is"
-doesn't.  If you would delete a sentence, you want to delete the white space
-at the same time, thus use "das".  If you want to type new text the white
-space can remain, thus you use "cis".
+stands for "Inner Sentence".  There is also the "as" ("A Sentence") object.
+The difference is that "as" includes the white space after the sentence and
+"is" doesn't.  If you would delete a sentence, you want to delete the white
+space at the same time, thus use "das".  If you want to type new text the
+white space can remain, thus you use "cis".
 
 You can also use text objects in Visual mode.  It will include the text object
 in the Visual selection.  Visual mode continues, thus you can do this several
@@ -470,13 +471,13 @@ character.
 *04.10*	Conclusion
 
 The operators, movement commands and text objects give you the possibility to
-make lots of combinations.  Now that you know how it works, you can use N
+make lots of combinations.  Now that you know how they work, you can use N
 operators with M movement commands to make N * M commands!
 
-You can find a list of operators here: |operator|
+You can find a list of operators here: |operator|.
 
 For example, there are many other ways to delete pieces of text.  Here are a
-few often used ones:
+few common ones:
 
 x	delete character under the cursor (short for "dl")
 X	delete character before the cursor (short for "dh")
@@ -492,14 +493,14 @@ If you use "c" instead of "d" they become change commands.  And with "y" you
 yank the text.  And so forth.
 
 
-There are a few often used commands to make changes that didn't fit somewhere
+There are a few common commands to make changes that didn't fit somewhere
 else:
 
-	~	change case of the character under the cursor, and move the
+	~	Change case of the character under the cursor, and move the
 		cursor to the next character.  This is not an operator (unless
 		'tildeop' is set), thus you can't use it with a motion
-		command.  It does work in Visual mode and changes case for
-		all the selected text then.
+		command.  It does work in Visual mode, where it changes case
+		for all the selected text.
 
 	I	Start Insert mode after moving the cursor to the first
 		non-blank in the line.
diff --git a/runtime/doc/usr_10.txt b/runtime/doc/usr_10.txt
index 3646786052..c47fc1d886 100644
--- a/runtime/doc/usr_10.txt
+++ b/runtime/doc/usr_10.txt
@@ -370,7 +370,8 @@ into "barfoo".
 was specified in this example.  This is different from ":substitute", which
 works on one line without a range.
    The command isn't perfect, since it also matches lines where "//" appears
-halfway in a line, and the substitution will also take place before the "//".
+halfway through a line, and the substitution will also take place before the
+"//".
 
 Just like with ":substitute", any pattern can be used.  When you learn more
 complicated patterns later, you can use them here.
@@ -634,9 +635,9 @@ using it.  To check the current value of 'textwidth': >
 	:set textwidth
 
 Now lines will be broken to take only up to 78 characters.  However, when you
-insert text halfway through a line or delete a few words, the line will get
-too long or too short as Vim won't automatically reformat the text.  To tell
-Vim to format the current paragraph:
+insert text halfway through a line, or when you delete a few words, the lines
+will get too long or too short.  Vim doesn't automatically reformat the text.
+To tell Vim to format the current paragraph: >
 
 	gqap