runtime(doc): clarify term_start() I/O behavior for Unix pty and MS-Windows ConPTY

Explain how stdin/stdout/stderr are connected in term_start():
- On Unix, they default to pty; only "err_cb" switches stderr to a pipe,
  which may cause output order differences due to buffering.
- On MS-Windows with ConPTY, they are always pipes and stdout/stderr
  share the same pipe, so "err_cb" cannot separate them.

related: #16354

Co-authored-by: Yasuhiro Matsumoto <[email protected]>
Signed-off-by: Hirohito Higashi <[email protected]>
Signed-off-by: Christian Brabandt <[email protected]>

Author: 2 people

runtime/doc/terminal.txt

@@ -1,4 +1,4 @@
-*terminal.txt*	For Vim version 9.2.  Last change: 2026 Mar 12
+*terminal.txt*	For Vim version 9.2.  Last change: 2026 Apr 02
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -944,9 +944,26 @@ term_start({cmd} [, {options}])			*term_start()*
 		   "in_io", "in_top", "in_bot", "in_name", "in_buf"
 		   "out_io", "out_name", "out_buf", "out_modifiable", "out_msg"
 		   "err_io", "err_name", "err_buf", "err_modifiable", "err_msg"
-		However, at least one of stdin, stdout or stderr must be
-		connected to the terminal.  When I/O is connected to the
-		terminal then the callback function for that part is not used.
+		On Unix:
+		stdin, stdout, and stderr are connected to a pty by default,
+		since bidirectional communication with the terminal is
+		required.  Setting "out_cb" does not switch stdout from the
+		pty to a pipe.  Only setting "err_cb" switches stderr to a
+		pipe.
+		Note: Since a pty is line-buffered and a pipe is
+		block-buffered, the order of output between stdout and stderr
+		may not be preserved.  Without "err_cb", stderr uses the same
+		pty as stdout, so the output order is preserved but stdout and
+		stderr cannot be distinguished.
+
+		On MS-Windows with |ConPTY|:
+		stdin, stdout, and stderr are always connected through pipes
+		to the pseudo console, regardless of callback settings.
+		Since stdout and stderr share the same pipe, they cannot be
+		separated by "err_cb".
+		This is because the CreatePseudoConsole() API only accepts one
+		input and one output handle, with no separate handle for
+		stderr.
 
 		There are extra options:
 		   "term_name"	     name to use for the buffer name, instead