Merge branch 'master' into colored-cmdline

21 files changed, 435 insertions, 437 deletions

diff --git a/runtime/CMakeLists.txt b/runtime/CMakeLists.txt
index 69498dc1a1..a9efc90b87 100644
--- a/runtime/CMakeLists.txt
+++ b/runtime/CMakeLists.txt
@@ -100,20 +100,6 @@ add_custom_target(
     ${GENERATED_PACKAGE_TAGS}
 )
 
-# Optional targets for nvim.desktop file and icon.
-find_program(XDG_MENU_PRG xdg-desktop-menu)
-find_program(XDG_ICON_PRG xdg-icon-resource)
-if(XDG_MENU_PRG)
-  add_custom_target(desktop-file
-    COMMAND xdg-desktop-menu install --novendor ${PROJECT_SOURCE_DIR}/runtime/nvim.desktop)
-  # add_dependencies(runtime desktop-file)
-endif()
-if(XDG_ICON_PRG)
-  add_custom_target(desktop-icon
-    COMMAND xdg-icon-resource install --novendor --size 128 ${PROJECT_SOURCE_DIR}/runtime/nvim.png)
-  # add_dependencies(runtime desktop-icon)
-endif()
-
 # CMake is painful here.  It will create the destination using the user's
 # current umask, and we don't want that.  And we don't just want to install
 # the target directory, as it will mess with existing permissions.  So this
@@ -128,6 +114,16 @@ install_helper(
   FILES ${GENERATED_SYN_VIM}
   DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/nvim/runtime/syntax/vim)
 
+if(NOT APPLE)
+  install_helper(
+    FILES ${CMAKE_CURRENT_SOURCE_DIR}/nvim.desktop
+    DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/applications)
+
+  install_helper(
+    FILES ${CMAKE_CURRENT_SOURCE_DIR}/nvim.png
+    DESTINATION ${CMAKE_INSTALL_DATAROOTDIR}/pixmaps)
+endif()
+
 file(GLOB_RECURSE RUNTIME_PROGRAMS
   RELATIVE ${CMAKE_CURRENT_SOURCE_DIR}
   *.awk *.sh *.bat)
diff --git a/runtime/autoload/provider.vim b/runtime/autoload/provider.vim
new file mode 100644
index 0000000000..a4d5241b57
--- /dev/null
+++ b/runtime/autoload/provider.vim
@@ -0,0 +1,18 @@
+" Common functionality for providers
+
+let s:stderr = {}
+
+function! provider#stderr_collector(chan_id, data, event) dict
+   let stderr = get(s:stderr, a:chan_id, [''])
+   let stderr[-1] .= a:data[0]
+   call extend(stderr, a:data[1:])
+   let s:stderr[a:chan_id] = stderr
+endfunction
+
+function! provider#clear_stderr(chan_id)
+   silent! call delete(s:stderr, a:chan_id)
+endfunction
+
+function! provider#get_stderr(chan_id)
+   return get(s:stderr, a:chan_id, [])
+endfunction
diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim
index a67681d28e..8eb694e9fa 100644
--- a/runtime/autoload/provider/clipboard.vim
+++ b/runtime/autoload/provider/clipboard.vim
@@ -6,7 +6,7 @@ let s:paste = {}
 
 " When caching is enabled, store the jobid of the xclip/xsel process keeping
 " ownership of the selection, so we know how long the cache is valid.
-let s:selection = { 'owner': 0, 'data': [] }
+let s:selection = { 'owner': 0, 'data': [], 'on_stderr': function('provider#stderr_collector') }
 
 function! s:selection.on_exit(jobid, data, event) abort
   " At this point this nvim instance might already have launched
@@ -14,6 +14,13 @@ function! s:selection.on_exit(jobid, data, event) abort
   if self.owner == a:jobid
     let self.owner = 0
   endif
+  if a:data != 0
+    let stderr = provider#get_stderr(a:jobid)
+    echohl WarningMsg
+    echomsg 'clipboard: error invoking '.get(self.argv, 0, '?').': '.join(stderr)
+    echohl None
+  endif
+  call provider#clear_stderr(a:jobid)
 endfunction
 
 let s:selections = { '*': s:selection, '+': copy(s:selection)}
@@ -135,18 +142,19 @@ function! s:clipboard.set(lines, regtype, reg) abort
   end
   let selection.data = [a:lines, a:regtype]
   let argv = split(s:copy[a:reg], " ")
+  let selection.argv = argv
   let selection.detach = s:cache_enabled
   let selection.cwd = "/"
   let jobid = jobstart(argv, selection)
-  if jobid <= 0
+  if jobid > 0
+    call jobsend(jobid, a:lines)
+    call jobclose(jobid, 'stdin')
+    let selection.owner = jobid
+  else
     echohl WarningMsg
-    echo "clipboard: error when invoking provider"
+    echomsg 'clipboard: failed to execute: '.(s:copy[a:reg])
     echohl None
-    return 0
   endif
-  call jobsend(jobid, a:lines)
-  call jobclose(jobid, 'stdin')
-  let selection.owner = jobid
 endfunction
 
 function! provider#clipboard#Call(method, args) abort
diff --git a/runtime/autoload/provider/pythonx.vim b/runtime/autoload/provider/pythonx.vim
index 2f64c22c71..7285ed43ea 100644
--- a/runtime/autoload/provider/pythonx.vim
+++ b/runtime/autoload/provider/pythonx.vim
@@ -5,17 +5,7 @@ endif
 
 let s:loaded_pythonx_provider = 1
 
-let s:stderr = {}
-let s:job_opts = {'rpc': v:true}
-
-" TODO(bfredl): this logic is common and should be builtin
-function! s:job_opts.on_stderr(chan_id, data, event)
-  let stderr = get(s:stderr, a:chan_id, [''])
-  let last = remove(stderr, -1)
-  let a:data[0] = last.a:data[0]
-  call extend(stderr, a:data)
-  let s:stderr[a:chan_id] = stderr
-endfunction
+let s:job_opts = {'rpc': v:true, 'on_stderr': function('provider#stderr_collector')}
 
 function! provider#pythonx#Require(host) abort
   let ver = (a:host.orig_name ==# 'python') ? 2 : 3
@@ -38,9 +28,11 @@ function! provider#pythonx#Require(host) abort
   catch
     echomsg v:throwpoint
     echomsg v:exception
-    for row in get(s:stderr, channel_id, [])
+    for row in provider#get_stderr(channel_id)
       echomsg row
     endfor
+  finally
+    call provider#clear_stderr(channel_id)
   endtry
   throw remote#host#LoadErrorForHost(a:host.orig_name,
         \ '$NVIM_PYTHON_LOG_FILE')
diff --git a/runtime/autoload/tutor.vim b/runtime/autoload/tutor.vim
index 43d8a87886..56e2283465 100644
--- a/runtime/autoload/tutor.vim
+++ b/runtime/autoload/tutor.vim
@@ -15,30 +15,17 @@ function! tutor#SetupVim()
     endif
 endfunction
 
-" Mappings: {{{1
-
-function! s:CheckMaps()
-    nmap
+" Loads metadata file, if available
+function! tutor#LoadMetadata()
+    let b:tutor_metadata = json_decode(join(readfile(expand('%').'.json'), "\n"))
 endfunction
 
-function! s:MapKeyWithRedirect(key, cmd)
-    if maparg(a:key) !=# ''
-        redir => l:keys
-        silent call s:CheckMaps()
-        redir END
-        let l:key_list = split(l:keys, '\n')
-
-        let l:raw_map = filter(copy(l:key_list), "v:val =~# '\\* ".a:key."'")
-        if len(l:raw_map) == 0
-            exe "nnoremap <buffer> <expr> ".a:key." ".a:cmd
-            return
-        endif
-        let l:map_data = split(l:raw_map[0], '\s*')
+" Mappings: {{{1
 
-        exe "nnoremap <buffer> <expr> ".l:map_data[0]." ".a:cmd
-    else
-        exe "nnoremap <buffer> <expr> ".a:key." ".a:cmd
-    endif
+function! tutor#SetNormalMappings()
+    nnoremap <silent> <buffer> <CR> :call tutor#FollowLink(0)<cr>
+    nnoremap <silent> <buffer> <2-LeftMouse> :call tutor#MouseDoubleClick()<cr>
+    nnoremap <buffer> >> :call tutor#InjectCommand()<cr>
 endfunction
 
 function! tutor#MouseDoubleClick()
@@ -46,7 +33,7 @@ function! tutor#MouseDoubleClick()
         normal! zo
     else
         if match(getline('.'), '^#\{1,} ') > -1
