On Sat, Jan 23, 2010 at 06:15:00PM +0000, Nicholas Marriott wrote:
> Hi
> 
> Thanks for the diff,
> 
> > Index: tmux.1
> > ===================================================================
> > RCS file: /cvsroot/tmux/tmux/tmux.1,v
> > retrieving revision 1.221
> > diff -u -r1.221 tmux.1
> > --- tmux.1  19 Jan 2010 00:46:30 -0000      1.221
> > +++ tmux.1  21 Jan 2010 09:33:23 -0000
> > @@ -335,6 +335,23 @@
> >  .Em bottom-right
> >  may be used instead of a pane index.
> >  .Pp
> > +.Ar shell-command
> > +arguments are sh(1) commands, as a single argument.  What "single
> 
> .Xr sh 1
> 
> Convention for man pages is new sentence, new line.

OK.  Sorry, was cargo-culting this one.

> > +argument" means can vary from shell to shell if you are calling
> > tmux
> 
> Man pages should be in the third person. 

"if he/she is calling"?  Ewww.  How about passive voice?  "if tmux
is being called"

> I wouldn't even say it can vary from shell to shell, let's just
> give an sh example.

'k.

> vim is a poor example because it isn't a standard Unix command, 

Heh.  Sorry, used to Linux, where vi is just a symlink to vim.

> so how about vi:
> 
> .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

Lovely.

> > +commands that accept such arguments from the command line, but
> > +inside tmux itself, this means single quotes, like this:
> > +.Bd -literal -offset indent
> > +new-window 'vim -o foo bar'
> > +.Ed
> > +.Pp
> > +.Ar command
> > +arguments are tmux commands, and in contrast to shell
> > +command arguments, each word of the command must be separate.  As a
> > +result, all
> > +.Ar command
> > +arguments are the last argument that command takes: all
> > +remaining words are consumed.
> > +.Pp
> 
> I think this is too much detail. 

People say that a lot about my documentation.  :)  Although I think
that you mean that it's overly verbose for the level of detail it
actually provides, which is subtly different.  And I think you're
right; using your version (tested).

By the way, as a side effect of testing that, I just discovered what
tmux does when you "set-window-option force-width" to something less
wide than the terminal.  That's ... really weird looking.  0.o  (not
suggesting a change, just sayin')

> >  Multiple commands may be specified together as part of a
> >  .Em command sequence .
> >  Each command should be separated by spaces and a semicolon;
> > @@ -342,8 +359,36 @@
> >  A literal semicolon may be included by escaping it with a backslash (for
> >  example, when specifying a command sequence to
> >  .Ic bind-key ) .
> > +In most shells, you will need to quote the semicolon in some way,
> > +but you cannot simply quote the whole sequence, because each
> > +command and each backslash must be a separate word, as mentioned in
> > +the
> > +.Ar command
> > +argument section above.  
> > +In sh(1), this command will not work at all, because tmux expects
> > +each element of a tmux command to be a seperate word:
> > +.Bd -literal -offset indent
> > +tmux 'new-session -d vim ; split-window ; attach'
> > +.Ed
> > +.Pp
> > +In contrast, the following command in sh(1) will open up a detached
> > +tmux session, then split the window, then attach to the session:
> > +.Bd -literal -offset indent
> > +tmux new-session -d vim \\; split-window \\; attach
> > +.Ed
> > +.Pp
> > +This is exactly equivalent to the running each of the following in
> > +the shell:
> > +.Bd -literal -offset indent
> > +tmux new-session -d vim
> > +tmux split-window
> > +tmux attach
> > +.Ed
> 
> I don't think we need all this text, 

I would have found it really helpful when I was learning tmux; I
doubt I'm the stupidest person who will ever use it. :)  I've
trimmed it greatly, though.

> I think it would be
> sufficient just to modify the examples:
> 
> Examples include:
> .Bd -literal -offset indent
> refresh-client -t/dev/ttyp2
> 
> set-window-option -t:0 monitor-activity on
> 
> new-window ; split-window -d
> .Ed
> 
> Or from
> .Xr sh 1 :
> .Bd -literal -offset indent
> $ tmux kill-window -t :1
> 
> $ tmux new-window \; split-window -d
> .Ed

Expanded on that a bit, but yeah.

