[PATCH] [doc] clone module using xterm's slave mode

[Stephane Chazelas <stephane@xxxxxxxxxxxx>]

Hi, while testing the patch for the pgrp restore issue, I came
up with a way to clone zsh onto a xterm and attach to the tty
device properly there (using xterm's slave mode).

Here's a doc patch to document that approach (requires socat,
though the same could be done with expect or some perl/python
pty module).

I changed the trap : INT to trap "" INT so the signals are
properly ignored. (trap : INT makes the signal harmless to sh,
but would still kill "sleep" in those sh implementations where
sleep is not builtin).

diff --git a/Doc/Zsh/mod_clone.yo b/Doc/Zsh/mod_clone.yo
index 02dc5be0e..a3801cd40 100644
--- a/Doc/Zsh/mod_clone.yo
+++ b/Doc/Zsh/mod_clone.yo
@@ -20,7 +20,7 @@ and non-zero on error.
 The target of tt(clone) should be an unused terminal, such as an unused virtual
 console or a virtual terminal created by
 
-example(xterm -e sh -c 'trap : INT QUIT TSTP; tty;
+example(xterm -e sh -c 'trap "" INT QUIT TSTP; tty;
         while :; do sleep 100000000; done')
 
 Some words of explanation are warranted about this long xterm command
@@ -39,11 +39,30 @@ enditemize()
 
 This does not apply when cloning to an em(unused) vc.
 
-Cloning to a used (and unprepared) terminal will result in two
-processes reading simultaneously from the same terminal, with
-input bytes going randomly to either process.
+It is possible however to clone zsh onto a xterm and that zsh process
+to lead the session attached to that terminal by using tt(xterm)'s slave
+mode in conjunction with an utility like tt(socat) that can create a
+pseudo-terminal pair:
 
-tt(clone) is mostly useful as a shell built-in replacement for
-openvt.
+example(socat pty,link=pty,wait-slave,echo=0 'exec:xterm -Spty/3,nofork,fdout=3,fdin=3' &
+        clone pty; (($!)) || { IFS= read -r WINDOWID && ((WINDOWID = 0x$WINDOWID));})
+
+Above, tt(socat) creates a pseudo terminal, and makes a tt(pty) symbolic
+link to the slave device in the current directory. As soon as a process
+opens that device, tt(xterm) is started with its file descriptor 3
+connected to the master side.
+
+The cloned zsh is the process that opens that device here. And once
+started, we make it read the X11 Window ID that tt(xterm) oututs there
+into tt($WINDOWID) (the same variable that xterm sets itself when not in
+slave mode) before resuming normal operation. That zsh process becomes
+the session leader attached to the tty device in the same way a zsh
+started with tt(xterm -e zsh) would, and job control works as it should.
+
+Cloning to a used (and unprepared) terminal will result in two processes
+reading simultaneously from the same terminal, with input bytes going
+randomly to either process.
+
+tt(clone) is mostly useful as a shell built-in replacement for openvt.
 )
 enditem()