'O' assistance

I don't care for this very much at all, but making it shorter will
reduce its usefullness.  It addresses one of the struggles exhibited
in the "a man and his cat" youtube video, where he was baffled when
selecting booleans didn't change their values and he later used Esc
instead of Enter after eventually finding number_pad.

This inserts some explanatory text (around three dozen lines,
unfortunately) at the start of 'O's menu.  Some of it is general menu
stuff, some is specific options stuff, and some attempts to fend off
various bug reports about options that do or don't persist across
save and restore or RC revisions that seem to have no effect.

The new introductory text can be disabled by turning off cmdassist.
Players who already do that don't need to see this.  Many who ignore
cmdassist and occasionally endure an outburst of compass directions
are likely to be goaded into turning it off.  I hope we won't need a
new 'optassist' for players who want to skip this but leave cmdassist
in general on.

It doesn't attempt to address his attempt to use arrow keys (possibly
arrows overloaded on number pad keys, or perhaps just digits on the
number pad while numpad mode was off) to navigate the menu then having
the Windows port 'helpfully' change those into hjkl which resulted in
selecting and subsequently unintentionally toggling some options on
the first page.  One was 'color' which he did notice and then re-run
'O' to successfully toggle it back on.  There was at least one other
which he either didn't notice to didn't both to reverse.

diff --git a/include/optlist.h b/include/optlist.h
index 0cb3bbcd9b6747dcac7b9e0790848beff08a0375..ba808dc4f55d0e37f6b10e29a8d9dd7fe6531f9e 100644 (file)
--- a/include/optlist.h
+++ b/include/optlist.h
@@ -454,8 +454,8 @@ opt_##a,
 #ifdef STATUS_HILITES
     NHOPTC(statushilites, 20, opt_in, set_in_game, Yes, Yes, Yes, No, NoAlias,
                 "0=no status highlighting, N=show highlights for N turns")
-    NHOPTO("status hilite rules", o_status_hilites, BUFSZ, opt_in, set_in_game,
-           No, Yes, No, NoAlias, "edit status hilites")
+    NHOPTO("status highlight rules", o_status_hilites, BUFSZ, opt_in,
+           set_in_game, No, Yes, No, NoAlias, "edit status hilites")
 #else
     NHOPTC(statushilites, 20, opt_in, set_in_config, Yes, Yes, Yes, No,
                 NoAlias, "highlight control")

diff --git a/src/options.c b/src/options.c
index 55faf8158e34352a898926cb1cf94cfaacb9ea2f..f0c6d455e27c84a09b540d9482015b28b55b2aac 100644 (file)
--- a/src/options.c
+++ b/src/options.c
@@ -7289,6 +7289,49 @@ longest_option_name(int startpass, int endpass)
     return longest_name_len;
 }
 
+/* text to optionally insert at the beginning of #options command's menu,
+   briefly describing how it works; [brevity is in the eye of the beholder
+   or perhaps a pig; it was brief when this comment was first written...] */
+static const char *const optmenu[] = {
+    "This menu shows the current value for all options and lets you",
+    "pick ones that you'd like to change.  Picking them doesn't make",
+    "any immediate changes though.  That will take place once you close",
+    "the menu.  For most of NetHack's interfaces, closing the menu is",
+    "done by pressing the <enter> key or <return> key; others might",
+    "require clicking on [ok].  Pressing the <escape> key or clicking",
+    "on [cancel] will close the menu and discard any pending changes.",
+    "",
+    "This menu is too long to fit on one screen.  Some interfaces",
+    "paginate menus; use the '>' key to advance a page or '<' to back",
+    "up.  They typically re-use selection letters (a-z) on each page.",
+    "Others use one long page and you need to use a scrollbar; once",
+    "past a-z and A-Z they'll have entries without selection letters.",
+    "Those can be selected by clicking on them.",
+    "",
+    "For toggling boolean (True/False or On/Off) options, selecting",
+    "them is all that is needed.  For compound options (below, after",
+    "the boolean ones), you will be prompted to supply a new value.",
+    "",
+    "At the start of each of the two sections are the values of some",
+    "unselectable options which can only be set before the game starts.",
+    "After the compound section are some \"other\" options which take a",
+    "set of multiple values and tend to be more complex to deal with.",
+    "",
+    "Some changes will only last until you save (or quit) the current",
+    "game.  Usually those are for things that might not be appropriate",
+    "if you were to restore the saved game on another computer with",
+    "different capabilities.  Other options will be included in this",
+    "game's save file and retain their settings after restore.  None set",
+    "here will affect other games, either already saved or new ones.",
+    "For that, you need to update your run-time configuration file and",
+    "specify the desired options settings there.  Even then, restoring",
+    "existing games that contain saved option values will use those.",
+    "",
+    "[Suppress this menu introduction by turning off 'cmdassist'.]",
+    "",
+    NULL
+};
+
 /* the #options command */
 int
 doset(void) /* changing options via menu by Per Liboriussen */
@@ -7307,6 +7350,16 @@ doset(void) /* changing options via menu by Per Liboriussen */
     tmpwin = create_nhwindow(NHW_MENU);
     start_menu(tmpwin, MENU_BEHAVE_STANDARD);
 
+    if (iflags.cmdassist) {
+        /* insert the optmenu[] explanatory text at the top of the menu */
+        any = cg.zeroany;
+        for (i = 0; optmenu[i]; ++i) {
+            Sprintf(buf, "%4s%.75s", "", optmenu[i]);
+            add_menu(tmpwin, &nul_glyphinfo, &any, 0, 0, FALSE,
+                     buf, MENU_ITEMFLAGS_NONE);
+        }
+    }
+
 #ifdef notyet /* SYSCF */
     /* XXX I think this is still fragile.  Fixing initial/from_file and/or
        changing the SET_* etc to bitmaps will let me make this better. */