softkeys(4)						     Kernel Interfaces Manual						       softkeys(4)

NAME

       softkeys - keysh softkey file format

BACKGROUND

       softkey	information  is  stored  in the form of a softkey node hierarchy.  The top level of this hierarchy represents the softkey commands
       themselves; lower levels represent various command options and parameters.

       The softkey labels form a into this softkey node hierarchy through which the user can view and select nodes.  A node is eligible if it was:

	      o  Enabled by default and has not been subsequently disabled by the selection of some sibling node, or

	      o  Disabled by default, has not been subsequently disabled by the selection of some sibling node, but has been subsequently  enabled
		 by the selection of some sibling node.

       When a softkey node is selected, it can enable or disable any of its siblings as appropriate.  A new window into the softkey node hierarchy
       is then computed as follows:

	      o  If the selected node was not a leaf node, its eligible children are displayed;

	      o  Otherwise, if the node still has eligible siblings remaining, they are redisplayed;

	      o  Otherwise, if the node's parent still has eligible siblings remaining, they are redisplayed, and so on, moving up the node  hier-
		 archy.

       This process of node display and selection continues until the user has entered a complete command.

       At  that  point,  performs the associated with each of the selected softkey nodes.  These editrules create the HP-UX command that is fed to
       the shell for execution.

