Update tmux.1.

tmux.1

@@ -442,16 +442,15 @@ are arguments.
 .Pp
 .Nm
 distinguishes between command parsing and execution.
-In order to execute a command,
+When commands are run from the shell, the shell parses its command line first;
-.Nm
+from inside
-needs it to be split up into its name and arguments.
-This is command parsing.
-If a command is run from the shell, the shell parses it; from inside
 .Nm
 or from a configuration file,
 .Nm
-does.
+parses the
-Examples of when
+.Nm
+command language.
+Examples of places where
 .Nm
 parses commands are:
 .Bl -dash -offset indent
@@ -470,42 +469,60 @@ or
 .Ic confirm\-before .
 .El
 .Pp
-To execute commands, each client has a
+Some commands accept other
-.Ql command queue .
+.Nm
-A global command queue not attached to any client is used on startup
+commands as arguments.
-for configuration files like
+For example,
-.Pa \[ti]/.tmux.conf .
-Parsed commands added to the queue are executed in order.
-Some commands, like
-.Ic if\-shell
-and
-.Ic confirm\-before ,
-parse their argument to create a new command which is inserted immediately
-after themselves.
-This means that arguments can be parsed twice or more - once when the parent
-command (such as
-.Ic if\-shell )
-is parsed and again when it parses and executes its command.
-Commands like
 .Ic if\-shell ,
 .Ic run\-shell
+.Fl C
 and
-.Ic display\-panes
+.Ic confirm\-before
-stop execution of subsequent commands on the queue until something happens -
+take a command to run later.
+That command may be given as a string or as a command list in braces.
+Braces avoid the need for extra escaping when the argument contains
+.Nm
+commands.
+For example:
+.Bd -literal -offset indent
+if\-shell true { display \-p \[aq]it worked\[aq] }
+.Ed
+.Pp
+is equivalent to:
+.Bd -literal -offset indent
+if\-shell true "display \-p \[aq]it worked\[aq]"
+.Ed
+.Pp
+Commands given as strings to commands such as
+.Ic if\-shell ,
+.Ic run\-shell
+.Fl C
+or
+.Ic confirm\-before
+are parsed when they are run.
+Commands given in braces are parsed when the outer command is parsed.
+.Pp
+Commands are executed in order.
+Commands like
 .Ic if\-shell
 and
 .Ic run\-shell
-until a shell command finishes and
+may run other commands before later commands continue.
+Commands such as
+.Ic if\-shell
+and
+.Ic run\-shell
+wait for a shell command to finish before continuing, and
 .Ic display\-panes
-until a key is pressed.
+waits for a key to be pressed.
 For example, the following commands:
 .Bd -literal -offset indent
 new\-session; new\-window
-if\-shell "true" "split\-window"
+if\-shell "true" { split\-window }
 kill\-session
 .Ed
 .Pp
-Will execute
+execute
 .Ic new\-session ,
 .Ic new\-window ,
 .Ic if\-shell ,
@@ -516,6 +533,14 @@ and
 .Ic kill\-session
 in that order.
 .Pp
+Commands separated by semicolons are in the same command sequence.
+If a command fails, any following commands in that sequence are skipped, but
+later command sequences continue.
+Newlines normally start a new command sequence, so a failure on one line does
+not skip commands on later lines.
+When a string argument is parsed as commands, its commands are parsed as one
+sequence even if the string contains newlines.
+.Pp
 The
 .Sx COMMANDS
 section lists the
@@ -532,10 +557,8 @@ or
 .Xr csh 1 .
 .Pp
 Each command is terminated by a newline or a semicolon (;).
-Commands separated by semicolons together form a
+A newline starts a new command sequence; commands separated by semicolons are
-.Ql command sequence
+in the same command sequence.
-- if a command in the sequence encounters an error, no subsequent commands are
-executed.
 .Pp
 It is recommended that a semicolon used as a command separator should be
 written as an individual token, for example from
@@ -604,33 +627,38 @@ comment is ignored until the end of the line.
 If the last character of a line is \e, the line is joined with the following
 line (the \e and the newline are completely removed).
 This is called line continuation and applies both inside and outside quoted
-strings and in comments, but not inside braces.
+strings, in comments and inside braces.
 .Pp
-Command arguments may be specified as strings surrounded by single (\[aq])
+Command arguments may be strings surrounded by single (\[aq]) quotes or double
-quotes or double quotes (\[dq]), or as command lists surrounded by braces ({}).
+quotes (\[dq]).
 .\" "
-This is required when the argument contains any special character.
+Quoting or escaping is required when a string argument contains any special
+character.
 Single and double quoted strings cannot span multiple lines except with line
 continuation.
