From afd947e0c3b34a0dc36140a373af46aa31d8f1ab Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 27 Apr 2019 17:53:56 +0200 Subject: doc [ci skip] ref #9886 --- runtime/doc/api.txt | 20 +++++++++++++++-- runtime/doc/eval.txt | 6 +++--- runtime/doc/various.txt | 57 +++++++++++++++++++------------------------------ src/nvim/api/vim.c | 28 +++++++++++++----------- 4 files changed, 59 insertions(+), 52 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index b2e37a6d60..44dc3a2011 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -763,10 +763,26 @@ 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/src/nvim/api/vim.c b/src/nvim/api/vim.c index 390f1bbddb..d5e4df829c 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. +/// +/// Examples: +/// 
+///     :echo nvim_get_color_by_name("Pink")
+///     :echo nvim_get_color_by_name("#cbcbcb")
+///
+/// +/// @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) { -- cgit From c11e6181330e9e27ec8af1712f505b38a00d8ca3 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 27 Apr 2019 18:25:55 +0200 Subject: gen_vimdoc.py: support 
 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:
 /// 
 ///     :echo nvim_get_color_by_name("Pink")
 ///     :echo nvim_get_color_by_name("#cbcbcb")
-- 
cgit