keysh(1)

NAME

keysh — context-sensitive softkey shell

SYNOPSIS

keysh

DESCRIPTION

keysh is an extension of the standard Korn-shell (for a description of the basic Korn-shell functionality, see ksh(1)).

keysh uses hierarchical softkey menus and context-sensitive help to aid users in building command-lines, combining the power of the Korn-shell with the ease-of-use of a menu system.

And keysh is entirely data-driven, allowing its menus and help to be easily extended as needed.

Note that during keysh invocation, the environment variable $TERM must specify the terminal type, as defined in the terminfo(4) database (see Environment Variables below).

COMMAND ENTRY

keysh continually parses the command-line and always presents the user with an appropriate set of current choices on the softkey labels.

The user can select these softkeys to create readable softkey commands on the command-line. keysh automatically translates these softkey commands into equivalent HP-UX commands prior to executing them.

Alternatively, the user can ignore the softkeys altogether in favor of entering the traditional HP-UX commands directly, as when using the Korn-shell.

During command entry, keysh ordinarily displays a status-line near the bottom of the screen. This status-line contains information such as the host name, current directory, and time and date.

Whenever the user must perform an action to complete the current softkey command, keysh temporarily displays a prompt message in place of the status-line. This message briefly describes the required action.

Softkey Types

keysh presents four basic softkey types:

--Help--

Selecting the --Help-- softkey causes keysh to display help information associated with the next selected softkey, rather than actually performing its action.

--More--

If there are more current choices than there are softkeys, keysh breaks the choices into banks and displays a special --More-- softkey along with the first bank. Selecting the --More-- softkey causes keysh to display the next bank of softkeys in sequence, eventually cycling back to the first.

<param>

parameter softkeys are displayed as a name enclosed between a pair of less-than and greater-than symbols. They indicate that the user-supplied text (such as a file name) should be entered into the command-line at that point, rather than actually selecting the softkey. (Actually selecting the softkey only causes keysh to display a hint message on the status line; the command-line remains unchanged.)

option

All other softkeys are option softkeys that can be used to insert the corresponding command or option name into the command-line.

Softkeys can be selected from left to right.

Editing The Command-Line

keysh supports the normal Korn-shell command-line editing modes. In addition, keysh also recognizes the cursor movement and editing keys found on most terminals, as defined in the terminfo(4) database. These include:

<Clear display>: Clear the screen and command-line. If the screen is scrolled, clear only from the cursor position to the end of scrolling memory.
<Clear line>: Clear from the cursor position to the end of the command-line.
<Delete line>: Clear the entire command-line.
<Insert line>: Translate any softkey commands in the current command-line and then edit the result.
<Delete char>: Delete the character under the cursor.
<Insert char>: Toggle between insert and overwrite modes.
<Up/Down arrow>: Recall the previous/next command from the history buffer.
<Left/Right arrow>: Move the cursor left/right.
<Home up/down>: Move the cursor to the beginning/end of the command-line.
<Tab>: If no <Insert line> key is present, perform the <Insert line> function (see above). Otherwise, if no --Help-- softkey is present, perform the --Help-- function (also see above). Otherwise, perform the normal tab function.
<Backtab>: Move the cursor to the beginning of the previous word.
<Ctrl-L>: Redraw the lower lines of the screen and restore any necessary terminal modes.

Visible Softkey Commands

If the visibles configuration option is enabled (see CONFIGURATION below), keysh displays a list of configured softkey commands on the softkey labels whenever it is expecting a new command. This is the the top-level softkey menu.

If the user selects one of these softkey commands, keysh inserts its command name into the command-line then displays a sub-menu listing the command's major parameters and/or options.

The user can then (from left to right) select option softkeys and/or enter text in place of parameter softkeys. keysh automatically navigates the hierarchical softkey menu, always presenting the user with an appropriate set of current choices on the softkey labels.

