51dd8c1a23acd2d3ab31ca143a92b8019c49d4b0
[chise/xemacs-chise.git-] / info / internals.info-1
1 This is ../info/internals.info, produced by makeinfo version 4.0 from
2 internals/internals.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Internals: (internals).       XEmacs Internals Manual.
7 END-INFO-DIR-ENTRY
8
9    Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
10 Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
11 Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
12
13    Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
16
17    Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided that the
19 entire resulting derived work is distributed under the terms of a
20 permission notice identical to this one.
21
22    Permission is granted to copy and distribute translations of this
23 manual into another language, under the above conditions for modified
24 versions, except that this permission notice may be stated in a
25 translation approved by the Foundation.
26
27    Permission is granted to copy and distribute modified versions of
28 this manual under the conditions for verbatim copying, provided also
29 that the section entitled "GNU General Public License" is included
30 exactly as in the original, and provided that the entire resulting
31 derived work is distributed under the terms of a permission notice
32 identical to this one.
33
34    Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that the section entitled "GNU General Public License"
37 may be included in a translation approved by the Free Software
38 Foundation instead of in the original English.
39
40 \1f
41 File: internals.info,  Node: Top,  Next: A History of Emacs,  Prev: (dir),  Up: (dir)
42
43    This Info file contains v1.0 of the XEmacs Internals Manual.
44
45 * Menu:
46
47 * A History of Emacs::          Times, dates, important events.
48 * XEmacs From the Outside::     A broad conceptual overview.
49 * The Lisp Language::           An overview.
50 * XEmacs From the Perspective of Building::
51 * XEmacs From the Inside::
52 * The XEmacs Object System (Abstractly Speaking)::
53 * How Lisp Objects Are Represented in C::
54 * Rules When Writing New C Code::
55 * A Summary of the Various XEmacs Modules::
56 * Allocation of Objects in XEmacs Lisp::
57 * Dumping::
58 * Events and the Event Loop::
59 * Evaluation; Stack Frames; Bindings::
60 * Symbols and Variables::
61 * Buffers and Textual Representation::
62 * MULE Character Sets and Encodings::
63 * The Lisp Reader and Compiler::
64 * Lstreams::
65 * Consoles; Devices; Frames; Windows::
66 * The Redisplay Mechanism::
67 * Extents::
68 * Faces::
69 * Glyphs::
70 * Specifiers::
71 * Menus::
72 * Subprocesses::
73 * Interface to X Windows::
74 * Index::
75
76
77 --- The Detailed Node Listing ---
78
79 A History of Emacs
80
81 * Through Version 18::          Unification prevails.
82 * Lucid Emacs::                 One version 19 Emacs.
83 * GNU Emacs 19::                The other version 19 Emacs.
84 * GNU Emacs 20::                The other version 20 Emacs.
85 * XEmacs::                      The continuation of Lucid Emacs.
86
87 Rules When Writing New C Code
88
89 * General Coding Rules::
90 * Writing Lisp Primitives::
91 * Adding Global Lisp Variables::
92 * Coding for Mule::
93 * Techniques for XEmacs Developers::
94
95 Coding for Mule
96
97 * Character-Related Data Types::
98 * Working With Character and Byte Positions::
99 * Conversion to and from External Data::
100 * General Guidelines for Writing Mule-Aware Code::
101 * An Example of Mule-Aware Code::
102
103 A Summary of the Various XEmacs Modules
104
105 * Low-Level Modules::
106 * Basic Lisp Modules::
107 * Modules for Standard Editing Operations::
108 * Editor-Level Control Flow Modules::
109 * Modules for the Basic Displayable Lisp Objects::
110 * Modules for other Display-Related Lisp Objects::
111 * Modules for the Redisplay Mechanism::
112 * Modules for Interfacing with the File System::
113 * Modules for Other Aspects of the Lisp Interpreter and Object System::
114 * Modules for Interfacing with the Operating System::
115 * Modules for Interfacing with X Windows::
116 * Modules for Internationalization::
117
118 Allocation of Objects in XEmacs Lisp
119
120 * Introduction to Allocation::
121 * Garbage Collection::
122 * GCPROing::
123 * Garbage Collection - Step by Step::
124 * Integers and Characters::
125 * Allocation from Frob Blocks::
126 * lrecords::
127 * Low-level allocation::
128 * Cons::
129 * Vector::
130 * Bit Vector::
131 * Symbol::
132 * Marker::
133 * String::
134 * Compiled Function::
135
136 Garbage Collection - Step by Step
137
138 * Invocation::
139 * garbage_collect_1::
140 * mark_object::
141 * gc_sweep::
142 * sweep_lcrecords_1::
143 * compact_string_chars::
144 * sweep_strings::
145 * sweep_bit_vectors_1::
146
147 Dumping
148
149 * Overview::
150 * Data descriptions::
151 * Dumping phase::
152 * Reloading phase::
153
154 Dumping phase
155
156 * Object inventory::
157 * Address allocation::
158 * The header::
159 * Data dumping::
160 * Pointers dumping::
161
162 Events and the Event Loop
163
164 * Introduction to Events::
165 * Main Loop::
166 * Specifics of the Event Gathering Mechanism::
167 * Specifics About the Emacs Event::
168 * The Event Stream Callback Routines::
169 * Other Event Loop Functions::
170 * Converting Events::
171 * Dispatching Events; The Command Builder::
172
173 Evaluation; Stack Frames; Bindings
174
175 * Evaluation::
176 * Dynamic Binding; The specbinding Stack; Unwind-Protects::
177 * Simple Special Forms::
178 * Catch and Throw::
179
180 Symbols and Variables
181
182 * Introduction to Symbols::
183 * Obarrays::
184 * Symbol Values::
185
186 Buffers and Textual Representation
187
188 * Introduction to Buffers::     A buffer holds a block of text such as a file.
189 * The Text in a Buffer::        Representation of the text in a buffer.
190 * Buffer Lists::                Keeping track of all buffers.
191 * Markers and Extents::         Tagging locations within a buffer.
192 * Bufbytes and Emchars::        Representation of individual characters.
193 * The Buffer Object::           The Lisp object corresponding to a buffer.
194
195 MULE Character Sets and Encodings
196
197 * Character Sets::
198 * Encodings::
199 * Internal Mule Encodings::
200 * CCL::
201
202 Encodings
203
204 * Japanese EUC (Extended Unix Code)::
205 * JIS7::
206
207 Internal Mule Encodings
208
209 * Internal String Encoding::
210 * Internal Character Encoding::
211
212 Lstreams
213
214 * Creating an Lstream::         Creating an lstream object.
215 * Lstream Types::               Different sorts of things that are streamed.
216 * Lstream Functions::           Functions for working with lstreams.
217 * Lstream Methods::             Creating new lstream types.
218
219 Consoles; Devices; Frames; Windows
220
221 * Introduction to Consoles; Devices; Frames; Windows::
222 * Point::
223 * Window Hierarchy::
224 * The Window Object::
225
226 The Redisplay Mechanism
227
228 * Critical Redisplay Sections::
229 * Line Start Cache::
230 * Redisplay Piece by Piece::
231
232 Extents
233
234 * Introduction to Extents::     Extents are ranges over text, with properties.
235 * Extent Ordering::             How extents are ordered internally.
236 * Format of the Extent Info::   The extent information in a buffer or string.
237 * Zero-Length Extents::         A weird special case.
238 * Mathematics of Extent Ordering::  A rigorous foundation.
239 * Extent Fragments::            Cached information useful for redisplay.
240
241 \1f
242 File: internals.info,  Node: A History of Emacs,  Next: XEmacs From the Outside,  Prev: Top,  Up: Top
243
244 A History of Emacs
245 ******************
246
247    XEmacs is a powerful, customizable text editor and development
248 environment.  It began as Lucid Emacs, which was in turn derived from
249 GNU Emacs, a program written by Richard Stallman of the Free Software
250 Foundation.  GNU Emacs dates back to the 1970's, and was modelled after
251 a package called "Emacs", written in 1976, that was a set of macros on
252 top of TECO, an old, old text editor written at MIT on the DEC PDP 10
253 under one of the earliest time-sharing operating systems, ITS
254 (Incompatible Timesharing System). (ITS dates back well before Unix.)
255 ITS, TECO, and Emacs were products of a group of people at MIT who
256 called themselves "hackers", who shared an idealistic belief system
257 about the free exchange of information and were fanatical in their
258 devotion to and time spent with computers. (The hacker subculture dates
259 back to the late 1950's at MIT and is described in detail in Steven
260 Levy's book `Hackers'.  This book also includes a lot of information
261 about Stallman himself and the development of Lisp, a programming
262 language developed at MIT that underlies Emacs.)
263
264 * Menu:
265
266 * Through Version 18::          Unification prevails.
267 * Lucid Emacs::                 One version 19 Emacs.
268 * GNU Emacs 19::                The other version 19 Emacs.
269 * GNU Emacs 20::                The other version 20 Emacs.
270 * XEmacs::                      The continuation of Lucid Emacs.
271
272 \1f
273 File: internals.info,  Node: Through Version 18,  Next: Lucid Emacs,  Prev: A History of Emacs,  Up: A History of Emacs
274
275 Through Version 18
276 ==================
277
278    Although the history of the early versions of GNU Emacs is unclear,
279 the history is well-known from the middle of 1985.  A time line is:
280
281    * GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985
282      and shared some code with a version of Emacs written by James
283      Gosling (the same James Gosling who later created the Java
284      language).
285
286    * GNU Emacs version 16 (first released version was 16.56) was
287      released on July 15, 1985.  All Gosling code was removed due to
288      potential copyright problems with the code.
289
290    * version 16.57: released on September 16, 1985.
291
292    * versions 16.58, 16.59: released on September 17, 1985.
293
294    * version 16.60: released on September 19, 1985.  These later
295      version 16's incorporated patches from the net, esp. for getting
296      Emacs to work under System V.
297
298    * version 17.36 (first official v17 release) released on December 20,
299      1985.  Included a TeX-able user manual.  First official unpatched
300      version that worked on vanilla System V machines.
301
302    * version 17.43 (second official v17 release) released on January 25,
303      1986.
304
305    * version 17.45 released on January 30, 1986.
306
307    * version 17.46 released on February 4, 1986.
308
309    * version 17.48 released on February 10, 1986.
310
311    * version 17.49 released on February 12, 1986.
312
313    * version 17.55 released on March 18, 1986.
314
315    * version 17.57 released on March 27, 1986.
316
317    * version 17.58 released on April 4, 1986.
318
319    * version 17.61 released on April 12, 1986.
320
321    * version 17.63 released on May 7, 1986.
322
323    * version 17.64 released on May 12, 1986.
324
325    * version 18.24 (a beta version) released on October 2, 1986.
326
327    * version 18.30 (a beta version) released on November 15, 1986.
328
329    * version 18.31 (a beta version) released on November 23, 1986.
330
331    * version 18.32 (a beta version) released on December 7, 1986.
332
333    * version 18.33 (a beta version) released on December 12, 1986.
334
335    * version 18.35 (a beta version) released on January 5, 1987.
336
337    * version 18.36 (a beta version) released on January 21, 1987.
338
339    * January 27, 1987: The Great Usenet Renaming.  net.emacs is now
340      comp.emacs.
341
342    * version 18.37 (a beta version) released on February 12, 1987.
343
344    * version 18.38 (a beta version) released on March 3, 1987.
345
346    * version 18.39 (a beta version) released on March 14, 1987.
347
348    * version 18.40 (a beta version) released on March 18, 1987.
349
350    * version 18.41 (the first "official" release) released on March 22,
351      1987.
352
353    * version 18.45 released on June 2, 1987.
354
355    * version 18.46 released on June 9, 1987.
356
357    * version 18.47 released on June 18, 1987.
358
359    * version 18.48 released on September 3, 1987.
360
361    * version 18.49 released on September 18, 1987.
362
363    * version 18.50 released on February 13, 1988.
364
365    * version 18.51 released on May 7, 1988.
366
367    * version 18.52 released on September 1, 1988.
368
369    * version 18.53 released on February 24, 1989.
370
371    * version 18.54 released on April 26, 1989.
372
373    * version 18.55 released on August 23, 1989.  This is the earliest
374      version that is still available by FTP.
375
376    * version 18.56 released on January 17, 1991.
377
378    * version 18.57 released late January, 1991.
379
380    * version 18.58 released ?????.
381
382    * version 18.59 released October 31, 1992.
383
384 \1f
385 File: internals.info,  Node: Lucid Emacs,  Next: GNU Emacs 19,  Prev: Through Version 18,  Up: A History of Emacs
386
387 Lucid Emacs
388 ===========
389
390    Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
391 C++ and Lisp development environments.  It began when Lucid decided they
392 wanted to use Emacs as the editor and cornerstone of their C++
393 development environment (called "Energize").  They needed many features
394 that were not available in the existing version of GNU Emacs (version
395 18.5something), in particular good and integrated support for GUI
396 elements such as mouse support, multiple fonts, multiple window-system
397 windows, etc.  A branch of GNU Emacs called Epoch, written at the
398 University of Illinois, existed that supplied many of these features;
399 however, Lucid needed more than what existed in Epoch.  At the time, the
400 Free Software Foundation was working on version 19 of Emacs (this was
401 sometime around 1991), which was planned to have similar features, and
402 so Lucid decided to work with the Free Software Foundation.  Their plan
403 was to add features that they needed, and coordinate with the FSF so
404 that the features would get included back into Emacs version 19.
405
406    Delays in the release of version 19 occurred, however (resulting in
407 it finally being released more than a year after what was initially
408 planned), and Lucid encountered unexpected technical resistance in
409 getting their changes merged back into version 19, so they decided to
410 release their own version of Emacs, which became Lucid Emacs 19.0.
411
412    The initial authors of Lucid Emacs were Matthieu Devin, Harlan
413 Sexton, and Eric Benson, and the work was later taken over by Jamie
414 Zawinski, who became "Mr. Lucid Emacs" for many releases.
415
416    A time line for Lucid Emacs/XEmacs is
417
418    * version 19.0 shipped with Energize 1.0, April 1992.
419
420    * version 19.1 released June 4, 1992.
421
422    * version 19.2 released June 19, 1992.
423
424    * version 19.3 released September 9, 1992.
425
426    * version 19.4 released January 21, 1993.
427
428    * version 19.5 was a repackaging of 19.4 with a few bug fixes and
429      shipped with Energize 2.0.  Never released to the net.
430
431    * version 19.6 released April 9, 1993.
432
433    * version 19.7 was a repackaging of 19.6 with a few bug fixes and
434      shipped with Energize 2.1.  Never released to the net.
435
436    * version 19.8 released September 6, 1993.
437
438    * version 19.9 released January 12, 1994.
439
440    * version 19.10 released May 27, 1994.
441
442    * version 19.11 (first XEmacs) released September 13, 1994.
443
444    * version 19.12 released June 23, 1995.
445
446    * version 19.13 released September 1, 1995.
447
448    * version 19.14 released June 23, 1996.
449
450    * version 20.0 released February 9, 1997.
451
452    * version 19.15 released March 28, 1997.
453
454    * version 20.1 (not released to the net) April 15, 1997.
455
456    * version 20.2 released May 16, 1997.
457
458    * version 19.16 released October 31, 1997.
459
460    * version 20.3 (the first stable version of XEmacs 20.x) released
461      November 30, 1997.  version 20.4 released February 28, 1998.
462
463 \1f
464 File: internals.info,  Node: GNU Emacs 19,  Next: GNU Emacs 20,  Prev: Lucid Emacs,  Up: A History of Emacs
465
466 GNU Emacs 19
467 ============
468
469    About a year after the initial release of Lucid Emacs, the FSF
470 released a beta of their version of Emacs 19 (referred to here as "GNU
471 Emacs").  By this time, the current version of Lucid Emacs was 19.6.
472 (Strangely, the first released beta from the FSF was GNU Emacs 19.7.) A
473 time line for GNU Emacs version 19 is
474
475    * version 19.8 (beta) released May 27, 1993.
476
477    * version 19.9 (beta) released May 27, 1993.
478
479    * version 19.10 (beta) released May 30, 1993.
480
481    * version 19.11 (beta) released June 1, 1993.
482
483    * version 19.12 (beta) released June 2, 1993.
484
485    * version 19.13 (beta) released June 8, 1993.
486
487    * version 19.14 (beta) released June 17, 1993.
488
489    * version 19.15 (beta) released June 19, 1993.
490
491    * version 19.16 (beta) released July 6, 1993.
492
493    * version 19.17 (beta) released late July, 1993.
494
495    * version 19.18 (beta) released August 9, 1993.
496
497    * version 19.19 (beta) released August 15, 1993.
498
499    * version 19.20 (beta) released November 17, 1993.
500
501    * version 19.21 (beta) released November 17, 1993.
502
503    * version 19.22 (beta) released November 28, 1993.
504
505    * version 19.23 (beta) released May 17, 1994.
506
507    * version 19.24 (beta) released May 16, 1994.
508
509    * version 19.25 (beta) released June 3, 1994.
510
511    * version 19.26 (beta) released September 11, 1994.
512
513    * version 19.27 (beta) released September 14, 1994.
514
515    * version 19.28 (first "official" release) released November 1, 1994.
516
517    * version 19.29 released June 21, 1995.
518
519    * version 19.30 released November 24, 1995.
520
521    * version 19.31 released May 25, 1996.
522
523    * version 19.32 released July 31, 1996.
524
525    * version 19.33 released August 11, 1996.
526
527    * version 19.34 released August 21, 1996.
528
529    * version 19.34b released September 6, 1996.
530
531    In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways,
532 worse.  Lucid soon began incorporating features from GNU Emacs 19 into
533 Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been
534 working on and using GNU Emacs for a long time (back as far as version
535 16 or 17).
536
537 \1f
538 File: internals.info,  Node: GNU Emacs 20,  Next: XEmacs,  Prev: GNU Emacs 19,  Up: A History of Emacs
539
540 GNU Emacs 20
541 ============
542
543    On February 2, 1997 work began on GNU Emacs to integrate Mule.  The
544 first release was made in September of that year.
545
546    A timeline for Emacs 20 is
547
548    * version 20.1 released September 17, 1997.
549
550    * version 20.2 released September 20, 1997.
551
552    * version 20.3 released August 19, 1998.
553
554 \1f
555 File: internals.info,  Node: XEmacs,  Prev: GNU Emacs 20,  Up: A History of Emacs
556
557 XEmacs
558 ======
559
560    Around the time that Lucid was developing Energize, Sun Microsystems
561 was developing their own development environment (called "SPARCWorks")
562 and also decided to use Emacs.  They joined forces with the Epoch team
563 at the University of Illinois and later with Lucid.  The maintainer of
564 the last-released version of Epoch was Marc Andreessen, but he dropped
565 out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson
566 away from a system administration job to become the primary Lucid Emacs
567 author for Epoch and Sun.  Chuck's area of specialty became the
568 redisplay engine (he replaced the old Lucid Emacs redisplay engine with
569 a ported version from Epoch and then later rewrote it from scratch).
570 Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs
571 to Microsoft Windows 3.1) in 1993, for what was initially a one-month
572 contract to fix some event problems but later became a many-year
573 involvement, punctuated by a six-month contract with Amdahl Corporation.
574
575    In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name
576 not favorable to either company); the first release called XEmacs was
577 version 19.11.  In June 1994, Lucid folded and Jamie quit to work for
578 the newly formed Mosaic Communications Corp., later Netscape
579 Communications Corp. (co-founded by the same Marc Andreessen, who had
580 quit his Epoch job to work on a graphical browser for the World Wide
581 Web).  Chuck then become the primary maintainer of XEmacs, and put out
582 versions 19.11 through 19.14 in conjunction with Ben.  For 19.12 and
583 19.13, Chuck added the new redisplay and many other display improvements
584 and Ben added MULE support (support for Asian and other languages) and
585 redesigned most of the internal Lisp subsystems to better support the
586 MULE work and the various other features being added to XEmacs.  After
587 19.14 Chuck retired as primary maintainer and Steve Baur stepped in.
588
589    Soon after 19.13 was released, work began in earnest on the MULE
590 internationalization code and the source tree was divided into two
591 development paths.  The MULE version was initially called 19.20, but was
592 soon renamed to 20.0.  In 1996 Martin Buchholz of Sun Microsystems took
593 over the care and feeding of it and worked on it in parallel with the
594 19.14 development that was occurring at the same time.  After much work
595 by Martin, it was decided to release 20.0 ahead of 19.15 in February
596 1997.  The source tree remained divided until 20.2 when the version 19
597 source was finally retired at version 19.16.
598
599    In 1997, Sun finally dropped all pretense of support for XEmacs and
600 Martin Buchholz left the company in November.  Since then, and mostly
601 for the previous year, because Steve Baur was never paid to work on
602 XEmacs, XEmacs has existed solely on the contributions of volunteers
603 from the Free Software Community.  Starting from 1997, Hrvoje Niksic and
604 Kyle Jones have figured prominently in XEmacs development.
605
606    Many attempts have been made to merge XEmacs and GNU Emacs, but they
607 have consistently failed.
608
609    A more detailed history is contained in the XEmacs About page.
610
611 \1f
612 File: internals.info,  Node: XEmacs From the Outside,  Next: The Lisp Language,  Prev: A History of Emacs,  Up: Top
613
614 XEmacs From the Outside
615 ***********************
616
617    XEmacs appears to the outside world as an editor, but it is really a
618 Lisp environment.  At its heart is a Lisp interpreter; it also
619 "happens" to contain many specialized object types (e.g. buffers,
620 windows, frames, events) that are useful for implementing an editor.
621 Some of these objects (in particular windows and frames) have
622 displayable representations, and XEmacs provides a function
623 `redisplay()' that ensures that the display of all such objects matches
624 their internal state.  Most of the time, a standard Lisp environment is
625 in a "read-eval-print" loop--i.e. "read some Lisp code, execute it, and
626 print the results".  XEmacs has a similar loop:
627
628    * read an event
629
630    * dispatch the event (i.e. "do it")
631
632    * redisplay
633
634    Reading an event is done using the Lisp function `next-event', which
635 waits for something to happen (typically, the user presses a key or
636 moves the mouse) and returns an event object describing this.
637 Dispatching an event is done using the Lisp function `dispatch-event',
638 which looks up the event in a keymap object (a particular kind of
639 object that associates an event with a Lisp function) and calls that
640 function.  The function "does" what the user has requested by changing
641 the state of particular frame objects, buffer objects, etc.  Finally,
642 `redisplay()' is called, which updates the display to reflect those
643 changes just made.  Thus is an "editor" born.
644
645    Note that you do not have to use XEmacs as an editor; you could just
646 as well make it do your taxes, compute pi, play bridge, etc.  You'd just
647 have to write functions to do those operations in Lisp.
648
649 \1f
650 File: internals.info,  Node: The Lisp Language,  Next: XEmacs From the Perspective of Building,  Prev: XEmacs From the Outside,  Up: Top
651
652 The Lisp Language
653 *****************
654
655    Lisp is a general-purpose language that is higher-level than C and in
656 many ways more powerful than C.  Powerful dialects of Lisp such as
657 Common Lisp are probably much better languages for writing very large
658 applications than is C. (Unfortunately, for many non-technical reasons
659 C and its successor C++ have become the dominant languages for
660 application development.  These languages are both inadequate for
661 extremely large applications, which is evidenced by the fact that newer,
662 larger programs are becoming ever harder to write and are requiring ever
663 more programmers despite great increases in C development environments;
664 and by the fact that, although hardware speeds and reliability have been
665 growing at an exponential rate, most software is still generally
666 considered to be slow and buggy.)
667
668    The new Java language holds promise as a better general-purpose
669 development language than C.  Java has many features in common with
670 Lisp that are not shared by C (this is not a coincidence, since Java
671 was designed by James Gosling, a former Lisp hacker).  This will be
672 discussed more later.
673
674    For those used to C, here is a summary of the basic differences
675 between C and Lisp:
676
677   1. Lisp has an extremely regular syntax.  Every function, expression,
678      and control statement is written in the form
679
680              (FUNC ARG1 ARG2 ...)
681
682      This is as opposed to C, which writes functions as
683
684              func(ARG1, ARG2, ...)
685
686      but writes expressions involving operators as (e.g.)
687
688              ARG1 + ARG2
689
690      and writes control statements as (e.g.)
691
692              while (EXPR) { STATEMENT1; STATEMENT2; ... }
693
694      Lisp equivalents of the latter two would be
695
696              (+ ARG1 ARG2 ...)
697
698      and
699
700              (while EXPR STATEMENT1 STATEMENT2 ...)
701
702   2. Lisp is a safe language.  Assuming there are no bugs in the Lisp
703      interpreter/compiler, it is impossible to write a program that
704      "core dumps" or otherwise causes the machine to execute an illegal
705      instruction.  This is very different from C, where perhaps the most
706      common outcome of a bug is exactly such a crash.  A corollary of
707      this is that the C operation of casting a pointer is impossible
708      (and unnecessary) in Lisp, and that it is impossible to access
709      memory outside the bounds of an array.
710
711   3. Programs and data are written in the same form.  The
712      parenthesis-enclosing form described above for statements is the
713      same form used for the most common data type in Lisp, the list.
714      Thus, it is possible to represent any Lisp program using Lisp data
715      types, and for one program to construct Lisp statements and then
716      dynamically "evaluate" them, or cause them to execute.
717
718   4. All objects are "dynamically typed".  This means that part of every
719      object is an indication of what type it is.  A Lisp program can
720      manipulate an object without knowing what type it is, and can
721      query an object to determine its type.  This means that,
722      correspondingly, variables and function parameters can hold
723      objects of any type and are not normally declared as being of any
724      particular type.  This is opposed to the "static typing" of C,
725      where variables can hold exactly one type of object and must be
726      declared as such, and objects do not contain an indication of
727      their type because it's implicit in the variables they are stored
728      in.  It is possible in C to have a variable hold different types
729      of objects (e.g. through the use of `void *' pointers or
730      variable-argument functions), but the type information must then be
731      passed explicitly in some other fashion, leading to additional
732      program complexity.
733
734   5. Allocated memory is automatically reclaimed when it is no longer
735      in use.  This operation is called "garbage collection" and
736      involves looking through all variables to see what memory is being
737      pointed to, and reclaiming any memory that is not pointed to and
738      is thus "inaccessible" and out of use.  This is as opposed to C,
739      in which allocated memory must be explicitly reclaimed using
740      `free()'.  If you simply drop all pointers to memory without
741      freeing it, it becomes "leaked" memory that still takes up space.
742      Over a long period of time, this can cause your program to grow
743      and grow until it runs out of memory.
744
745   6. Lisp has built-in facilities for handling errors and exceptions.
746      In C, when an error occurs, usually either the program exits
747      entirely or the routine in which the error occurs returns a value
748      indicating this.  If an error occurs in a deeply-nested routine,
749      then every routine currently called must unwind itself normally
750      and return an error value back up to the next routine.  This means
751      that every routine must explicitly check for an error in all the
752      routines it calls; if it does not do so, unexpected and often
753      random behavior results.  This is an extremely common source of
754      bugs in C programs.  An alternative would be to do a non-local
755      exit using `longjmp()', but that is often very dangerous because
756      the routines that were exited past had no opportunity to clean up
757      after themselves and may leave things in an inconsistent state,
758      causing a crash shortly afterwards.
759
760      Lisp provides mechanisms to make such non-local exits safe.  When
761      an error occurs, a routine simply signals that an error of a
762      particular class has occurred, and a non-local exit takes place.
763      Any routine can trap errors occurring in routines it calls by
764      registering an error handler for some or all classes of errors.
765      (If no handler is registered, a default handler, generally
766      installed by the top-level event loop, is executed; this prints
767      out the error and continues.) Routines can also specify cleanup
768      code (called an "unwind-protect") that will be called when control
769      exits from a block of code, no matter how that exit occurs--i.e.
770      even if a function deeply nested below it causes a non-local exit
771      back to the top level.
772
773      Note that this facility has appeared in some recent vintages of C,
774      in particular Visual C++ and other PC compilers written for the
775      Microsoft Win32 API.
776
777   7. In Emacs Lisp, local variables are "dynamically scoped".  This
778      means that if you declare a local variable in a particular
779      function, and then call another function, that subfunction can
780      "see" the local variable you declared.  This is actually
781      considered a bug in Emacs Lisp and in all other early dialects of
782      Lisp, and was corrected in Common Lisp. (In Common Lisp, you can
783      still declare dynamically scoped variables if you want to--they
784      are sometimes useful--but variables by default are "lexically
785      scoped" as in C.)
786
787    For those familiar with Lisp, Emacs Lisp is modelled after MacLisp,
788 an early dialect of Lisp developed at MIT (no relation to the Macintosh
789 computer).  There is a Common Lisp compatibility package available for
790 Emacs that provides many of the features of Common Lisp.
791
792    The Java language is derived in many ways from C, and shares a
793 similar syntax, but has the following features in common with Lisp (and
794 different from C):
795
796   1. Java is a safe language, like Lisp.
797
798   2. Java provides garbage collection, like Lisp.
799
800   3. Java has built-in facilities for handling errors and exceptions,
801      like Lisp.
802
803   4. Java has a type system that combines the best advantages of both
804      static and dynamic typing.  Objects (except very simple types) are
805      explicitly marked with their type, as in dynamic typing; but there
806      is a hierarchy of types and functions are declared to accept only
807      certain types, thus providing the increased compile-time
808      error-checking of static typing.
809
810    The Java language also has some negative attributes:
811
812   1. Java uses the edit/compile/run model of software development.  This
813      makes it hard to use interactively.  For example, to use Java like
814      `bc' it is necessary to write a special purpose, albeit tiny,
815      application.  In Emacs Lisp, a calculator comes built-in without
816      any effort - one can always just type an expression in the
817      `*scratch*' buffer.
818
819   2. Java tries too hard to enforce, not merely enable, portability,
820      making ordinary access to standard OS facilities painful.  Java
821      has an "agenda".  I think this is why `chdir' is not part of
822      standard Java, which is inexcusable.
823
824    Unfortunately, there is no perfect language.  Static typing allows a
825 compiler to catch programmer errors and produce more efficient code, but
826 makes programming more tedious and less fun.  For the foreseeable
827 future, an Ideal Editing and Programming Environment (and that is what
828 XEmacs aspires to) will be programmable in multiple languages: high
829 level ones like Lisp for user customization and prototyping, and lower
830 level ones for infrastructure and industrial strength applications.  If
831 I had my way, XEmacs would be friendly towards the Python, Scheme, C++,
832 ML, etc... communities.  But there are serious technical difficulties to
833 achieving that goal.
834
835    The word "application" in the previous paragraph was used
836 intentionally.  XEmacs implements an API for programs written in Lisp
837 that makes it a full-fledged application platform, very much like an OS
838 inside the real OS.
839
840 \1f
841 File: internals.info,  Node: XEmacs From the Perspective of Building,  Next: XEmacs From the Inside,  Prev: The Lisp Language,  Up: Top
842
843 XEmacs From the Perspective of Building
844 ***************************************
845
846    The heart of XEmacs is the Lisp environment, which is written in C.
847 This is contained in the `src/' subdirectory.  Underneath `src/' are
848 two subdirectories of header files: `s/' (header files for particular
849 operating systems) and `m/' (header files for particular machine
850 types).  In practice the distinction between the two types of header
851 files is blurred.  These header files define or undefine certain
852 preprocessor constants and macros to indicate particular
853 characteristics of the associated machine or operating system.  As part
854 of the configure process, one `s/' file and one `m/' file is identified
855 for the particular environment in which XEmacs is being built.
856
857    XEmacs also contains a great deal of Lisp code.  This implements the
858 operations that make XEmacs useful as an editor as well as just a Lisp
859 environment, and also contains many add-on packages that allow XEmacs to
860 browse directories, act as a mail and Usenet news reader, compile Lisp
861 code, etc.  There is actually more Lisp code than C code associated with
862 XEmacs, but much of the Lisp code is peripheral to the actual operation
863 of the editor.  The Lisp code all lies in subdirectories underneath the
864 `lisp/' directory.
865
866    The `lwlib/' directory contains C code that implements a generalized
867 interface onto different X widget toolkits and also implements some
868 widgets of its own that behave like Motif widgets but are faster, free,
869 and in some cases more powerful.  The code in this directory compiles
870 into a library and is mostly independent from XEmacs.
871
872    The `etc/' directory contains various data files associated with
873 XEmacs.  Some of them are actually read by XEmacs at startup; others
874 merely contain useful information of various sorts.
875
876    The `lib-src/' directory contains C code for various auxiliary
877 programs that are used in connection with XEmacs.  Some of them are used
878 during the build process; others are used to perform certain functions
879 that cannot conveniently be placed in the XEmacs executable (e.g. the
880 `movemail' program for fetching mail out of `/var/spool/mail', which
881 must be setgid to `mail' on many systems; and the `gnuclient' program,
882 which allows an external script to communicate with a running XEmacs
883 process).
884
885    The `man/' directory contains the sources for the XEmacs
886 documentation.  It is mostly in a form called Texinfo, which can be
887 converted into either a printed document (by passing it through TeX) or
888 into on-line documentation called "info files".
889
890    The `info/' directory contains the results of formatting the XEmacs
891 documentation as "info files", for on-line use.  These files are used
892 when you enter the Info system using `C-h i' or through the Help menu.
893
894    The `dynodump/' directory contains auxiliary code used to build
895 XEmacs on Solaris platforms.
896
897    The other directories contain various miscellaneous code and
898 information that is not normally used or needed.
899
900    The first step of building involves running the `configure' program
901 and passing it various parameters to specify any optional features you
902 want and compiler arguments and such, as described in the `INSTALL'
903 file.  This determines what the build environment is, chooses the
904 appropriate `s/' and `m/' file, and runs a series of tests to determine
905 many details about your environment, such as which library functions
906 are available and exactly how they work.  The reason for running these
907 tests is that it allows XEmacs to be compiled on a much wider variety
908 of platforms than those that the XEmacs developers happen to be
909 familiar with, including various sorts of hybrid platforms.  This is
910 especially important now that many operating systems give you a great
911 deal of control over exactly what features you want installed, and allow
912 for easy upgrading of parts of a system without upgrading the rest.  It
913 would be impossible to pre-determine and pre-specify the information for
914 all possible configurations.
915
916    In fact, the `s/' and `m/' files are basically _evil_, since they
917 contain unmaintainable platform-specific hard-coded information.
918 XEmacs has been moving in the direction of having all system-specific
919 information be determined dynamically by `configure'.  Perhaps someday
920 we can `rm -rf src/s src/m'.
921
922    When configure is done running, it generates `Makefile's and
923 `GNUmakefile's and the file `src/config.h' (which describes the
924 features of your system) from template files.  You then run `make',
925 which compiles the auxiliary code and programs in `lib-src/' and
926 `lwlib/' and the main XEmacs executable in `src/'.  The result of
927 compiling and linking is an executable called `temacs', which is _not_
928 the final XEmacs executable.  `temacs' by itself is not intended to
929 function as an editor or even display any windows on the screen, and if
930 you simply run it, it will exit immediately.  The `Makefile' runs
931 `temacs' with certain options that cause it to initialize itself, read
932 in a number of basic Lisp files, and then dump itself out into a new
933 executable called `xemacs'.  This new executable has been
934 pre-initialized and contains pre-digested Lisp code that is necessary
935 for the editor to function (this includes most basic editing functions,
936 e.g. `kill-line', that can be defined in terms of other Lisp
937 primitives; some initialization code that is called when certain
938 objects, such as frames, are created; and all of the standard
939 keybindings and code for the actions they result in).  This executable,
940 `xemacs', is the executable that you run to use the XEmacs editor.
941
942    Although `temacs' is not intended to be run as an editor, it can, by
943 using the incantation `temacs -batch -l loadup.el run-temacs'.  This is
944 useful when the dumping procedure described above is broken, or when
945 using certain program debugging tools such as Purify.  These tools get
946 mighty confused by the tricks played by the XEmacs build process, such
947 as allocation memory in one process, and freeing it in the next.
948
949 \1f
950 File: internals.info,  Node: XEmacs From the Inside,  Next: The XEmacs Object System (Abstractly Speaking),  Prev: XEmacs From the Perspective of Building,  Up: Top
951
952 XEmacs From the Inside
953 **********************
954
955    Internally, XEmacs is quite complex, and can be very confusing.  To
956 simplify things, it can be useful to think of XEmacs as containing an
957 event loop that "drives" everything, and a number of other subsystems,
958 such as a Lisp engine and a redisplay mechanism.  Each of these other
959 subsystems exists simultaneously in XEmacs, and each has a certain
960 state.  The flow of control continually passes in and out of these
961 different subsystems in the course of normal operation of the editor.
962
963    It is important to keep in mind that, most of the time, the editor is
964 "driven" by the event loop.  Except during initialization and batch
965 mode, all subsystems are entered directly or indirectly through the
966 event loop, and ultimately, control exits out of all subsystems back up
967 to the event loop.  This cycle of entering a subsystem, exiting back out
968 to the event loop, and starting another iteration of the event loop
969 occurs once each keystroke, mouse motion, etc.
970
971    If you're trying to understand a particular subsystem (other than the
972 event loop), think of it as a "daemon" process or "servant" that is
973 responsible for one particular aspect of a larger system, and
974 periodically receives commands or environment changes that cause it to
975 do something.  Ultimately, these commands and environment changes are
976 always triggered by the event loop.  For example:
977
978    * The window and frame mechanism is responsible for keeping track of
979      what windows and frames exist, what buffers are in them, etc.  It
980      is periodically given commands (usually from the user) to make a
981      change to the current window/frame state: i.e. create a new frame,
982      delete a window, etc.
983
984    * The buffer mechanism is responsible for keeping track of what
985      buffers exist and what text is in them.  It is periodically given
986      commands (usually from the user) to insert or delete text, create
987      a buffer, etc.  When it receives a text-change command, it
988      notifies the redisplay mechanism.
989
990    * The redisplay mechanism is responsible for making sure that
991      windows and frames are displayed correctly.  It is periodically
992      told (by the event loop) to actually "do its job", i.e. snoop
993      around and see what the current state of the environment (mostly
994      of the currently-existing windows, frames, and buffers) is, and
995      make sure that that state matches what's actually displayed.  It
996      keeps lots and lots of information around (such as what is
997      actually being displayed currently, and what the environment was
998      last time it checked) so that it can minimize the work it has to
999      do.  It is also helped along in that whenever a relevant change to
1000      the environment occurs, the redisplay mechanism is told about
1001      this, so it has a pretty good idea of where it has to look to find
1002      possible changes and doesn't have to look everywhere.
1003
1004    * The Lisp engine is responsible for executing the Lisp code in
1005      which most user commands are written.  It is entered through a
1006      call to `eval' or `funcall', which occurs as a result of
1007      dispatching an event from the event loop.  The functions it calls
1008      issue commands to the buffer mechanism, the window/frame
1009      subsystem, etc.
1010
1011    * The Lisp allocation subsystem is responsible for keeping track of
1012      Lisp objects.  It is given commands from the Lisp engine to
1013      allocate objects, garbage collect, etc.
1014
1015    etc.
1016
1017    The important idea here is that there are a number of independent
1018 subsystems each with its own responsibility and persistent state, just
1019 like different employees in a company, and each subsystem is
1020 periodically given commands from other subsystems.  Commands can flow
1021 from any one subsystem to any other, but there is usually some sort of
1022 hierarchy, with all commands originating from the event subsystem.
1023
1024    XEmacs is entered in `main()', which is in `emacs.c'.  When this is
1025 called the first time (in a properly-invoked `temacs'), it does the
1026 following:
1027
1028   1. It does some very basic environment initializations, such as
1029      determining where it and its directories (e.g. `lisp/' and `etc/')
1030      reside and setting up signal handlers.
1031
1032   2. It initializes the entire Lisp interpreter.
1033
1034   3. It sets the initial values of many built-in variables (including
1035      many variables that are visible to Lisp programs), such as the
1036      global keymap object and the built-in faces (a face is an object
1037      that describes the display characteristics of text).  This
1038      involves creating Lisp objects and thus is dependent on step (2).
1039
1040   4. It performs various other initializations that are relevant to the
1041      particular environment it is running in, such as retrieving
1042      environment variables, determining the current date and the user
1043      who is running the program, examining its standard input, creating
1044      any necessary file descriptors, etc.
1045
1046   5. At this point, the C initialization is complete.  A Lisp program
1047      that was specified on the command line (usually `loadup.el') is
1048      called (temacs is normally invoked as `temacs -batch -l loadup.el
1049      dump').  `loadup.el' loads all of the other Lisp files that are
1050      needed for the operation of the editor, calls the `dump-emacs'
1051      function to write out `xemacs', and then kills the temacs process.
1052
1053    When `xemacs' is then run, it only redoes steps (1) and (4) above;
1054 all variables already contain the values they were set to when the
1055 executable was dumped, and all memory that was allocated with
1056 `malloc()' is still around. (XEmacs knows whether it is being run as
1057 `xemacs' or `temacs' because it sets the global variable `initialized'
1058 to 1 after step (4) above.) At this point, `xemacs' calls a Lisp
1059 function to do any further initialization, which includes parsing the
1060 command-line (the C code can only do limited command-line parsing,
1061 which includes looking for the `-batch' and `-l' flags and a few other
1062 flags that it needs to know about before initialization is complete),
1063 creating the first frame (or "window" in standard window-system
1064 parlance), running the user's init file (usually the file `.emacs' in
1065 the user's home directory), etc.  The function to do this is usually
1066 called `normal-top-level'; `loadup.el' tells the C code about this
1067 function by setting its name as the value of the Lisp variable
1068 `top-level'.
1069
1070    When the Lisp initialization code is done, the C code enters the
1071 event loop, and stays there for the duration of the XEmacs process.
1072 The code for the event loop is contained in `keyboard.c', and is called
1073 `Fcommand_loop_1()'.  Note that this event loop could very well be
1074 written in Lisp, and in fact a Lisp version exists; but apparently,
1075 doing this makes XEmacs run noticeably slower.
1076
1077    Notice how much of the initialization is done in Lisp, not in C.  In
1078 general, XEmacs tries to move as much code as is possible into Lisp.
1079 Code that remains in C is code that implements the Lisp interpreter
1080 itself, or code that needs to be very fast, or code that needs to do
1081 system calls or other such stuff that needs to be done in C, or code
1082 that needs to have access to "forbidden" structures. (One conscious
1083 aspect of the design of Lisp under XEmacs is a clean separation between
1084 the external interface to a Lisp object's functionality and its internal
1085 implementation.  Part of this design is that Lisp programs are
1086 forbidden from accessing the contents of the object other than through
1087 using a standard API.  In this respect, XEmacs Lisp is similar to
1088 modern Lisp dialects but differs from GNU Emacs, which tends to expose
1089 the implementation and allow Lisp programs to look at it directly.  The
1090 major advantage of hiding the implementation is that it allows the
1091 implementation to be redesigned without affecting any Lisp programs,
1092 including those that might want to be "clever" by looking directly at
1093 the object's contents and possibly manipulating them.)
1094
1095    Moving code into Lisp makes the code easier to debug and maintain and
1096 makes it much easier for people who are not XEmacs developers to
1097 customize XEmacs, because they can make a change with much less chance
1098 of obscure and unwanted interactions occurring than if they were to
1099 change the C code.
1100