Merge #4923 from justinmk/doc

doc: cleanup

26 files changed, 653 insertions, 1189 deletions

diff --git a/runtime/CMakeLists.txt b/runtime/CMakeLists.txt
index 4dbd193dab..a30bae388d 100644
--- a/runtime/CMakeLists.txt
+++ b/runtime/CMakeLists.txt
@@ -26,23 +26,15 @@ foreach(DF ${DOCFILES})
   list(APPEND BUILDDOCFILES ${GENERATED_RUNTIME_DIR}/doc/${F})
 endforeach()
 
-add_custom_command(OUTPUT copy_docfiles
-    COMMAND ${CMAKE_COMMAND} -E copy_directory
-    ${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
-)
-
 add_custom_target(helptags
+  COMMAND ${CMAKE_COMMAND} -E remove_directory ${GENERATED_RUNTIME_DIR}/doc
+  COMMAND ${CMAKE_COMMAND} -E copy_directory
+    ${PROJECT_SOURCE_DIR}/runtime/doc ${GENERATED_RUNTIME_DIR}/doc
   COMMAND "${PROJECT_BINARY_DIR}/bin/nvim"
-    -u NONE
-    -i NONE
-    -e
-    --headless
-    -c "helptags ++t ."
-    -c quit
+    -u NONE -i NONE -e --headless -c "helptags ++t doc" -c quit
   DEPENDS
-    copy_docfiles
     nvim
-  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}/doc"
+  WORKING_DIRECTORY "${GENERATED_RUNTIME_DIR}"
 )
 
 add_custom_command(OUTPUT ${GENERATED_HELP_TAGS}
diff --git a/runtime/autoload/provider/clipboard.vim b/runtime/autoload/provider/clipboard.vim
index 2272519dfd..77bc8c781d 100644
--- a/runtime/autoload/provider/clipboard.vim
+++ b/runtime/autoload/provider/clipboard.vim
@@ -58,7 +58,7 @@ elseif executable('doitclient')
   let s:copy['*'] = s:copy['+']
   let s:paste['*'] = s:paste['+']
 else
-  echom 'clipboard: No clipboard tool available. See :help nvim-clipboard'
+  echom 'clipboard: No clipboard tool available. See :help clipboard'
   finish
 endif
 
diff --git a/runtime/autoload/provider/python.vim b/runtime/autoload/provider/python.vim
index cb9d5c5296..b99a046375 100644
--- a/runtime/autoload/provider/python.vim
+++ b/runtime/autoload/provider/python.vim
@@ -1,5 +1,5 @@
 " The Python provider uses a Python host to emulate an environment for running
-" python-vim plugins. See ":help nvim-provider" for more information.
+" python-vim plugins. See ":help provider".
 "
 " Associating the plugin with the Python host is the first step because plugins
 " will be passed as command-line arguments
diff --git a/runtime/autoload/provider/python3.vim b/runtime/autoload/provider/python3.vim
index f4a751e7a2..4f47a03a9b 100644
--- a/runtime/autoload/provider/python3.vim
+++ b/runtime/autoload/provider/python3.vim
@@ -1,5 +1,5 @@
 " The Python3 provider uses a Python3 host to emulate an environment for running
-" python3 plugins. See ":help nvim-provider" for more information.
+" python3 plugins. See ":help provider".
 "
 " Associating the plugin with the Python3 host is the first step because
 " plugins will be passed as command-line arguments
diff --git a/runtime/autoload/provider/pythonx.vim b/runtime/autoload/provider/pythonx.vim
index c3256e8308..0ebf00112f 100644
--- a/runtime/autoload/provider/pythonx.vim
+++ b/runtime/autoload/provider/pythonx.vim
@@ -106,7 +106,7 @@ function! s:check_interpreter(prog, major_ver, skip) abort
 
   if v:shell_error == 2
     return [0, prog_path . ' does not have the neovim module installed. '
-          \ . 'See ":help nvim-python".']
+          \ . 'See ":help provider-python".']
   elseif v:shell_error == 127
     " This can happen with pyenv's shims.
     return [0, prog_path . ' does not exist: ' . prog_ver]
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ca79465e0d..bdeca367b1 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1,31 +1,32 @@
-*api.txt*    For Nvim.							 {Nvim}
+*api.txt*		 						{Nvim}
 
 
 		 NVIM REFERENCE MANUAL    by Thiago de Arruda
 
