Add a customize mode where options may be browsed and changed, includes adding

a brief description of each option. Bound to "C" by default.

19 files changed, 1754 insertions, 345 deletions

diff --git a/Makefile.am b/Makefile.am
index a395ecdb..fdd39107 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -180,6 +180,7 @@ dist_tmux_SOURCES = \
 	window-client.c \
 	window-clock.c \
 	window-copy.c \
+	window-customize.c \
 	window-tree.c \
 	window.c \
 	xmalloc.c \
diff --git a/cmd-choose-tree.c b/cmd-choose-tree.c
index 0ada8fd4..a58469ac 100644
--- a/cmd-choose-tree.c
+++ b/cmd-choose-tree.c
@@ -68,6 +68,19 @@ const struct cmd_entry cmd_choose_buffer_entry = {
 	.exec = cmd_choose_tree_exec
 };
 
+const struct cmd_entry cmd_customize_mode_entry = {
+	.name = "customize-mode",
+	.alias = NULL,
+
+	.args = { "F:f:Nt:Z", 0, 0 },
+	.usage = "[-NZ] [-F format] [-f filter] " CMD_TARGET_PANE_USAGE,
+
+	.target = { 't', CMD_FIND_PANE, 0 },
+
+	.flags = 0,
+	.exec = cmd_choose_tree_exec
+};
+
 static enum cmd_retval
 cmd_choose_tree_exec(struct cmd *self, struct cmdq_item *item)
 {
@@ -84,7 +97,9 @@ cmd_choose_tree_exec(struct cmd *self, struct cmdq_item *item)
 		if (server_client_how_many() == 0)
 			return (CMD_RETURN_NORMAL);
 		mode = &window_client_mode;
-	} else
+	} else if (cmd_get_entry(self) == &cmd_customize_mode_entry)
+		mode = &window_customize_mode;
+	else
 		mode = &window_tree_mode;
 
 	window_pane_set_mode(wp, NULL, mode, target, args);
diff --git a/cmd-set-option.c b/cmd-set-option.c
index e04aa7ff..6f4637d7 100644
--- a/cmd-set-option.c
+++ b/cmd-set-option.c
@@ -30,15 +30,6 @@
 
 static enum cmd_retval	cmd_set_option_exec(struct cmd *, struct cmdq_item *);
 
-static int	cmd_set_option_set(struct cmd *, struct cmdq_item *,
-		    struct options *, struct options_entry *, const char *);
-static int	cmd_set_option_flag(struct cmdq_item *,
-		    const struct options_table_entry *, struct options *,
-		    const char *);
-static int	cmd_set_option_choice(struct cmdq_item *,
-		    const struct options_table_entry *, struct options *,
-		    const char *);
-
 const struct cmd_entry cmd_set_option_entry = {
 	.name = "set-option",
 	.alias = "set",
@@ -138,7 +129,7 @@ cmd_set_option_exec(struct cmd *self, struct cmdq_item *item)
 	parent = options_get(oo, name);
 
 	/* Check that array options and indexes match up. */
-	if (idx != -1 && (*name == '@' || !options_isarray(parent))) {
+	if (idx != -1 && (*name == '@' || !options_is_array(parent))) {
 		cmdq_error(item, "not an array: %s", argument);
 		goto fail;
 	}
@@ -185,10 +176,15 @@ cmd_set_option_exec(struct cmd *self, struct cmdq_item *item)
 			goto fail;
 		}
 		options_set_string(oo, name, append, "%s", value);
-	} else if (idx == -1 && !options_isarray(parent)) {
-		error = cmd_set_option_set(self, item, oo, parent, value);
-		if (error != 0)
+	} else if (idx == -1 && !options_is_array(parent)) {
+		error = options_from_string(oo, options_table_entry(parent),
+		    options_table_entry(parent)->name, value,
+		    args_has(args, 'a'), &cause);
+		if (error != 0) {
+			cmdq_error(item, "%s", cause);
+			free(cause);
 			goto fail;
+		}
 	} else {
 		if (value == NULL) {
 			cmdq_error(item, "empty value");
@@ -212,51 +208,7 @@ cmd_set_option_exec(struct cmd *self, struct cmdq_item *item)
 		}
 	}
 
