feat(jobs): jobstart(…,{term=true}), deprecate termopen() #31343

Problem:
`termopen` has long been a superficial wrapper around `jobstart`, and
has no real purpose. Also, `vim.system` and `nvim_open_term` presumably
will replace all features of `jobstart` and `termopen`, so centralizing
the logic will help with that.

Solution:
- Introduce `eval/deprecated.c`, where all deprecated eval funcs will live.
- Introduce "term" flag of `jobstart`.
- Deprecate `termopen`.

10 files changed, 186 insertions, 207 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 95c8a6056f..c8e0dcd0c5 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2170,12 +2170,12 @@ nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
     This temporarily switches current buffer to "buffer". If the current
     window already shows "buffer", the window is not switched. If a window
     inside the current tabpage (including a float) already shows the buffer,
-    then one of these windows will be set as current window temporarily.
+    then one of those windows will be set as current window temporarily.
     Otherwise a temporary scratch window (called the "autocmd window" for
     historical reasons) will be used.
 
     This is useful e.g. to call Vimscript functions that only work with the
-    current buffer/window currently, like |termopen()|.
+    current buffer/window currently, like `jobstart(…, {'term': v:true})`.
 
     Attributes: ~
         Lua |vim.api| only
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 5f74080e0c..0e9c1c8512 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -5309,7 +5309,7 @@ jobresize({job}, {width}, {height})                                *jobresize()*
                   (`any`)
 
 jobstart({cmd} [, {opts}])                                          *jobstart()*
-		Note: Prefer |vim.system()| in Lua (unless using the `pty` option).
+		Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
 
 		Spawns {cmd} as a job.
 		If {cmd} is a List it runs directly (no 'shell').
@@ -5317,8 +5317,11 @@ jobstart({cmd} [, {opts}])                                          *jobstart()*
 		  call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}'])
 <		(See |shell-unquoting| for details.)
 
-		Example: >vim
-		  call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}})
+		Example: start a job and handle its output: >vim
+		  call jobstart(['nvim', '-h'], {'on_stdout':{j,d,e->append(line('.'),d)}})
+<
+		Example: start a job in a |terminal| connected to the current buffer: >vim
+		  call jobstart(['nvim', '-h'], {'term':v:true})
 <
 		Returns |job-id| on success, 0 on invalid arguments (or job
 		table is full), -1 if {cmd}[0] or 'shell' is not executable.
@@ -5383,6 +5386,10 @@ jobstart({cmd} [, {opts}])                                          *jobstart()*
 		  stdin:      (string) Either "pipe" (default) to connect the
 			      job's stdin to a channel or "null" to disconnect
 			      stdin.
+		  term:	    (boolean) Spawns {cmd} in a new pseudo-terminal session
+		          connected to the current (unmodified) buffer. Implies "pty".
+		          Default "height" and "width" are set to the current window
+		          dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
 		  width:      (number) Width of the `pty` terminal.
 
 		{opts} is passed as |self| dictionary to the callback; the
@@ -11168,28 +11175,6 @@ tempname()                                                          *tempname()*
                 Return: ~
                   (`string`)
 
-termopen({cmd} [, {opts}])                                          *termopen()*
-		Spawns {cmd} in a new pseudo-terminal session connected
-		to the current (unmodified) buffer. Parameters and behavior
-		are the same as |jobstart()| except "pty", "width", "height",
-		and "TERM" are ignored: "height" and "width" are taken from
-		the current window. Note that termopen() implies a "pty" arg
-		to jobstart(), and thus has the implications documented at
-		|jobstart()|.
-
-		Returns the same values as jobstart().
-
-		Terminal environment is initialized as in |jobstart-env|,
-		except $TERM is set to "xterm-256color". Full behavior is
-		described in |terminal|.
-
-                Parameters: ~
-                  • {cmd} (`string|string[]`)
-                  • {opts} (`table?`)
-
-                Return: ~
-                  (`integer`)
-
 test_garbagecollect_now()                            *test_garbagecollect_now()*
 		Like |garbagecollect()|, but executed right away.  This must
 		only be called directly to avoid any structure to exist
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index 7184151cda..dc9b0735ea 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -20,8 +20,8 @@ There are several ways to open a channel:
 
   2. Through stdin, stdout and stderr of a process spawned by |jobstart()|.
 
