using the create_log
subcommand (described below).  For example, dialog editor log output
can be redirected to the current xterm window using the command

    apex_display -editor dialog create_log here

Also note that the output of some subcommands may be produced
asynchronously if apex_display does not wait for the subcommand to
complete.  Use the -synchronous (-s) or -max_wait (-mw) option to
force apex_display to wait for subcommand completion.


Error Messages
--------------

Certain types of apex_display errors are reported in the apex message
window, for example invalid options subcommands.  However, in many
cases, invalid arguments or option values are not reported.  If an
apex_display subcommand appears to do nothing, then either 1) the
output has been written to a server log file, 2) there is an error in
the command, or 3) the subcommand does not produce output.


Syntax Notation
---------------

The syntax equations below use conventional apex syntax notation.
Syntactic elements are named and enclosed in angle brackets ("<>"),
e.g. <option>.

The ellipsis ("...") indicates one or more occurrences of the preceding
element are allowed, usually with a separator character appearing just
before the "...".  For example,

    <number> ...

means one or more numbers separated by spaces, e.g.

    10 5 365

while 

    <number>,...

means one or more numbers separated by commas, e.g.

    10,5,365


Braces ("{}") are used to group elements and to enclose informal
descriptions of elements.  

A vertical bar ("|") is used to separate alternative forms.  

Square brackets ("[]") enclose optional elements.

An occurrence of "//" indicates the rest of the line is a comment
describing an element.


Overall Syntax
--------------

An apex_display command has the form

  apex_display [<option> ...] <subcommand> [<rest>]

where

  <subcommand> ::= <name> | -<name> | <regular_expression>
  <regular_expression> ::= {syntax: . is like * in shell?}

Usually, a simple <name> is used for the subcommand.  A subcommand can
begin with "-" so long as the subcommand name does not conflict with
an option name (purpose?).  If a regular expression is specified, it
must match a single subcommand name.

  <rest> ::=         // syntax depends on the subcommand: 
      [<arg> ...] |  // for a simple subcommand
      [<option> ...] <operation> [<operation_option> ...] [<arg> ...]
                     // for a subcommand that has multiple operations

  <option>       ::= <opt_flag><option_name> [<option_value>]
                               // a command option
  <opt_flag>     ::= -|+
  <option_name>  ::= <name>    // an option name, see Command Options below
  <option_value> ::= <string>  // meaning depends on option
  <name>         ::= {an identifier}
  <string>       ::= {a sequence of characters containing no blanks
                      or a quoted sequence of arbitrary characters}
  <operation>    ::= <name>    // name of the operation to be performed
  <operation_option> := {an option specific to an operation}
  <arg>          ::= <string>  // an argument to the subcommand or operation

Note: Unused options or arguments to a subcommand are generally ignored
      without comment.


Command Options
---------------

The apex_display command recognizes the command options described in
this section.  In addition, specific subcommands (or operations
thereof) may also accept certain options which are described in the
context of the particular subcommand or operation.

All apex_display command options begin with '-' or '+'.  Generally
speaking, command options control the conditions under which a
subcommand is performed.  They may appear before the subcommand and,
for some subcommands, they may also appear after. In either case, the
meaning is the same.

Some options require a value.  If the value contains two or more words
separated by spaces it must be enclosed in quotes.  The same is true
for arguments.

Notes: 
    Each option applies only to specific subcommands, however, no
    errors are issued for the use of inappropriate options.  
    
    The relevant command options are noted in each subcommand
    description.

    Invalid option names are reported. Invalid values may or may not
    be reported.

The command options are:

  <options> ::=
    -editor <editor>        | // editor to process command
    -e <editor>             | // same as -editor <editor>
    -secondary              | // set editor number other?
    -editor2                | // set editor number other?
    -editor3                | // set editor number 3?
    -editor4                | // set editor number 4?
    -editor5                | // set editor number 5?
    -rational               | // set editor number "Force_Apex"?
    -as_text                | // for visits, show object as text
    -emacs                  | // set editor number "Force_Emacs"?
    -use_editor             | // set editor number "User_Editor"?
    -readonly               | // non-editable
    +editable               | // non-editable, read-only
    -editable               | // editable, not read-only
    -activate               | // set focus to a window
    +activate               | // do not set focus
    -no_activate            | // same as +activate
    -iconic                 | // -no_activate plus create window as icon
    -existing               | // do not create
    -key <window>           | // alias key of the window operand
                              // (see Window Identification below)
    -item <item>            | // add item to the items list
    -i <item>               | // same as -item <item>
    -underlines <path>      | // set underlines file
    -options <option>       | // add option to options list
    -as_merged <option>     | // add "-window_kind merged" to options list
    -dialog_option <arg>    | // add arg to dialog_options list
    -dialog_options "<arg> ..." | // add each arg to dialog_options list
    -context <path>         | // set context to <path>
    -c <path>               | // same as -context <path>
    -parameters <param>     | // add <param> to parameters list
    -max_wait <duration>    | // set max_wait to <duration>
    -mw <duration>          | // same as -max_wait <duration>
    -synchronous            | // same as -max_wait UINT_MAX
    -s                      | // same as -synchronous
    -respondent <server?>   | // server? to receive reply from operation
    -server <server>        | // name of an apex server process to use, 
                              // e.g. Apex_Dialog_Server
    -server_required        | // ?
    -d                      | // ?
    -direct                 | // ?
    -reuse <key>            | // set reuse_key?
    -reuse_editor <editor>  | // set reuse_editor?
    -reuse_window <window>  | // set reuse_window?
    -modifiers <modifier_keys> | // set modifiers keys that alter subcommand
    -local                  | // use to the current machine
    -machine <machine>      | // use the specified <machine>
    -m <machine>            | // same as -machine <machine>
    -instance <machine>     | // ?
    -session <session>      | // identifies a saved session
    -window_to_notify <window> | // window to be notified upon completion
    -here                   | // wait for and display the subcommand result?
    -h                      | // same as -here

    -trace_this             | // same as -trace_value 1
    -t                      | // same as -trace_this
    -trace_value <trace_option>     | // set trace option value
    -tv <trace_option>              | // same as -trace_value <trace_option>
    -trace_show <trace_show_option> | // set trace and show option
    -ts <trace_show_option> | // same as -trace_show <trace_show_option>
    -tvs <trace_value_show_option>  | // set trace value and show option
    -tb <trace_breakpoint>  | // puts a server in an interactive loop at
                              // a predefined breakpoint.

    -script_trace           | // trace script at statement level
    -st                     | // same as -script_trace
    -script_trace_value <script_trace_option>
                            | // set a script tracing option
    -stv <script_trace_option> | // same as -script_trace_value <trace_option>
    -script_breakpoint <script_breakpoint> | // set a breakpoint for scripts
    -sb <breakpoint>        | // same as -script_breakpoint <breakpoint>

    <wild_option>           | // regular expression matching any option above
    <window_option>         | // window appearance options
    <output_option>         | // output redirection options

  <editor>   ::= dialog | directory | text | output | windows | 
                 dialog_window | <tbd>?
  <window>   ::= {a window alias, see Window Identification below}
  <machine>  ::= {name of a host machine}
  <session>  ::= ?[:?]
  <duration> ::= {a period of time in seconds}
  <param>    ::= <string>     // a parameter

  Note: See the "tracing" document in /ned/sierra/docs/user_interface.ss 
        form a more detailed description of trace options.

  <trace_option> ::= <trace_level> | <trace_class>
                              // more than one -trace option may be
                              // specified to trace more than one
                              // class, alternatively multiple options
                              // may be enclosed in quotes

  <trace_level> ::= // higher numbers select more trace output
    0   |  // turn tracing off
    1   |  // flow control tracing
    3   |  // operations on many data structures
    5   |  // Rba_String operations (rather voluminous)

  <trace_class> ::= <class>[:{<function_name>+... | <trace_level>}]
                              // enables tracing of a particular apex 
                              // class and optionally sets a trace level 
                              // for that class.  The <function_name>s 
                              // indicate specific methods to be traced.

  <class> ::= {name of an apex class, using lower case without the three
               character prefix, e.g. string_map for Red_String_Map}

  <function_name> ::= {name of function in <class> to be traced, may
                       contain wild card character '.' which matches
                       any characters}

  <trace_show_option> ::= <trace_class> 
                                // only a <function_name> is allowed,
                                // shows the object when the function
                                // is invoked

  <trace_value_show_option> ::= <trace_option> 
                                // like <trace_option> but also has
                                // the effect of a <trace_show_option>

  <trace_breakpoint> ::= // enters a command loop at a point during command
                         // execution, only supported for the following
                         // methods, see the "tracing" document.
    dialog_manager:start_dialog |  // break: when displaying a dialog
    object_editor:display       |  // when displaying a non-dialog window
    evaluator:evaluate          |  // when evaluating a script
    parser:parse_program        |  // when parsing a script
    job_operations:execute      |  // when executing a job
    now                         |  // now
    end                            // at termination (when Rhi_Processes::
                                   // Terminate is called)
                                   
  Note: See "Apex/Summit Script Language Guide" (the apex_shell document) 
        for more details on script breakpoints and script tracing.

  <script_trace_option> ::= <script_tracing_option>[:0] 
                            // Turn a script tracing option on, or off 
                            // if ":0" suffix is included
  <script_tracing_option>
    off             |  // turn tracing off
    all             |  // include subexpression tracing     
    lines           |  // include line numbers in trace
    stmts           |  // trace only statements (not subexpressions)
    original        |  // trace statements before substitution
    resolved        |  // trace statements after args evaluated
    visit_errors    |  // visit source file on line with error
    visit_stmts     |  // visit statements as executed
    visit_exprs     |  // visit subexpressions as executed (for dlisp)
    hilite_stmts    |  // highlight statements as executed
    hilite_errors   |  // highlight statements in error
    dump_original   |  // show original statement in parse tree dump?
    dump_internals  |  // show more information in parse tree dump?
    stdout             // send trace message to standard output

  <script_breakpoint> ::=   // prompt for debugger commands during script
                            // execution (see apex_shell documentation)
    [<script_breakpoint_option> ...]
    <file> <line>        |  // break at <line> in the script in <file>
    <dialog>.<prog>      |  // break at entry to a %prog or %function
                            // named <prog> in a <dialog> type
    <function>           |  // break at entry to a global function
    <action> [<when>]    |  // break on an <action>

  <script_breakpoint_option> ::=  
    -temporary           |  // clear this breakpoint upon first break
    -visit               |  // enable visit script source on break
    +visit               |  // disable visit script source on break
    -clear               |  // remove all script breakpoints (for a server)

  <when> ::=                // for an action script breakpoint
    start                |  // break at start of action (default)
    error                |  // break on error
    end                  |  // break at end of action and on any error

  <dialog>   ::= <name>     // name of a dialog type (e.g. cmvcCheckIn)
  <prog>     ::= <name>     // name of a %prog or %function in a dialog
  <function> ::= <name>     // name of a global function defined in a dlisp
                            // or action file

  <action> ::= [<modifier_key>-...-]<name> // name of an action (prefixed 
                                           // with any qualifying modifiers)

  <modifiers_keys> ::= <modifier_key> ... // list of modifier keys which
                                          // qualify a subcommand
  <modifier_key> ::= shift | lock | control |
                     mod1 | mod2 | mod3 | mod4 | mod5 |
                     button1 | button2 | button3 | button4 | button5

  <path> ::= <string>       // a pathname
  <wild_option> ::= <regular_expression> [<value>]
                            // the expression must match a single option above
  <window_option> ::= 
    // X-related options affecting the appearance of an apex window.

    -title <string>               |  // title for a window created
    -icon_name <string>           |  // title to appear on icon
    -icon_name_prefix <string>    |  // prefix of icon name?
    -window_kind <string>         |  // kind of window (e.g. dialog, text)
    -window_kind_image <string>   |  // ?
    -highlights <string>          |  // describes text to highlight
    -format <string>              |  // ?
    -name_format <string>         |  // ?
    -origin <string>              |  // ?
    -replace <string>             |  // ?
    -geometry <geometry>          |  // size and location on screen
    -background <color>           |  // background color
    -bg <color>                   |  // same as -background color        
    -foreground <color>           |  // foreground color
    -fg <color>                   |  // same as -foreground <color>
    -font <font>                  |  // window text or list font
    -fn <font>                    |  // same as -font <font>
    -buttonbar_background <color> |  // button bar background color
    -buttonbar_foreground <color> |  // button bar foreground color
    -buttonbar_font <font>        |  // font for button bar
    -buttonbar_height <integer>   |  // height of button bar in pixels
    -buttonbar_index <integer>    |  // ?
    -menubar_background <color>   |  // menu bar background color
    -menubar_foreground <color>   |  // menu bar foreground color
    -menubar_font <font>          |  // font for button bar
    -border_color <color>         |  // color for window border
    -bd <color>                   |  // same as -border_color <color>
    -border_width <integer>       |  // width of border in pixels
    -bw <integer>                 |  // same as -border_width <integer>
    -workspace <string>           |  // ?
    -display_options <display_options> |  // window display options
    -center                       |  // center window on screen
    -focus                        |  // set focus to window?
    -not_restorable               |  // ?
    -client_data <string>            // callback data?

  <geometry> ::= {window size and location; see X geometry options}
  <color>    ::= {X color specification}
  <font>     ::= {X font specification}

  <output_option> := 
      // options controlling the display of output produced
      -output_options <output_ops> |  // output disposition options
      -output_title <title>        |  // output heading
      -t <title>                   |  // same as -output_title <title>
      -output_window <window>      |  // window in which output is displayed
      -ow <window>                 |  // same as -output_window <window>
      -output_message                 // create new output window

  <title> ::= <string>
  <output_ops> ::= ?

  <display_options> ::= <display_option> ... 

  <display_option> ::=         // a window display option
    -child_indent <number>  |  // number of spaces to indent subunits
    -clone_window_kind      |  // kind of window to create when a clone
                               // is requested ?
    -default_context <path> |  // initial context for the window
    -format <string>        |  // adds a format to the list for window
                            |  // formats are identified by position
    -full_subunit_names     |  // do not elide the prefixes of subunit names
                               // that are the same as the preceding subunit
    -geometry <string>      |  // specifies the X geometry option for the
                               // window (size and location see X windows)
    -iconic                 |  // create window in the iconified state
    -indent <number>        |  // number of spaces to indent subdirectories
    -initial_format <name>  |  // the name of the initial display format
                               // (see the "perform format" subcommand)
    -limit_slashes          |  // suppress "/"s after directory names
    -no_suffix              |  // suppress all type marks after names
    -root_format            |  // adds a root format to the list for window
    -rule_file <path>       |  // the rules file to use for the window
                               // (contains actions, display formats, etc., 
                               //  see directory_rules.C function read rules)
                               // 
    -show_all               |  // show all window entries (e.g. hidden files)
    -show_all_same_order    |  // show all window entries and ? (used?)
    -show_parent            |  // show the ".." directory entry
    -sort_by_control        |  // sort by CM status: out/in/uncontrolled
    -sort_by_kind1          |  // sort by kind: each index identifies a
    -sort_by_kind2          |  // Red_Object_Matcher object used to sort -
    -sort_by_kind3          |  // kind1 corresponds to the View:Sort:By Kind
    -sort_by_kind4          |  // which sorts by file kind
    -sort_by_kind5          |
    -sort_by_kind6          |
    -sort_by_kind7          |
    -sort_by_kind8          |
    -sort_by_kind9          |
    -sort_by_kind10         |
    -sort_by_name           |  // sort lines by name of line
    -sort_by_size           |  // sort from largest to smallest
    -sort_by_time           |  // sort entries most recent modification time
    -sort_by_time_directories_first 
                            |  // sort by time with directory lines at
                               // beginning
    -sort_by_time_directories_last
                            |  // sort by time with directory lines at end
    -sort_children          |  // ?
    -sort_directories_first |  // place directory lines at beginning
    -sort_directories_last  |  // place directory lines at end
    -subunit_levels <number>|  // level of the deepest subunit to display
    -title <string>         |  // the title bar text for the window
    -window_kind [<kind>.]<subkind>] |
                               // the kind of window to create (see 
                               // editor_interface.ss//editor_names/
                               // dir_window_kinds
                               // (<kind> defaults to "directory")
    hide <regular_exp>      |  // hides lines with names matching a
                               // regular expression (filter option)
    show <regular_exp>      |  // show lines with names matching a
                               // regular expression (filter option)