Note that keysh automatically redisplays the top-level softkey menu when it detects that a command separator (such as a pipe or semi-colon) has been entered, thus allowing the user to use softkeys for subsequent commands on the command-line as well as the first.

Invisible Softkey Commands

If the invisibles configuration option is enabled (see CONFIGURATION below) and keysh recognizes a traditional HP-UX command being entered, it gives the user one last chance to use the softkeys by again presenting an appropriate set of current choices on the softkey labels. As with the top-level softkey menu options, the user can choose to ignore the softkeys in favor of entering the traditional HP-UX options directly.

Backup Softkeys

If the backups configuration option is enabled (see CONFIGURATION below), keysh displays the backup softkeys and programs the terminal function keys appropriately whenever it has no other softkeys to display (such as when a command is running). These provide the traditional static softkey control which many users may be used to.

Traditional HP-UX Commands

If the user enters a traditional HP-UX command when keysh is displaying its top-level softkey menu, keysh simply displays the backup softkeys and allows the user to proceed.

If keysh subsequently detects a command separator, it again redisplays the top-level softkey menu.

Softkey Command Syntax Errors

Many softkey commands present the user with a set of softkey options from which exactly one (or at least one) must be selected. If the user fails to do this, keysh treats it as a syntax error, displaying an error message and not accepting the command until the error has been corrected.

Similarly, many softkey commands require that the user enter one or more softkey parameters before the command is semantically complete. If the user fails to do this, keysh again treats it as a syntax error.

Softkey Command Redirections

The user can append redirection symbols (such as a less-than or greater-than symbol followed by a file name) following a softkey command. These are appended verbatim to the translated HP-UX command.

USING KEYSH WITH TERMINAL SESSION MANAGER

When operating under the Terminal Session Manager (see tsm(1)), keysh displays the tsm softkeys instead of the backup softkeys. If desired, this interaction can be overridden by setting the $KEYTSM environment variable (see Environment Variables below).

When operating under tsm, keysh also automatically displays the tsm window number in the status-line.

CONFIGURATION

All keysh configuration functions are accessed through the top-level Keysh_config softkey command or kc built-in command. These functions include:

adding, placing, and deleting softkeys,
specifying backup softkeys,
selecting global options,
selecting status-line items,
restarting keysh,
writing configuration changes, and
undoing other configuration changes.

Each time the user changes keysh's configuration, keysh automatically updates the user's $HOME/.keyshrc file. Upon subsequent invocations, keysh automatically reconfigures itself as configured previously.

Adding, Placing, And Deleting Softkeys

Any of the standard softkeys (see STANDARD SOFTKEY DEFINITIONS below) can be added to the top-level softkey menu using the kc softkey add command. If desired, an alternate softkey label may be specified (usually in place of a cryptic HP-UX command name) using the with_label option.

By default, added softkeys are placed at the end of the last --More-- bank of the top-level softkey menu. This placement can be overridden using the and_place option of the kc softkey add command or using the kc softkey move command.

In addition to the standard softkeys, custom softkeys can also be added from custom softkey files using the from_user or from_file options. For a description of the softkey file format, see softkeys(4).

Note that any time a softkey is added from a particular softkey file, all of the remaining softkeys from that file are automatically loaded for use as invisible softkey commands. All softkeys from a file can also be loaded for use as invisible softkey commands using the kc softkey add invisibles command.

Any of the softkeys in the top-level softkey menu can be deleted using the kc softkey delete command.

Specifying Backup Softkeys

Backup softkeys are typically specified in the user's $HOME/.softkeys file. The basic backup softkey definition line resembles:

backup softkey "<softkey>" literal "<string>"; 

Where <softkey> is the softkey label to display and <string> is the text string to program the terminal function key with. A maximum of eight backup softkeys can be specified.

Note that backup softkeys must be explicitly added using the kc softkey add backups command before keysh can program them.

Selecting Global Options

Various global options can be configured using the kc option command, including:

