doc (#9288)

- misc
- doc: `:help config`. closes #9329
- cleanup test/README.md

2 files changed, 25 insertions, 28 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 0219488088..7dab69df22 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1138,7 +1138,7 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
                 which returns a namespace id. Pass it in to this function as
                 `ns_id` to add highlights to the namespace. All highlights in
                 the same namespace can then be cleared with single call to
-                |nvim_buf_clear_highlight|. If the highlight never will be
+                |nvim_buf_clear_namespace|. If the highlight never will be
                 deleted by an API call, pass `ns_id = -1`.
 
                 As a shorthand, `ns_id = 0` can be used to create a new
@@ -1162,20 +1162,21 @@ nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
                 Return: ~
                     The ns_id that was used
 
-                                                  *nvim_buf_clear_highlight()*
-nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end})
-                Clears highlights and virtual text from a given source id and
-                range of lines
+                                                  *nvim_buf_clear_namespace()*
+nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end})
+                Clears namespaced objects, highlights and virtual text, from a
+                line range
 
-                To clear a source group in the entire buffer, pass in 0 and -1
+                To clear the namespace in the entire buffer, pass in 0 and -1
                 to line_start and line_end respectively.
 
                 Parameters: ~
                     {buffer}      Buffer handle
-                    {ns_id}       Namespace to clear, or -1 to clear all.
+                    {ns_id}       Namespace to clear, or -1 to clear all
+                                  namespaces.
                     {line_start}  Start of range of lines to clear
                     {line_end}    End of range of lines to clear (exclusive)
-                                  or -1 to clear to end of file.
+                                  or -1 to clear to end of buffer.
 
                                                  *nvim_buf_set_virtual_text()*
 nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
@@ -1184,18 +1185,17 @@ nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
                 By default (and currently the only option) the text will be
                 placed after the buffer text. Virtual text will never cause
                 reflow, rather virtual text will be truncated at the end of
-                the screen line. The virtual text will begin after one cell to
-                the right of the ordinary text, this will contain the |lcs-
-                eol| char if set, otherwise just be a space.
+                the screen line. The virtual text will begin one cell (|lcs-
+                eol| or space) after the ordinary text.
 
                 Namespaces are used to support batch deletion/updating of
                 virtual text. To create a namespace, use
                 |nvim_create_namespace|. Virtual text is cleared using
-                |nvim_buf_clear_highlight|. The same `ns_id` can be used for
+                |nvim_buf_clear_namespace|. The same `ns_id` can be used for
                 both virtual text and highlights added by
                 |nvim_buf_add_highlight|, both can then be cleared with a
-                single call to |nvim_buf_clear_highlight|. If the virtual text
-                never will be cleared by an API call, pass `src_id = -1`.
+                single call to |nvim_buf_clear_namespace|. If the virtual text
+                never will be cleared by an API call, pass `ns_id = -1`.
 
                 As a shorthand, `ns_id = 0` can be used to create a new
                 namespace for the virtual text, the allocated id is then
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 1da2441929..450d2967b4 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -410,20 +410,17 @@ accordingly.  Vim proceeds in this order:
 
 3. Execute Ex commands, from environment variables and/or files
 	An environment variable is read as one Ex command line, where multiple
-	commands must be separated with '|' or "<NL>".
-						    *init.vim* *vimrc* *exrc*
-	A file that contains initialization commands is called a "vimrc" file.
-	Each line in a vimrc file is executed as an Ex command line.  It is
-	sometimes also referred to as "exrc" file.  They are the same type of
-	file, but "exrc" is what Vi always used, "vimrc" is a Vim specific
-	name, "init.vim" is Neovim specific location for vimrc file.  Also see 
-	|vimrc-intro|.
-
-	Places for your personal initializations (see |base-directories|):
-		Unix		$XDG_CONFIG_HOME/nvim/init.vim
-				(default for $XDG_CONFIG_HOME is ~/.config)
-		Windows		$XDG_CONFIG_HOME/nvim/init.vim
-				(default for $XDG_CONFIG_HOME is ~/AppData/Local)
+	commands must be separated with '|' or <NL>.
+					*config* *init.vim* *vimrc* *exrc*
+	A file that contains initialization commands is generically called
+	a "vimrc" or config file.  Each line in a vimrc file is executed as an
+	Ex command line.  See also |vimrc-intro| and |base-directories|.
+
+	The Nvim config file is named "init.vim", located at:
+		Unix		~/.config/nvim/init.vim
+		Windows		~/AppData/Local/nvim/init.vim
+	Or if |$XDG_CONFIG_HOME| is defined:
+				$XDG_CONFIG_HOME/nvim/init.vim
 
 	RECOMMENDATION: Put all your Vim configuration stuff in the 
 	$HOME/.config/nvim/ directory. That makes it easy to copy it to