Trace Command Options
---------------------

The trace command options noted above (e.g. -trace_value,
-script_trace_value) set trace options in the current process (the
process executing the apex_display command).  These trace options
persist in the current process after the apex_display command
completes.  For example, when the apex_shell is used, the trace
options will also apply to the next command processed.  The current
trace options can be changed using another apex_display command with
the desired trace options.

To turn on tracing in a specific editor or server (instead of the
current process), use the trace* and script_trace* subcommands.  Also
see the "tracing" document in /ned/sierra/docs/user_interface.ss for
more information.


Window Identification 
---------------------

Some subcommands and options require an argument which identifies a
window (usually denoted as <window>).  The way in which a window is
identified depends on its type.

  - Directory and text windows are identified by the full canonical path
    name of the directory or file they display.

  - Summary windows are identified by generated unique keys. The key
    for the last summary window created can be obtained via the
    command

      apex_display -editor directory query last_created

  - Dialog windows are generally identified by generated unique keys.  
    The key for the last dialog created can be obtained using the
    command

      apex_display -editor dialog query last_created

  - Task editor dialogs are a special case and are identified by the full
    pathname of the task displayed.


Common Arguments
----------------

The following are definitions of arguments which occur in a number of
subcommands:

<server_or_editor> ::= <program> | <editor>

  Identifies a server process via a program name
  (e.g. Apex_Dialog_Server) or by naming an editor that the server
  program hosts.  For example, the dialog editor is hosted by the
  Apex_Dialog_Server program so both

      Apex_Dialog_Server 
  and
      dialog

  identify the same server.

  Although a full path name can be used to identify a server, only a
  simple name is required since apex server programs are normally
  found via the $path variable.

  <tbd: others>


Subcommands
-----------

The following subcommands are supported by the apex_display command:

  <subcommand> ::=
      action_perform                  host_architecture
      ada_naming                      iconify
      alias                           iconify_all
      analyzer                        impact
      analyzer_query                  imports
      apply                           index
      asis                            inform
      batch                           jobs
      beep                            jobs_history
      build_body                      jobs_queue
      build_key                       killpg
      call                            language
      canonical_message               length
      canonical_path                  lower
      change_state                    lower_all
      check_bindings                  machines_info
      check_license                   make_inline
      check_menus                     match
      check_rules                     message
      close                           model
      close_all                       move_session
      close_with_save                 notes
      cmvc_data                       notify_window
      cmvc_data_latest                open_dialog
      cmvc_status                     output_window
      command_server                  perform
      completed                       pop_session
      copy_session                    predefined
      cpp_browse                      program_finished
      create_log                      program_started
      create_shell                    push_session
      create_shell_on                 push_shell
      create_summary                  query
      debug                           raise
      debugger_break                  raise_all
      debugger_breakpoints            release_access
      debugger_catch                  release_license
      debugger_catch_all              replace_session
      debugger_catch_here             reread_bindings
      debugger_continue               reread_rules
      debugger_display                restore_history
      debugger_exceptions             restore_session
      debugger_input_output           return_access
      debugger_jump_to                rose
      debugger_log                    rose_query
      debugger_memory                 run
      debugger_modify                 run_job
      debugger_monitors               run_program
      debugger_propagate              save
      debugger_propagate_all          save_all
      debugger_propagate_here         save_history
      debugger_raise                  save_session
      debugger_registers              saved_sessions
      debugger_repeat_step            script_break
      debugger_run_returned           script_run
      debugger_run_to                 script_trace
      debugger_show                   selection
      debugger_stack                  send
      debugger_step_instruction       server_exists
      debugger_step_into              server_state
      debugger_step_over              servers
      debugger_step_statment          session_default
      debugger_stop                   session_exists
      debugger_tasks                  session_message
      debugger_visit_assembly         session_shutdown
      delete_root_property            sessions
      delete_session                  sessions_refresh
      demotion_impact                 set_environment
      deselect                        set_priority
      dialog                          set_root_property
      dialog_get                      set_selection
      dialog_run                      set_value
      dialog_run_last                 setenv
      dialog_run_specific             shell
      differences                     show_errors
      editor_call                     show_history
      editor_operation                show_licenses
      elements                        show_session
      enclosing_subsystem             show_state
      enclosing_view                  show_unused
      errors                          show_usage
      execute                         shutdown
      execution_add                   shutdown_all
      execution_add_cross             shutdown_viewer
      execution_archive               start
      execution_archsetup             start_on
      execution_command_servers       started
      execution_cross                 substring
      execution_info                  switches
      execution_machines              synchronous_call
      execution_method                target_architecture
      execution_remove                terminal
      execution_remove_cross          terminal_handle
      execution_reset                 test_license
      execution_save                  test_shell
      execution_server_machine        trace
      execution_tempdir               trace_all
      exit_apex                       trace_break
      exports                         trace_off
      file_version_info               trace_show
      gen_menus                       trace_verbose
      get_context                     ttyname
      get_environment                 unregister
      get_license                     unsaved
      get_log_name                    unused
      get_priority                    usage
      get_root_property               version
      get_value                       version_info
      getenv                          version_number
      help                            versions
      histories                       view_kind
      history                         view_relative
      hold                            visit
      hold_add                        visit_ada
      hold_archive                    visit_asis
      hold_archives                   visit_cpp
      hold_images                     visit_diana
      hold_insert                     visit_rose
      hold_internals                  wait
      hold_items                      wait_for_command
      hold_items_full                 wait_for_job
      hold_names                      wait_for_last
      hold_other_datas                which
      hold_paths                      which_session
      hold_prepend                    window_exists
      hold_replace                    window_image
      hold_set                        window_info
      hold_set_full                   window_list
      hold_show                       window_perform
      hold_values                     window_query
      hold_window                     windows


Some of the most commonly used subcommands and operations are
described in the sections which follow.
        

beep
----

  Rings the bell.


close <window>  ...
-----

  Closes the windows with given alias keys. The -editor option is
  required unless the <window> is identified by a pathname.

  Command options used: -editor, -server, max_wait, respondent.


close_all
---------

  Closes all windows managed by <editor> or <server> if the -editor or 
  -server option is specified. Otherwise, closes all apex windows.

  Command options used: -editor, -server.


create_log <log>
----------

  Each apex server has a log file to which various trace messages and
  diagnostics are written.  A file is created in /tmp for log output
  when an apex server is started. See Command Output above.

  The create_log command starts a new "log file" for a server.  The
  server may be specified by the -server option or an editor may be
  specified with the -editor option (which indicates the server that
  hosts the specified editor).  If no server is specified, the
  Apex_Message_Server is assumed.

  The <log> argument indicates where the server log output should go.

    <log> ::= 
        here    | // redirect output to the current xterm window
        xterm   | // create and redirect output to a new xterm window
        <file>  | // redirect output to the specified file
        default   // redirect output to the standard log file

  Command options used: -editor, -server.


