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 <mattn.jp@gmail.com>
Signed-off-by: Hirohito Higashi <h.east.727@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/terminal.txt b/runtime/doc/terminal.txt
index b46899ceae571b6ca4f9ba4b3c33a1115db1d55f..7a4f9cd5378db5c6fb7941337b25bb64c0b6cf37 100644 (file)
--- a/runtime/doc/terminal.txt
+++ b/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