From e776e4f45e20c1218b62ad95ab5445432a7b643f Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Thu, 20 Mar 2025 23:04:28 +0100
Subject: [PATCH 1/5] Fix documentation around optional arguments
This includes:
- Syncing between the usage string in code and in the manpage
- Adding optional arguments that were simply not mentioned (e.g.
shell-command arguments)
- Adding square brackets around arguments that are actually optional
Co-authored-by: Julian Prein <julian@druck.dev>
---
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-send-keys.c | 2 +-
cmd-set-buffer.c | 2 +-
cmd-show-options.c | 2 +-
cmd-split-window.c | 2 +-
tmux.1 | 31 ++++++++++++++++++-------------
11 files changed, 30 insertions(+), 24 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 5e742ce1..ce1f1ccc 100644
--- a/cmd-display-menu.c
+++ b/cmd-display-menu.c
@@ -42,7 +42,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 },
@@ -59,7 +59,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-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 252a33c6..56f8178f 100644
--- a/cmd-show-options.c
+++ b/cmd-show-options.c
@@ -65,7 +65,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 5cddbbd4..3d366a00 100644
--- a/cmd-split-window.c
+++ b/cmd-split-window.c
@@ -42,7 +42,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 483e3987..5baf2b79 100644
--- a/tmux.1
+++ b/tmux.1
@@ -1247,7 +1247,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
@@ -3088,7 +3088,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.
@@ -3336,7 +3336,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
@@ -3362,7 +3362,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
@@ -3490,10 +3490,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
@@ -3673,7 +3673,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
@@ -3732,7 +3733,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
@@ -3771,7 +3773,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.
@@ -3924,7 +3926,8 @@ Commands which set options are as follows:
.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
@@ -5460,7 +5463,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 ,
@@ -5481,6 +5484,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
@@ -6652,7 +6656,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
@@ -6825,7 +6830,7 @@ 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
From 840a826fa34b74cf98f0b530ceb191c2746a2f1d Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Thu, 20 Mar 2025 23:04:46 +0100
Subject: [PATCH 2/5] Fix run-shell's maximum argument count
Co-authored-by: Julian Prein <julian@druck.dev>
---
cmd-run-shell.c | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
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]",
From 569bef01f9903e3417290715cf9b03f09514b75f Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Thu, 20 Mar 2025 23:04:53 +0100
Subject: [PATCH 3/5] Document default-command as display-popup's fallback
Co-authored-by: Julian Prein <julian@druck.dev>
---
tmux.1 | 4 +++-
1 file changed, 3 insertions(+), 1 deletion(-)
diff --git a/tmux.1 b/tmux.1
index 5baf2b79..1b4ff289 100644
--- a/tmux.1
+++ b/tmux.1
@@ -6835,7 +6835,9 @@ forwards any input read from stdin to the empty pane given by
.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.
From 217c56dd238f0d9aab9422bfa7c5d748311bdf4d Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Fri, 21 Mar 2025 00:07:18 +0100
Subject: [PATCH 4/5] Improve the documentation of bright colours slightly
Before it seemed as if bright{red,green,yellow} were the only possible
bright colours.
Co-authored-by: Julian Prein <julian@druck.dev>
---
tmux.1 | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/tmux.1 b/tmux.1
index 1b4ff289..d41315af 100644
--- a/tmux.1
+++ b/tmux.1
@@ -6141,9 +6141,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
From c258ed209a3c5f96a9293ff4004abd6526cf9628 Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Fri, 21 Mar 2025 00:09:53 +0100
Subject: [PATCH 5/5] Improve documentation on the type of options
To be more close to the implementation, use 'scope' for what was
previously called 'type', and improve the documentation on the actual
option types (i.e. flag, choices, ...).
Rephrase the sentence before {set,show}-options commands to be similar
to the one in the HOOKS section, since show-options does not actually
set options.
Co-authored-by: Julian Prein <julian@druck.dev>
---
tmux.1 | 55 ++++++++++++++++++++++++++++++++++++++++++++-----------
1 file changed, 44 insertions(+), 11 deletions(-)
diff --git a/tmux.1 b/tmux.1
index d41315af..2d8b935e 100644
--- a/tmux.1
+++ b/tmux.1
@@ -3850,13 +3850,45 @@ option prevents errors being returned.
.Sh OPTIONS
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 ,
+may be modified by changing the value of various 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
@@ -3920,7 +3952,7 @@ $ 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
@@ -3943,7 +3975,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 +3996,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 it's value (choice options toggle between the first two
+choices).
.Pp
The
.Fl o
@@ -4020,7 +4053,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