-  3. Through the PTY master end of a PTY opened with
-     `jobstart(..., {'pty': v:true})` or |termopen()|.
+  3. Through the PTY master end of a PTY opened with |nvim_open_term()| or
+     `jobstart(…, {'pty': v:true})`.
 
   4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|.
 
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 592b6389c4..ec98cc844f 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -16,49 +16,34 @@ Deprecated features
 DEPRECATED IN 0.11					*deprecated-0.11*
 
 API
-- nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
-- nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.
-
-LUA
-- vim.region()		Use |getregionpos()| instead.
-- *vim.highlight*	Renamed to |vim.hl|.
-- vim.validate(opts: table) Use form 1. See |vim.validate()|.
+• nvim_subscribe()	Plugins must maintain their own "multicast" channels list.
+• nvim_unsubscribe()	Plugins must maintain their own "multicast" channels list.
 
 DIAGNOSTICS
-- *vim.diagnostic.goto_next()*	Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead.
-- *vim.diagnostic.goto_prev()*	Use |vim.diagnostic.jump()| with `{count=-1, float=true}` instead.
-- *vim.diagnostic.get_next_pos()*
-	Use the "lnum" and "col" fields from the return value of
-	|vim.diagnostic.get_next()| instead.
-- *vim.diagnostic.get_prev_pos()*
-	Use the "lnum" and "col" fields from the return value of
-	|vim.diagnostic.get_prev()| instead.
-- The "win_id" parameter used by various functions is deprecated in favor of
+• *vim.diagnostic.goto_next()*	Use |vim.diagnostic.jump()| with `{count=1, float=true}` instead.
+• *vim.diagnostic.goto_prev()*	Use |vim.diagnostic.jump()| with `{count=-1, float=true}` instead.
+• *vim.diagnostic.get_next_pos()* Use the "lnum" and "col" fields from the
+				return value of |vim.diagnostic.get_next()| instead.
+• *vim.diagnostic.get_prev_pos()* Use the "lnum" and "col" fields from the
+				return value of |vim.diagnostic.get_prev()| instead.
+• The "win_id" parameter used by various functions is deprecated in favor of
   "winid" |winid|
-- The "cursor_position" parameter of |vim.diagnostic.JumpOpts| is renamed to
-  "pos"
+• |vim.diagnostic.JumpOpts| renamed its "cursor_position" field to "pos".
 
 HIGHLIGHTS
-• *TermCursorNC*	As of Nvim 0.11, unfocused |terminal| windows no
-			longer have any cursor.
-
-TREESITTER
-• *TSNode:child_containing_descendant()*	Use
-  |TSNode:child_with_descendant()| instead; it is identical except that it can
-  return the descendant itself.
+• *TermCursorNC*	Unfocused |terminal| windows do not have a cursor.
 
 LSP
 • *vim.lsp.util.jump_to_location*	Use |vim.lsp.util.show_document()| with
-  `{focus=true}` instead.
+					`{focus=true}` instead.
 • *vim.lsp.buf.execute_command*		Use |Client:exec_cmd()| instead.
 • *vim.lsp.buf.completion*		Use |vim.lsp.completion.trigger()| instead.
 • vim.lsp.buf_request_all		The `error` key has been renamed to `err` inside
 					the result parameter of the handler.
 • *vim.lsp.with()*			Pass configuration to equivalent
 					functions in `vim.lsp.buf.*`.
-• |vim.lsp.handlers|
-	No longer support client to server response handlers. Only server to
-	client requests/notification handlers are supported.
+• |vim.lsp.handlers| Does not support client-to-server response handlers. Only
+  supports server-to-client requests/notification handlers.
 • *vim.lsp.handlers.signature_help()*	Use |vim.lsp.buf.signature_help()| instead.
 • `client.request()`			Use |Client:request()| instead.
 • `client.request_sync()`		Use |Client:request_sync()| instead.
@@ -70,6 +55,18 @@ LSP
 • `client.on_attach()`			Use |Client:on_attach()| instead.
 • `vim.lsp.start_client()`		Use |vim.lsp.start()| instead.
 
+LUA
+• vim.region()		Use |getregionpos()| instead.
+• *vim.highlight*	Renamed to |vim.hl|.
+• vim.validate(opts: table) Use form 1. See |vim.validate()|.
+
+TREESITTER
+• *TSNode:child_containing_descendant()* Use |TSNode:child_with_descendant()|
+  instead; it is identical except that it can return the descendant itself.
+
+VIMSCRIPT
+• *termopen()* Use |jobstart() with `{term: v:true}`.
+
 ------------------------------------------------------------------------------
 DEPRECATED IN 0.10					*deprecated-0.10*
 