backups: Enable or disable the programming of the backup softkeys.
help: Enable or disable the --Help-- softkey.
invisibles: Enable or disable the recognition of invisible softkey commands.
prompts: Enable or disable the automatic generation of prompt messages. When enabled, keysh displays a prompt message whenever the user must perform an action to complete the current softkey command. This message briefly describes the required action.
selectors: Enable or disable the use of keyboard selectors. When enabled, keysh displays an upper-case selector character in each softkey label. Typing the unquoted (upper-case) character selects the softkey just as if its corresponding function key had been pressed. Quoting the selector character in any way restores its traditional meaning. Selector keys are intended to be used on terminals that do not support a sufficient number of softkeys.
translations: Enable or disable the display of HP-UX command translations.
visibles: Enable or disable the presentation and recognition of visible softkey commands.

Selecting Status-Line Items

Various information items can be configured into the status-line displayed at the bottom of the screen using the kc status_line command, including:

host_name: The host name.
user_name: The user name.
current_dir: The current directory.
mail_status: The mail status based on the $MAIL environment variable (i.e., No mail, You have mail, or You have new mail).
date: The date.
time: The time of day.

In addition, the $KEYSH environment variable, if set, is always displayed first in the status-line.

Restarting Keysh

keysh can be forced to reread the $HOME/.keyshrc file with the kc restart command. This command is typically used to update a keysh to a new configuration specified in another window.

keysh can also be forced to remove the $HOME/.keyshrc file and restart from the default user configuration with the kc restart default command.

Writing Configuration Changes

keysh can be forced to rewrite the $HOME/.keyshrc file with the kc write command.

Undoing Other Configuration Changes

keysh can also be forced to rewrite the $HOME/.keyshrc file with its original contents, thus undoing all configuration changes made since keysh was invoked, using the kc undo command.

Scaling Keysh Functionalities

keysh provides a scalable set of functionalities which can be tailored to suit personal preferences.

For users who are familiar with the HP-UX command names (though not necessarily with the command options) or for users who prefer to usually have the tsm softkeys visible, the command kc options visibles off prevents keysh from displaying its top-level softkey menu while waiting for a command; instead, it displays the backup softkeys or tsm softkeys, as appropriate. (keysh start-up time can then be decreased significantly by editing the $HOME/.keyshrc file and removing the lines which add visible softkeys.)

For users who are also familiar with the HP-UX command options, the command kc options invisibles off prevents keysh from displaying softkey menus for invisible softkey commands, also.

And for users who have no need for the backup softkeys, the command kc options backups off prevents keysh from ever programming the backup softkeys.

Note that if visibles, invisibles, and backups are all turned off, keysh performs no softkey processing at all. keysh effectively transforms into a Korn-shell which displays a status-line and recognizes the cursor movement and editing keys.

EXAMPLES

To add the od (see od(1)) softkey to the end of the top-level softkey menu and label it Octal_dump,

kc softkey add od with_label Octal_dump 

To add the paste(1) softkey to the beginning of the top-level softkey menu and label it Paste,

kc softkey add paste and_place as_first_softkey 

To add the custom emacs softkey from the file ~rpt/.softkeys to the top-level softkey menu immediately before the ls (see ls(1)) softkey,

kc softkey add emacs from_user rpt and_place before_softkey ls 

To add all invisible softkeys from the file ~rpt/.softkeys,

kc softkey add invisibles from_user rpt 

To add the backup softkeys from the file $HOME/.softkeys,

kc softkey add backups 

To delete the Edit_file softkey from the top-level softkey menu,

kc softkey delete Edit_file 

To disable the --Help-- softkey,

kc options help off 

To configure the user name into the status-line,

kc status_line user_name on 

To configure the exit-value of the last command executed into the status-line,

KEYSH="\${?#0}" 

To list the ten largest files in the current directory,

ls long_format | Sort_lines numerically reverse_order \ 
     starting_at_field 5 | head 

