*** empty log message ***
[emacs.git] / etc / emacstool.1
blob22eb311789ad7fe634ec58d27f415ec7395e3889
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 
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.
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.
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
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, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
141 Permission is granted to make and distribute verbatim copies of this
142 document provided the copyright notice and this permission notice are
143 preserved on all copies.
145 Permission is granted to copy and distribute modified versions of
146 this document under the conditions for verbatim copying, provided that
147 the entire resulting derived work is distributed under the terms of
148 a permission notice identical to this one.
150 Permission is granted to copy and distribute translations of this
151 document into another language, under the above conditions for
152 modified versions, except that this permission notice may be stated
153 in a translation approved by the Free Software Foundation.
155 .\" arch-tag: a1f44815-5163-4026-89c1-4404e4b81d37