From e1069d367d116198cb2dfefc7c4de2e78ced181e Mon Sep 17 00:00:00 2001
From: Robert Field <rfield@openjdk.org>
Date: Tue, 19 Dec 2017 11:37:00 -0800
Subject: [PATCH] 8179858: jshell tool: sync nomenclature from reference to
 online /help

Reviewed-by: dlsmith, jjg
---
 .../jdk/internal/jshell/tool/JShellTool.java  |   5 +-
 .../jshell/tool/resources/l10n.properties     | 365 ++++++++++--------
 .../jdk/jshell/CommandCompletionTest.java     |   4 +-
 test/langtools/jdk/jshell/EditorTestBase.java |   2 +-
 test/langtools/jdk/jshell/ToolBasicTest.java  |  10 +-
 test/langtools/jdk/jshell/ToolSimpleTest.java |   2 +-
 6 files changed, 214 insertions(+), 174 deletions(-)

diff --git a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java
index 79a0a1f71f8..8fc94b1b47b 100644
--- a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java
+++ b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/JShellTool.java
@@ -1817,7 +1817,7 @@ public class JShellTool implements MessageHandler {
 
         // Documentation pseudo-commands
         registerCommand(new Command("/<id>",
-                "help.id",
+                "help.slashID",
                 arg -> cmdHelp("rerun"),
                 EMPTY_COMPLETION_PROVIDER,
                 CommandKind.HELP_ONLY));
@@ -1829,6 +1829,9 @@ public class JShellTool implements MessageHandler {
         registerCommand(new Command("intro",
                 "help.intro",
                 CommandKind.HELP_SUBJECT));
+        registerCommand(new Command("id",
+                "help.id",
+                CommandKind.HELP_SUBJECT));
         registerCommand(new Command("shortcuts",
                 "help.shortcuts",
                 CommandKind.HELP_SUBJECT));
diff --git a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties
index 0d7e517f185..5c405b6e821 100644
--- a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties
+++ b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n.properties
@@ -46,7 +46,7 @@ jshell.err.file.not.found = File ''{1}'' for ''{0}'' is not found.
 jshell.err.file.exception = File ''{1}'' for ''{0}'' threw exception: {2}
 jshell.err.file.filename = ''{0}'' requires a filename argument.
 
-jshell.err.startup.unexpected.exception = Unexpected exception reading start-up: {0}
+jshell.err.startup.unexpected.exception = Unexpected exception reading startup: {0}
 jshell.err.unexpected.exception = Unexpected exception: {0}
 
 jshell.err.invalid.command = Invalid command: {0}
@@ -104,9 +104,9 @@ For example ''/help /list'' or ''/help intro''.\n\
 Subjects:\n\
 \n
 
-jshell.err.no.snippet.with.id = No snippet with id: {0}
+jshell.err.no.snippet.with.id = No snippet with ID: {0}
 jshell.err.end.snippet.range.less.than.start = End of snippet range less than start: {0} - {1}
-jshell.err.range.requires.id = Snippet ranges require snippet ids: {0}
+jshell.err.range.requires.id = Snippet ranges require snippet IDs: {0}
 
 jshell.err.exit.not.expression = The argument to /exit must be a valid integer expression, it is not an expression: {0}
 jshell.err.exit.bad.type = The argument to /exit must be a valid integer expression. The type is {1} : {0}
@@ -114,7 +114,7 @@ jshell.err.exit.bad.value = The argument to /exit has bad value is {1} : {0}
 
 jshell.err.drop.arg =\
 In the /drop argument, please specify an import, variable, method, or class to drop.\n\
-Specify by id or name. Use /list to see ids. Use /reset to reset all state.
+Specify by ID or name. Use /list to see IDs. Use /reset to reset all state.
 jshell.err.failed = Failed.
 jshell.msg.native.method = Native Method
 jshell.msg.unknown.source = Unknown Source
@@ -193,15 +193,15 @@ For more information see:\n\
    /help shortcuts
 
 help.usage = \
-Usage:   jshell <option>... <load file>...\n\
+Usage:   jshell <option>... <load-file>...\n\
 where possible options include:\n\
 \    --class-path <path>   Specify where to find user class files\n\
 \    --module-path <path>  Specify where to find application modules\n\
 \    --add-modules <module>(,<module>)*\n\
 \                          Specify modules to resolve, or all modules on the\n\
 \                            module path if <module> is ALL-MODULE-PATHs\n\
-\    --startup <file>      One run replacement for the start-up definitions\n\
-\    --no-startup          Do not run the start-up definitions\n\
+\    --startup <file>      One run replacement for the startup definitions\n\
+\    --no-startup          Do not run the startup definitions\n\
 \    --feedback <mode>     Specify the initial feedback mode. The mode may be\n\
 \                            predefined (silent, concise, normal, or verbose) or\n\
 \                            previously user-defined\n\
@@ -218,12 +218,22 @@ where possible options include:\n\
 \    --show-version        Print version information and continue\n\
 \    --help                Print this synopsis of standard options and exit\n\
 \    --help-extra, -X      Print help on non-standard options and exit\n\
+\n\
 A file argument may be a file name, or one of the predefined file names: DEFAULT,\n\
 PRINTING, or JAVASE.\n\
-A load file may also be "-" to indicate standard input, without interactive I/O.\n
+A load-file may also be "-" to indicate standard input, without interactive I/O.\n\
+\n\
+For more information on the evaluation context options (--class-path,\n\
+--module-path, and --add-modules) see:\n\t\
+     /help context\n\
+\n\
+A path lists the directories and archives to search. For Windows, use a\n\
+semicolon (;) to separate items in the path. On other platforms, use a\n\
+colon (:) to separate items.\n\
 
 help.usage.x = \
-\    --add-exports <module>/<package>   Export specified module-private package to snippets\n\
+\    --add-exports <module>/<package>   Specify a package to be considered as\n\
+\                                         exported from its defining module \n\
 \    --execution <spec>                 Specify an alternate execution engine.\n\
 \                                         Where <spec> is an ExecutionControl spec.\n\
 \                                         See the documentation of the package\n\
@@ -234,47 +244,43 @@ help.usage.x = \
 help.list.summary = list the source you have typed
 help.list.args = [<name or id>|-all|-start]
 help.list =\
-Show the source of snippets, prefaced with the snippet id.\n\
+Show the snippets, prefaced with their snippet IDs.\n\
 \n\
 /list\n\t\
     List the currently active snippets of code that you typed or read with /open\n\n\
 /list -start\n\t\
-    List the automatically evaluated start-up snippets\n\n\
+    List the evaluated startup snippets\n\n\
 /list -all\n\t\
-    List all snippets including failed, overwritten, dropped, and start-up\n\n\
+    List all snippets including failed, overwritten, dropped, and startup\n\n\
 /list <name>\n\t\
     List snippets with the specified name (preference for active snippets)\n\n\
 /list <id>\n\t\
-    List the snippet with the specified snippet id\n\n\
-/list <id> <id>...\n\t\
-    List the snippets with the specified snippet ids\n\n\
-/list <id>-<id>\n\t\
-    List the snippets within the range of snippet ids
+    List the snippet with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'
 
-help.edit.summary = edit a source entry referenced by name or id
+help.edit.summary = edit a source entry
 help.edit.args = <name or id>
 help.edit =\
 Edit a snippet or snippets of source in an external editor.\n\
-The editor to use is set with /set editor.\n\
-If no editor has been set, a simple editor will be launched.\n\
+The editor to use is set with /set editor. If no editor is set, then the\n\
+following environment variables are checked in order: JSHELLEDITOR, VISUAL,\n\
+and EDITOR. If no editor has been set and none of the editor environment\n\
+variables is set, a simple editor will be launched.\n\
 \n\
 /edit <name>\n\t\
     Edit the snippet or snippets with the specified name (preference for active snippets)\n\n\
 /edit <id>\n\t\
-    Edit the snippet with the specified snippet id\n\n\
-/edit <id> <id>...\n\t\
-    Edit the snippets with the specified snippet ids\n\n\
-/edit <id>-<id>\n\t\
-    Edit the snippets within the range of snippet ids\n\n\
+    Edit the snippet with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'\n\n\
 /edit -start\n\t\
-    Edit the automatically evaluated start-up snippets. Any changes are in this\n\t\
-    session, and do not affect the start-up setting\n\n\
+    Edit the startup snippets. Any changes are in this session, and do not\n\t\
+    affect the startup setting\n\n\
 /edit -all\n\t\
-    Edit all snippets including failed, overwritten, dropped, and start-up\n\n\
+    Edit all snippets including failed, overwritten, dropped, and startup\n\n\
 /edit\n\t\
     Edit the currently active snippets of code that you typed or read with /open
 
-help.drop.summary = delete a source entry referenced by name or id
+help.drop.summary = delete a source entry
 help.drop.args = <name or id>
 help.drop =\
 Drop a snippet -- making it inactive.\n\
@@ -282,13 +288,10 @@ Drop a snippet -- making it inactive.\n\
 /drop <name>\n\t\
     Drop the snippet with the specified name\n\n\
 /drop <id>\n\t\
-    Drop the snippet with the specified snippet id\n\n\
-/drop <id> <id>...\n\t\
-    Drop the snippets with the specified snippet ids\n\n\
-/drop <id>-<id>\n\t\
-    Drop the snippets within the range of snippet ids
+    Drop the snippet with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'
 
-help.save.summary = Save snippet source to a file.
+help.save.summary = Save snippet source to a file
 help.save.args = [-all|-history|-start] <file>
 help.save =\
 Save the specified snippets and/or commands to the specified file.\n\
@@ -297,17 +300,15 @@ Save the specified snippets and/or commands to the specified file.\n\
     Save the source of current active snippets to the file.\n\n\
 /save -all <file>\n\t\
     Save the source of all snippets to the file.\n\t\
-    Includes source including overwritten, failed, and start-up code.\n\n\
+    Includes source of overwritten, failed, and startup code\n\n\
 /save -history <file>\n\t\
-    Save the sequential history of all commands and snippets entered since jshell was launched.\n\n\
+    Save the sequential history of all commands and snippets entered since the\n\t\
+    jshell tool was launched.\n\n\
 /save -start <file>\n\t\
-    Save the current start-up definitions to the file.\n\n\
+    Save the current startup definitions to the file\n\n\
 /save <id> <file>\n\t\
-    Save the snippet with the specified snippet id\n\n\
-/save <id> <id>... <file>\n\t\
-    Save the snippets with the specified snippet ids\n\n\
-/save <id>-<id> <file>\n\t\
-    Save the snippets within the range of snippet ids
+    Save the snippet with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'
 
 help.open.summary = open a file as source input
 help.open.args = <file>
@@ -315,97 +316,94 @@ help.open =\
 Open a file and read its contents as snippets and commands.\n\
 \n\
 /open <file>\n\t\
-    Read the specified file as jshell input.
+    Read the specified file as the jshell tool input.\n\
+\n\
+The <file> may be an operating system file name, or one of the predefined\n\
+file names: DEFAULT, PRINTING, or JAVASE.\n\
+These are respectively: the default import snippets (as used by -default),\n\
+definitions of print(), println(), and printf() method snippets, or\n\
+imports of all Java SE packages.\n
 
 help.vars.summary = list the declared variables and their values
 help.vars.args = [<name or id>|-all|-start]
 help.vars =\
-List the type, name, and value of jshell variables.\n\
+List the type, name, and value of variables that were entered.\n\
 \n\
 /vars\n\t\
-    List the type, name, and value of the current active jshell variables\n\n\
+    List the type, name, and value of the current active variables\n\n\
 /vars <name>\n\t\
-    List jshell variables with the specified name (preference for active variables)\n\n\
+    List variables with the specified name (preference for active variables)\n\n\
 /vars <id>\n\t\
-    List the jshell variable with the specified snippet id\n\n\
-/vars <id> <id>... <file>\n\t\
-    List the jshell variables with the specified snippet ids\n\n\
-/vars <id>-<id> <file>\n\t\
-    List the jshell variables within the range of snippet ids\n\n\
+    List the variable with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'\n\n\
 /vars -start\n\t\
-    List the automatically added start-up jshell variables\n\n\
+    List the variables in the evaluated startup snippets\n\n\
 /vars -all\n\t\
-    List all jshell variables including failed, overwritten, dropped, and start-up
+    List all variables including failed, overwritten, dropped, and startup
 
 help.methods.summary = list the declared methods and their signatures
 help.methods.args = [<name or id>|-all|-start]
 help.methods =\
-List the name, parameter types, and return type of jshell methods.\n\
+List the name, parameter types, and return type of methods that were entered.\n\
 \n\
 /methods\n\t\
-    List the name, parameter types, and return type of the current active jshell methods\n\n\
+    List the name, parameter types, and return type of the current active methods\n\n\
 /methods <name>\n\t\
-    List jshell methods with the specified name (preference for active methods)\n\n\
+    List methods with the specified name (preference for active methods)\n\n\
 /methods <id>\n\t\
-    List the jshell method with the specified snippet id\n\n\
-/methods <id> <id>... <file>\n\t\
-    List jshell methods with the specified snippet ids\n\n\
-/methods <id>-<id> <file>\n\t\
-    List jshell methods within the range of snippet ids\n\n\
+    List the method with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'\n\n\
 /methods -start\n\t\
-    List the automatically added start-up jshell methods\n\n\
+    List the methods in the evaluated startup snippets\n\n\
 /methods -all\n\t\
-    List all snippets including failed, overwritten, dropped, and start-up
+    List all snippets including failed, overwritten, dropped, and startup
 
-help.types.summary = list the declared types
+help.types.summary = list the type declarations
 help.types.args =[<name or id>|-all|-start]
 help.types =\
-List jshell classes, interfaces, and enums.\n\
+List classes and interfaces that were entered.\n\
 \n\
 /types\n\t\
-    List the current active jshell classes, interfaces, and enums.\n\n\
+    List the current active type declarations\n\n\
 /types <name>\n\t\
-    List jshell types with the specified name (preference for active types)\n\n\
+    List type declarations with the specified name (preference for active snippets)\n\n\
 /types <id>\n\t\
-    List the jshell type with the specified snippet id\n\n\
-/types <id> <id>... <file>\n\t\
-    List jshell types with the specified snippet ids\n\n\
-/types <id>-<id> <file>\n\t\
-    List jshell types within the range of snippet ids\n\n\
+    List the type declaration with the specified snippet ID.\n\t\
+    One or more IDs or ID ranges may used, see '/help id'\n\n\
 /types -start\n\t\
-    List the automatically added start-up jshell types\n\n\
+    List the type declarations in the evaluated startup snippets\n\n\
 /types -all\n\t\
-    List all jshell types including failed, overwritten, dropped, and start-up
+    List all type declarations including failed, overwritten, dropped, and startup
 
 help.imports.summary = list the imported items
 help.imports.args =
 help.imports =\
-List the current active jshell imports.
+List the current active imports.  This will include imports from\n\
+startup snippets.
 
-help.exit.summary = exit jshell
+help.exit.summary = exit the jshell tool
 help.exit.args =[<integer-expression-snippet>]
 help.exit =\
 Leave the jshell tool.  No work is saved.\n\
 Save any work before using this command\n\
 \n\
 /exit\n\t\
-    Leave the jshell tool.  The exit status is zero.\n\n\
+    Leave the jshell tool.  The exit status is zero\n\n\
 /exit <integer-expression-snippet>\n\t\
     Evaluate the snippet.  If the snippet fails or is not an integer expression,\n\t\
     display the error.  Otherwise leave the jshell tool with the\n\t\
     value of the expression as the exit status
 
-help.reset.summary = reset jshell
+help.reset.summary = reset the jshell tool
 help.reset.args = \
 [-class-path <path>] [-module-path <path>] [-add-modules <modules>]...
 help.reset =\
 Reset the jshell tool code and execution state:\n\t\
-   * All entered code is lost.\n\t\
-   * Start-up code is re-executed.\n\t\
-   * The execution state is restarted.\n\t\
-Tool settings are maintained, as set with: /set ...\n\
+   * All entered code is lost\n\t\
+   * The execution state is restarted\n\t\
+   * Startup code is re-executed\n\
 Save any work before using this command.\n\
-The /reset command accepts context options, see:\n\n\t\
+The /reset command accepts evaluation context options, see:\n\n\t\
      /help context\n\
 
 
@@ -417,18 +415,19 @@ Reset the jshell tool code and execution state then replay each valid snippet\n\
 and any /drop commands in the order they were entered.\n\
 \n\
 /reload\n\t\
-     Reset and replay the valid history since jshell was entered, or\n\t\
-     a /reset, or /reload command was executed -- whichever is most\n\t\
-     recent.\n\n\
+     Reset and replay the valid history since the jshell tool was entered, or\n\t\
+     a /reset or /reload command was executed -- whichever is most\n\t\
+     recent\n\n\
 /reload -restore\n\t\
      Reset and replay the valid history between the previous and most\n\t\
-     recent time that jshell was entered, or a /reset, /reload, or /env\n\t\
+     recent time that the jshell tool was entered, or a /reset, /reload, or /env\n\t\
      command was executed. This can thus be used to restore a previous\n\t\
-     jshell tool session.\n\n\
+     jshell tool session\n\n\
 /reload [-restore] -quiet\n\t\
-     With the '-quiet' argument the replay is not shown.  Errors will display.\n\
+     With the '-quiet' argument the replay is not shown, however any errors\n\t\
+     will be displayed\n\
 \n\
-Each of the above accepts context options, see:\n\n\t\
+Each of the above accepts evaluation context options, see:\n\n\t\
      /help context\n\
 \n\
 For example:\n\n\t\
@@ -439,28 +438,30 @@ help.env.args = \
 [-class-path <path>] [-module-path <path>] [-add-modules <modules>] ...
 help.env =\
 View or change the evaluation context.  The evaluation context is the class path,\n\
-module path, etc.\n\
+module path, etc.\n\n\
 /env\n\t\
-     Show the evaluation context displayed as context options.\n\n\
+     Show the evaluation context displayed as context options\n\n\
 /env [-class-path <path>] [-module-path <path>] [-add-modules <modules>] ...\n\t\
      With at least one option set, sets the evaluation context.  If snippets\n\t\
      have been defined, the execution state is reset with the new\n\t\
      evaluation context and the snippets will be replayed -- the replay is not\n\t\
-     shown, however, errors will display.  This is equivalent to: /reload -quiet\n\t\
-     For details of context options, see:\n\n\t\t\
-           /help context\n\n\t\
-     For example:\n\n\t\t\
-           /env -add-modules com.greetings
+     shown, however any errors will be displayed.  This is equivalent to:\n\n\t\t\
+             /reload -quiet ...\n\
+\n\
+For details of evaluation context options, see:\n\n\t\
+     /help context\n\n\
+For example:\n\n\t\
+     /env -add-modules com.greetings
 
 help.history.summary = history of what you have typed
 help.history.args =
 help.history =\
-Display the history of snippet and command input since this jshell was launched.
+Display the history of snippet and command input since this jshell tool was launched.
 
-help.debug.summary = toggle debugging of the jshell
+help.debug.summary = toggle debugging of the jshell tool
 help.debug.args = [0][r][g][f][c][d][e]
 help.debug =\
-Display debugging information for the jshell implementation.\n\
+Display debugging information for the jshell tool implementation.\n\
 0: Debugging off\n\
 r: Tool level debugging on\n\
 g: General debugging on\n\
@@ -469,12 +470,12 @@ c: Completion analysis debugging on\n\
 d: Dependency debugging on\n\
 e: Event debugging on
 
-help.help.summary = get information about jshell
+help.help.summary = get information about using the jshell tool
 help.help.args = [<command>|<subject>]
 help.help =\
-Display information about jshell.\n\
+Display information about using the jshell tool.\n\
 /help\n\t\
-     List the jshell commands and help subjects.\n\n\
+     List the jshell tool commands and help subjects\n\n\
 /help <command>\n\t\
      Display information about the specified command. The slash must be included.\n\t\
      Only the first few letters of the command are needed -- if more than one\n\t\
@@ -482,40 +483,40 @@ Display information about jshell.\n\
 /help <subject>\n\t\
      Display information about the specified help subject. Example: /help intro
 
-help.set.summary = set jshell configuration information
+help.set.summary = set configuration information
 help.set.args = editor|start|feedback|mode|prompt|truncation|format ...
 help.set =\
-Set jshell configuration information, including:\n\
-the external editor to use, the start-up definitions to use, a new feedback mode,\n\
+Set the jshell tool configuration information, including:\n\
+the external editor to use, the startup definitions to use, a new feedback mode,\n\
 the command prompt, the feedback mode to use, or the format of output.\n\
 \n\
 /set editor [-wait] <command> <optional-arg>...\n\t\
      Specify the command to launch for the /edit command.\n\t\
-     The <command> is an operating system dependent string.\n\n\
+     The <command> is an operating system dependent string\n\n\
 /set start <file>\n\t\
-     The contents of the specified <file> become the default start-up snippets and commands.\n\n\
+     The contents of the specified <file> become the default startup snippets and commands\n\n\
 /set feedback <mode>\n\t\
-     Set the feedback mode describing displayed feedback for entered snippets and commands.\n\n\
+     Set the feedback mode describing displayed feedback for entered snippets and commands\n\n\
 /set mode <mode> [<old-mode>] -command|-quiet|-delete\n\t\
-     Create or update a user-defined feedback mode, optionally copying from an existing mode.\n\n\
+     Create or update a user-defined feedback mode, optionally copying from an existing mode\n\n\
 /set prompt <mode> "<prompt>" "<continuation-prompt>"\n\t\
-     Set the displayed prompts for a given feedback mode.\n\n\
+     Set the displayed prompts for a given feedback mode\n\n\
 /set truncation <mode> <length> <selector>...\n\t\
-     Set the maximum length of a displayed value.\n\n\
+     Set the maximum length of a displayed value\n\n\
 /set format <mode> <field> "<format>" <selector>...\n\t\
-     Configure a feedback mode by setting the format of a field when the selector matches.\n\n\
+     Configure a feedback mode by setting the format of a field when the selector matches\n\n\
 /set\n\t\
      Show editor, start, and feedback settings as /set commands.\n\t\
-     To show the settings of any of the above, omit the set value.\n\n\
+     To show the settings of any of the above, omit the set value\n\n\
 To get more information about one of these forms, use /help with the form specified.\n\
 For example:   /help /set format
 
-help.quest.summary = get information about jshell
+help.quest.summary = get information about using the jshell tool
 help.quest.args = [<command>|<subject>]
 help.quest =\
-Display information about jshell (abbreviation for /help).\n\
+Display information about using the jshell tool (abbreviation for /help).\n\
 /?\n\t\
-     Display list of commands and help subjects.\n\
+     Display list of commands and help subjects\n\
 /? <command>\n\t\
      Display information about the specified command. The slash must be included.\n\t\
      Only the first few letters of the command are needed -- if more than one\n\t\
@@ -528,17 +529,18 @@ help.bang.args =
 help.bang =\
 Reevaluate the most recently entered snippet.
 
-help.id.summary = rerun snippets by id or id range -- see /help rerun
-help.id.args =
-help.id =\
+help.slashID.summary = rerun snippets by ID or ID range -- see /help rerun
+help.slashID.args =
+help.slashID =\
 /<id> <id> <id>\n\
 \n\
 /<id>-<id>\n\
 \n\
-Reevaluate the snippets specified by the id or id range.\n\
-An id range is represented as a two ids separated by a hyphen, e.g.:  3-17\n\
-Start-up and error snippets maybe used, e.g.:  s3-s9    or   e1-e4\n\
-Any number of ids or id ranges may be used, e.g.:  /3-7 s4 14-16 e2
+Reevaluate the snippets specified by the ID or ID range.\n\
+An ID range is represented as a two IDs separated by a hyphen, e.g.:  3-17\n\
+Startup and error snippets maybe used, e.g.:  s3-s9    or   e1-e4\n\
+Any number of IDs or ID ranges may be used, e.g.:  /3-7 s4 14-16 e2\n\
+See '/help id'.
 
 help.previous.summary = rerun n-th previous snippet -- see /help rerun
 help.previous.args =
@@ -553,7 +555,7 @@ or a Java expression, like:  x + x\n\
 or a Java statement or import.\n\
 These little chunks of Java code are called 'snippets'.\n\
 \n\
-There are also jshell commands that allow you to understand and\n\
+There are also the jshell tool commands that allow you to understand and\n\
 control what you are doing, like:  /list\n\
 \n\
 For a list of commands: /help
@@ -565,7 +567,7 @@ Supported shortcuts include:\n\
 \n\
 <tab>\n\t\t\
         After entering the first few letters of a Java identifier,\n\t\t\
-        a jshell command, or, in some cases, a jshell command argument,\n\t\t\
+        a jshell tool command, or, in some cases, a jshell tool command argument,\n\t\t\
         press the <tab> key to complete the input.\n\t\t\
         If there is more than one completion, then possible completions will be shown.\n\t\t\
         Will show documentation if available and appropriate.\n\n\
@@ -580,26 +582,26 @@ Shift-<tab> m\n\t\t\
         of the expression.\n\n\
 Shift-<tab> i\n\t\t\
         After an unresolvable identifier, hold down <shift> while pressing <tab>,\n\t\t\
-        then release and press "i", and jshell will propose possible imports\n\t\t\
+        then release and press "i", and the jshell tool will propose possible imports\n\t\t\
         which will resolve the identifier based on the content of the specified classpath.
 
 help.context.summary = a description of the evaluation context options for /env /reload and /reset
 help.context =\
-These options configure the evaluation context, they can be specified when\n\
-jshell is started: on the command-line, or restarted with the commands /env,\n\
-/reload, or /reset.\n\
+These options configure the evaluation context.  They can be specified on the\n\
+command-line when the jshell tool is started or as command options when the jshell tool is\n\
+restarted with the commands /env, /reload, or /reset.\n\
 \n\
 They are:\n\t\
-    --class-path <class search path of directories and zip/jar files>\n\t\t\
-                  A list of directories, JAR archives,\n\t\t\
+    --class-path <path>\n\t\t\
+                  The <path> is a list of directories, JAR archives,\n\t\t\
                   and ZIP archives to search for class files.\n\t\t\
-                  The list is separated with the path separator\n\t\t\
-                  (a : on unix/linux/mac, and ; on windows).\n\t\
-    --module-path <module path>...\n\t\t\
-                  A list of directories, each directory\n\t\t\
-                  is a directory of modules.\n\t\t\
-                  The list is separated with the path separator\n\t\t\
-                  (a : on unix/linux/mac, and ; on windows).\n\t\
+                  For Windows, use a semicolon (;) to separate items in the\n\t\t\
+                  path. On other platforms, use a  colon (:) to separate items.\n\t\
+    --module-path <path>...\n\t\t\
+                  The <path> is a list of directories, JAR archives,\n\t\t\
+                  and ZIP archives to search for modules.\n\t\t\
+                  For Windows, use a semicolon (;) to separate items in the\n\t\t\
+                  path. On other platforms, use a  colon (:) to separate items.\n\t\
     --add-modules <modulename>[,<modulename>...]\n\t\t\
                   root modules to resolve in addition to the initial module.\n\t\t\
                   <modulename> can also be ALL-DEFAULT, ALL-SYSTEM,\n\t\t\
@@ -611,8 +613,42 @@ They are:\n\t\
                   unnamed modules. In jshell, if the <target-module> is not\n\t\t\
                   specified (no =) then ALL-UNNAMED is used.\n\
 \n\
+Evaluation context options entered on the command line or provided with a\n\
+previous /reset, /env, or /reload command are maintained unless an option is\n\
+entered that overwrites the setting.\n\
+\n\
 On the command-line these options must have two dashes, e.g.: --module-path\n\
-On jshell commands they can have one or two dashes, e.g.: -module-path\n\
+On the jshell tool commands they can have one or two dashes, e.g.: -module-path
+
+help.id.summary = a description of snippet IDs and how use them
+help.id =\
+Every snippet of code you enter has its own unique snippet ID.  Even if you\n\
+enter the same snippet again, it will have a new ID.  For normal snippets the ID\n\
+is an increasing number.  Snippets which fail with an error have a snippet ID\n\
+which begins with 'e'.  Snippets in the startup have an ID which begins with 's'.\n\
+\n\
+A snippet ID is one way to refer to a snippet in a command.  For example, this\n\
+command drops the snippet with ID '14':\n\
+\n\t\
+        /drop 14\n\
+\n\
+To see the ID of a snippet or snippets use the '/list' command.  To see the ID\n\
+of all snippets. including failed, startup, and overwritten snippets, use the\n\
+'/list -all' command.\n\
+\n\
+You can also refer to a range of IDs by separating the beginning ID and ending\n\
+ID with a hypen.  For example, '1-4' is the same as '1 2 3 4'.  All commands\n\
+which refer to snippets will take a list of IDs, ID ranges, and snippet names\n\
+as arguments.  These commands are: /list, /edit, /drop, /save, /vars, /methods,\n\
+/types, and /<id>.  Some examples:\n\
+\n\t\
+        /edit 7-23\n\
+\n\t\
+        /save s1-s4 3-8 foo 12 myfile\n\
+\n\t\
+        /9-12 33\n\
+\n\
+See '/help /edit', '/help /save', and '/help rerun' respectively.
 
 help.rerun.summary = a description of ways to re-evaluate previously entered snippets
 help.rerun =\
@@ -639,10 +675,11 @@ For example:\n\
     \t2 + 2\n\
     \t$5 ==> 4\n\
 \n\
-The snippets to re-evaluate may be specified by snippet id or id range.\n\
-An id range is represented as a two ids separated by a hyphen, e.g.:  3-17\n\
-Start-up and error snippets maybe used, e.g.:  s3-s9    or   e1-e4\n\
-Any number of ids or id ranges may be used, e.g.:  /3-7 s4 14-16 e2\n\
+The snippets to re-evaluate may be specified by snippet ID or ID range.\n\
+An ID range is represented as a two IDs separated by a hyphen, e.g.:  3-17\n\
+Startup and error snippets maybe used, e.g.:  s3-s9    or   e1-e4\n\
+Any number of IDs or ID ranges may be used, e.g.:  /3-7 s4 14-16 e2\n\
+See also '/help id'.\n\
 \n\
 Finally, you can search backwards through history by entering ctrl-R followed by the string to search for.
 
@@ -656,7 +693,7 @@ The -retain option can be used on the following forms of /set:\n\n\t\
 See these commands for more detail -- for example /help /set editor
 
 help.set.format.summary = \
-Set the format for reporting a snippet event.
+Set the format for reporting a snippet event
 
 help.set.format = \
 Set the format for reporting a snippet event:\n\
@@ -746,7 +783,7 @@ mode and field are shown.  Example:\n\t\
 shows the format settings for the mode mymode\n
 
 help.set.truncation.summary = \
-Set the max length of a displayed value.
+Set the max length of a displayed value
 
 help.set.truncation = \
 Set the max length of a displayed value:\n\
@@ -789,7 +826,7 @@ Example:\n\t\
 shows the truncation settings for the mode mymode\n
 
 help.set.feedback.summary = \
-Set the feedback mode describing displayed feedback for entered snippets and commands.
+Set the feedback mode describing displayed feedback for entered snippets and commands
 
 help.set.feedback = \
 Set the feedback mode describing displayed feedback for entered snippets and commands:\n\
@@ -814,7 +851,7 @@ runs of the jshell tool.\n\
 The form without <mode> or -retain displays the current feedback mode and available modes.\n
 
 help.set.mode.summary = \
-Create a user-defined feedback mode, optionally copying from an existing mode.
+Create a user-defined feedback mode, optionally copying from an existing mode
 
 help.set.mode = \
 Create a user-defined feedback mode, optionally copying from an existing mode:\n\
@@ -869,7 +906,7 @@ Example:\n\t\
 shows the mode, prompt, format, and truncation settings for the mode mymode
 
 help.set.prompt.summary = \
-Set the prompts.
+Set the prompts
 
 help.set.prompt = \
 Set the prompts.  Both the normal prompt and the continuation-prompt must be set:\n\
@@ -881,9 +918,9 @@ Show the normal prompt and the continuation-prompts:\n\
 /set prompt [<mode>]\n\
 \n\
 Where <mode> is the name of a previously defined feedback mode.\n\
-Where <prompt> and <continuation-prompt> are quoted strings printed as input prompts;\n\
-Both may optionally contain '%%s' which will be substituted with the next snippet id --\n\
-note that what is entered may not be assigned that id, for example it may be an error or command.\n\
+Where <prompt> and <continuation-prompt> are quoted strings to be printed as input prompts.\n\
+Both may optionally contain '%%s' which will be substituted with the next snippet ID --\n\
+note that what is entered may not be assigned that ID, for example it may be an error or command.\n\
 The continuation-prompt is used on the second and subsequent lines of a multi-line snippet.\n\
 \n\
 The form without <prompt> shows the currently set prompts.\n\
@@ -893,7 +930,7 @@ Example:\n\t\
 shows the prompts set for the mode mymode\n
 
 help.set.editor.summary =\
-Specify the command to launch for the /edit command.
+Specify the command to launch for the /edit command
 
 help.set.editor =\
 Specify the command to launch for the /edit command:\n\
@@ -937,10 +974,10 @@ runs of the jshell tool.\n\
 The form without <command> or options shows the editor setting.\n
 
 help.set.start.summary =\
-Set the start-up configuration.
+Set the startup configuration
 
 help.set.start =\
-Set the start-up configuration -- a sequence of snippets and commands read at start-up:\n\
+Set the startup configuration -- a sequence of snippets and commands read at startup:\n\
 \n\t\
 /set start [-retain] <file>...\n\
 \n\t\
@@ -948,29 +985,29 @@ Set the start-up configuration -- a sequence of snippets and commands read at st
 \n\t\
 /set start [-retain] -none\n\
 \n\
-Retain the start-up configuration for future sessions:\n\
+Retain the startup configuration for future sessions:\n\
 \n\t\
 /set start -retain\n\
 \n\
-Show the start-up setting:\n\
+Show the startup setting:\n\
 \n\t\
 /set start\n\
 \n\
-The contents of the specified <file> become the start-up snippets and commands used\n\
+The contents of the specified <file> become the startup snippets and commands used\n\
 when the /reset, /reload, or /env commands are used in this session.\n\
-If instead the -default option is specified, the predefined start-up import\n\
+If instead the -default option is specified, the predefined startup import\n\
 snippets will be used.\n\
-If the -none option is used, the start-up will be empty -- no start-up snippets\n\
+If the -none option is used, the startup will be empty -- no startup snippets\n\
 or commands will be used.\n\
-This command is good for testing the start-up settings.  To retain them for future\n\
+This command is good for testing the startup settings.  To retain them for future\n\
 runs of the jshell tool use the command:\n\t\
 /set start -retain\n\
 \n\
 When the -retain option is used, the setting will be used in this and future\n\
 runs of the jshell tool.\n\
 \n\
-The form without <file> or options shows the start-up setting.\n\
-Note: if the start-up was last set from a file, this is shown with the\n\
+The form without <file> or options shows the startup setting.\n\
+Note: if the startup was last set from a file, this is shown with the\n\
 'set start' command followed by the contents of the file.\n\
 \n\
 The <file> may be an operating system file name, or one of the predefined\n\
diff --git a/test/langtools/jdk/jshell/CommandCompletionTest.java b/test/langtools/jdk/jshell/CommandCompletionTest.java
index 535a9eb1c7e..827cd047287 100644
--- a/test/langtools/jdk/jshell/CommandCompletionTest.java
+++ b/test/langtools/jdk/jshell/CommandCompletionTest.java
@@ -162,13 +162,13 @@ public class CommandCompletionTest extends ReplToolTesting {
                 "/edit ", "/env ", "/exit ",
                 "/help ", "/history ", "/imports ",
                 "/list ", "/methods ", "/open ", "/reload ", "/reset ",
-                "/save ", "/set ", "/types ", "/vars ", "context ", "intro ", "rerun ", "shortcuts "),
+                "/save ", "/set ", "/types ", "/vars ", "context ", "id ", "intro ", "rerun ", "shortcuts "),
                 a -> assertCompletion(a, "/? |", false,
                 "/! ", "/-<n> ", "/<id> ", "/? ", "/drop ",
                 "/edit ", "/env ", "/exit ",
                 "/help ", "/history ", "/imports ",
                 "/list ", "/methods ", "/open ", "/reload ", "/reset ",
-                "/save ", "/set ", "/types ", "/vars ", "context ", "intro ", "rerun ", "shortcuts "),
+                "/save ", "/set ", "/types ", "/vars ", "context ", "id ", "intro ", "rerun ", "shortcuts "),
                 a -> assertCompletion(a, "/help /s|", false,
                 "/save ", "/set "),
                 a -> assertCompletion(a, "/help /set |", false,
diff --git a/test/langtools/jdk/jshell/EditorTestBase.java b/test/langtools/jdk/jshell/EditorTestBase.java
index a4fddac9018..14e20d6339f 100644
--- a/test/langtools/jdk/jshell/EditorTestBase.java
+++ b/test/langtools/jdk/jshell/EditorTestBase.java
@@ -73,7 +73,7 @@ public abstract class EditorTestBase extends ReplToolTesting {
         for (String edit : new String[] {"/ed", "/edit"}) {
             test(new String[]{"--no-startup"},
                     a -> assertCommandOutputStartsWith(a, edit + " 1",
-                            "|  No snippet with id: 1"),
+                            "|  No snippet with ID: 1"),
                     a -> assertCommandOutputStartsWith(a, edit + " unknown",
                             "|  No such snippet: unknown")
             );
diff --git a/test/langtools/jdk/jshell/ToolBasicTest.java b/test/langtools/jdk/jshell/ToolBasicTest.java
index 04174aec298..7ddc10aa622 100644
--- a/test/langtools/jdk/jshell/ToolBasicTest.java
+++ b/test/langtools/jdk/jshell/ToolBasicTest.java
@@ -189,8 +189,8 @@ public class ToolBasicTest extends ReplToolTesting {
 
     public void testRerun() {
         test(false, new String[] {"--no-startup"},
-                (a) -> assertCommand(a, "/0", "|  No snippet with id: 0"),
-                (a) -> assertCommand(a, "/5", "|  No snippet with id: 5")
+                (a) -> assertCommand(a, "/0", "|  No snippet with ID: 0"),
+                (a) -> assertCommand(a, "/5", "|  No snippet with ID: 5")
         );
         String[] codes = new String[] {
                 "int a = 0;", // var
@@ -251,9 +251,9 @@ public class ToolBasicTest extends ReplToolTesting {
         );
 
         test(false, new String[] {"--no-startup"},
-                (a) -> assertCommand(a, "/s1", "|  No snippet with id: s1"),
-                (a) -> assertCommand(a, "/1", "|  No snippet with id: 1"),
-                (a) -> assertCommand(a, "/e1", "|  No snippet with id: e1")
+                (a) -> assertCommand(a, "/s1", "|  No snippet with ID: s1"),
+                (a) -> assertCommand(a, "/1", "|  No snippet with ID: 1"),
+                (a) -> assertCommand(a, "/e1", "|  No snippet with ID: e1")
         );
     }
 
diff --git a/test/langtools/jdk/jshell/ToolSimpleTest.java b/test/langtools/jdk/jshell/ToolSimpleTest.java
index f0906c7f7a2..3a6ae752622 100644
--- a/test/langtools/jdk/jshell/ToolSimpleTest.java
+++ b/test/langtools/jdk/jshell/ToolSimpleTest.java
@@ -296,7 +296,7 @@ public class ToolSimpleTest extends ReplToolTesting {
     @Test
     public void testDropNegative() {
         test(false, new String[]{"--no-startup"},
-                a -> assertCommandOutputStartsWith(a, "/drop 0", "|  No snippet with id: 0"),
+                a -> assertCommandOutputStartsWith(a, "/drop 0", "|  No snippet with ID: 0"),
                 a -> assertCommandOutputStartsWith(a, "/drop a", "|  No such snippet: a"),
                 a -> assertCommandCheckOutput(a, "/drop",
                         assertStartsWith("|  In the /drop argument, please specify an import, variable, method, or class to drop.")),