unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 keysh(1)							    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.





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




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





 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




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




 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




    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.





 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




    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.




 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




	   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.




 Hewlett-Packard Company	    - 6 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




      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





 Hewlett-Packard Company	    - 7 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




      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.

 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.



 Hewlett-Packard Company	    - 8 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




      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.



 Hewlett-Packard Company	    - 9 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




 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 <&lt&lt&lt;ESC>&gt&gt&gt;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.





 Hewlett-Packard Company	   - 10 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




      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.





 Hewlett-Packard Company	   - 11 -   HP-UX Release 11i: November 2000






 keysh(1)							    keysh(1)




 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

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

























 Hewlett-Packard Company	   - 12 -   HP-UX Release 11i: November 2000