doc

- develop.txt is for design/guidelines; architecture/concepts should
  live elsewhere (currently src/nvim/README.md)
- move dev-jargon to intro.txt
- replace https://neovim.io/community (deprecated) with
  https://neovim.io/#chat
- <Cmd> avoids CmdlineEnter/Leave
  https://github.com/vim/vim/issues/2889

.travis.yml

@@ -52,9 +52,9 @@ jobs:
     - stage: normal builds
       os: linux
       compiler: clang-4.0
+      # Use Lua so that ASAN can test our embedded Lua support. 8fec4d53d0f6
       env: >
         CLANG_SANITIZER=ASAN_UBSAN
-        # Use Lua so that ASAN can test our embedded Lua support. 8fec4d53d0f6
         CMAKE_FLAGS="$CMAKE_FLAGS -DPREFER_LUA=ON"
         ASAN_SYMBOLIZE=asan_symbolize-4.0
     - os: linux

man/nvim.1

@@ -24,7 +24,7 @@ Start
 .Nm
 followed by any number of options and/or files:
 .Pp
-.Dl nvim [options] [filelist]
+.Dl nvim [options] [file ...]
 .Pp
 Commands in
 .Nm

runtime/doc/api.txt

@@ -478,6 +478,9 @@ nvim_err_writeln({str})                                   *nvim_err_writeln()*
 nvim_list_bufs()                                            *nvim_list_bufs()*
                 Gets the current list of buffer handles
 
+                Includes unlisted (unloaded/deleted) buffers, like `:ls!`. Use
+                |nvim_buf_is_loaded()| to check if a buffer is loaded.
+
                 Return: ~
                     List of buffer handles
 
@@ -529,6 +532,30 @@ nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
                 Parameters: ~
                     {tabpage}  Tabpage handle
 
+nvim_create_namespace({name})                        *nvim_create_namespace()*
+                create a new namespace, or get one with an exisiting name
+
+                Namespaces are currently used for buffer highlighting and
+                virtual text, see |nvim_buf_add_highlight| and
+                |nvim_buf_set_virtual_text|.
+
+                Namespaces can have a name of be anonymous. If `name` is a
+                non-empty string, and a namespace already exists with that
+                name,the existing namespace id is returned. If an empty string
+                is used, a new anonymous namespace is returned.
+
+                Parameters: ~
+                    {name}  Name of the namespace or empty string
+
+                Return: ~
+                    the namespace id
+
+nvim_get_namespaces()                                  *nvim_get_namespaces()*
+                Get existing named namespaces
+
+                Return: ~
+                    dict that maps from names to namespace ids.
+
 nvim_subscribe({event})                                     *nvim_subscribe()*
                 Subscribes to event broadcasts
 
@@ -1082,35 +1109,36 @@ nvim_buf_get_mark({buffer}, {name})                      *nvim_buf_get_mark()*
                     (row, col) tuple
 
                                                     *nvim_buf_add_highlight()*
-nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
+nvim_buf_add_highlight({buffer}, {ns_id}, {hl_group}, {line},
                        {col_start}, {col_end})
                 Adds a highlight to buffer.
 
                 Useful for plugins that dynamically generate highlights to a
                 buffer (like a semantic highlighter or linter). The function
-                adds a single highlight to a buffer. Unlike matchaddpos()
+                adds a single highlight to a buffer. Unlike |matchaddpos()|
                 highlights follow changes to line numbering (as lines are
                 inserted/removed above the highlighted line), like signs and
                 marks do.
 
-                `src_id` is useful for batch deletion/updating of a set of
+                Namespaces are used for batch deletion/updating of a set of
-                highlights. When called with `src_id = 0`, an unique source id
+                highlights. To create a namespace, use |nvim_create_namespace|
-                is generated and returned. Successive calls can pass that
+                which returns a namespace id. Pass it in to this function as
-                `src_id` to associate new highlights with the same source
+                `ns_id` to add highlights to the namespace. All highlights in
-                group. All highlights in the same group can be cleared with
+                the same namespace can then be cleared with single call to
-                `nvim_buf_clear_highlight`. If the highlight never will be
+                |nvim_buf_clear_highlight|. If the highlight never will be
-                manually deleted, pass `src_id = -1`.
+                deleted by an API call, pass `ns_id = -1`.
 
-                If `hl_group` is the empty string no highlight is added, but a
+                As a shorthand, `ns_id = 0` can be used to create a new
-                new `src_id` is still returned. This is useful for an external
+                namespace for the highlight, the allocated id is then
-                plugin to synchrounously request an unique `src_id` at
+                returned. If `hl_group` is the empty string no highlight is
-                initialization, and later asynchronously add and clear
+                added, but a new `ns_id` is still returned. This is supported
-                highlights in response to buffer changes.
+                for backwards compatibility, new code should use
+                |nvim_create_namespace| to create a new empty namespace.
 
                 Parameters: ~
                     {buffer}     Buffer handle
