From: PatR <rankin@nethack.org>
Date: Sun, 5 Jun 2016 08:09:52 +0000 (-0700)
Subject: 'whatdoes' command and new file: dat/keyhelp
X-Git-Tag: NetHack-3.6.1_RC01~700
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=4ef23c6ac48ca99cf5ee0a7f1f8d4df784d775ff;p=nethack

'whatdoes' command and new file: dat/keyhelp

Make the whatdoes ('&' or '?f') command support the 'altmeta' option
for meta-characters generated by two character seqeunce 'ESC char'.
Also, make it be more descriptive when reporting "no such command"
by including the numeric value it operated on when failing to match
any command.  That might provide a way for us to get some extra
information when players report problems with odd keystrokes:  we ask
them to type such at the "what command?" prompt and then tell us what
numbers come up.

It's been given a help file to deal with assorted idiosyncracies
which can come up when querying what keys do.  Unfortunately that
ended up being way more verbose than intended.

Installation of the extra data file has only been done for Unix.
Other platforms will get "can't open file" if they respond with
'&' or '?' to the "what command?" prompt.  The command will still
work though, just without the extra text.
---

diff --git a/Files b/Files
index 919d50808..8c3a948d0 100644
--- a/Files
+++ b/Files
@@ -12,13 +12,13 @@ dat:
 (files for all versions)
 Arch.des        Barb.des        Caveman.des     Healer.des      Knight.des
 Monk.des        Priest.des      Ranger.des      Rogue.des       Samurai.des
-Tourist.des     Valkyrie.des    Wizard.des      bigroom.des     castle.des
-cmdhelp         data.base       dungeon.def     endgame.des     gehennom.des
-help            hh              history         knox.des        license
-medusa.des      mines.des       opthelp         oracle.des      oracles.txt
-quest.txt       rumors.fal      rumors.tru      sokoban.des     symbols
-tower.des       wizhelp         yendor.des      tribute         bogusmon.txt
-engrave.txt     epitaph.txt
+Tourist.des     Valkyrie.des    Wizard.des      bigroom.des     bogusmon.txt
+castle.des      cmdhelp         data.base       dungeon.def     endgame.des
+engrave.txt     epitaph.txt     gehennom.des    help            hh
+history         keyhelp         knox.des        license         medusa.des
+mines.des       opthelp         oracle.des      oracles.txt     quest.txt
+rumors.fal      rumors.tru      sokoban.des     symbols         tower.des
+tribute         wizhelp         yendor.des
 
 doc:
 (files for all versions)
