etc/emacstool.1

   1 .TH EMACSTOOL 1
   2 .SH NAME
   3 .I emacstool
   4 \- run emacs under Sun windows with function-key and mouse support.
   5 .SH SYNOPSIS
   6 .I emacstool
   7 [{window_args} {-rc run_command_path} args ... ]
   8 .SH TYPICAL USAGE
   9 In ~/.suntools or ~/.rootmenu include a line like this:
  10 .br
  11 "Emacstool"     emacstool -WI emacs.icon -f emacstool-init
  12 .SH DESCRIPTION
  13 .B  Emacstool
  14 creates a SunView frame and a tty subwindow within which mouse events
  15 and function keys are translated to ASCII sequences which Emacs can
  16 parse.  The translated input events are sent to the process running in
  17 the tty subwindow, which is typically GNU Emacs.  Emacstool thereby
  18 allows GNU Emacs users to make full use of the mouse and function keys.
  19 GNU Emacs can be loaded with functions to interpret the mouse and
  20 function-key events to make a truly fine screen oriented editor for
  21 the Sun Workstation.
  22 .PP
  23 (Note that GNU Emacs has a special interface to the X window system as
  24 well.  The X window system has many technical advantages, it is an
  25 industry standard, and it is also free software.  The Free Software
  26 Foundation urges you to try X windows, and distributes a free copy of
  27 X on Emacs distribution tapes.)
  28 .PP
  29 Function keys are translated to a sequence of the form
  30 `^X*[a-o][lrt]'.  The last character is `l', `r', or `t' corresponding
  31 to whether the key is among the Left, Right, or Top function keys.
  32 The third character indicates which button of the group
  33 was pressed.  Thus, the function key in the lower right corner will
  34 transmit the sequence `^X*or'.  In addition, the [lrt] is affected by
  35 the Control, Meta, and Shift keys.  Unshifted Control keys will be
  36 non-alphabetic: C-l is [,], C-r is [2], C-t is [4].
  37 .PP
  38 Mouse buttons are encoded as `^X^@([124] x y)\\n'.  ^X^@ is the
  39 standard GNU Emacs mouse event prefix, it is followed by a list
  40 indicating the button pressed and the character row and column of the
  41 point in the window where the mouse cursor is, and followed by a
  42 newline character.  In GNU Emacs, the ^X^@ dispatches to a
  43 mouse event handler which then reads the following list.
  44 .SH OPTIONS
  45 .B Emacstool
  46 supports all the standard window arguments, including font and icon
  47 specifiers.
  48 .PP
  49 By default, Emacstool runs the program
  50 .I emacs
  51 in the created subwindow.
  52 The value of the environment variable
  53 .I EMACSTOOL
  54 can be used to override this if your version of
  55 .B Emacs
  56 is not accessible on your search path by the name
  57 .I Emacs.
  58 In addition, the run command can be set by the
  59 .I pathname
  60 following the last occurrence of the
  61 .I \-rc
  62 flag.
  63 This is convenient for using Emacstool to run on remote machines.
  64 .PP
  65 All other command line arguments not used by the window system are passed
  66 as arguments to the program that runs in the Emacstool window.
  67 .PP
  68 For example:
  69 .PP
  70 local% (emacstool -rc rlogin remote -8 &)&
  71 .PP
  72 will create an Emacstool window logged in to a machine named
  73 .I remote.
  74 If Emacs is run from this window,
  75 Emacstool will encode mouse and function keys, and send them to rlogin.
  76 If Emacs is run from this shell on the remote machine, it will see
  77 the mouse and function keys properly.
  78 However, since the remote host does not have access to the screen,
  79 the cursor cannot be changed, menus will not appear, and the selection
  80 buffer (STUFF) is limited.
  81 .SH Using With GNU Emacs:
  82 The GNU Emacs files
  83 lisp/term/sun.el,
  84 lisp/sun-mouse.el,
  85 lisp/sun-fns.el,
  86 and
  87 src/sunfns.c
  88 provide emacs support for the Emacstool and function keys.
  89 Emacstool will automatically set the TERM environment variable to be "sun"
  90 and unset the environment variable TERMCAP.  That is, these variables will
  91 not be inherited from the shell that starts Emacstool.
  92 Since the terminal type is
  93 .I SUN
  94 (that is, the environment variable TERM is set to
  95 .I SUN),
  96 Emacs will automatically load the file lisp/term/sun.
  97 This, in turn, will ensure that sun-mouse.el is autoloaded when any mouse
  98 events are detected.  It is suggested that
  99 .I sun-mouse
 100 and
 101 .I sun-fns
 102 be loaded in your site-init.el file, so that they will always be loaded
 103 when running on a Sun workstation.
 104 .PP
 105 In addition, Emacstool sets the environment variable IN_EMACSTOOL = "t".
 106 Lisp code in your ~/.emacs can use (getenv "IN_EMACSTOOL")
 107 to determine whether to do Emacstool specific initialization.
 108 Sun.el uses this to automatically call emacstool-init (getenv "IN_EMACSTOOL")
 109 is defined.
 110 .PP
 111 The file src/sunfns.c defines several useful functions for emacs on
 112 the Sun.  Among these are procedures to pop-up SunView
 113 .I menus,
 114 put and get from the SunView
 115 .I STUFF
 116 buffer, and a procedure for changing the cursor
 117 .I icon.
 118 If you want to define or edit cursor icons,
 119 there is a rudimentary mouse driven icon editor in the file
 120 lisp/sun-cursors.el.  Try invoking (sc:edit-cursor)
 121 .SH BUGS
 122 It takes a few milliseconds to create a menu before it pops up.
 123 .SH ENVIRONMENT VARIABLES
 124 EMACSTOOL
 125 IN_EMACSTOOL
 126 TERM
 127 TERMCAP
 128 .SH FILES
 129 .DT
 130 emacs
 131 .SH "SEE ALSO"
 132 emacs(1)
 133  .../etc/SUN-SUPPORT
 134  .../lisp/term/sun.el
 135 .SH COPYING
 136 Copyright
 137 .if t \(co
 138 .if n (c)
 139 2001 Free Software Foundation, Inc.
 140 .PP
 141 Permission is granted to copy, distribute and/or modify this document
 142 under the terms of the GNU Free Documentation License, Version 1.1
 143 or any later version published by the Free Software Foundation;
 144 with no Invariant Sections, with no Front-Cover Texts, and no
 145 Back-Cover Texts.
 146 .PP
 147 This document is part of a collection distributed under the GNU Free
 148 Documentation License.  If you want to distribute this document
 149 separately from the collection, you can do so by adding a copy of the
 150 license to the document, as described in section 6 of the license.
 151 A copy of the license is included in the
 152 .BR gfdl ( 1 )
 153 man page, and in the section entitled "GNU Free Documentation
 154 License" in the Emacs manual.