-The C API of Nvim						     *nvim-api*
 
-1. Introduction			|nvim-api-intro|
-2. API Types			|nvim-api-types|
-3. API metadata			|nvim-api-metadata|
-4. Buffer highlighting		|nvim-api-highlights|
+C API for Nvim							   *API* *api*
+
+1. Introduction			|api-intro|
+2. API Types			|api-types|
+3. API metadata			|api-metadata|
+4. Buffer highlighting		|api-highlights|
 
 ==============================================================================
-1. Introduction			*nvim-api-intro*
+1. Introduction							   *api-intro*
 
-Nvim defines a C API as the primary way for external code to interact with
-the NVim core. In the present version of Nvim the API is primarily used by
-external processes to interact with Nvim using the msgpack-rpc protocol, see
-|msgpack-rpc|. The API will also be used from vimscript to access new Nvim core
-features, but this is not implemented yet. Later on, Nvim might be embeddable
-in C applications as libnvim, and the application will then control the
-embedded instance by calling the C API directly.
+Nvim exposes a public API for external code to interact with the Nvim core. In
+the present version of Nvim the API is primarily used by external processes to
+interact with Nvim using the msgpack-rpc protocol, see |msgpack-rpc|. The API
+will also be used from vimscript to access new Nvim core features, but this is
+not implemented yet. Later on, Nvim might be embeddable in C applications as
+libnvim, and the application will then control the embedded instance by
+calling the C API directly.
 
 ==============================================================================
-2. API Types						       *nvim-api-types*
+2. API Types							   *api-types*
 
 Nvim's C API uses custom types for all functions. Some are just typedefs
-around C99 standard types, and some are Nvim defined data structures.
+around C99 standard types, and some are Nvim-defined data structures.
 
 Boolean				  -> bool
 Integer (signed 64-bit integer)	  -> int64_t
@@ -46,7 +47,7 @@ Window				  -> enum value kObjectTypeWindow
 Tabpage				  -> enum value kObjectTypeTabpage
 
 ==============================================================================
-3. API metadata						    *nvim-api-metadata*
+3. API metadata							 *api-metadata*
 
 Nvim exposes metadata about the API as a Dictionary with the following keys:
 
@@ -54,11 +55,11 @@ functions  	calling signature of the API functions
 types		The custom handle types defined by Nvim
 error_types	The possible kinds of errors an API function can exit with.
 
-This metadata is mostly useful for external programs accessing the api over
-msgpack-api, see |msgpack-rpc-api|.
+This metadata is mostly useful for external programs accessing the API via
+RPC, see |rpc-api|.
 
 ==============================================================================
-4. Buffer highlighting					  *nvim-api-highlights*
+4. Buffer highlighting					       *api-highlights*
 
 Nvim allows plugins to add position-based highlights to buffers. This is
 similar to |matchaddpos()| but with some key differences. The added highlights
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index 25ae94f784..6641732679 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -912,8 +912,7 @@ TermClose			When a terminal buffer ends.
 						 {Nvim} *TermOpen*
 TermOpen			When a terminal buffer is starting.  This can
 				be used to configure the terminal emulator by
-				setting buffer variables.
-				See |nvim-terminal-emulator| for details.
+				setting buffer variables. |terminal-emulator|
 							*TermResponse*
 TermResponse			After the response to |t_RV| is received from
 				the terminal.  The value of |v:termresponse|
diff --git a/runtime/doc/change.txt b/runtime/doc/change.txt
index c3f1b69da7..4565cdf63e 100644
--- a/runtime/doc/change.txt
+++ b/runtime/doc/change.txt
@@ -1250,7 +1250,7 @@ register.
 Use these registers for storing and retrieving the selected text for the GUI.
 See |quotestar| and |quoteplus|.  When the clipboard is not available or not
 working, the unnamed register is used instead.  For Unix systems and Mac OS X,