-                    {src_id}     Source group to use or 0 to use a new group,
+                    {ns_id}      namespace to use or -1 for ungrouped
-                                 or -1 for ungrouped highlight
+                                 highlight
                     {hl_group}   Name of the highlight group to use
                     {line}       Line to highlight (zero-indexed)
                     {col_start}  Start of (byte-indexed) column range to
@@ -1119,10 +1147,10 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
                                  highlight, or -1 to highlight to end of line
 
                 Return: ~
-                    The src_id that was used
+                    The ns_id that was used
 
                                                   *nvim_buf_clear_highlight()*
-nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
+nvim_buf_clear_highlight({buffer}, {ns_id}, {line_start}, {line_end})
                 Clears highlights and virtual text from a given source id and
                 range of lines
 
@@ -1131,15 +1159,13 @@ nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
 
                 Parameters: ~
                     {buffer}      Buffer handle
-                    {src_id}      Highlight source group to clear, or -1 to
+                    {ns_id}       Namespace to clear, or -1 to clear all.
-                                  clear all.
                     {line_start}  Start of range of lines to clear
                     {line_end}    End of range of lines to clear (exclusive)
                                   or -1 to clear to end of file.
 
                                                  *nvim_buf_set_virtual_text()*
-nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
+nvim_buf_set_virtual_text({buffer}, {ns_id}, {line}, {chunks}, {opts})
-                          {opts})
                 Set the virtual text (annotation) for a buffer line.
 
                 By default (and currently the only option) the text will be
@@ -1149,13 +1175,22 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
                 the right of the ordinary text, this will contain the |lcs-
                 eol| char if set, otherwise just be a space.
 
-                The same src_id can be used for both virtual text and
+                Namespaces are used to support batch deletion/updating of
-                highlights added by nvim_buf_add_highlight. Virtual text is
+                virtual text. To create a namespace, use
-                cleared using nvim_buf_clear_highlight.
+                |nvim_create_namespace|. Virtual text is cleared using
+                |nvim_buf_clear_highlight|. The same `ns_id` can be used for
+                both virtual text and highlights added by
+                |nvim_buf_add_highlight|, both can then be cleared with a
+                single call to |nvim_buf_clear_highlight|. If the virtual text
+                never will be cleared by an API call, pass `src_id = -1`.
+
+                As a shorthand, `ns_id = 0` can be used to create a new
+                namespace for the virtual text, the allocated id is then
+                returned.
 
                 Parameters: ~
                     {buffer}  Buffer handle
-                    {src_id}  Source group to use or 0 to use a new group, or
+                    {ns_id}   Namespace to use or 0 to create a namespace, or
                               -1 for a ungrouped annotation
                     {line}    Line to annotate with virtual text (zero-
                               indexed)
@@ -1166,7 +1201,7 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
                     {opts}    Optional parameters. Currently not used.
 
                 Return: ~
-                    The src_id that was used
+                    The ns_id that was used
 
 
 ==============================================================================
@@ -1181,6 +1216,13 @@ nvim_win_get_buf({window})                                *nvim_win_get_buf()*
                 Return: ~
                     Buffer handle
 
+nvim_win_set_buf({window}, {buffer})                      *nvim_win_set_buf()*
+                Sets the current buffer in a window, without side-effects
+
+                Parameters: ~
+                    {window}  Window handle
+                    {buffer}  Buffer handle
+
 nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
                 Gets the cursor position in the window
 

runtime/doc/autocmd.txt

@@ -526,20 +526,18 @@ CmdlineChanged			After a change was made to the text in the
 				command line.  Be careful not to mess up
 				the command line, it may cause Vim to lock up.
 							*CmdlineEnter*
-CmdlineEnter			After moving the cursor to the command line,
+CmdlineEnter			After entering the command-line (including
-				where the user can type a command or search
+				non-interactive use of ":" in a mapping: use
-				string.
+				|<Cmd>| instead to avoid this).
-				<afile> is set to a single character,
+				<afile> is set to the |cmdline-char|.
-				indicating the type of command-line.
-				|cmdline-char|
 				Sets these |v:event| keys:
 				    cmdlevel
 				    cmdtype
 							*CmdlineLeave*
-CmdlineLeave			Before leaving the command line.
+CmdlineLeave			Before leaving the command-line (including
-				<afile> is set to a single character,
+				non-interactive use of ":" in a mapping: use
-				indicating the type of command-line.
+				|<Cmd>| instead to avoid this).
-				|cmdline-char|
+				<afile> is set to the |cmdline-char|.
 				Sets these |v:event| keys:
 				    abort (mutable)
 				    cmdlevel