-            normal! zc
+            silent normal! zc
         else
             call tutor#FollowLink(0)
         endif
@@ -59,114 +46,6 @@ function! tutor#InjectCommand()
     redraw | echohl WarningMsg | echon  "tutor: ran" | echohl None | echon " " | echohl Statement | echon l:cmd
 endfunction
 
-function! tutor#SetNormalMappings()
-    call s:MapKeyWithRedirect('l', 'tutor#ForwardSkipConceal(v:count1)')
-    call s:MapKeyWithRedirect('h', 'tutor#BackwardSkipConceal(v:count1)')
-    call s:MapKeyWithRedirect('<right>', 'tutor#ForwardSkipConceal(v:count1)')
-    call s:MapKeyWithRedirect('<left>', 'tutor#BackwardSkipConceal(v:count1)')
-
-    nnoremap <silent> <buffer> <CR> :call tutor#FollowLink(0)<cr>
-    nnoremap <silent> <buffer> <2-LeftMouse> :call tutor#MouseDoubleClick()<cr>
-    nnoremap <buffer> >> :call tutor#InjectCommand()<cr>
-endfunction
-
-function! tutor#SetSampleTextMappings()
-    noremap <silent> <buffer> A :if match(getline('.'), '^--->') > -1 \| call search('\s{\@=', 'Wc') \| startinsert \| else \| startinsert! \| endif<cr>
-    noremap <silent> <buffer> $ :if match(getline('.'), '^--->') > -1 \| call search('.\s{\@=', 'Wc') \| else \| call search('$', 'Wc') \| endif<cr>
-    onoremap <silent> <buffer> $ :if match(getline('.'), '^--->') > -1 \| call search('.\s{\@=', 'Wc') \| else \| call search('$', 'Wc') \| endif<cr>
-    noremap <silent> <buffer> ^ :if match(getline('.'), '^--->') > -1 \| call search('\(--->\s\)\@<=.', 'bcW') \| else \| call search('^', 'bcW') \|endif<cr>
-    onoremap <silent> <buffer> ^ :if match(getline('.'), '^--->') > -1 \| call search('\(--->\s\)\@<=.', 'bcW') \| else \| call search('^', 'bcW') \|endif<cr>
-    nmap <silent> <buffer> 0 ^<esc>
-    nmap <silent> <buffer> <Home> ^<esc>
-    nmap <silent> <buffer> <End> $
-    imap <silent> <buffer> <Home> <esc>^<esc>:startinsert<cr>
-    imap <silent> <buffer> <End> <esc>$:startinsert<cr>
-    noremap <silent> <buffer> I :exe "normal! 0" \| startinsert<cr>
-endfunction
-
-" Navigation: {{{1
-
-" taken from http://stackoverflow.com/a/24224578
-
-function! tutor#ForwardSkipConceal(count)
-    let cnt=a:count
-    let mvcnt=0
-    let c=col('.')
-    let l=line('.')
-    let lc=col('$')
-    let line=getline('.')
-    while cnt
-        if c>=lc
-            let mvcnt+=cnt
-            break
-        endif
-        if stridx(&concealcursor, 'n')==-1
-            let isconcealed=0
-        else
-            let [isconcealed, cchar, group] = synconcealed(l, c)
-        endif
-        if isconcealed
-            let cnt-=strchars(cchar)
-            let oldc=c
-            let c+=1
-            while c < lc
-              let [isconcealed2, cchar2, group2] = synconcealed(l, c)
-              if !isconcealed2 || cchar2 != cchar
-                  break
-              endif
-              let c+= 1
-            endwhile
-            let mvcnt+=strchars(line[oldc-1:c-2])
-        else
-            let cnt-=1
-            let mvcnt+=1
-            let c+=len(matchstr(line[c-1:], '.'))
-        endif
-    endwhile
-    return mvcnt.'l'
-endfunction
-
-function! tutor#BackwardSkipConceal(count)
-    let cnt=a:count
-    let mvcnt=0
-    let c=col('.')
-    let l=line('.')
-    let lc=0
-    let line=getline('.')
-    while cnt
-        if c<=1
-            let mvcnt+=cnt
-            break
-        endif
-        if stridx(&concealcursor, 'n')==-1 || c == 0
-            let isconcealed=0
-        else
-            let [isconcealed, cchar, group]=synconcealed(l, c-1)
-        endif
-        if isconcealed
-            let cnt-=strchars(cchar)
-            let oldc=c
-            let c-=1
-            while c>1
-              let [isconcealed2, cchar2, group2] = synconcealed(l, c-1)
-              if !isconcealed2 || cchar2 != cchar
-                  break
-              endif
-              let c-=1
-            endwhile
-            let c = max([c, 1])
-            let mvcnt+=strchars(line[c-1:oldc-2])
-        else
-            let cnt-=1
-            let mvcnt+=1
-            let c-=len(matchstr(line[:c-2], '.$'))
-        endif
-    endwhile
-    return mvcnt.'h'
-endfunction
-
-" Hypertext: {{{1
-
 function! tutor#FollowLink(force)
     let l:stack_s = join(map(synstack(line('.'), col('.')), 'synIDattr(v:val, "name")'), '')
     if l:stack_s =~# 'tutorLink'
@@ -209,42 +88,40 @@ function! tutor#InfoText()
     return join(l:info_parts, " ")
 endfunction
 
-" Marks {{{1
-function! tutor#PlaceXMarks()
-    call cursor(1, 1)
-    let b:tutor_sign_id = 1
-    while search('^--->', 'W') > 0
-        call tutor#CheckText(getline('.'))
-        let b:tutor_sign_id+=1
-    endwhile
-    call cursor(1, 1)
+
+" Marks: {{{1
+
+function! tutor#ApplyMarks()
+    hi! link tutorExpect Special
+    if exists('b:tutor_metadata') && has_key(b:tutor_metadata, 'expect')
+        let b:tutor_sign_id = 1
+        for expct in keys(b:tutor_metadata['expect'])
+            let lnum = eval(expct)
+            call matchaddpos('tutorExpect', [lnum])
+            call tutor#CheckLine(lnum)
+        endfor
+    endif
 endfunction
 
-function! tutor#CheckText(text)
-    if match(a:text, '{expect:ANYTHING}\s*$') == -1
-        if match(getline('.'), '^--->\s*$') > -1
-            exe "sign place ".b:tutor_sign_id." line=".line('.')." name=tutorbad buffer=".bufnr('%')
-        else
-            if match(getline('.'), '|expect:.\+|') == -1
-                let l:cur_text = matchstr(a:text, '---> \zs.\{-}\ze {expect:')
-                let l:expected_text = matchstr(a:text, '{expect:\zs.*\ze}\s*$')
-            else
-                let l:cur_text = matchstr(a:text, '---> \zs.\{-}\ze |expect:')
-                let l:expected_text = matchstr(a:text, '|expect:\zs.*\ze|\s*$')
-            endif
-            if l:cur_text ==# l:expected_text
-                exe "sign place ".b:tutor_sign_id." line=".line('.')." name=tutorok buffer=".bufnr('%')
-            else
-                exe "sign place ".b:tutor_sign_id." line=".line('.')." name=tutorbad buffer=".bufnr('%')
-            endif
+function! tutor#ApplyMarksOnChanged()
+    if exists('b:tutor_metadata') && has_key(b:tutor_metadata, 'expect')
+        let lnum = line('.')
+        if index(keys(b:tutor_metadata['expect']), string(lnum)) > -1
+            call tutor#CheckLine(lnum)
         endif
     endif
 endfunction
 
-function! tutor#OnTextChanged()
-    let l:text = getline('.')
-    if match(l:text, '^--->') > -1
-        call tutor#CheckText(l:text)
+function! tutor#CheckLine(line)
+    if exists('b:tutor_metadata') && has_key(b:tutor_metadata, 'expect')
+        let bufn = bufnr('%')
+        let ctext = getline(a:line)
+        if b:tutor_metadata['expect'][string(a:line)] == -1 || ctext ==# b:tutor_metadata['expect'][string(a:line)]
+            exe "sign place ".b:tutor_sign_id." line=".a:line." name=tutorok buffer=".bufn
+        else
+            exe "sign place ".b:tutor_sign_id." line=".a:line." name=tutorbad buffer=".bufn
+        endif
+        let b:tutor_sign_id+=1
     endif
 endfunction
 
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index 6af3c4d5d7..f82d61370c 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -861,8 +861,7 @@ Exceptions:
 Substitute with an expression			*sub-replace-expression*
 						*sub-replace-\=* *s/\=*
 When the substitute string starts with "\=" the remainder is interpreted as an
