xemacs-beta: man/internals/internals.texi comparison

comparison man/internals/internals.texi @ 2:ac2d302a0011 r19-15b2

Import from CVS: tag r19-15b2

author	cvs
date	Mon, 13 Aug 2007 08:46:35 +0200
parents	376386a54a3c
children	d620409f5eb8

comparison

equal deleted inserted replaced

-:c0c6a60d29db
+:ac2d302a0011
 Rules When Writing New C Code
 * General Coding Rules::
 * Writing Lisp Primitives::
 * Adding Global Lisp Variables::
+* Techniques for XEmacs Developers::
 A Summary of the Various XEmacs Modules
 * Low-Level Modules::
 * Basic Lisp Modules::
 @item
 version 18.35 (a beta version) released on January 5, 1987.
 @item
 version 18.36 (a beta version) released on January 21, 1987.
 @item
+January 27, 1987: The Great Usenet Renaming.  net.emacs is now
+comp.emacs.
+@item
 version 18.37 (a beta version) released on February 12, 1987.
 @item
 version 18.38 (a beta version) released on March 3, 1987.
 @item
 version 18.39 (a beta version) released on March 14, 1987.
 version 18.50 released on February 13, 1988.
 @item
 version 18.51 released on May 7, 1988.
 @item
 version 18.52 released on September 1, 1988.
-@item
-January 27, 1989: The Great Usenet Renaming.  net.emacs is now
-comp.emacs.
 @item
 version 18.53 released on February 24, 1989.
 @item
 version 18.54 released on April 26, 1989.
 @item
 @end itemize
 etc.
 The important idea here is that there are a number of independent
-subsystems each with their own responsibility and persistent state, just
+subsystems each with its own responsibility and persistent state, just
 like different employees in a company, and each subsystem is
 periodically given commands from other subsystems.  Commands can flow
 from any one subsystem to any other, but there is usually some sort of
 hierarchy, with all commands originating from the event subsystem.
 @menu
 * General Coding Rules::
 * Writing Lisp Primitives::
 * Adding Global Lisp Variables::
+* Techniques for XEmacs Developers::
 @end menu
 @node General Coding Rules
 @section General Coding Rules
 garbage-collection mechanism won't know that the object in this variable
 is in use, and will happily collect it and reuse its storage for another
 Lisp object, and you will be the one who's unhappy when you can't figure
 out how your variable got overwritten.
+@node Techniques for XEmacs Developers
+@section Techniques for XEmacs Developers
+To make a quantified XEmacs, do: @code{make quantmacs}.
+You simply can't dump Quantified and Purified images.  Run the image
+like so:  @code{quantmacs -batch -l loadup.el run-temacs -q}.
+Before you go through the trouble, are you compiling with all
+debugging and error-checking off?  If not try that first.  Be warned
+that while Quantify is directly responsible for quite a few
+optimizations which have been made to XEmacs, doing a run which
+generates results which can be acted upon is not necessarily a trivial
+task.
+Also, if you're still willing to do some runs make sure you configure
+with the @samp{--quantify} flag.  That will keep Quantify from starting
+to record data until after the loadup is completed and will shut off
+recording right before it shuts down (which generates enough bogus data
+to throw most results off).  It also enables three additional elisp
+commands: @code{quantify-start-recording-data},
+@code{quantify-stop-recording-data} and @code{quantify-clear-data}.
+To get started debugging XEmacs, take a look at the @file{gdbinit} and
+@file{dbxrc} files in the @file{src} directory.
 @node A Summary of the Various XEmacs Modules, Allocation of Objects in XEmacs Lisp, Rules When Writing New C Code, Top
 @chapter A Summary of the Various XEmacs Modules
 This is accurate as of XEmacs 20.0.
 in their C structure, which includes all objects except the few most
 basic ones.
 @file{emacsfns.h} contains prototypes for most of the exported functions
 in the various modules. (In particular, prototypes for Lisp primitives
-should always go in this header file.  Prototypes for other functions
+should always go into this header file.  Prototypes for other functions
 can either go here or in a module-specific header file, depending on how
 general-purpose the function is and whether it has special-purpose
 argument types requiring definitions not in @file{lisp.h}.)  All
 initialization functions are prototyped in @file{symsinit.h}.
 82900  buffer.c
 60964  buffer.h
 6059  bufslots.h
 @end example