runtime/doc/develop.txt

@@ -6,19 +6,20 @@
 
 Development of Nvim					*development*
 
-Nvim is open source software.  Everybody is encouraged to contribute.
+This reference describes design constraints and guidelines, for developing
-    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
+Nvim applications or Nvim itself.
+Architecture and internal concepts are covered in src/nvim/README.md
 
-See src/nvim/README.md for an overview of the source code.
+Nvim is free and open source.  Everybody is encouraged to contribute.
+    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
 
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
 Design goals						*design-goals*
 
-Most important things come first (roughly).
+Most important things come first (roughly).  Some items conflict; this is
-
+intentional.  A balance must be found.
-Note that some items conflict; this is intentional.  A balance must be found.
 
 
 NVIM IS... IMPROVED					*design-improved*
@@ -81,41 +82,6 @@ include the kitchen sink... but it's good for plumbing."
 Developer guidelines				        *dev*
 
 
-JARGON	 						*dev-jargon*
-
-API client ~
-All external UIs and remote plugins (as opposed to regular Vim plugins) are
-"clients" in general; but we call something an "API client" if its purpose is
-to abstract or wrap the RPC API for the convenience of other applications
-(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
-using an HTTP client like curl, but boto3 wraps that in a convenient python
-interface). For example, the Nvim lua-client is an API client:
-    https://github.com/neovim/lua-client
-
-Host ~
-A plugin "host" is both a client (of the Nvim API) and a server (of an
-external platform, e.g. python). It is a remote plugin that hosts other
-plugins.
-
-Remote plugin ~
-Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
-process and communicates with Nvim via the |api|.
-
-Window ~
-The word "window" is commonly used for several things: A window on the screen,
-the xterm window, a window inside Vim to view a buffer.
-To avoid confusion, other items that are sometimes called window have been
-given another name.  Here is an overview of the related items:
-
-screen		The whole display.
-shell		The Vim application.  This can cover the whole screen (e.g.,
-		when running in a console) or part of it (xterm or GUI).
-window		View on a buffer.  There can be several windows in Vim,
-		together with the command line, menubar, toolbar, etc. they
-		fit in the shell.
-frame		Windows are kept in a tree of frames.  Each frame contains
-		a column, row, or window ("leaf" frame).
-
 PROVIDERS 						*dev-provider*
 
 A goal of Nvim is to allow extension of the editor without special knowledge

runtime/doc/help.txt

@@ -150,6 +150,7 @@ GUI ~
 
 Interfaces ~
 |if_cscop.txt|	using Cscope with Vim
+|if_lua.txt|	Lua interface
 |if_pyth.txt|	Python interface
 |if_ruby.txt|	Ruby interface
 |sign.txt|	debugging signs

runtime/doc/intro.txt

@@ -94,7 +94,7 @@ For the most recent information about sponsoring look on the Vim web site:
 
 Neovim development is funded separately from Vim:
 
-	https://neovim.io/sponsors/
+	https://neovim.io/#sponsor
 
 ==============================================================================
 Credits				*credits* *author* *Bram* *Moolenaar*
@@ -702,18 +702,15 @@ window.  You may make the window as small as you like, but if it gets too
 small not a single line will fit in it.  Make it at least 40 characters wide
 to be able to read most messages on the last line.
 
-On most Unix systems, resizing the window is recognized and handled correctly
-by Vim.
-
 ==============================================================================
-Definitions						*definitions*
+Definitions						*definitions* *jargon*
 
-  buffer		Contains lines of text, usually read from a file.
+  buffer		Contains lines of text, usually from a file.
-  screen		The whole area that Vim uses to work in.  This can be
+  screen		The whole area that Nvim uses to display things.
-			a terminal emulator window.  Also called "the Vim
-			window".
   window		A view on a buffer.  There can be multiple windows for
 			one buffer.
+  frame			Windows are kept in a tree of frames.  Each frame
+			contains a column, row, or window ("leaf" frame).
 
 A screen contains one or more windows, separated by status lines and with the
 command line at the bottom.
@@ -746,7 +743,7 @@ A difference is made between four types of lines:
 			lines with wrapping, line breaks, etc.  applied.  They
 			can only be as long as the width of the window allows,
 			longer lines are wrapped or truncated.
-  screen lines		The lines of the screen that Vim uses.  Consists of
+  screen lines		The lines of the screen that Nvim uses.  Consists of
 			the window lines of all windows, with status lines
 			and the command line added.  They can only be as long
 			as the width of the screen allows.  When the command