-expression.  This does not work recursively: a |substitute()| function inside
-the expression cannot use "\=" for the substitute string.
+expression.
 
 The special meaning for characters as mentioned at |sub-replace-special| does
 not apply except for "<CR>".  A <NL> character is used as a line break, you
diff --git a/runtime/doc/digraph.txt b/runtime/doc/digraph.txt
index 89351c5b4f..43f8ccab06 100644
--- a/runtime/doc/digraph.txt
+++ b/runtime/doc/digraph.txt
@@ -143,7 +143,7 @@ a standard meaning:
 	Two			2	Hook
 	Nine			9	Horn
 
-	Equals			=	Cyrillic (= used as second char) 
+	Equals			=	Cyrillic (= used as second char)
 	Asterisk		*	Greek
 	Percent sign		%	Greek/Cyrillic special
 	Plus			+	smalls: Arabic, capitals: Hebrew
@@ -922,6 +922,7 @@ char  digraph	hex	dec	official name ~
 †	/-	2020	8224	DAGGER
 ‡	/=	2021	8225	DOUBLE DAGGER
 ‥	..	2025	8229	TWO DOT LEADER
+…	,.	2026	8230	HORIZONTAL ELLIPSIS
 ‰	%0	2030	8240	PER MILLE SIGN
 ′	1'	2032	8242	PRIME
 ″	2'	2033	8243	DOUBLE PRIME
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 3a928c97ec..e1d156e91f 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -4046,7 +4046,9 @@ getcompletion({pat}, {type} [, {filtered}])		*getcompletion()*
 		locale		locale names (as output of locale -a)
 		mapping		mapping name
 		menu		menus
+		messages	|:messages| suboptions
 		option		options
+		packadd		optional package |pack-add| names
 		shellcmd	Shell command
 		sign		|:sign| suboptions
 		syntax		syntax file names |'syntax'|
@@ -4273,7 +4275,8 @@ getqflist([{what}])					*getqflist()*
 		If the optional {what} dictionary argument is supplied, then
 		returns only the items listed in {what} as a dictionary. The
 		following string items are supported in {what}:
-			nr	get information for this quickfix list
+			nr	get information for this quickfix list; zero
+				means the current quickfix list
 			title	get the list title
 			winid	get the |window-ID| (if opened)
 			all	all of the above quickfix properties
@@ -5526,6 +5529,51 @@ max({expr})	Return the maximum value of all items in {expr}.
 		items in {expr} cannot be used as a Number this results in
                 an error.  An empty |List| or |Dictionary| results in zero.
 
+menu_get({path}, {modes})				*menu_get()*
+		Returns a |List| of |Dictionaries| describing |menus| (defined
+		by |:menu|, |:amenu|, etc.).
+		{path} limits the result to a subtree of the menu hierarchy
+		(empty string matches all menus). E.g. to get items in the
+		"File" menu subtree: >
+			:echo menu_get('File','')
+<
+		{modes} is a string of zero or more modes (see |maparg()| or
+		|creating-menus| for the list of modes). "a" means "all".
+
+		For example: >
+			nnoremenu &Test.Test inormal
+			inoremenu Test.Test insert
+			vnoremenu Test.Test x
+			echo menu_get("")
+<
+		returns something like this:
+>
+			[ {
+			  "hidden": 0,
+			  "name": "Test",
+			  "priority": 500,
+			  "shortcut": 84,
+			  "submenus": [ {
+			    "hidden": 0,
+			    "mappings": {
+			      i": {
+				"enabled": 1,
+				"noremap": 1,
+				"rhs": "insert",
+				"sid": 1,
+				"silent": 0
+			      },
+			      n": { ... },
+			      s": { ... },
+			      v": { ... }
+			    },
+			    "name": "Test",
+			    "priority": 500,
+			    "shortcut": 0
+			  } ]
+			} ]
+<
+
 							*min()*
 min({expr})	Return the minimum value of all items in {expr}.
 		{expr} can be a list or a dictionary.  For a dictionary,
@@ -5984,9 +6032,9 @@ range({expr} [, {max} [, {stride}]])				*range()*
 							*readfile()*
 readfile({fname} [, {binary} [, {max}]])
 		Read file {fname} and return a |List|, each line of the file
-		as an item.  Lines broken at NL characters.  Macintosh files
-		separated with CR will result in a single long line (unless a
-		NL appears somewhere).
+		as an item.  Lines are broken at NL characters.  Macintosh
+		files separated with CR will result in a single long line
+		(unless a NL appears somewhere).
 		All NUL characters are replaced with a NL character.
 		When {binary} contains "b" binary mode is used:
 		- When the last line ends in a NL an extra empty list item is
@@ -6504,15 +6552,27 @@ serverlist()						*serverlist()*
 			nvim --cmd "echo serverlist()" --cmd "q"
 <
 serverstart([{address}])				*serverstart()*
-		Opens a TCP socket (IPv4/IPv6), Unix domain socket (Unix),
-		or named pipe (Windows) at {address} for clients to connect
-		to and returns {address}.
+		Opens a socket or named pipe at {address} and listens for
+		|RPC| messages. Clients can send |API| commands to the address
+		to control Nvim. Returns the address string.
 
-		If {address} contains `:`, a TCP socket is used. Everything in
-		front of the last occurrence of `:` is the IP or hostname,
-		everything after it the port. If the port is empty or `0`,
-		a random port will be assigned.
+		If {address} does not contain a colon ":" it is interpreted as
+		a named pipe or Unix domain socket path.
 
+		Example: >
+			if has('win32')
+			  call serverstart('\\.\pipe\nvim-pipe-1234')
+			else
+			  call serverstart('nvim.sock')
+			endif
+<
+		If {address} contains a colon ":" it is interpreted as a TCP
+		address where the last ":" separates the host and port.
+		Assigns a random port if it is empty or 0. Supports IPv4/IPv6.
+
+		Example: >
+			:call serverstart('::1:12345')
+<
 		If no address is given, it is equivalent to: >
 			:call serverstart(tempname())
 
@@ -7291,6 +7351,9 @@ submatch({nr}[, {list}])			*submatch()* *E935*
 		|substitute()| this list will always contain one or zero
 		items, since there are no real line breaks.
 
+		When substitute() is used recursively only the submatches in
+		the current (deepest) call can be obtained.
+
 		Example: >
 			:s/\d\+/\=submatch(0) + 1/
 <		This finds the first number in the line and adds one to it.
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 88d04aa76b..b9cc94ce5f 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -249,8 +249,7 @@ Vi	"the original".  Without further remarks this is the version
 	of Vi that appeared in Sun OS 4.x.  ":version" returns
 	"Version 3.7, 6/7/85".  Sometimes other versions are referred
 	to.  Only runs under Unix.  Source code only available with a
-	license.  More information on Vi can be found through:
-		http://vi-editor.org	[doesn't currently work...]
+	license.
 							*Nvi*
 Nvi	The "New" Vi.  The version of Vi that comes with BSD 4.4 and FreeBSD.
 	Very good compatibility with the original Vi, with a few extensions.
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index bfcf621cb8..944f7474be 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1202,6 +1202,7 @@ completion can be enabled:
 	-complete=locale	locale names (as output of locale -a)
 	-complete=mapping	mapping name
 	-complete=menu		menus
+	-complete=messages	|:messages| suboptions
 	-complete=option	options
 	-complete=packadd	optional package |pack-add| names
 	-complete=shellcmd	Shell command
diff --git a/runtime/doc/nvim.txt b/runtime/doc/nvim.txt
index 29059f83d9..f3f4305ad5 100644
--- a/runtime/doc/nvim.txt
+++ b/runtime/doc/nvim.txt
@@ -6,6 +6,8 @@
 
 Nvim							   *nvim* *nvim-intro*
 