-Braces can span multiple lines.
+Some arguments may be command lists surrounded by braces ({}).
+Braces can span multiple lines and are parsed as
+.Nm
+command syntax.
 .Pp
-Outside of quotes and inside double quotes, these replacements are performed:
+Outside single quotes, these replacements are recognized:
 .Bl -dash -offset indent
 .It
-Environment variables preceded by $ are replaced with their value from the
+Environment variables preceded by $ are replaced when the command is run
-global environment (see the
+with their value from the client environment, if present, or the global
+environment (see the
 .Sx GLOBAL AND SESSION ENVIRONMENT
 section).
 .It
-A leading \[ti] or \[ti]user is expanded to the home directory of the current or
+A leading \[ti] or \[ti]user is replaced when the command is run by the
-specified user.
+home directory of the current or specified user.
 .It
 \euXXXX or \euXXXXXXXX is replaced by the Unicode codepoint corresponding to
 the given four or eight digit hexadecimal number.
 .It
-When preceded (escaped) by a \e, the following characters are replaced: \ee by
+When preceded (escaped) by a \e, the following characters are replaced: \ea by
-the escape character; \er by a carriage return; \en by a newline; and \et by a
+bell; \eb by backspace; \ee by escape; \ef by form feed; \er by carriage
-tab.
+return; \en by newline; \es by space; \et by tab; and \ev by vertical tab.
 .It
 \eooo is replaced by a character of the octal value ooo.
 Three octal digits are required, for example \e001.
@@ -642,16 +670,12 @@ is removed) and are not treated as having any special meaning - so for example
 variable.
 .El
 .Pp
-Braces are parsed as a configuration file (so conditions such as
+Braces are designed to avoid additional escaping when passing a group of
-.Ql %if
-are processed) and then converted into a string.
-They are designed to avoid the need for additional escaping when passing a
-group of
 .Nm
 commands as an argument (for example to
 .Ic if\-shell ) .
-These two examples produce an identical command - note that no escaping is
+These two examples have the same effect - note that no escaping is needed when
-needed when using {}:
+using {}:
 .Bd -literal -offset indent
 if\-shell true {
     display \-p \[aq]brace\-dollar\-foo: }$foo\[aq]
@@ -673,7 +697,8 @@ Environment variables may be set by using the syntax
 .Ql name=value ,
 for example
 .Ql HOME=/home/user .
-Variables set during parsing are added to the global environment.
+Variables set this way are added to the global environment when the command is
+run.
 A hidden variable may be set with
 .Ql %hidden ,
 for example:
@@ -687,7 +712,7 @@ See the
 .Sx GLOBAL AND SESSION ENVIRONMENT
 section.
 .Pp
-Commands may be parsed conditionally by surrounding them with
+Commands may be made conditional by surrounding them with
 .Ql %if ,
 .Ql %elif ,
 .Ql %else
@@ -697,14 +722,11 @@ The argument to
 .Ql %if
 and
 .Ql %elif
-is expanded as a format (see
+is expanded as a format when it is evaluated (see
 .Sx FORMATS )
-and if it evaluates to false (zero or empty), subsequent text is ignored until
+and the first true branch is executed.
-the closing
+Branches which are not selected are not executed.
-.Ql %elif ,
+All branches must still be syntactically valid.
-.Ql %else
-or
-.Ql %endif .
 For example:
 .Bd -literal -offset indent
 %if "#{==:#{host},myhost}"
@@ -4387,7 +4409,7 @@ to list from.
 .Fl 1
 lists only the first matching key.
 .Fl p
-allows each command to use multiple lines.
+prints each command using multiple lines where possible.
 .Fl O
 specifies the sort order: one of
 .Ql key ,
@@ -4751,10 +4773,16 @@ length.
 .Ar name=value
 .Xc
 This is an array of custom aliases for commands.
-If an unknown command matches
+If a command name matches
 .Ar name ,
-it is replaced with
+the alias
-.Ar value .
+.Ar value
+is parsed as
+.Nm
+commands and used instead.
+Any arguments after
+.Ar name
+are appended to the last command in the alias.
 For example, after:
 .Pp
 .Dl set \-s command\-alias[zoom] zoom=\[aq]resize\-pane \-Z\[aq]
@@ -4767,10 +4795,9 @@ Is equivalent to:
 .Pp
 .Dl resize\-pane \-Z \-t:.1
 .Pp
-Note that aliases are expanded when a command is parsed rather than when it is
+Aliases are expanded when commands are run, so a change to
-executed, so binding an alias with
+.Ic command\-alias[]
-.Ic bind\-key
+affects stored commands such as key bindings when they are next run.
-will bind the expanded form.
 .It Ic codepoint\-widths[] Ar string
 An array option allowing widths of Unicode codepoints to be overridden.
 Note the new width applies to all clients.