Merge #9172 from justinmk/vim-d473c8c10126

14 files changed, 219 insertions, 39 deletions

diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index bacd0e7cf1..75a26bf614 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -287,6 +287,7 @@ Name			triggered by ~
 |VimSuspend|		before Nvim is suspended
 
 	Various
+|DiffUpdated|		after diffs have been updated
 |DirChanged|		after the |current-directory| was changed
 
 |FileChangedShell|	Vim notices that a file changed since editing started
@@ -856,6 +857,9 @@ OptionSet			After setting an option.  The pattern is
 				plugin. You can always use `:noa` to prevent
 				triggering this autocommand.
 
+				When using |:set| in the autocommand the event
+				is not triggered again.
+
 							*QuickFixCmdPre*
 QuickFixCmdPre			Before a quickfix command is run (|:make|,
 				|:lmake|, |:grep|, |:lgrep|, |:grepadd|,
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index ec122d3a13..c73b460767 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -667,6 +667,7 @@ The flags that you can use for the substitute commands:
 	    CTRL-E  to scroll the screen up
 	    CTRL-Y  to scroll the screen down
 
+							*:s_e*
 [e]     When the search pattern fails, do not issue an error message and, in
 	particular, continue in maps as if no error occurred.  This is most
 	useful to prevent the "No match" error from breaking a mapping.  Vim
@@ -677,29 +678,34 @@ The flags that you can use for the substitute commands:
 		Trailing characters
 		Interrupted
 
+							*:s_g*
 [g]	Replace all occurrences in the line.  Without this argument,
 	replacement occurs only for the first occurrence in each line.  If the
 	'gdefault' option is on, this flag is on by default and the [g]
 	argument switches it off.
 
+							*:s_i*
 [i]	Ignore case for the pattern.  The 'ignorecase' and 'smartcase' options
 	are not used.
 
+							*:s_I*
 [I]	Don't ignore case for the pattern.  The 'ignorecase' and 'smartcase'
 	options are not used.
 
+							*:s_n*
 [n]	Report the number of matches, do not actually substitute.  The [c]
 	flag is ignored.  The matches are reported as if 'report' is zero.
 	Useful to |count-items|.
 	If \= |sub-replace-expression| is used, the expression will be
 	evaluated in the |sandbox| at every match.
 
-[p]	Print the line containing the last substitute.
+[p]	Print the line containing the last substitute.  *:s_p*
 
-[#]	Like [p] and prepend the line number.
+[#]	Like [p] and prepend the line number.  *:s_#*
 
-[l]	Like [p] but print the text like |:list|.
+[l]	Like [p] but print the text like |:list|.  *:s_l*
 
+							*:s_r*
 [r]	Only useful in combination with `:&` or `:s` without arguments.  `:&r`
 	works the same way as `:~`:  When the search pattern is empty, use the
 	previously used search pattern instead of the search pattern from the
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index d51940c69e..d4f8d170ef 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -495,8 +495,46 @@ after a command causes the rest of the line to be ignored.  This can be used
 to add comments.  Example: >
 	:set ai		"set 'autoindent' option
 It is not possible to add a comment to a shell command ":!cmd" or to the
-":map" command and a few others, because they see the '"' as part of their
-argument.  This is mentioned where the command is explained.
+":map" command and a few others (mainly commands that expect expressions)
+that see the '"' as part of their argument:
+
+    :argdo
+    :autocmd
+    :bufdo
+    :cexpr (and the like)
+    :call
+    :cdo (and the like)
+    :command
+    :cscope (and the like)
+    :debug
+    :display
+    :echo (and the like)
+    :elseif
+    :execute
+    :folddoopen
+    :folddoclosed
+    :for
+    :grep (and the like)
+    :help (and the like)
+    :if
+    :let
+    :make
+    :map (and the like including :abbrev commands)
+    :menu (and the like)
+    :mkspell
+    :normal
+    :ownsyntax
+    :popup
+    :promptfind (and the like)
+    :registers
+    :return
+    :sort
+    :syntax
+    :tabdo
+    :tearoff
+    :vimgrep (and the like)
+    :while
+    :windo
 
 							*:bar* *:\bar*
 '|' can be used to separate commands, so you can give multiple commands in one
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 20c0ce0876..f03189485c 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -921,6 +921,13 @@ These three can be repeated and mixed.	Examples:
 
 expr8							*expr8*
 -----
+This expression is either |expr9| or a sequence of the alternatives below,
+in any order.  E.g., these are all possible:
+	expr9[expr1].name
+	expr9.name[expr1]
+	expr9(expr1, ...)[expr1].name
+
+
 expr8[expr1]		item of String or |List|	*expr-[]* *E111*
 							*subscript*
 
@@ -2223,7 +2230,6 @@ remote_read({serverid} [, {timeout}])
 remote_send({server}, {string} [, {idvar}])
 				String	send key sequence
 remote_startserver({name})	none	become server {name}
-				String	send key sequence
 remove({list}, {idx} [, {end}])	any	remove items {idx}-{end} from {list}
 remove({dict}, {key})		any	remove entry {key} from {dict}
 rename({from}, {to})		Number	rename (move) file from {from} to {to}
@@ -2416,10 +2422,10 @@ and({expr}, {expr})					*and()*
 api_info()						*api_info()*
 		Returns Dictionary of |api-metadata|.
 
-append({lnum}, {expr})					*append()*
-		When {expr} is a |List|: Append each item of the |List| as a
+append({lnum}, {text})					*append()*
+		When {text} is a |List|: Append each item of the |List| as a
 		text line below line {lnum} in the current buffer.
-		Otherwise append {expr} as one text line below line {lnum} in
+		Otherwise append {text} as one text line below line {lnum} in
 		the current buffer.
 		{lnum} can be zero to insert a line before the first one.
 		Returns 1 for failure ({lnum} out of range or out of memory),
@@ -2489,7 +2495,7 @@ assert_exception({error} [, {msg}])			*assert_exception()*
 			  call assert_exception('E492:')
 			endtry
 
-assert_fails({cmd} [, {error}])					*assert_fails()*
+assert_fails({cmd} [, {error} [, {msg}]])			*assert_fails()*
 		Run {cmd} and add an error message to |v:errors| if it does
 		NOT produce an error.
 		When {error} is given it must match in |v:errmsg|.
@@ -4051,6 +4057,8 @@ getcmdline()						*getcmdline()*
 		Example: >
 			:cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR>
 <		Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|.
+		Returns an empty string when entering a password or using
+		|inputsecret()|.
 
 getcmdpos()						*getcmdpos()*
 		Return the position of the cursor in the command line as a
@@ -5445,11 +5453,14 @@ match({expr}, {pat} [, {start} [, {count}]])			*match()*
 		When {expr} is a |List| then this returns the index of the
 		first item where {pat} matches.  Each item is used as a
 		String, |Lists| and |Dictionaries| are used as echoed.
+
 		Otherwise, {expr} is used as a String.	The result is a
 		Number, which gives the index (byte offset) in {expr} where
 		{pat} matches.
+
 		A match at the first character or |List| item returns zero.
 		If there is no match -1 is returned.
+
 		For getting submatches see |matchlist()|.
 		Example: >
 			:echo match("testing", "ing")	" results in 4
@@ -7711,7 +7722,7 @@ synconcealed({lnum}, {col})				*synconcealed()*
 		   concealable region if there are two consecutive regions
 		   with the same replacement character.  For an example, if
 		   the text is "123456" and both "23" and "45" are concealed
-		   and replace by the character "X", then:
+		   and replaced by the character "X", then:
 			call			returns ~
 		   	synconcealed(lnum, 1)   [0, '', 0]
 		   	synconcealed(lnum, 2)   [1, 'X', 1]
diff --git a/runtime/doc/filetype.txt b/runtime/doc/filetype.txt
index 55e49efff0..92404440da 100644
--- a/runtime/doc/filetype.txt
+++ b/runtime/doc/filetype.txt
@@ -573,11 +573,31 @@ By default the following options are set, in accordance with PEP8: >
 
 	setlocal expandtab shiftwidth=4 softtabstop=4 tabstop=8
 
-To disable this behaviour, set the following variable in your vimrc: >
+To disable this behavior, set the following variable in your vimrc: >
 
 	let g:python_recommended_style = 0
 
 
+R MARKDOWN						*ft-rmd-plugin*
+
+By default ftplugin/html.vim is not sourced. If you want it sourced, add to
+your |vimrc|: >
+	let rmd_include_html = 1
+
+The 'formatexpr' option is set dynamically with different values for R code
+and for Markdown code. If you prefer that 'formatexpr' is not set, add to your
+|vimrc|: >
+	let rmd_dynamic_comments = 0
+
+
+R RESTRUCTURED TEXT					*ft-rrst-plugin*
+
+The 'formatexpr' option is set dynamically with different values for R code
+and for ReStructured text. If you prefer that 'formatexpr' is not set, add to
+your |vimrc|: >
+	let rrst_dynamic_comments = 0
+
+
 RPM SPEC						*ft-spec-plugin*
 
 Since the text for this plugin is rather long it has been put in a separate
diff --git a/runtime/doc/help.txt b/runtime/doc/help.txt
index 2ae2504b02..976402c915 100644
--- a/runtime/doc/help.txt
+++ b/runtime/doc/help.txt
@@ -182,4 +182,4 @@ will try to find help for it.  Especially for options in single quotes, e.g.
 'hlsearch'.
 
 ------------------------------------------------------------------------------
- vim:tw=78:fo=tcq2:isk=!-~,^*,^\|,^\":ts=8:noet:ft=help:norl:
+ vim:tw=78:isk=!-~,^*,^\|,^\":ts=8:noet:ft=help:norl:
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index dfa1d6e212..81a7816c93 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -42,9 +42,10 @@ Example: >
 	endfunction
 
 To see what version of Python you have: >
-	:python import sys
 	:python print(sys.version)
 
+There is no need to import sys, it's done by default.
+
 Note: Python is very sensitive to the indenting.  Make sure the "class" line
 and "EOF" do not have any indent.
 
@@ -63,6 +64,18 @@ Examples:
 	:pydo return "%s\t%d" % (line[::-1], len(line))
 	:pydo if line: return "%4d: %s" % (linenr, line)
 <
+One can use `:pydo` in possible conjunction with `:py` to filter a range using
+python. For example: >
+
+	:py3 << EOF
+	needle = vim.eval('@a')
+	replacement = vim.eval('@b')
+
+	def py_vim_string_replace(str):
+		return str.replace(needle, replacement)
+	EOF
+	:'<,'>py3do return py_vim_string_replace(line)
+<
 							*:pyfile* *:pyf*
 :[range]pyf[ile] {file}
 			Execute the Python script in {file}.  The whole
@@ -79,7 +92,6 @@ Python commands cannot be used in the |sandbox|.
 
 To pass arguments you need to set sys.argv[] explicitly.  Example: >
 
-	:python import sys
 	:python sys.argv = ["foo", "bar"]
 	:pyfile myscript.py
 
diff --git a/runtime/doc/indent.txt b/runtime/doc/indent.txt
index e95725920b..aae091aa99 100644
--- a/runtime/doc/indent.txt
+++ b/runtime/doc/indent.txt
@@ -937,6 +937,11 @@ Indent after a nested paren: >
 Indent for a continuation line: >
 	let g:pyindent_continue = '&sw * 2'
 
+The method uses searchpair() to look back for unclosed parenthesis.  This can
+sometimes be slow, thus it timeouts after 150 msec.  If you notice the
+indenting isn't correct, you can set a larger timeout in msec: >
+	let g:pyindent_searchpair_timeout = 500
+
 
 R								*ft-r-indent*
 
@@ -974,6 +979,11 @@ Below is an example of indentation with and without this option enabled:
        paste(x)                                      paste(x)
    }                                             }
 <
+The code will be indented after lines that match the pattern
+`'\(&\||\|+\|-\|\*\|/\|=\|\~\|%\|->\)\s*$'`. If you want indentation after
+lines that match a different pattern, you should set the appropriate value of
+`r_indent_op_pattern` in your |vimrc|.
+
 
 SHELL							*ft-sh-indent*
 
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index d42c5082c0..81eeae80ed 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1026,13 +1026,13 @@ The function must return the column where the completion starts.  It must be a
 number between zero and the cursor column "col('.')".  This involves looking
 at the characters just before the cursor and including those characters that
 could be part of the completed item.  The text between this column and the
-cursor column will be replaced with the matches.
+cursor column will be replaced with the matches.  If the returned value is
+larger than the cursor column, the cursor column is used.
 
-Special return values:
-   -1 If no completion can be done, the completion will be cancelled with an
-      error message.
-   -2 To cancel silently and stay in completion mode.
-   -3 To cancel silently and leave completion mode.
+Negative return values:
+   -2 	To cancel silently and stay in completion mode.
+   -3 	To cancel silently and leave completion mode.
+   Another negative value: completion starts at the cursor column
 
 On the second invocation the arguments are:
    a:findstart  0
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 0898dd98b9..30e7f644b3 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -371,8 +371,9 @@ several modes.  In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
 
 							*omap-info*
 Operator-pending mappings can be used to define a movement command that can be
-used with any operator.  Simple example: ":omap { w" makes "y{" work like "yw"
-and "d{" like "dw".
+used with any operator.  Simple example: >
+	:omap { w
+makes "y{" work like "yw" and "d{" like "dw".
 
 To ignore the starting cursor position and select different text, you can have
 the omap start Visual mode to select the text to be operated upon.  Example
@@ -383,9 +384,11 @@ Normal mode commands find the first '(' character and select the first word
 before it.  That usually is the function name.
 
 To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
-first define it for all three modes, then unmap it for Operator-pending mode:
+first define it for all three modes, then unmap it for
+Operator-pending mode: >
 	:map    xx something-difficult
 	:ounmap xx
+
 Likewise for a mapping for Visual and Operator-pending mode or Normal and
 Operator-pending mode.
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index 0076049b94..7cf3aa1d60 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -100,17 +100,17 @@ and the following arguments will be ignored.
 When 'verbose' is non-zero, displaying an option value will also tell where it
 was last set.  Example: >
 	:verbose set shiftwidth cindent?
-<	  shiftwidth=4 ~
-		  Last set from modeline ~
-	  cindent ~
-		  Last set from /usr/local/share/vim/vim60/ftplugin/c.vim ~
+<  shiftwidth=4 ~
+	  Last set from modeline line 1 ~
+  cindent ~
+	  Last set from /usr/local/share/vim/vim60/ftplugin/c.vim line 30 ~
 This is only done when specific option values are requested, not for ":verbose
 set all" or ":verbose set" without an argument.
 When the option was set by hand there is no "Last set" message.
 When the option was set while executing a function, user command or
 autocommand, the script in which it was defined is reported.
 A few special texts:
-	Last set from modeline ~
+	Last set from modeline line 1 ~
 		Option was set in a |modeline|.
 	Last set from --cmd argument ~
 		Option was set with command line argument |--cmd| or +.
@@ -691,6 +691,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	'{A-Z0-9}, or `{A-Z0-9} command takes one to another file.
 	Note that for some commands the 'autowrite' option is not used, see
 	'autowriteall' for that.
+	Some buffers will not be written, specifically when 'buftype' is
+	"nowrite", "nofile", "terminal" or "prompt".
 
 			 *'autowriteall'* *'awa'* *'noautowriteall'* *'noawa'*
 'autowriteall' 'awa'	boolean	(default off)
@@ -1456,8 +1458,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 	displayed.  E.g., when moving vertically it may change column.
 
 
-'conceallevel' 'cole'		*'conceallevel'* *'cole'*
-			number (default 0)
+						*'conceallevel'* *'cole'*
+'conceallevel' 'cole'	number (default 0)
 			local to window
 	Determine how text with the "conceal" syntax attribute |:syn-conceal|
 	is shown:
@@ -1902,6 +1904,15 @@ A jump table for the options with a short description can be found at |Q_op|.
 				When omitted a context of six lines is used.
 				See |fold-diff|.
 
+		iblank		Ignore changes where lines are all blank.  Adds
+				the "-B" flag to the "diff" command if
+				'diffexpr' is empty.  Check the documentation
+				of the "diff" command for what this does
+				exactly.
+				NOTE: the diff windows will get out of sync,
+				because no differences between blank lines are
+				taken into account.
+
 		icase		Ignore changes in case of text.  "a" and "A"
 				are considered the same.  Adds the "-i" flag
 				to the "diff" command if 'diffexpr' is empty.
@@ -1913,6 +1924,18 @@ A jump table for the options with a short description can be found at |Q_op|.
 				exactly.  It should ignore adding trailing
 				white space, but not leading white space.
 
+		iwhiteall	Ignore all white space changes.  Adds
+				the "-w" flag to the "diff" command if
+				'diffexpr' is empty.  Check the documentation
+				of the "diff" command for what this does
+				exactly.
+
+		iwhiteeol	Ignore white space changes at end of line.
+				Adds the "-Z" flag to the "diff" command if
+				'diffexpr' is empty.  Check the documentation
+				of the "diff" command for what this does
+				exactly.
+
 		horizontal	Start diff mode with horizontal splits (unless
 				explicitly specified otherwise).
 
@@ -3201,8 +3224,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	so far, matches.  The matched string is highlighted.  If the pattern
 	is invalid or not found, nothing is shown.  The screen will be updated
 	often, this is only useful on fast terminals.
-	Also applies to the `:s`, `:g` and `:v` commands.
-	Note that the match will be shown, but the cursor will return to its
+<	Note that the match will be shown, but the cursor will return to its
 	original position when no match is found and when pressing <Esc>.  You
 	still need to finish the search command with <Enter> to move the
 	cursor to the match.
@@ -3369,7 +3391,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	Identifiers are used in recognizing environment variables and after a
 	match of the 'define' option.  It is also used for "\i" in a
 	|pattern|.  See 'isfname' for a description of the format of this
-	option.
+	option.  For '@' only characters up to 255 are used.
 	Careful: If you change this option, it might break expanding
 	environment variables.  E.g., when '/' is included and Vim tries to
 	expand "$HOME/.local/share/nvim/shada/main.shada".  Maybe you should 
@@ -3381,8 +3403,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 			local to buffer
 	Keywords are used in searching and recognizing with many commands:
 	"w", "*", "[i", etc.  It is also used for "\k" in a |pattern|.  See
-	'isfname' for a description of the format of this option.  For C
-	programs you could use "a-z,A-Z,48-57,_,.,-,>".
+	'isfname' for a description of the format of this option.  For '@'
+	characters above 255 check the "word" character class.
+	For C programs you could use "a-z,A-Z,48-57,_,.,-,>".
 	For a help file it is set to all non-blank printable characters except
 	'*', '"' and '|' (so that CTRL-] on a command finds the help for that
 	command).
@@ -4397,13 +4420,13 @@ A jump table for the options with a short description can be found at |Q_op|.
 	security reasons.
 
 						*'printencoding'* *'penc'*
-'printencoding' 'penc'	String	(default empty, except for some systems)
+'printencoding' 'penc'	string	(default empty, except for some systems)
 			global
 	Sets the character encoding used when printing.
 	See |penc-option|.
 
 						*'printexpr'* *'pexpr'*
-'printexpr' 'pexpr'	String	(default: see below)
+'printexpr' 'pexpr'	string	(default: see below)
 			global
 	Expression used to print the PostScript produced with |:hardcopy|.
 	See |pexpr-option|.
diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt
index 654a9cde7b..7789d4bdbc 100644
--- a/runtime/doc/recover.txt
+++ b/runtime/doc/recover.txt
@@ -27,6 +27,9 @@ You can see the name of the current swap file being used with the command:
 
 	:sw[apname]					*:sw* *:swapname*
 
+Or you can use the |swapname()| function, which also allows for seeing the
+swap file name of other buffers.
+
 The name of the swap file is normally the same as the file you are editing,
 with the extension ".swp".
 - On Unix, a '.' is prepended to swap file names in the same directory as the
diff --git a/runtime/doc/syntax.txt b/runtime/doc/syntax.txt
index e96b109ceb..4c3c7d329a 100644
--- a/runtime/doc/syntax.txt
+++ b/runtime/doc/syntax.txt
@@ -1243,7 +1243,7 @@ doxygen_javadoc_autobrief	1	Set to 0 to disable javadoc autobrief
 doxygen_end_punctuation		'[.]'	Set to regexp match for the ending
 					punctuation of brief
 
-There are also some hilight groups worth mentioning as they can be useful in
+There are also some highlight groups worth mentioning as they can be useful in
 configuration.
 
 Highlight			Effect ~
@@ -2610,6 +2610,48 @@ Any combination of these three variables is legal, but might highlight more
 commands than are actually available to you by the game.
 
 
+R							*r.vim* *ft-r-syntax*
+
+The parsing of R code for syntax highlight starts 40 lines backwards, but you
+can set a different value in your |vimrc|. Example: >
+	let r_syntax_minlines = 60
+
+You can also turn off syntax highlighting of ROxygen: >
+	let r_syntax_hl_roxygen = 0
+
+enable folding of code delimited by parentheses, square brackets and curly
+braces: >
+	let r_syntax_folding = 1
+
+and highlight as functions all keywords followed by an opening parenthesis: >
+	let r_syntax_fun_pattern = 1
+
+
+R MARKDOWN					*rmd.vim* *ft-rmd-syntax*
+
+To disable syntax highlight of YAML header, add to your |vimrc|: >
+	let rmd_syn_hl_yaml = 0
+
+To disable syntax highlighting of citation keys: >
+	let rmd_syn_hl_citations = 0
+
+To highlight R code in knitr chunk headers: >
+	let rmd_syn_hl_chunk = 1
+
+By default, chunks of R code will be highlighted following the rules of R
+language. If you want proper syntax highlighting of chunks of other languages,
+you should add them to either `markdown_fenced_languages` or
+`rmd_fenced_languages`. For example to properly highlight both R and Python,
+you may add this to your |vimrc|: >
+	let rmd_fenced_languages = ['r', 'python']
+
+
+R RESTRUCTURED TEXT				*rrst.vim* *ft-rrst-syntax*
+
+To highlight R code in knitr chunk headers, add to your |vimrc|: >
+	let rrst_syn_hl_chunk = 1
+
+
 READLINE				*readline.vim* *ft-readline-syntax*
 
 The readline library is primarily used by the BASH shell, which adds quite a
@@ -3138,6 +3180,12 @@ by syntax/tex.vim.  Please consider uploading any extensions that you write,
 which typically would go in $HOME/after/syntax/tex/[pkgname].vim, to
 http://vim.sf.net/.
 
+I've included some support for various popular packages on my website: >
+
+	http://www.drchip.org/astronaut/vim/index.html#LATEXPKGS
+<
+The syntax files there go into your .../after/syntax/tex/ directory.
+
 					*tex-error* *g:tex_no_error*
  Tex: Excessive Error Highlighting? ~
 
diff --git a/runtime/doc/usr_11.txt b/runtime/doc/usr_11.txt
index ad3c0de541..e5591ac1d1 100644
--- a/runtime/doc/usr_11.txt
+++ b/runtime/doc/usr_11.txt
@@ -283,6 +283,8 @@ machines.  Therefore, don't rely on Vim always warning you.
 If you really don't want to see this message, you can add the 'A' flag to the
 'shortmess' option.  But it's very unusual that you need this.
 
+For programatic access to the swap file, see |swapinfo()|.
+
 ==============================================================================
 *11.4*	Further reading