+Nvim is based on Vim by Bram Moolenaar.
+
 If you are new to Vim see |help.txt|, or type ":Tutor".
 If you already use Vim see |nvim-from-vim| for a quickstart.
 
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index dc968cd666..bc9705d116 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -2736,7 +2736,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 'guicursor' 'gcr'	string	(default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20")
 			global
 	Configures the cursor style for each mode. Works in the GUI and many
-	terminals.  See |cursor-shape| for details.
+	terminals.  See |tui-cursor-shape|.
 
 	To disable cursor-styling, reset the option: >
 		:set guicursor=
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index d869516bff..0b72ec9960 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -349,6 +349,9 @@ argument.
 							*--api-info*
 --api-info 	Print msgpack-encoded |api-metadata| and exit.
 
+							*--headless*
+--headless 	Do not start the built-in UI.
+
 ==============================================================================
 2. Initialization				*initialization* *startup*
 
diff --git a/runtime/doc/term.txt b/runtime/doc/term.txt
index bce944eab5..73c8956085 100644
--- a/runtime/doc/term.txt
+++ b/runtime/doc/term.txt
@@ -1,76 +1,62 @@
 *term.txt*      Nvim
 
 
-		  VIM REFERENCE MANUAL    by Bram Moolenaar
+                            NVIM REFERENCE MANUAL
 
 
 Terminal information
 
-Vim uses information about the terminal you are using to fill the screen and
-recognize what keys you hit.  If this information is not correct, the screen
-may be messed up or keys may not be recognized.  The actions which have to be
-performed on the screen are accomplished by outputting a string of
-characters.
+Nvim (except in |--headless| mode) uses information about the terminal you are
+using to present a built-in UI.  If that information is not correct, the
+screen may be messed up or keys may not be recognized.
 
                                       Type <M-]> to see the table of contents.
 
 ==============================================================================
 Startup						*startup-terminal*
 
-When Vim is started a default terminal type is assumed.  for MS-DOS this is
-the pc terminal, for Unix an ansi terminal.
+Nvim (except in |--headless| mode) guesses a terminal type when it starts.
+|$TERM| is the primary hint that determines the terminal type.
 
 					*terminfo* *E557* *E558* *E559*
-On Unix the terminfo database is used.  There is no access to the terminfo
-settings with |:set|.
+The terminfo database is used if available.
 
 The Unibilium library (used by Nvim to read terminfo) allows you to override
-an out-of-date system terminfo database with one in your $HOME/.terminfo/
-directory, in part or in whole.
+the system terminfo with one in $HOME/.terminfo/ directory, in part or in
+whole.
 
-Building your own up-to-date terminfo database is usually as simple as running
-this as a non-superuser:
+Building your own terminfo is usually as simple as running this as
+a non-superuser:
 >
-  wget http://invisible-island.net/datafiles/current/terminfo.src.gz
+  curl -LO http://invisible-island.net/datafiles/current/terminfo.src.gz
   gunzip terminfo.src.gz
   tic terminfo.src
 <
-								*TERM*
-If you experience terminal difficulties, first ensure that you have set the
-correct terminal type in your $TERM environment variable so that Nvim is
-pulling the correct entry from the terminfo database in the first place.
+								*$TERM*
+The $TERM environment variable must match the terminal you are using!
+Otherwise Nvim cannot know what sequences your terminal expects, and weird
+or sub-optimal behavior will result (scrolling quirks, wrong colors, etc.).
 
-Per the terminfo source file from ncurses:
+$TERM is also important because it is mirrored by SSH to the remote session,
+unlike other common client-end environment variables ($COLORTERM,
+$XTERM_VERSION, $VTE_VERSION, $KONSOLE_PROFILE_NAME, $TERM_PROGRAM, ...).
 
- For these terminals          Set $TERM to                |builtin-terms|?
+ For this terminal            Set $TERM to                |builtin-terms|?
 
   iTerm.app                "iterm" or "iTerm.app"                Y
   anything libvte based    "vte" or "vte-256color"               Y
-   (e.g. GNOME Terminal)   ("gnome" and "gnome-256color" are
-                            available as aliases for these)
+   (e.g. GNOME Terminal)   (aliases: "gnome", "gnome-256color")
   tmux                     "tmux" or "tmux-256color"             Y
   screen                   "screen" or "screen-256color"         Y
   PuTTY                    "putty" or "putty-256color"           Y
   Terminal.app             "nsterm"                              N
   Linux virtual terminal   "linux" or "linux-256color"           Y
 
-Describing any of these as "xterm" or "xterm-256colour" will not describe the
-terminal correctly to Nvim, and will cause various kinds of problematic
-behaviours.
-
-Setting your $TERM environment variable to the correct value also avoids the
-problem that SSH does not mirror arbitrary client-end environment variables
-such as $COLORTERM, $XTERM_VERSION, $VTE_VERSION, $KONSOLE_PROFILE_NAME, and
-$TERM_PROGRAM to the server end, whereas it does send the $TERM environment
-variable.
-
-See |terminfo| for dealing with out of date terminfo databases.
-
 					*builtin-terms* *builtin_terms*
 If a |terminfo| database is not available, or no entry for the terminal type is
-found in that database, Nvim will look up the terminal type in a compiled-in
-mini-database of terminfo entries for "xterm", "putty", "screen", "tmux",
-"rxvt", "iterm", "interix", "linux", "st", "vte", "gnome", and "ansi".
+found in that database, Nvim will use a compiled-in mini-database of terminfo
+entries for "xterm", "putty", "screen", "tmux", "rxvt", "iterm", "interix",
+"linux", "st", "vte", "gnome", and "ansi".
 
 The lookup matches the initial portion of the terminal type, so (for example)
 "putty-256color" and "putty" will both be mapped to the built-in "putty"
@@ -87,8 +73,8 @@ supplying an external one with entries for the terminal type.
 
 Settings depending on terminal			*term-dependent-settings*
 
-If you want to set options or mappings, depending on the terminal name, you
-can do this best in your init.vim.  Example: >
+If you want to set terminal-dependent options or mappings, you can do this in
+your init.vim.  Example: >
 
     if $TERM =~ '^\(rxvt\|screen\|interix\|putty\)\(-.*\)\?$'
         set notermguicolors
@@ -127,62 +113,49 @@ variable, set by genuine Xterm, that it looks for is not automatically
 replicated over an SSH login session.
 
 					*256-color* *terminfo-colors* *termcap-colors*
-Nvim can make use of 256-colour terminals and tries to do so whereever it can.
+Nvim uses 256 colours by default, ignoring |terminfo| for most terminal types,
+including "linux" (whose virtual terminals have had 256-colour support since
+4.8) and anything claiming to be "xterm".  Also when $COLORTERM or $TERM
+contain the string "256".
 
-If the |terminfo| description of the terminal says that it supports fewer
-colours, Nvim will override this for many terminal types, including "linux"
-(whose virtual terminals have had 256-colour support since version 4.8) and
-anything (even if falsely) claiming to be "xterm".  It will also set 256
-colours when the COLORTERM or TERM environment variables contain the string
-"256" somewhere.
-
-Nvim similarly assumes that any terminal emulator that sets the COLORTERM
-environment variable at all, to anything, is capable of at least 16-colour
-operation; and it will override |terminfo| saying that it has fewer colours
-available.
+Nvim similarly assumes that any terminal emulator that sets $COLORTERM to any
+value, is capable of at least 16-colour operation.
 
 						*true-color* *xterm-true-color*
-Nvim supports using true (24-bit) colours in the terminal, on terminals that
-support it.  It uses the same |terminfo| extensions that were proposed by
-Rüdiger Sonderfeld in 2013 for this: "setrgbf" and "setrgbb".  If your
-terminfo definition specifies these, then nothing more is required.
-
-If your terminfo definition is missing them, then Nvim will decide whether to
-add them to your terminfo definition, using the ISO 8613-6:1994/ITU T.416:1993
-control sequences for setting RGB colours, but modified to use semicolons
-instead of colons unless the terminal is known to follow the standard.
-(Semicolons cause ambiguities that the standard avoided by specifying colons
-as a sub-parameter delimiter.  A historical misunderstanding meant that many
-terminal emulators ended up using semicolons for many years, though.)
-
-A new convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension.
-If your terminal's terminfo definition has this flag, Nvim will add
-constructed "setrgbf" and "setrgbb" capabilities as if they had been in the
-terminfo definition.
-
-If your terminal's terminfo definition does not (yet) have this flag, Nvim
-will fall back to looking at the TERM and other environment variables.  It
-will add constructed "setrgbf" and "setrgbb" capabilities in the case of the
-the "rxvt", "linux", "st", "tmux", and "iterm" terminal types, or when
-Konsole, genuine Xterm, a libvte terminal emulator version 0.36 or later, or a
-terminal emulator that sets the COLORTERM environment variable to "truecolor"
-is detected.
+Nvim emits true (24-bit) colours in the terminal, if 'termguicolors' is set.
+
+It uses the "setrgbf" and "setrgbb" |terminfo| extensions (proposed by Rüdiger
+Sonderfeld in 2013). If your terminfo definition is missing them, then Nvim
+will decide whether to add them to your terminfo definition, using the ISO
+8613-6:1994/ITU T.416:1993 control sequences for setting RGB colours (but
+modified to use semicolons instead of colons unless the terminal is known to
+follow the standard).
+
+Another convention, pioneered in 2016 by tmux, is the "Tc" terminfo extension.
+If terminfo has this flag, Nvim will add constructed "setrgbf" and "setrgbb"
+capabilities as if they had been in the terminfo definition.
+
+If terminfo does not (yet) have this flag, Nvim will fall back to $TERM and
+other environment variables.  It will add constructed "setrgbf" and "setrgbb"
+capabilities in the case of the the "rxvt", "linux", "st", "tmux", and "iterm"
+terminal types, or when Konsole, genuine Xterm, a libvte terminal emulator
+version 0.36 or later, or a terminal emulator that sets the COLORTERM
+environment variable to "truecolor" is detected.
 
 							*xterm-resize*
 Nvim can resize the terminal display on some terminals that implement an