-see |nvim-clipboard|.
+see |primary-selection|.
 
 9. Black hole register "_				*quote_*
 When writing to this register, nothing happens.  This can be used to delete
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 8881845fdd..1b77d87aac 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -1,23 +1,19 @@
-*develop.txt*   For Vim version 7.4.  Last change: 2016 Jan 31
+*develop.txt*
 
 
-		  VIM REFERENCE MANUAL    by Bram Moolenaar
+                            NVIM REFERENCE MANUAL
 
 
-Development of Vim.					*development*
-
-This text is important for those who want to be involved in further developing
-Vim.
+Development of Nvim.					*development*
 
 1. Design goals		|design-goals|
 2. Design decisions	|design-decisions|
 
-See the file "src/nvim/README.md" for a high-level overview of the source
-code.
+Nvim is open source software.  Everybody is encouraged to contribute.
+    https://github.com/neovim/neovim/blob/master/CONTRIBUTING.md
 
-Vim is open source software.  Everybody is encouraged to contribute to help
-improving Vim.  For sending patches a context diff "diff -c" is preferred.
-Also see http://vim.wikia.com/wiki/How_to_make_and_submit_a_patch.
+See src/nvim/README.md for a high-level overview of the source code:
+    https://github.com/neovim/neovim/blob/master/src/nvim/README.md
 
 ==============================================================================
 1. Design goals						*design-goals*
@@ -28,7 +24,7 @@ Note that quite a few items are contradicting.  This is intentional.  A
 balance must be found between them.
 
 
-VIM IS... IMPROVED					*design-improved*
+NVIM IS... IMPROVED					*design-improved*
 
 The IMproved bits of Vim should make it a better Vi, without becoming a
 completely different editor.  Extensions are done with a "Vi spirit".
@@ -49,7 +45,7 @@ completely different editor.  Extensions are done with a "Vi spirit".
   implement and (3) someone actually implementing it.
 
 
-VIM IS... MULTI PLATFORM				*design-multi-platform*
+NVIM IS... MULTI PLATFORM				*design-multi-platform*
 
 Vim tries to help as many users on as many platforms as possible.
 - Support many kinds of terminals.  The minimal demands are cursor positioning
@@ -68,7 +64,7 @@ Vim tries to help as many users on as many platforms as possible.
   contradicts the previous item, these two must be balanced.]
 
 
-VIM IS... WELL DOCUMENTED				*design-documented*
+NVIM IS... WELL DOCUMENTED				*design-documented*
 
 - A feature that isn't documented is a useless feature.  A patch for a new
   feature must include the documentation.
@@ -76,9 +72,14 @@ VIM IS... WELL DOCUMENTED				*design-documented*
   recommended.
 - Don't make the text unnecessarily long.  Less documentation means that an
   item is easier to find.
+- Do not prefix doc-tags with "nvim-". Use |vim_diff.txt| to document
+  differences from Vim. The {Nvim} annotation is also available
+  to mark a specific feature. No other distinction is necessary.
+- If a feature is removed, delete its doc entry and move its tag to
+  |vim_diff.txt|.
 
 
-VIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*
+NVIM IS... HIGH SPEED AND SMALL IN SIZE			*design-speed-size*
 
 Using Vim must not be a big attack on system resources.  Keep it small and
 fast.
@@ -89,13 +90,11 @@ fast.
   possible.  Useful commands may take longer.
 - Don't forget that some people use Vim over a slow connection.  Minimize the
   communication overhead.
-- Items that add considerably to the size and are not used by many people
-  should be a feature that can be disabled.
 - Vim is a component among other components.  Don't turn it into a massive
   application, but have it work well together with other programs.
 
 
-VIM IS... MAINTAINABLE					*design-maintain*
+NVIM IS... MAINTAINABLE					*design-maintain*
 
 - The source code should not become a mess.  It should be reliable code.
 - Use comments in a useful way!  Quoting the function name and argument names
@@ -106,7 +105,7 @@ VIM IS... MAINTAINABLE					*design-maintain*
   knowledge spread to other parts of the code.
 
 
-VIM IS... FLEXIBLE					*design-flexible*
+NVIM IS... FLEXIBLE					*design-flexible*
 
 Vim should make it easy for users to work in their preferred styles rather
 than coercing its users into particular patterns of work.  This can be for
@@ -117,27 +116,15 @@ be used to adjust Vim to the desire of the user and its environment.
 
 NVIM IS... NOT						*design-not*
 