-	/* Update timers and so on for various options. */
-	if (strcmp(name, "automatic-rename") == 0) {
-		RB_FOREACH(w, windows, &windows) {
-			if (w->active == NULL)
-				continue;
-			if (options_get_number(w->options, "automatic-rename"))
-				w->active->flags |= PANE_CHANGED;
-		}
-	}
-	if (strcmp(name, "key-table") == 0) {
-		TAILQ_FOREACH(loop, &clients, entry)
-			server_client_set_key_table(loop, NULL);
-	}
-	if (strcmp(name, "user-keys") == 0) {
-		TAILQ_FOREACH(loop, &clients, entry) {
-			if (loop->tty.flags & TTY_OPENED)
-				tty_keys_build(&loop->tty);
-		}
-	}
-	if (strcmp(name, "status") == 0 ||
-	    strcmp(name, "status-interval") == 0)
-		status_timer_start_all();
-	if (strcmp(name, "monitor-silence") == 0)
-		alerts_reset_all();
-	if (strcmp(name, "window-style") == 0 ||
-	    strcmp(name, "window-active-style") == 0) {
-		RB_FOREACH(wp, window_pane_tree, &all_window_panes)
-			wp->flags |= PANE_STYLECHANGED;
-	}
-	if (strcmp(name, "pane-border-status") == 0) {
-		RB_FOREACH(w, windows, &windows)
-			layout_fix_panes(w);
-	}
-	RB_FOREACH(s, sessions, &sessions)
-		status_update_cache(s);
-
-	/*
-	 * Update sizes and redraw. May not always be necessary but do it
-	 * anyway.
-	 */
-	recalculate_sizes();
-	TAILQ_FOREACH(loop, &clients, entry) {
-		if (loop->session != NULL)
-			server_redraw_client(loop);
-	}
+	options_push_changes(name);
 
 out:
 	free(argument);
@@ -270,147 +222,3 @@ fail:
 	free(name);
 	return (CMD_RETURN_ERROR);
 }
