===================================================================
RCS file: /cvsrepo/anoncvs/cvs/src/usr.bin/tmux/tmux.1,v
retrieving revision 1.152
retrieving revision 1.153
diff -u -r1.152 -r1.153
--- src/usr.bin/tmux/tmux.1	2010/02/11 20:39:40	1.152
+++ src/usr.bin/tmux/tmux.1	2010/02/17 21:12:06	1.153
@@ -1,4 +1,4 @@
-.\" $OpenBSD: tmux.1,v 1.152 2010/02/11 20:39:40 nicm Exp $
+.\" $OpenBSD: tmux.1,v 1.153 2010/02/17 21:12:06 nicm Exp $
 .\"
 .\" Copyright (c) 2007 Nicholas Marriott <nicm@users.sourceforge.net>
 .\"
@@ -14,7 +14,7 @@
 .\" IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
 .\" OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: February 11 2010 $
+.Dd $Mdocdate: February 17 2010 $
 .Dt TMUX 1
 .Os
 .Sh NAME
@@ -111,6 +111,11 @@
 server will be started to retrieve the
 .Ic default-shell
 option.
+This option is for compatibility with
+.Xr sh 1
+when
+.Nm
+is used as a login shell.
 .It Fl f Ar file
 Specify an alternative configuration file.
 By default,
@@ -342,6 +347,32 @@
 .Em bottom-right
 may be used instead of a pane index.
 .Pp
+.Ar shell-command
+arguments are
+.Xr sh 1
+commands.
+These must be passed as a single item, which typically means quoting them, for
+example:
+.Bd -literal -offset indent
+new-window 'vi /etc/passwd'
+.Ed
+.Pp
+.Ar command
+.Op Ar arguments
+refers to a
+.Nm
+command, passed with the command and arguments separately, for example:
+.Bd -literal -offset indent
+bind-key F1 set-window-option force-width 81
+.Ed
+.Pp
+Or if using
+.Xr sh 1 :
+.Pp
+.Bd -literal -offset indent
+$ tmux bind-key F1 set-window-option force-width 81
+.Ed
+.Pp
 Multiple commands may be specified together as part of a
 .Em command sequence .
 Each command should be separated by spaces and a semicolon;
@@ -350,7 +381,9 @@
 example, when specifying a command sequence to
 .Ic bind-key ) .
 .Pp
-Examples include:
+Example
+.Nm
+commands include:
 .Bd -literal -offset indent
 refresh-client -t/dev/ttyp2
 
@@ -360,8 +393,40 @@
 
 new-window ; split-window -d
 .Ed
+.Pp
+Or from
+.Xr sh 1 :
+.Pp
+.Bd -literal -offset indent
+$ tmux kill-window -t :1
+
+$ tmux new-window \\; split-window -d
+
+$ tmux new-session -d 'vi /etc/passwd' \\; split-window -d \\; attach
+.Ed
 .Sh CLIENTS AND SESSIONS
-The following commands are available:
+The
+.Nm
+server manages clients, sessions, windows and panes.
+Clients are attached to sessions to interact with them, either
+when they are created with the
+.Ic new-session
+command, or later with the
+.Ic attach-session
+command.
+Each session has one of more windows
+.Em linked
+into it.
+Windows may be linked to multiple sessions and are made up of one or
+more panes,
+each of which contains a pseudo terminal.
+Commands for creating, linking and otherwise manipulating windows
+are covered
+in the
+.Sx WINDOWS AND PANES
+section.
+.Pp
+The following commands are available to manage clients and sessions:
 .Bl -tag -width Ds
 .It Xo Ic attach-session
 .Op Fl dr
@@ -428,18 +493,19 @@
 .Op Fl n Ar window-name
 .Op Fl s Ar session-name
 .Op Fl t Ar target-session
-.Op Ar command
+.Op Ar shell-command
 .Xc
 .D1 (alias: Ic new )
 Create a new session with name
 .Ar session-name .
+.Pp
 The new session is attached to the current terminal unless
 .Fl d
 is given.
 .Ar window-name
 and
-.Ar command
-are the name of and command to execute in the initial window.
+.Ar shell-command
+are the name of and shell command to execute in the initial window.
 .Pp
 If run from a terminal, any
 .Xr termios 4
@@ -460,7 +526,7 @@
 Giving
 .Fl n
 or
-.Ar command
+.Ar shell-command
 are invalid if
 .Fl t
 is used.
@@ -886,7 +952,7 @@
 .Op Fl dk
 .Op Fl n Ar window-name
 .Op Fl t Ar target-window
-.Op Ar command
+.Op Ar shell-command
 .Xc
 .D1 (alias: Ic neww )
 Create a new window.