STANDARD SOFTKEY DEFINITIONS

Copy_files, Move_files, Print_files, Set_file_attribs, Switch.

adjust, ar, bdf, cal, cancel, cat, cd, cdb, chatr, chgrp, chmod, chown, cmp, col, comm, cpio, cut, dd, df, diff, dircmp, disable, du, elm, enable, exit, find, fold, grep, head, jobs, kill, lp, lpstat, ls, mailx, make, man, mkdir, more, nm, nroff, od, paste, pg, pr, ps, remsh, rlogin, rm, rmdir, sdiff, set, shar, sort, tail, tar, tee, touch, tr, umask, uname, vi, wc, who, write, xd, xdb.

EXTERNAL INFLUENCES

Environment Variables

TERM: Specifies the terminal type, as defined in the terminfo(4) database. This variable must be either part of keysh's invocation environment or it must be set within one of the standard Korn-shell start-up files.
COLUMNS: Specifies the number of columns in the terminal screen if different than the terminfo(4) default.
LINES: Specifies the number of lines in the terminal screen if not the same as the terminfo(4) default.
PAGER: Specifies the preferred pager to be used to display help. The default is more (see more(1)).
TZ: Specifies the time-zone to be used for time and date representations on the status-line. The default is en_US.roman8.
KEYBEL: Specifies the character sequence sent to the terminal by keysh to ring the bell. The default is ^G.
KEYENV: Specifies an alternate keysh configuration file. The default is $HOME/.keyshrc.
KEYESC: Specifies the maximum allowable delay between characters (in milliseconds) if they are to be treated as part of a terminal escape sequence. The default is 350 ms.
KEYKSH: If set, specifies that keysh should mimic the behavior of the Korn-shell as closely as possible. No softkeys or status-line are displayed. This mode is particularly useful over slow modem lines.
KEYLOC: If set, specifies that keysh should leave the terminal keypad in local mode while commands are being entered. This mimics the behavior of the Korn-shell.
KEYPS1: If set, specifies that keysh should not reset the initial values of $PS1, $PS2, and $PS3. Note that $PS1 must be a constant character string in order for keysh to recognize it and provide subsequent softkey assistance.
KEYSH: Specifies arbitrary text to be included in the keysh status-line.
KEYSIM: If set, specifies that keysh should always simulate softkey labels and not use the built-in labels on HP terminals.
KEYTSM: If set, specifies that keysh should not use the tsm softkeys when tsm is running. In this case, the user can either use the tsm hotkey, the backup softkeys, or the Switch softkey command (see STANDARD SOFTKEY DEFINITIONS above) to switch tsm windows.

KSH DIFFERENCES

keysh is an extension of ksh(1) with the following exceptions:

Screen Updates

keysh optimizes its display output to take advantage of available terminal capabilities. Unlike the Korn-shell which often has to redraw large portions of the command-line, keysh can simply insert or delete characters at the appropriate screen position.

This makes keysh significantly faster over slow modem lines, especially if the $KEYKSH environment variable is set (see Environment Variables above).

Emacs-Mode Editing

The new <ESC>v command performs the function of the vi-mode v command.

An initial ^N command recalls the history line following the history line executed as the previous command. This provides an easy mechanism to repeat a sequence of history commands.

gmacs editing mode is not supported; emacs editing mode follows the GNU emacs (18.54) definition of ^T.

The ^@ and <ESC>n ^K commands are not supported.

The M-<letter> and M-]<letter> alias functions are not supported (in lieu of true softkey support).

Vi-Mode Editing

The new o command performs the function of the emacs-mode ^O command.

An initial j command recalls the history line following the history line executed as the previous command. This provides an easy mechanism to repeat a sequence of history commands.

The | command is not supported.

The @<letter> alias function is not supported (in lieu of true softkey support).

The u command performs an emacs-style nested undo; u<space> performs a traditional vi-style undo.

WARNINGS