@@ -130,198 +127,198 @@ TREESITTER
 DEPRECATED IN 0.9					*deprecated-0.9*
 
 API
-- *nvim_get_hl_by_name()*		Use |nvim_get_hl()| instead.
-- *nvim_get_hl_by_id()*			Use |nvim_get_hl()| instead.
+• *nvim_get_hl_by_name()*		Use |nvim_get_hl()| instead.
+• *nvim_get_hl_by_id()*			Use |nvim_get_hl()| instead.
 
 TREESITTER
-- *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()| instead.
-- *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()| instead.
-- *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
+• *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()| instead.
+• *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()| instead.
+• *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
 						and |TSNode:type()| instead.
 • The following top level Treesitter functions have been moved:
-  - *vim.treesitter.inspect_language()*    -> |vim.treesitter.language.inspect()|
-  - *vim.treesitter.get_query_files()*     -> |vim.treesitter.query.get_files()|
-  - *vim.treesitter.set_query()*           -> |vim.treesitter.query.set()|
-  - *vim.treesitter.query.set_query()*     -> |vim.treesitter.query.set()|
-  - *vim.treesitter.get_query()*           -> |vim.treesitter.query.get()|
-  - *vim.treesitter.query.get_query()*     -> |vim.treesitter.query.get()|
-  - *vim.treesitter.parse_query()*         -> |vim.treesitter.query.parse()|
-  - *vim.treesitter.query.parse_query()*   -> |vim.treesitter.query.parse()|
-  - *vim.treesitter.add_predicate()*       -> |vim.treesitter.query.add_predicate()|
-  - *vim.treesitter.add_directive()*       -> |vim.treesitter.query.add_directive()|
-  - *vim.treesitter.list_predicates()*     -> |vim.treesitter.query.list_predicates()|
-  - *vim.treesitter.list_directives()*     -> |vim.treesitter.query.list_directives()|
-  - *vim.treesitter.query.get_range()*     -> |vim.treesitter.get_range()|
-  - *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
+  • *vim.treesitter.inspect_language()*    -> |vim.treesitter.language.inspect()|
+  • *vim.treesitter.get_query_files()*     -> |vim.treesitter.query.get_files()|
+  • *vim.treesitter.set_query()*           -> |vim.treesitter.query.set()|
+  • *vim.treesitter.query.set_query()*     -> |vim.treesitter.query.set()|
+  • *vim.treesitter.get_query()*           -> |vim.treesitter.query.get()|
+  • *vim.treesitter.query.get_query()*     -> |vim.treesitter.query.get()|
+  • *vim.treesitter.parse_query()*         -> |vim.treesitter.query.parse()|
+  • *vim.treesitter.query.parse_query()*   -> |vim.treesitter.query.parse()|
+  • *vim.treesitter.add_predicate()*       -> |vim.treesitter.query.add_predicate()|
+  • *vim.treesitter.add_directive()*       -> |vim.treesitter.query.add_directive()|
+  • *vim.treesitter.list_predicates()*     -> |vim.treesitter.query.list_predicates()|
+  • *vim.treesitter.list_directives()*     -> |vim.treesitter.query.list_directives()|
+  • *vim.treesitter.query.get_range()*     -> |vim.treesitter.get_range()|
+  • *vim.treesitter.query.get_node_text()* -> |vim.treesitter.get_node_text()|
 
 LUA
-  - *nvim_exec()*				Use |nvim_exec2()| instead.
-  - *vim.pretty_print()*			Use |vim.print()| instead.
+  • *nvim_exec()*				Use |nvim_exec2()| instead.
+  • *vim.pretty_print()*			Use |vim.print()| instead.
 
 
 ------------------------------------------------------------------------------
 DEPRECATED IN 0.8 OR EARLIER
 
 API
-- *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
-- *nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
-- *nvim_command_output()*	Use |nvim_exec2()| instead.
-- *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
-- *nvim_get_option_info()*	Use |nvim_get_option_info2()| instead.
+• *nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+• *nvim_buf_set_virtual_text()*	Use |nvim_buf_set_extmark()| instead.
+• *nvim_command_output()*	Use |nvim_exec2()| instead.
+• *nvim_execute_lua()*		Use |nvim_exec_lua()| instead.
+• *nvim_get_option_info()*	Use |nvim_get_option_info2()| instead.
 
 COMMANDS
