doc

MAINTAIN.md

@@ -3,8 +3,6 @@ Maintaining the Neovim project
 
 Notes on maintaining the Neovim project.
 
-See also: https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt
-
 General guidelines
 ------------------
 
@@ -14,7 +12,7 @@ General guidelines
 * Use automation to solve problems
 * Never break the API
 
-Ticket Triage
+Ticket triage
 -------------
 
 In practice we haven't found a meaningful way to forecast more precisely than
@@ -38,14 +36,14 @@ just not something you care very much about, by construction. Post-release you
 can review open issues, but chances are your next milestone is already getting
 full :)
 
-Release Policy
+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. High-risk changes may be merged to `master` if
-the next feature-release is not imminent.
+the next release is not imminent.
 
 For maintenance releases, create a `release-x.y` branch. If the current release
 has a major bug:
@@ -55,5 +53,11 @@ has a major bug:
 3. Cut a release from `release-x.y`.
     - Run `./scripts/release.sh`
     - Update (force-push) the remote `stable` tag.
+    - The [nightly job](https://github.com/neovim/bot-ci/blob/master/ci/nightly.sh)
+      will update the release assets based on the `stable` tag.
 
-See also: https://github.com/neovim/neovim/issues/862
+See also
+--------
+
+- https://github.com/neovim/neovim/issues/862
+- https://github.com/git/git/blob/master/Documentation/howto/maintain-git.txt

man/nvim.1

@@ -89,10 +89,14 @@ Ex mode, reading stdin as Ex commands.
 Ex mode, reading stdin as text.
 .Ic :help Ex-mode
 .It Fl es
-Silent/batch mode, reading stdin as Ex commands.
+Silent (non-interactive) Ex mode, reading stdin as Ex commands.
+Useful for scripting because it does NOT start a UI, unlike
+.Fl e .
 .Ic :help silent-mode
 .It Fl \&Es
-Silent/batch mode, reading stdin as text.
+Silent (non-interactive) Ex mode, reading stdin as text.
+Useful for scripting because it does NOT start a UI, unlike
+.Fl E .
 .Ic :help silent-mode
 .It Fl d
 Diff mode.

runtime/doc/api.txt

@@ -310,6 +310,7 @@ Here is an example for creating a float with scratch buffer: >
     call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
 >
 To close the float, |nvim_win_close()| can be used.
+
 ==============================================================================
 Global Functions                                                  *api-global*
 
@@ -748,6 +749,21 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                                 an external top-level window. Currently
                                 accepts no other positioning configuration
                                 together with this.
+                              •  `style` : Configure the apparance of the window.
+                                Currently only takes one non-empty value:
+                                • "minimal" Nvim will display the window with
+                                  many UI options disabled. This is useful
+                                  when displaing a temporary float where the
+                                  text should not be edited. Disables
+                                  'number', 'relativenumber', 'cursorline',
+                                  'cursorcolumn', 'spell' and 'list' options.
+                                  'signcolumn' is changed to `auto` . The
+                                  end-of-buffer region is hidden by setting
+                                  `eob` flag of 'fillchars' to a space char,
+                                  and clearing the |EndOfBuffer| region in
+                                  'winhighlight'.
+                              • top-level window. Currently accepts no other
+                                positioning configuration together with this.
 
                 Return: ~
                     Window handle, or 0 on error
@@ -875,6 +891,23 @@ nvim_get_color_map()                                    *nvim_get_color_map()*
                 Return: ~
                     Map of color names and RGB values.
 
+nvim_get_context({types})                                 *nvim_get_context()*
+                Gets a map of the current editor state.
+
+                Parameters: ~
+                    {types}  Context types ("regs", "jumps", "buflist",
+                             "gvars", ...) to gather, or NIL for all (see
+                             |context-types|).
+
+                Return: ~
+                    map of global |context|.
+
+nvim_load_context({dict})                                *nvim_load_context()*
+                Sets the current editor state from the given |context| map.
+
+                Parameters: ~
+                    {dict}  |Context| map.
+
 nvim_get_mode()                                              *nvim_get_mode()*
                 Gets the current mode. |mode()| "blocking" is true if Nvim is
                 waiting for input.
@@ -1276,7 +1309,7 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
                               Implies `insert` .
                     {opts}    Optional parameters. Reserved for future use.
 
-nvim__inspect_cell({row}, {col})                        *nvim__inspect_cell()*
+nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
                 TODO: Documentation
 
 
@@ -1306,7 +1339,8 @@ nvim_buf_line_count({buffer})                          *nvim_buf_line_count()*
                     Line count, or 0 for unloaded buffer. |api-buffer|
 
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
-                Activates buffer-update events on the channel.
+                Activates buffer-update events on a channel, or as lua
+                callbacks.
 
                 Parameters: ~
                     {buffer}       Buffer handle, or 0 for current buffer
@@ -1315,14 +1349,19 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                                    first notification will be a
                                    `nvim_buf_lines_event` . Otherwise, the
                                    first notification will be a
-                                   `nvim_buf_changedtick_event`
+                                   `nvim_buf_changedtick_event` . Not used for
-                    {opts}         Optional parameters. Reserved for future
+                                   lua callbacks.
-                                   use.
+                    {opts}         Optional parameters. `on_lines` : lua
+                                   callback received on change.
+                                   `on_changedtick` : lua callback received on
+                                   changedtick increment without text change.
+                                   See |api-buffer-updates-lua| for more
+                                   information
 
                 Return: ~
                     False when updates couldn't be enabled because the buffer
                     isn't loaded or `opts` contained an invalid key; otherwise
-                    True.
+                    True. TODO: LUA_API_NO_EVAL
 
 nvim_buf_detach({buffer})                                  *nvim_buf_detach()*
                 Deactivates buffer-update events on the channel.

runtime/doc/eval.txt

@@ -2062,6 +2062,13 @@ count({list}, {expr} [, {ic} [, {start}]])
 				Number	 count how many {expr} are in {list}
 cscope_connection([{num}, {dbpath} [, {prepend}]])
 				Number	checks existence of cscope connection
+ctxget([{index}])		Dict	return the |context| dict at {index}
+ctxpop()			none	pop and restore |context| from the
+					|context-stack|
+ctxpush([{types}])		none	push the current |context| to the
+					|context-stack|
+ctxset({context}[, {index}])	none	set |context| at {index}
+ctxsize()			Number	return |context-stack| size
 cursor({lnum}, {col} [, {off}])
 				Number	move cursor to {lnum}, {col}, {off}
 cursor({list})			Number	move cursor to position in {list}
@@ -3232,6 +3239,32 @@ cscope_connection([{num} , {dbpath} [, {prepend}]])
 		cscope_connection(4, "out", "local")			0
 		cscope_connection(4, "cscope.out", "/usr/local")	1
 <
+
+ctxget([{index}])					*ctxget()*
+		Returns a |Dictionary| representing the |context| at {index}
+		from the top of the |context-stack| (see |context-dict|).
+		If {index} is not given, it is assumed to be 0 (i.e.: top).
+
+ctxpop()						*ctxpop()*
+		Pops and restores the |context| at the top of the
+		|context-stack|.
+
+ctxpush([{types}])					*ctxpush()*
+		Pushes the current editor state (|context|) on the
+		|context-stack|.
+		If {types} is given and is a |List| of |String|s, it specifies
+		which |context-types| to include in the pushed context.
+		Otherwise, all context types are included.
+
+ctxset({context}[, {index}])				*ctxset()*
+		Sets the |context| at {index} from the top of the
+		|context-stack| to that represented by {context}.
+		{context} is a Dictionary with context data (|context-dict|).
+		If {index} is not given, it is assumed to be 0 (i.e.: top).
+
+ctxsize()						*ctxsize()*
+		Returns the size of the |context-stack|.
+
 cursor({lnum}, {col} [, {off}])				*cursor()*
 cursor({list})
 		Positions the cursor at the column (byte count) {col} in the
@@ -5416,24 +5449,22 @@ jobstop({id})						*jobstop()*
 		(if any) will be invoked.
 		See |job-control|.
 
-jobwait({ids}[, {timeout}])				*jobwait()*
+jobwait({jobs}[, {timeout}])				*jobwait()*
-		Wait for a set of jobs and their |on_exit| handlers to
+		Waits for jobs and their |on_exit| handlers to complete.
-		complete.
 
-		{ids} is a list of |job-id|s to wait for.
+		{jobs} is a List of |job-id|s to wait for.
 		{timeout} is the maximum waiting time in milliseconds, -1
 		means forever.
 
 		Timeout of 0 can be used to check the status of a job: >
 			let running = jobwait([{job-id}], 0)[0] == -1
 <
-		During jobwait() callbacks for jobs not in the {ids} list may
+		During jobwait() callbacks for jobs not in the {jobs} list may
 		be invoked. The screen will not redraw unless |:redraw| is
 		invoked by a callback.
 
-		Returns a list of len({ids}) integers, where each integer is
+		Returns a list of len({jobs}) integers, where each integer is
-		the wait-result of the corresponding job. Each wait-result is
+		the status of the corresponding job:
-		one of the following:
 			Exit-code, if the job exited
 			-1 if the timeout was exceeded
 			-2 if the job was interrupted (by |CTRL-C|)

runtime/doc/intro.txt

@@ -43,9 +43,8 @@ There are many books on Vi and Vim.  We recommend these books:
 	"Modern Vim" by Drew Neil
 	https://vimcasts.org/publications/
 
-"Practical Vim" is a popular because of its focus on quickly learning common
+"Practical Vim" is acclaimed for its focus on quickly learning common editing
-editing tasks with Vim.  "Modern Vim" explores new features introduced by Nvim
+tasks with Vim.  "Modern Vim" explores new features in Nvim and Vim 8.
-and Vim 8.
 
 	"Vim - Vi Improved" by Steve Oualline
 

runtime/doc/job_control.txt

@@ -4,7 +4,7 @@
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
 
-Nvim job control					*job-control*
+Nvim job control					*job* *job-control*
 
 Job control is a way to perform multitasking in Nvim, so scripts can spawn and
 control multiple processes without blocking the current Nvim instance.

runtime/doc/repeat.txt

@@ -11,7 +11,7 @@ Chapter 26 of the user manual introduces repeating |usr_26.txt|.
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-1. Single repeats					*single-repeat*
+Single repeats						*single-repeat*
 
 							*.*
 .			Repeat last change, with count replaced with [count].
@@ -35,7 +35,7 @@ of area is used, see |visual-repeat|.
 
 
 ==============================================================================
-2. Multiple repeats					*multi-repeat*
+Multiple repeats					*multi-repeat*
 
 						*:g* *:global* *E148*
 :[range]g[lobal]/{pattern}/[cmd]
@@ -103,7 +103,7 @@ repeated for each matching line.  While doing this you cannot use ":global".
 To abort this type CTRL-C twice.
 
 ==============================================================================
-3. Complex repeats					*complex-repeat*
+Complex repeats						*complex-repeat*
 
 							*q* *recording*
 q{0-9a-zA-Z"}		Record typed characters into register {0-9a-zA-Z"}
@@ -157,7 +157,7 @@ q			Stops recording.
 			line [addr] (default is current line).
 
 ==============================================================================
-4. Using Vim scripts					*using-scripts*
+Using Vim scripts					*using-scripts*
 
 For writing a Vim script, see chapter 41 of the user manual |usr_41.txt|.
 
@@ -470,7 +470,7 @@ Rationale:
 	backslash is to make it very unlikely this is a normal comment line.
 
 ==============================================================================
-5. Using Vim packages					*packages*
+Using Vim packages					*packages*
 
 A Vim package is a directory that contains one or more plugins.  The
 advantages over normal plugins:
@@ -586,7 +586,7 @@ The "after" directory is most likely not useful in a package.  It's not
 disallowed though.
 
 ==============================================================================
-6. Creating Vim packages				*package-create*
+Creating Vim packages					*package-create*
 
 This assumes you write one or more plugins that you distribute as a package.
 
@@ -652,7 +652,7 @@ This works, because loading packages will first add all found directories to
 'runtimepath' before sourcing the plugins.
 
 ==============================================================================
-7. Debugging scripts					*debug-scripts*
+Debugging scripts					*debug-scripts*
 
 Besides the obvious messages that you can add to your scripts to find out what
 they are doing, Vim offers a debug mode.  This allows you to step through a
@@ -876,7 +876,7 @@ OBSCURE
 		user, don't use typeahead for debug commands.
 
 ==============================================================================
-8. Profiling						*profile* *profiling*
+Profiling						*profile* *profiling*
 
 Profiling means that Vim measures the time that is spent on executing
 functions and/or scripts.  The |+profile| feature is required for this.
@@ -993,5 +993,32 @@ mind there are various things that may clobber the results:
 
 - The "self" time is wrong when a function is used recursively.
 
+==============================================================================
+Context							*Context* *context*
+
+The editor state is represented by the Context concept. This includes things
+like the current |jumplist|, values of |registers|, and more, described below.
+
+							*context-types*
+The following Context items are supported:
+	"jumps"		|jumplist|
+	"regs"		|registers|
+	"buflist"	|buffer-list|
+	"gvars"		|global-variable|s
+	"sfuncs"	|script-local| functions
+	"funcs"		global and |script-local| functions
+
+							*context-dict*
+Context objects are dictionaries with the following key-value pairs:
+- "jumps", "regs", "buflist", "gvars":
+      |readfile()|-style |List| representation of corresponding msgpack
+      objects (see |msgpackdump()| and |msgpackparse()|).
+- "funcs" (includes |script-local| functions as well):
+      |List| of |:function| definitions.
+
+							*context-stack*
+An initially-empty internal Context stack is maintained by the ctx-family
+functions (see |ctx-functions|).
+
 
  vim:tw=78:ts=8:noet:ft=help:norl:

runtime/doc/starting.txt

@@ -199,9 +199,8 @@ argument.
 		  -E reads stdin as text (into buffer 1).
 
 -es						*-es* *-Es* *-s-ex* *silent-mode*
--Es		Silent or batch mode.  Special case of |-s| (which takes an
+-Es		Silent mode (no UI), for scripting.  Unrelated to |-s|.
-		argument while "-es" doesn't).  Disables most prompts,
+		Disables most prompts, messages, warnings and errors.
-		messages, warnings and errors.
 
 		-es reads/executes stdin as Ex commands. >
 			printf "put ='foo'\n%%print\n" | nvim -es

runtime/doc/usr_41.txt

@@ -972,6 +972,13 @@ Prompt Buffer:					*promptbuffer-functions*
 	prompt_setinterrupt()	set interrupt callback for a buffer
 	prompt_setprompt()	set the prompt text for a buffer
 
+Context Stack:					*ctx-functions*
+	ctxget()		return context at given index from top
+	ctxpop()		pop and restore top context
+	ctxpush()		push given context
+	ctxset()		set context at given index from top
+	ctxsize()		return context stack size
+
 Various:					*various-functions*
 	mode()			get current editing mode
 	visualmode()		last visual mode used

runtime/doc/vim_diff.txt

@@ -169,6 +169,7 @@ Highlight groups:
   |expr-highlight| highlight groups (prefixed with "Nvim")
   |hl-NormalFloat| highlights floating window
   |hl-NormalNC| highlights non-current windows
+  |hl-MsgArea| highlights messages/cmdline area
   |hl-MsgSeparator| highlights separator for scrolled messages
   |hl-QuickFixLine|
   |hl-Substitute|

runtime/nvim.appdata.xml

@@ -26,6 +26,7 @@
   </screenshots>
 
   <releases>
+    <release date="2019-07-03" version="0.3.8"/>
     <release date="2019-04-29" version="0.3.5"/>
     <release date="2019-01-13" version="0.3.4"/>
     <release date="2019-01-05" version="0.3.3"/>
@@ -33,7 +34,7 @@
     <release date="2018-07-19" version="0.3.1"/>
     <release date="2018-07-11" version="0.3.0"/>
   </releases>
-  
+
   <content_rating type="oars-1.1"/>
   <launchable type="desktop-id">nvim.desktop</launchable>
   <url type="homepage">https://neovim.io/</url>

src/nvim/README.md

@@ -62,6 +62,8 @@ Configure the sanitizer(s) via these environment variables:
 
     # Change to detect_leaks=1 to detect memory leaks (slower).
     export ASAN_OPTIONS="detect_leaks=0:log_path=$HOME/logs/asan"
+    # Show backtraces in the logs.
+    export UBSAN_OPTIONS=print_stacktrace=1
     export MSAN_OPTIONS="log_path=${HOME}/logs/tsan"
     export TSAN_OPTIONS="log_path=${HOME}/logs/tsan"
 

src/nvim/api/vim.c

@@ -1019,7 +1019,7 @@ fail:
 ///
 /// Currently this is used to open floating and external windows.
 /// Floats are windows that are drawn above the split layout, at some anchor
-/// position in some other window. Floats can be draw internally or by external
+/// position in some other window. Floats can be drawn internally or by external
 /// GUI with the |ui-multigrid| extension. External windows are only supported
 /// with multigrid GUIs, and are displayed as separate top-level windows.
 ///
@@ -1416,9 +1416,9 @@ Dictionary nvim_get_color_map(void)
 /// Gets a map of the current editor state.
 ///
 /// @param  types  Context types ("regs", "jumps", "buflist", "gvars", ...)
-///                to gather, or NIL for all.
+///                to gather, or NIL for all (see |context-types|).
 ///
-/// @return map of global context
+/// @return map of global |context|.
 Dictionary nvim_get_context(Array types)
   FUNC_API_SINCE(6)
 {
@@ -1453,9 +1453,9 @@ Dictionary nvim_get_context(Array types)
   return dict;
 }
 
-/// Sets the current editor state to that in given context dictionary.
+/// Sets the current editor state from the given |context| map.
 ///
-/// @param ctx_dict  Context dictionary.
+/// @param  dict  |Context| map.
 Object nvim_load_context(Dictionary dict)
   FUNC_API_SINCE(6)
 {

test/README.md

@@ -140,7 +140,7 @@ To run a *specific* functional test:
 
 To *repeat* a test:
 
-    .deps/usr/bin/busted --lpath='build/?.lua' --filter 'foo' --repeat 1000 test/functional/ui/foo_spec.lua
+    BUSTED_ARGS="--repeat=100 --no-keep-going" TEST_FILE=test/functional/foo_spec.lua make functionaltest
 
 ### Filter by tag
 
@@ -173,43 +173,27 @@ Writing tests
 Guidelines
 ----------
 
-- Consider [BDD](http://en.wikipedia.org/wiki/Behavior-driven_development)
-  guidelines for organization and readability of tests. Describe what you're
-  testing (and the environment if applicable) and create specs that assert its
-  behavior.
-- For testing static functions or functions that have side effects visible only
-  in module-global variables, create accessors for the modified variables. For
-  example, say you are testing a function in misc1.c that modifies a static
-  variable, create a file `test/c-helpers/misc1.c` and add a function that
-  retrieves the value after the function call. Files under `test/c-helpers` will
-  only be compiled when building the test shared library.
 - Luajit needs to know about type and constant declarations used in function
   prototypes. The
   [helpers.lua](https://github.com/neovim/neovim/blob/master/test/unit/helpers.lua)
   file automatically parses `types.h`, so types used in the tested functions
-  must be moved to it to avoid having to rewrite the declarations in the test
+  could be moved to it to avoid having to rewrite the declarations in the test
-  files (even though this is how it's currently done currently in the misc1/fs
+  files.
-  modules, but contributors are encouraged to refactor the declarations).
+  - `#define` constants must be rewritten `const` or `enum` so they can be
-  - Macro constants must be rewritten as enums so they can be "visible" to the
+    "visible" to the tests.
-    tests automatically.
+- Use **pending()** to skip tests
-- Busted supports various "output providers". The
-  **[gtest](https://github.com/Olivine-Labs/busted/pull/394) output provider**
-  shows verbose details that can be useful to diagnose hung tests. Either modify
-  the Makefile or compile with `make
-  CMAKE_EXTRA_FLAGS=-DBUSTED_OUTPUT_TYPE=gtest` to enable it.
-- **Use busted's `pending()` feature** to skip tests
   ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
   Do not silently skip the test with `if-else`. If a functional test depends on
   some external factor (e.g. the existence of `md5sum` on `$PATH`), *and* you
   can't mock or fake the dependency, then skip the test via `pending()` if the
   external factor is missing. This ensures that the *total* test-count
   (success + fail + error + pending) is the same in all environments.
-    - *Note:* `pending()` is ignored if it is missing an argument _unless_ it is
+    - *Note:* `pending()` is ignored if it is missing an argument, unless it is
       [contained in an `it()` block](https://github.com/neovim/neovim/blob/d21690a66e7eb5ebef18046c7a79ef898966d786/test/functional/ex_cmds/grep_spec.lua#L11).
       Provide empty function argument if the `pending()` call is outside of `it()`
       ([example](https://github.com/neovim/neovim/commit/5c1dc0fbe7388528875aff9d7b5055ad718014de#diff-bf80b24c724b0004e8418102f68b0679R18)).
-- Really long `source([=[...]=])` blocks may break syntax highlighting. Try
+- Really long `source([=[...]=])` blocks may break Vim's Lua syntax
-  `:syntax sync fromstart` to fix it.
+  highlighting. Try `:syntax sync fromstart` to fix it.
 
 Where tests go
 --------------
@@ -254,6 +238,8 @@ Test behaviour is affected by environment variables. Currently supported
 treated as Integer; when defined, treated as String; when defined, treated as 
 Number; !must be defined to function properly):
 
+- `BUSTED_ARGS` (F) (U): arguments forwarded to `busted`.
+
 - `GDB` (F) (D): makes nvim instances to be run under `gdbserver`. It will be
   accessible on `localhost:7777`: use `gdb build/bin/nvim`, type `target remote
   :7777` inside.