-extension pioneered by the dtterm program.  |terminfo| does not have a flag
-for this extension.  So Nvim simply assumes that (all) "dtterm", "xterm",
-"teraterm", "rxvt" terminal types, and Konsole, are capable of this.
+extension pioneered by dtterm.  |terminfo| does not have a flag for this
+extension.  So Nvim simply assumes that (all) "dtterm", "xterm", "teraterm",
+"rxvt" terminal types, and Konsole, are capable of this.
 
-			*cursor-shape* *terminfo-cursor-shape* *termcap-cursor-shape*
+			                                  *tui-cursor-shape* 
 Nvim will adjust the shape of the cursor from a block to a line when in insert
 mode (or as specified by the 'guicursor' option), on terminals that support
 it.  It uses the same |terminfo| extensions that were pioneered by tmux for
-this: "Ss" and "Se".  If your terminfo definition specifies these, as some
-(such as those based upon "xterm+tmux") do, then nothing more is required.
+this: "Ss" and "Se".
 
 If your terminfo definition is missing them, then Nvim will decide whether to
-add them to your terminfo definition, by looking at the TERM and other
+add them to your terminfo definition, by looking at $TERM and other
 environment variables.  For the "rxvt", "putty", "linux", "screen",
 "teraterm", and "iterm" terminal types, or when Konsole, a libvte-based
 terminal emulator, or genuine Xterm are detected, it will add constructed
@@ -195,19 +168,14 @@ receives from Nvim into whatever control sequence is appropriate for the
 terminal that it is outputting to.  It shares a common mechanism with Nvim, of
 using the "Ss" and "Se" capabilities from terminfo (for the output terminal)
 if they are present.  Unlike Nvim, if they are not present in terminfo you
-will have to add them by setting the tmux "terminal-overrides" setting in
-$HOME/.tmux.conf .
+must add them by setting "terminal-overrides" in ~/.tmux.conf .
 
 See the tmux(1) manual page for the details of how and what to do in the tmux
 configuration file.  It will look something like: >
-
-		set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
+	set -ga terminal-overrides '*:Ss=\E[%p1%d q:Se=\E[ q'
 <or (alas!) for Konsole specifically, something more complex like: >
-	set -ga terminal-overrides \
-        'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
-<but these are only rough examples that do not include all of the other stuff
-that occurs in that setting.
-
+	set -ga terminal-overrides 'xterm*:\E]50;CursorShape=%?%p1%{3}%<%t%{0}%e%{1}%;%d\007'
+<
 							*cs7-problem*
 Note: If the terminal settings are changed after running Vim, you might have
 an illegal combination of settings.  This has been reported on Solaris 2.5
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 42f273588a..9e063b1c04 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -79,8 +79,8 @@ Working intuitively and consistently is a major goal of Nvim. Examples:
   avoids features that cannot be provided on all platforms--instead that is
   delegated to external plugins/extensions.
 
-- Test-only globals and functions such as test_autochdir(), test_settime(),
-  etc., are not exposed (because they don't exist).
+- Vim's internal test functions (test_autochdir(), test_settime(), etc.) are
+  not exposed (nor implemented); instead Nvim has a robust API.
 
 ARCHITECTURE ~
 
@@ -89,6 +89,9 @@ stability and allows those plugins to work without blocking the editor. Even
 "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_py| and
 |if_ruby|) run out-of-process.
 
+Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
+features and bug fixes, and other projects benefit from improvements to libuv
+by Nvim developers.
 
 FEATURES ~
 
@@ -126,6 +129,7 @@ Commands:
 Functions:
   |dictwatcheradd()| notifies a callback whenever a |Dict| is modified
   |dictwatcherdel()|
+  |menu_get()|
   |msgpackdump()|, |msgpackparse()| provide msgpack de/serialization
 
 Events:
diff --git a/runtime/ftplugin/tutor.vim b/runtime/ftplugin/tutor.vim
index 1579753170..ec55472b78 100644
--- a/runtime/ftplugin/tutor.vim
+++ b/runtime/ftplugin/tutor.vim
@@ -19,27 +19,30 @@ setlocal noundofile
 setlocal keywordprg=:help
 setlocal iskeyword=@,-,_
 
-setlocal foldmethod=expr
+" The user will have to enable the folds himself, but we provide the foldexpr
+" function.
+setlocal foldmethod=manual
 setlocal foldexpr=tutor#TutorFolds()
-setlocal foldcolumn=1
 setlocal foldlevel=4
-setlocal nowrap
 
 setlocal statusline=%{toupper(expand('%:t:r'))}\ tutorial%=
 setlocal statusline+=%{tutor#InfoText()}
 
+" Load metadata if it exists: {{{1
+if filereadable(expand('%').'.json')
+    call tutor#LoadMetadata()
+endif
+
 " Mappings: {{{1
 
 call tutor#SetNormalMappings()
-call tutor#SetSampleTextMappings()
 
 " Checks: {{{1
 
 sign define tutorok text=✓ texthl=tutorOK
 sign define tutorbad text=✗ texthl=tutorX
 
-if  !exists('g:tutor_debug') || g:tutor_debug == 0
-    call tutor#PlaceXMarks()
-    autocmd! TextChanged <buffer> call tutor#OnTextChanged()
-    autocmd! TextChangedI <buffer> call tutor#OnTextChanged()
+if !exists('g:tutor_debug') || g:tutor_debug == 0
+    call tutor#ApplyMarks()
+    autocmd! TextChanged,TextChangedI <buffer> call tutor#ApplyMarksOnChanged()
 endif
diff --git a/runtime/syntax/tutor.vim b/runtime/syntax/tutor.vim
index bce9189660..fbf159582a 100644
--- a/runtime/syntax/tutor.vim
+++ b/runtime/syntax/tutor.vim
@@ -31,26 +31,20 @@ syn keyword tutorMarks TODO NOTE IMPORTANT TIP ATTENTION EXERCISE
 syn keyword tutorMarks todo note tip attention exercise
 syn keyword tutorMarks Todo Note Tip Excersise
 
-syn match tutorTextMark /\\\@<!--->/ conceal cchar=→
-syn region tutorSampleText start=/^\(--->\)\@=/ end=/$/ keepend contains=@SPELL
-syn match tutorSampleTextMark /^--->/ contained containedin=tutorSampleText conceal cchar=→
-syn match tutorSampleTextExpect /\}\@<! {expect:.\+}\s*$/ contained containedin=tutorSampleText conceal
-syn match tutorSampleTextExpect /|\@<! |expect:.\+|\s*$/ contained containedin=tutorSampleText conceal
-
 syn region tutorCodeblock matchgroup=Delimiter start=/^\~\{3}.*$/ end=/^\~\{3}/
 