-Nvim is not an Operating System; instead it should be composed with other
-tools, or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does
-not attempt to include everything but the kitchen sink, but some people use it
-for plumbing."
+Nvim is not an operating system; instead it should be composed with other
+tools or hosted as a component. Marvim once said: "Unlike Emacs, Nvim does not
+include the kitchen sink... but you can use it for plumbing."
 
 
 ==============================================================================
 2. Design decisions					*design-decisions*
 
-Folding
-
-Several forms of folding should be possible for the same buffer.  For example,
-have one window that shows the text with function bodies folded, another
-window that shows a function body.
-
-Folding is a way to display the text.  It should not change the text itself.
-Therefore the folding has been implemented as a filter between the text stored
-in a buffer (buffer lines) and the text displayed in a window (logical lines).
-
-
-Naming the window
+Window
 
 The word "window" is commonly used for several things: A window on the screen,
 the xterm window, a window inside Vim to view a buffer.
@@ -153,110 +140,52 @@ window		View on a buffer.  There can be several windows in Vim,
 		fit in the shell.
 
 
-Spell checking						*develop-spell*
-
-When spell checking was going to be added to Vim a survey was done over the
-available spell checking libraries and programs.  Unfortunately, the result
-was that none of them provided sufficient capabilities to be used as the spell
-checking engine in Vim, for various reasons:
-
-- Missing support for multi-byte encodings.  At least UTF-8 must be supported,
-  so that more than one language can be used in the same file.
-  Doing on-the-fly conversion is not always possible (would require iconv
-  support).
-- For the programs and libraries: Using them as-is would require installing
-  them separately from Vim.  That's mostly not impossible, but a drawback.
-- Performance: A few tests showed that it's possible to check spelling on the
-  fly (while redrawing), just like syntax highlighting.  But the mechanisms
-  used by other code are much slower.  Myspell uses a hashtable, for example.
-  The affix compression that most spell checkers use makes it slower too.
-- For using an external program like aspell a communication mechanism would
-  have to be setup.  That's complicated to do in a portable way (Unix-only
-  would be relatively simple, but that's not good enough).  And performance
-  will become a problem (lots of process switching involved).
-- Missing support for words with non-word characters, such as "Etten-Leur" and
-  "et al.", would require marking the pieces of them OK, lowering the
-  reliability.
-- Missing support for regions or dialects.  Makes it difficult to accept
-  all English words and highlight non-Canadian words differently.
-- Missing support for rare words.  Many words are correct but hardly ever used
-  and could be a misspelled often-used word.
-- For making suggestions the speed is less important and requiring to install
-  another program or library would be acceptable.  But the word lists probably
-  differ, the suggestions may be wrong words.
-
-
-Spelling suggestions				*develop-spell-suggestions*
-
-For making suggestions there are two basic mechanisms:
-1. Try changing the bad word a little bit and check for a match with a good
-   word.  Or go through the list of good words, change them a little bit and
-   check for a match with the bad word.  The changes are deleting a character,
-   inserting a character, swapping two characters, etc.
-2. Perform soundfolding on both the bad word and the good words and then find
-   matches, possibly with a few changes like with the first mechanism.
-
-The first is good for finding typing mistakes.  After experimenting with
-hashtables and looking at solutions from other spell checkers the conclusion
-was that a trie (a kind of tree structure) is ideal for this.  Both for
-reducing memory use and being able to try sensible changes.  For example, when
-inserting a character only characters that lead to good words need to be
-tried.  Other mechanisms (with hashtables) need to try all possible letters at
-every position in the word.  Also, a hashtable has the requirement that word
-boundaries are identified separately, while a trie does not require this.
-That makes the mechanism a lot simpler.
-
-Soundfolding is useful when someone knows how the words sounds but doesn't
-know how it is spelled.  For example, the word "dictionary" might be written
-as "daktonerie".  The number of changes that the first method would need to
-try is very big, it's hard to find the good word that way.  After soundfolding
-the words become "tktnr" and "tkxnry", these differ by only two letters.
-
-To find words by their soundfolded equivalent (soundalike word) we need a list
-of all soundfolded words.  A few experiments have been done to find out what
-the best method is.  Alternatives:
-1. Do the sound folding on the fly when looking for suggestions.  This means
-   walking through the trie of good words, soundfolding each word and
-   checking how different it is from the bad word.  This is very efficient for
-   memory use, but takes a long time.  On a fast PC it takes a couple of
-   seconds for English, which can be acceptable for interactive use.  But for
-   some languages it takes more than ten seconds (e.g., German, Catalan),
-   which is unacceptable slow.  For batch processing (automatic corrections)
-   it's too slow for all languages.
-2. Use a trie for the soundfolded words, so that searching can be done just
-   like how it works without soundfolding.  This requires remembering a list
-   of good words for each soundfolded word.  This makes finding matches very
-   fast but requires quite a lot of memory, in the order of 1 to 10 Mbyte.
-   For some languages more than the original word list.
-3. Like the second alternative, but reduce the amount of memory by using affix
-   compression and store only the soundfolded basic word.  This is what Aspell
-   does.  Disadvantage is that affixes need to be stripped from the bad word
-   before soundfolding it, which means that mistakes at the start and/or end
-   of the word will cause the mechanism to fail.  Also, this becomes slow when
-   the bad word is quite different from the good word.
-
-The choice made is to use the second mechanism and use a separate file.  This
-way a user with sufficient memory can get very good suggestions while a user
-who is short of memory or just wants the spell checking and no suggestions
-doesn't use so much memory.
-
-
-Word frequency
-
-For sorting suggestions it helps to know which words are common.  In theory we
-could store a word frequency with the word in the dictionary.  However, this
-requires storing a count per word.  That degrades word tree compression a lot.
-And maintaining the word frequency for all languages will be a heavy task.
-Also, it would be nice to prefer words that are already in the text.  This way
-the words that appear in the specific text are preferred for suggestions.
-
-What has been implemented is to count words that have been seen during
-displaying.  A hashtable is used to quickly find the word count.  The count is
-initialized from words listed in COMMON items in the affix file, so that it
-also works when starting a new file.
-
-This isn't ideal, because the longer Vim is running the higher the counts
-become.  But in practice it is a noticeable improvement over not using the word
-count.
+Providers 							*dev-provider*
+
+A goal of Nvim is to allow extension of the editor without special knowledge
+in the core. But some Vim components are too tightly coupled; in those cases
+a "provider" hook is exposed.
+
+Consider two examples of integration with external systems that are
+implemented in Vim and are now decoupled from Nvim core as providers:
+
+1. In the Vim source code, clipboard logic accounts for more than 1k lines of
+   C source code (ui.c), to perform two tasks that are now accomplished with
+   shell commands such as xclip or pbcopy/pbpaste.
+
+2. Python scripting support: Vim has three files dedicated to embedding the
+   Python interpreter: if_python.c, if_python3.c and if_py_both.h. Together
+   these files sum about 9.5k lines of C source code. In contrast, Nvim Python
+   scripting is performed by an external host process implemented in ~2k lines
+   of Python.
+
+Ideally we could implement Python and clipboard integration in pure vimscript
+and without touching the C code. But this is infeasible without compromising
+backwards compatibility with Vim; that's where providers help.
+
+The provider framework helps call vimscript from C. It is composed of two
+functions in eval.c:
+
+- eval_call_provider(name, method, arguments): calls provider#(name)#Call
+  with the method and arguments.
+- eval_has_provider(name): Checks if a provider is implemented. Returns true
+  if the provider#(name)#Call function is implemented. Called by |has()|
+  (vimscript) to check if features are available.
+
+The provider#(name)#Call function implements integration with an external
+system, because shell commands and |RPC| clients are easier to work with in
+vimscript.
+
+For example, the Python provider is implemented by the
+autoload/provider/python.vim script; the provider#python#Call function is only
+defined if a valid external Python host is found. That works well with the
+`has('python')` expression (normally used by Python plugins) because if the
+Python host isn't installed then the plugin will "think" it is running in
+a Vim compiled without the |+python| feature.
+
+
+RPC API
+API client
+remote plugin
 
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index 71a7682f15..b89b68837e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1653,9 +1653,9 @@ v:scrollstart	String describing the script or function that caused the
 		hit-enter prompt.
 
 					*v:servername* *servername-variable*
