1 5/12/80 - Site instructions for installing Emacs at your site.
2 10.0 Release.
3
4 ** This document is not intended for use with the help command. **
5 ** It is intended for perusal by print, dprint, or an editor. **
6
7
8 ^L
9 ______________________________________________________________________
10
11
12 Multics Emacs is a state-of-the-art text processing and editing system.
13 A new version is being distributed as part of Release 10.0, as an unbundled
14 offering. It offers facilities comparable to stand-alone word-processing
15 systems, combined with the power of the entire Multics environment.
16
17 Multics Emacs is a very large and complex subsystem which requires
18 special actions and customizations to be effected by site personnel:
19 this document specifies these actions.
20
21 Multics Emacs is basically a "real-time video editor." This means that
22 as opposed to interacting with a user on a line-by-line basis, modifying text
23 in response to "command lines", and printing text on demand, a selected
24 portion of the text being edited is continuously displayed upon a screen.
25 The terminal identifies a given location in the text via its cursor.
26 By typing selected characters, the text at the cursor is modified, deleted,
27 moved, etc., and the image of the text on the screen is dynamically updated
28 to reflect these changes as they are made. New text is entered simply
29 by typing it. There is no need for a "print" request; text is always visible.
30 There is no need for a "substitute" request; once undesired text is deleted,
31 new text is simply entered.
32
33 Responding to characters typed at a keyboard in a real-time video
34 environment requires careful screen maintenance in response to each character
35 typed _^Ha_^Hs _^Hi_^Ht _^Hi_^Hs _^Ht_^Hy_^Hp_^He_^Hd: to simply print a character upon the screen
36 as it is typed requires intelligent screen maintenance. It is impermissible
37 to allow the terminal or the front-end processor to echo characters. Thus,
38 Multics Emacs must respond to _^He_^Hv_^He_^Hr_^Hy character as it is typed.
39 The ability to respond to every single character as it is typed is a new one
40 for Multics; until now, there was no need for it. This feature is provided
41 by _^Hb_^Hr_^He_^Ha_^Hk_^Ha_^Hl_^Hl _^Hm_^Ho_^Hd_^He, a feature of the Multics Communications
42 System MCS.
43
44 Although every effort has been made to streamline the per-character
45 loop of Emacs and Multics, including extensive modification to the
46 mainframe and communications processor software, response to every
47 character "in real time" is innately much more expensive in CPU and paging
48 than response to "whole lines". Implementors of real-time video editors
49 on many systems have all found that these editors are much more expensive
50 than non-video editors because of this. Yet, various scenarios of
51 mainframe time availability, video terminal availability, working hours,
52 and system resource pricing have made the technology of real-time editing
53 extremely popular in spite of the innate expense.
54
55 It is the responsibility of the site personnel to make the
56 commitment to allow this software to be used at all at his or her site,
57 and if that commitment is made, to ascertain at precisely what point, at
58 what times of day, and on what configurations does, if at all, Emacs usage
59 become problematic. In two and a half years of experience at the Honeywell
60 exposure sites, UNRESTRICTED Emacs usage has not ONCE created
61 a performance problem; nevertheless, a very large number of Emacs
62 users may have a deleterious effect on system performnace.
63
64 **************************************************
65
66 Multics Emacs is a developing, experimental offering. It is still
67 undergoing development. There are known bugs and deficiencies. All known
68 problems and deficiencies are listed in the file emacs.status.info in the
69 documentation directory >doc>ss>emacs. In spite of these bugs and problems,
70 Multics Emacs is eminently usable, quite robust. Multics Emacs has been in
71 heavy use at the two Multics development sites for three years, and has
72 acquired a user community of hundreds.
73
74
75 Emacs' trouble-reporting mechanism is the same as for all other Multics
76 Software; the TR system should be used. Please check the known bug list
77 before generating a trouble report. We intend to maintain reasonable
78 compatibility in user interface in future releases; the internal interfaces
79 available to the extension writer, however, are more subject to change.
80 However, the intent is to fully document all changes.
81
82
83 **************************************************
84
85
86 The use of Multics Emacs, and its entire repertoire of command and
87 function, for the installed version, is documented in Honeywell Manual
88 CH27, "Emacs Text Editor User's Guide". The writing of user extensions
89 and terminal support modules not of interest to anyone except very
90 advanced users and site maintenance personnel is documented in Honeywell
91 Manual CJ52, "Emacs Editor Extension Writer's Guide".
92
93 The unofficial documentation which was the only documentation before
94 the release of the above-mentioned manuals is distributed in
95 >doc>ss>emacs, where this info segment lives. Starting there, the segment
96 emacs.gi.info contains all other online documentation pointers. This
97 documentation is inteded to be dprinted, and is not suitable for perusal
98 with the "help" command. This documentation, however, is completely
99 up to date, and often contains information in more detail, and
100 differently organized than the published manuals.
101
102 ******************************
103
104 Multics Emacs was modelled after the EMACS editor at the MIT Artificial
105 Intelligence Lab. EMACS on the AI Lab PDP-10's was written, in TECO, by
106 staff members of the MIT AI Lab and the MIT Laboratory for Computer Science
107 LCS, without whose encouragement and support this project would not have
108 been possible.
109
110 Multics Emacs makes no claims to current or future compatibility with
111 other implementations of EMACS or any other editor. Although largely
112 compatible in general philosophy and repertoire with the AI Lab editor, there
113 are significant differences, both in some specific commands with which we
114 chose to differ, facilities implemented in one and not the other, and things
115 that are of necessity different due to the difference in operating systems.
116 Nevertheless, users familiar with any video editor generally find no problem
117 whatsoever adapting to another.
118
119 Compatibility with AI Lab EMACS is not a large consideration for the
120 future.
121
122 Multics Emacs was implemented from scratch at Honeywell with
123 contributions from some programmers at the MIT Information Processing Center.
124 No part of any other program on any other system was used, studied, copied,
125 translated, or otherwise incorporated during the development of Multics Emacs.
126
127 **************************************************
128
129 Emacs resides in the unbundled library, >system_library_unbundled.
130 There are four object segments there:
131
132 o bound_multics_emacs_. The basic editor, online
133 documentation system, command dispatcher, and display
134 manager.
135
136 o bound_emacs_packages_. Various optional features, including
137 the modes for editing PL/I and Lisp programs, the directory
138 and buffer editors, and so on.
139
140 o bound_emacs_rmail_. The Emacs mail system.
141
142 o bound_emacs_preinit_. Code needed at the time Emacs modules
143 or extensions are compiled or loaded, including the
144 command definition facility and the default binding tables.
145
146 The source for these segments is kept in the conventionally-named
147 source archives in the unbundled source library.
148
149 *****IMPORTANT*****
150
151 The terminal-specific knowledge of Emacs is embedded in small Lisp
152 programs known as "ctls", whose exectuable objects reside in
153 >unbundled>emacs_ctls. The site is expected to add terminal control
154 modules to this directory as needed at each site. The names on the
155 "ctl"s, as well as the names on links in the ctl directory, must reflect
156 the names in the TTF for terminals used at your site. Any terminal
157 type to be supported by Emacs at your site must have the name
158 <type>ctl on the appropriate ctl in the ctl directory: As shipped from
159 Phoenix, the ctl directory and TTF are consistent; you must adjust
160 the ctl names for local terminal names in use at your site, as well
161 as supply new ctls for terminals not supportedd in the distributed release.
162 The primary names of the segments and links will be the only names
163 reported stripped of the "ctl" suffix in response to user query
164 about what types of terminals are supported at your site.
165 Instructions on these matters, as well as writing new ctls,
166 are given in CJ52, as well as online in ctl-writing.info. Source for
167 the ctls is in emacs_ctls.s.archive in the unbundled source library.
168 There is a link in >unb>emacs_ctls to >unb>e_pl1_.
169
170 People writing emacs "extensions" see below are encouraged to use
171 the source of Emacs as a model; thus, it ought be retained on line, but
172 need not be. This is even more true for the terminal control modules.
173
174
175 Also in the unbundled directory is:
176
177 o emacs.sv.lisp, the "Saved Lisp Environment" from which Emacs
178 initializes its Lisp Environment each it is invoked. This
179 environment is produced by executing the exec_com
180 make_emacs.ec, which is supplied in
181 bound_multics_emacs_.s.archive. This exec_com _^Hm_^Hu_^Hs_^Ht be
182 executed every time the creates and installs
183 a new version of bound_multics_emacs_ this is NOT needed
184 for the released version. The resulting object,
185 emacs.sv.lisp must then be installed in >unbundled.
186 The old saved enviroment need not
187 be renamed, as Emacs only reads it once at startup time,
188 and does not retain pointers to it.
189
190 The environment must also be "resaved" i.e. make_emacs.ec
191 executed if a new version of the program e_binding_table_ is
192 installed in >unbundled other than the released.
193 This program defines the default key bindings.
194 It is in bound_emacs_preinit_.
195
196 Failure to re-save the environment when either bound_multics_emacs_
197 or e_binding_table_ is changed will result in users getting
198 the message "Error lisp_linkage_error by .... The version of
199 <programname> is not the same one as was loaded into this
200 environment." Users will receive this error whenever Emacs
201 is re-invoked in a process after a new version has been installed.
202 Users should be advised to new_proc if they receive this message
203 if dynamic installation of Emacs at your site is a possibility.
204 The environment _^Hm_^Hu_^Hs_^Ht be resaved if any of these programs are
205 changed; new_proc will not alleviate the problem. A copy of
206 the exec_com also exists in bound_multics_emacs_.s.archive.
207
208 o e-macros.incl, an object program. This program is the
209 compiled version of the include file, e-macros.incl.lisp.
210 Having this object program, which can be generated by
211 directly compiling the include file, makes use of the
212 include file which uses this compiled version if
213 locatable much more efficient.
214
215 *****************************
216 **********IMPORTANT**********
217 *****************************
218
219 There are several site-specific objects that Emacs expects to find.
220 These segments used to reside in a directory >sc1>emacs_dir; this
221 is no longer necessary. The following are the segments.
222
223 o emacs_info_vfile_, an indexed sequential vfile used by the online
224 documentation system to store command descriptions in encoded form.
225 This MSF vfile resides in >unbundled. Make sure that
226 users have s on the MSF dir and r on the components. Experts
227 familiar with the online documentation system can change
228 or augment online command documentation without installations
229 if they have rw to this MSF, thus, it is site modifiable.
230
231 o A segment, metering.acs, access to which controls logging of
232 Emacs usage see the section below. Site optional.
233
234
235 There should exist a link in >unb>include, or wherever your site chooses to
236 put the include file e-define-command.lisp, to e_define_command_ in the
237 executable directory. This is needed in order for the two include files,
238 e-macros.incl.lisp and e-define-command.incl.lisp, to find the program
239 e_define_command_ at the time these include files are used at extension
240 compile time. There must also be a link from wherever the include file
241 e-macros.incl.lisp is kept to the segment e-macros.incl in the executable
242 directory.
243
244 **************************************************
245
246 The table rmail-full-name-table, which used to reside in >sc1>emacs_dir,
247 is no longer necessary, as its functionallity has been subsumed by the
248 my-personal-name Emacs variable.
249
250 **************************************************
251
252 A well-debugged version of the Multics MacLisp subsystem is being
253 shipped in >unbundled in Release 10.0, specifically for the support of
254 Multics Emacs. Honeywell is neither supporting nor documenting Multics
255 MacLisp in Release 10.0 as other than part of the support of Multics Emacs.
256
257
258 Multics MacLisp was developed at the Massachusetts Institute of
259 Technology, under government funding. Documentation is available from
260 the MIT Information Processing Center. Honeywell currently supports Multics
261 MacLisp only to the degree required to keep Honeywell-supplied subsystems
262 implemented in it operative.
263
264 There is an introduction to the language Lisp, in which Multics Emacs
265 is coded and "extended" in the file "extensions.info" in the Emacs
266 documentation directory, as well as in CJ52. This introduction is felt to
267 be adequate for those wishing to write their own Emacs "extensions" see
268 below, and was written with that in mind. It is not, however, a general
269 introduction to the subject, or adequate to fully understand the source
270 code of the deep levels of the Emacs editor.
271
272 The Multics MacLisp subsystem in the unbundled library is complete and
273 fully operative. It is the most advanced version of Multics MacLisp. The
274 principal user interfaces are:
275
276 o lisp, the interpreter
277
278 o lcp, lisp_compiler, which can compile source segments named
279 <name>.lisp into object segments loadable by the interpreter
280
281 o lap, the Lisp-oriented Multics assembler.
282
283 o display_lisp_object_segment, a tool.
284
285 Honeywell will fix bugs in Lisp that affect Emacs, as shipped in Release
286 10.0. We make no statement about any level of future support or documentation,
287 or continued support even at this level of Multics MacLisp.
288
289 **************************************************
290
291 Although Multics Emacs is easily used by personnel with no technical
292 training or programming experience, those with some programming experience
293 can utilize it even more effectively via "extensions". Extensions are
294 fragments of Lisp code, not part of the deep level of the editor, which
295 imbed knowledge of given problem domains, without knowledge of the internal
296 data structure of the editor, or even more to the point, of display management,
297 at all. Examples of supplied extensions are the various language modes
298 and the Emacs mail subsystem.
299
300 Via extension writing, a given shop can create Emacs environments for
301 selected or all users with locally defined functionality, such as document
302 formats, special languages, and other text processing considerations,
303 available on keystrokes to the Emacs user. Similarly, a user who is not
304 completely satisfied with the way some Emacs command behaves is encouraged to
305 look at the source and add his or her own version to his environment.
306
307 It is a major design feature of Multics Emacs that extension, the
308 development of prepared functionality, is performed in a very powerful,
309 concise, and clean language, namely Lisp extended by appropriate "Lisp
310 Macros". This design differs from that of conventional editors, which use the
311 same language that they present as a user interface for writing "macros". By
312 necessity, those languages are always compromised in both directions,
313 conciseness for interactive editing, and the diversity of a programming
314 language for "macro writers". Emacs does not suffer this deficiency.
315
316 CJ52, "Emacs Extension Writer's Guide," includes a complete explanation
317 from the ground up of all knowledge about Lisp necessary to write extensions,
318 including how to debug them interactively within Emacs, and take full
319 advantage of Lisp mode. extensions.info, in >doc>ss>emacs, is much of the
320 same material, but is less complete, less up to date, and less accurate.
321
322 We strongly recommend that some programmer at your site look into
323 these documents, just to see the type of thing that can be done. Tailored
324 Emacs environments provide a way to use all the text processing and display
325 management power of Emacs to best suit your data processing needs. It is
326 our experience that programmers with no background in Lisp at all have
327 been able to write extensions proficiently in one day; even non-technical
328 personnel have successfully written extensions. You will find that
329 writing "Emacs extensions in Lisp" means very little more than saying
330 what you want done in English with a pair of parentheses around each line.
331
332
333 **************************************************
334
335 An audit trail mechanism exists with Emacs to monitor the usage and
336 resources consumed by Emacs users. By default, it is not enabled. To enable
337 it, the site should create the segment >unbundled>metering.acs, zero max
338 length, giving rw access to *.* or all persons/prjects to be audited. The
339 site must then modify the segment emacs_data_.cds, which can be found in
340 bound_multics_emacs_.s.archive, changing the value of "text_data.log_dir" to
341 the pathname of a directory. The site must create this directory, put a
342 terminal quota on it, and give all users or *.* being audited sma to this
343 directory. An IACL of rw *.* should be put on this directory. Watching rate
344 of growth of logs in this directory, and cleaning it out, is the site's
345 responsibility. If not cleaned, record quota overflows will prevent people
346 from using Emacs. This facility is not "secure", and is intended for
347 performance monitoring purposes.
348
349 Users will create log segments automatically in this directory,
350 which can be displayed with the print_log tools. Entries are of the
351 three forms:
352
353 98 1426.0 0 Jones.SYSTEMS.a: Entering emacs on VIP7801 none a.l111
354 101 1427.1 0 Jones.SYSTEMS.a: VIP7801 in 11, r0/r4 echo 0/3, out 927.
355 101 1427.1 0 Jones.SYSTEMS.a: 1.0 min, v/cpu 1/5 mem 67 paging 1029/1218
356
357 The first message, at entry time, gives the user ID, the user's terminal type
358 as specified to MCS, the user's answer-back, and the line over which the user
359 is logged in. The second two messages occur at the time that the user leaves
360 Emacs. The first message gives the user name, the terminal type as finally
361 negotiated with Emacs, the number of input characters, the number of
362 characters echoed by the supervisor via echo negotiation, the number of
363 characters echoed by Emacs that would have been echoed by the supervisor were
364 the system faster than the user's typing, and the number of output characters.
365 The second message gives, in addition to the user ID, the elapsed real time in
366 Emacs, virtual and real CPU consumption, memory units in thousands, and
367 paging device and all page faults.
368
369 END