@@ -770,5 +767,27 @@ buffer lines	logical lines	window lines	screen lines ~
 				5. ddd		13. (command line)
 				6. ~ 
 
+
+API client ~
+All external UIs and remote plugins (as opposed to regular Vim plugins) are
+"clients" in general; but we call something an "API client" if its purpose is
+to abstract or wrap the RPC API for the convenience of other applications
+(just like a REST client or SDK such as boto3 for AWS: you can speak AWS REST
+using an HTTP client like curl, but boto3 wraps that in a convenient python
+interface). For example, the Nvim lua-client is an API client:
+    https://github.com/neovim/lua-client
+
+
+Host ~
+A plugin "host" is both a client (of the Nvim API) and a server (of an
+external platform, e.g. python). It is a remote plugin that hosts other
+plugins.
+
+
+Remote plugin ~
+Arbitrary code registered via |:UpdateRemotePlugins|, that runs in a separate
+process and communicates with Nvim via the |api|.
+
+
 ==============================================================================
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/map.txt

@@ -286,6 +286,9 @@ current mode (instead of always going to normal-mode).  Visual-mode is
 preserved, so tricks with |gv| are not needed.  Commands can be invoked
 directly in cmdline-mode (which otherwise would require timer hacks).
 
+Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
+|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
+
 Unlike <expr> mappings, there are no special restrictions on the <Cmd>
 command: it is executed as if an (unrestricted) |autocmd| was invoked or an
 async event event was processed.

src/nvim/api/vim.c

@@ -743,6 +743,9 @@ void nvim_err_writeln(String str)
 
 /// Gets the current list of buffer handles
 ///
+/// Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
+/// Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
+///
 /// @return List of buffer handles
 ArrayOf(Buffer) nvim_list_bufs(void)
   FUNC_API_SINCE(1)

src/nvim/version.c

@@ -2173,7 +2173,7 @@ void intro_message(int colon)
     N_(NVIM_VERSION_LONG),
     "",
     N_("Nvim is open source and freely distributable"),
-    N_("https://neovim.io/community"),
+    N_("https://neovim.io/#chat"),
     "",
     N_("type  :help nvim<Enter>       if you are new! "),
     N_("type  :checkhealth<Enter>     to optimize Nvim"),

test/functional/api/vim_spec.lua

@@ -1237,7 +1237,7 @@ describe('API', function()
 
   describe('nvim_list_uis', function()
     it('returns empty if --headless', function()
-      -- --embed implies --headless.
+      -- Test runner defaults to --headless.
       eq({}, nvim("list_uis"))
     end)
     it('returns attached UIs', function()

test/functional/ui/screen.lua

@@ -494,7 +494,7 @@ function Screen:_wait(check, flags)
   if warn_immediate and immediate_seen then
      print([[
 
-Warning: A screen test has immediate success. Try to avoid this unless the
+warning: Screen test succeeded immediately. Try to avoid this unless the
 purpose of the test really requires it.]])
     if intermediate_seen then
       print([[
@@ -503,8 +503,7 @@ Use screen:snapshot_util() or screen:redraw_debug() to find them, and add them
 to the test if they make sense.
 ]])
     else
-      print([[If necessary, silence this warning by
+      print([[If necessary, silence this warning with 'unchanged' argument of screen:expect.]])
-supplying the 'unchanged' argument to screen:expect.]])
     end
     did_warn = true
   end
@@ -512,19 +511,17 @@ supplying the 'unchanged' argument to screen:expect.]])
   if failure_after_success then
     print([[
 
-Warning: Screen changes were received after the expected state. This indicates
+warning: Screen changes were received after the expected state. This indicates
 indeterminism in the test. Try adding screen:expect(...) (or wait()) between
 asynchronous (feed(), nvim_input()) and synchronous API calls.
-  - Use Screen:redraw_debug() to investigate the problem. It might find
+  - Use screen:redraw_debug() to investigate; it may find relevant intermediate
-    relevant intermediate states that should be added to the test to make it
+    states that should be added to the test to make it more robust.
-    more robust.
+  - If the purpose of the test is to assert state after some user input sent
-  - If the point of the test is to assert the state after some user input
+    with feed(), adding screen:expect() before the feed() will help to ensure
-    sent with feed(...), also adding an screen:expect(...) before the feed(...)
+    the input is sent when Nvim is in a predictable state. This is preferable
-    will help ensure the input is sent to nvim when nvim is in a predictable
+    to wait(), for being closer to real user interaction.
-    state. This is preferable to using wait(), as it is more closely emulates
-    real user interaction.
   - wait() can trigger redraws and consequently generate more indeterminism.
-    In that case try removing every wait().
+    Try removing wait().
       ]])
     did_warn = true
   end