-syn region tutorShell matchgroup=Delimiter start=/^\~\{3} sh\s*$/ end=/^\~\{3}/ keepend contains=@TUTORSHELL concealends
+syn region tutorShell matchgroup=Delimiter start=/^\~\{3} sh\s*$/ end=/^\~\{3}/ keepend contains=@TUTORSHELL
 syn match tutorShellPrompt /\(^\s*\)\@<=[$#]/ contained containedin=tutorShell
 
-syn region tutorInlineCode matchgroup=Delimiter start=/\\\@<!`/ end=/\\\@<!\(`{\@!\|`\s\)/ concealends
+syn region tutorInlineCode matchgroup=Delimiter start=/\\\@<!`/ end=/\\\@<!\(`{\@!\|`\s\)/
 
-syn region tutorCommand matchgroup=Delimiter start=/^\~\{3} cmd\( :\)\?\s*$/ end=/^\~\{3}/ keepend contains=@VIM concealends
-syn region tutorInlineCommand matchgroup=Delimiter start=/\\\@<!`\(.*{vim}\)\@=/ end=/\\\@<!`\({vim}\)\@=/ nextgroup=tutorInlineType contains=@VIM concealends
+syn region tutorCommand matchgroup=Delimiter start=/^\~\{3} cmd\( :\)\?\s*$/ end=/^\~\{3}/ keepend contains=@VIM
+syn region tutorInlineCommand matchgroup=Delimiter start=/\\\@<!`\(.*{vim}\)\@=/ end=/\\\@<!`\({vim}\)\@=/ nextgroup=tutorInlineType contains=@VIM
 
-syn region tutorNormal matchgroup=Delimiter start=/^\~\{3} norm\(al\?\)\?\s*$/ end=/^\~\{3}/ contains=@VIMNORMAL concealends
-syn region tutorInlineNormal matchgroup=Delimiter start=/\\\@<!`\(\S*{normal}\)\@=/ end=/\\\@<!`\({normal}\)\@=/ nextgroup=tutorInlineType contains=@VIMNORMAL concealends
+syn region tutorNormal matchgroup=Delimiter start=/^\~\{3} norm\(al\?\)\?\s*$/ end=/^\~\{3}/ contains=@VIMNORMAL
+syn region tutorInlineNormal matchgroup=Delimiter start=/\\\@<!`\(\S*{normal}\)\@=/ end=/\\\@<!`\({normal}\)\@=/ nextgroup=tutorInlineType contains=@VIMNORMAL
 
-syn match tutorInlineType /{\(normal\|vim\)}/ contained conceal
+syn match tutorInlineType /{\(normal\|vim\)}/ contained
 
 syn match tutorInlineOK /✓/
 syn match tutorInlineX /✗/
@@ -72,7 +66,7 @@ hi! tutorMarks cterm=bold gui=bold
 hi! tutorEmphasis gui=italic cterm=italic
 hi! tutorBold gui=bold cterm=bold
 
-hi! link tutorSampleText Special
+hi! link tutorExpect Special
 hi! tutorOK ctermfg=green guifg=#00ff88 cterm=bold gui=bold
 hi! tutorX ctermfg=red guifg=#ff2000  cterm=bold gui=bold
 hi! link tutorInlineOK tutorOK
diff --git a/runtime/tutor/en/vim-01-beginner.tutor b/runtime/tutor/en/vim-01-beginner.tutor
index 47d4ed06a1..fee7de21d2 100644
--- a/runtime/tutor/en/vim-01-beginner.tutor
+++ b/runtime/tutor/en/vim-01-beginner.tutor
@@ -18,10 +18,10 @@ be saved. Don't worry about messing things up; just remember that pressing
 [<Esc>](<Esc>) and then [u](u) will undo the latest change.
 
 This tutorial is interactive, and there are a few things you should know.
-Pressing [<Enter>](<Enter>) over text highlighted [like this](holy-grail) will take you to some relevant
-help (hopefully), and pressing K over any word will try to do so too. Sometimes
-you will be required to modify text like
---->  this here {expect:this here}
+Pressing [<Enter>](<Enter>) over text highlighted [like this](holy-grail) will take you to some
+relevant help (hopefully), and pressing K over any word will try to do so too.
+Sometimes you will be required to modify text like
+this here
 Once you have done the changes correctly, the ✗ sign at the left will change
 to ✓. I imagine you can already see how neat Vim can be ;)
 Other times, you'll be prompted to run a command (I'll explain this later):
@@ -99,7 +99,7 @@ NOTE:  [:q!](:q) <Enter>  discards any changes you made.  In a few lessons you
 
 4. Repeat steps 2 through 4 until the sentence is correct.
 
----> The ccow jumpedd ovverr thhe mooon. {expect:The cow jumped over the moon.}
+The ccow jumpedd ovverr thhe mooon.
 
 5. Now that the line is correct, go on to Lesson 1.4.
 
@@ -119,8 +119,8 @@ NOTE: As you go through this tutor, do not try to memorize, learn by usage.
   4. As each error is fixed press <Esc> to return to Normal mode.
      Repeat steps 2 through 4 to correct the sentence.
 
----> There is text misng this . {expect:There is some text missing from this line.}
----> There is some text missing from this line. {expect:There is some text missing from this line.}
+There is text misng this .
+There is some text missing from this line.
 
   5. When you are comfortable inserting text move to lesson 1.5.
 
@@ -138,10 +138,10 @@ NOTE: As you go through this tutor, do not try to memorize, learn by usage.
   4. Move the cursor to the second line marked ---> and repeat
      steps 2 and 3 to correct this sentence.
 
----> There is some text missing from th {expect:There is some text missing from this line.}
----> There is some text missing from this line. {expect:There is some text missing from this line.}
----> There is also some text miss {expect:There is also some text missing here.}
----> There is also some text missing here. {expect:There is also some text missing here.}
+There is some text missing from th
+There is some text missing from this line.
+There is also some text miss
+There is also some text missing here.
 
   5. When you are comfortable appending text move to lesson 1.6.
 
@@ -212,7 +212,7 @@ Now continue with Lesson 2.
 
   4. Type [d](d)[w](w)   to make the word disappear.
 
----> There are a some words fun that don't belong paper in this sentence. {expect:There are some words that don't belong in this sentence.}
+There are a some words fun that don't belong paper in this sentence.
 
   5. Repeat steps 3 and 4 until the sentence is correct and go to Lesson 2.2.
 
@@ -228,7 +228,7 @@ Now continue with Lesson 2.
 
   4. Type `d$`{normal} to delete to the end of the line.
 
----> Somebody typed the end of this line twice. end of this line twice. {expect:ANYTHING}
+Somebody typed the end of this line twice. end of this line twice.
 
   5. Move on to Lesson 2.3 to understand what is happening.
 
@@ -268,7 +268,7 @@ NOTE:  Pressing just the motion while in Normal mode without an operator will
 
   5. Repeat steps 2 and 3 with different numbers.
 
----> This is just a line with words you can move around in. {expect:ANYTHING}
+This is just a line with words you can move around in.
 
   6. Move on to Lesson 2.5.
 
@@ -287,7 +287,7 @@ insert a count before the motion to delete more:
   3. Repeat steps 1 and 2 with a different count to delete the consecutive
      UPPER CASE words with one command
 
----> this ABC DE line FGHI JK LMN OP of words is Q RS TUV cleaned up. {expect:this line of words is cleaned up.}
+this ABC DE line FGHI JK LMN OP of words is Q RS TUV cleaned up.
 
 # Lesson 2.6: OPERATING ON LINES
 
@@ -301,13 +301,13 @@ insert a count before the motion to delete more:
   3. Now move to the fourth line.
   4. Type `2dd`{normal} to delete two lines.
 
---->  1)  Roses are red, {expect:ANYTHING}
---->  2)  Mud is fun, {expect:ANYTHING}
---->  3)  Violets are blue, {expect:ANYTHING}
---->  4)  I have a car, {expect:ANYTHING}
---->  5)  Clocks tell time, {expect:ANYTHING}
---->  6)  Sugar is sweet {expect:ANYTHING}
---->  7)  And so are you. {expect:ANYTHING}
+1)  Roses are red,
+2)  Mud is fun,
+3)  Violets are blue,
+4)  I have a car,
+5)  Clocks tell time,
+6)  Sugar is sweet
+7)  And so are you.
 
 # Lesson 2.7: THE UNDO COMMAND
 
@@ -322,7 +322,7 @@ insert a count before the motion to delete more:
   6. Now type  `u`{normal}  a few times to undo the  U  and preceding commands.
   7. Now type  `<Ctrl-r>`{normal}  a few times to redo the commands (undo the undo's).
 
----> Fiix the errors oon thhis line and reeplace them witth undo. {expect:Fix the errors on this line and replace them with undo.}
+Fiix the errors oon thhis line and reeplace them witth undo.
 
   8. These are very useful commands.  Now move on to the Lesson 2 Summary.
 
@@ -362,10 +362,10 @@ insert a count before the motion to delete more:
 
   5. Repeat steps 2 through 4 to put all the lines in correct order.
 
----> d) Can you learn too? {expect:ANYTHING}
----> b) Violets are blue, {expect:ANYTHING}
----> c) Intelligence is learned, {expect:ANYTHING}
----> a) Roses are red, {expect:ANYTHING}
+d) Can you learn too?
+b) Violets are blue,
+c) Intelligence is learned,
+a) Roses are red,
 
 # Lesson 3.2: THE REPLACE COMMAND
 
@@ -379,8 +379,8 @@ insert a count before the motion to delete more:
 
   4. Repeat steps 2 and 3 until the first line is equal to the second one.
 
