From abe1a5c8ba591abffbd498503794267ae130ae9e Mon Sep 17 00:00:00 2001
From: Christian Heller <c.heller@plomlompom.de>
Date: Wed, 25 Nov 2020 05:05:21 +0100
Subject: [PATCH] Improve documentation/help choise of words.

---
 rogue_chat.html      | 59 +++++++++++++++++++++++---------------------
 rogue_chat_curses.py | 30 +++++++++++-----------
 2 files changed, 46 insertions(+), 43 deletions(-)

diff --git a/rogue_chat.html b/rogue_chat.html
index 1846e98..636773d 100644
--- a/rogue_chat.html
+++ b/rogue_chat.html
@@ -44,7 +44,7 @@ terminal columns: <input id="n_cols" type="number" step=4 min=80 value=80 />
   </tr>
   <tr>
     <td><button id="switch_to_study">study mode</button></td>
-    <td><button id="toggle_map_mode">toggle everything/terrain/annotations view</button>
+    <td><button id="toggle_map_mode">toggle map view</button>
   </tr>
   <tr>
     <td><button id="switch_to_play">play mode</button></td>
@@ -57,19 +57,19 @@ terminal columns: <input id="n_cols" type="number" step=4 min=80 value=80 />
   <tr>
     <td><button id="switch_to_edit">map edit mode</button></td>
     <td>
-      <button id="switch_to_write">change tile</button>
+      <button id="switch_to_write">change terrain</button>
       <button id="flatten">flatten surroundings</button>
       <button id="switch_to_annotate">annotate tile</button>
-      <button id="switch_to_portal">edit portal link</button>
-      <button id="switch_to_password">change tile editing password</button>
+      <button id="switch_to_portal">edit portal</button>
+      <button id="switch_to_password">enter map edit password</button>
     </td>
   </tr>
   <tr>
     <td><button id="switch_to_admin_enter">admin mode</button></td>
     <td>
-      <button id="switch_to_control_pw_type">change tile control password</button>
-      <button id="switch_to_control_tile_type">change tiles control</button>
-      <button id="toggle_tile_draw">toggle tiles control drawing</button>
+      <button id="switch_to_control_pw_type">change protection character password</button>
+      <button id="switch_to_control_tile_type">change protection areas</button>
+      <button id="toggle_tile_draw">toggle protection character drawing</button>
     </td>
   <tr>
   </tr>
@@ -89,8 +89,8 @@ terminal columns: <input id="n_cols" type="number" step=4 min=80 value=80 />
 <li>help: <input id="key_help" type="text" value="h" />
 <li>flatten surroundings: <input id="key_flatten" type="text" value="F" />
 <li>teleport: <input id="key_teleport" type="text" value="p" />
-<li>take thing under player: <input id="key_take_thing" type="text" value="z" />
-<li>drop carried thing: <input id="key_drop_thing" type="text" value="u" />
+<li>pick up thing: <input id="key_take_thing" type="text" value="z" />
+<li>drop thing: <input id="key_drop_thing" type="text" value="u" />
 <li><input id="key_switch_to_chat" type="text" value="t" />
 <li><input id="key_switch_to_play" type="text" value="p" />
 <li><input id="key_switch_to_study" type="text" value="?" />
@@ -102,8 +102,8 @@ terminal columns: <input id="n_cols" type="number" step=4 min=80 value=80 />
 <li><input id="key_switch_to_control_tile_type" type="text" value="Q" />
 <li><input id="key_switch_to_annotate" type="text" value="M" />
 <li><input id="key_switch_to_portal" type="text" value="T" />
-<li>toggle everything/terrain/annotations view: <input id="key_toggle_map_mode" type="text" value="M" />
-<li>toggle everything/terrain/annotations view: <input id="key_toggle_tile_draw" type="text" value="m" />
+<li>toggle map view: <input id="key_toggle_map_mode" type="text" value="M" />
+<li>toggle protection character drawing: <input id="key_toggle_tile_draw" type="text" value="m" />
 </ul>
 </div>
 <script>