+					*$NVIM_LISTEN_ADDRESS*
 v:servername	Default {Nvim} server address. Equivalent to
-		|$NVIM_LISTEN_ADDRESS| on startup, but may differ if the
-		latter is modified or unset. |serverstop()|
+		|$NVIM_LISTEN_ADDRESS| on startup. |serverstop()|
 		Read-only.
 
 		
@@ -2031,11 +2031,11 @@ resolve({filename})		String	get filename a shortcut points to
 reverse({list})		List	reverse {list} in-place
 round({expr})			Float	round off {expr}
 rpcnotify({channel}, {event}[, {args}...])
-				Sends a |msgpack-rpc| notification to {channel}
+				Sends an |RPC| notification to {channel}
 rpcrequest({channel}, {method}[, {args}...])
-				Sends a |msgpack-rpc| request to {channel}
-rpcstart({prog}[, {argv}])	Spawns {prog} and opens a |msgpack-rpc| channel
-rpcstop({channel})		Closes a |msgpack-rpc| {channel}
+				Sends an |RPC| request to {channel}
+rpcstart({prog}[, {argv}])	Spawns {prog} and opens an |RPC| channel
+rpcstop({channel})		Closes an |RPC| {channel}
 screenattr({row}, {col})	Number	attribute at screen position
 screenchar({row}, {col})	Number	character at screen position
 screencol()			Number	current cursor column
