Merge remote-tracking branch 'upstream/master' into colorcolcharcolorcolchar

1 files changed, 24 insertions, 41 deletions

diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt
index 4c184ddf94..0836ec54d8 100644
--- a/runtime/doc/if_pyth.txt
+++ b/runtime/doc/if_pyth.txt
@@ -17,26 +17,25 @@ Commands						*python-commands*
 :[range]py[thon] {stmt}
 			Execute Python statement {stmt}.  A simple check if
 			the `:python` command is working: >vim
-				:python print "Hello"
+				:python print("Hello")
 
-:[range]py[thon] << [endmarker]
+:[range]py[thon] << [trim] [{endmarker}]
 {script}
 {endmarker}
 			Execute Python script {script}.  Useful for including
 			python code in Vim scripts.  Requires Python, see
 			|script-here|.
 
-The {endmarker} below the {script} must NOT be preceded by any white space.
-
 If [endmarker] is omitted from after the "<<", a dot '.' must be used after
-{script}, like for the |:append| and |:insert| commands.
+{script}, like for the |:append| and |:insert| commands.  Refer to
+|:let-heredoc| for more information.
 
 Example: >vim
 	function! IcecreamInitialize()
 	python << EOF
 	class StrawberryIcecream:
 		def __call__(self):
-			print 'EAT ME'
+			print('EAT ME')
 	EOF
 	endfunction
 
@@ -101,11 +100,9 @@ To pass arguments you need to set sys.argv[] explicitly.  Example: >vim
 
 Here are some examples					*python-examples*
 >vim
-
 	:python from vim import *
-	:python from string import upper
-	:python current.line = upper(current.line)
-	:python print "Hello"
+	:python current.line = str.upper(current.line)
+	:python print("Hello")
 	:python str = current.buffer[42]
 
 Note that changes (such as the "import" statements) persist from one command
@@ -113,26 +110,16 @@ to the next, just like the Python REPL.
 
 							*script-here*
 When using a script language in-line, you might want to skip this when the
-language isn't supported.  Note that this mechanism doesn't work:
+language isn't supported.
 >vim
    if has('python')
      python << EOF
-       this will NOT work!
+       print("python works")
    EOF
    endif
-
-Instead, put the Python command in a function and call that function:
->vim
-    if has('python')
-      function DefPython()
-        python << EOF
-          this works
-    EOF
-      endfunction
-      call DefPython()
-    endif
-
-Note that "EOF" must be at the start of the line.
+<
+Note that "EOF" must be at the start of the line without preceding white
+space.
 
 ==============================================================================
 The vim module							*python-vim*
@@ -144,7 +131,7 @@ module before using it: >vim
 	:python import vim
 
 Overview >vim
-	:py print "Hello"		# displays a message
+	:py print("Hello")		# displays a message
 	:py vim.command(cmd)		# execute an Ex command
 	:py w = vim.windows[n]		# gets window "n"
 	:py cw = vim.current.window	# gets the current window
@@ -176,10 +163,6 @@ vim.command(str)					*python-command*
 		# Note the use of single quotes to delimit a string containing
 		# double quotes
 		normal('"a2dd"aP')
-<								*E659*
-	The ":python" command cannot be used recursively with Python 2.2 and
-	older.  This only works with Python 2.3 and later: >vim
-	    :py vim.command("python print 'Hello again Python'")
 
 vim.eval(str)						*python-eval*
 	Evaluates the expression str using the vim internal expression
@@ -191,8 +174,8 @@ vim.eval(str)						*python-eval*
 	Examples: >vim
 	    :py text_width = vim.eval("&tw")
 	    :py str = vim.eval("12+12")		# NB result is a string! Use
-						# string.atoi() to convert to
-						# a number.
+						# int() to convert to a
+						# number.
 
 vim.strwidth(str)					*python-strwidth*
 	Like |strwidth()|: returns number of display cells str occupies, tab
@@ -204,8 +187,8 @@ vim.foreach_rtp(callable)				*python-foreach_rtp*
 	are no longer paths. If stopped in case callable returned non-None,
 	vim.foreach_rtp function returns the value returned by callable.
 
-vim.chdir(*args, **kwargs)				*python-chdir*
-vim.fchdir(*args, **kwargs)				*python-fchdir*
+`vim.chdir(*args, **kwargs)`				*python-chdir*
+`vim.fchdir(*args, **kwargs)`				*python-fchdir*
 	Run os.chdir or os.fchdir, then all appropriate vim stuff.
 	Note: you should not use these functions directly, use os.chdir and
 	      os.fchdir instead. Behavior of vim.fchdir is undefined in case
@@ -468,7 +451,7 @@ A trailing '\n' is allowed and ignored, so that you can do: >vim
 Buffer object type is available using "Buffer" attribute of vim module.
 
 Examples (assume b is the current buffer) >vim
-	:py print b.name		# write the buffer file name
+	:py print(b.name)		# write the buffer file name
 	:py b[0] = "hello!!!"		# replace the top line
 	:py b[:] = None			# delete the whole buffer
 	:py del b[:]			# delete the whole buffer
@@ -592,17 +575,17 @@ Python 3						*python3*
 
 As Python 3 is the only supported version in Nvim, "python" is synonymous
 with "python3" in the current version. However, code that aims to support older
-versions of Neovim, as well as Vim, should prefer to use "python3"
-variants explicitly if Python 3 is required.
+versions of Nvim, as well as Vim, should prefer to use "python3" variants
+explicitly if Python 3 is required.
 
 							*:py3* *:python3*
 :[range]py3 {stmt}
-:[range]py3 << [endmarker]
+:[range]py3 << [trim] [{endmarker}]
 {script}
 {endmarker}
 
 :[range]python3 {stmt}
-:[range]python3 << [endmarker]
+:[range]python3 << [trim] [{endmarker}]
 {script}
 {endmarker}
 	The `:py3` and `:python3` commands work similar to `:python`.  A
@@ -629,7 +612,7 @@ You can test if Python is available with: >vim
 	if has('pythonx')
 	  echo 'there is Python'
 	endif
-  	if has('python3')
+	if has('python3')
 	  echo 'there is Python 3.x'
 	endif
 
@@ -652,7 +635,7 @@ To see what version of Python is being used: >vim
 	:pyx print(sys.version)
 <
 					*:pyxfile* *python_x-special-comments*
-`:pyxfile` works the same as `:py3file`. 
+`:pyxfile` works the same as `:py3file`.
 
 							*:pyxdo*
 `:pyxdo` works the same as `:py3do`.