From b526e678b50e197fdc9e70ff072f75abd1167a26 Mon Sep 17 00:00:00 2001
From: nicm <nicm>
Date: Wed, 9 Apr 2025 06:27:43 +0000
Subject: [PATCH 1/3] Make some usages more consistent and add -h to show
 usage, GitHub issue 4455 from David Mandelberg.

---
 cmd-command-prompt.c      |  2 +-
 cmd-confirm-before.c      |  2 +-
 cmd-set-environment.c     |  2 +-
 cmd-show-environment.c    |  2 +-
 cmd-show-prompt-history.c |  4 ++--
 tmux.c                    | 20 +++++++++++---------
 6 files changed, 17 insertions(+), 15 deletions(-)

diff --git a/cmd-command-prompt.c b/cmd-command-prompt.c
index 60f7ca37..36a1f03c 100644
--- a/cmd-command-prompt.c
+++ b/cmd-command-prompt.c
@@ -44,7 +44,7 @@ const struct cmd_entry cmd_command_prompt_entry = {
 
 	.args = { "1bFkiI:Np:t:T:", 0, 1, cmd_command_prompt_args_parse },
 	.usage = "[-1bFkiN] [-I inputs] [-p prompts] " CMD_TARGET_CLIENT_USAGE
-		 " [-T type] [template]",
+		 " [-T prompt-type] [template]",
 
 	.flags = CMD_CLIENT_TFLAG,
 	.exec = cmd_command_prompt_exec
diff --git a/cmd-confirm-before.c b/cmd-confirm-before.c
index af630b1e..1f592ae0 100644
--- a/cmd-confirm-before.c
+++ b/cmd-confirm-before.c
@@ -42,7 +42,7 @@ const struct cmd_entry cmd_confirm_before_entry = {
 	.alias = "confirm",
 
 	.args = { "bc:p:t:y", 1, 1, cmd_confirm_before_args_parse },
-	.usage = "[-by] [-c confirm_key] [-p prompt] " CMD_TARGET_CLIENT_USAGE
+	.usage = "[-by] [-c confirm-key] [-p prompt] " CMD_TARGET_CLIENT_USAGE
 		 " command",
 
 	.flags = CMD_CLIENT_TFLAG,
diff --git a/cmd-set-environment.c b/cmd-set-environment.c
index cec1f3e3..78c32452 100644
--- a/cmd-set-environment.c
+++ b/cmd-set-environment.c
@@ -35,7 +35,7 @@ const struct cmd_entry cmd_set_environment_entry = {
 	.alias = "setenv",
 
 	.args = { "Fhgrt:u", 1, 2, NULL },
-	.usage = "[-Fhgru] " CMD_TARGET_SESSION_USAGE " name [value]",
+	.usage = "[-Fhgru] " CMD_TARGET_SESSION_USAGE " variable [value]",
 
 	.target = { 't', CMD_FIND_SESSION, CMD_FIND_CANFAIL },
 
diff --git a/cmd-show-environment.c b/cmd-show-environment.c
index b52db366..3440c33e 100644
--- a/cmd-show-environment.c
+++ b/cmd-show-environment.c
@@ -39,7 +39,7 @@ const struct cmd_entry cmd_show_environment_entry = {
 	.alias = "showenv",
 
 	.args = { "hgst:", 0, 1, NULL },
-	.usage = "[-hgs] " CMD_TARGET_SESSION_USAGE " [name]",
+	.usage = "[-hgs] " CMD_TARGET_SESSION_USAGE " [variable]",
 
 	.target = { 't', CMD_FIND_SESSION, CMD_FIND_CANFAIL },
 
diff --git a/cmd-show-prompt-history.c b/cmd-show-prompt-history.c
index c85950b0..1b95bcaf 100644
--- a/cmd-show-prompt-history.c
+++ b/cmd-show-prompt-history.c
@@ -32,7 +32,7 @@ const struct cmd_entry cmd_show_prompt_history_entry = {
 	.alias = "showphist",
 
 	.args = { "T:", 0, 0, NULL },
-	.usage = "[-T type]",
+	.usage = "[-T prompt-type]",
 
 	.flags = CMD_AFTERHOOK,
 	.exec = cmd_show_prompt_history_exec
@@ -43,7 +43,7 @@ const struct cmd_entry cmd_clear_prompt_history_entry = {
 	.alias = "clearphist",
 
 	.args = { "T:", 0, 0, NULL },
-	.usage = "[-T type]",
+	.usage = "[-T prompt-type]",
 
 	.flags = CMD_AFTERHOOK,
 	.exec = cmd_show_prompt_history_exec
diff --git a/tmux.c b/tmux.c
index 38ffa05c..28cb9f70 100644
--- a/tmux.c
+++ b/tmux.c
@@ -47,20 +47,20 @@ const char	*socket_path;
 int		 ptm_fd = -1;
 const char	*shell_command;
 
-static __dead void	 usage(void);
+static __dead void	 usage(int);
 static char		*make_label(const char *, char **);
 
 static int		 areshell(const char *);
 static const char	*getshell(void);
 
 static __dead void
-usage(void)
+usage(int status)
 {
-	fprintf(stderr,
-	    "usage: %s [-2CDlNuVv] [-c shell-command] [-f file] [-L socket-name]\n"
+	fprintf(status ? stderr : stdout,
+	    "usage: %s [-2CDhlNuVv] [-c shell-command] [-f file] [-L socket-name]\n"
 	    "            [-S socket-path] [-T features] [command [flags]]\n",
 	    getprogname());
-	exit(1);
+	exit(status);
 }
 
 static const char *
@@ -389,7 +389,7 @@ main(int argc, char **argv)
 		environ_set(global_environ, "PWD", 0, "%s", cwd);
 	expand_paths(TMUX_CONF, &cfg_files, &cfg_nfiles, 1);
 
-	while ((opt = getopt(argc, argv, "2c:CDdf:lL:NqS:T:uUvV")) != -1) {
+	while ((opt = getopt(argc, argv, "2c:CDdf:hlL:NqS:T:uUvV")) != -1) {
 		switch (opt) {
 		case '2':
 			tty_add_features(&feat, "256", ":,");
@@ -418,6 +418,8 @@ main(int argc, char **argv)
 			cfg_files[cfg_nfiles++] = xstrdup(optarg);
 			cfg_quiet = 0;
 			break;
+		case 'h':
+			usage(0);
 		case 'V':
 			printf("tmux %s\n", getversion());
 			exit(0);
@@ -447,16 +449,16 @@ main(int argc, char **argv)
 			log_add_level();
 			break;
 		default:
-			usage();
+			usage(1);
 		}
 	}
 	argc -= optind;
 	argv += optind;
 
 	if (shell_command != NULL && argc != 0)
-		usage();
+		usage(1);
 	if ((flags & CLIENT_NOFORK) && argc != 0)
-		usage();
+		usage(1);
 
 	if ((ptm_fd = getptmfd()) == -1)
 		err(1, "getptmfd");

From 3e14e7c48b3e6c348a9abe7b867394449b397d86 Mon Sep 17 00:00:00 2001
From: nicm <nicm>
Date: Wed, 9 Apr 2025 06:51:31 +0000
Subject: [PATCH 2/3] Formats can use environment variables, from David
 Mandelberg.

---
 tmux.1 | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/tmux.1 b/tmux.1
index 33410173..2e4cbaa5 100644
--- a/tmux.1
+++ b/tmux.1
@@ -23,7 +23,7 @@
 .Sh SYNOPSIS
 .Nm tmux
 .Bk -words
-.Op Fl 2CDlNuVv
+.Op Fl 2CDhlNuVv
 .Op Fl c Ar shell-command
 .Op Fl f Ar file
 .Op Fl L Ar socket-name
@@ -154,6 +154,8 @@ command may be used to load a file later.
 .Nm
 shows any error messages from commands in configuration files in the first
 session created, and continues to process the rest of the configuration file.
+.It Fl h
+Print usage information and exit.
 .It Fl L Ar socket-name
 .Nm
 stores the server socket in a directory under
@@ -5576,7 +5578,8 @@ for example
 .Ql #{session_name} .
 The possible variables are listed in the table below, or the name of a
 .Nm
-option may be used for an option's value.
+option may be used for an option's value, or the name of an environment
+variable.
 Some variables have a shorter alias such as
 .Ql #S ;
 .Ql ##
@@ -6384,7 +6387,7 @@ Commands to alter and view the environment are:
 .It Xo Ic set-environment
 .Op Fl Fhgru
 .Op Fl t Ar target-session
-.Ar name Op Ar value
+.Ar variable Op Ar value
 .Xc
 .D1 Pq alias: Ic setenv
 Set or unset an environment variable.

From 68ffe654990764ed5bdb7efb88e4d01b921fd3d5 Mon Sep 17 00:00:00 2001
From: nicm <nicm>
Date: Wed, 9 Apr 2025 07:03:04 +0000
Subject: [PATCH 3/3] Fix documentation around optional arguments. This
 includes:

- Syncing between the usage string in code and in the man page.
- Adding optional arguments that were not mentioned (such as
  shell-command arguments).
- Adding square brackets around arguments that are actually optional.

From Julian Prein (julian at druck dot dev) in GitHub issue 4419.
---
 cmd-bind-key.c       |  2 +-
 cmd-display-menu.c   |  4 +-
 cmd-new-session.c    |  2 +-
 cmd-new-window.c     |  3 +-
 cmd-respawn-pane.c   |  2 +-
 cmd-respawn-window.c |  2 +-
 cmd-run-shell.c      |  2 +-
 cmd-send-keys.c      |  2 +-
 cmd-set-buffer.c     |  2 +-
 cmd-show-options.c   |  2 +-
 cmd-split-window.c   |  2 +-
 tmux.1               | 93 +++++++++++++++++++++++++++++++-------------
 12 files changed, 80 insertions(+), 38 deletions(-)

diff --git a/cmd-bind-key.c b/cmd-bind-key.c
index dab03b01..01f8e961 100644
--- a/cmd-bind-key.c
+++ b/cmd-bind-key.c
@@ -38,7 +38,7 @@ const struct cmd_entry cmd_bind_key_entry = {
 
 	.args = { "nrN:T:", 1, -1, cmd_bind_key_args_parse },
 	.usage = "[-nr] [-T key-table] [-N note] key "
-	         "[command [arguments]]",
+	         "[command [argument ...]]",
 
 	.flags = CMD_AFTERHOOK,
 	.exec = cmd_bind_key_exec
diff --git a/cmd-display-menu.c b/cmd-display-menu.c
index ac136766..ab1b7047 100644
--- a/cmd-display-menu.c
+++ b/cmd-display-menu.c
@@ -43,7 +43,7 @@ const struct cmd_entry cmd_display_menu_entry = {
 	.usage = "[-MO] [-b border-lines] [-c target-client] "
 		 "[-C starting-choice] [-H selected-style] [-s style] "
 		 "[-S border-style] " CMD_TARGET_PANE_USAGE " [-T title] "
-		 "[-x position] [-y position] name key command ...",
+		 "[-x position] [-y position] name [key] [command] ...",
 
 	.target = { 't', CMD_FIND_PANE, 0 },
 
@@ -60,7 +60,7 @@ const struct cmd_entry cmd_display_popup_entry = {
 		 "[-d start-directory] [-e environment] [-h height] "
 		 "[-s style] [-S border-style] " CMD_TARGET_PANE_USAGE
 		 " [-T title] [-w width] [-x position] [-y position] "
-		 "[shell-command]",
+		 "[shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_PANE, 0 },
 
diff --git a/cmd-new-session.c b/cmd-new-session.c
index c90369bc..06082653 100644
--- a/cmd-new-session.c
+++ b/cmd-new-session.c
@@ -43,7 +43,7 @@ const struct cmd_entry cmd_new_session_entry = {
 	.usage = "[-AdDEPX] [-c start-directory] [-e environment] [-F format] "
 		 "[-f flags] [-n window-name] [-s session-name] "
 		 CMD_TARGET_SESSION_USAGE " [-x width] [-y height] "
-		 "[shell-command]",
+		 "[shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_SESSION, CMD_FIND_CANFAIL },
 
diff --git a/cmd-new-window.c b/cmd-new-window.c
index f2d932de..dd64baab 100644
--- a/cmd-new-window.c
+++ b/cmd-new-window.c
@@ -40,7 +40,8 @@ const struct cmd_entry cmd_new_window_entry = {
 
 	.args = { "abc:de:F:kn:PSt:", 0, -1, NULL },
 	.usage = "[-abdkPS] [-c start-directory] [-e environment] [-F format] "
-		 "[-n window-name] " CMD_TARGET_WINDOW_USAGE " [shell-command]",
+		 "[-n window-name] " CMD_TARGET_WINDOW_USAGE
+		 " [shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_WINDOW, CMD_FIND_WINDOW_INDEX },
 
diff --git a/cmd-respawn-pane.c b/cmd-respawn-pane.c
index 6d60002e..1e1dd4c6 100644
--- a/cmd-respawn-pane.c
+++ b/cmd-respawn-pane.c
@@ -36,7 +36,7 @@ const struct cmd_entry cmd_respawn_pane_entry = {
 
 	.args = { "c:e:kt:", 0, -1, NULL },
 	.usage = "[-k] [-c start-directory] [-e environment] "
-		 CMD_TARGET_PANE_USAGE " [shell-command]",
+		 CMD_TARGET_PANE_USAGE " [shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_PANE, 0 },
 
diff --git a/cmd-respawn-window.c b/cmd-respawn-window.c
index 9a1a02c9..e1eae0af 100644
--- a/cmd-respawn-window.c
+++ b/cmd-respawn-window.c
@@ -36,7 +36,7 @@ const struct cmd_entry cmd_respawn_window_entry = {
 
 	.args = { "c:e:kt:", 0, -1, NULL },
 	.usage = "[-k] [-c start-directory] [-e environment] "
-		 CMD_TARGET_WINDOW_USAGE " [shell-command]",
+		 CMD_TARGET_WINDOW_USAGE " [shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_WINDOW, 0 },
 
diff --git a/cmd-run-shell.c b/cmd-run-shell.c
index be4c7cac..4b4399c8 100644
--- a/cmd-run-shell.c
+++ b/cmd-run-shell.c
@@ -44,7 +44,7 @@ const struct cmd_entry cmd_run_shell_entry = {
 	.name = "run-shell",
 	.alias = "run",
 
-	.args = { "bd:Ct:c:", 0, 2, cmd_run_shell_args_parse },
+	.args = { "bd:Ct:c:", 0, 1, cmd_run_shell_args_parse },
 	.usage = "[-bC] [-c start-directory] [-d delay] " CMD_TARGET_PANE_USAGE
 	         " [shell-command]",
 
diff --git a/cmd-send-keys.c b/cmd-send-keys.c
index 35b3f140..aa7b22fd 100644
--- a/cmd-send-keys.c
+++ b/cmd-send-keys.c
@@ -35,7 +35,7 @@ const struct cmd_entry cmd_send_keys_entry = {
 
 	.args = { "c:FHKlMN:Rt:X", 0, -1, NULL },
 	.usage = "[-FHKlMRX] [-c target-client] [-N repeat-count] "
-	         CMD_TARGET_PANE_USAGE " key ...",
+	         CMD_TARGET_PANE_USAGE " [key ...]",
 
 	.target = { 't', CMD_FIND_PANE, 0 },
 
diff --git a/cmd-set-buffer.c b/cmd-set-buffer.c
index 35e72955..0b0ec3a2 100644
--- a/cmd-set-buffer.c
+++ b/cmd-set-buffer.c
@@ -35,7 +35,7 @@ const struct cmd_entry cmd_set_buffer_entry = {
 
 	.args = { "ab:t:n:w", 0, 1, NULL },
 	.usage = "[-aw] " CMD_BUFFER_USAGE " [-n new-buffer-name] "
-	         CMD_TARGET_CLIENT_USAGE " data",
+	         CMD_TARGET_CLIENT_USAGE " [data]",
 
 	.flags = CMD_AFTERHOOK|CMD_CLIENT_TFLAG|CMD_CLIENT_CANFAIL,
 	.exec = cmd_set_buffer_exec
diff --git a/cmd-show-options.c b/cmd-show-options.c
index 0e7e5192..68494060 100644
--- a/cmd-show-options.c
+++ b/cmd-show-options.c
@@ -66,7 +66,7 @@ const struct cmd_entry cmd_show_hooks_entry = {
 	.alias = NULL,
 
 	.args = { "gpt:w", 0, 1, NULL },
-	.usage = "[-gpw] " CMD_TARGET_PANE_USAGE,
+	.usage = "[-gpw] " CMD_TARGET_PANE_USAGE " [hook]",
 
 	.target = { 't', CMD_FIND_PANE, CMD_FIND_CANFAIL },
 
diff --git a/cmd-split-window.c b/cmd-split-window.c
index 128e9e8b..bbec0cc8 100644
--- a/cmd-split-window.c
+++ b/cmd-split-window.c
@@ -43,7 +43,7 @@ const struct cmd_entry cmd_split_window_entry = {
 	.args = { "bc:de:fF:hIl:p:Pt:vZ", 0, -1, NULL },
 	.usage = "[-bdefhIPvZ] [-c start-directory] [-e environment] "
 		 "[-F format] [-l size] " CMD_TARGET_PANE_USAGE
-		 " [shell-command]",
+		 " [shell-command [argument ...]]",
 
 	.target = { 't', CMD_FIND_PANE, 0 },
 
diff --git a/tmux.1 b/tmux.1
index 2e4cbaa5..bd184811 100644
--- a/tmux.1
+++ b/tmux.1
@@ -1248,7 +1248,7 @@ Lock all clients attached to
 .Op Fl t Ar group-name
 .Op Fl x Ar width
 .Op Fl y Ar height
-.Op Ar shell-command
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic new
 Create a new session with name
@@ -3091,7 +3091,7 @@ option.
 .Op Fl F Ar format
 .Op Fl n Ar window-name
 .Op Fl t Ar target-window
-.Op Ar shell-command
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic neww
 Create a new window.
@@ -3339,7 +3339,7 @@ to manual in the window options.
 .Op Fl c Ar start-directory
 .Op Fl e Ar environment
 .Op Fl t Ar target-pane
-.Op Ar shell-command
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic respawnp
 Reactivate a pane in which the command has exited (see the
@@ -3365,7 +3365,7 @@ command.
 .Op Fl c Ar start-directory
 .Op Fl e Ar environment
 .Op Fl t Ar target-window
-.Op Ar shell-command
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic respawnw
 Reactivate a window in which the command has exited (see the
@@ -3493,10 +3493,10 @@ the command behaves like
 .Op Fl bdfhIvPZ
 .Op Fl c Ar start-directory
 .Op Fl e Ar environment
+.Op Fl F Ar format
 .Op Fl l Ar size
 .Op Fl t Ar target-pane
-.Op Ar shell-command
-.Op Fl F Ar format
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic splitw
 Create a new pane by splitting
@@ -3676,7 +3676,8 @@ Commands related to key bindings are as follows:
 .Op Fl nr
 .Op Fl N Ar note
 .Op Fl T Ar key-table
-.Ar key command Op Ar argument ...
+.Ar key
+.Op Ar command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic bind
 Bind key
@@ -3735,7 +3736,8 @@ command.
 .Tg lsk
 .It Xo Ic list-keys
 .Op Fl 1aN
-.Op Fl P Ar prefix-string Fl T Ar key-table
+.Op Fl P Ar prefix-string
+.Op Fl T Ar key-table
 .Op Ar key
 .Xc
 .D1 Pq alias: Ic lsk
@@ -3774,7 +3776,7 @@ lists the command for keys that do not have a note rather than skipping them.
 .Op Fl c Ar target-client
 .Op Fl N Ar repeat-count
 .Op Fl t Ar target-pane
-.Ar key ...
+.Op Ar key ...
 .Xc
 .D1 Pq alias: Ic send
 Send a key or keys to a window or client.
@@ -3852,12 +3854,44 @@ option prevents errors being returned.
 The appearance and behaviour of
 .Nm
 may be modified by changing the value of various options.
-There are four types of option:
-.Em server options ,
-.Em session options ,
-.Em window options ,
+Each option belongs to one or multiple scopes
+.Po
+.Em server ,
+.Em session ,
+.Em window ,
 and
-.Em pane options .
+.Em pane
+.Pc and has a type
+.Po
+.Em string ,
+.Em number ,
+.Em key ,
+.Em colour ,
+.Em flag ,
+.Em choice ,
+or
+.Em command
+.Pc . Values of
+.Em flag Ns -type
+options may be one of:
+.Ic 1 ,
+.Ic on ,
+.Ic yes ,
+.Ic 0 ,
+.Ic off ,
+or
+.Ic no ;
+for possible
+.Em choice
+values, see the respective option; for
+.Em key
+options, the
+.Sx KEY BINDINGS
+section; and for
+.Em colour
+options, the
+.Sx STYLES
+section.
 .Pp
 The
 .Nm
@@ -3921,13 +3955,14 @@ $ tmux show -wv @foo
 abc123
 .Ed
 .Pp
-Commands which set options are as follows:
+Options are managed with these commands:
 .Bl -tag -width Ds
 .Tg set
 .It Xo Ic set-option
 .Op Fl aFgopqsuUw
 .Op Fl t Ar target-pane
-.Ar option Ar value
+.Ar option
+.Op Ar value
 .Xc
 .D1 Pq alias: Ic set
 Set a pane option with
@@ -3943,7 +3978,7 @@ or
 .Fl s
 may be unnecessary -
 .Nm
-will infer the type from the option name, assuming
+will infer the scope from the option name, assuming
 .Fl w
 for pane options.
 If
@@ -3964,8 +3999,9 @@ unsets an option (like
 but if the option is a pane option also unsets the option on any panes in the
 window.
 .Ar value
-depends on the option and may be a number, a string, or a flag (on, off, or
-omitted to toggle).
+depends on the option and its type and can be omitted for flag and choice
+options to toggle its value (choice options toggle between the first two
+choices).
 .Pp
 The
 .Fl o
@@ -4020,7 +4056,7 @@ or
 .Fl s
 may be unnecessary -
 .Nm
-will infer the type from the option name, assuming
+will infer the scope from the option name, assuming
 .Fl w
 for pane options.
 Global session or window options are listed if
@@ -5467,7 +5503,7 @@ Hooks are managed with these commands:
 .Op Fl agpRuw
 .Op Fl t Ar target-pane
 .Ar hook-name
-.Ar command
+.Op Ar command
 .Xc
 Without
 .Fl R ,
@@ -5488,6 +5524,7 @@ immediately.
 .It Xo Ic show-hooks
 .Op Fl gpw
 .Op Fl t Ar target-pane
+.Op Ar hook
 .Xc
 Shows hooks.
 The flags are the same as for
@@ -6149,9 +6186,10 @@ The colour is one of:
 .Ic cyan ,
 .Ic white ;
 if supported the bright variants
+.Ic brightblack ,
 .Ic brightred ,
-.Ic brightgreen ,
-.Ic brightyellow ;
+.Eo ...;
+.Ec
 .Ic colour0
 to
 .Ic colour255
@@ -6664,7 +6702,8 @@ the default is
 .Op Fl y Ar position
 .Ar name
 .Ar key
-.Ar command Op Ar argument ...
+.Ar command
+.Op Ar name key command ...
 .Xc
 .D1 Pq alias: Ic menu
 Display a menu on
@@ -6837,12 +6876,14 @@ forwards any input read from stdin to the empty pane given by
 .Op Fl w Ar width
 .Op Fl x Ar position
 .Op Fl y Ar position
-.Op Ar shell-command
+.Op Ar shell-command Op Ar argument ...
 .Xc
 .D1 Pq alias: Ic popup
 Display a popup running
 .Ar shell-command
-on
+(or
+.Ar default-command
+when omitted) on
 .Ar target-client .
 A popup is a rectangular box drawn over the top of any panes.
 Panes are not updated while a popup is present.