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

comparison man/internals/internals.texi @ 440:8de8e3f6228a r21-2-28

Import from CVS: tag r21-2-28

author	cvs
date	Mon, 13 Aug 2007 11:33:38 +0200
parents	84b14dcb0985
children	abe6d1db359e

comparison

equal deleted inserted replaced

-:357dd071b03c
+:8de8e3f6228a
 @c %**end of header
 @ifinfo
 @dircategory XEmacs Editor
 @direntry
-* Internals: (internals).	XEmacs Internals Manual.
+* Internals: (internals).       XEmacs Internals Manual.
 @end direntry
 Copyright @copyright{} 1992 - 1996 Ben Wing.
 Copyright @copyright{} 1996, 1997 Sun Microsystems.
 Copyright @copyright{} 1994 - 1998 Free Software Foundation.
 windows, frames, events) that are useful for implementing an editor.
 Some of these objects (in particular windows and frames) have
 displayable representations, and XEmacs provides a function
 @code{redisplay()} that ensures that the display of all such objects
 matches their internal state.  Most of the time, a standard Lisp
-environment is in a @dfn{read-eval-print} loop -- i.e. ``read some Lisp
+environment is in a @dfn{read-eval-print} loop---i.e. ``read some Lisp
 code, execute it, and print the results''.  XEmacs has a similar loop:
 @itemize @bullet
 @item
 read an event
 handler for some or all classes of errors. (If no handler is registered,
 a default handler, generally installed by the top-level event loop, is
 executed; this prints out the error and continues.) Routines can also
 specify cleanup code (called an @dfn{unwind-protect}) that will be
 called when control exits from a block of code, no matter how that exit