create_summary [<option> ...] <path> 
--------------

  Creates a summary window using the datafile identified by <path>.
  
  The following command options (specifically window options) are used
  in creating the window:

    -title <string>        // window title
    -icon_name <string>    // short (icon) title
    -window_kind <name>    // the kind of window  
    -summary_key <string>  // the identifier for the summary window
    -delete_file           // delete the datafile after processing
    -dont_delete_file      // don't delete the datafile after processing
    -visit_if_one          // visit the only item instead of creating a window
    -replace               // replace existing summary window items
    -display_options "<display_options>" // display options (for a new window)

    <display_options> ::= <display_option> ...  (see Command Options above)
    
  If the -summary_key option is specified and a window exists with that
  key, the information in the datafile <path> is appended to the summary
  window or replaces existing data in the summary window if the -replace
  option is used.  Otherwise, a new summary window with the specified
  summary key is created using the datafile.

  The datafile is processed by Red_Directory_Display::process_datafile
  in directory_display.C.  If the -delete_file option is specified, the
  datafile is deleted after processing.  The processing of the datafile
  depends on the type of summary window.

  If the summary is being created and the -visit_if_one option is
  specified and there would be just one item in the window, the item
  is visited and the window is not created.


dialog <name> [<dlg_option> ...] [<arg> ...]
------

  Creates and displays an instance of the dialog type <name> with the
  specified options and arguments.

  The <dlg_option>s control properties of the dialog instance created:

  <dlg_option> ::= 
    -window_id <window>  |  // calling window (originator)
    -key <window>        |  // alias for dialog window (generated by default)
    -window_kind <kind>  |  // a string indicating the kind of window
                            // (defaults to "dialog")
    -window_kind_image <image> 
                         |  // the kind name to be displayed in the
                            // Windows window (defaults to <kind>)
    -dialog_file <path>  |  // name of the file containing the dialog
    -revert              |  // close existing instances and reload the 
                            // dialog file (do not reuse an existing
                            // instance)
    -not_restorable      |  // indicates dialog cannot be restored
                            // when the session is restored
    -server_instance <?> |  // passed along to the dialog as an option?
    -initialize_script <prog> 
                         |  // a dialog %prog to be run to initialize the
                            // dialog instance (e.g. for a specific use)
    -destroy_on_close    |  // delete the dialog upon close (do not
                            // reuse the instance created)

  If the -dialog_file option is omitted, the dialog <name> must have
  already been loaded from a dialog file, such as the dialog files in
  $APEX_HOME/dialogs that are loaded at startup (also see the dialog
  editor "perform" operation "load").

  The arguments [<arg> ...] are passed to the dialog when it is started
  as dialog arguments number 3 and up. The first argument to a dialog
  is considered argument number 0.  The arguments passed to a dialog
  are the following:

    arg[0]   - <name>, also the default title
    arg[1]   - context (directory) in which dialog is to run
    arg[2]   - options to the dialog instance. These include any options
               specified using the command options -dialog_option or
               -dialog_options.  Options specified using the command
               option -options are passed as the value of an option
               named -display_options in this argument.
    arg[3..] - operands of the dialog (e.g. a list of file names) or 
               other dialog specific arguments (these are copied from
               the [<arg> ...] list).

  Command options used: -editor, -key, -context, -machine, -max_wait, 
    -respondent.
                
    
dialog_run_last
---------------

  Effectively presses the OK button in the last dialog created and
  waits for the operation invoked to complete.

  Command options used: -max_wait, -machine.


dialog_run_specific <window>
-------------------

  Effectively presses the OK button in the dialog identified by
  <window> and waits for the operation invoked to complete.

  Command options used: -max_wait, -machine.


elements <path> ...
--------

  Displays an Elements window for the object identified by a <path>.
  If <path> is a view, the elements in the default history are
  displayed.  If <path> is a version, the elements of that objects
  history are displayed.  If <path> is Summit history directory
  (<subsystem>/.Rational/Version_History/<history>), the elements of
  that history are displayed.

  Command options used: -max_wait, -context, -server_required, 
    -machine, -respondent


execute [<exec_option> ...] {<program> [<arg> ...] | <command> ...}
-------

  The subcommands "execute" and "run" are the same.  The specified
  <program> or the <command>s are executed. The <exec_option>s control
  how the program or commands are executed.
  
  If the -commands option is present, the list of commands is executed
  in the given order.  Commands containing spaces must be quoted.
  Otherwise, the specified <program> is executed with the trailing
  arguments [<arg> ...] passed as parameters.

  After the options are processed, the Red_Job_Operations::Execute
  function in /ned/sierra/editor_interface.ss//job_operations.C is
  called to carry out the request.

  <exec_options> ::= 

    // Input/Output:

    -xterm                 |  // read/write std input/output from/to xterm
    -xtermerr              |  // write standard error to xterm
    -xtermin               |  // read standard input from xterm
    -xtermout              |  // write standard output to xterm

    -filein  <file>        |  // accept standard input from <file>
    -in <file>             |  // same as -filein <file>
    -fileout <file>        |  // redirect standard output to <file>
    -output_file <file>    |  // same as -fileout <file>
    -out <file>            |  // same as -fileout <file>
    -fileerr <file>        |  // redirect standard error to <file>
    -err <file>            |  // same as -fileerr <file>

    -fdin  <descriptor>    |  // accept standard input from file <descriptor>
    -fdout <descriptor>    |  // redirect standard output to file <descriptor>
    -fderr <descriptor>    |  // redirect standard error to file <descriptor>

    -null                  |  // same as -nullout
    -nullout               |  // discard standard output
    -nullerr               |  // discard standard error output
    -nullin                |  // use empty standard input

    -inherit_error         |  // inherit standard error from current process
    -inherit_input         |  // inherit standard error from current process
    -inherit_output        |  // inherit standard output from current process

    -append                |  // append to standard output and error files
    -append_error          |  // append to standard error
    -append_output         |  // append to standard output
    -delete_input          |  // delete standard input file at end?

    // Host Machine:

    -machine <machine>     |  // run program on host <machine>
    -m <machine>           |  // same as -machine <machine>
    -same_machine          |  // run on current machine
    -sm                    |  // same as -same_machine
    -arch_or_same_machine  |  // run on same architecture or same machine?
    -no_query              |  // do not query for selected machine?

    // Job registration:

    -register_info <cmd_info> |  // register with <cmd_info>
    -register                 |  // register as user job ?
    -no_register              |  // do not register job
    -nr                       |  // same as -no_register
    -action_register <cmd_info> <cmd_line> 
                              |  // register as action with <cmd_info> and
                              |  // <cmd_line> ?
    -register_other <other_data> |  // ?
    -job_id <job_id>          |  // use <job_id> as job identifier

    // Command server utilization:

    -default_command_server |  // use the default command server
    -dcs                    |  // same as -default_command_server
    -command_server         |  // ?  
    -cs                     |  // same as -command_server
    -command_server_name <cmd_server?> 
                            |  // use command server <cmd_server>
    -csn                    |  // same as -command_server_name

    // Scheduling:

    -batch                  |  // queue as batch job
    -at <time>              |  // start after <time>
    -start_after <time>     |  // start after <time>
    -after_job <job_id>     |  // start after <job_id> completes
    -aj <job_id>            |  // same as -after_job
    -after_selected         |  // start after ?
    -as                     |  // same as -after_selected
    -after_last             |  // start after last job finishes?
    -al                     |  // same as -after_last
    -after_running_jobs     |  // start after all jobs running now complete
    -after_queued_jobs      |  // start after all jobs queued now complete
    -after_all_jobs         |  // start after all jobs?
    -aa                     |  // same as -after_all_jobs
    -indefinite             |  // ?
    -show                   |  // same as -indefinite ??

    // Output disposition:

    -here                   |  // display output in current xterm window?
    -connection <file>      |  // ?
    -connection_output <?>  |  // ?
    -push_connection <?>    |  // ?
    -rio_out                |  // ?
    -output_window          |  // use output window?
    -ow                     |  // same as -output_window
    -message_window         |  // output to message window?
    -output_message         |  // same as -message_window
    -om                     |  // same as -output_message
    -title <string>         |  // job output title
    -output_title <string>  |  // same as -output_window and -title <string>
    -ot <string>            |  // same as -output_title <string>
    -canonical_output       |  // ?
    -co                     |  // same as canonical_output

    // Execution synchronization:

    -wait                   |  // wait for child processes to complete
    +wait                   |  // do not wait child processes to complete

    -s                      |  // set max_wait to UINT_MAX
    -synchronous            |  // set max_wait to UINT_MAX
    -mw <duration>          |  // set max_wait to <duration>
    -max_wait <duration>    |  // set max_wait to <duration>
    -respondent <editor?>   |  // set respondent ?
    -window_to_notify <window> |  // window to notify upon completion

    // Debugging:

    -debug                  |  // use debugger
    -debug_number <number>  |  // ?
    -dn <number>            |  // same as -debug_number <number>
    -debugger <name>        |  // debug with debugger <name>
    -d <name>               |  // same as -debugger <name>
    -debug_options <opt>    |  // add <opt> to debugger options list
    -environment <opt>      |  // same as -debug_options except that
                               // -debug must first be specified?
    -attach_pid <pid>       |  // add -attach_pid <pid> to debugger options
                               // indicates existing process to be debugged?
    // Misc.

    -commands               |  // execute the <command>s given, otherwise
                               // execute the <program> with [<arg> ...]
    -first_error            |  // quit on first error
    -fe                     |  // same as -first_error
    -orphan                 |  // ?
    +orphan                 |  // ?
    -pre <commands>         |  // execute <commands> before program
    -post <commands>        |  // execute <commands> after program
    -base                   |  // ?
    -setenv <name_value>    |  // set an environment variable in the
                               // process created
    -trace                  |  // set the trace option value to 1 in
                               // current process
    -no_interpret           |  // run a script or apex command in a new
                               // process instead of directly interpreting
                               // in the command server process?
    -context <path>         |  // context in which to execute program
    -server                 |  // set job kind to user_server?
    -server_instance <local_name> // ?

  <descriptor> ::= <number>  // a unix file descriptor
  <file>       ::= <path>    // a file pathname
  <machine>    ::= {name of a host machine to run program on}
  <time>       ::= {format?} // a time and date
  <cmd_info>   ::= {command information for job registration?}
  <cmd_line>   ::= ?
  <cmd_server> ::= ?
  <opt>        ::= {a debugger option, in quotes if necessary}
  <pid>        ::= <number>  // a process id
  <duration>   ::= <number>  // a period of time in seconds
  <job_id>     ::= {a job identifier}
  <name_value> ::= <name>=<value> // an environment variable name and value
  <commands>   ::= {one or more commands separated by newlines}

  Command options used: None. The above options must be used instead.

  Execute argument processing:

    The arguments to the <program> may contain options that require
    preprocessing.  If there is a global apex_shell function called

      execution_command_options
    or
      _execution_command_options

    that function is called passing the <program> and the arguments
    specified.  This function may return a modified <program> and
    arguments to use in place of the original values.

    If no such global function exists, certain standard command option
    preprocessing is performed based on the architecture and the
    project (if any) associated with the context in which the program
    is to be executed. ?

    The command or program to be run is checked against a list of
    commands or programs that have filters.  If the program is apex,
    apex_action, or apex_summit the subcommand immediately following
    the program is checked. Otherwise the program is checked.  Each
    argument is checked against the filter and if a match is found,
    ...?
  

exports [<view> ...]
-------

  Displays exports for one or more views in Exports windows. 

  Command options used: -max_wait, -context, -server_required, 
    -machine, -respondent


get_value <property>
---------

  Queries the message server to return the value of <property> (?).
  If -editor is specified, the particular editor is queried via the
  window_query subcommand.  Otherwise, the message server handles the
  request. ?

  Command options used: -editor, -server, max_wait, machine.


