updated for version 7.4.191

Problem:    Escaping a file name for shell commands can't be done without a
            function.
Solution:   Add the :S file name modifier.

runtime/doc/eval.txt

@@ -5428,6 +5428,7 @@ shellescape({string} [, {special}])			*shellescape()*
 <		This results in a directory listing for the file under the
 		cursor.  Example of use with |system()|: >
 		    :call system("chmod +w -- " . shellescape(expand("%")))
+<		See also |::S|.
 
 
 shiftwidth()						*shiftwidth()*
@@ -5910,14 +5911,16 @@ system({expr} [, {input}])				*system()* *E677*
 		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: 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.
+		Note: Use |shellescape()| or |::S| with |expand()| or 
+		|fnamemodify()| 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 " .  shellescape(expand('%:h')))
+		    :let files = system('ls ' . expand('%:h:S'))
 
 <		To make the result more system-independent, the shell output
 		is filtered to replace <CR> with <NL> for Macintosh, and

runtime/doc/options.txt

@@ -4757,8 +4757,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global or local to buffer |global-local|
 			{not in Vi}
 	Program to use for the ":make" command.  See |:make_makeprg|.
-	This option may contain '%' and '#' characters, which are expanded to
-	the current and alternate file name. |:_%| |:_#|
+	This option may contain '%' and '#' characters (see  |:_%| and |:_#|), 
+	which are expanded to the current and alternate file name.  Use |::S| 
+	to escape file names in case they contain special characters.
 	Environment variables are expanded |:set_env|.  See |option-backslash|
 	about including spaces and backslashes.
 	Note that a '|' must be escaped twice: once for ":set" and once for

runtime/doc/quickfix.txt

@@ -838,7 +838,7 @@ Unfortunately, there is no standard way to run the tests.
 The alltests.py script seems to be used quite often, that's all.
 Useful values for the 'makeprg' options therefore are:
  setlocal makeprg=./alltests.py " Run a testsuite
- setlocal makeprg=python %      " Run a single testcase
+ setlocal makeprg=python\ %:S   " Run a single testcase
 
 Also see http://vim.sourceforge.net/tip_view.php?tip_id=280.
 
@@ -1332,7 +1332,7 @@ or: >
 Here is an alternative from Michael F. Lamb for Unix that filters the errors
 first: >
   :setl errorformat=%Z%f:%l:\ %m,%A%p^,%-G%*[^sl]%.%#
-  :setl makeprg=javac\ %\ 2>&1\ \\\|\ vim-javac-filter
+  :setl makeprg=javac\ %:S\ 2>&1\ \\\|\ vim-javac-filter
 
 You need to put the following in "vim-javac-filter" somewhere in your path
 (e.g., in ~/bin) and make it executable: >

runtime/doc/usr_30.txt

@@ -128,7 +128,7 @@ be escaped with a backslash.  Example: >
 You can include special Vim keywords in the command specification.  The %
 character expands to the name of the current file.  So if you execute the
 command: >
-	:set makeprg=make\ %
+	:set makeprg=make\ %:S
 
 When you are editing main.c, then ":make" executes the following command: >
 
@@ -137,7 +137,7 @@ When you are editing main.c, then ":make" executes the following command: >
 This is not too useful, so you will refine the command a little and use the :r
 (root) modifier: >
 
-	:set makeprg=make\ %:r.o
+	:set makeprg=make\ %:r:S.o
 
 Now the command executed is as follows: >
 

runtime/doc/usr_40.txt

@@ -209,7 +209,7 @@ The ":map" command can be followed by another command.  A | character
 separates the two commands.  This also means that a | character can't be used
 inside a map command.  To include one, use <Bar> (five characters).  Example:
 >
-	:map <F8> :write <Bar> !checkin %<CR>
+	:map <F8> :write <Bar> !checkin %:S<CR>
 
 The same problem applies to the ":unmap" command, with the addition that you
 have to watch out for trailing white space.  These two commands are different:

runtime/doc/usr_42.txt

@@ -311,7 +311,7 @@ redefine what these items do (after the default menus are setup).
 item with a bitmap.  For example, define a new toolbar item with: >
 
 	:tmenu ToolBar.Compile  Compile the current file
-	:amenu ToolBar.Compile  :!cc % -o %:r<CR>
+	:amenu ToolBar.Compile  :!cc %:S -o %:r:S<CR>
 
 Now you need to create the icon.  For MS-Windows it must be in bitmap format,
 with the name "Compile.bmp".  For Unix XPM format is used, the file name is

runtime/doc/vi_diff.txt

@@ -540,7 +540,7 @@ character (and shows it immediately).
 Added :wnext command.  Same as ":write" followed by ":next".
 
 The ":w!" command always writes, also when the file is write protected.  In Vi
-you would have to do ":!chmod +w %" and ":set noro".
+you would have to do ":!chmod +w %:S" and ":set noro".
 
 When 'tildeop' has been set, "~" is an operator (must be followed by a
 movement command).