-
-static int
-cmd_set_option_check_string(const struct options_table_entry *oe,
-    const char *value, char **cause)
-{
-	struct style	sy;
-
-	if (strcmp(oe->name, "default-shell") == 0 && !checkshell(value)) {
-		xasprintf(cause, "not a suitable shell: %s", value);
-		return (-1);
-	}
-	if (oe->pattern != NULL && fnmatch(oe->pattern, value, 0) != 0) {
-		xasprintf(cause, "value is invalid: %s", value);
-		return (-1);
-	}
-	if ((oe->flags & OPTIONS_TABLE_IS_STYLE) &&
-	    strstr(value, "#{") == NULL &&
-	    style_parse(&sy, &grid_default_cell, value) != 0) {
-		xasprintf(cause, "invalid style: %s", value);
-		return (-1);
-	}
-	return (0);
-}
-
-static int
-cmd_set_option_set(struct cmd *self, struct cmdq_item *item, struct options *oo,
-    struct options_entry *parent, const char *value)
-{
-	const struct options_table_entry	*oe;
-	struct args				*args = cmd_get_args(self);
-	int					 append = args_has(args, 'a');
-	long long				 number;
-	const char				*errstr, *new;
-	char					*old, *cause;
-	key_code				 key;
-
-	oe = options_table_entry(parent);
-	if (value == NULL &&
-	    oe->type != OPTIONS_TABLE_FLAG &&
-	    oe->type != OPTIONS_TABLE_CHOICE) {
-		cmdq_error(item, "empty value");
-		return (-1);
-	}
-
-	switch (oe->type) {
-	case OPTIONS_TABLE_STRING:
-		old = xstrdup(options_get_string(oo, oe->name));
-		options_set_string(oo, oe->name, append, "%s", value);
-		new = options_get_string(oo, oe->name);
-		if (cmd_set_option_check_string(oe, new, &cause) != 0) {
-			cmdq_error(item, "%s", cause);
-			free(cause);
-
-			options_set_string(oo, oe->name, 0, "%s", old);
-			free(old);
-			return (-1);
-		}
-		free(old);
-		return (0);
-	case OPTIONS_TABLE_NUMBER:
-		number = strtonum(value, oe->minimum, oe->maximum, &errstr);
-		if (errstr != NULL) {
-			cmdq_error(item, "value is %s: %s", errstr, value);
-			return (-1);
-		}
-		options_set_number(oo, oe->name, number);
-		return (0);
-	case OPTIONS_TABLE_KEY:
-		key = key_string_lookup_string(value);
-		if (key == KEYC_UNKNOWN) {
-			cmdq_error(item, "bad key: %s", value);
-			return (-1);
-		}
-		options_set_number(oo, oe->name, key);
-		return (0);
-	case OPTIONS_TABLE_COLOUR:
-		if ((number = colour_fromstring(value)) == -1) {
-			cmdq_error(item, "bad colour: %s", value);
-			return (-1);
-		}
-		options_set_number(oo, oe->name, number);
-		return (0);
-	case OPTIONS_TABLE_FLAG:
-		return (cmd_set_option_flag(item, oe, oo, value));
-	case OPTIONS_TABLE_CHOICE:
-		return (cmd_set_option_choice(item, oe, oo, value));
-	case OPTIONS_TABLE_COMMAND:
-		break;
-	}
-	return (-1);
-}
-
-static int
-cmd_set_option_flag(struct cmdq_item *item,
-    const struct options_table_entry *oe, struct options *oo,
-    const char *value)
-{
-	int	flag;
-
-	if (value == NULL || *value == '\0')
-		flag = !options_get_number(oo, oe->name);
-	else if (strcmp(value, "1") == 0 ||
-	    strcasecmp(value, "on") == 0 ||
-	    strcasecmp(value, "yes") == 0)
-		flag = 1;
-	else if (strcmp(value, "0") == 0 ||
-	    strcasecmp(value, "off") == 0 ||
-	    strcasecmp(value, "no") == 0)
-		flag = 0;
-	else {
-		cmdq_error(item, "bad value: %s", value);
-		return (-1);
-	}
-	options_set_number(oo, oe->name, flag);
-	return (0);
-}
-
-static int
-cmd_set_option_choice(struct cmdq_item *item,
-    const struct options_table_entry *oe, struct options *oo,
-    const char *value)
-{
-	const char	**cp;
-	int		  n, choice = -1;
-
-	if (value == NULL) {
-		choice = options_get_number(oo, oe->name);
-		if (choice < 2)
-			choice = !choice;
-	} else {
-		n = 0;
-		for (cp = oe->choices; *cp != NULL; cp++) {
-			if (strcmp(*cp, value) == 0)
-				choice = n;
-			n++;
-		}
-		if (choice == -1) {
-			cmdq_error(item, "unknown value: %s", value);
-			return (-1);
-		}
-	}
-	options_set_number(oo, oe->name, choice);
-	return (0);
-}
diff --git a/cmd-show-options.c b/cmd-show-options.c
index 1286037c..ed93311a 100644
--- a/cmd-show-options.c
+++ b/cmd-show-options.c
@@ -150,7 +150,7 @@ cmd_show_options_print(struct cmd *self, struct cmdq_item *item,
 		xasprintf(&tmp, "%s[%d]", name, idx);
 		name = tmp;
 	} else {
-		if (options_isarray(o)) {
+		if (options_is_array(o)) {
 			a = options_array_first(o);
 			if (a == NULL) {
 				if (!args_has(args, 'v'))
@@ -167,10 +167,10 @@ cmd_show_options_print(struct cmd *self, struct cmdq_item *item,
 		}
 	}
 
-	value = options_tostring(o, idx, 0);
+	value = options_to_string(o, idx, 0);
 	if (args_has(args, 'v'))
 		cmdq_print(item, "%s", value);
-	else if (options_isstring(o)) {
+	else if (options_is_string(o)) {
 		escaped = args_escape(value);
 		if (parent)
 			cmdq_print(item, "%s* %s", name, escaped);
@@ -228,7 +228,7 @@ cmd_show_options_all(struct cmd *self, struct cmdq_item *item, int scope,
 		} else
 			parent = 0;
 
-		if (!options_isarray(o))
+		if (!options_is_array(o))
 			cmd_show_options_print(self, item, o, -1, parent);
 		else if ((a = options_array_first(o)) == NULL) {
 			if (!args_has(args, 'v')) {
diff --git a/cmd.c b/cmd.c
index 9cd5ab49..09483680 100644
--- a/cmd.c
+++ b/cmd.c
@@ -39,6 +39,7 @@ extern const struct cmd_entry cmd_clock_mode_entry;
 extern const struct cmd_entry cmd_command_prompt_entry;
 extern const struct cmd_entry cmd_confirm_before_entry;
 extern const struct cmd_entry cmd_copy_mode_entry;
+extern const struct cmd_entry cmd_customize_mode_entry;
 extern const struct cmd_entry cmd_delete_buffer_entry;
 extern const struct cmd_entry cmd_detach_client_entry;
 extern const struct cmd_entry cmd_display_menu_entry;
@@ -129,6 +130,7 @@ const struct cmd_entry *cmd_table[] = {
 	&cmd_command_prompt_entry,
 	&cmd_confirm_before_entry,
 	&cmd_copy_mode_entry,
+	&cmd_customize_mode_entry,
 	&cmd_delete_buffer_entry,
 	&cmd_detach_client_entry,
 	&cmd_display_menu_entry,
diff --git a/format-draw.c b/format-draw.c
index 3751082e..bd32b2a8 100644
--- a/format-draw.c
+++ b/format-draw.c
@@ -547,7 +547,7 @@ format_draw(struct screen_write_ctx *octx, const struct grid_cell *base,
 	 */
 	cp = expanded;
 	while (*cp != '\0') {
-		if (cp[0] != '#' || cp[1] != '[') {
+		if (cp[0] != '#' || cp[1] != '[' || sy.ignore) {
 			/* See if this is a UTF-8 character. */
 			if ((more = utf8_open(ud, *cp)) == UTF8_MORE) {
 				while (*++cp != '\0' && more == UTF8_MORE)
diff --git a/format.c b/format.c
index 2c3e9046..3af7ae69 100644
--- a/format.c
+++ b/format.c
@@ -1392,7 +1392,7 @@ format_find(struct format_tree *ft, const char *key, int modifiers,
 	if (o == NULL)
 		o = options_parse_get(global_s_options, key, &idx, 0);
 	if (o != NULL) {
-		found = options_tostring(o, idx, 1);
+		found = options_to_string(o, idx, 1);
 		goto found;
 	}
 
diff --git a/key-bindings.c b/key-bindings.c
index 85bfb788..1847b6e6 100644
--- a/key-bindings.c
+++ b/key-bindings.c
@@ -278,6 +278,7 @@ key_bindings_init(void)
 		"bind -N 'Toggle the marked pane' m select-pane -m",
 		"bind -N 'Select the next window' n next-window",
 		"bind -N 'Select the next pane' o select-pane -t:.+",
+		"bind -N 'Customizeoptions' C customize-mode",
 		"bind -N 'Select the previous pane' p previous-window",
 		"bind -N 'Display pane numbers' q display-panes",
 		"bind -N 'Redraw the current client' r refresh-client",
diff --git a/mode-tree.c b/mode-tree.c
index c08c802d..8f7ba85f 100644
--- a/mode-tree.c
+++ b/mode-tree.c
@@ -45,6 +45,7 @@ struct mode_tree_data {
 	mode_tree_draw_cb         drawcb;
 	mode_tree_search_cb       searchcb;
 	mode_tree_menu_cb         menucb;
+	mode_tree_height_cb       heightcb;
 
 	struct mode_tree_list	  children;
 	struct mode_tree_list	  saved;
@@ -210,7 +211,7 @@ mode_tree_clear_tagged(struct mode_tree_list *mtl)
 	}
 }
 
-static void
+void
 mode_tree_up(struct mode_tree_data *mtd, int wrap)
 {
 	if (mtd->current == 0) {
@@ -343,7 +344,8 @@ mode_tree_each_tagged(struct mode_tree_data *mtd, mode_tree_each_cb cb,
 struct mode_tree_data *
 mode_tree_start(struct window_pane *wp, struct args *args,
     mode_tree_build_cb buildcb, mode_tree_draw_cb drawcb,
-    mode_tree_search_cb searchcb, mode_tree_menu_cb menucb, void *modedata,
+    mode_tree_search_cb searchcb, mode_tree_menu_cb menucb,
+    mode_tree_height_cb heightcb, void *modedata,
     const struct menu_item *menu, const char **sort_list, u_int sort_size,
     struct screen **s)
 {
@@ -381,6 +383,7 @@ mode_tree_start(struct window_pane *wp, struct args *args,
 	mtd->drawcb = drawcb;
 	mtd->searchcb = searchcb;
 	mtd->menucb = menucb;
+	mtd->heightcb = heightcb;
 
 	TAILQ_INIT(&mtd->children);
 
@@ -404,6 +407,27 @@ mode_tree_zoom(struct mode_tree_data *mtd, struct args *args)
 		mtd->zoomed = -1;
 }
 
+static void
+mode_tree_set_height(struct mode_tree_data *mtd)
+{
+	struct screen	*s = &mtd->screen;
+	u_int		 height;
+
+	if (mtd->heightcb != NULL) {
+		height = mtd->heightcb(mtd, screen_size_y(s));
+		if (height < screen_size_y(s))
+		    mtd->height = screen_size_y(s) - height;
+	} else {
+		mtd->height = (screen_size_y(s) / 3) * 2;
+		if (mtd->height > mtd->line_size)
+			mtd->height = screen_size_y(s) / 2;
+	}
+	if (mtd->height < 10)
+		mtd->height = screen_size_y(s);
+	if (screen_size_y(s) - mtd->height < 2)
+		mtd->height = screen_size_y(s);
+}
+
 void
 mode_tree_build(struct mode_tree_data *mtd)
 {
@@ -434,15 +458,9 @@ mode_tree_build(struct mode_tree_data *mtd)
 	mode_tree_set_current(mtd, tag);
 
 	mtd->width = screen_size_x(s);
-	if (mtd->preview) {
-		mtd->height = (screen_size_y(s) / 3) * 2;
-		if (mtd->height > mtd->line_size)
-			mtd->height = screen_size_y(s) / 2;
-		if (mtd->height < 10)
-			mtd->height = screen_size_y(s);
-		if (screen_size_y(s) - mtd->height < 2)
-			mtd->height = screen_size_y(s);
-	} else
+	if (mtd->preview)
+		mode_tree_set_height(mtd);
+	else
 		mtd->height = screen_size_y(s);
 	mode_tree_check_selected(mtd);
 }
@@ -502,7 +520,8 @@ mode_tree_add(struct mode_tree_data *mtd, struct mode_tree_item *parent,
 
 	mti->tag = tag;
 	mti->name = xstrdup(name);
-	mti->text = xstrdup(text);
+	if (text != NULL)
+		mti->text = xstrdup(text);
 
 	saved = mode_tree_find_item(&mtd->saved, tag);
 	if (saved != NULL) {
@@ -621,8 +640,8 @@ mode_tree_draw(struct mode_tree_data *mtd)
 			tag = "*";
 		else
 			tag = "";
-		xasprintf(&text, "%-*s%s%s%s: ", keylen, key, start, mti->name,
-		    tag);
+		xasprintf(&text, "%-*s%s%s%s%s", keylen, key, start, mti->name,
+		    tag, (mti->text != NULL) ? ": " : "" );
 		width = utf8_cstrwidth(text);
 		if (width > w)
 			width = w;
@@ -636,11 +655,17 @@ mode_tree_draw(struct mode_tree_data *mtd)
 		if (i != mtd->current) {
 			screen_write_clearendofline(&ctx, 8);
 			screen_write_nputs(&ctx, w, &gc0, "%s", text);
-			format_draw(&ctx, &gc0, w - width, mti->text, NULL);
+			if (mti->text != NULL) {
+				format_draw(&ctx, &gc0, w - width, mti->text,
+				    NULL);
+			}
 		} else {
 			screen_write_clearendofline(&ctx, gc.bg);
 			screen_write_nputs(&ctx, w, &gc, "%s", text);
-			format_draw(&ctx, &gc, w - width, mti->text, NULL);
+			if (mti->text != NULL) {
+				format_draw(&ctx, &gc, w - width, mti->text,
+				    NULL);
+			}
 		}
 		free(text);
 
@@ -662,9 +687,12 @@ mode_tree_draw(struct mode_tree_data *mtd)
 	screen_write_cursormove(&ctx, 0, h, 0);
 	screen_write_box(&ctx, w, sy - h);
 
-	xasprintf(&text, " %s (sort: %s%s)", mti->name,
-	    mtd->sort_list[mtd->sort_crit.field],
-	    mtd->sort_crit.reversed ? ", reversed" : "");
+	if (mtd->sort_list != NULL) {
+		xasprintf(&text, " %s (sort: %s%s)", mti->name,
+		    mtd->sort_list[mtd->sort_crit.field],
+		    mtd->sort_crit.reversed ? ", reversed" : "");
+	} else
+		xasprintf(&text, " %s", mti->name);
 	if (w - 2 >= strlen(text)) {
 		screen_write_cursormove(&ctx, 1, h, 0);
 		screen_write_puts(&ctx, &gc0, "%s", text);
@@ -1027,7 +1055,7 @@ mode_tree_key(struct mode_tree_data *mtd, struct client *c, key_code *key,
 		break;
 	case 'O':
 		mtd->sort_crit.field++;
-		if (mtd->sort_crit.field == mtd->sort_size)
+		if (mtd->sort_crit.field >= mtd->sort_size)
 			mtd->sort_crit.field = 0;
 		mode_tree_build(mtd);
 		break;
diff --git a/options-table.c b/options-table.c
index be657694..c3a9f23b 100644
--- a/options-table.c
+++ b/options-table.c
@@ -102,9 +102,9 @@ static const char *options_table_window_size_list[] = {
 	"," \
 		"#[range=window|#{window_index} list=focus " \
 			"#{?#{!=:#{window-status-current-style},default}," \
-	                        "#{window-status-current-style}," \
-	                        "#{window-status-style}" \
-	                "}" \
+				"#{window-status-current-style}," \
+				"#{window-status-style}" \
+			"}" \
 			"#{?#{&&:#{window_last_flag}," \
 				"#{!=:#{window-status-last-style},default}}, " \
 				"#{window-status-last-style}," \
@@ -174,6 +174,7 @@ const struct options_table_entry options_table[] = {
 	  .type = OPTIONS_TABLE_KEY,
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .default_num = '\177',
+	  .text = "The key to send for backspace."
 	},
 
 	{ .name = "buffer-limit",
@@ -181,7 +182,9 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .minimum = 1,
 	  .maximum = INT_MAX,
-	  .default_num = 50
+	  .default_num = 50,
+	  .text = "The maximum number of automatic buffers. "
+		  "When this is reached, the oldest buffer is deleted."
 	},
 
 	{ .name = "command-alias",
@@ -194,25 +197,31 @@ const struct options_table_entry options_table[] = {
 			 "info=show-messages -JT,"
 			 "choose-window=choose-tree -w,"
 			 "choose-session=choose-tree -s",
-	  .separator = ","
+	  .separator = ",",
+	  .text = "Array of command aliases. "
+		  "Each entry is an alias and a command separated by '='."
 	},
 
 	{ .name = "copy-command",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_str = ""
+	  .default_str = "",
+	  .text = "Shell command run when text is copied. "
+		  "If empty, no command is run."
 	},
 
 	{ .name = "default-terminal",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_str = "screen"
+	  .default_str = "screen",
+	  .text = "Default for the 'TERM' environment variable."
 	},
 
 	{ .name = "editor",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_str = _PATH_VI
+	  .default_str = _PATH_VI,
+	  .text = "Editor run to edit files."
 	},
 
 	{ .name = "escape-time",
@@ -220,31 +229,38 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 500
+	  .default_num = 500,
+	  .text = "Time to wait before assuming a key is Escape."
 	},
 
 	{ .name = "exit-empty",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_num = 1
+	  .default_num = 1,
+	  .text = "Whether the server should exit if there are no sessions."
 	},
 
 	{ .name = "exit-unattached",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether the server should exit if there are no attached "
+		  "clients."
 	},
 
 	{ .name = "focus-events",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether to send focus events to applications."
 	},
 
 	{ .name = "history-file",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SERVER,
-	  .default_str = ""
+	  .default_str = "",
+	  .text = "Location of the command prompt history file. "
+		  "Empty does not write a history file."
 	},
 
 	{ .name = "message-limit",
@@ -252,14 +268,18 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 1000
+	  .default_num = 1000,
+	  .text = "Maximum number of server messages to keep."
 	},
 
 	{ .name = "set-clipboard",
 	  .type = OPTIONS_TABLE_CHOICE,
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .choices = options_table_set_clipboard_list,
-	  .default_num = 1
+	  .default_num = 1,
+	  .text = "Whether to attempt to set the system clipboard ('on' or "
+		  "'external') and whether to allow applications to create "
+		  "paste buffers with an escape sequence ('on' only)."
 	},
 
 	{ .name = "terminal-overrides",
@@ -267,7 +287,8 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .flags = OPTIONS_TABLE_IS_ARRAY,
 	  .default_str = "",
-	  .separator = ","
+	  .separator = ",",
+	  .text = "List of terminal capabilities overrides."
 	},
 
 	{ .name = "terminal-features",
@@ -275,8 +296,10 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .flags = OPTIONS_TABLE_IS_ARRAY,
 	  .default_str = "xterm*:clipboard:ccolour:cstyle:title,"
-	                 "screen*:title",
-	  .separator = ","
+			 "screen*:title",
+	  .separator = ",",
+	  .text = "List of terminal features, used if they cannot be "
+		  "automatically detected."
 	},
 
 	{ .name = "user-keys",
@@ -284,7 +307,10 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SERVER,
 	  .flags = OPTIONS_TABLE_IS_ARRAY,
 	  .default_str = "",
-	  .separator = ","
+	  .separator = ",",
+	  .text = "User key assignments. "
+		  "Each sequence in the list is translated into a key: "
+		  "'User0', 'User1' and so on."
 	},
 
 	/* Session options. */
@@ -292,7 +318,8 @@ const struct options_table_entry options_table[] = {
 	  .type = OPTIONS_TABLE_CHOICE,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .choices = options_table_bell_action_list,
-	  .default_num = ALERT_OTHER
+	  .default_num = ALERT_OTHER,
+	  .text = "Action to take on an activity alert."
 	},
 
 	{ .name = "assume-paste-time",
@@ -301,6 +328,9 @@ const struct options_table_entry options_table[] = {
 	  .minimum = 0,
 	  .maximum = INT_MAX,
 	  .default_num = 1,
+	  .unit = "milliseconds",
+	  .text = "Maximum time between input to assume it pasting rather "
+		  "than typing."
 	},
 
 	{ .name = "base-index",
@@ -308,57 +338,69 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Default index of the first window in each session."
 	},
 
 	{ .name = "bell-action",
 	  .type = OPTIONS_TABLE_CHOICE,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .choices = options_table_bell_action_list,
-	  .default_num = ALERT_ANY
+	  .default_num = ALERT_ANY,
+	  .text = "Action to take on a bell alert."
 	},
 
 	{ .name = "default-command",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_str = ""
+	  .default_str = "",
+	  .text = "Default command to run in new panes. If empty, a shell is "
+		  "started."
 	},
 
 	{ .name = "default-shell",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_str = _PATH_BSHELL
+	  .default_str = _PATH_BSHELL,
+	  .text = "Location of default shell."
 	},
 
 	{ .name = "default-size",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .pattern = "[0-9]*x[0-9]*",
-	  .default_str = "80x24"
+	  .default_str = "80x24",
+	  .text = "Initial size of new sessions."
 	},
 
 	{ .name = "destroy-unattached",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether to destroy sessions when they have no attached "
+		  "clients."
 	},
 
 	{ .name = "detach-on-destroy",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 1
+	  .default_num = 1,
+	  .text = "Whether to detach when a session is destroyed, or switch "
+		  "the client to another session if any exist."
 	},
 
 	{ .name = "display-panes-active-colour",
 	  .type = OPTIONS_TABLE_COLOUR,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 1
+	  .default_num = 1,
+	  .text = "Colour of the active pane for 'display-panes'."
 	},
 
 	{ .name = "display-panes-colour",
 	  .type = OPTIONS_TABLE_COLOUR,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 4
+	  .default_num = 4,
+	  .text = "Colour of not active panes for 'display-panes'."
 	},
 
 	{ .name = "display-panes-time",
@@ -366,7 +408,9 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 1,
 	  .maximum = INT_MAX,
-	  .default_num = 1000
+	  .default_num = 1000,
+	  .unit = "milliseconds",
+	  .text = "Time for which 'display-panes' should show pane numbers."
 	},
 
 	{ .name = "display-time",
@@ -374,7 +418,9 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 750
+	  .default_num = 750,
+	  .unit = "milliseconds",
+	  .text = "Time for which status line messages should appear."
 	},
 
 	{ .name = "history-limit",
@@ -382,13 +428,19 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 2000
+	  .default_num = 2000,
+	  .unit = "lines",
+	  .text = "Maximum number of lines to keep in the history for each "
+		  "pane. "
+		  "If changed, the new value applies only to new panes."
 	},
 
 	{ .name = "key-table",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_str = "root"
+	  .default_str = "root",
+	  .text = "Default key table. "
+		  "Key presses are first looked up in this table."
 	},
 
 	{ .name = "lock-after-time",
@@ -396,13 +448,16 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 0,
 	  .maximum = INT_MAX,
-	  .default_num = 0
+	  .default_num = 0,
+	  .unit = "seconds",
+	  .text = "Time after which a client is locked if not used."
 	},
 
 	{ .name = "lock-command",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_str = "lock -np"
+	  .default_str = "lock -np",
+	  .text = "Shell command to run to lock a client."
 	},
 
 	{ .name = "message-command-style",
@@ -410,7 +465,9 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .default_str = "bg=black,fg=yellow",
 	  .flags = OPTIONS_TABLE_IS_STYLE,
-	  .separator = ","
+	  .separator = ",",
+	  .text = "Style of the command prompt when in command mode, if "
+		  "'mode-keys' is set to 'vi'."
 	},
 
 	{ .name = "message-style",
@@ -418,31 +475,39 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .default_str = "bg=yellow,fg=black",
 	  .flags = OPTIONS_TABLE_IS_STYLE,
-	  .separator = ","
+	  .separator = ",",
+	  .text = "Style of the command prompt."
 	},
 
 	{ .name = "mouse",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether the mouse is recognised and mouse key bindings are "
+		  "executed. "
+		  "Applications inside panes can use the mouse even when 'off'."
 	},
 
 	{ .name = "prefix",
 	  .type = OPTIONS_TABLE_KEY,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .default_num = '\002',
+	  .text = "The prefix key."
 	},
 
 	{ .name = "prefix2",
 	  .type = OPTIONS_TABLE_KEY,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .default_num = KEYC_NONE,
+	  .text = "A second prefix key."
 	},
 
 	{ .name = "renumber-windows",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether windows are automatically renumbered rather than "
+		  "leaving gaps."
 	},
 
 	{ .name = "repeat-time",
@@ -450,45 +515,56 @@ const struct options_table_entry options_table[] = {
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .minimum = 0,
 	  .maximum = SHRT_MAX,
-	  .default_num = 500
+	  .default_num = 500,
+	  .unit = "milliseconds",
+	  .text = "Time to wait for a key binding to repeat, if it is bound "
+		  "with the '-r' flag."
 	},
 
 	{ .name = "set-titles",
 	  .type = OPTIONS_TABLE_FLAG,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_num = 0
+	  .default_num = 0,
+	  .text = "Whether to set the terminal title, if supported."
 	},
 
 	{ .name = "set-titles-string",
 	  .type = OPTIONS_TABLE_STRING,
 	  .scope = OPTIONS_TABLE_SESSION,
-	  .default_str = "#S:#I:#W - \"#T\" #{session_alerts}"
+	  .default_str = "#S:#I:#W - \"#T\" #{session_alerts}",
+	  .text = "Format of the terminal title to set."
 	},
 
 	{ .name = "silence-action",
 	  .type = OPTIONS_TABLE_CHOICE,
 	  .scope = OPTIONS_TABLE_SESSION,
 	  .choices = options_table_bell_action_list,
-	  .default_num = ALERT_OTHER
+	  .default_num = ALERT_OTHER,
+	  .text = "Action to take on a silence alert."
 	},