getenv [<env_option> ...] <variable>
------

  Displays the values of environment variables from the current
  process, if the -here option is specified, or from the server
  indicated by the -server or -editor command option. By default the
  Apex_Message_Server is queried.

    <variable> ::= {variable name which may include wild card characters}
    <env_option> ::= <format> | -flat | -here

    <format> ::=  // the format in which the values are to be displayed
      -sh    | // use sh format: <name>=<value>, but quote any
               // value (`<value>`) containing a special character
      -csh   | // use csh format: setenv <name> <value>
      -value   // display values only: <value>

    -flat      // replace embedded newlines with spaces, otherwise
               // they are included and escaped with backslashes

    -here      // display environment variables of the current process

  The <format>s are mutually exclusive. If no <format> is specified,
  the sh format is used without quoting.

  Command options used: -editor, -server, -max_wait, -machine.


help [[-info] -dialog <name> ... | Version | <topic> ...]
---- 

  Displays the Apex html documentation in the web browser. There are
  four different forms of this command

  With no options, the main Apex help page (topic name H) is
  displayed.

  If the -dialog option is specified, help information for each dialog
  named is checked.  An error is reported if no information is found.
  If the -info option is also included, only the topic name and the html
  filename are displayed.  Otherwise, the html page for the dialog is
  displayed in the web browser.

  If the Version option is specified, a page containing the Apex
  version information for the current session is displayed by the web
  browser.

  If a list of topics is specified, 

    <topic> ::= <name> // identifies a topic (<tbd> naming conventions)

  each topic is displayed in the web browser.  A single web browser
  window is used to display the topics.
  

iconify <window> ...
-------

  Iconifies the specified windows. The -editor option is required
  unless the <window> is identified by a pathname.

  Command options used: -editor, -server, max_wait, respondent.


iconify_all
-----------

  Iconifies all windows managed by <editor> or <server> if the -editor
  or -server option is specified. Otherwise, iconifies all apex
  windows.

  Command options used: -editor, -server.


lower <window> ...
-----

  Lowers the specified windows in the Z order (send to back). The
  -editor option is generally required unless the <window> is
  identified by a pathname. (works?)

  Command options used: -editor, -server, max_wait, respondent.


lower_all
---------

  Lowers all windows managed by <editor> or <server> if the -editor or 
  -server option is specified. Otherwise, lowers all apex windows.
  (works?)

  Command options used: -editor, -server.


message [<arg> ...]
-------

  Writes the arguments to the message window (or a blank line if no
  arguments are specified).

  Command options used: None.


perform [<option> ...] <operation> [<context>] [<modifiers>] [<op_args>]
-------

  Performs an editor-specific operation where

    <options>   ::= {additional command options}
    <operation> ::= {name of operation - depends on editor (see below)}
    <context>   ::= -context <path>
    <modifiers> ::= -modifiers <modifier_keys>
    <op_args>   ::= <arg> ... // arguments depending on <operation>

  Command options used: -editor, -key, -context, -modifiers, -machine, 
    -max_wait, -respondent, -here, -server, -server_required.

  The -key <window> option is used for perform operations that apply
  to a specific window.

  The <context> and <modifiers> may also be specified as command options
  -context and -modifiers.

  The perform subcommand is handled in object_editor_operations.C
  which sends a message to the appropriate server according to the
  editor specified.  Each editor has a function that handles perform
  operations.  The editor must be specified using the -editor command
  option.

  Perform subcommands are ignored in batch mode.

  If -context is omitted, the current working directory is used.
  The interpretation of <operation> depends on the editor.


  o general perform operations
  -----------------


    new_menu_item <window_kinds> <menu_item_kind> <menu_path> <widget>
    ------------- [<label> [<mnemonic>]]

      Creates a new menu item (via the specified -editor), where

        <window_kinds> ::=    // the kinds of windows to be modified
          <window_kind> ... |
          <window_kind_pattern> ... // wild carded window kinds
                  // window kinds are defined by the menu database in
                  // /ned/sierra/misc/menus.ss, see partial list below.

        <menu_item_kind> :=  // type of menu item to be created
          Root         |     // (Root not allowed by new_menu_item)
          cascade      |
          pushbutton   |
          togglebutton |
          text_choice  |
          separator    |
          Popup
            
        <menu_path> ::= item_name.... | ""  // identifies menu

     The <menu_path> is the "pathname" of the menu to receive the new
     item. This is a list of menu widget names separated by dots
     ("."), e.g "file.new" for File:New. The value "" indicates the
     menu bar.

        <widget>    ::= <name>       // name of the new menu item widget
        <label>     ::= <string>     // label on new menu item
        <mnemonic>  ::= <character>  // short-cut character for the new item

    If <label> is omitted or empty, <widget> is used as the label.

    The menus of existing windows in the session are updated
    immediately.  The user's .Rational directory is updated to define
    the new menu item in subsequent sessions.

    Partial list of window kinds (see /ned/sierra/misc/menus.ss):

      <window_kind> ::=
        // For the directory editor, some of the kinds are:
        directory |
        directory.branchdir |
        directory.clients |
        directory.compare |
        directory.completion |
        directory.completion |
        directory.cpp_items |
        directory.cpp_unused |
        ... <tbd> |
        directory.objects |
        directory.other |
        directory.status | 
        directory.subsystems |
        directory.tasklist |
        directory.tree_view |
        directory.unused |
        directory.usage |
        directory.versions |
        directory.views |
        hold |
        windows |

        // For the text server, some of the kinds are:
        text |
        text.configuration |
        text.cpp |
        text.cpp_browser |
        text.difference |
        text.merged |
        text.notes |
        text.switches |
        text.version


    send  <server> <operation> [<arg> ...]
    ----

      Sends a command (<operation>) with arguments to the specified
      <server>.  Used to communicate with Rose.?

        <operation> ::= <number> |  // operation code
                        <name>      // operation name
     

  o dialog editor perform operations:
  -----------------------

    Perform operations for the dialog editor are processed in
    /ned/sierra/dialogs//dialog_support.ss//dialog_manager.C by
    Rfm_Dialog_Manager::Perform.

    The following dialog perform <operation>s are provided:


    add_dialog_path <path> ...
    ---------------

      Adds the specified pathnames to the dialog search path.  These
      are the directories that the dialog server searches when loading
      dialog files.


    call <function> [<arg> ...]
    ----

      Invokes the specified dlisp or apex_shell global dialog
      %function with the specified arguments.  A dlisp call of the
      form

        <call,<function>,<arg>,...>

      is executed where

        <function> ::= <name>  // the name of a global %function

      The call occurs without any dialog context.


    cause_reload [all | <dialog> ...]
    ------------

      Causes instances of the specified dialog types (<dialog> ...)
      to be closed and discarded.  This forces new instances to be
      created the next time these dialogs are invoked. The keyword
      "all" indicates that all dialogs are to be reloaded.


    clear_cache
    -----------

      Purges all dialog instances. (Does not close the dialogs first.)


    clear_types
    ----------- 

      Closes all dialogs and discards all dialog types.


    clear_widget_tree [all | <dialog> ...]
    -----------------

      Discards the widget tree for the named dialog types.


    help_check <dialog>
    ----------

      Forms the help topic for the given dialog type name and checks
      the existence of the associated help file.


    help_info <dialog>
    --------

      Same as help_check, but also displays the topic, the matching
      link name and associated help file name.


    load <file> ...
    ----

      Finds the specified dialogs files (searching the dialog path if
      necessary). Each dialog file found is loaded (or reloaded),
      i.e. read and parsed.  The definitions in the file are added to
      the lists of known dialog types and functions.


    parse <file> ...
    -----

      Similar to load, except that the files read are only checked.
      The definitions are not added to the known dialogs and
      functions.


    remove_type <dialog> ...
    -----------

      Similar to cause_reload except that programs for each dialog
      type are cleared and the type binding is discarded.  This forces
      the type to be reloaded when required.


    reset <path> ...
    -----

      Sets the dialog search path using the specified list of
      pathnames, closes all dialogs, deletes all dialog types and then
      reloads dialog from the new dialog path.


    set_dialog_path <path> ...
    ---------------

      Sets the dialog search path using the specified list of
      pathnames.


    set_x_selection <text>
    ---------------

      Sets the clipboard selection in each dialog instance to the
      specified <text>.


    visit_project <project> ... 
    -------------

      Finds the file corresponding to each project name and visits it
      (purpose ?).


  o dialog_window editor perform operations:
  -------------------------------

    The dialog_window editor is implemented by dialog_window_editor.C
    (Red_Dialog_Window_Editor) in editor.ss.  Dialog windows are
    implemented like dialogs but may also have menu bars.  Menu items
    can invoke predefined actions or actions defined locally by %progs
    in the *.wnd file that defines the dialog_window.

    The following options are recognized by the perform operations
    handle by this editor:

    <dialog_option> ::=
      -window_id <string> |  // alias key for a window to notify
      -revert             |  // reread the *.wnd action file
      -action_file <path> |  // pathname of the action file
      -key <string>       |  // dialog alias key
      -options <string>   |  // options passed to dialog (arg[2])
      -context <path>     |  // dialog context directory (arg[1])

    The following dialog window perform <operation>s are provided:


    create [<dialog_option> ...] <window_kind> <dialog_type> [<arg> ...]
    ------

      Creates a new dialog window of the type specified by the
      <dialog_type> option.  If the -key option is specified, it is
      used as the alias key for the dialog window, otherwise a new key
      of the form K<number> is automatically generated.  The remaining
      dialog options have the same meanings in the "dialog" subcommand.
      Any <arg>s specified are added to the arguments passed to the
      dialog as arg[3] and up.

      The window (if any) identified by the -window_id option is notified.
        
      <window_kind> ::= <name>  // name of a window kind
      <dialog_type> ::= <name>  // the name of a dialog type

      
    show [<dialog_option> ...] <window_kind> <dialog_type> [<arg> ...]
    ----

      Searches for a dialog window of the given <window_kind>.  If
      such a window is found, it is raised.  If not, the window is
      created as though the create <operation> above were called. In
      either case, the window (if any) identified by the -window_id
      option is notified.

      <window_kind> ::= <name>  // name of a window kind
      <dialog_type> ::= <name>  // the name of a dialog type


  o directory editor perform operations:
  --------------------------

    Perform operations for the directory editor are processed in
    /ned/sierra/edit/directory_editor.ss//directory_ops.C by
    Red_Directory_Ops::Perform_Action. These operations have the
    form

    <action> [<args> ...] 

      Performs <action> (an operation) with the specified arguments in
      the <window> identified by the -key command option.  These
      actions apply to most windows containing menu bars.

      Directory menu operations can be invoked, as well as window
      operations such as selecting display lines.  There are
      approximately 183 actions supported.

      For a menu <action>, if any arguments are specified they are
      used in place of the current selection in the window.

      The <action> name for a menu operation is generally the same as
      the simple menu item name in lower case with any spaces removed.
      For example,

          abandon is the action for Control:Abandon
          checkin is the action for Control:Check In

      in some cases the enclosing menu name is included, e.g.

          showdifferences is the action for Control:Show:Differences

      The operations "visit" and "visitinplace" are exceptions. These
      operations require arguments.  There are special operations
      corresponding to the visit menu items:

          visitmenuitem is the action for Navigate:Visit
          visitinplacemenuitem is the action for 
              Navigate:Visit In Place          

      An example of an operation that is not a menu item is

          selectlines - selects lines identified by line numbers
             in the directory window

      See dir_operation_names.C in host_interface.ss//names for a
      complete list of these action names (table Red_Diract).  See
      Perform_Action in directory_ops.C for the action
      implementations.

      <action> ::= // the following actions are provided
        abandon                         newc
        addchildren                     newconfiguration
        addexport                       newcpp
        addholdnames                    newdirectory
        addimport                       newexportset
        addtowindow                     newfile
        analyze                         newhistory
        applyalternative1               newobject
        applyalternative2               newsubsystem
        applyalternative3               newview
        applyalternative4               notes
        applyoperation                  objectdeleted
        applysource                     parse
        buildbody                       parseada
        buildprivate                    pretty
        busy                            print
        changefileproperties            redisplayselected
        changesubsystemproperties       refresh
        changeviewproperties            refreshformats
        check                           refreshimports
        checkin                         registermainprogram
        checkout                        remodel
        clean                           removeexport
        clone                           removeimport
        cloneparent                     removewarnings
        cmvclocation                    revert
        cmvcmerge                       revertall
        cmvcrefresh                     runprogram
        code                            select
        compare                         selectall
        compareall                      selectlines
        compareconfigurations           selectmatching
        comparedirectories              selectsomebutton
        compareexports                  setholdnames
        compareimports                  shell
        comparelatest                   showclients
        comparesubsystems               showcomparison
        compareswitches                 showdependencies
        context                         showdifference
        copy                            showdifferences
        copypathnames                   showerrors
        cut                             showexports
        debugprogram                    showhistories
        delete                          showholdnames
        deselectall                     showimpact
        deselectother                   showimporters
        deselectwindow                  showimports
        discard                         showimportstatus
        dofilter                        showjustbutton
        dogrep                          showlocks
        domerge                         showmainprograms
        donotes                         shownotes
        doreplace                       showobjectstatus
        doselect                        showproperties
        doubleclick                     showstatus
        drop                            showswitches
        editor                          showunused
        elements                        showusage
        elide                           showversion
        enclosing                       showversionimage
        enclosinginplace                showversions
        expand                          showviews
        expandobject                    sortkind
        filecopy                        subdirectories
        filefind                        subsystemproperties
        fileproperties                  toolsfind
        filter                          toolsreplace
        finalizewindow                  traceprogram
        find                            tracereplay
        findbutton                      unbusy
        format                          undiscard
        hidebutton                      unhidebutton
        histories                       unregistermainprogram
        hold                            updatedependencies
        holdada                         updateobjects
        holdsetnext                     updateviews
        holdsetprevious                 versions
        holdtext                        versionsattributes
        home                            viewproperties
        homeinplace                     viewsbutton
        importers                       visit
        importrelations                 visitadaname
        importsdiagram                  visitbody
        jobs                            visited
        link                            visitinplace
        maintain                        visitinplacemenuitem
        make                            visitmenuitem
        makeinline                      visitswitches
        move                            windowchanged
        movestorage                     windowhistory
        newada                          windowremoved
                                        windows

    Actions:


    format <format_name>
    ------

      Formats a directory window using the format called <format_name>.
      The format names correspond to View:Format menu items as follows.

        <format_name> ::=
          names              |  // Names
          cmvc_status        |  // CM Status
          file_attributes    |  // File Attributes
          cmvc_attributes    |  // CM Attributes
          version_attributes |  // Version Attributes
          access_attributes  |  // Access Attributes
          with_kind          |  // With Kind
          ada_attributes     |  // Ada Attributes
          rci_attributes     |  // Rci Attributes
          user_format<n>        // user-defined format number n (1-based)
                                // each has a user-defined menu name

      (See the View:Format:Define dialog for more information about formats.)
    

    refreshformats
    --------------

      Performs the Redisplay operation on all windows that have the
      View:Formats:Define dialog command, e.g. to update the windows
      after a format is changed.


    runProgram  <arg> ...
    ---------- 

      Runs a job in the manner of the File:Run command.


    shell [-machine <name>] [-title <string>] [-context <path>] 
    ----- [-unmanaged] <xterm_options> ...

      Creates a new Apex shell window (like Tools:Shell).  The options
      are:

        -machine <name>  // the host machine on which to run the window
        -title <string>  // the window title
        -context <path>  // the initial working directory

        -unmanaged       // do not set LIBPATH, display, shell and 
                         // title arguments.  If omitted, the
                         // APEX_UNMANAGED_SHELLS switch is checked.

        <xterm_options> ::= {additional options or arguments passed to
                             the xterm program (if xterm is used)}


    showdifference [<file1> [<file2>]]
    --------------

      If no arguments are specified and the button1 modifier is used,
      the -key command option is required and specifies a window in
      which the selected files are to be diff'ed.  Otherwise the
      specified files are diff'ed.


    showdifferences [<file1> [<file2>]]
    ---------------

      If two files are specified, diff those files.  Otherwise check
      modifiers and if alternative 2 is set diff latest and current,
      or if alternative 3 is set diff last checked in and current.
      Otherwise, diff the selected files in the window identified by
      -key.


    windows <mask> | [<option> ...] [<display_option> ...]
    -------

      Displays or raises the Windows window which lists the windows
      belonging to the current session.  The <mask> or <option>s
      control which types of windows are displayed.  The <mask> sets a
      bit array that indicates the desired options.  The <option>s
      alternatively specify window types individually or in groups.
      The display options set the window display options for the
      windows window.

        <option> ::=        // specifies window options including individual
                            // window types or groups of window types to
                            // be displayed
          -editor        |  // kinds: text, configuration, switches, header, 
                            // c, c++, java, and ada
          -text_other    |  // all other kinds (non -editor) of text windows?
          -directories   |  // kinds: subsystem, view, and directory
          -<window_kind> |  // name of a specific window kind

          -new_window    |  // force creation of a new windows window
                            // rather than changing the default instance
          -no_prefix     |  // do not display the window-kind prefixes
          -verbose          // (not used?)

        <window_kind> ::= 
          <name>      |  // the name of a specific directory window kind
                         // or one of the following window kind names used 
                         // by the windows window:
          subsystem   |  
          view        |
          windows     |
          ada         |
          diana       |
          asis        |
          text        |
          config      |
          switches    |
          header      |
          c           |
          c++         |
          c++browser  |
          java        |
          text        |
          difference  |
          merged      |
          version     |
          notes       |
          debugger    |
          output      |
          terminal    |
          shell       |
          jobs        |
          hold        |
          dialog      |
          rose        |
          analyzer    |
          external    |
          other

        <mask> ::= <archive_image>
            // indicates which types of windows are displayed

        <archive_image> ::= {1|0}_<count>_<number>_...
            // This serves as the image of a bit array.  No spaces are
            // allowed.  The 1 or 0 indicates whether bits should be
            // cleared or not. The <count> is the highest bit used.  
            // of <number>s is separated by underscores.  Each number
            // indicates unsigned decimal value of the bits in a 32-bit
            // the slice of the array.


  o text editor perform operations:
  ---------------------


    finishDialog <alias> <op> <file> <offset> <scope> <context> <mask>
    ------------

    Performs an operation in the context of a compilation (<context>).
    
        <alias> ::= {alias for a text window}

        <op> ::= <tbd>  // operation to be performed

    (Details <tbd>, processed by text_window.C in /ned/sierra/edit/test_oe.ss)


  o taskmgmt editor perform operations:
  -------------------------

    <tbd>


  o debugger perform operations:
  ------------------

    <tbd>


  o output_editor perform operations:
  -----------------------


    closeterminal  <window>
    -------------

      Closes the xterm window identified by <window>.


    raiseterminal  <window>
    -------------

      Raises the xterm window identified by <window>.