----> Whan this lime was tuoed in, someone presswd some wrojg keys! {expect:When this line was typed in, someone pressed some wrong keys!}
----> When this line was typed in, someone pressed some wrong keys! {expect:When this line was typed in, someone pressed some wrong keys!}
+Whan this lime was tuoed in, someone presswd some wrojg keys!
+When this line was typed in, someone pressed some wrong keys!
 
   5. Now move on to Lesson 3.3.
 
@@ -400,8 +400,8 @@ NOTE: Remember that you should be learning by doing, not memorization.
 
   5. Repeat steps 3 and 4 until the first sentence is the same as the second.
 
----> This lubw has a few wptfd that mrrf changing usf the change operator. {expect:This line has a few words that need changing using the change operator.}
----> This line has a few words that need changing using the change operator. {expect:This line has a few words that need changing using the change operator.}
+This lubw has a few wptfd that mrrf changing usf the change operator.
+This line has a few words that need changing using the change operator.
 
 Notice that [c](c)e deletes the word and places you in Insert mode.
 
@@ -421,8 +421,8 @@ Notice that [c](c)e deletes the word and places you in Insert mode.
 
   5. Type `c$`{normal} and type the rest of the line like the second and press `<Esc>`{normal}.
 
----> The end of this line needs some help to make it like the second. {expect:The end of this line needs to be corrected using the  c$  command.}
----> The end of this line needs to be corrected using the  c$  command. {expect:The end of this line needs to be corrected using the  c$  command.}
+The end of this line needs some help to make it like the second.
+The end of this line needs to be corrected using the  c$  command.
 
 NOTE:  You can use the Backspace key to correct mistakes while typing.
 
@@ -484,7 +484,7 @@ NOTE:  You may see the cursor position in the lower right corner of the screen
   5. To go back to where you came from press  `<Ctrl-o>`{normal}  (Keep Ctrl down while
      pressing the letter o).  Repeat to go back further.  `<Ctrl-i>`{normal} goes forward.
 
---->  "errroor" is not the way to spell error;  errroor is an error. {expect:ANYTHING}
+"errroor" is not the way to spell error;  errroor is an error.
 
 NOTE: When the search reaches the end of the file it will continue at the
       start, unless the ['wrapscan']('wrapscan') option has been reset.
@@ -503,7 +503,7 @@ NOTE: When the search reaches the end of the file it will continue at the
 
   5. Move the cursor to another (,),[,],{ or } and see what `%`{normal} does.
 
----> This ( is a test line with ('s, ['s ] and {'s } in it. )) {expect:ANYTHING}
+This ( is a test line with ('s, ['s ] and {'s } in it. ))
 
 NOTE: This is very useful in debugging a program with unmatched parentheses!
 
@@ -528,7 +528,7 @@ NOTE: This is very useful in debugging a program with unmatched parentheses!
      Adding the g [flag](:s_flags) means to substitute globally in the line, change
      all occurrences of "thee" in the line.
 
----> thee best time to see thee flowers is in thee spring. {expect:the best time to see the flowers is in the spring.}
+thee best time to see thee flowers is in thee spring.
 
   4. To change every occurrence of a character string between two lines, type
 ~~~ cmd
@@ -719,12 +719,12 @@ NOTE:  You can also read the output of an external command.  For example,
 
   3. Now type some text and press `<Esc>`{normal} to exit Insert mode.
 
----> After typing  o  the cursor is placed on the open line in Insert mode. {expect:ANYTHING}
+After typing  o  the cursor is placed on the open line in Insert mode.
 
   4. To open up a line ABOVE the cursor, simply type a [capital O](O), rather
      than a lowercase `o`{normal}.  Try this on the line below.
 
----> Open up a line above this by typing O while the cursor is on this line. {expect:ANYTHING}
+Open up a line above this by typing O while the cursor is on this line.
 
 # Lesson 6.2: THE APPEND COMMAND
 
@@ -741,8 +741,8 @@ NOTE:  You can also read the output of an external command.  For example,
 
   5. Use `e`{normal} to move to the next incomplete word and repeat steps 3 and 4.
 
----> This li will allow you to pract appendi text to a line. {expect:This line will allow you to practice appending text to a line.}
----> This line will allow you to practice appending text to a line. {expect:This line will allow you to practice appending text to a line.}
+This li will allow you to pract appendi text to a line.
+This line will allow you to practice appending text to a line.
 
 NOTE:  [a](a), [i](i) and [A](A) all go to the same Insert mode, the only difference is where
        the characters are inserted.
@@ -762,8 +762,8 @@ NOTE:  [a](a), [i](i) and [A](A) all go to the same Insert mode, the only differ
 
   4. Repeat the steps to replace the remaining "xxx".
 
----> Adding 123 to xxx gives you xxx. {expect:Adding 123 to 456 gives you 579.}
----> Adding 123 to 456 gives you 579. {expect:Adding 123 to 456 gives you 579.}
+Adding 123 to xxx gives you xxx.
+Adding 123 to 456 gives you 579.
 
 NOTE:  Replace mode is like Insert mode, but every typed character deletes an
        existing character.
@@ -785,8 +785,8 @@ NOTE:  Replace mode is like Insert mode, but every typed character deletes an
   6. Use Visual mode to select " item.", yank it with `y`{normal}, move to the end of
      the next line with `j$`{normal} and put the text there with `p`{normal}.
 
----> a) this is the first item.
---->     b)  {expect:    b) this is the second item}
+a) this is the first item.
+    b) 
 
   NOTE: you can also use `y`{normal} as an operator; `yw`{normal} yanks one word.
 
@@ -947,8 +947,10 @@ There are many resources online to learn more about vim. Here's a bunch of them:
 - Vim Video-Tutorials by Derek Wyatt: http://derekwyatt.org/vim/tutorials/
 - *Learn Vimscript the Hard Way*: http://learnvimscriptthehardway.stevelosh.com/
 - *7 Habits of Effective Text Editing*: http://www.moolenaar.net/habits.html
+- *vim-galore*: https://github.com/mhinz/vim-galore
 
-If you prefer a book, *Practival Vim* by Drew Neil is recommended often.
+If you prefer a book, *Practical Vim* by Drew Neil is recommended often (the sequel, *Modern
+Vim*, includes material specific to nvim!).
 
 This tutorial was written by Michael C. Pierce and Robert K. Ware, Colorado
 School of Mines using ideas supplied by Charles Smith, Colorado State
diff --git a/runtime/tutor/en/vim-01-beginner.tutor.json b/runtime/tutor/en/vim-01-beginner.tutor.json
new file mode 100644
index 0000000000..3f55971a09
--- /dev/null
+++ b/runtime/tutor/en/vim-01-beginner.tutor.json
@@ -0,0 +1,45 @@
+{
+    "expect": {
+	"24": -1,
+	"102": "The cow jumped over the moon.",
+	"122": "There is some text missing from this line.",
+	"123": "There is some text missing from this line.",
+	"141": "There is some text missing from this line.",
+	"142": "There is some text missing from this line.",
+	"143": "There is also some text missing here.",
+	"144": "There is also some text missing here.",
+	"215": "There are some words that don't belong in this sentence.",
+	"231": "Somebody typed the end of this line twice.",
+	"271": -1,
+	"290": "this line of words is cleaned up.",
+	"304": -1,
+	"305": -1,
+	"306": -1,
+	"307": -1,
+	"308": -1,
+	"309": -1,
+	"310": -1,
+	"325": "Fix the errors on this line and replace them with undo.",
+	"365": -1,
+	"366": -1,
+	"367": -1,
+	"368": -1,
+	"382": "When this line was typed in, someone pressed some wrong keys!",
+	"383": "When this line was typed in, someone pressed some wrong keys!",
+	"403": "This line has a few words that need changing using the change operator.",
+    	"404": "This line has a few words that need changing using the change operator.",
+	"424": "The end of this line needs to be corrected using the  c$  command.",
+    	"425": "The end of this line needs to be corrected using the  c$  command.",
+	"487": -1,
+	"506": -1,
+	"531": "the best time to see the flowers is in the spring.",
+	"722": -1,
+	"727": -1,
+	"744": "This line will allow you to practice appending text to a line.",
+	"745": "This line will allow you to practice appending text to a line.",
+	"765": "Adding 123 to 456 gives you 579.",
+	"766": "Adding 123 to 456 gives you 579.",
+	"788": "a) this is the first item.",
+	"789": "    b) this is the second item."
+    }
+}
diff --git a/runtime/tutor/tutor.tutor b/runtime/tutor/tutor.tutor
index 1ad64a18ff..c937bd686a 100644
--- a/runtime/tutor/tutor.tutor
+++ b/runtime/tutor/tutor.tutor
@@ -60,27 +60,27 @@ is displayed like
 
 1. Format the line below so it becomes a lesson description:
 
