From c11e6181330e9e27ec8af1712f505b38a00d8ca3 Mon Sep 17 00:00:00 2001
From: "Justin M. Keyes" <justinkz@gmail.com>
Date: Sat, 27 Apr 2019 18:25:55 +0200
Subject: [PATCH] gen_vimdoc.py: support <pre> preformatted text [ci skip]

---
 MAINTAIN.md           | 10 ++++++----
 runtime/doc/api.txt   |  6 ++++--
 scripts/gen_vimdoc.py | 10 +++++++---
 src/nvim/api/vim.c    |  2 +-
 4 files changed, 18 insertions(+), 10 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 44dc3a2011..fb4818bc2f 100644
--- a/runtime/doc/api.txt
+++ b/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
-                nvim_get_color_by_name("#cbcbcb")
+                Examples: >
+                    :echo nvim_get_color_by_name("Pink")
+                    :echo nvim_get_color_by_name("#cbcbcb")
+<
 
                 Parameters: ~
                     {name}  Color name or "#rrggbb" string
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 d5e4df829c..9e59eca396 100644
--- a/src/nvim/api/vim.c
+++ b/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")