query <operation> [<arg> ...]
-----

  Retrieves information from an editor according to the <operation>
  specified.  The <operation>s depend on the <editor> specified in the
  -editor command option.

  Command options used: -editor, -max_wait, -context, -key, -machine.


  o common query operations (for any editor):
  --------------


    action <action_designator>
    ------

    Displays an action from the rules file for the editor given by the
    -editor command option.  The filename and line number where the
    action is defined is displayed, and an indication of whether the
    action requires the "/bin/csh" shell or the "apex" shell.

      <action_description> ::= <modifiers> ... <name>
                   // identifies an action (e.g. action "shift print")


    actions
    -------

      Displays all actions in the rules file for the editor given by
      the -editor command option.  For each action, the modifiers and
      action name are displayed, the filename and line number where it
      occurs, and an indication of whether the action requires the
      "/bin/csh" shell or the "apex" shell.


    context
    -------

      Returns the current working directory for the server specified
      by the -server or -editor option.


    function <name>
    --------

      Reports the filename and line number where the function (if
      any), identified by <name> and visible to the <editor> specified
      by the -editor command option, is defined.


    functions
    ---------

      Reports the filename and line number of every function visible
      to the <editor> specified by the -editor command option.


  o directory editor query operations:
  ------------------------


    last_created
    ------------

      Returns the alias key of the last directory window created.


  o dialog editor query operations:
  ---------------------


    last_created
    ------------

      Returns the alias key of the last dialog window created.


  o output editor query operations:
  ---------------------


    lastoutputwindow
    ----------------

      Returns the alias key of the last output window created.


  o windows editor query operations:
  ----------------------


    all_windows
    ----------- 

      Displays sorted information about all apex windows (from the
      windows window), including

        prefix kind  // the kind name displayed in the windows window
        window kind  // the actual kind name
        alias key    // window identifier
        title        // window title
        server       // server owning the window
        local name   // ?

  ...<tbd> more queries in most editors


raise <window> ...
-----

  Raises the specified windows. The -editor option is generally
  required unless the <window> is identified by a pathname (a text
  or directory window).

  Command options used: -editor, -server, max_wait, respondent.


raise_all
---------

  Raises all windows managed by <editor> or <server> if the -editor or
  -server command option is specified. Otherwise, raises all apex
  windows.

  Command options used: -editor, -server.