-@file{buffer.c} implements the buffer Lisp object type.  This includes
+@file{buffer.c} implements the @dfn{buffer} Lisp object type.  This
-functions that create and destroy buffers; retrieve buffers by name or
+includes functions that create and destroy buffers; retrieve buffers by
-by other properties; manipulate lists of buffers (remember that buffers
+name or by other properties; manipulate lists of buffers (remember that
-are permanent objects and stored in various ordered lists); retrieve or
+buffers are permanent objects and stored in various ordered lists);
-change buffer properties; etc.  It also contains the definitions of all
+retrieve or change buffer properties; etc.  It also contains the
-the built-in buffer-local variables (which can be viewed as buffer
+definitions of all the built-in buffer-local variables (which can be
-properties).  It does @emph{not} contain code to manipulate buffer-local
+viewed as buffer properties).  It does @emph{not} contain code to
-variables (that's in @file{symbols.c}, described above); or code to manipulate
+manipulate buffer-local variables (that's in @file{symbols.c}, described
-the text in a buffer.
+above); or code to manipulate the text in a buffer.
 @file{buffer.h} defines the structures associated with a buffer and the various
 macros for retrieving text from a buffer and special buffer positions
 (e.g. @code{point}, the default location for text insertion).  It also
 contains macros for working with buffer positions and converting between
 @example
 10975  marker.c
 @end example
-This module implements the marker Lisp object type, which conceptually
+This module implements the @dfn{marker} Lisp object type, which
-is a pointer to a text position in a buffer that moves around as text is
+conceptually is a pointer to a text position in a buffer that moves
-inserted and deleted, so as to remain in the same relative position.
+around as text is inserted and deleted, so as to remain in the same
-This module doesn't actually move the markers around -- that's handled
+relative position.  This module doesn't actually move the markers around
-in @file{insdel.c}.  This module just creates them and implements the
+-- that's handled in @file{insdel.c}.  This module just creates them and
-primitives for working with them.  As markers are simple objects, this
+implements the primitives for working with them.  As markers are simple
-does not entail much.
+objects, this does not entail much.
 Note that the standard arithmetic primitives (e.g. @code{+}) accept
 markers in place of integers and automatically substitute the value of
 @code{marker-position} for the marker, i.e. an integer describing the
 current buffer position of the marker.
 @example
 193714  extents.c
 15686  extents.h
 @end example
-This module implements the extent Lisp object type, which is like a
+This module implements the @dfn{extent} Lisp object type, which is like
-marker that works over a range of text rather than a single position.
+a marker that works over a range of text rather than a single position.
 Extents are also much more complex and powerful than markers and have a
 more efficient (and more algorithmically complex) implementation.  The
 implementation is described in detail in comments in @file{extents.c}.
 The code in @file{extents.c} works closely with @file{insdel.c} so that
 @end example
 These implement the handling of events (user input and other system
 notifications).
-@file{events.c} and @file{events.h} define the event Lisp object type
+@file{events.c} and @file{events.h} define the @dfn{event} Lisp object
-and primitives for manipulating it.
+type and primitives for manipulating it.
 @file{event-stream.c} implements the basic functions for working with
 event queues, dispatching an event by looking it up in relevant keymaps
 and such, and handling timeouts; this includes the primitives
 @code{next-event} and @code{dispatch-event}, as well as related
 @example
 129583  keymap.c
 2621  keymap.h
 @end example
-@file{keymap.c} and @file{keymap.h} define the keymap Lisp object type
+@file{keymap.c} and @file{keymap.h} define the @dfn{keymap} Lisp object
-and associated methods and primitives. (Remember that keymaps are
+type and associated methods and primitives. (Remember that keymaps are
 objects that associate event descriptions with functions to be called to
 ``execute'' those events; @code{dispatch-event} looks up events in the
 relevant keymaps.)
 11667  device-x.h
 26056  device.c
 22993  device.h
 @end example
-These modules implement the device Lisp object type.  This abstracts a
+These modules implement the @dfn{device} Lisp object type.  This
-particular screen or connection on which frames are displayed.  As with
+abstracts a particular screen or connection on which frames are
-Lisp objects, event interfaces, and other subsystems, the device code is
+displayed.  As with Lisp objects, event interfaces, and other
-separated into a generic component that contains a standardized
+subsystems, the device code is separated into a generic component that
-interface (in the form of a set of methods) onto particular device
+contains a standardized interface (in the form of a set of methods) onto
-types.
+particular device types.
 The device subsystem defines all the methods and provides method
 services for not only device operations but also for the frame, window,
 menubar, scrollbar, toolbar, and other displayable-object subsystems.
 The reason for this is that all of these subsystems have the same
 usually this is a top-level window but it could potentially be one of a
 number of overlapping child windows within a top-level window, using the
 MDI (Multiple Document Interface) protocol in Microsoft Windows or a
 similar scheme.
-The @file{frame-*} files implement the frame Lisp object type and provide the
+The @file{frame-*} files implement the @dfn{frame} Lisp object type and
-generic and device-type-specific operations on frames (e.g. raising,
+provide the generic and device-type-specific operations on frames
-lowering, resizing, moving, etc.).
+(e.g. raising, lowering, resizing, moving, etc.).
 @example
 160783  window.c
 Each frame consists of one or more non-overlapping @dfn{windows} (better
 known as @dfn{panes} in standard window-system terminology) in which a
 buffer's text can be displayed.  Windows can also have scrollbars
 displayed around their edges.
-@file{window.c} and @file{window.h} implement the window Lisp object
+@file{window.c} and @file{window.h} implement the @dfn{window} Lisp
-type and provide code to manage windows.  Since windows have no
+object type and provide code to manage windows.  Since windows have no
 associated resources in the window system (the window system knows only
 about the frame; no child windows or anything are used for XEmacs
 windows), there is no device-type-specific code here; all of that code
 is part of the redisplay mechanism or the code for particular object
 types such as scrollbars.
 -------  ---------------------
 43362  lstream.c
 14240  lstream.h
 @end example
-These modules implement the stream Lisp object type.  This is an
+These modules implement the @dfn{stream} Lisp object type.  This is an
 internal-only Lisp object that implements a generic buffering stream.
 The idea is to provide a uniform interface onto all sources and sinks of
 data, including file descriptors, stdio streams, chunks of memory, Lisp
 buffers, Lisp strings, etc.  That way, I/O functions can be written to
 the stream interface and can transparently handle all possible sources
 2454  elhash.h
 12169  hash.c
 3369  hash.h
 @end example
-These files implement the hashtable Lisp object type.  @file{hash.c} and
+These files implement the @dfn{hashtable} Lisp object type.
-@file{hash.h} provide a generic C implementation of hash tables (which
+@file{hash.c} and @file{hash.h} provide a generic C implementation of
-can stand independently of XEmacs), and @file{elhash.c} and
+hash tables (which can stand independently of XEmacs), and
-@file{elhash.h} provide a Lisp interface onto the C hash tables using
+@file{elhash.c} and @file{elhash.h} provide a Lisp interface onto the C
-the hashtable Lisp object type.
+hash tables using the hashtable Lisp object type.
 @example
 95691  specifier.c
 11167  specifier.h
 @end example
-This module implements the specifier Lisp object type.  This is
+This module implements the @dfn{specifier} Lisp object type.  This is
 primarily used for displayable properties, and allows for values that
 are specific to a particular buffer, window, frame, device, or device
 class, as well as a default value existing.  This is used, for example,
 to control the height of the horizontal scrollbar or the appearance of
 the @code{default}, @code{bold}, or other faces.  The specifier object
 @example
 20234  rangetab.c
 @end example
-This module implements the range table Lisp object type, which provides
+This module implements the @dfn{range table} Lisp object type, which
-for a mapping from ranges of integers to arbitrary Lisp objects.
+provides for a mapping from ranges of integers to arbitrary Lisp
+objects.
 @example
 3201  opaque.c
 2206  opaque.h
 @end example
-This module implements the opaque Lisp object type, an internal-only
+This module implements the @dfn{opaque} Lisp object type, an
-Lisp object that encapsulates an arbitrary block of memory so that it
+internal-only Lisp object that encapsulates an arbitrary block of memory
-can be managed by the Lisp allocation system.  To create an opaque
+so that it can be managed by the Lisp allocation system.  To create an
-object, you call @code{make_opaque()}, passing a pointer to a block of
+opaque object, you call @code{make_opaque()}, passing a pointer to a
-memory.  An object is created that is big enough to hold the memory,
+block of memory.  An object is created that is big enough to hold the
-which is copied into the object's storage.  The object will then stick
+memory, which is copied into the object's storage.  The object will then
-around as long as you keep pointers to it, after which it will be
+stick around as long as you keep pointers to it, after which it will be
 automatically reclaimed.
 @cindex mark method
 Opaque objects can also have an arbitrary @dfn{mark method} associated
 with them, in case the block of memory contains other Lisp objects that
 actually provides a general interface for all sorts of languages, not
 just Asian languages (although they are generally the most complicated
 to support).  This code is still in beta.
 @file{mule-charset.*} and @file{mule-coding.*} provide the heart of the
-XEmacs MULE support.  @file{mule-charset.*} implements the @dfn{charset} Lisp object,
+XEmacs MULE support.  @file{mule-charset.*} implements the @dfn{charset}
-which encapsulates a character set (an ordered one- or two-dimensional
+Lisp object type, which encapsulates a character set (an ordered one- or
-set of characters, such as US ASCII or JISX0208 Japanese Kanji).
+two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
-@file{mule-coding.*} implements the coding-system Lisp object, which
+Kanji).
-encapsulates a method of converting between different encodings.  An
-encoding is a representation of a stream of characters from multiple
+@file{mule-coding.*} implements the @dfn{coding-system} Lisp object
-character sets using a stream of bytes or words and defines (e.g.) which
+type, which encapsulates a method of converting between different
-escape sequences are used to specify particular character sets, how the
+encodings.  An encoding is a representation of a stream of characters
-indices for a character are converted into bytes (sometimes this
+from multiple character sets using a stream of bytes or words and
-involves setting the high bit; sometimes complicated rearranging of the
+defines (e.g.) which escape sequences are used to specify particular
-values takes place, as in the Shift-JIS encoding), etc.
+character sets, how the indices for a character are converted into bytes
+(sometimes this involves setting the high bit; sometimes complicated
+rearranging of the values takes place, as in the Shift-JIS encoding),
+etc.
 @file{mule-ccl.c} provides the CCL (Code Conversion Language)
 interpreter.  CCL is similar in spirit to Lisp byte code and is used to
 implement converters for custom encodings.
 Simple lrecords (of type (c) above) just have a @code{struct
 lrecord_header} at their beginning.  lcrecords, however, actually have a
 @code{struct lcrecord_header}.  This, in turn, has a @code{struct
 lrecord_header} at its beginning, so sanity is preserved; but it also
-has a pointer used to chain all lrecords together, and a special ID
+has a pointer used to chain all lcrecords together, and a special ID
 field used to distinguish one lcrecord from another. (This field is used
 only for debugging and could be removed, but the space gain is not
 significant.)
 Simple lrecords are created using @code{ALLOCATE_FIXED_TYPE()}, just
 During the sweep stage of garbage collection, when objects are
 reclaimed, the garbage collector goes through all string-chars blocks,
 looking for unused strings.  Each chunk of string data is preceded by a
 pointer to the corresponding @code{struct Lisp_String}, which indicates
 both whether the string is used and how big the string is, i.e. how to
-get to the next chuck of string data.  Holes are compressed by
+get to the next chunk of string data.  Holes are compressed by
 block-copying the next string into the empty space and relocating the
 pointer stored in the corresponding @code{struct Lisp_String}.
 @strong{This means you have to be careful with strings in your code.}
 See the section above on @code{GCPRO}ing.
 Events come into the system in an asynchronous fashion (typically
 through a callback being called) and are converted into a
 synchronous event queue (first-in, first-out) in a process that
 we will call @dfn{collection}.
-Note that each application has their own event queue. (It is
+Note that each application has its own event queue. (It is
 immaterial whether the collection process directly puts the
 events in the proper application's queue, or puts them into
 a single system queue, which is later split up.)
 The most basic level of event collection is done by the
 @example
 struct specbinding
 @{
 Lisp_Object symbol, old_value;
-Lisp_Object (*func) ();
+Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
-Lisp_Object unused;         /* Dividing by 16 is faster than by 12 */
 @};
 @end example
 @code{struct specbinding} is used for local-variable bindings and
 unwind-protects.  @code{specpdl} holds an array of @code{struct specbinding}'s,
 already-running XEmacs process to display another frame on your local
 TTY.
 Thus, there is a hierarchy console -> display -> frame -> window.
 There is a separate Lisp object type for each of these four concepts.
 Furthermore, there is logically a @dfn{selected console},
 @dfn{selected display}, @dfn{selected frame}, and @dfn{selected window}.
-This particular object is distinguished in various ways, such as
+Each of these objects is distinguished in various ways, such as being the
-that it is the default object for various functions that act
+default object for various functions that act on objects of that type.
-on objects of that type.  Note that every containing object
+Note that every containing object rememembers the ``selected'' object
-rememembers the ``selected'' object among the objects that it
+among the objects that it contains: e.g. not only is there a selected
-contains: e.g. not only is there a selected window, but
+window, but every frame remembers the last window in it that was
-every frame remembers the last window in it that was selected,
+selected, and changing the selected frame causes the remembered window
-and changing the selected frame causes the remembered window
+within it to become the selected window.  Similar relationships apply
-within it to become the selected window.  Similar relationships
+for consoles to devices and devices to frames.
-apply for consoles to devices and devices to frames.
 @node Point
 @section Point
 Recall that every buffer has a current insertion position, called
 Here are some rules:
 @enumerate
 @item
-Horizontal combination windows can never have children that
+Horizontal combination windows can never have children that are
-are horizontal combination windows; same for vertical.
+horizontal combination windows; same for vertical.
 @item
 Only leaf windows can be split (obviously) and this splitting does one
 of two things: (a) turns the leaf window into a combination window and
 creates two new leaf children, or (b) turns the leaf window into one of

Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 2:ac2d302a0011 r19-15b2