-- *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
-- *:wv* *:wviminfo*		Deprecated alias to |:wshada| command.
+• *:rv* *:rviminfo*		Deprecated alias to |:rshada| command.
+• *:wv* *:wviminfo*		Deprecated alias to |:wshada| command.
 
 ENVIRONMENT VARIABLES
-- *$NVIM_LISTEN_ADDRESS*
-  - Deprecated way to:
-    - set the server name (use |--listen| or |serverstart()| instead)
-    - get the server name (use |v:servername| instead)
-    - detect a parent Nvim (use |$NVIM| instead)
-  - Ignored if --listen is given.
-  - Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
+• *$NVIM_LISTEN_ADDRESS*
+  • Deprecated way to:
+    • set the server name (use |--listen| or |serverstart()| instead)
+    • get the server name (use |v:servername| instead)
+    • detect a parent Nvim (use |$NVIM| instead)
+  • Ignored if --listen is given.
+  • Unset by |terminal| and |jobstart()| unless explicitly given by the "env"
     option. Example: >vim
 	call jobstart(['foo'], { 'env': { 'NVIM_LISTEN_ADDRESS': v:servername  } })
 <
 
 EVENTS
-- *BufCreate*		Use |BufAdd| instead.
-- *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
-- *FileEncoding*	Never fired; equivalent to |EncodingChanged|.
-- *GUIEnter*		Never fired; use |UIEnter| instead.
-- *GUIFailed*		Never fired.
+• *BufCreate*		Use |BufAdd| instead.
+• *EncodingChanged*	Never fired; 'encoding' is always "utf-8".
+• *FileEncoding*	Never fired; equivalent to |EncodingChanged|.
+• *GUIEnter*		Never fired; use |UIEnter| instead.
+• *GUIFailed*		Never fired.
 
 KEYCODES
-- *<MouseDown>*		Use <ScrollWheelUp> instead.
-- *<MouseUp>*		Use <ScrollWheelDown> instead.
-
-FUNCTIONS
-- *buffer_exists()*	Obsolete name for |bufexists()|.
-- *buffer_name()*	Obsolete name for |bufname()|.
-- *buffer_number()*	Obsolete name for |bufnr()|.
-- *file_readable()*	Obsolete name for |filereadable()|.
-- *highlight_exists()*	Obsolete name for |hlexists()|.
-- *highlightID()*	Obsolete name for |hlID()|.
-- *inputdialog()*	Use |input()| instead.
-- *jobclose()*		Obsolete name for |chanclose()|
-- *jobsend()*		Obsolete name for |chansend()|
-- *last_buffer_nr()*	Obsolete name for bufnr("$").
-- *rpcstart()*		Use |jobstart()| with `{'rpc': v:true}` instead.
-- *rpcstop()*		Use |jobstop()| instead to stop any job, or
-			`chanclose(id, "rpc")` to close RPC communication
-			without stopping the job. Use chanclose(id) to close
-			any socket.
+• *<MouseDown>*		Use <ScrollWheelUp> instead.
+• *<MouseUp>*		Use <ScrollWheelDown> instead.
 
 HIGHLIGHTS
-- *hl-VertSplit*	Use |hl-WinSeparator| instead.
+• *hl-VertSplit*	Use |hl-WinSeparator| instead.
 
 LSP DIAGNOSTICS
 For each of the functions below, use the corresponding function in
 |vim.diagnostic| instead (unless otherwise noted). For example, use
 |vim.diagnostic.get()| instead of |vim.lsp.diagnostic.get()|.
 
