Users of immediate-mode tools should get help whenever tools are invoked without correct or usable arguments. If help for a tool is invoked, it should present not only the help for that tool, but also a list of possible subtools and a prompt at which the user may continue to make input (rather than typing in the entire command line again).
The user invokes any tool by typing its name with incorrect or missing arguments; the tool responds by giving tool help, a list of possible continuation arguments, and a prompt at which the user may continue input (rather than retyping the entire command line). For the email gateway, this simply returns the help text in the form of an email message.
An installed product
Outputted help text and (in immediate mode) a prompt.
Table 4-3. Normal Course of Action
|Actor Actions||System Actions|
|Enters a tool (usu through command line) with invalid arguments||Prints help text message for that tool, including possible args|
|Prints a list of registered subcommands|
|If in immediate mode (not email or web gateway) presents the user with a prompt and awaits additional input.|
PROGRESSIVE-HELP.FR1. Each tool should have a stock "long_description_text" string feature listing a typical usage string, short description of the tool, and a listing of possible parameters and their explanations
PROGRESSIVE-HELP.FR2. Each tool should have a "possible subcommands" string feature listing the text indices of the subcommands it currently holds
PROGRESSIVE-HELP.FR3. If invoked without arguments, or with invalid arguments, each tool should display the help text and possible subcommands and return that information to the user.
PROGRESSIVE-HELP.FR4. If invoked without arguments, or with invalid arguments, and in interactive mode, each tool should display a prompt for the user and await further commands, to be invoked by the current tool as a command line.
PROGRESSIVE-HELP.FR5. Each tool should have a "is_interactive" flag denoting whether or not the tool has been invoked in interactive mode (note-- this is a lower priority feature, used to implement PROGRESSIVE-HELP.FR4, and is required by that feature).
PROGRESSIVE-HELP.FR6. Each tool must have a boolean feature "last_invocation_succeeded" indicating the results of the last invocation
PROGRESSIVE-HELP.FR7. Each tool must have a boolean feature "has_been_invoked" indicating whether or not the tool has been invoked with any arguments
PROGRESSIVE-HELP.FR8. Each tool must have a short (one line) textual description feature named "short_description_text"