gen_vimdoc.py: support <pre> preformatted text [ci skip]

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
+For maintenance releases, create a `release-x.y` branch. If the current release
-release has a major bug:
+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

runtime/doc/api.txt

@@ -766,8 +766,10 @@ nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
                 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
+                Examples: >
-                nvim_get_color_by_name("#cbcbcb")
+                    :echo nvim_get_color_by_name("Pink")
+                    :echo nvim_get_color_by_name("#cbcbcb")
+<
 
                 Parameters: ~
                     {name}  Color name or "#rrggbb" string

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)

src/nvim/api/vim.c

@@ -1201,7 +1201,7 @@ void nvim_unsubscribe(uint64_t channel_id, String event)
 /// Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
 /// "#rrggbb" hexadecimal string.
 ///
-/// Examples:
+/// Example:
 /// <pre>
 ///     :echo nvim_get_color_by_name("Pink")
 ///     :echo nvim_get_color_by_name("#cbcbcb")