-- *vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
-- *vim.lsp.diagnostic.disable()*          Use |vim.diagnostic.enable()| instead.
-- *vim.lsp.diagnostic.display()*	Use |vim.diagnostic.show()| instead.
-- *vim.lsp.diagnostic.enable()*
-- *vim.lsp.diagnostic.get()*
-- *vim.lsp.diagnostic.get_all()*	Use |vim.diagnostic.get()| instead.
-- *vim.lsp.diagnostic.get_count()*	Use |vim.diagnostic.count()| instead.
-- *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead.
-- *vim.lsp.diagnostic.get_next()*
-- *vim.lsp.diagnostic.get_next_pos()*
-- *vim.lsp.diagnostic.get_prev()*
-- *vim.lsp.diagnostic.get_prev_pos()*
-- *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use
+• *vim.lsp.diagnostic.clear()*		Use |vim.diagnostic.hide()| instead.
+• *vim.lsp.diagnostic.disable()*          Use |vim.diagnostic.enable()| instead.
+• *vim.lsp.diagnostic.display()*	Use |vim.diagnostic.show()| instead.
+• *vim.lsp.diagnostic.enable()*
+• *vim.lsp.diagnostic.get()*
+• *vim.lsp.diagnostic.get_all()*	Use |vim.diagnostic.get()| instead.
+• *vim.lsp.diagnostic.get_count()*	Use |vim.diagnostic.count()| instead.
+• *vim.lsp.diagnostic.get_line_diagnostics()* Use |vim.diagnostic.get()| instead.
+• *vim.lsp.diagnostic.get_next()*
+• *vim.lsp.diagnostic.get_next_pos()*
+• *vim.lsp.diagnostic.get_prev()*
+• *vim.lsp.diagnostic.get_prev_pos()*
+• *vim.lsp.diagnostic.get_virtual_text_chunks_for_line()* No replacement. Use
   options provided by |vim.diagnostic.config()| to customize virtual text.
-- *vim.lsp.diagnostic.goto_next()*
-- *vim.lsp.diagnostic.goto_prev()*
-- *vim.lsp.diagnostic.redraw()*		Use |vim.diagnostic.show()| instead.
-- *vim.lsp.diagnostic.reset()*
-- *vim.lsp.diagnostic.save()*		Use |vim.diagnostic.set()| instead.
-- *vim.lsp.diagnostic.set_loclist()*	Use |vim.diagnostic.setloclist()| instead.
-- *vim.lsp.diagnostic.set_qflist()*	Use |vim.diagnostic.setqflist()| instead.
-- *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead.
-- *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead.
+• *vim.lsp.diagnostic.goto_next()*
+• *vim.lsp.diagnostic.goto_prev()*
+• *vim.lsp.diagnostic.redraw()*		Use |vim.diagnostic.show()| instead.
+• *vim.lsp.diagnostic.reset()*
+• *vim.lsp.diagnostic.save()*		Use |vim.diagnostic.set()| instead.
+• *vim.lsp.diagnostic.set_loclist()*	Use |vim.diagnostic.setloclist()| instead.
+• *vim.lsp.diagnostic.set_qflist()*	Use |vim.diagnostic.setqflist()| instead.
+• *vim.lsp.diagnostic.show_line_diagnostics()* Use |vim.diagnostic.open_float()| instead.
+• *vim.lsp.diagnostic.show_position_diagnostics()* Use |vim.diagnostic.open_float()| instead.
 
 The following are deprecated without replacement. These functions are moved
 internally and are no longer exposed as part of the API. Instead, use
 |vim.diagnostic.config()| and |vim.diagnostic.show()|.
 
-- *vim.lsp.diagnostic.set_signs()*
-- *vim.lsp.diagnostic.set_underline()*
-- *vim.lsp.diagnostic.set_virtual_text()*
+• *vim.lsp.diagnostic.set_signs()*
+• *vim.lsp.diagnostic.set_underline()*
+• *vim.lsp.diagnostic.set_virtual_text()*
 
 LSP FUNCTIONS
-- *vim.lsp.buf.server_ready()*
+• *vim.lsp.buf.server_ready()*
   Use |LspAttach| instead, depending on your use-case. "Server ready" is not
   part of the LSP spec, so the Nvim LSP client cannot meaningfully implement
   it. "Ready" is ambiguous because:
-  - Language servers may finish analyzing the workspace, but edits can always
+  • Language servers may finish analyzing the workspace, but edits can always
     re-trigger analysis/builds.
-  - Language servers can serve some requests even while processing changes.
-- *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
+  • Language servers can serve some requests even while processing changes.
+• *vim.lsp.buf.range_code_action()*		Use |vim.lsp.buf.code_action()| with
 						the `range` parameter.
-- *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.
-- *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
-- *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
-- *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_clients()| with
+• *vim.lsp.util.diagnostics_to_items()*		Use |vim.diagnostic.toqflist()| instead.
+• *vim.lsp.util.set_qflist()*			Use |setqflist()| instead.
+• *vim.lsp.util.set_loclist()*			Use |setloclist()| instead.
+• *vim.lsp.buf_get_clients()*			Use |vim.lsp.get_clients()| with
 						{buffer=bufnr} instead.
-- *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
+• *vim.lsp.buf.formatting()*			Use |vim.lsp.buf.format()| with
 						{async=true} instead.
