doc

9 files changed, 134 insertions, 30 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1af327e572..c372bb401e 100644
--- a/runtime/doc/api.txt
+++ b/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`
-                    {opts}         Optional parameters. Reserved for future
-                                   use.
+                                   `nvim_buf_changedtick_event` . Not used for
+                                   lua callbacks.
+                    {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.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 5032dc16ee..53a5f247f9 100644
--- a/runtime/doc/eval.txt
+++ b/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()*
-		Wait for a set of jobs and their |on_exit| handlers to
-		complete.
+jobwait({jobs}[, {timeout}])				*jobwait()*
+		Waits for jobs and their |on_exit| handlers to 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
-		the wait-result of the corresponding job. Each wait-result is
-		one of the following:
+		Returns a list of len({jobs}) integers, where each integer is
+		the status of the corresponding job:
 			Exit-code, if the job exited
 			-1 if the timeout was exceeded
 			-2 if the job was interrupted (by |CTRL-C|)
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index c240f08a75..887ef764bd 100644
--- a/runtime/doc/intro.txt
+++ b/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
-editing tasks with Vim.  "Modern Vim" explores new features introduced by Nvim
-and Vim 8.
+"Practical Vim" is acclaimed for its focus on quickly learning common editing
+tasks with Vim.  "Modern Vim" explores new features in Nvim and Vim 8.
 
 	"Vim - Vi Improved" by Steve Oualline
 
diff --git a/runtime/doc/job_control.txt b/runtime/doc/job_control.txt
index ae208c0755..bf01e8e266 100644
--- a/runtime/doc/job_control.txt
+++ b/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.
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index 425ef4e926..8f6d3aec2e 100644
--- a/runtime/doc/repeat.txt
+++ b/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:
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index fa4d87e915..1775fcddbd 100644
--- a/runtime/doc/starting.txt
+++ b/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
-		argument while "-es" doesn't).  Disables most prompts,
-		messages, warnings and errors.
+-Es		Silent mode (no UI), for scripting.  Unrelated to |-s|.
+		Disables most prompts, messages, warnings and errors.
 
 		-es reads/executes stdin as Ex commands. >
 			printf "put ='foo'\n%%print\n" | nvim -es
diff --git a/runtime/doc/usr_41.txt b/runtime/doc/usr_41.txt
index 2a2885b4d3..c770950a96 100644
--- a/runtime/doc/usr_41.txt
+++ b/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
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index a358da460c..3c1654fd2b 100644
--- a/runtime/doc/vim_diff.txt
+++ b/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|
diff --git a/runtime/nvim.appdata.xml b/runtime/nvim.appdata.xml
index fb409ff0b8..32d3c523c6 100644
--- a/runtime/nvim.appdata.xml
+++ b/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>