keysh(1)						      General Commands Manual							  keysh(1)

NAME

       keysh - context-sensitive softkey shell

SYNOPSIS

DESCRIPTION

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

       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 is entirely data-driven, allowing its menus and help to be easily extended as needed.

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

COMMAND ENTRY

       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.  automatically translates  these  softkey  com-
       mands 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, 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, temporarily displays a prompt message in place of the
       status-line.  This message briefly describes the required action.

   Softkey Types
       presents four basic softkey types:

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

	      If there are more current choices than there are softkeys,
			     breaks the choices into banks and displays a special softkey along with the first bank.  Selecting the softkey causes
			     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 indi-
			     cate  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 to display a hint  message  on  the
			     status line; the command-line remains unchanged.)

	      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
       supports the normal Korn-shell command-line editing modes.  In addition, 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 softkey is
			   present, perform the 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 configuration option is enabled (see below), 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, inserts its command name into the command-line then displays a sub-menu listing the com-
       mand'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.   automatically  navigates
       the hierarchical softkey menu, always presenting the user with an appropriate set of current choices on the softkey labels.

       Note  that  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 configuration option is enabled (see below) and 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 configuration option is enabled (see below), 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 is displaying its top-level softkey menu,  simply  displays	the  backup  softkeys  and
       allows the user to proceed.

       If 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, treats it as a syntax error, displaying an error message and not accepting the command until the error has been cor-
       rected.

       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, 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)), displays the softkeys instead of the backup softkeys.  If desired, this
       interaction can be overridden by setting the environment variable (see below).

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

CONFIGURATION

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

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

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

   Adding, Placing, And Deleting Softkeys
       Any  of	the  standard softkeys (see below) can be added to the top-level softkey menu using the command.  If desired, an alternate softkey
       label may be specified (usually in place of a cryptic HP-UX command name) using the option.

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

       In  addition to the standard softkeys, custom softkeys can also be added from custom softkey files using the or 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 com-
       mand.

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

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

       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 command before can program them.

   Selecting Global Options
       Various global options can be configured using the command, including:

	      Enable or disable the programming of the backup softkeys.

	      Enable or disable the
			     softkey.

	      Enable or disable the recognition of invisible softkey commands.

	      Enable or disable the automatic generation of prompt messages.
			     When enabled, displays a prompt message whenever the user must perform an action to complete the current softkey com-
			     mand.  This message briefly describes the required action.

	      Enable or disable the use of keyboard selectors.
			     When enabled, 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 char-
			     acter 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.

	      Enable or disable the display of HP-UX command translations.

	      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 command, including:

	      The host name.

	      The user name.

	      The current directory.

	      The mail status based on the
			     environment variable (i.e., or

	      The date.

	      The time of day.

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

   Restarting Keysh
       can  be forced to reread the file with the command.  This command is typically used to update a to a new configuration specified in another
       window.

       can also be forced to remove the file and restart from the default user configuration with the command.

   Writing Configuration Changes
       can be forced to rewrite the file with the command.

   Undoing Other Configuration Changes
       can also be forced to rewrite the file with its original contents, thus undoing all configuration changes made since was invoked, using the
       command.

   Scaling Keysh Functionalities
       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 usu-
       ally have the softkeys visible, the command prevents from displaying its top-level softkey menu while waiting for a  command;  instead,	it
       displays the backup softkeys or softkeys, as appropriate.  start-up time can then be decreased significantly by editing the file and remov-
       ing the lines which add visible softkeys.)

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

       And for users who have no need for the backup softkeys, the command prevents from ever programming the backup softkeys.

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

EXAMPLES

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

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

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

       To add all invisible softkeys from the file

       To add the backup softkeys from the file

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

       To disable the softkey,

       To configure the user name into the status-line,

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

       To list the ten largest files in the current directory,

STANDARD SOFTKEY DEFINITIONS

EXTERNAL INFLUENCES

   Environment Variables
       Specifies the terminal type, as defined in the
		      terminfo(4) database.  This variable must be either part of invocation environment or it must be set within one of the stan-
		      dard Korn-shell start-up files.

       Specifies the number of columns in the terminal screen if different than the
		      terminfo(4) default.

       Specifies the number of lines in the terminal screen
		      if not the same as the terminfo(4) default.

       Specifies the preferred pager to be used to display help.
		      The default is (see more(1)).

       Specifies the time-zone to be used
		      for time and date representations on the status-line.  The default is

       Specifies the character sequence sent to the terminal by
		      to ring the bell.  The default is

       Specifies an alternate
		      configuration file.  The default is

       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.

       If set, specifies that
		      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.

       If set, specifies that
		      should leave the terminal keypad in local mode while commands are being entered.	This mimics  the  behavior  of	the  Korn-
		      shell.

       If set, specifies that
		      should  not  reset  the initial values of and Note that must be a constant character string in order for to recognize it and
		      provide subsequent softkey assistance.

       Specifies arbitrary text to be included in the
		      status-line.

       If set, specifies that
		      should always simulate softkey labels and not use the built-in labels on HP terminals.

       If set, specifies that
		      should not use the softkeys when is running.  In this case, the user can either use the the backup softkeys, or the  softkey
		      command (see above) to switch windows.

KSH DIFFERENCES

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

   Screen Updates
       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, can simply insert or delete characters at the appropriate screen position.

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

   Emacs-Mode Editing
       The new command performs the function of the vi-mode command.

       An initial 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.

       editing mode is not supported; editing mode follows the GNU emacs (18.54) definition of

       The ^@ and commands are not supported.

       The and alias functions are not supported (in lieu of true softkey support).

   Vi-Mode Editing
       The new command performs the function of the emacs-mode command.

       An  initial  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 command performs an emacs-style nested undo; performs a traditional vi-style undo.

WARNINGS

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

       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.

       initializes and and types them read-only -- do not change them.	Instead, use to display additional status information.

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

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

       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 emacs-mode or vi-mode editing command can often be used to pre-expand these parameters.

       The  emacs-mode	editing  command and 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 to overflow a 1-Mbyte Korn-shell data size limitation, causing disconcerting behavior.

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

       The  default  value for 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 (new-line) in the literal key sequence for a backup softkey causes undesired results on HP terminals; use a  (carriage-return)
       instead.

       does not display 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
       determines the language in which softkeys and messages are displayed.

       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

       was developed by HP and AT&T.

FILES

       main executable
       softkey definition file
       standard softkey definitions file
       default user configuration file
       message catalog
       user configuration file
       user softkey definitions file

SEE ALSO

       ksh(1), tsm(1), softkeys(4), terminfo(4).

																	  keysh(1)