--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1856,7 +1856,8 @@ setreg( {n}, {v}[, {opt}])	Number	set re
 settabwinvar( {tabnr}, {winnr}, {varname}, {val})    set {varname} in window
 					{winnr} in tab page {tabnr} to {val}
 setwinvar( {nr}, {varname}, {val})	set {varname} in window {nr} to {val}
-shellescape( {string})		String	escape {string} for use as shell
+shellescape( {string} [, {special}])
+				String	escape {string} for use as shell
 					command argument
 simplify( {filename})		String	simplify filename as much as possible
 sin( {expr})			Float	sine of {expr}
@@ -4018,10 +4019,10 @@ mkdir({name} [, {path} [, {prot}]])
 <
 							*mode()*
 mode([expr])	Return a string that indicates the current mode.
-		If [expr] is supplied and it evaluates to a non-zero number or
-		a non-empty string, then the full mode is returned, otherwise
-		only the first letter is returned.  Note that " " and "0" are
-		also non-empty strings.
+		If [expr] is supplied and it evaluates to a non-zero Number or
+		a non-empty String (|non-zero-arg|), then the full mode is
+		returned, otherwise only the first letter is returned.  Note
+		that " " and "0" are also non-empty strings.
 
 			n	Normal
 			no	Operator-pending
@@ -4941,19 +4942,23 @@ setwinvar({nr}, {varname}, {val})			*set
 			:call setwinvar(1, "&list", 0)
 			:call setwinvar(2, "myvar", "foobar")
 
-shellescape({string})					*shellescape()*
+shellescape({string} [, {special}])			*shellescape()*
 		Escape {string} for use as shell command argument.
 		On MS-Windows and MS-DOS, when 'shellslash' is not set, it
-		will enclose {string} double quotes and double all double
+		will enclose {string} in double quotes and double all double
 		quotes within {string}.
 		For other systems, it will enclose {string} in single quotes
 		and replace all "'" with "'\''".
-		Example: >
-			:echo shellescape('c:\program files\vim')
-<		results in:
-			"c:\program files\vim" ~
-		Example usage: >
-			:call system("chmod +x -- " . shellescape(expand("%")))
+		When the {special} argument is present and it's a non-zero
+		Number or a non-empty String (|non-zero-arg|), then special
+		items such as "%", "#" and "<cword>" will be preceded by a
+		backslash.  This backslash will be removed again by the |:!|
+		command.
+		Example of use with a |:!| command: >
+		    :exe '!dir ' . shellescape(expand('<cfile>'), 1)
+<		This results in a directory listing for the file under the
+		cursor.  Example of use with |system()|: >
+		    :call system("chmod +w -- " . shellescape(expand("%")))
 
 
 simplify({filename})					*simplify()*
@@ -5333,13 +5338,14 @@ system({expr} [, {input}])				*system()*
 		passed as stdin to the command.  The string is written as-is,
 		you need to take care of using the correct line separators
 		yourself.  Pipes are not used.
-		Note: newlines in {expr} may cause the command to fail.  The
-		characters in 'shellquote' and 'shellxquote' may also cause
-		trouble.
+		Note: Use |shellescape()| to escape special characters in a
+		command argument.  Newlines in {expr} may cause the command to
+		fail.  The characters in 'shellquote' and 'shellxquote' may
+		also cause trouble.
 		This is not to be used for interactive commands.
+
 		The result is a String.  Example: >
-
-			:let files = system("ls")
+		    :let files = system("ls " .  shellescape(expand('%:h')))
 
 <		To make the result more system-independent, the shell output
 		is filtered to replace <CR> with <NL> for Macintosh, and
@@ -5559,11 +5565,13 @@ visualmode([expr])						*visualmode()*
 		Visual mode that was used.
 		If Visual mode is active, use |mode()| to get the Visual mode
 		(e.g., in a |:vmap|).
-
-		If [expr] is supplied and it evaluates to a non-zero number or
-		a non-empty string, then the Visual mode will be cleared and
+							*non-zero-arg*
+		If [expr] is supplied and it evaluates to a non-zero Number or
+		a non-empty String, then the Visual mode will be cleared and
 		the old value is returned.  Note that " " and "0" are also
-		non-empty strings, thus cause the mode to be cleared.
+		non-empty strings, thus cause the mode to be cleared.  A List,
+		Dictionary or Float is not a Number or String, thus does not
+		cause the mode to be cleared.
 
 							*winbufnr()*
 winbufnr({nr})	The result is a Number, which is the number of the buffer
@@ -6738,8 +6746,10 @@ 7. Commands						*expression-commands*
 
 			Be careful to correctly escape special characters in
 			file names.  The |fnameescape()| function can be used
-			for this.  Example: >
+			for Vim commands, |shellescape()| for |:!| commands.
+			Examples: >
 		:execute "e " . fnameescape(filename)
+		:execute "!ls " . shellescape(expand('%:h'), 1)
 <
 			Note: The executed string may be any command-line, but
 			you cannot start or end a "while", "for" or "if"