unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



 softkeys(4)							 softkeys(4)




 NAME
      softkeys - keysh softkey file format

 BACKGROUND
      keysh 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 window into this softkey node hierarchy
      through which the user can view and select eligible nodes.  A node is
      eligible if it was:

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

	   +  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:

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

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

	   +  Otherwise, if the node's parent still has eligible siblings
	      remaining, they are redisplayed, and so on, moving up the node
	      hierarchy.

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

      At that point, keysh performs the editrules 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 softkey nodes.

      There are two basic types of softkey nodes:

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




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






 softkeys(4)							 softkeys(4)




	   string	  ``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 softkey can be used as a synonym for the keyword
      option.

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

	   {option|string} softkey
	   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:

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

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

	   {filter|command}	    This node is only active for filters or
				    commands, respectively - default is
				    either.

	   {motorola|precision}	    This node is only active when keysh is
				    running on a Motorola (MC680x0) or



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






 softkeys(4)							 softkeys(4)




				    precision (PA-RISC) processor,
				    respectively - default is either.

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

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

	   editrule editrule	    The editrule for this node.

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

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

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

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

      Arguments are as follows:

	   count       A signed integer, the word none, or the word all.

	   editrule    An editrule (described below).

	   helptext    nroff-style 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:

	   backup softkey softkey [literal 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.





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






 softkeys(4)							 softkeys(4)




    Softkey Command Translation
      To translate softkey commands into HP-UX commands, keysh executes the
      editrules associated with each softkey selected by the user.  These
      editrules create a word list via an awk-like 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 last and next
      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 argument is set
      equal to the user input for the softkey (e.g., *.c for the softkey
      corresponding to the file name in this example).

      Note that keysh 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:

	   +  an expression followed by a ;,
	   +  an if statement, or
	   +  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

	   last				 see above
	   next				 see above
	   argument			 see above

	   motorola			 boolean flag
	   precision			 boolean flag
	   command			 boolean flag
	   filter			 boolean flag



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






 softkeys(4)							 softkeys(4)




	   word[number]			 see above

      Simple expressions can be combined with any of:

	   string[number]		 single-character substring
	   string[number,number]	 multiple-character substring

	   number+number		 addition
	   number-number		 subtraction
	   number*number		 multiplication
	   number/number		 division
	   number%number		 modulus
	   string&&amp&amp&string		 concatenation
	   -number			 negation

	   string==string		 equality
	   string!=string		 inequality
	   number>&gt&gt>=number		 greater than or equal
	   number<&lt&lt&lt;=number		 less than or equal
	   number>&gt&gt&gt;number		 greater than
	   number<&lt&lt&lt;number		 less than
	   number&&amp&amp&amp;&&amp&amp&amp;number		 logical and
	   number||number		 logical or
	   !number			 logical not

	   (string)			 grouping

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

	   strlen(string)		 number of characters in string
	   strchr(string,char)		 index of first char in string, or
					 -1
	   strrchr(string,char)		 index of last char in string, or -1
	   trim(string)			 string without leading/trailing
					 blanks
	   hex(number)			 number in hex with leading 0x
	   octal(number)		 number in octal with leading 0

      Assignments can be done with any of:

	   variable=string		 simple assignment
	   variable+=number		 add and assign
	   variable-=number		 subtract and assign
	   variable*=number		 multiply and assign
	   variable/=number		 divide and assign
	   variable%=number		 modulus and assign
	   variable&&amp&amp&amp;=string		 concatenate and assign

	   word[number]=string		 simple assignment




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






 softkeys(4)							 softkeys(4)




	   word[number]+=number		 add and assign
	   word[number]-=number		 subtract and assign
	   word[number]*=number		 multiply and assign
	   word[number]/=number		 divide and assign
	   word[number]%=number		 modulus and assign
	   word[number1]&&amp&amp&amp;=string	 concatenate and assign

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

	   if(number) {
	      edit statement
	      .
	      .
	      .
	   } else {
	      edit statement
	      .
	      .
	      .
	   }

      Where the else 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(number, string);	 Insert string as a new word in the
					 word list immediately before
					 word[number].

	   append(string);		 Insert string as a new word in the
					 word list immediately after the
					 last word in the word list.
					 Equivalent to
					 insert(next, string);.

	   dash(string);		 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(number);		 Delete word[number] from the word
					 list.




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






 softkeys(4)							 softkeys(4)




    Helptext
      Each softkey node can have an associated helptext, 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:

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

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

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

	   .sp				 Force a break and then display a
					 single blank line (a vertical
					 space).

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

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

	   .IL tag indent		 Begin a new indented line (similar
					 to .IP except no blank line is
					 displayed).

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

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

	   softkey cd
	   editrule { append("cd"); }



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






 softkeys(4)							 softkeys(4)




	   {
	     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 <&lt&lt&lt;dir>&gt&gt&gt; disable all
	     editrule { append(argument); }
	     required "Enter the name of the directory to move to."
	     ;
	   }

      For other examples, refer to the file /usr/lib/keysh/C/softkeys.

 AUTHOR
      keysh was developed by HP and AT&T.

 FILES
      $HOME/.softkeys				   user softkey definitions
						   file

      /usr/lib/keysh/$LANG/softkeys		   standard softkey
						   definitions file

 SEE ALSO
      keysh(1), man(5).


















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