-- *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
+• *vim.lsp.buf.formatting_sync()*		Use |vim.lsp.buf.format()| with
 						{async=false} instead.
-- *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
+• *vim.lsp.buf.range_formatting()*		Use |vim.lsp.formatexpr()|
 						or |vim.lsp.buf.format()| instead.
 
 LUA
-- vim.register_keystroke_callback()	Use |vim.on_key()| instead.
+• vim.register_keystroke_callback()	Use |vim.on_key()| instead.
 
 NORMAL COMMANDS
-- *]f* *[f*		Same as "gf".
+• *]f* *[f*		Same as "gf".
 
 OPTIONS
-- *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special*
+• *cpo-<* *:menu-<special>* *:menu-special* *:map-<special>* *:map-special*
   `<>` notation is always enabled.
-- *'fe'*		'fenc'+'enc' before Vim 6.0; no longer used.
-- *'highlight'* *'hl'*	Names of builtin |highlight-groups| cannot be changed.
-- *'langnoremap'*	Deprecated alias to 'nolangremap'.
-- 'sessionoptions'	Flags "unix", "slash" are ignored and always enabled.
-- *'vi'*
-- 'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
-- *'viminfo'*		Deprecated alias to 'shada' option.
-- *'viminfofile'*	Deprecated alias to 'shadafile' option.
-- *'paste'* *'nopaste'*	Just Paste It.™  The 'paste' option is obsolete:
+• *'fe'*		'fenc'+'enc' before Vim 6.0; no longer used.
+• *'highlight'* *'hl'*	Names of builtin |highlight-groups| cannot be changed.
+• *'langnoremap'*	Deprecated alias to 'nolangremap'.
+• 'sessionoptions'	Flags "unix", "slash" are ignored and always enabled.
+• *'vi'*
+• 'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
+• *'viminfo'*		Deprecated alias to 'shada' option.
+• *'viminfofile'*	Deprecated alias to 'shadafile' option.
+• *'paste'* *'nopaste'*	Just Paste It.™  The 'paste' option is obsolete:
 			|paste| is handled automatically when you paste text
 			using your terminal's or GUI's paste feature
 			(CTRL-SHIFT-v, CMD-v (macOS), middle-click, …).
 			Enables "paste mode":
-			  - Disables mappings in Insert, Cmdline mode.
-			  - Disables abbreviations.
-			  - Resets 'autoindent' 'expandtab' 'revins' 'ruler'
+			  • Disables mappings in Insert, Cmdline mode.
+			  • Disables abbreviations.
+			  • Resets 'autoindent' 'expandtab' 'revins' 'ruler'
 			    'showmatch' 'smartindent' 'smarttab' 'softtabstop'
 			    'textwidth' 'wrapmargin'.
-			  - Treats 'formatoptions' as empty.
-			  - Disables the effect of these options:
-			    - 'cindent'
-			    - 'indentexpr'
-			    - 'lisp'
+			  • Treats 'formatoptions' as empty.
+			  • Disables the effect of these options:
+			    • 'cindent'
+			    • 'indentexpr'
+			    • 'lisp'
 
 UI EXTENSIONS
-- *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
+• *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
 			by the `ext_wildmenu` |ui-option|. Emits these events:
-			- `["wildmenu_show", items]`
-			- `["wildmenu_select", selected]`
-			- `["wildmenu_hide"]`
-- *term_background*	Unused. The terminal background color is now detected
+			• `["wildmenu_show", items]`
+			• `["wildmenu_select", selected]`
+			• `["wildmenu_hide"]`
+• *term_background*	Unused. The terminal background color is now detected
 			by the Nvim core directly instead of the TUI.
 
 VARIABLES
-- *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
-- *b:terminal_job_id*	Use `&channel` instead. To access in non-current buffer:
-			- Lua: `vim.bo[bufnr].channel`
-			- Vimscript: `getbufvar(bufnr, '&channel')`
+• *b:terminal_job_pid*	Use `jobpid(&channel)` instead.
+• *b:terminal_job_id*	Use `&channel` instead. To access in non-current buffer:
+			• Lua: `vim.bo[bufnr].channel`
+			• Vimscript: `getbufvar(bufnr, '&channel')`
+
+VIMSCRIPT
+• *buffer_exists()*	Obsolete name for |bufexists()|.
+• *buffer_name()*	Obsolete name for |bufname()|.
+• *buffer_number()*	Obsolete name for |bufnr()|.
+• *file_readable()*	Obsolete name for |filereadable()|.
+• *highlight_exists()*	Obsolete name for |hlexists()|.
+• *highlightID()*	Obsolete name for |hlID()|.
+• *inputdialog()*	Use |input()| instead.
+• *jobclose()*		Obsolete name for |chanclose()|
+• *jobsend()*		Obsolete name for |chansend()|
+• *last_buffer_nr()*	Obsolete name for bufnr("$").
+• *rpcstart()*		Use |jobstart()| with `{'rpc': v:true}` instead.
+• *rpcstop()*		Use |jobstop()| instead to stop any job, or
+			`chanclose(id, "rpc")` to close RPC communication
+			without stopping the job. Use chanclose(id) to close
+			any socket.
 
 
  vim:noet:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 172fa4625c..011970f5eb 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -294,6 +294,7 @@ TERMINAL
   means that the |TermCursorNC| highlight group is no longer supported: an
   unfocused terminal window will have no cursor at all (so there is nothing to
   highlight).
+• |jobstart()| gained the "term" flag.
 
 TREESITTER
 
diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index f9536c2f0c..ff8e3a976f 100644
--- a/runtime/doc/terminal.txt
+++ b/runtime/doc/terminal.txt
@@ -26,7 +26,7 @@ Start						*terminal-start*
 There are several ways to create a terminal buffer:
 
 - Run the |:terminal| command.
-- Call the |nvim_open_term()| or |termopen()| function.
+- Call |nvim_open_term()| or `jobstart(…, {'term': v:true})`.
 - Edit a "term://" buffer. Examples: >vim
     :edit term://bash
     :vsplit term://top
diff --git a/runtime/lua/vim/_defaults.lua b/runtime/lua/vim/_defaults.lua
index 0b8a54e957..4216a2acb7 100644
--- a/runtime/lua/vim/_defaults.lua
+++ b/runtime/lua/vim/_defaults.lua
@@ -435,7 +435,7 @@ do
     group = nvim_terminal_augroup,
     desc = 'Treat term:// buffers as terminal buffers',
     nested = true,
-    command = "if !exists('b:term_title')|call termopen(matchstr(expand(\"<amatch>\"), '\\c\\mterm://\\%(.\\{-}//\\%(\\d\\+:\\)\\?\\)\\?\\zs.*'), {'cwd': expand(get(matchlist(expand(\"<amatch>\"), '\\c\\mterm://\\(.\\{-}\\)//'), 1, ''))})",
+    command = "if !exists('b:term_title')|call jobstart(matchstr(expand(\"<amatch>\"), '\\c\\mterm://\\%(.\\{-}//\\%(\\d\\+:\\)\\?\\)\\?\\zs.*'), {'term': v:true, 'cwd': expand(get(matchlist(expand(\"<amatch>\"), '\\c\\mterm://\\(.\\{-}\\)//'), 1, ''))})",
   })
 
   vim.api.nvim_create_autocmd({ 'TermClose' }, {
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 8d759278d0..bea6df43bb 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -272,12 +272,12 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end
 --- This temporarily switches current buffer to "buffer".
 --- If the current window already shows "buffer", the window is not switched.
 --- If a window inside the current tabpage (including a float) already shows the
---- buffer, then one of these windows will be set as current window temporarily.
+--- buffer, then one of those windows will be set as current window temporarily.
 --- Otherwise a temporary scratch window (called the "autocmd window" for
 --- historical reasons) will be used.
 ---
 --- This is useful e.g. to call Vimscript functions that only work with the
---- current buffer/window currently, like `termopen()`.
+--- current buffer/window currently, like `jobstart(…, {'term': v:true})`.
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param fun function Function to call inside the buffer (currently Lua callable
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index cf1beda15f..b580357c85 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -4805,7 +4805,7 @@ function vim.fn.jobresize(job, width, height) end
 --- @return any
 function vim.fn.jobsend(...) end
 
---- Note: Prefer |vim.system()| in Lua (unless using the `pty` option).
+--- Note: Prefer |vim.system()| in Lua (unless using `rpc`, `pty`, or `term`).
 ---
 --- Spawns {cmd} as a job.
 --- If {cmd} is a List it runs directly (no 'shell').
@@ -4813,8 +4813,11 @@ function vim.fn.jobsend(...) end
 ---   call jobstart(split(&shell) + split(&shellcmdflag) + ['{cmd}'])
 --- <(See |shell-unquoting| for details.)
 ---
---- Example: >vim
----   call jobstart('nvim -h', {'on_stdout':{j,d,e->append(line('.'),d)}})
+--- Example: start a job and handle its output: >vim
+---   call jobstart(['nvim', '-h'], {'on_stdout':{j,d,e->append(line('.'),d)}})
+--- <
+--- Example: start a job in a |terminal| connected to the current buffer: >vim
+---   call jobstart(['nvim', '-h'], {'term':v:true})
 --- <
 --- Returns |job-id| on success, 0 on invalid arguments (or job
 --- table is full), -1 if {cmd}[0] or 'shell' is not executable.
@@ -4879,6 +4882,10 @@ function vim.fn.jobsend(...) end
 ---   stdin:      (string) Either "pipe" (default) to connect the
 ---         job's stdin to a channel or "null" to disconnect
 ---         stdin.
+---   term:      (boolean) Spawns {cmd} in a new pseudo-terminal session
+---           connected to the current (unmodified) buffer. Implies "pty".
+---           Default "height" and "width" are set to the current window
+---           dimensions. |jobstart()|. Defaults $TERM to "xterm-256color".
 ---   width:      (number) Width of the `pty` terminal.
 ---
 --- {opts} is passed as |self| dictionary to the callback; the
@@ -10168,19 +10175,8 @@ function vim.fn.tanh(expr) end
 --- @return string
 function vim.fn.tempname() end
 
---- Spawns {cmd} in a new pseudo-terminal session connected
---- to the current (unmodified) buffer. Parameters and behavior
---- are the same as |jobstart()| except "pty", "width", "height",
---- and "TERM" are ignored: "height" and "width" are taken from
---- the current window. Note that termopen() implies a "pty" arg
---- to jobstart(), and thus has the implications documented at
---- |jobstart()|.
----
---- Returns the same values as jobstart().
----
---- Terminal environment is initialized as in |jobstart-env|,
---- except $TERM is set to "xterm-256color". Full behavior is
---- described in |terminal|.
+--- @deprecated
+--- Use |jobstart()| with `{term: v:true}` instead.
 ---
 --- @param cmd string|string[]
 --- @param opts? table
diff --git a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
index fd8c4b8817..b6da91a833 100644
--- a/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
+++ b/runtime/pack/dist/opt/termdebug/plugin/termdebug.vim
@@ -38,7 +38,7 @@
 " NEOVIM COMPATIBILITY
 "
 " The vim specific functionalities were replaced with neovim specific calls:
-" - term_start -> termopen
+" - term_start -> `jobstart(…, {'term': v:true})`
 " - term_sendkeys -> chansend
 " - term_getline -> getbufline
 " - job_info && term_getjob -> nvim_get_chan_info
@@ -251,7 +251,7 @@ endfunc
 " Open a terminal window without a job, to run the debugged program in.
 func s:StartDebug_term(dict)
   execute s:vertical ? 'vnew' : 'new'
-  let s:pty_job_id = termopen('tail -f /dev/null;#gdb program')
+  let s:pty_job_id = jobstart('tail -f /dev/null;#gdb program', {'term': v:true})
   if s:pty_job_id == 0
     call s:Echoerr('Invalid argument (or job table is full) while opening terminal window')
     return
@@ -323,7 +323,7 @@ func s:StartDebug_term(dict)
 
   execute 'new'
   " call ch_log($'executing "{join(gdb_cmd)}"')
-  let s:gdb_job_id = termopen(gdb_cmd, {'on_exit': function('s:EndTermDebug')})
+  let s:gdb_job_id = jobstart(gdb_cmd, {'term': v:true, 'on_exit': function('s:EndTermDebug')})
   if s:gdb_job_id == 0
     call s:Echoerr('Invalid argument (or job table is full) while opening gdb terminal window')
     exe 'bwipe! ' . s:ptybufnr
@@ -491,7 +491,7 @@ func s:StartDebug_prompt(dict)
     " Unix: Run the debugged program in a terminal window.  Open it below the
     " gdb window.
     belowright new
-    let s:pty_job_id = termopen('tail -f /dev/null;#gdb program')
+    let s:pty_job_id = jobstart('tail -f /dev/null;#gdb program', {'term': v:true})
     if s:pty_job_id == 0
       call s:Echoerr('Invalid argument (or job table is full) while opening terminal window')
       return