SOFTKEY FILE FORMAT

       Each softkey file contains one or more softkey definitions, each of which is represented as a sub-hierarchy of

       There are two basic types of softkey nodes:

	      "Options" show up on softkey labels
			     and insert literal text into the command-line when selected.  Examples are command and option names.

	      ``Strings'' (or ``parameters'')
			     show up on softkey labels but do not insert text into the command-line when selected; rather,  they  display  a  hint
			     message.  The user must then type the desired text into the command-line.	Examples are file and user names.

       Note that the keyword can be used as a synonym for the keyword

       The basic softkey node definition is composed of the following components:

	      attribute
		 .
		 .
		 .

       Where  softkey  is  the softkey node name from which the command-line text and softkey label are derived.  If necessary, a single plus sign
       within softkey can be used to force hyphenation of the softkey label at a syllable boundary.

       If a softkey node has an associated sub-menu, its trailing is replaced with a list of child nodes as follows:

	      softkey node
		 .
		 .
		 .

       Each softkey node can have the following optional attribute fields:

	      Selecting this node will disable
				       count softkey nodes to the right of this one - default is 0.

	      Selecting this softkey will enable
				       count softkey nodes to the right of this one - default is 0.

	      This node is only active for filters or commands, respectively - default
				       is either.

	      This node is only active when
				       is running on a Motorola (MC680x0) or precision (PA-RISC) processor, respectively - default is either.

	      This node starts out disabled and must be enabled to be used - default is
				       to start out enabled.

	      The command will be entered automatically when this node is selected.

	      The editrule for this node.

	      An editrule to be executed
				       after all other editrules associated with this softkey command - only one cleanuprule is allowed per  soft-
				       key command.

	      The one line hint for this node - only valid for ``string'' softkey nodes.

	      The help for this node (may be more than one line).

	      The one-line error message to display if this node is not selected.

       Arguments are as follows:

	      count	  A signed integer, the word or the word

	      editrule	  An editrule (described below).

	      helptext	  help enclosed in quotes (also described below).

	      string	  An arbitrary string enclosed in quotes.  Note that within quotes, escapes the next character as when using awk(1).

       A typical backup softkey node definition resembles:

	      softkey literal]

       where literal is the literal text string to program the terminal function key with (if different than softkey).

       An unquoted hash-mark character in a softkey file delimits a comment to the end of the line.

   Softkey Command Translation
       To  translate  softkey  commands  into  HP-UX  commands,  executes  the editrules associated with each softkey selected by the user.  These
       editrules create a via an editing language.  This translated word list is then passed to the shell for execution.

       For a simple translation, this list might resemble:

							+--------+     +---------+     +---------+
							|  ls	 |     |   -l	 |     |   *.c	 |
							|	 +-----+	 +-----+	 |
							+--------+     +---------+     +---------+
							 word[0]	 word[1]	 word[2]

       Every time an editrule is invoked, the special constants and are defined to the index of the last word in the list (``2'' in this  example)
       and the would-be-next word in the list (``3'' in this example), respectively.  In addition, the constant is set equal to the user input for
       the softkey (e.g., for the softkey corresponding to the file name in this example).

       Note that automatically casts numbers and strings back and forth as necessary to carry out editrules.  Also,  variables	are  cleared  only
       before the first editrule associated with a softkey command.  All assigned variables are available to subsequent editrules.

   Editrules
       An editrule is a list of edit statements enclosed in curly-braces (i.e., and

       An edit statement is:

	      o  an expression followed by a
	      o  an statement, or
	      o  a word allocation statement.

   Expressions
       A simple expression can be any of:

	      variable			    single letter from a to z
	      number			    unsigned integer
	      string			    enclosed in quotes
	      char			    enclosed in quotes

	      see above
	      see above
	      see above

	      boolean flag
	      boolean flag
	      boolean flag
	      boolean flag

	      see above

       Simple expressions can be combined with any of:

	      single-character substring
	      multiple-character substring

	      addition
	      subtraction
	      multiplication
	      division
	      modulus
	      concatenation
	      negation

	      equality
	      inequality
	      greater than or equal
	      less than or equal
	      greater than
	      less than
	      logical and
	      logical or
	      logical not

	      grouping

       The following functions are also supported and return the indicated results:

	      number of characters in	    string
	      index of first		    char in string, or -1
	      index of last		    char in string, or -1
	      string			    without leading/trailing blanks
	      number			    in hex with leading
	      number			    in octal with leading

       Assignments can be done with any of:

	      simple assignment
	      add and assign
	      subtract and assign
	      multiply and assign
	      divide and assign
	      modulus and assign
	      concatenate and assign

	      simple assignment
	      add and assign
	      subtract and assign
	      multiply and assign
	      divide and assign
	      modulus and assign
	      concatenate and assign

   if Statement
       The statement is similar to the full-block mode statement in awk, and is structured as follows:

		 edit statement
		 .
		 .
		 .
		 edit statement
		 .
		 .
		 .

       Where the part is optional.  If number is non-zero, the first block of edit statements is executed.  Otherwise, if the second block of edit
       statements is present, it is executed.

   Word Allocation Statements
       Word allocation statements include the following:

	      Insert			    string as a new word in the word list immediately before

	      Insert			    string as a new word in the word list immediately after the last word in the word list.  Equivalent to

	      Append			    string to the last word in the word list if that word already begins with a dash.  Otherwise,  a  dash
					    is inserted as a new word in the word list immediately after the last word in the word list and string
					    is appended to that.

	      Delete			    from the word list.

   Helptext
       Each softkey node can have an associated to be displayed upon a user request for help.  This helptext is formatted on-the-fly and presented
       to the user through the preferred pager.

       The  helptext  format  is an nroff-like language, supporting a subset of the man(5) macros used to write standard HP-UX manual entries.	In
       particular, this subset includes:

	      Begin			    mode.  Display text as-is, preserving new-lines and spaces, until a

	      Resume			    mode.  Display text with words filled onto each output line, attempting to utilize 90% of  the  screen
					    width.  (This is the default mode.)

	      Force a			    in the current output line.  Display subsequent text on the next line.

	      Force a break and then display a single blank line (a vertical

	      Force a break, display a single blank line, and then begin a new
					    with no indent.

	      Force a break,		    display  a	single blank line, and then display the specified tag, then begin a new with the specified
					    indent.

	      Begin a new		    (similar to except no blank line is displayed).

       Note that these macros are recognized in the input helptext, not just at the beginning of a line.  Also, all macro arguments even  if  they
       consist of nothing more than a quoted empty string.

EXAMPLES

       For a custom command (see cd(1)):

	      softkey cd
	      editrule { append("cd"); }
	      {
		softkey keysh-src disable all
		editrule { append("~/keysh/src"); }
		;
		softkey keysh-test disable all
		editrule { append("~/keysh/test"); }
		;
		softkey keysh-doc disable all
		editrule { append("~/keysh/doc"); }
		;
		softkey demo disable all
		editrule { append("~/demo"); }
		;
		softkey tmp disable all
		editrule { append("/tmp"); }
		;
		string <dir> disable all
		editrule { append(argument); }
		required "Enter the name of the directory to move to."
		;
	      }

       For other examples, refer to the file

AUTHOR

       was developed by HP and AT&T.

FILES

       user softkey definitions file

       standard softkey definitions file

SEE ALSO

       keysh(1), man(5).

																       softkeys(4)