-occurs -- i.e. even if a function deeply nested below it causes a
+occurs---i.e. even if a function deeply nested below it causes a
 non-local exit back to the top level.
 Note that this facility has appeared in some recent vintages of C, in
 particular Visual C++ and other PC compilers written for the Microsoft
 Win32 API.
 that if you declare a local variable in a particular function, and then
 call another function, that subfunction can ``see'' the local variable
 you declared.  This is actually considered a bug in Emacs Lisp and in
 all other early dialects of Lisp, and was corrected in Common Lisp. (In
 Common Lisp, you can still declare dynamically scoped variables if you
-want to -- they are sometimes useful -- but variables by default are
+want to---they are sometimes useful---but variables by default are
 @dfn{lexically scoped} as in C.)
 @end enumerate
 For those familiar with Lisp, Emacs Lisp is modelled after MacLisp, an
 early dialect of Lisp developed at MIT (no relation to the Macintosh
 most other data structures in Lisp.
 @item char
 An object representing a single character of text; chars behave like
 integers in many ways but are logically considered text rather than
 numbers and have a different read syntax. (the read syntax for a char
-contains the char itself or some textual encoding of it -- for example,
+contains the char itself or some textual encoding of it---for example,
 a Japanese Kanji character might be encoded as @samp{^[$(B#&^[(B} using the
-ISO-2022 encoding standard -- rather than the numerical representation
+ISO-2022 encoding standard---rather than the numerical representation
 of the char; this way, if the mapping between chars and integers
 changes, which is quite possible for Kanji characters and other extended
 characters, the same character will still be created.  Note that some
 primitives confuse chars and integers.  The worst culprit is @code{eq},
 which makes a special exception and considers a char to be @code{eq} to
 The tag describes the type of the Lisp object.  For integers and chars,
 the lower 28 bits contain the value of the integer or char; for all
 others, the lower 28 bits contain a pointer.  The mark bit is used
 during garbage-collection, and is always 0 when garbage collection is
 not happening. (The way that garbage collection works, basically, is that it
-loops over all places where Lisp objects could exist -- this includes
+loops over all places where Lisp objects could exist---this includes
 all global variables in C that contain Lisp objects [including
 @code{Vobarray}, the C equivalent of @code{obarray}; through this, all
-Lisp variables will get marked], plus various other places -- and
+Lisp variables will get marked], plus various other places---and
 recursively scans through the Lisp objects, marking each object it finds
 by setting the mark bit.  Then it goes through the lists of all objects
 allocated, freeing the ones that are not marked and turning off the mark
 bit of the ones that are marked.)
 machines/compilers do this, and on the ones that don't, a more
 complicated definition is selected by defining
 @code{EXPLICIT_SIGN_EXTEND}.
 Note that when @code{ERROR_CHECK_TYPECHECK} is defined, the extractor
-macros become more complicated -- they check the tag bits and/or the
+macros become more complicated---they check the tag bits and/or the
 type field in the first four bytes of a record type to ensure that the
 object is really of the correct type.  This is great for catching places
-where an incorrect type is being dereferenced -- this typically results
+where an incorrect type is being dereferenced---this typically results
 in a pointer being dereferenced as the wrong type of structure, with
 unpredictable (and sometimes not easily traceable) results.
 There are similar @code{XSET@var{TYPE}()} macros that construct a Lisp
 object.  These macros are of the form @code{XSET@var{TYPE}
 the same directory as the C sources) and @file{lisp.h}.  @file{config.h}
 must always be included before any other header files (including
 system header files) to ensure that certain tricks played by various
 @file{s/} and @file{m/} files work out correctly.
+When including header files, always use angle brackets, not double
+quotes, except when the file to be included is in the same directory as
+the including file.  If either file is a generated file, then that is
+not likely to be the case.  In order to understand why we have this
+rule, imagine what happens when you do a build in the source directory
+using @samp{./configure} and another build in another directory using
+@samp{../work/configure}.  There will be two different @file{config.h}
+files.  Which one will be used if you @samp{#include "config.h"}?
 @strong{All global and static variables that are to be modifiable must
 be declared uninitialized.}  This means that you may not use the
 ``declare with initializer'' form for these variables, such as @code{int
 some_variable = 0;}.  The reason for this has to do with some kludges
 done during the dumping process: If possible, the initialized data
 segment is re-mapped so that it becomes part of the (unmodifiable) code
 segment in the dumped executable.  This allows this memory to be shared
 among multiple running XEmacs processes.  XEmacs is careful to place as
 much constant data as possible into initialized variables (in
-particular, into what's called the @dfn{pure space} -- see below) during
+particular, into what's called the @dfn{pure space}---see below) during
 the @file{temacs} phase.
 @cindex copy-on-write
 @strong{Please note:} This kludge only works on a few systems nowadays,
 and is rapidly becoming irrelevant because most modern operating systems
 The C source code makes heavy use of C preprocessor macros.  One popular
 macro style is:
 @example
-#define FOO(var, value) do @{		\
+#define FOO(var, value) do @{           \
-Lisp_Object FOO_value = (value);	\
+Lisp_Object FOO_value = (value);      \
-... /* compute using FOO_value */	\
+... /* compute using FOO_value */     \
-(var) = bar;				\
+(var) = bar;                          \
 @} while (0)
 @end example
 The @code{do @{...@} while (0)} is a standard trick to allow FOO to have
 statement semantics, so that it can safely be used within an @code{if}
 declarations (i.e. a simple declaration like @code{struct foo;} where
 the structure itself is defined elsewhere) should be placed into the
 typedefs section as necessary.
 @file{lrecord.h} contains the basic structures and macros that implement
-all record-type Lisp objects -- i.e. all objects whose type is a field
+all record-type Lisp objects---i.e. all objects whose type is a field
 in their C structure, which includes all objects except the few most
 basic ones.
 @file{lisp.h} contains prototypes for most of the exported functions in
 the various modules.  Lisp primitives defined using @code{DEFUN} that
 not dependent on any particular object type, and interfaces to
 particular types of objects using a standardized interface of
 type-specific methods.  This scheme is a fundamental principle of
 object-oriented programming and is heavily used throughout XEmacs.  The
 great advantage of this is that it allows for a clean separation of
-functionality into different modules -- new classes of Lisp objects, new
+functionality into different modules---new classes of Lisp objects, new
 event interfaces, new device types, new stream interfaces, etc. can be
 added transparently without affecting code anywhere else in XEmacs.
 Because the different subsystems are divided into general and specific
 code, adding a new subtype within a subsystem will in general not
 require changes to the generic subsystem code or affect any of the other
 @end example
 @file{symbols.c} implements the handling of symbols, obarrays, and
 retrieving the values of symbols.  Much of the code is devoted to
 handling the special @dfn{symbol-value-magic} objects that define
-special types of variables -- this includes buffer-local variables,
+special types of variables---this includes buffer-local variables,
 variable aliases, variables that forward into C variables, etc.  This
 module is initialized extremely early (right after @file{alloc.c}),
 because it is here that the basic symbols @code{t} and @code{nil} are
 created, and those symbols are used everywhere throughout XEmacs.
 @example
 keyboard.c
 @end example
 @file{keyboard.c} contains functions that implement the actual editor
-command loop -- i.e. the event loop that cyclically retrieves and
+command loop---i.e. the event loop that cyclically retrieves and
 dispatches events.  This code is also rather tricky, just like
 @file{event-stream.c}.
 @example
 font-lock.c
 @end example
-This file provides C support for syntax highlighting -- i.e.
+This file provides C support for syntax highlighting---i.e.
 highlighting different syntactic constructs of a source file in
 different colors, for easy reading.  The C support is provided so that
 this is fast.
 @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
 need to be marked for garbage-collection purposes. (If you need other
 object methods, such as a finalize method, you should just go ahead and
-create a new Lisp object type -- it's not hard.)
+create a new Lisp object type---it's not hard.)
 @example
 abbrev.c
 format; this includes conses, strings, vectors, and sometimes symbols.
 With the exception of vectors, objects in this category are allocated in
 @dfn{frob blocks}, i.e. large blocks of memory that are subdivided into
 individual objects.  This saves a lot on malloc overhead, since there
 are typically quite a lot of these objects around, and the objects are
-small.  (A cons, for example, occupies 8 bytes on 32-bit machines -- 4
+small.  (A cons, for example, occupies 8 bytes on 32-bit machines---4
 bytes for each of the two objects it contains.) Vectors are individually
 @code{malloc()}ed since they are of variable size.  (It would be
 possible, and desirable, to allocate vectors of certain small sizes out
 of frob blocks, but it isn't currently done.) Strings are handled
 specially: Each string is allocated in two parts, a fixed size structure
 variable @samp{gcprolist} pointing to the head of the list and the nth
 local @code{gcpro} variable pointing to the first @code{gcpro} variable
 in the next enclosing stack frame.  Each @code{GCPRO}ed thing is an
 lvalue, and the @code{struct gcpro} local variable contains a pointer to
 this lvalue.  This is why things will mess up badly if you don't pair up
-the @code{GCPRO}s and @code{UNGCPRO}s -- you will end up with
+the @code{GCPRO}s and @code{UNGCPRO}s---you will end up with
 @code{gcprolist}s containing pointers to @code{struct gcpro}s or local
 @code{Lisp_Object} variables in no-longer-active stack frames.
 @item
 It is actually possible for a single @code{struct gcpro} to
 Note that there is one situation not handled: a string that is too big
 to fit into a string-chars block.  Such strings, called @dfn{big
 strings}, are all @code{malloc()}ed as their own block. (#### Although it
 would make more sense for the threshold for big strings to be somewhat
 lower, e.g. 1/2 or 1/4 the size of a string-chars block.  It seems that
-this was indeed the case formerly -- indeed, the threshold was set at
+this was indeed the case formerly---indeed, the threshold was set at
-1/8 -- but Mly forgot about this when rewriting things for 19.8.)
+1/8---but Mly forgot about this when rewriting things for 19.8.)
 Note also that the string data in string-chars blocks is padded as
 necessary so that proper alignment constraints on the @code{struct
 Lisp_String} back pointers are maintained.
 XEmacs has its own types of events (called @dfn{Emacs events}),
 which provides an abstract layer on top of the system-dependent
 nature of the most basic events that are received.  Part of the
 complex nature of the XEmacs event collection process involves
 converting from the operating-system events into the proper
-Emacs events -- there may not be a one-to-one correspondence.
+Emacs events---there may not be a one-to-one correspondence.
 Emacs events are documented in @file{events.h}; I'll discuss them
 later.
 @node Main Loop
 one console), and the engine that looks up keystrokes and
 constructs full key sequences is called the @dfn{command builder}.
 This is documented elsewhere.
 The guts of the command loop are in @code{command_loop_1()}.  This
-function doesn't catch errors, though -- that's the job of
+function doesn't catch errors, though---that's the job of
 @code{command_loop_2()}, which is a condition-case (i.e. error-trapping)
 wrapper around @code{command_loop_1()}.  @code{command_loop_1()} never
 returns, but may get thrown out of.
 When an error occurs, @code{cmd_error()} is called, which usually
 @end deftypefn
 @deftypefn Macro void Lstream_ungetc (Lstream *@var{stream}, int @var{c})
 Push one byte back onto the input queue.  This will be the next byte
 read from the stream.  Any number of bytes can be pushed back and will
-be read in the reverse order they were pushed back -- most recent
+be read in the reverse order they were pushed back---most recent
-first. (This is necessary for consistency -- if there are a number of
+first. (This is necessary for consistency---if there are a number of
 bytes that have been unread and I read and unread a byte, it needs to be
 the first to be read again.) This is a macro and so it is very
 efficient.  The @var{c} argument is only evaluated once but the @var{stream}
 argument is evaluated more than once.
 @end deftypefn
 @end deftypefun
 @deftypefun void Lstream_reopen (Lstream *@var{stream})
 Reopen a closed stream.  This enables I/O on it again.  This is not
 meant to be called except from a wrapper routine that reinitializes
-variables and such -- the close routine may well have freed some
+variables and such---the close routine may well have freed some
 necessary storage structures, for example.
 @end deftypefun
 @deftypefun void Lstream_rewind (Lstream *@var{stream})
 Rewind the stream to the beginning.
 @deftypefn {Lstream Method} int rewinder (Lstream *@var{stream})
 Rewind the stream.  If this is @code{NULL}, the stream is not seekable.
 @end deftypefn
 @deftypefn {Lstream Method} int seekable_p (Lstream *@var{stream})
-Indicate whether this stream is seekable -- i.e. it can be rewound.
+Indicate whether this stream is seekable---i.e. it can be rewound.
 This method is ignored if the stream does not have a rewind method.  If
 this method is not present, the result is determined by whether a rewind
 method is present.
 @end deftypefn
 @dfn{one above the other}.
 @item
 Leaf windows also have markers in their @code{start} (the
 first buffer position displayed in the window) and @code{pointm}
-(the window's stashed value of @code{point} -- see above) fields,
+(the window's stashed value of @code{point}---see above) fields,
 while combination windows have nil in these fields.
 @item
 The list of children for a window is threaded through the
 @code{next} and @code{prev} fields of each child window.
 does nothing except set a special @code{dead} bit to 1 and clear out the
 @code{next}, @code{prev}, @code{hchild}, and @code{vchild} fields, for
 GC purposes.
 @item
-Most frames actually have two top-level windows -- one for the
+Most frames actually have two top-level windows---one for the
 minibuffer and one (the @dfn{root}) for everything else.  The modeline
 (if present) separates these two.  The @code{next} field of the root
 points to the minibuffer, and the @code{prev} field of the minibuffer
 points to the root.  The other @code{next} and @code{prev} fields are
 @code{nil}, and the frame points to both of these windows.
 information basically for free.  In those cases where a user is simply
 scrolling around viewing a buffer there is a high probability that this
 is sufficient to always provide the needed information.  The second
 thing we can do is be smart about invalidating the cache.
-TODO -- Be smart about invalidating the cache.  Potential places:
+TODO---Be smart about invalidating the cache.  Potential places:
 @itemize @bullet
 @item
 Insertions at end-of-line which don't cause line-wraps do not alter the
 starting positions of any display lines.  These types of buffer
 @section Format of the Extent Info
 An extent-info structure consists of a list of the buffer or string's
 extents and a @dfn{stack of extents} that lists all of the extents over
 a particular position.  The stack-of-extents info is used for
-optimization purposes -- it basically caches some info that might
+optimization purposes---it basically caches some info that might
 be expensive to compute.  Certain otherwise hard computations are easy
 given the stack of extents over a particular position, and if the
 stack of extents over a nearby position is known (because it was
 calculated at some prior point in time), it's easy to move the stack
 of extents to the proper position.
 @dfn{runs} of text such that no extent starts or ends within a run
 (extents that abut the run don't count).
 An extent fragment is a structure that holds data about the run that
 contains a particular buffer position (if the buffer position is at the
-junction of two runs, the run after the position is used) -- the
+junction of two runs, the run after the position is used)---the
 beginning and end of the run, a list of all of the extents in that run,
 the @dfn{merged face} that results from merging all of the faces
 corresponding to those extents, the begin and end glyphs at the
 beginning of the run, etc.  This is the information that redisplay needs
 in order to display this run.
 cached on a window basis.
 Any action on a glyph first consults the cache before actually
 instantiating a widget.
-@section Widget-Glyphs in the MS-WIndows Environment
+@section Widget-Glyphs in the MS-Windows Environment
 To Do
 @section Widget-Glyphs in the X Environment

Mercurial > hg > xemacs-beta

comparison man/internals/internals.texi @ 440:8de8e3f6228a r21-2-28