@@ -5526,31 +5526,31 @@ round({expr})							*round()*
 <			-5.0
 
 rpcnotify({channel}, {event}[, {args}...])		  {Nvim} *rpcnotify()*
-		Sends {event} to {channel} via |msgpack-rpc| and returns
-		immediately. If {channel} is 0, the event is broadcast to all
-		channels. Example: >
+		Sends {event} to {channel} via |RPC| and returns immediately.
+		If {channel} is 0, the event is broadcast to all channels.
+		Example: >
 			:au VimLeave call rpcnotify(0, "leaving")
 
 rpcrequest({channel}, {method}[, {args}...])		 {Nvim} *rpcrequest()*
 		Sends a request to {channel} to invoke {method} via
-		|msgpack-rpc| and blocks until a response is received.
+		|RPC| and blocks until a response is received.
 		Example: >
 			:let result = rpcrequest(rpc_chan, "func", 1, 2, 3)
 
 rpcstart({prog}[, {argv}])				   {Nvim} *rpcstart()*
 		Spawns {prog} as a job (optionally passing the list {argv}),
-		and opens a |msgpack-rpc| channel with the spawned process's
-		stdin/stdout. It returns:
-		  - The channel id on success, which is used by |rpcrequest()|,
+		and opens an |RPC| channel with the spawned process's
+		stdin/stdout. Returns:
+		  - channel id on success, which is used by |rpcrequest()|,
 		    |rpcnotify()| and |rpcstop()|
-		  - 0 on failure.
+		  - 0 on failure
 		Example: >
 			:let rpc_chan = rpcstart('prog', ['arg1', 'arg2'])
 
 rpcstop({channel})					    {Nvim} *rpcstop()*
-		Closes a |msgpack-rpc| {channel}, possibly created via
+		Closes an |RPC| {channel}, possibly created via
 		|rpcstart()|. Also closes channels created by connections to
-		|$NVIM_LISTEN_ADDRESS|.
+		|v:servername|.
 
 screenattr(row, col)						*screenattr()*
 		Like screenchar(), but return the attribute.  This is a rather
@@ -6841,7 +6841,7 @@ termopen({cmd}[, {opts}])			{Nvim} *termopen()*
 		and `$TERM` is set to "xterm-256color".
 		Returns the same values as |jobstart()|.
 
-		See |nvim-terminal-emulator| for more information.
+		See |terminal-emulator| for more information.
 
 tan({expr})						*tan()*
 		Return the tangent of {expr}, measured in radians, as a |Float|
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 8d97678af2..e2fb501ac5 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -395,9 +395,9 @@ You may make selections with the mouse (see |gui-mouse-select|), or by using
 Vim's Visual mode (see |v|).  If 'a' is present in 'guioptions', then
 whenever a selection is started (Visual or Select mode), or when the selection
 is changed, Vim becomes the owner of the windowing system's primary selection
-(on MS-Windows the |gui-clipboard| is used).
+(on MS-Windows the |clipboard| is used).
 
-							*clipboard*
+							*primary-selection*
 There is a special register for storing this selection, it is the "*
 register.  Nothing is put in here unless the information about what text is
 selected is about to change (e.g. with a left mouse click somewhere), or when
