33091: improve documentation for ttyctl

1 files changed, 15 insertions, 3 deletions

diff --git a/Doc/Zsh/builtins.yo b/Doc/Zsh/builtins.yo
index f709f5020..9862c637e 100644
--- a/Doc/Zsh/builtins.yo
+++ b/Doc/Zsh/builtins.yo
@@ -1639,14 +1639,26 @@ Do nothing and return an exit status of 0.
 findex(ttyctl)
 cindex(tty, freezing)
 item(tt(ttyctl) tt(-fu))(
-The tt(-f) option freezes the tty, and tt(-u) unfreezes it.
+The tt(-f) option freezes the tty (i.e. terminal or terminal emulator), and
+tt(-u) unfreezes it.
 When the tty is frozen, no changes made to the tty settings by
 external programs will be honored by the shell, except for changes in the
 size of the screen; the shell will
 simply reset the settings to their previous values as soon as each
 command exits or is suspended.  Thus, tt(stty) and similar programs have
-no effect when the tty is frozen.  Without options it reports whether the
-terminal is frozen or not.
+no effect when the tty is frozen.  Freezing the tty does not cause
+the current state to be remembered: instead, it causes future changes
+to the state to be blocked.
+
+Without options it reports whether the terminal is frozen or not.
+
+Note that, regardless of whether the tty is frozen or not, the
+shell needs to change the settings when the line editor starts, so
+unfreezing the tty does not guarantee settings made on the
+command line are preserved.  Strings of commands run between
+editing the command line will see a consistent tty state.
+See also the shell variable tt(STTY) for a means of initialising
+the tty before running external commands.
 )
 findex(type)
 item(tt(type) [ tt(-wfpams) ] var(name) ...)(