@@ -898,12 +964,19 @@
 shown, unless the
 .Fl k
 flag is used, in which case it is destroyed.
-.Ar command
+.Ar shell-command
 is the command to execute.
 If
-.Ar command
-is not specified, the default command is used.
+.Ar shell-command
+is not specified, the value of the
+.Ic default-command
+option is used.
 .Pp
+When the shell command completes, the window closes.
+See the
+.Ic remain-on-exit
+option to change this behaviour.
+.Pp
 The
 .Ev TERM
 environment variable must be set to
@@ -930,7 +1003,7 @@
 .It Xo Ic pipe-pane
 .Op Fl o
 .Op Fl t Ar target-pane
-.Op Ar command
+.Op Ar shell-command
 .Xc
 .D1 (alias: Ic pipep )
 Pipe any output sent by the program in
@@ -938,10 +1011,10 @@
 to a shell command.
 A pane may only be piped to one command at a time, any existing pipe is
 closed before
-.Ar command
+.Ar shell-command
 is executed.
 If no
-.Ar command
+.Ar shell-command
 is given, the current pipe (if any) is closed.
 .Pp
 The
@@ -989,14 +1062,14 @@
 .It Xo Ic respawn-window
 .Op Fl k
 .Op Fl t Ar target-window
-.Op Ar command
+.Op Ar shell-command
 .Xc
 .D1 (alias: Ic respawnw )
-Reactive a window in which the command has exited (see the
+Reactivate a window in which the command has exited (see the
 .Ic remain-on-exit
 window option).
 If
-.Ar command
+.Ar shell-command
 is not given, the command used when the window was created is executed.
 The window must be already inactive, unless
 .Fl k
@@ -1035,7 +1108,7 @@
 .Ar size |
 .Fl p Ar percentage Oc
 .Op Fl t Ar target-pane
-.Op Ar command
+.Op Ar shell-command
 .Xc
 .D1 (alias: splitw )
 Create a new pane by splitting
@@ -1376,10 +1449,10 @@
 Set the number of buffers kept for each session; as new buffers are added to
 the top of the stack, old ones are removed from the bottom if necessary to
 maintain this maximum length.
-.It Ic default-command Ar command
+.It Ic default-command Ar shell-command
 Set the command used for new windows (if not specified when the window is
 created) to
-.Ar command ,
+.Ar shell-command ,
 which may be any
 .Xr sh 1
 command.
@@ -1450,7 +1523,7 @@
 .Ic lock-server
 option is set.
 The default is not to lock (set to 0).
-.It Ic lock-command Ar command
+.It Ic lock-command Ar shell-command
 Command to run when locking each client.
 The default is to run
 .Xr lock 1
@@ -1545,6 +1618,13 @@
 Set the
 .Ic remain-on-exit
 window option for any windows first created in this session.
+When this option is true, windows in which the running program has
+exited do not close, instead remaining open but inactivate.
+Use the
+.Ic respawn-window
+command to reactivate such a window, or the
+.Ic kill-window
+command to destroy it.
 .It Xo Ic set-titles
 .Op Ic on | off
 .Xc
@@ -1601,7 +1681,7 @@
 may contain any of the following special character sequences:
 .Bl -column "Character pair" "Replaced with" -offset indent
 .It Sy "Character pair" Ta Sy "Replaced with"
-.It Li "#(command)" Ta "First line of command's output"
+.It Li "#(shell-command)" Ta "First line of the command's output"
 .It Li "#[attributes]" Ta "Colour or attribute change"
 .It Li "#H" Ta "Hostname of local host"
 .It Li "#F" Ta "Current window flag"
@@ -1613,9 +1693,9 @@
 .It Li "##" Ta "A literal" Ql #
 .El
 .Pp
-The #(command) form executes
-.Ql command
-as a shell command and inserts the first line of its output.
+The #(shell-command) form executes
+.Ql shell-command
+and inserts the first line of its output.
 Note that shell commands are only executed once at the interval specified by
 the
 .Ic status-interval
@@ -2295,15 +2375,13 @@
 Lock each client individually by running the command specified by the
 .Ic lock-command
 option.
-.It Ic run-shell Ar command
+.It Ic run-shell Ar shell-command
 .D1 (alias: Ic run )
 Execute
-.Ar command
+.Ar shell-command
 in the background without creating a window.
-After the command finishes, any output to stdout is displayed in output mode.
-If
-.Ar command
-doesn't return success, the exit status is also displayed.
+After it finishes, any output to stdout is displayed in output mode.
+If the command doesn't return success, the exit status is also displayed.
 .It Ic server-info
 .D1 (alias: Ic info )
 Show server information and terminal details.