Feature PROGRESSIVE-HELP

Description and Priority

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).

Stimulus/Response Sequences

PROGRESSIVE-HELP.UC: Get progressive help from a command-line tool

Description

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.

Requires

An installed product

Ensures

Outputted help text and (in immediate mode) a prompt.

Priority

Medium

Normal Course

Table 4-3. Normal Course of Action

Actor ActionsSystem Actions
Enters a tool (usu through command line) with invalid argumentsPrints 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.

Functional Requirements

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"