VSH(5)                               BSD                                VSH(5)



NAME
     vsh - visual shell startup file format

DESCRIPTION
     The visual shell uses an ascii-format startup file, $HOME/.vshrc.  The
     file tells vsh to start up user applications when it is the session
     manager and defines the user commands in the vsh menu bar.  If
     $HOME/.vshrc does not exist, vsh uses the default startup file,
     /usr/X11/lib/system.vshrc.  If vsh is the session manager, then the
     lines:
        session-manager-startup
     will start up the specified program.  vsh is a session manager when
     invoked with the argument -sm.

     session-manager-startup assignments are of the form
        session-manager-startup : command name
     The user menus are defined with declarations of the form
        menu { }
     and
        alias { }
     The menu declaration defines an entry in the vsh menu bar, and alias
     defines a menu selection in that menu.  The order of entries is the order
     that will be found in the vsh menus.

     The assignment session_manager_startup is the only assignment allowed
     outside of either a menu or an alias declaration.  It tells vsh to
     execute the command in the background during startup, if the visual shell
     is the login shell (also called the session manager).  If the vsh is not
     the session manager, this assignment is ignored.  The example shows that
     xclock will start up automatically when the user logs in with vsh as the
     session manager.  At logout, programs started with the
     session_manager_startup command will be terminated.

     The menu declaration is used to create a menu in the vsh menu bar.  After
     the keyword "menu" is the name of the menu entry name, followed by {
     which is followed by one or more alias {} declarations.  Use } after the
     last alias {} declaration to close the menu definition.  Each alias
     declaration in a menu appears in a button in its container menu.  For
     example, the Print menu specified by the example .vshrc below will have
     three entries.  The entry name is the string after the word "alias."

     An alias may have a number of assignments.  These are "output" and
     "command" to tell vsh in what output environment the command is to be
     executed.  There are three possible values:

     background
          For commands that are either server processes or provide their own
          output window like X programs.

     mterm
          If the program requires terminal emulation.

     foreground
          All other programs should output to foreground.

     The syntax for the command strings in the alias assignments is:
     $n
     $*
     $"prompt string"

     These can be used as follows:

     $n   Inserts into the command string the name of the nth object selected
          in the DDA.  (Objects are "ordered" from left to right, as if you
          were reading a page.)

     $*   Inserts the names of all selected objects into the command string,
          so that the command will be executed once for each selected object.

     $"prompt string"
          Produces a dialog box to prompt the user with the string between the
          double quotes.  The user's input will be inserted into the command
          string before the command is executed.

          The $"prompt" command string is useful for changing command line
          arguments.  For example, to print a single file with different
          printer options, the command might be

     pr -f $"printer options" $1
          This command will ask you the question "printer options?" and pause
          to let you answer it.  Since the command uses $1, there must be at
          least one object selected in the DDA or an error will be reported.
          To print all selected files, change the command string to:

     pr -f $"printer options" $*
          If you want, you could locate both of these commands in a menu
          grouping called "Print" with one alias called "Print One" and the
          other called "Print All."  See "Print Menu Grouping," below.

     Syntax errors in the .vshrc file will be reported with a pop-up dialog
     box.  In such an event, no user menus will be defined.  To correct the
     syntax error and properly set up user menus, edit the startup file to
     correct the errors, select "system" from the menu bar, press "User
     Command Menus" and then select "Load Commands" from the bottom of the
     dialogue box.  This will cause vsh to re-read the startup file.

EXAMPLE STARTUP FILE
      session_manager_startup : /usr/X11/bin/xclock -geometry +300+0

      menu 'Print'
      {
          alias 'print 1'
          {
              output  : foreground
              command : 'pr $1'
          }
          alias 'print all'
          {
              output  : foreground
              command : 'pr $*'
          }
          alias 'print all opt'
          {
              output  : foreground
              command : 'pr $"Print Options" $*'
          }
      }

      menu "X"
      {
          alias 'xcalc'
          {
              output  : background
              command : /usr/X11/bin/xcalc -geometry +500+0 -rpn
          }
      }

SEE ALSO
     vsh(1)