diff --git a/runtime/doc/gui_w32.txt b/runtime/doc/gui_w32.txt
deleted file mode 100644
index 228be9eab2..0000000000
--- a/runtime/doc/gui_w32.txt
+++ /dev/null
@@ -1,437 +0,0 @@
-*gui_w32.txt*   For Vim version 7.4.  Last change: 2014 Dec 20
-
-
-		  VIM REFERENCE MANUAL    by Bram Moolenaar
-
-
-Vim's Win32 Graphical User Interface			*gui-w32* *win32-gui*
-
-1. Starting the GUI		|gui-w32-start|
-2. Vim as default editor	|vim-default-editor|
-3. Using the clipboard		|gui-clipboard|
-4. Shell Commands		|gui-shell-win32|
-5. Special colors		|win32-colors|
-6. Windows dialogs & browsers	|gui-w32-dialogs|
-7. Command line arguments	|gui-w32-cmdargs|
-8. Various			|gui-w32-various|
-
-Other relevant documentation:
-|gui.txt|	For generic items of the GUI.
-|os_win32.txt| 	For Win32 specific items.
-
-==============================================================================
-1. Starting the GUI					*gui-w32-start*
-
-The Win32 GUI version of Vim will always start the GUI, no matter how you
-start it or what it's called.
-
-The GUI will always run in the Windows subsystem.  Mostly shells automatically
-return with a command prompt after starting gvim.  If not, you should use the
-"start" command: >
-	start gvim [options] file ..
-
-Note: All fonts (bold, italic) must be of the same size!!!  If you don't do
-this, text will disappear or mess up the display.  Vim does not check the font
-sizes.  It's the size in screen pixels that must be the same.  Note that some
-fonts that have the same point size don't have the same pixel size!
-Additionally, the positioning of the fonts must be the same (ascent and
-descent).
-
-The Win32 GUI has an extra menu item:  "Edit/Select Font".  It brings up the
-standard Windows font selector.
-
-Setting the menu height doesn't work for the Win32 GUI.
-
-							*gui-win32-maximized*
-If you want Vim to start with a maximized window, add this command to your
-vimrc or gvimrc file: >
-	au GUIEnter * simalt ~x
-<
-==============================================================================
-2. Vim as default editor				*vim-default-editor*
-
-To set Vim as the default editor for a file type:
-1. Start a Windows Explorer
-2. Choose View/Options -> File Types
-3. Select the path to gvim for every file type that you want to use it for.
-   (you can also use three spaces in the file type field, for files without an
-   extension).
-   In the "open" action, use: >
-	gvim "%1"
-<  The quotes are required for using file names with embedded spaces.
-   You can also use this: >
-	gvim "%L"
-<  This should avoid short (8.3 character) file names in some situations.  But
-   I'm not sure if this works everywhere.
-
-When you open a file in Vim by double clicking it, Vim changes to that
-file's directory.
-
-If you want Vim to start full-screen, use this for the Open action: >
-	gvim -c "simalt ~x" "%1"
-
-Another method, which also works when you put Vim in another directory (e.g.,
-when you have got a new version):
-1. select a file you want to use Vim with
-2. <Shift-F10>
-3. select "Open With..." menu entry
-4. click "Other..."
-5. browse to the (new) location of Vim and click "Open"
-6. make "Always Use this program..." checked
-7. <OK>
-
-						*send-to-menu* *sendto*
-You can also install Vim in the "Send To" menu:
-1. Start a Windows Explorer
-2. Navigate to your sendto directory:
-   Windows NT: %windir%\profiles\%user%\sendto (e.g.
-	       "c:\winnt\profiles\mattha\sendto").
-3. Right-click in the file pane and select New->Shortcut
-4. Follow the shortcut wizard, using the full path to VIM/GVIM.
-
-When you 'send a file to Vim', Vim changes to that file's directory.  Note,
-however, that any long directory names will appear in their short (MS-DOS)
-form.  This is a limitation of the Windows "Send To" mechanism.
-
-						*notepad*
-You could replace notepad.exe with gvim.exe, but that has a few side effects.
-Some programs rely on notepad arguments, which are not recognized by Vim.  For
-example "notepad -p" is used by some applications to p