----> This is text with important information {expect:This is text with **important information**}
----> This is text with **important information** {expect:This is text with **important information**}
+This is text with important information
+This is text with **important information**
 
 Note: Some words (e.g., NOTE, IMPORTANT, tip, ATTENTION, etc.) will also be
 highlighted. You don't need to mark them specially.
 
 2. Turn the line below into a TODO item:
 
----> Document '&variable' {expect:TODO: Document '&variable'}
----> TODO: Document '&variable' {expect:TODO: Document '&variable'}
+Document '&variable'
+TODO: Document '&variable'
 
 ### Headers *headers*
 
 3. Practice fixing the lines below:
 
----> This is a level 1 header {expect:# This is a level 1 header}
----> # This is a level 1 header {expect:# This is a level 1 header}
----> This is a level 3 header {expect:### This is a level 3 header}
----> ### This is a level 3 header {expect:### This is a level 3 header}
----> This is a header with a label {expect:# This is a header with a label {*label*}}
----> # This is a header with a label {*label*} {expect:# This is a header with a label {*label*}}
+This is a level 1 header
+# This is a level 1 header
+This is a level 3 header
+### This is a level 3 header
+This is a header with a label
+# This is a header with a label {*label*}
 
 4. Now, create a 4th level section here, and add a label like in the previous
 exercise:
@@ -105,8 +105,8 @@ If the target of a link matches a help topic, opening it will open it.
 
 5. Fix the following line:
 
----> A link to help for the 'breakindent' option {expect:A link to help for the ['breakindent']('breakindent') option}
----> A link to help for the ['breakindent']('breakindent') option {expect:A link to help for the ['breakindent']('breakindent') option}
+A link to help for the 'breakindent' option
+A link to help for the ['breakindent']('breakindent') option
 
 #### Anchor links
 
@@ -120,8 +120,8 @@ and are hidden by default. Links to them look like
 
 6. Add the appropiate link:
 
----> A link to the Links section {expect:A link to the [Links](*links*) section}
----> A link to the [Links](*links*) section {expect:A link to the [Links](*links*) section}
+A link to the Links section
+A link to the [Links](*links*) section
 
 7. Now, create a link to the section you created on exercise 4
    above.
@@ -136,8 +136,8 @@ You can also have links to other tutorials. For this, you'll write the anchor in
 
 7. Create a link to this tutorial:
 
----> A link to the vim-tutor-mode tutorial {expect:A link to [the vim-tutor-mode tutorial](@tutor:tutor)}
----> A link to [the vim-tutor-mode tutorial](@tutor:tutor) {expect:A link to [the vim-tutor-mode tutorial](@tutor:tutor)}
+A link to the vim-tutor-mode tutorial
+A link to [the vim-tutor-mode tutorial](@tutor:tutor)
 
 ### Codeblocks *codeblocks*
 
@@ -154,13 +154,13 @@ echom "hello"
 
 8. Copy the viml section below
 
---->  {expect:~~~ viml}
---->  {expect:echom "the value of &number is".string(&number)}
---->  {expect:~~~}
 
----> ~~~ viml {expect:~~~ viml}
----> echom "the value of &number is".string(&number) {expect:echom "the value of &number is".string(&number)}
----> ~~~ {expect:~~~}
+
+
+
+~~~ viml
+echom 'the value of &number is'.string(&number)
+~~~
 
 You can inline viml code using "\`" and "\`{vim}":
 
@@ -185,13 +185,13 @@ Note: you can also write `norm` or `normal`.
 
 9. Copy the normal section below
 
---->  {expect:~~~ normal}
---->  {expect:d2w}
---->  {expect:~~~}
 
----> ~~~ normal {expect:~~~ normal}
----> d2w {expect:d2w}
----> ~~~ {expect:~~~}
+
+
+
+~~~ normal
+d2w
+~~~
 
 You can also inline normal commands by using "\`" and "\`{normal}":
 
@@ -203,10 +203,11 @@ is displayed:
 
 10. Complete the line as shown
 
----> d {expect:«d2w»}
----> «d2w» {expect:«d2w»}
+d
+`d2w`{normal}
 
-Commands to run in the system shell can be highlighted by indenting a line starting with "$".
+Commands to run in the system shell can be highlighted by indenting a line
+starting with "$".
 
 ~~~ sh
     $ vim --version
@@ -215,45 +216,32 @@ Commands to run in the system shell can be highlighted by indenting a line start
 ## INTERACTIVE ELEMENTS *interactive*
 
 As visible in this very document, vim-tutor-mode includes some interactive
-elements, to provide feedback to the user about his progress. These elements
-all have the syntax
-
-    \---> TEXT {CLAUSE}
-
-where \---> must start at the beginning of the line. If TEXT satisfies CLAUSE,
-a ✓ sign will appear to the left. A ✗ sign is displayed otherwise. The CLAUSE
-itself is hidden unless debug mode is set or ['conceallevel']('conceallevel')
-is 2.
+elements to provide feedback to the user about his progress. If the text in
+these elements satisfies some set condition, a ✓ sign will appear in the gutter
+to the left. Otherwise, a ✗ sign is displayed.
 
 ### expect *expect*
 
-The basic clause is "expect", which is satisfied if TEXT is the same as the
-content of the clause. For example
-
-    \---> TEXT {expect:TEXT}
-
-is satisfied, but
-
-    \---> OTHER TEXT {expect:TEXT}
-
-is not.
+"expect" lines check that the contents of the line are identical to some preset text
+(like in the exercises above).
 
-13. Make both lines the same:
+These elements are specified in separate JSON files like this
 
----> this is not right {expect:---> this is right} |expect:---> this is right {expect:---> this is right}|
----> ---> this is right {expect:---> this is right} |expect:---> this is right {expect:---> this is right}|
-
-
-If the content of a expect clause is ANYTHING, no checks will be performed. This is
-useful to create a line that is highlighted you want the user to play with.
-
-    \---> TEXT {expect:ANYTHING}
-
-is displayed
+~~~ json
+{
+    "expect": {
+	"1": "This is how this line should look.",
+	"2": "This is how this line should look.",
+	"3": -1
+    }
+}
+~~~
 
----> this is free text {expect:ANYTHING}
+These files contain an "expect" dictionary, for which the keys are line numbers and 
+the values are the expected text. A value of -1 means that the condition for the line
+will always be satisfied, no matter what (this is useful for letting the user play a bit).
 
-14. Turn the line below into free text:
+This is an "expect" line that is always satisfied. Try changing it.
 
----> this is some text |expect:---> this is some text {expect:ANYTHING}|
----> ---> this is some text {expect:ANYTHING} |expect:---> this is some text {expect:ANYTHING}|
+These files conventionally have the same name as the tutorial document with the `.json`
+extension appended (for a full example, see the file that corresponds to this tutorial).
diff --git a/runtime/tutor/tutor.tutor.json b/runtime/tutor/tutor.tutor.json
new file mode 100644
index 0000000000..bf3eae8586
--- /dev/null
+++ b/runtime/tutor/tutor.tutor.json
@@ -0,0 +1,35 @@
+{
+    "expect": {
+	"63": "This is text with **important information**",
+	"64": "This is text with **important information**",
+	"71": "Document '&variable'",
+	"72": "Document '&variable'",
+	"78": "# This is a level 1 header",
+	"79": "# This is a level 1 header",
+    	"80": "### This is a level 3 header",
+	"81": "### This is a level 3 header",
+    	"82": "# This is a header with a label {*label*}",
+	"83": "# This is a header with a label {*label*}",
+	"108": "A link to help for the ['breakindent']('breakindent') option",
+	"109": "A link to help for the ['breakindent']('breakindent') option",
+	"123": "A link to the [Links](*links*) section",
+	"124": "A link to the [Links](*links*) section",
+	"139": "A link to [the vim-tutor-mode tutorial](@tutor:tutor)",
+    	"140": "A link to [the vim-tutor-mode tutorial](@tutor:tutor)",
+	"157": "~~~ viml",
+	"158": "echom 'the value of &number is'.string(&number)",
+	"159": "~~~",
+	"161": "~~~ viml",
+	"162": "echom 'the value of &number is'.string(&number)",
+	"163": "~~~",
+	"188": "~~~ normal",
+	"189": "d2w",
+	"190": "~~~",
+	"192": "~~~ normal",
+	"193": "d2w",
+	"194": "~~~",
+	"206": "`d2w`{normal}",
+	"207": "`d2w`{normal}",
+	"244": -1
+    }
+}