> >  .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 shell-command's output"
> 
> I'd use #(shell-command) but say "First line of a command's output".

Yeah, was kinda iffy on that one myself.

New version attached.

-Robin

-- 
They say:  "The first AIs will be built by the military as weapons."
And I'm  thinking:  "Does it even occur to you to try for something
other  than  the default  outcome?"  See http://shrunklink.com/cdiz
http://www.digitalkingdom.org/~rlpowell/ *** http://www.lojban.org/
Index: tmux.1
===================================================================
RCS file: /cvsroot/tmux/tmux/tmux.1,v
retrieving revision 1.221
diff -u -r1.221 tmux.1
--- tmux.1      19 Jan 2010 00:46:30 -0000      1.221
+++ tmux.1      23 Jan 2010 19:53:23 -0000
@@ -111,6 +111,8 @@
 server will be started to retrieve the
 .Ic default-shell
 option.
+This is used when tmux is set as the login shell, since external
+tools expect -c to work with any shell.
 .It Fl f Ar file
 Specify an alternative configuration file.
 By default,
@@ -335,6 +337,31 @@
 .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
+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;
@@ -342,8 +369,14 @@
 A literal semicolon may be included by escaping it with a backslash (for
 example, when specifying a command sequence to
 .Ic bind-key ) .
+Note that all the commands, and the semicolons, must be separate words when
+running a tmux command sequence from a shell.
+
+tmux 'new-session -d vim ; split-window ; attach'
+tmux new-session -d vim \\; split-window \\; attach
+
 .Pp
-Examples include:
+Examples of tmux commands include:
 .Bd -literal -offset indent
 refresh-client -t/dev/ttyp2
 
@@ -352,7 +385,22 @@
 set-window-option -t:0 monitor-activity on
 
 new-window ; split-window -d
+
+.Ed
+.Pp
+Or from
+.Xr sh 1 :
+.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
+.Pp
+See the
+.Sx EXAMPLES
+section for more.
 .Sh CLIENTS AND SESSIONS
 The following commands are available:
 .Bl -tag -width Ds
@@ -417,7 +465,7 @@
 .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
@@ -427,8 +475,8 @@
 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
@@ -449,7 +497,7 @@
 Giving
 .Fl n
 or
-.Ar command
+.Ar shell-command
 are invalid if
 .Fl t
 is used.
@@ -817,6 +865,13 @@
 .Ar src-window
 to the specified
 .Ar dst-window .
+Since tmux has no concept of windows belonging to a particular
+session, only links from sessions to windows, this means that both
+the "old" and "new" locations for the window work just the same as
+every other window, and everything done to the window from any link
+is reflected in every other link.  This can be done across sessions,
+to create a window that can be interacted with from multiple
+sessions.
 If
 .Ar dst-window
 is specified and no such window exists, the
@@ -854,7 +909,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.
@@ -866,11 +921,11 @@
 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 default-command option is used.
 .Pp
 The
 .Ev TERM
@@ -898,7 +953,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
@@ -906,10 +961,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
@@ -957,14 +1012,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
@@ -1003,7 +1058,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
@@ -1344,10 +1399,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.
@@ -1414,7 +1469,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
@@ -1565,7 +1620,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"
@@ -1577,8 +1632,8 @@
 .It Li "##" Ta "A literal" Ql #
 .El
 .Pp
-The #(command) form executes
-.Ql command
+The #(shell-command) form executes
+.Ql shell-command
 as a shell command and inserts the first line of its output.
 Note that shell commands are only executed once at the interval specified by
 the
@@ -2245,14 +2300,16 @@
 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.
+After the 
+.Ar shell-command
+finishes, any output to stdout is displayed in output mode.
 If
-.Ar command
+.Ar shell-command
 doesn't return success, the exit status is also displayed.
 .It Ic server-info
 .D1 (alias: Ic info )
------------------------------------------------------------------------------
Throughout its 18-year history, RSA Conference consistently attracts the
world's best and brightest in the field, creating opportunities for Conference
attendees to learn about information security's most important issues through
interactions with peers, luminaries and emerging and established companies.
http://p.sf.net/sfu/rsaconf-dev2dev
_______________________________________________
tmux-users mailing list
tmux-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/tmux-users

Reply via email to