Merge #9946 from justinmk/doc

6 files changed, 74 insertions, 59 deletions

diff --git a/MAINTAIN.md b/MAINTAIN.md
index 55f4e7afc2..e102d7a94b 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -44,14 +44,16 @@ Release Policy
 Release "often", but not "early".
 
 The (unreleased) `master` branch is the "early" channel; it should not be
-released if it's not stable. Medium-risk changes may be merged to `master` if
+released if it's not stable. High-risk changes may be merged to `master` if
 the next feature-release is not imminent.
 
-For maintenance releases, create a `release-x.y` branch. If the current stable
-release has a major bug:
+For maintenance releases, create a `release-x.y` branch. If the current release
+has a major bug:
 
 1. Fix the bug on `master`.
 2. Cherry-pick the fix to `release-x.y`.
-3. Cut a release from `release-x.y` (run `scripts/release.sh`).
+3. Cut a release from `release-x.y`.
+    - Run `./scripts/release.sh`
+    - Update (force-push) the remote `stable` tag.
 
 See also: https://github.com/neovim/neovim/issues/862
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,
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 3449cf68e5..cdcab817ad 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -139,7 +139,7 @@ def is_blank(text):
     return '' == clean_lines(text)
 
 
-def get_text(parent):
+def get_text(parent, preformatted=False):
     """Combine all text in a node."""
     if parent.nodeType == parent.TEXT_NODE:
         return parent.data
@@ -147,9 +147,9 @@ def get_text(parent):
     out = ''
     for node in parent.childNodes:
         if node.nodeType == node.TEXT_NODE:
-            out += clean_text(node.data)
+            out += node.data if preformatted else clean_text(node.data)
         elif node.nodeType == node.ELEMENT_NODE:
-            out += ' ' + get_text(node)
+            out += ' ' + get_text(node, preformatted)
     return out
 
 
@@ -271,6 +271,10 @@ def render_node(n, text, prefix='', indent='', width=62):
         text += doc_wrap(n.data, indent=indent, width=width)
     elif n.nodeName == 'computeroutput':
         text += ' `{}` '.format(get_text(n))
+    elif n.nodeName == 'preformatted':
+        o = get_text(n, preformatted=True)
+        ensure_nl = '' if o[-1] == '\n' else '\n'
+        text += ' >{}{}\n<'.format(ensure_nl, o)
     elif is_inline(n):
         for c in n.childNodes:
             text += render_node(c, text)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 390f1bbddb..9e59eca396 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1198,25 +1198,29 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
   rpc_unsubscribe(channel_id, e);
 }
 
-/// If the given name is an hexadecimal value (e.g. #XXXXXX)
-/// translates it to RGB. Otherwise, translates given name
-/// (e.g. “Pink”) to its RGB value. Returns -1 if it wasn’t
-/// able to find a correct RGB value for the given color name.
-///
-/// @param name Color name string
-/// @return A 24-bit RGB value of the given name or -1 if it wasn’t able
-///         to find a correct RGB value for the given color name.
+/// Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
+/// "#rrggbb" hexadecimal string.
+///
+/// Example:
+/// <pre>
+///     :echo nvim_get_color_by_name("Pink")
+///     :echo nvim_get_color_by_name("#cbcbcb")
+/// </pre>
+///
+/// @param name Color name or "#rrggbb" string
+/// @return 24-bit RGB value, or -1 for invalid argument.
 Integer nvim_get_color_by_name(String name)
   FUNC_API_SINCE(1)
 {
   return name_to_color((char_u *)name.data);
 }
 
-/// Returns a map (dictionary) with all colors from rgb.txt.
-/// Every key in the map is a color name (e.g. “Aqua”), and every
-/// value is a 24-bit RGB value (e.g. 65535).
+/// 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 associating names of colors and color RGB values.
+/// @return Map of color names and RGB values.
 Dictionary nvim_get_color_map(void)
   FUNC_API_SINCE(1)
 {