reread_bindings <object_editor>
---------------

  Rereads the key bindings file for the specified <editor> and may
  thereby redefine keystroke actions. The editors (grouped by server)
  include:

    Directory server:
      directory
      windows
      hold

    Text server:
      text

    Debugger server:
      debugger

    Any server:
      apex

    Output server:
      output
      jobs

  An "<editor>_bindings" file (in the user's .Rational directory) may
  define a mapping from keystrokes (or keystroke combinations) to apex
  actions for an editor.  See the "key_bindings" document in
  /ned/sierra/docs/user_interface.ss for details.

  Command options used: -server, max_wait, respondent.


reread_rules
------------

  Reinitializes the information which controls and/or customizes the
  operation of the <editor> specified by -editor option (or the
  directory editor by default).  

  This information in general is referred to as the "rules" for the
  editor.  In the case of the directory editor the rules read from the
  file include:

    apex_rules and directory_rules files 
        - these are read from in the $APEX_HOME/editor_files and
          subdirectories thereof and from the user's .Rational
          directory
    default directory format - (reloaded internally)
    predefined directory formats - (reloaded internally)
    user directory formats - from user's .Rational directory


restore_session [-replace | -iconify] [<session_name> [<editor>]]
---------------

  Restores the saved apex session identified by <session_name> or the
  "latest" session by default.  Windows from the restored session are
  recreated.  The options may occur anywhere after the subcommand
  name.
  
    -replace   // replace existing windows with the restored windows

    -iconify   // iconify existing windows before restoring

    <session_name> ::= <name>  // name of the session to be restored,
                               // without the ".session" extension
                               // (default is "latest")

    <editor> ::= <name>        // editor to be restored (default is
                               // all editors)

  When both -replace and -iconify are omitted, a standard restore is
  performed in which saved windows are added to the existing windows
  in the current session.

  The <editor> argument determines what is restored.  When no editor
  is specified, windows of all editors are stored.  The -server and
  -editor command options may be used instead of the <editor>
  argument.

  Command options used: -editor, -server, max_wait, respondent.


run [<exec_option> ...] {<program> [<arg> ...] | <command> ...}
---                       

  Same as the "execute" subcommand.


run_program  <program> [<arg> ...]
-----------

  Sends a run_program request to the Message Server to execute
  <program> with the specified <arg>s.  The <program> is executed
  as a child process of the Message Server.

    <program> ::= <path>  // path name of the executable (can be a script)

  Command options used: -context, -machine.


save <window> ...
----

  Save the windows identified.  An editor or server may be specified.
  For a text window, the text is saved in the associated file.

  Command options used: -editor, -server, max_wait, respondent.


save_session [-visible] [<session_name> [<editor>]]
------------

  Save windows for a session, which can be restored using the
  restore_session subcommand.

    -visible                   // do not save iconified windows

    <session_name> ::= <name>  // name of the session to be saved,
                               // without the ".session" extension
                               // (default is "latest")

    <editor> ::= <name>        // editor to be saved (default is
                               // all editors)

  The <editor> argument determines what is saved.  When no editor is
  specified, windows of all editors are saved.  The -server and
  -editor command options may be used instead of the <editor>
  argument.

  Command options used: -editor, -server, max_wait, respondent.


script_break <editor> <script_breakpoint>
------------

  Sets a script breakpoint which causes the script debugger to prompt
  for commands when the evaluator encounters the breakpoint.

    <script_breakpoint> ::= {see the Command Options section}

  See "Apex/Summit Script Language Guide" (the apex_shell document) for
  details.


script_run [<s_option> ...] [<editor> [<s_option> ...] [<script>]] [<arg> ...]
----------

  Runs an apex_shell script, optionally in the context of a specified
  editor and window (e.g. a dialog or directory window).  If no
  <editor> is specified and the -editor command option is omitted, the
  script is run by the current process.  A <window> context may be
  specified using the -key command option.

  The script may be specified literally in the argument <script> or by
  the -rest option, or by the name of a file containing the script, or
  by the name of a known action or function.  The trailing arguments
  are passed as the parameters to the script.

  The result returned via a return statement may be displayed, as well
  as any standard output produced and the text of the condition
  produced by the script evaluator.  These results are written to
  standard output, if requested, in the following order:

    result:     usually one line, but depends on the script
    condition:  a blank line if successful, else a script failure message
    output:     any lines written to standard output by the script

  <s_option> ::=
      -context <path>    |  // same as the command option
      -key <window>      |  // same as the command option
      -machine <machine> |  // same as the command option
      -local             |  // same as the command option
      -window_to_notify <window> | // same as the command option

      -file <path>       |  // specifies the file containing the script
      -script <path>     |  // same as -file <path>
      -rest              |  // indicates that the rest of the command line
                            // is the script to be run
      <control_option>      // script control option

  The <control_option>s are passed as options to the evaluator
  (which interprets or executes the script).

  <control_option> ::=  <tbd: some descriptions>
      -action <name>   |  // name of the action to invoke
      -function <name> |  // name of the function to invoke
      -b <breakpoint>  |  // sets a script breakpoint for debugging
      -bt <arg>        |  // set temporary script breakpoint
      -ignore_errors   |  // continue execution when errors occur
      -inline <names>  |  // a list of commands that are to be interpreted
                          // as apex_shell files. These are parsed and
                          // interpreted by evaluator when invoked.
      -job_line <line> |  // ?
      -last_line <line>|  // line number at which to terminate script 
                       |  // execution (not used?)
      -line <line>     |  // line number at which to begin script
                          // execution (not used?)

      // Results requested:

      -result          |  // return the result in standard output
      -condition       |  // return evaluator condition in standard output
      -output          |  // return output from script in standard output

      // Script output disposition:

      -message_window  |  // write output to message window
      -output_window   |  // write output to output window
      -title <title>   |  // title to use in message or output window
      -xterm           |  // write output to a new xterm window
      -output_file <file> | //  write standard output to file
      -no_output       |  // discard output
      -standard_output |  // send script output to standard output? (default?)
      -show_result     |  // include result in output?

      -no_register     |  // do not register as job

      // Prefix and suffix are evaluated in the same context as script:

      -prefix <statements> |  // statements to execute before script
      -suffix <statements> |  // statements to execute after script

      -script_machine <machine> |  // machine to run script on?
      -separate        |  // run as action?
      -shell <name>    |  // shell interpreter (default: apex_shell)

  <breakpoint> ::= <script_breakpoint> // see the Command Options section

  <script> ::= <statements>  // statements comprising the script

  <statements> ::=        // statements in the scripting language, e.g. for
                          // shell scripts:
    "<statement>;..."  |  // quoted statements separated by semicolons}
    <statement>\;...      // statements not requiring quotes separated
                          // by escaped semicolons

  The script to be executed may be specified in one of the following
  ways. If the option

    -file <path>
  or
    -script <path>

  is used, the file identified by <path> contains the script.

  The script may be specified literally as the argument <script>
  (usually in quotes with statements separated by semicolons).

    "<statement>;..."

  The script may be specified literally as the remaining 
  arguments following the -rest option

    -rest <statement>\;...

  In shell scripts, the statements must be separated by semicolons
  which must be escaped if they are not enclosed in quotes.

  Instead of a script, the -action or -function option may specify a
  global action or function to be invoked that is known to the
  specified editor.  Such actions and functions include those in
  scripts that are loaded by an editor from the $APEX_HOME/dialogs or
  $APEX_HOME/editor_files directories, when the editor is initialized.

  If both a script and the -action or -function option are specified,
  only the named action or function within that script is executed.

  When a script contains functions, the script body consists of the
  statements which are not in any function body.

  Command options used: -editor, -server, -key, -context,
    -window_to_notify, -max_wait, -machine.


script_trace <editor> <script_trace_option>
------------

  Sets a script tracing option.

    <script_trace_option> ::= {see the Command Options section}
  
  See "Apex/Summit Script Language Guide" (the apex_shell document) for
  details.


server_state <operation> [<arg> ...] | [<server> ...]
------------  

  Displays the internal state of apex servers. If the <operation>
  clause is omitted, detailed information about the specified
  <server>s is displayed.  If the <server>s are also omitted, detailed
  information for all servers is displayed.

  Command options used: -max_wait

  Operations:


    apps [all]
    ----

      Shows registered applications including servers.?  If "all" is
      specified, complete data is provided.


    jobs [-verbose | -v]
    ---- 

      Shows registered applications which are jobs.? If the -verbose or
      -v option is included, the command and context are also shown for
      each job.


    name
    ----

      Shows the name of the current apex session. (Blank line if none).


    servers [<server> ...]
    -------

      Shows summary data for the apex servers specified, if any, and
      for all active servers otherwise.


setenv <variable> <value>
------

  Sets the value of the environment variable named by <variable> to
  <value> in all apex servers or in a specified server (when the
  -server or -editor option is included).

  Command options used: -server, -editor, -max_wait, -respondent.


show_licenses
-------------

  Displays license information managed by the Message Server.
  Shows which licenses are available. ?

  Command options used: -max_wait.


show_state <editor> <show_command> [<arg> ...]
----------

  Displays information about the state of the specified <editor>.  The
  <show_command> and arguments indicate the specific information to be
  displayed which generally depends on the <editor>.  When information
  about a specific window is to be shown, the -key command option must
  be included.

    <show_command> ::= 
        <general_show_command> | // general show command
        <<editor>_show_command>  // editor-specific show command

    <general_show_command> ::= // most editors support these show commands
      breakpoints     | // show script breakpoints
      function_names  | // show script function names
      functions       | // show script function info
      function_trees  | // show script function parse trees
      function <name> | // show parse tree of function <name>
      menus           | // show menu state
      actions         | // show action state
      action <name>   | // show info about action <name>
      editor_server   | // show the editor->server name map (not working?)
      prefs           | // show the window preferences state ?
      log_policy      | // show log policy image ?
      hiswitches      | // show cached environment variable values 

    <dialog_show_command> ::= // dialog editor show commands
      dialog_names       | // show names of all dialog types
      <dialog>           | // show information about a specific dialog type
      dialogs            | // show names and titles of dialog instances
      dialog_instances   | // show more information about dialog instances
      <dlg_window>       | // show summary information about a specific dialog
      <dlg_window> all   | // show full information about a specific dialog
      domain_programs    | // show all popup domain programs (name & address)
      domain_program <popup> 
                         | // show parse tree of a specific popup domain
      range_programs     | // show popup range programs (name & address)
      range_program <popup>// show parse tree of a specific popup range

    <dialog>     ::= <name>   // name of a dialog type (e.g. cmvcCheckOut)
    <dlg_window> ::= <window> // alias key for a dialog window (e.g. D7)
    <popup>      ::= <name>   // name of a dialog popup menu

    <directory_show_command> ::=
      rules   | // show directory_rules state ?
      filter  | // show filtering state ?
      windows   // show state of the Windows directory

    <tbd: any other show commands>

  Command options used: -editor, -key, -machine, -max_wait, -respondent.


show_state <editor> <registered_object>
----------

  This is another form of the show_state subcommand where

    <registered_object> ::= <name>  // name of a registered object

  This subcommands displays a registered object in the specified
  editor.  A registered object is an object that has been registered
  with a name dynamically in the C++ code.  The set of registered
  objects is itself registered. Thus, the objects registered for the
  dialog editor can be displayed with the command:

    apex_display show_state dialog register_objects

  See the "apex_shell" document in /ned/sierra/docs/user_interface.ss
  for more details about registered objects.

  Command options used: -editor, -machine, -max_wait, -respondent.


shutdown <server_or_editor> [<save_info>]
--------

  Shuts down the specified apex server or the server associated with
  the specified editor.  Session info is optionally saved.  This may
  be used before restarting a server (e.g. in the debugger).

    <save_info> ::= [<option> ...] <session> <arg> ...

    <option> ::=   // options are passed to server
      -visible  |  // only save windows that are not iconified
      <tbd>

    <session> ::= <name>  // name of session file to save (without extension)

    <arg> ::= <string>    // additional argument passed to server <tbd>

  Command options used: -editor, -server.


shutdown_all  [<save_info>]
------------

  Shuts down all apex servers in the current session.  Effectively
  does an Exit Apex, optionally saving the session.

    <save_info> ::= {see the shutdown subcommand}

  Command options used: None.


start [<option> ...] <server_or_editor> [<arg> ...]
-----

  Starts an apex server passing any arguments specified (e.g. trace
  options).  The <server_or_editor> may also be specified using the
  -editor or -server option.
  
  This command no effect if the server is already running.

  If a unqualified server executable name is specified, it is resolved
  using of the $path variable value.

  Also see the start_on subcommand.

  Command options used: -context.
  

start_on [<option> ...] <machine> <server_or_editor> [<arg> ...]
--------

  This subcommand is the same as start above, except that the server
  is started on a specified machine.

    <machine> ::= {name host machine to run the server on}

  Command options used: -context.


trace <editor> <trace_option> | <editor> low_level | <server>
----- 

  Sets the specified <trace_option> in <editor>, or if <server> or
  low_level is specified, turns on low-level tracing in the indicated
  server.
  
    <trace_option> ::= {indicates type of tracing, see Command Options}

  <tbd: explain effect or specifying editor rather than server>?

  See the "tracing" document in /ned/sierra/docs/user_interface.ss for
  details.


trace_all <editor> | <server>
---------

  Same as

    trace {<editor> | <server>} 1

  which turns on control flow tracing in the specied <editor> or
  <server>.


trace_break {<editor> | <server>} <trace_breakpoint>
-----------

  Set a breakpoint at one of the predefined trace breakpoint
  locations.  The server prompts for commands when the breakpoint is
  encountered.

    <trace_breakpoint> ::= {see the Command Options section}


trace_off <editor> | <editor> low_level | <server>
---------   

  Cancel tracing options for the specified <editor> or turn off
  low-level tracing in a server.


trace_show {<editor> | <server>} <trace_show_option>
----------

  Displays an object when a function is invoked in the given <editor>
  or <server>.

    <trace_show_option> ::= {see the Command Options section}


trace_verbose <editor> | <server>
-------------

  Same as

     trace {<editor> | <server} 3

  which shows operations on many apex data structure classes.


unregister [<server_or_editor>]
----------

  Removes the specified server from the server table.  If a server
  fails or dies without unregistering itself, it may be necessary to
  issue this subcommand before the server can be restarted.  If the
  <server_or_editor> is omitted, the -server or -editor command option
  must be specified instead.

  Command options used: -server, -editor.


visit <arg> ...
-----

  Same as apex visit command.


window_exists [<editor> <window>]
-------------

  Checks if <window>, managed by <editor>, exists.  The variable
  "status" is set to 0 if the window exists and to a non-zero value
  otherwise.  If the <editor> and <window> arguments are omitted they
  must be specified using the -editor and -key options instead.

  Command options used: -editor, -key, -max_wait, -machine.


window_image [<editor> <window>]
------------

  Writes the textual contents of <window> managed by <editor> to
  standard output. If the <editor> and <window> arguments are omitted,
  they must be specified using the -editor and -key options instead.

  Command options used: -editor, -key, -max_wait, -machine.


window_perform [<editor> <window>] <operation> [<arg> ...]
--------------

  The window_perform subcommand performs an operation on a specific
  window.  If the <editor> and <window> arguments are omitted, the
  -editor and -key command options must be specified instead.  The
  operations are editor specific.

  Command options used: -editor, -key, -modifiers, -machine, 
    -max_wait, -respondent.


  o general window_perform operations:
  ------------------------


    activate
    --------

      Same as "setfocus" followed by "makelatest" (see below).


    applyitems [<location> [<alternative>]]
    ----------

      Applies an action to each item in the hold set.  Actions depend
      on the window and selection.

      <location> ::= -1  |  // is apply ?  (the default)
                     -2  |  // on menu bar
                     -3  |  // on tool bar
                     -4     // on window

      <alternative> ::= <number>   // alternative commands 0-4
                    
      The default actions may be performed for a window if <location>
      is "on menu bar" (-2) or "on tool bar" (-3) and the item is an
      object.  If the -modifiers command option includes the control
      key, the "Open" dialog is raised for the item.  Otherwise the
      item is visited directly.
      
      
    close
    -----

      Close the window.


    display  <option> ... <alias_key>
    -------

      Displays (visits) an item (object) in an editor window and
      activates the window.

      <option> ::=
        -in_place          |  // display the item in place
        -editable          |  // make it editable
        -item <item>       |  // item to be displayed
        -options <options>    // other options <tbd>

      <alias_key> ::= <string>  // alias key for new window


    display_item  <item> [<mode>]
    ------------

      Displays an <item>? in the given <mode> or else "as is".
      Action depends on the editor.

        <item> ::= <tbd>     // the item to display
        <mode> ::= <number>  // the mode <tbd> ?


    drop
    ----

      Applies each item in the current drag and drop set to the current
      drop location. <tbd - more details>


    getholdset  [<location>]
    ----------

      Builds and displays a hold set from the window.  The <location>
      is an index into the window's data that indicates the item(s) to
      be held.  If <location> is omitted, -1 is used which is
      interpreted as the first item in the window.  If the location is
      within the current selection in the window, the entire selection
      is held.  Otherwise only the specified location is held.

      The hold set contents are displayed in the message window in the
      form of an error message. The hold set is then discarded.

        <location> ::= <number>  // an item index within the window.

      See editor.ss//frame.C function Get_Hold_Set for details.


    holdline [<hold_options>] <text>
    --------

      Holds the specified single line of <text> with the <options>
      specified.

        <text> ::= <string>  // a single line of text giving a location

        <hold_options> ::= <hold_option> ...
        <hold_option> ::= 
          -all              |  // hold all of selection
          -quite            |  // do not display the hold set
          -replace          |  // replace existing hold set entries
          -insert  <number> |  // insert after hold item <number>
      

    holdtext [[<hold_options>] <text>]
    --------

      With no arguments copies the current selection as text to the
      hold set.  Otherwise, stores the given <text> in the hold set
      with any specified <options>.

        <text> ::= <string>   // the text to be placed in the hold set
        <hold_options> ::= {see the holdline subcommand}
        

    iconify
    -------

      Iconify the window.


    makecurrent
    -----------

      Meaning depends on the editor.?


    makelatest
    ----------

      Meaning depends on the editor.?


    raise
    -----

      Raise the window.


    saveifneeded
    ------------

      Save the window (via Save) if it needs to be saved (according to
      Save_Needed) to the associated file.

    
    saveto <file>
    ------

      Save the window in <file>.  Action depends on type of window.


    setbusy  [<busy>]
    -------

      Increments or decrements the busy count for the window. If the
      count is incremented to one, the watch (busy) cursor is
      displayed, if the count is decremented to 0 the the default
      cursor is displayed, otherwise the cursor is not changed.
      
        <busy> ::= <boolean>  // true to increment, false to decrement
                              // default is true


    setbusycount <value>
    ------------

      Sets the busy count to <value>.  The cursor is not affected.

        <value> ::= <number>  // the value to store in the busy count


    setcontext <path>
    ----------

      Set the directory context for the window to <path>.

    
    setfocus
    -------- 

      Raise the window, set input focus to the window, and set the
      current widget in the window to the default focus widget.


    settitle <title>
    --------

      Change the title of the window to <title> and report the
      change to the windows window.

        <title> ::= <string>


    setshorttitle <title>
    -------------

      Change the short title (the icon title) of the window to <title>.

        <title> ::= <string>


  o dialog editor window_perform operations:
  ------------------------------


    apply [<execution_option> ...]
    -----
    
      Effectively presses the Apply button in the dialog identified by
      <window>.  Does not wait for the operation invoked by the dialog
      (if any) to complete.  (Also see the "dialog_run_*" subcommands
      which do wait.)

      <execution_option> ::= 
        -after_selected |   // sets modifiers button1, shift and mod1
        -indefinite     |   // sets modifiers button1, control, shift and mod1
        -parallel       |   // inserts the option -parallel
        -clients        |   // inserts -parallel and appends -clients
        -imports        |   // inserts -parallel and appends -imports
        -batch          |   // appends -batch

      The <execution_option>s affect the perform or execute command
      (if any) run by the dialog %prog exec.  These options correspond
      to options on the menu displayed when the OK or Apply button is
      pressed with mouse button 3.  See the Job Control dialog for
      details.


     call <name> [<arg> ...]
     ----

      The operations "call" and "run_program" are the same. They
      invoke the %prog or %function identified by <name> in the
      context of the specified dialog <window>, passing any arguments
      provided.


    cancel
    ------

      Effectively presses the Cancel button in the dialog identified by
      <window>.


    help
    ----

      Effectively presses the Help button in the dialog identified by
      <window>.


    make_busy
    ---------

      Makes the dialog specified by <window> display the busy (watch)
      cursor.


    ok  [<execution_option> ...]
    --

    Effectively presses the OK button in the dialog identified by
    <window>.  See "apply" above for details.


    reset
    -----

      Effectively presses the Reset button in the dialog identified by
      <window>.


    run_program <name> [<arg> ...]
    -----------

      Same as "call" above.  Invoke the %prog or %function identified
      by <name> in the context of the specified dialog <window>,
      passing any arguments provided.


    setw <widget> <value>
    ----

      Sets the value of <widget> to <value> in the dialog identified
      by <window>. The <window> may have the value LAST_CREATED to
      indicate the most recently created dialog.


    unbusy
    ------

      Changes the cursor for the specified dialog <window> to the
      default cursor.


  o directory editor window_perform operations:
  ---------------------------------


    <action> [<arg> ...]

    These <action>s (except for those below) are exactly the same as
    the actions invoked by a perform subcommand of the form

        perform <action> [<arg> ...]

    See the directory editor perform operations for details.


    apply_test_format <format>
    -----------------

      Applies the specified formatting command string <format> to the
      directory window to reformat it. (See the View:Format:Define
      dialog for information about formats.)


  o text editor window_perform operations:
  ----------------------------


    <action> [<arg> ...]

    These actions are applicable to text editing windows.  Several of
    these actions permit <search_option>s which have the following
    syntax:

      <search_option> ::= 
        <direction> |   // if not specified, search the entire file
        -case       |   // consider case of alphabetic characters
        -wildcard   |   // interpret wildcard characters
        -append     |   // append to current underline list
        -color <name>   // name of highlight color (default "highlight")

      <direction> ::= -forward | -backward  
                        // forward or backward from cursor position,
                        // if omitted, searches forward from start
                        // of text


    capitalize
    ----------

      Changes the first letter of each word in the current selection to
      begin with a capital letter and changes all other letters to
      lower case.  Words are delimited by spaces, dots (.), and
      underscores (_).

      If nothing is selected, the operation applies to the token at
      the cursor.


    changeall [<search_option> ...] <target> <replacement>
    ---------

      Changes occurrences of <target> to <replacement>.  (See
      Search & Replace command on the text window Search bar.)


    changeallselected [<search_option> ...] <replacement>
    -----------------

      Changes occurrences of the selected text to <replacement>.  (See
      Search & Replace command on the text window Search bar.)


    changeselected <replacement>
    --------------

      Changes the current selection to <replacement>.  (See Search &
      Replace command on the text window Search bar.)


    changetext <target> <replacement>
    ----------
    
      Replaces a string, whose position in the text window is defined
      by <target>, with the string <replacement> where

        <target> ::= 
            <line_target> |  // identifies target by line and column
            <char_target>    // identifies a target by character position

        Note: No spaces are allowed in <target>!

        <line_target> ::= # [<relative>] <offset> [: <column>] [. <length>]
        <char_target> ::= % [<relative>] <offset> [. <length>]

        <relative> ::= - | +   // above or below cursor position
                               // (default is below beginning)

        <offset> ::= <number>  // offset of starting line or character
        <column> ::= <number>  // starting column number (default 1)
        <length> ::= <number>  // number of characters

    
    clearmarks  [<which> [<scope>]]
    ----------

      Clears marks in text window(s), where

        <which> ::=  -2 |  // all marks in window
                     -1 |  // first mark
                      0 |  // current mark
                      1 |  // all but the last mark

        <scope>  ::=  0 |  // current window
                      1 |  // all windows
                      2 |  // other windows
        
      When no options are specified the -modifier command option is
      interpreted as follows:

        if      shift then <scope> = other windows
        else if mod1  then <scope> = current window
        else               <scope> = all windows

        if cntl then <option> = current mark
        else         <option> = all marks


    displayhighlights <highlights> <show_first>
    -----------------

      Displays the given <highlights> in the text window.  The
      <highlights> describe the strings to be highlighted by position
      and may specify the highlight colors and messages as well.

        <highlights> ::= <option> ... ["<global_message>"]\n 
                         <highlight>\n...

        <option> ::= 
           -color <global_color> |  // sets the default color name
           -append               |  // add to current underlines

        <global_message> ::= <string>  // default message for highlights

        <highlight> ::= ["<message>"] {%<char_highlight> |
                                       [#]<line_highlight> |
                                       <name_highlight> }

        <line_highlight> ::=
          <line_no>:<column>.<length>[,<color>][-<message>]

        <char_highlight> ::= 
          <char_offset>.<length>[,<color>][-<message>]

        <name_highlight> ::=
          <key>[,<color>][-<message>]

        Note: In the above <*_highlight> constructs, only the <message>
              may contain spaces. A <global_message> may also contain
              spaces.

        <line_no> ::= <number>     // a line number - 1 based
        <column>  ::= <number>     // a column number - 1 based
        <char_offset> ::= <number> // a character number - 0 based

        <key> ::= <name>        // a name which somehow identifies text,
                                // (tool dependent? <tbd>)

        <message> ::= <string>  // a message associated with the highlight
                                // (e.g. a compilation error message)
                                // (default is the <global_message>, if any)

        <color> ::= <name>      // highlight color, if omitted, use
                                // <global_color> (if any), otherwise
                                // use the default highlight color

        \n ::= {a newline character}


    displayunderlines <underlines_spec> <show_first>
    -----------------

      Displays the given underlines (with associated messages) in the
      text window.  The <underlines_spec> describes the strings to be
      underlined by position and may specify the highlight colors and
      message as well.

        <underlines_spec> ::= 
          <path>       |    // the name of a file containing <underlines>
          <underlines>      // the actual underlines specification

        <underlines>  ::= line [<tool_kind>] [<option> ...]\n
                          <global_message>\n
                          <line_underline>\n...

                      ::= char [<tool_kind>] [<option> ...]\n
                          <global_message>\n
                          <char_underline>\n...

                      ::= name [<tool_kind>] [<option> ...]\n
                          <global_message>\n
                          <name_underline>\n...

        <tool_kind> ::= <name>  // the kind of tool owning the 
                                // underlines (e.g. grep)

        <global_message> ::= <string> // default message for underlines

        <option> ::= 
             -color <global_color> |  // sets the default color name
             -append               |  // add to current underlines
             -delete_file             // delete the file (if any) after use

        <global_color> ::= <color>    // default color name

        <line_underline> ::= 
          <line_no>:<column>.<length>[,<color>][-<message>]

        <char_underline> ::= 
          <char_offset>.<length>[,<color>][-<message>]

        <name_underline> ::= 
          <key>[,<color>][-<message>]

        Note: In the above <*_underline> constructs, only the <message>
              may contain spaces. A <global_message may also contain
              spaces.

        <line_no> ::= <number>     // a line number - 1 based
        <column>  ::= <number>     // a column number - 1 based
        <char_offset> ::= <number> // character number - 0 based

        <key> ::= <name>        // a name which somehow identifies text,
                                // (tool dependent? <tbd>)

        <message> ::= <string>  // a message associated with the underline
                                // (e.g. a compilation error message)
                                // (default is the <global_message>, if any)

        <color> ::= <name>      // highlight color, if omitted, use
                                // <global_color> (if any), otherwise
                                // use the default highlight color

        \n ::= {a newline character}


    gotomark [<which> [<scope>]]
    --------

      Set the cursor at a mark in the text window(s), where:

        <which> ::=   0 |  // last mark
                      1 |  // first mark
                     -1 |  // prior mark
                     -2    // next mark

        <scope> ::=   0 |  // current window
                      1 |  // all windows (default)
                      2    // other windows

      When no options are specified the -modifier command option is
      and interpreted as follows:

        if      shift then <scope> = current window 
        else if mod1  then <scope> = other windows 
        else               <scope> = all windows

        if cntl then <which> = last mark
        else         <which> = prior mark


    highlight  [<search_option> ...] <string>
    ---------

      Search the window for occurrences of <string> and highlight
      them. (See text window Search bar Highlight All.)


    highlightother  [<search_option> ...] <window> <string>
    --------------

      Search the specified <window> for occurrences of <string> and
      highlight them in that window.

    
    highlightselected  [<search_option> ...]
    -----------------

      Searches the text window for occurrences of the selected text
      and highlights them. (See Edit:Highlight command.)


    indent  [<amount>]
    ------

      Indents the selected text by the specified <amount>. The default
      amount is 4.


    lowercase
    ---------

      Changes all letters in the selected text to uppercase. If
      nothing is selected the operation applies to the token at the
      cursor.


    nextsection [ada | page]
    -----------

      Searches for the next "section" in the text window beginning at
      the current cursor position.  If "ada" is specified, the pattern
      "-----" (5 hyphens) is a section mark.  If "page" is specified,
      a form-feed is added to the pattern.  If no pattern is specified
      in this way, "/////" (5 slashes) is used as the section mark.


    previoussection [ada | page]
    ---------------

      Like nextsection above, except that the search direction is
      reversed.

    
    release 
    -------
    
      Saves the text window contents in the associated file, releases
      the edit lock and makes the text window read-only.


    revertChanges [<arg>]
    -------------
    
      Reverts the text in the window from the associated file.  Does not
      revert if an argument is specified. ?


    saveChanges [ -save | -cancel ]
    -----------

      Invokes the confirmation callback used for the "save changes" dialog.

        -save    // save the text
        -cancel  // do nothing

      The -save option indicates that the text is to be saved, if
      omitted, the text is not saved.


    seteditable <editable>
    -----------

      Changes the editable state of the text window where

      <editable> ::= <boolean> // true to make window editable, 
                               // false to make window read-only


    setmark [<index>]
    -------

      Set a mark at the current cursor position or at <index> if
      specified. (Does not appear to working for emacs.)


    unindent  [<amount>]
    --------

      Unindents the selected text by the specified <amount>. The
      default amount is 4.


    uppercase
    ---------

      Changes all letters in the selected text to uppercase.  If
      nothing is selected the operation applies to the token at the
      cursor.


  o ...<tbd: other editors>


window_query [<editor> <window>] <operation> [<arg> ...]
------------

  Retrieves information related to a window managed by a specified
  editor.  If the <editor> and <window> arguments are omitted, they
  must be specified using the -editor and -key options instead.

  The <operation>s supported depend on the editor.

  Command options used: -editor, -key, -max_wait, -machine.


  o dialog editor window_query operations:
  ----------------------------

    All dialog queries may have the option -silent immediately after
    the <operation>. This options suppresses the error message
    normally emitted when the dialog window to be queried does not
    exist.


    call [<arg> ...]
    ----

      Executes the dlisp call command

        <call[,<arg>,...]>

      in the context of the dialog identified by <window> .


    dialog_type
    -----------

      Returns the name of the dialog type of <window> (usually the
      simple filename of the .dlg file with the suffix removed).


    function <name>
    --------

      Displays the filename and line number for the %prog or %function 
      called <name> belonging to the dialog in <window>.


    functions
    ---------

      Lists the name and the filename and line number of each %prog
      of %function defined by the dialog in <window>.


    title
    -----

      Returns the title of the dialog identified by <window>.


    valw <widget>
    ----

      Retrieves the value of <widget> in dialog <window> where

        <widget> ::= {widget name in the form of a X-resource}
    

    widgets [hex]
    -------

      Displays an indented listing of the widgets comprising the
      dialog in <window>.  For echo widget, the name, type, and
      label (if any) are displayed.  If the "hex" option is
      specified, the widget pointer values are included.


  o ...<tbd: other editors>


  o directory editor window_query operations:
  -------------------------------

    context
    -------

      Returns the pathname of the directory displayed.


    object_locations <path>
    ----------------

      Returns the line number of the item (if any) in the directory
      window identified by <window> that has the pathname <path>.  The
      null string is returned if there is no such item.


    title
    -----

      Returns the title of the directory or summary window identified
      by <window>.


    ...<tbd>


Subcommand Syntax Summary
-------------------------

The following is an alphabetic list of all documented subcommands with
syntactic descriptions:

beep
close <window> ...
close_all
create_log <log>
create_summary [<option> ...] <path> 
dialog <name> [<dlg_option> ...] [<arg> ...]
dialog_run_last
dialog_run_specific <window>
elements <path> ...
execute [<exec_option> ...] {<program> [<arg> ...] | <command> ...}
get_value <property>
getenv [<env_option> ...] <variable>
help [ -info ] -dialog <name> ... | Version | <topic> ...
iconify <window> ...
iconify_all
lower <window> ...
lower_all
message [<arg> ...]

perform [<option> ...] <operation> [<context>] [<modifiers>] [<op_args>]

  general:
    new_menu_item <window_kinds> <menu_item_kind> <menu_path> <widget> \
                  [<label> [<mnemonic>]]
    send  <server> <operation> [<arg> ...]

  dialog editor:
    add_dialog_path <path> ...
    call <function> [<arg> ...]
    cause_reload [all | <dialog> ...]
    clear_cache
    clear_types
    clear_widget_tree [all | <dialog> ...]
    help_check <dialog>
    load <file> ...
    parse <file> ...
    remove_type <dialog>
    reset <path> ...
    set_dialog_path <path> ...
    set_x_selection <arg> ...
    visit_project <project> ... 

  dialog_window editor:
    create [<dialog_option> ...] <window_kind> <dialog_type> [<arg> ...]
    show [<dialog_option> ...] <window_kind> <dialog_type> [<arg> ...]

  directory editor:
    format <format_name>
    refreshformats
    runProgram  <arg> ...
    shell [-machine <machine>] [-title <string>] [-context <path>] \
          [-unmanaged] <xterm_options> ...
    showdifference [<file1> [<file2>]]
    showdifferences [<file1> [<file2>]]
    windows <mask> | [<option> ...] [<display_option> ...]

  text editor:
    finishDialog <alias> <op> <file> <offset> <scope> <context> <mask>

  output editor:
    closeterminal  <window>
    raiseterminal  <window>

    new_menu_item <window_kinds> <menu_item_kind> <menu_path> <widget> \
                  [<label> [<mnemonic>]]
    send  <server> <operation> [<arg> ...]

query <operation> [<arg> ...]

  general:
    action <action_designator>
    actions
    context
    function <name>
    functions

  directory editor:
    last_created

  dialog editor:
    last_created

  output editor:
    lastoutputwindow

  windows editor:
    all_windows

raise <window> ...
raise_all
reread_bindings <object_editor>
reread_rules
restore_session [-replace | -iconify] [<session_name> [<editor>]]
run [<exec_option> ...] {<program> [<arg> ...] | <command> ...} (see execute)
save <window> ...
save_session [-visible] [<session_name> [<editor>]]
script_break <editor> <script_breakpoint>
script_run [<s_option> ...] [<editor> [<s_option> ...] [<script>]] [<arg> ...]
script_trace <editor> <script_trace_option>
server_state <operation> [<arg> ...] | [<server> ...]
setenv <variable> <value>
show_licenses
show_state <editor> <show_command> [<arg> ...]
show_state <editor> <registered_object>
shutdown [<server_or_editor>]
shutdown_all
start [<option> ...] <server_or_editor> [<arg> ...]
start_on [<option> ...] <machine> <server_or_editor> [<arg> ...]
trace <editor> <trace_option> | <editor> low_level | <server>
trace_all <editor> | <server>
trace_break {<editor> | <server>} <trace_breakpoint>
trace_off <editor> | <editor> low_level | <server>
trace_show {<editor> | <server>} <trace_show_option>
trace_verbose <editor> | <server>
unregister [<server_or_editor>]
visit <arg> ...
window_exists [<editor> <window>]
window_image [<editor> <window>]

window_perform [<editor> <window>] <operation> [<arg> ...]

  general:
    activate
    applyitems [<location> [<alternative>]]
    close
    display  <option> ... <alias_key>
    display_item  <item> [<mode>]
    drop
    getholdset  <location>
    holdline [<options>] <text>
    holdtext [[<options>] <text>]
    iconify
    makecurrent
    raise
    saveifneeded
    saveto <file>
    setbusy  [<busy>]
    setbusycount <value>
    setcontext <path>
    setfocus
    settitle <title>
    setshorttitle <title>

  dialog editor:
    apply [<execution_option> ...] (see ok)
    call <name> [<arg> ...] (see runprogram)
    cancel
    help
    make_busy
    ok [<execution_option> ...]
    reset
    run_program <name> [<arg> ...]
    setw <widget> <value>
    unbusy

  directory editor:
    apply_test_format <format>
    gotomark [<which> [<scope>]]

  text editor:

    capitalize
    changeall [<search_option> ...] <target> <replacement>
    changeallselected [<search_option> ...] <replacement>
    changeselected <replacement>
    changetext <target> <replacement>
    clearmarks  [<option> [<scope>]]
    displayhighlights <highlights> <show_first>
    displayunderlines <underlines_spec> <show_first>
    highlight  [<search_option> ...] <string>
    highlightother  [<search_option> ...] <window> <string>
    highlightselected  [<search_option> ...]
    indent  [<amount>]
    lowercase
    nextsection [ada | page]
    previoussection [ada | page]
    release
    revertChanges [<arg>]
    saveChanges [ -save | -cancel ]
    seteditable <editable>
    setmark [<index>]
    unindent  [<amount>]
    uppercase

window_query [<editor> <window>] <operation> [<arg> ...]

  dialog editor:
    call [<arg> ...]
    dialog_type
    function <name>
    functions
    title
    valw <widget>
    widgets [hex]

  directory editor:
    context
    object_locations <path>
    title