doc

5 files changed, 49 insertions, 50 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index c8b9dd5fad..6b80b71335 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -206,17 +206,15 @@ Highlights are registered using the |nvim_buf_add_highlight()| function. If an
 external highlighter plugin wants to add many highlights in a batch,
 performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) reqesting a source id.
-Example using the Nvim python-client:
+
+Example using the Python API client (|pynvim|):
 >
     src = vim.new_highlight_source()
-
     buf = vim.current.buffer
     for i in range(5):
         buf.add_highlight("String",i,0,-1,src_id=src)
-
-    # some time later
-
-    buf.clear_highlight(src)
+    # some time later ...
+    buf.clear_namespace(src)
 <
 If the highlights don't need to be deleted or updated, just pass -1 as
 src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to
@@ -224,13 +222,12 @@ clear highlights from a specific source, in a specific line range or the
 entire buffer by passing in the line range 0, -1 (the latter is the default in
 python as used above).
 
-An example of calling the api from vimscript: >
+Example using the API from Vimscript: >
 
     call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
     let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
     call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)
-
-    " later
+    " some time later ...
     call nvim_buf_clear_namespace(0, src, 0, -1)
 
 
@@ -656,6 +653,7 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                 For a general overview of floats, see |api-floatwin|.
 
                 Exactly one of `external` and `relative` must be specified.
+                The `width` and `height` of the new window must be specified.
 
                 With editor positioning row=0, col=0 refers to the top-left
                 corner of the screen-grid and row=Lines-1, Columns-1 refers to
@@ -697,7 +695,7 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                               - `height` : window height (in character cells).
                                 Minimum of 1.
                               - `width` : window width (in character cells).
-                                Minimum of 2.
+                                Minimum of 1.
                               - `row` : row position. Screen cell height are
                                 used as unit. Can be floating point.
                               - `col` : column position. Screen cell width is
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 9e74efabe0..9272c0693e 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -12,6 +12,9 @@ updated.
 
 ==============================================================================
 
+API ~
+*nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+
 Commands ~
 *:rv*
 *:rviminfo*		Deprecated alias to |:rshada| command.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index d400df6b7d..9e2994ae2e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1502,7 +1502,8 @@ v:dying		Normally zero.	When a deadly signal is caught it's set to
 v:exiting	Exit code, or |v:null| if not exiting. |VimLeave|
 
 					*v:errmsg* *errmsg-variable*
-v:errmsg	Last given error message.  It's allowed to set this variable.
+v:errmsg	Last given error message.
+		Modifiable (can be set).
 		Example: >
 	:let v:errmsg = ""
 	:silent! next
@@ -1827,7 +1828,8 @@ v:shell_error	Result of the last shell command.  When non-zero, the last
 	:endif
 <
 					*v:statusmsg* *statusmsg-variable*
-v:statusmsg	Last given status message.  It's allowed to set this variable.
+v:statusmsg	Last given status message.
+		Modifiable (can be set).
 
 					*v:stderr* *stderr-variable*
 v:stderr	|channel-id| corresponding to stderr. The value is always 2;
@@ -1893,9 +1895,9 @@ v:termresponse	The escape sequence returned by the terminal for the DA
 v:testing	Must be set before using `test_garbagecollect_now()`.
 
 				*v:this_session* *this_session-variable*
-v:this_session	Full filename of the last loaded or saved session file.  See
-		|:mksession|.  It is allowed to set this variable.  When no
-		session file has been saved, this variable is empty.
+v:this_session	Full filename of the last loaded or saved session file.
+		Empty when no session file has been saved.  See |:mksession|.
+		Modifiable (can be set).
 
 					*v:throwpoint* *throwpoint-variable*
 v:throwpoint	The point where the exception most recently caught and not
@@ -1922,22 +1924,20 @@ v:val		Value of the current item of a |List| or |Dictionary|.	Only
 		|filter()|.  Read-only.
 
 					*v:version* *version-variable*
-v:version	Version number of Vim: Major version number times 100 plus
-		minor version number.  Version 5.0 is 500.  Version 5.1 (5.01)
-		is 501.  Read-only.  "version" also works, for backwards
-		compatibility.
-		Use |has()| to check if a certain patch was included, e.g.: >
-			if has("patch-7.4.123")
-<		Note that patch numbers are specific to the version, thus both
-		version 5.0 and 5.1 may have a patch 123, but these are
-		completely different.
+v:version	Vim version number: major version times 100 plus minor
+		version.  Vim 5.0 is 500, Vim 5.1 is 501.
+		Read-only.
+		Use |has()| to check the Nvim (not Vim) version: >
+			:if has("nvim-0.2.1")
+<
 
 				*v:vim_did_enter* *vim_did_enter-variable*
-v:vim_did_enter	Zero until most of startup is done.  It is set to one just
-		before |VimEnter| autocommands are triggered.
+v:vim_did_enter	0 during startup, 1 just before |VimEnter|.
+		Read-only.
 
 					*v:warningmsg* *warningmsg-variable*
