--- a/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties	Fri Apr 21 19:33:57 2017 +0200
+++ b/langtools/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties	Fri Apr 21 12:27:02 2017 -0700
@@ -701,7 +701,8 @@
 help.set.mode = \
 Create a user-defined feedback mode, optionally copying from an existing mode:\n\
 \n\t\
-/set mode <mode> [<old-mode>] [-command|-quiet|-delete]\n\
+/set mode <new-mode> [<old-mode>] (-command|-quiet)\n\
+\n\
 Retain a user-defined feedback mode for future sessions:\n\
 \n\t\
 /set mode -retain <mode>\n\
@@ -715,25 +716,39 @@
 /set mode [<mode>]\n\
 \n\
 Where <new-mode> is the name of a mode you wish to create.\n\
-Where <old-mode> is the name of a previously defined feedback mode.\n\
+Where <old-mode> is the name of a existing feedback mode.\n\
+Where <mode> is the name of a existing feedback mode.\n\
+\n\
 If <old-mode> is present, its settings are copied to the new mode.\n\
-'-command' vs '-quiet' determines if informative/verifying command feedback is displayed.\n\
+\n\
+The feedback that a mode provides for entered snippets is determined by the\n\
+'/set format' settings. However, for entered commands, feedback is either on or off,\n\
+as determined by the option used when creating the mode; Either the option '-command'\n\
+or the option '-quiet' must be specified. If '-command' is used, informative and\n\
+verifying command feedback is displayed when in the new mode.  If '-quiet' is used,\n\
+commands give only essential feedback (e.g., errors).\n\
 \n\
 Once the new mode is created, use '/set format', '/set prompt' and '/set truncation'\n\
 to configure it.  Use '/set feedback' to use the new mode.\n\
 \n\
-When the -retain option is used, the mode (including its component prompt, format,\n\
-and truncation settings) will be used in this and future runs of the jshell tool.\n\
-When both -retain and -delete are used, the mode is deleted from the current\n\
-and future sessions.\n\
+When the '-retain' option is used (without the '-delete' option), the mode (including\n\
+its current prompt, format, and truncation settings) will be stored for use in\n\
+future runs of the jshell tool.  If retain is not used, the mode is only defined in\n\
+the current session. After updating the mode's settings, retain the mode again to\n\
+preserve the updates across sessions.\n\
 \n\
-The form without options shows the mode settings.\n\
-When the <mode> is specified only the mode settings for that mode are shown.\n\
+When only the '-delete' option is used, the mode is deleted from the current session.\n\
+When both '-retain' and '-delete' are used, the mode is deleted from the current and\n\
+future sessions.\n\
+\n\
+When the form without options is used, the mode settings are displayed.\n\
+When the <mode> is specified, only the mode settings for that mode are shown.\n\
 Note: the settings for the mode include the settings for prompt, format, and\n\
-truncation -- so these are displayed as well.\n\
+truncation.\n\
 Example:\n\t\
 /set mode myformat\n\
-shows the mode, prompt, format, and truncation settings for the mode myformat\n
+\n\
+shows the mode, prompt, format, and truncation settings for the mode myformat
 
 help.set.prompt = \
 Set the prompts.  Both the normal prompt and the continuation-prompt must be set:\n\