@@ -114,34 +114,34 @@ let websocket_location = "wss://plomlompom.com/rogue_chat/";
 let mode_helps = {
     'play': {
         'short': 'play',
-        'long': 'This mode allows you to interact with the map.'
+        'long': 'This mode allows you to interact with the map in various ways.'
     },
     'study': {
         'short': 'study',
-        'long': 'This mode allows you to study the map and its tiles in detail.  Move the question mark over a tile, and the right half of the screen will show detailed information on it.'},
+        'long': 'This mode allows you to study the map and its tiles in detail.  Move the question mark over a tile, and the right half of the screen will show detailed information on it.  Toggle the map view to show or hide different information layers.'},
     'edit': {
         'short': 'map edit',
-        'long': 'This mode allows you to change the map in various ways.'
+        'long': 'This mode allows you to change the map in various ways.  Individual map tiles are shown together with their "protection characters".  You can edit a tile if you set the map edit password that matches its protection character.  The character "." marks the absence of protection:  Such tiles can always be edited.'
     },
     'write': {
-        'short': 'terrain write',
+        'short': 'change terrain',
         'long': 'This mode allows you to change the map tile you currently stand on (if your map editing password authorizes you so).  Just enter any printable ASCII character to imprint it on the ground below you.'
     },
     'control_pw_type': {
-        'short': 'change tiles control password',
-        'long': 'This mode is the first of two steps to change the password for a tile control character.  First enter the tile control character for which you want to change the password.'
+        'short': 'change protection character password',
+        'long': 'This mode is the first of two steps to change the password for a tile protection character.  First enter the tile protection character for which you want to change the password.'
     },
     'control_pw_pw': {
         'short': 'change tiles control password',
-        'long': 'This mode is the second of two steps to change the password for a tile control character.  Enter the new password for the tile control character you chose.'
+        'long': 'This mode is the second of two steps to change the password for a tile protection character.  Enter the new password for the tile protection character you chose.'
     },
     'control_tile_type': {
         'short': 'change tiles control',
-        'long': 'This mode is the first of two steps to change tile control areas on the map.  First enter the tile control character you want to write.'
+        'long': 'This mode is the first of two steps to change tile protection areas on the map.  First enter the tile tile protection character you want to write.'
     },
     'control_tile_draw': {
         'short': 'change tiles control',
-        'long': 'This mode is the second of two steps to change tile control areas on the map.  Toggle tile control drawing on, then move cursor around the map to draw selected tile control character.'
+        'long': 'This mode is the second of two steps to change tile protection areas on the map.  Toggle tile protection drawing on/off and move the ?? cursor around the map to draw the selected tile protection character.'
     },
     'annotate': {
         'short': 'annotate tile',
@@ -157,7 +157,7 @@ let mode_helps = {
     },
     'login': {
         'short': 'login',
-        'long': 'Pick your player name.'
+        'long': 'Enter your player name.'
     },
     'waiting_for_server': {
         'short': 'waiting for server response',
@@ -168,7 +168,7 @@ let mode_helps = {
         'long': 'Waiting for a server response.'
     },
     'password': {
-        'short': 'map edit password',
+        'short': 'set map edit password',
         'long': 'This mode allows you to change the password that you send to authorize yourself for editing password-protected map tiles.  Hit return to confirm and leave.'
     },
     'admin_enter': {
@@ -936,7 +936,10 @@ let tui = {
     }
   },
   draw_help: function() {
-      let movement_keys_desc = Object.keys(this.movement_keys).join(',');
+      let movement_keys_desc = '';
+      if (!this.mode.is_intro) {
+          movement_keys_desc = Object.keys(this.movement_keys).join(',');
+      }
       let content = this.mode.short_desc + " help\n\n" + this.mode.help_intro + "\n\n";
       if (this.mode.name == 'play') {
           content += "Available actions:\n";
@@ -947,24 +950,24 @@ let tui = {
               content += "[" + this.keys.take_thing + "] – pick up thing\n";
           }
           if (game.tasks.includes('DROP')) {
-              content += "[" + this.keys.drop_thing + "] – drop picked-up thing\n";
+              content += "[" + this.keys.drop_thing + "] – drop thing\n";
           }
-          content += "[" + tui.keys.teleport + "] – teleport to other space\n";
+          content += "[" + tui.keys.teleport + "] – teleport\n";
           content += '\n';
       } else if (this.mode.name == 'study') {
           content += "Available actions:\n";
           content += '[' + movement_keys_desc + '] – move question mark\n';
-          content += '[' + this.keys.toggle_map_mode + '] – toggle view between terrain, annotations, and password protection areas\n';
+          content += '[' + this.keys.toggle_map_mode + '] – toggle map view\n';
           content += '\n';
       } else if (this.mode.name == 'edit') {
           content += "Available actions:\n";
           if (game.tasks.includes('FLATTEN_SURROUNDINGS')) {
-              content += "[" + tui.keys.flatten + "] – flatten player's surroundings\n";
+              content += "[" + tui.keys.flatten + "] – flatten surroundings\n";
           }
           content += '\n';
       } else if (this.mode.name == 'control_tile_draw') {
           content += "Available actions:\n";
-          content += "[" + tui.keys.toggle_tile_draw + "] – toggle tile control drawing\n";
+          content += "[" + tui.keys.toggle_tile_draw + "] – toggle protection character drawing\n";
           content += '\n';
       } else if (this.mode.name == 'chat') {
           content += '/nick NAME – re-name yourself to NAME\n';
diff --git a/rogue_chat_curses.py b/rogue_chat_curses.py
index b498ce0..49eb01a 100755
--- a/rogue_chat_curses.py
+++ b/rogue_chat_curses.py
@@ -14,34 +14,34 @@ from plomrogue.errors import BrokenSocketConnection
 mode_helps = {
     'play': {
         'short': 'play',
-        'long': 'This mode allows you to interact with the map.'
+        'long': 'This mode allows you to interact with the map in various ways.'
     },
     'study': {
         'short': 'study',
-        'long': 'This mode allows you to study the map and its tiles in detail.  Move the question mark over a tile, and the right half of the screen will show detailed information on it.'},
+        'long': 'This mode allows you to study the map and its tiles in detail.  Move the question mark over a tile, and the right half of the screen will show detailed information on it.  Toggle the map view to show or hide different information layers.'},
     'edit': {
         'short': 'map edit',
-        'long': 'This mode allows you to change the map in various ways.'
+        'long': 'This mode allows you to change the map in various ways.  Individual map tiles are shown together with their "protection characters".  You can edit a tile if you set the map edit password that matches its protection character.  The character "." marks the absence of protection:  Such tiles can always be edited.'
     },
     'write': {
-        'short': 'terrain write',
+        'short': 'change terrain',
         'long': 'This mode allows you to change the map tile you currently stand on (if your map editing password authorizes you so).  Just enter any printable ASCII character to imprint it on the ground below you.'
     },
     'control_pw_type': {
-        'short': 'change tiles control password',
-        'long': 'This mode is the first of two steps to change the password for a tile control character.  First enter the tile control character for which you want to change the password.'
+        'short': 'change protection character password',
+        'long': 'This mode is the first of two steps to change the password for a tile protection character.  First enter the tile protection character for which you want to change the password.'
     },
     'control_pw_pw': {
         'short': 'change tiles control password',
-        'long': 'This mode is the second of two steps to change the password for a tile control character.  Enter the new password for the tile control character you chose.'
+        'long': 'This mode is the second of two steps to change the password for a tile protection character.  Enter the new password for the tile protection character you chose.'
     },
     'control_tile_type': {
         'short': 'change tiles control',
-        'long': 'This mode is the first of two steps to change tile control areas on the map.  First enter the tile control character you want to write.'
+        'long': 'This mode is the first of two steps to change tile protection areas on the map.  First enter the tile tile protection character you want to write.'
     },
     'control_tile_draw': {
         'short': 'change tiles control',
-        'long': 'This mode is the second of two steps to change tile control areas on the map.  Toggle tile control drawing on, then move cursor around the map to draw selected tile control character.'
+        'long': 'This mode is the second of two steps to change tile protection areas on the map.  Toggle tile protection drawing on/off and move the ?? cursor around the map to draw the selected tile protection character.'
     },
     'annotate': {
         'short': 'annotate tile',
@@ -57,7 +57,7 @@ mode_helps = {
     },
     'login': {
         'short': 'login',
-        'long': 'Pick your player name.'
+        'long': 'Enter your player name.'
     },
     'waiting_for_server': {
         'short': 'waiting for server response',
@@ -68,7 +68,7 @@ mode_helps = {
         'long': 'Waiting for a server response.'
     },
     'password': {
-        'short': 'map edit password',
+        'short': 'set map edit password',
         'long': 'This mode allows you to change the password that you send to authorize yourself for editing password-protected map tiles.  Hit return to confirm and leave.'
     },
     'admin_enter': {
@@ -742,18 +742,18 @@ class TUI:
                 if 'PICK_UP' in self.game.tasks:
                     content += "[%s] – pick up thing\n" % self.keys['take_thing']
                 if 'DROP' in self.game.tasks:
-                    content += "[%s] – drop picked-up thing\n" % self.keys['drop_thing']
-                content += '[%s] – teleport to other space\n' % self.keys['teleport']
+                    content += "[%s] – drop thing\n" % self.keys['drop_thing']
+                content += '[%s] – teleport\n' % self.keys['teleport']
                 content += '\n'
             elif self.mode.name == 'study':
                 content += 'Available actions:\n'
                 content += '[%s] – move question mark\n' % ','.join(self.movement_keys)
-                content += '[%s] – toggle view between anything, terrain, and annotations\n' % self.keys['toggle_map_mode']
+                content += '[%s] – toggle map view\n' % self.keys['toggle_map_mode']
                 content += '\n'
             elif self.mode.name == 'edit':
                 content += "Available actions:\n"
                 if 'FLATTEN_SURROUNDINGS' in self.game.tasks:
-                    content += "[%s] – flatten player's surroundings\n" % self.keys['flatten']
+                    content += "[%s] – flatten surroundings\n" % self.keys['flatten']
                 content += '\n'
             elif self.mode.name == 'control_tile_draw':
                 content += "Available actions:\n"
-- 
2.30.2