-v:warningmsg	Last given warning message.  It's allowed to set this variable.
+v:warningmsg	Last given warning message.
+		Modifiable (can be set).
 
 					*v:windowid* *windowid-variable*
 v:windowid	Application-specific window "handle" which may be set by any
@@ -4674,8 +4674,8 @@ has({feature})	Returns 1 if {feature} is supported, 0 otherwise.  The
 		{feature} argument is a feature name like "nvim-0.2.1" or
 		"win32", see below.  See also |exists()|.
 
-		Vim's compile-time feature names (prefixed with "+") are not
-		supported because Nvim is always compiled with ALL possible
+		Vim's compile-time feature-names (prefixed with "+") are not
+		recognized because Nvim is always compiled with all possible
 		features. |feature-compile| 
 
 		Feature names can be:
@@ -4704,14 +4704,12 @@ has({feature})	Returns 1 if {feature} is supported, 0 otherwise.  The
 			wsl		WSL (Windows Subsystem for Linux) system
 
 							*has-patch*
-		3.  Vim patches.  The "patch123" feature means that Vim patch
-		    123 has been included.  This does not check the Vim
-		    version, you could check |v:version| for that.
-		    Example: >
+		3.  Vim patch. For example the "patch123" feature means that
+		    Vim patch 123 at the current |v:version| was included: >
 			:if v:version > 602 || v:version == 602 && has("patch148")
 
-<		5.  Vim version. For example the "patch-7.4.237" feature means
-		    that the Vim version is 7.4.237 or later. >
+<		4.  Vim version. For example the "patch-7.4.237" feature means
+		    that Nvim is Vim-compatible to version 7.4.237 or later. >
 			:if has("patch-7.4.237")
 
 
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 862aa7b750..91a4a3c267 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -114,17 +114,18 @@ You can also embed an Nvim instance via |jobstart()|, and communicate using
 ==============================================================================
 4. Implementing API clients			*rpc-api-client* *api-client*
 
-"API clients" wrap the Nvim API to provide idiomatic "SDKs" for their
-respective platforms (see |dev-jargon|). You can build a new API client for
-your favorite platform or programming language.
+API clients wrap the Nvim API to provide idiomatic "SDKs" for their respective
+platforms (see |jargon|). You can build a new API client for your favorite
+platform or programming language.
 
-Existing API clients are listed here:
+API clients are listed here:
     https://github.com/neovim/neovim/wiki/Related-projects#api-clients
 
+                                                                      *pynvim*
 The Python client is the reference implementation for API clients. It is
 always up-to-date with the Nvim API, so its source code and test suite are
 authoritative references.
-    https://github.com/neovim/python-client
+    https://github.com/neovim/pynvim
 
 API client implementation guidelines ~
 
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 98476ea8fa..3d14f83ae5 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -220,7 +220,7 @@ Grid Events (line-based)					  *ui-linegrid*
 
 These events are used if `ext_linegrid` option is set (recommended for all new
 UIs). The biggest change compared to previous revision is to use a single
-event `grid_line` to update the contents of a screen line (where the old
+`grid_line` event to update the contents of a screen line (where the old
 protocol used a combination of cursor, highlight and text events)
 
 Most of these events take a `grid` index as first parameter.  Grid 1 is the
@@ -465,10 +465,10 @@ Detailed highlight state Extension 				  *ui-hlstate*
 Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
 `ext_linegrid`.
 
-By default, nvim will only describe grid cells using the final calculated
-higlight attributes, as described by the dict keys in |ui-event-highlight_set|.
+By default Nvim will only describe grid cells using the final calculated
+highlight attributes, as described by the dict keys in |ui-event-highlight_set|.
 The `ext_hlstate` extension allows to the UI to also receive a semantic
-describtion of the higlights active in a cell. In this mode highlights will be
+description of the highlights active in a cell. In this mode highlights will be
 predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|.
 The `info` parameter in `hl_attr_define` will contain a semantic description
 of the highlights. As highlight groups can be combined, this will be an array
@@ -476,14 +476,13 @@ of items, with the item with highest priority last. Each item is a dictionary
 with the following possible keys:
 
     `kind`:	always present. One of the following values:
-	"ui":       A builtin ui highlight.
-	"syntax":   highlight applied to a buffer by a syntax declaration or
-	            other runtime/plugin functionallity such as
+	"ui":       Builtin UI highlight. |highlight-groups|
+	"syntax":   Highlight applied to a buffer by a syntax declaration or
+	            other runtime/plugin functionality such as
 		    |nvim_buf_add_highlight()|
 	"terminal": highlight from a process running in a |terminal-emulator|.
-		    Contains no futher semantic information.
-    `ui_name`:	Name of the builtin highlight. See |highlight-groups| for
-	        possible values. Only present for "ui".
+		    Contains no further semantic information.
+    `ui_name`:	Highlight name from |highlight-groups|. Only for "ui" kind.
     `hi_name`:	Name of the final |:highlight| group where the used
 		attributes are defined.
     `id`:	Unique numeric id representing this item.