diff --git a/dat/keyhelp b/dat/keyhelp
new file mode 100644
index 000000000..41ab37ef1
--- /dev/null
+++ b/dat/keyhelp
@@ -0,0 +1,58 @@
+	Depending upon hardware or operating system or NetHack's interface,
+	some keystrokes may be off-limits.
+
+	For example, ^S and ^Q are often used for XON/XOFF flow-control,
+	meaning that ^S suspends output and subsequent ^Q resumes suspended
+	output.  When that it the case, neither of those characters will
+	reach NetHack when it is waiting for a command keystroke.  So they
+	aren't used as commands, but 'whatdoes' might not be able to tell
+	you that if they don't get passed through to NetHack.
+
+	^M or <return> or <enter> is likely to be transformed into ^J or
+	<linefeed> or 'newline' before being passed to NetHack for handling.
+	So it isn't used as a command, and 'whatdoes' might seem as if it
+	is reporting the wrong character but will be operating correctly if
+	it describes ^J when you type ^M.
+
+	A NUL character, typed as ^<space> on some keyboards, ^@ on others,
+	and maybe not typeable at all on yet others.  It is not used as a
+	command, and will be converted into ESC before reaching 'whatdoes'.
+	Unlike ^M, this transformation is performed by NetHack itself.
+	But like ^M, if you type NUL and get feedback about ESC, the
+	situation is expected.
+
+	ESC itself is a synonym for ^[, and is another source of oddity.
+	Various function keys, including cursor arrow keys, may transmit
+	an "escape sequence" of ESC + [ + other stuff, confusing NetHack
+	as to what command was intended since the ESC will be processed
+	and then whatever follows will seem to NetHack like--and be used
+	as--something typed by the user.  (If you press a function key and
+	a menu of the armor your hero is wearing appears, what happened
+	was that an escape sequence was sent to NetHack, its ESC aborted
+	any pending key operation, its '[' was then treated as a command
+	to show worn armor, and the "other stuff" probably got silently
+	discarded as invalid choices while you dismissed the menu.)
+
+	If you have NetHack's 'altmeta' option enabled, meaning that the
+	<alt> or <option> key, when used as shift while typing some other
+	character, transmits ESC and then the other character so NetHack
+	should treat that other character as a meta-character, then ESC
+	takes on added potential for confusion.  Implicit in the handling
+	of a two character sequence ESC + something is the fact that when
+	NetHack sees ESC, it needs to wait for another character before
+	it can decide what to do.  So if you type ESC manually, you'll
+	need to type it a second time or NetHack will sit there waiting.
+	(It will then be treated as if you typed ESC rather than M-ESC.)
+
+	On some systems, typing ^\ will send a QUIT signal to the current
+	process, probably killing it and possibly causing it to save a
+	core dump.  It is not used for any NetHack command, so don't type
+	that character.
+
+	One last note:  characters shown as ^x mean that you should hold
+	down the <control> or <ctrl> key as a shift and then type 'x'.
+	Control characters are all implicitly uppercase, but you don't
+	need to press the shift key while typing them.  The opposite is
+	true for meta-characters:  they can be either case, so you need
+	to use shift as well as <meta> or <alt> to generate an uppercase
+	letter meta-character.
diff --git a/include/global.h b/include/global.h
index 0a4c76ac5..4a6647243 100644
--- a/include/global.h
+++ b/include/global.h
@@ -1,4 +1,4 @@
-/* NetHack 3.6	global.h	$NHDT-Date: 1450306170 2015/12/16 22:49:30 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.47 $ */
+/* NetHack 3.6	global.h	$NHDT-Date: 1465114189 2016/06/05 08:09:49 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.49 $ */
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -18,6 +18,7 @@
 #define RECORD "record"         /* file containing list of topscorers */
 #define HELP "help"             /* file containing command descriptions */
 #define SHELP "hh"              /* abbreviated form of the same */
+#define KEYHELP "keyhelp"       /* explanatory text for 'whatdoes' command */
 #define DEBUGHELP "wizhelp"     /* file containing debug mode cmds */
 #define RUMORFILE "rumors"      /* file with fortune cookies */
 #define ORACLEFILE "oracles"    /* file with oracular information */
diff --git a/src/pager.c b/src/pager.c
index 77ade35b0..b35601f9e 100644
--- a/src/pager.c
+++ b/src/pager.c
@@ -1,4 +1,4 @@
-/* NetHack 3.6	pager.c	$NHDT-Date: 1463790247 2016/05/21 00:24:07 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.98 $ */
+/* NetHack 3.6	pager.c	$NHDT-Date: 1465114189 2016/06/05 08:09:49 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.107 $ */
 /* Copyright (c) Stichting Mathematisch Centrum, Amsterdam, 1985. */
 /* NetHack may be freely redistributed.  See license for details. */
 
@@ -1306,6 +1306,32 @@ doidtrap()
     return 0;
 }
 
+STATIC_DCL void
+dowhatdoes_help()
+{
+    dlb *fp;
+    char *p, buf[BUFSZ];
+    winid tmpwin = create_nhwindow(NHW_TEXT);
+
+    fp = dlb_fopen(KEYHELP, "r");
+    if (!fp) {
+        pline("Cannot open \"%s\" data file!", KEYHELP);
+        display_nhwindow(WIN_MESSAGE, TRUE);
+        return;
+    }
+    while (dlb_fgets(buf, (int) sizeof buf, fp)) {
+        if (*buf == '#')
+            continue;
+        for (p = buf; *p; p++)
+            if (*p != ' ' && *p != '\t')
+                break;
+        putstr(tmpwin, 0, p);
+    }
+    (void) dlb_fclose(fp);
+    display_nhwindow(tmpwin, TRUE);
+    destroy_nhwindow(tmpwin);
+}
+
 char *
 dowhatdoes_core(q, cbuf)
 char q;
@@ -1317,7 +1343,7 @@ char *cbuf;
 
     fp = dlb_fopen(CMDHELPFILE, "r");
     if (!fp) {
-        pline("Cannot open data file!");
+        pline("Cannot open \"%s\" data file!", CMDHELPFILE);
         return 0;
     }
 
@@ -1353,21 +1379,40 @@ char *cbuf;
 int
 dowhatdoes()
 {
+    static boolean once = FALSE;
     char bufr[BUFSZ];
     char q, *reslt;
 
+    if (!once) {
+        pline("Ask about '&' or '?' to get more info.%s",
+              iflags.altmeta ? "  (For ESC, type it twice.)" : "");
+        once = TRUE;
+    }
 #if defined(UNIX) || defined(VMS)
-    introff();
+    introff(); /* disables ^C but not ^\ */
 #endif
     q = yn_function("What command?", (char *) 0, '\0');
+    if (q == '\033' && iflags.altmeta) {
+        /* in an ideal world, we would know whether another keystroke
+           was already pending, but this is not an ideal world...
+           if user types ESC, we'll essentially hang until another
+           character is typed */
+        q = yn_function("", (char *) 0, '\0');
+        if (q != '\033')
+            q = (char) ((uchar) q | 0200);
+    }
 #if defined(UNIX) || defined(VMS)
-    intron();
+    intron(); /* reenables ^C */
 #endif
     reslt = dowhatdoes_core(q, bufr);
-    if (reslt)
-        pline1(reslt);
-    else
-        pline("I've never heard of such commands.");
+    if (reslt) {
+        if (q == '&' || q == '?')
+            dowhatdoes_help();
+        pline("%s", reslt);
+    } else {
+        pline("No such command '%s', char code %d (0%03o or 0x%02x).",
+              visctrl(q), (uchar) q, (uchar) q, (uchar) q);
+    }
     return 0;
 }
 
diff --git a/sys/unix/Makefile.top b/sys/unix/Makefile.top
index 88907a786..88dc3b878 100644
--- a/sys/unix/Makefile.top
+++ b/sys/unix/Makefile.top
@@ -1,5 +1,5 @@
 #	NetHack Makefile.
-# NetHack 3.6  Makefile.top	$NHDT-Date: 1449621572 2015/12/09 00:39:32 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.33 $
+# NetHack 3.6  Makefile.top	$NHDT-Date: 1465114189 2016/06/05 08:09:49 $  $NHDT-Branch: NetHack-3.6.0 $:$NHDT-Revision: 1.35 $
 
 # Root of source tree:
 NHSROOT=.
@@ -76,7 +76,7 @@ VARDAT = $(VARDATD) $(VARDATND)
 # end of configuration
 #
 
-DATHELP = help hh cmdhelp history opthelp wizhelp
+DATHELP = help hh cmdhelp keyhelp history opthelp wizhelp
 
 SPEC_LEVS = asmodeus.lev baalz.lev bigrm-*.lev castle.lev fakewiz?.lev \
 	juiblex.lev knox.lev medusa-?.lev minend-?.lev minefill.lev \