keysh requires that the $TERM environment variable be set appropriately in your $HOME/.profile file. It also requires that $LINES and $COLUMNS be set appropriately if running on a non-standard size terminal. Otherwise, an error message or a garbled screen display results.

keysh requires that option softkeys be selected from left to right. When editing a command-line, it is possible to back up and insert a softkey out-of-order -- resulting in a command error.

keysh initializes $PS1, $PS2, and $PS3 and types them read-only — do not change them. Instead, use $KEYSH to display additional status information.

keysh normally maintains the $HOME/.keyshrc file without user intervention; however, start-up errors may occasionally occur and persist. In this case, either execute the command kc restart default (to remove the file and revert to the default user configuration) or execute the command kc write (to rewrite the file with the current configuration).

keysh assumes that HP-UX commands are not heavily aliased; otherwise unexpected command translations may occur.

keysh neglects the effects of the Korn-shell expansion mechanisms when counting command-line parameters, causing it to occasionally underestimate the true number of parameters specified. The <ESC>* emacs-mode or vi-mode editing command can often be used to pre-expand these parameters.

The <ESC>v emacs-mode editing command and v vi-mode editing command cannot be used to edit (pre-translated) softkey commands, since no subsequent command translation can occur.

Adding a large number of softkeys can cause keysh to overflow a 1-Mbyte Korn-shell data size limitation, causing disconcerting behavior.

keysh can only program the function keys on terminals whose terminfo(4) entry defines the pfkey capability; similarly, it can only use hardware softkey labels on terminals whose terminfo(4) entry defines the pln capability (along with specifying lh equal to 2).

The default value for $KEYESC was chosen to provide reasonable response in both local and networked environments. If keysh misinterprets quickly typed emacs-mode or vi-mode editing commands as terminal escape sequences, it may be necessary to decrease this value.

Specifying a \n (new-line) in the literal key sequence for a backup softkey causes undesired results on HP terminals; use a \r (carriage-return) instead.

keysh does not display tsm softkeys when simulating softkey labels.

A limited number of environment variables and arguments are exported to the pager when displaying help.

EXTERNAL INFLUENCES

Environment Variables

LANG determines the language in which softkeys and messages are displayed.

LC_TIME determines the format and contents of date and time strings in the status-line.

International Code Set Support

Single-byte character code sets are supported.

AUTHOR

keysh was developed by HP and AT&T.

FILES

/usr/bin/keysh: main executable
/usr/lib/keysh/builtins: Keysh_config softkey definition file
/usr/lib/keysh/$LANG/softkeys: standard softkey definitions file
/usr/lib/keysh/$LANG/keyshrc: default user configuration file
/usr/lib/nls/$LANG/keysh.cat: message catalog
$HOME/.keyshrc: user configuration file
$HOME/.softkeys: user softkey definitions file

keysh(1)

Technical documentation

» Table of Contents

» Index

NAME

SYNOPSIS

DESCRIPTION

COMMAND ENTRY

Softkey Types

Editing The Command-Line

Visible Softkey Commands

Invisible Softkey Commands

Backup Softkeys

Traditional HP-UX Commands

Softkey Command Syntax Errors

Softkey Command Redirections

USING KEYSH WITH TERMINAL SESSION MANAGER

CONFIGURATION

Adding, Placing, And Deleting Softkeys

Specifying Backup Softkeys

Selecting Global Options

Selecting Status-Line Items

Restarting Keysh

Writing Configuration Changes

Undoing Other Configuration Changes

Scaling Keysh Functionalities

EXAMPLES

STANDARD SOFTKEY DEFINITIONS

EXTERNAL INFLUENCES

Environment Variables

KSH DIFFERENCES

Screen Updates

Emacs-Mode Editing

Vi-Mode Editing

WARNINGS

EXTERNAL INFLUENCES

Environment Variables

International Code Set Support

AUTHOR

FILES

SEE ALSO