Merge #9946 from justinmk/doc

3 files changed, 45 insertions, 40 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index b2e37a6d60..fb4818bc2f 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -763,10 +763,28 @@ nvim_unsubscribe({event})                                 *nvim_unsubscribe()*
                     {event}  Event type string
 
 nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
-                TODO: Documentation
+                Returns the 24-bit RGB value of a |nvim_get_color_map()| color
+                name or "#rrggbb" hexadecimal string.
+
+                Examples: >
+                    :echo nvim_get_color_by_name("Pink")
+                    :echo nvim_get_color_by_name("#cbcbcb")
+<
+
+                Parameters: ~
+                    {name}  Color name or "#rrggbb" string
+
+                Return: ~
+                    24-bit RGB value, or -1 for invalid argument.
 
 nvim_get_color_map()                                    *nvim_get_color_map()*
-                TODO: Documentation
+                Returns a map of color names and RGB values.
+
+                Keys are color names (e.g. "Aqua") and values are 24-bit RGB
+                color values (e.g. 65535).
+
+                Return: ~
+                    Map of color names and RGB values.
 
 nvim_get_mode()                                              *nvim_get_mode()*
                 Gets the current mode. |mode()| "blocking" is true if Nvim is
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index b05c806ec3..54f4f3d8c3 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -7823,7 +7823,7 @@ substitute({expr}, {pat}, {sub}, {flags})		*substitute()*
 		|submatch()| returns. Example: >
 		   :echo substitute(s, '\(\x\x\)', {m -> '0x' . m[1]}, 'g')
 
-swapinfo({fname})					swapinfo()
+swapinfo({fname})					*swapinfo()*
 		The result is a dictionary, which holds information about the
 		swapfile {fname}. The available fields are:
 			version VIM version
@@ -7970,7 +7970,7 @@ system({cmd} [, {input}])				*system()* *E677*
 		items converted to NULs).
 		When {input} is given and is a valid buffer id, the content of
 		the buffer is written to the file line by line, each line
-		terminated by a NL (and NUL where the text has NL).
+		terminated by NL (and NUL where the text has NL).
 								*E5677*
 		Note: system() cannot write to or read from backgrounded ("&")
 		shell commands, e.g.: >
@@ -7987,7 +7987,7 @@ system({cmd} [, {input}])				*system()* *E677*
 		The characters in 'shellquote' and 'shellxquote' may also
 		cause trouble.
 
-		The result is a String.  Example: >
+		Result is a String.  Example: >
 		    :let files = system("ls " .  shellescape(expand('%:h')))
 		    :let files = system('ls ' . expand('%:h:S'))
 
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 6f809af387..a0b2846b2b 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -235,35 +235,32 @@ g8			Print the hex values of the bytes used in the
 							*:!cmd* *:!* *E34*
 :!{cmd}			Execute {cmd} with 'shell'. See also |:terminal|.
 
-			Any '!' in {cmd} is replaced with the previous
-			external command (see also 'cpoptions').  But not when
-			there is a backslash before the '!', then that
-			backslash is removed.  Example: ":!ls" followed by
+			The command runs in a non-interactive shell connected
+			to a pipe (not a terminal). Use |:terminal| to run an
+			interactive shell connected to a terminal.
+
+			Backgrounded ("&") commands must not write to stdout
+			or stderr, the streams are closed immediately. |E5677|
+			Use |jobstart()| instead. >
+				:call jobstart('foo', {'detach':1})
+<
+			Any "!" in {cmd} is replaced with the previous
+			external command (see also 'cpoptions'), unless
+			escaped by a backslash.  Example: ":!ls" followed by
 			":!echo ! \! \\!" executes "echo ls ! \!".
 
-			A '|' in {cmd} is passed to the shell, you cannot use
-			it to append a Vim command.  See |:bar|.
+			Any "|" in {cmd} is passed to the shell, you cannot
+			use it to append a Vim command.  See |:bar|.
 
-			If {cmd} contains "%" it is expanded to the current
-			file name.  Special characters are not escaped, use
-			quotes to avoid their special meaning: >
+			Any "%" in {cmd} is expanded to the current file name.
+			Special characters are not escaped, use quotes or
+			|shellescape()|: >
 				:!ls "%"
-<			If the file name contains a "$" single quotes might
-			work better (but a single quote causes trouble): >
-				:!ls '%'
-<			This should always work, but it's more typing: >
 				:exe "!ls " . shellescape(expand("%"))
 <
-			A newline character ends {cmd}, what follows is
-			interpreted as a following ":" command.  However, if
-			there is a backslash before the newline it is removed
-			and {cmd} continues.  It doesn't matter how many
-			backslashes are before the newline, only one is
-			removed.
-
-			The command runs in a non-interactive shell connected
-			to a pipe (not a terminal). Use |:terminal| to run an
-			interactive shell connected to a terminal.
+			Newline character ends {cmd} unless a backslash
+			precedes the newline.  What follows is interpreted as
+			another |:| command.
 
 			After the command has been executed, the timestamp and
 			size of the current file is checked |timestamp|.
@@ -273,15 +270,9 @@ g8			Print the hex values of the bytes used in the
 			data is lost, this only affects the display.  The last
 			few lines are always displayed (never skipped).
 
-			Vim redraws the screen after the command is finished,
-			because it may have printed any text.  This requires a
-			hit-enter prompt, so that you can read any messages.
-			To avoid this use: >
+			To avoid the hit-enter prompt use: >
 				:silent !{cmd}
-<			The screen is not redrawn then, thus you have to use
-			CTRL-L or ":redraw!" if the command did display
-			something.
-
+<
 							*:!!*
 :!!			Repeat last ":!{cmd}".
 
@@ -289,10 +280,6 @@ g8			Print the hex values of the bytes used in the
 :ve[rsion]		Print editor version and build information.
 			See also |feature-compile|.
 
-:ve[rsion] {nr}		Ignored.  Previously used to check the version number
-			of a .vimrc file.  You can now use the ":if" command
-			for version-dependent behavior.
-
 							*:redi* *:redir*
 :redi[r][!] > {file}	Redirect messages to file {file}.  The messages which
 			are the output of commands are written to that file,