@ifinfo
@dircategory XEmacs Editor
@direntry
-* Internals: (internals). XEmacs Internals Manual.
+* Internals: (internals). XEmacs Internals Manual.
@end direntry
Copyright @copyright{} 1992 - 1996 Ben Wing.
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
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
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
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
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
@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.
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
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
macro style is:
@example
-#define FOO(var, value) do @{ \
- Lisp_Object FOO_value = (value); \
- ... /* compute using FOO_value */ \
- (var) = bar; \
+#define FOO(var, value) do @{ \
+ Lisp_Object FOO_value = (value); \
+ ... /* compute using FOO_value */ \
+ (var) = bar; \
@} while (0)
@end example
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.
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
@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
@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}.
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.
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.)
@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
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.
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
-1/8 -- but Mly forgot about this when rewriting things for 19.8.)
+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.)
Note also that the string data in string-chars blocks is padded as
necessary so that proper alignment constraints on the @code{struct
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.
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.
@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
-first. (This is necessary for consistency -- if there are a number of
+be read in the reverse order they were pushed back---most recent
+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}
@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
@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.
@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
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
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
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
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
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
projects / chise / xemacs-chise.git.1 / blobdiff