(J90-7023): Unify JIS X 0208:1978 and 1983 code points.
[chise/xemacs-chise.git] / info / internals.info-3
index c6ed97c..48b542a 100644 (file)
@@ -1,4 +1,4 @@
-This is ../info/internals.info, produced by makeinfo version 4.0 from
+This is ../info/internals.info, produced by makeinfo version 4.0b from
 internals/internals.texi.
 
 INFO-DIR-SECTION XEmacs Editor
@@ -38,105 +38,6 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
-File: internals.info,  Node: Working With Character and Byte Positions,  Next: Conversion to and from External Data,  Prev: Character-Related Data Types,  Up: Coding for Mule
-
-Working With Character and Byte Positions
------------------------------------------
-
-   Now that we have defined the basic character-related types, we can
-look at the macros and functions designed for work with them and for
-conversion between them.  Most of these macros are defined in
-`buffer.h', and we don't discuss all of them here, but only the most
-important ones.  Examining the existing code is the best way to learn
-about them.
-
-`MAX_EMCHAR_LEN'
-     This preprocessor constant is the maximum number of buffer bytes
-     per Emacs character, i.e. the byte length of an `Emchar'.  It is
-     useful when allocating temporary strings to keep a known number of
-     characters.  For instance:
-
-          {
-            Charcount cclen;
-            ...
-            {
-              /* Allocate place for CCLEN characters. */
-              Bufbyte *buf = (Bufbyte *)alloca (cclen * MAX_EMCHAR_LEN);
-          ...
-
-     If you followed the previous section, you can guess that,
-     logically, multiplying a `Charcount' value with `MAX_EMCHAR_LEN'
-     produces a `Bytecount' value.
-
-     In the current Mule implementation, `MAX_EMCHAR_LEN' equals 4.
-     Without Mule, it is 1.
-
-`charptr_emchar'
-`set_charptr_emchar'
-     The `charptr_emchar' macro takes a `Bufbyte' pointer and returns
-     the `Emchar' stored at that position.  If it were a function, its
-     prototype would be:
-
-          Emchar charptr_emchar (Bufbyte *p);
-
-     `set_charptr_emchar' stores an `Emchar' to the specified byte
-     position.  It returns the number of bytes stored:
-
-          Bytecount set_charptr_emchar (Bufbyte *p, Emchar c);
-
-     It is important to note that `set_charptr_emchar' is safe only for
-     appending a character at the end of a buffer, not for overwriting a
-     character in the middle.  This is because the width of characters
-     varies, and `set_charptr_emchar' cannot resize the string if it
-     writes, say, a two-byte character where a single-byte character
-     used to reside.
-
-     A typical use of `set_charptr_emchar' can be demonstrated by this
-     example, which copies characters from buffer BUF to a temporary
-     string of Bufbytes.
-
-          {
-            Bufpos pos;
-            for (pos = beg; pos < end; pos++)
-              {
-                Emchar c = BUF_FETCH_CHAR (buf, pos);
-                p += set_charptr_emchar (buf, c);
-              }
-          }
-
-     Note how `set_charptr_emchar' is used to store the `Emchar' and
-     increment the counter, at the same time.
-
-`INC_CHARPTR'
-`DEC_CHARPTR'
-     These two macros increment and decrement a `Bufbyte' pointer,
-     respectively.  They will adjust the pointer by the appropriate
-     number of bytes according to the byte length of the character
-     stored there.  Both macros assume that the memory address is
-     located at the beginning of a valid character.
-
-     Without Mule support, `INC_CHARPTR (p)' and `DEC_CHARPTR (p)'
-     simply expand to `p++' and `p--', respectively.
-
-`bytecount_to_charcount'
-     Given a pointer to a text string and a length in bytes, return the
-     equivalent length in characters.
-
-          Charcount bytecount_to_charcount (Bufbyte *p, Bytecount bc);
-
-`charcount_to_bytecount'
-     Given a pointer to a text string and a length in characters,
-     return the equivalent length in bytes.
-
-          Bytecount charcount_to_bytecount (Bufbyte *p, Charcount cc);
-
-`charptr_n_addr'
-     Return a pointer to the beginning of the character offset CC (in
-     characters) from P.
-
-          Bufbyte *charptr_n_addr (Bufbyte *p, Charcount cc);
-
-\1f
 File: internals.info,  Node: Conversion to and from External Data,  Next: General Guidelines for Writing Mule-Aware Code,  Prev: Working With Character and Byte Positions,  Up: Coding for Mule
 
 Conversion to and from External Data
@@ -152,99 +53,132 @@ convert it to an appropriate external encoding, lest the internal stuff
 
    The interface to conversion between the internal and external
 representations of text are the numerous conversion macros defined in
-`buffer.h'.  Before looking at them, we'll look at the external formats
-supported by these macros.
-
-   Currently meaningful formats are `FORMAT_BINARY', `FORMAT_FILENAME',
-`FORMAT_OS', and `FORMAT_CTEXT'.  Here is a description of these.
-
-`FORMAT_BINARY'
-     Binary format.  This is the simplest format and is what we use in
-     the absence of a more appropriate format.  This converts according
-     to the `binary' coding system:
-
-       a. On input, bytes 0-255 are converted into characters 0-255.
+`buffer.h'.  There used to be a fixed set of external formats supported
+by these macros, but now any coding system can be used with these
+macros.  The coding system alias mechanism is used to create the
+following logical coding systems, which replace the fixed external
+formats.  The (dontusethis-set-symbol-value-handler) mechanism was
+enhanced to make this possible (more work on that is needed - like
+remove the `dontusethis-' prefix).
+
+`Qbinary'
+     This is the simplest format and is what we use in the absence of a
+     more appropriate format.  This converts according to the `binary'
+     coding system:
+
+       a. On input, bytes 0-255 are converted into (implicitly Latin-1)
+          characters 0-255.  A non-Mule xemacs doesn't really know about
+          different character sets and the fonts to display them, so
+          the bytes can be treated as text in different 1-byte
+          encodings by simply setting the appropriate fonts.  So in a
+          sense, non-Mule xemacs is a multi-lingual editor if, for
+          example, different fonts are used to display text in
+          different buffers, faces, or windows.  The specifier
+          mechanism gives the user complete control over this kind of
+          behavior.
 
        b. On output, characters 0-255 are converted into bytes 0-255
-          and other characters are converted into `X'.
+          and other characters are converted into `~'.
 
-`FORMAT_FILENAME'
-     Format used for filenames.  In the original Mule, this is
-     user-definable with the `pathname-coding-system' variable.  For
-     the moment, we just use the `binary' coding system.
+`Qfile_name'
+     Format used for filenames.  This is user-definable via either the
+     `file-name-coding-system' or `pathname-coding-system' (now
+     obsolete) variables.
 
-`FORMAT_OS'
+`Qnative'
      Format used for the external Unix environment--`argv[]', stuff
      from `getenv()', stuff from the `/etc/passwd' file, etc.
+     Currently this is the same as Qfile_name.  The two should be
+     distinguished for clarity and possible future separation.
+
+`Qctext'
+     Compound-text format.  This is the standard X11 format used for
+     data stored in properties, selections, and the like.  This is an
+     8-bit no-lock-shift ISO2022 coding system.  This is a real coding
+     system, unlike Qfile_name, which is user-definable.
+
+   There are two fundamental macros to convert between external and
+internal format.
+
+   `TO_INTERNAL_FORMAT' converts external data to internal format, and
+`TO_EXTERNAL_FORMAT' converts the other way around.  The arguments each
+of these receives are a source type, a source, a sink type, a sink, and
+a coding system (or a symbol naming a coding system).
+
+   A typical call looks like
+     TO_EXTERNAL_FORMAT (LISP_STRING, str, C_STRING_MALLOC, ptr, Qfile_name);
+
+   which means that the contents of the lisp string `str' are written
+to a malloc'ed memory area which will be pointed to by `ptr', after the
+function returns.  The conversion will be done using the `file-name'
+coding system, which will be controlled by the user indirectly by
+setting or binding the variable `file-name-coding-system'.
+
+   Some sources and sinks require two C variables to specify.  We use
+some preprocessor magic to allow different source and sink types, and
+even different numbers of arguments to specify different types of
+sources and sinks.
+
+   So we can have a call that looks like
+     TO_INTERNAL_FORMAT (DATA, (ptr, len),
+                         MALLOC, (ptr, len),
+                         coding_system);
+
+   The parenthesized argument pairs are required to make the
+preprocessor magic work.
+
+   Here are the different source and sink types:
+
+``DATA, (ptr, len),''
+     input data is a fixed buffer of size LEN at address PTR
+
+``ALLOCA, (ptr, len),''
+     output data is placed in an alloca()ed buffer of size LEN pointed
+     to by PTR
+
+``MALLOC, (ptr, len),''
+     output data is in a malloc()ed buffer of size LEN pointed to by PTR
+
+``C_STRING_ALLOCA, ptr,''
+     equivalent to `ALLOCA (ptr, len_ignored)' on output.
+
+``C_STRING_MALLOC, ptr,''
+     equivalent to `MALLOC (ptr, len_ignored)' on output
+
+``C_STRING, ptr,''
+     equivalent to `DATA, (ptr, strlen (ptr) + 1)' on input
+
+``LISP_STRING, string,''
+     input or output is a Lisp_Object of type string
+
+``LISP_BUFFER, buffer,''
+     output is written to `(point)' in lisp buffer BUFFER
+
+``LISP_LSTREAM, lstream,''
+     input or output is a Lisp_Object of type lstream
+
+``LISP_OPAQUE, object,''
+     input or output is a Lisp_Object of type opaque
 
-     Perhaps should be the same as FORMAT_FILENAME.
-
-`FORMAT_CTEXT'
-     Compound-text format.  This is the standard X format used for data
-     stored in properties, selections, and the like.  This is an 8-bit
-     no-lock-shift ISO2022 coding system.
-
-   The macros to convert between these formats and the internal format,
-and vice versa, follow.
-
-`GET_CHARPTR_INT_DATA_ALLOCA'
-`GET_CHARPTR_EXT_DATA_ALLOCA'
-     These two are the most basic conversion macros.
-     `GET_CHARPTR_INT_DATA_ALLOCA' converts external data to internal
-     format, and `GET_CHARPTR_EXT_DATA_ALLOCA' converts the other way
-     around.  The arguments each of these receives are PTR (pointer to
-     the text in external format), LEN (length of texts in bytes), FMT
-     (format of the external text), PTR_OUT (lvalue to which new text
-     should be copied), and LEN_OUT (lvalue which will be assigned the
-     length of the internal text in bytes).  The resulting text is
-     stored to a stack-allocated buffer.  If the text doesn't need
-     changing, these macros will do nothing, except for setting LEN_OUT.
-
-     The macros above take many arguments which makes them unwieldy.
-     For this reason, a number of convenience macros are defined with
-     obvious functionality, but accepting less arguments.  The general
-     rule is that macros with `INT' in their name convert text to
-     internal Emacs representation, whereas the `EXT' macros convert to
-     external representation.
-
-`GET_C_CHARPTR_INT_DATA_ALLOCA'
-`GET_C_CHARPTR_EXT_DATA_ALLOCA'
-     As their names imply, these macros work on C char pointers, which
-     are zero-terminated, and thus do not need LEN or LEN_OUT
-     parameters.
-
-`GET_STRING_EXT_DATA_ALLOCA'
-`GET_C_STRING_EXT_DATA_ALLOCA'
-     These two macros convert a Lisp string into an external
-     representation.  The difference between them is that
-     `GET_STRING_EXT_DATA_ALLOCA' stores its output to a generic
-     string, providing LEN_OUT, the length of the resulting external
-     string.  On the other hand, `GET_C_STRING_EXT_DATA_ALLOCA' assumes
-     that the caller will be satisfied with output string being
-     zero-terminated.
-
-     Note that for Lisp strings only one conversion direction makes
-     sense.
-
-`GET_C_CHARPTR_EXT_BINARY_DATA_ALLOCA'
-`GET_CHARPTR_EXT_BINARY_DATA_ALLOCA'
-`GET_STRING_BINARY_DATA_ALLOCA'
-`GET_C_STRING_BINARY_DATA_ALLOCA'
-`GET_C_CHARPTR_EXT_FILENAME_DATA_ALLOCA'
-`...'
-     These macros convert internal text to a specific external
-     representation, with the external format being encoded into the
-     name of the macro.  Note that the `GET_STRING_...' and
-     `GET_C_STRING...'  macros lack the `EXT' tag, because they only
-     make sense in that direction.
-
-`GET_C_CHARPTR_INT_BINARY_DATA_ALLOCA'
-`GET_CHARPTR_INT_BINARY_DATA_ALLOCA'
-`GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA'
-`...'
-     These macros convert external text of a specific format to its
-     internal representation, with the external format being incoded
-     into the name of the macro.
+   Often, the data is being converted to a '\0'-byte-terminated string,
+which is the format required by many external system C APIs.  For these
+purposes, a source type of `C_STRING' or a sink type of
+`C_STRING_ALLOCA' or `C_STRING_MALLOC' is appropriate.  Otherwise, we
+should try to keep XEmacs '\0'-byte-clean, which means using (ptr, len)
+pairs.
+
+   The sinks to be specified must be lvalues, unless they are the lisp
+object types `LISP_LSTREAM' or `LISP_BUFFER'.
+
+   For the sink types `ALLOCA' and `C_STRING_ALLOCA', the resulting
+text is stored in a stack-allocated buffer, which is automatically
+freed on returning from the function.  However, the sink types `MALLOC'
+and `C_STRING_MALLOC' return `xmalloc()'ed memory.  The caller is
+responsible for freeing this memory using `xfree()'.
+
+   Note that it doesn't make sense for `LISP_STRING' to be a source for
+`TO_INTERNAL_FORMAT' or a sink for `TO_EXTERNAL_FORMAT'.  You'll get an
+assertion failure if you try.
 
 \1f
 File: internals.info,  Node: General Guidelines for Writing Mule-Aware Code,  Next: An Example of Mule-Aware Code,  Prev: Conversion to and from External Data,  Up: Coding for Mule
@@ -275,10 +209,22 @@ _Always convert external data_
      internal buffers literally.
 
      This means that when a system function, such as `readdir', returns
-     a string, you need to convert it using one of the conversion macros
-     described in the previous chapter, before passing it further to
-     Lisp.  In the case of `readdir', you would use the
-     `GET_C_CHARPTR_INT_FILENAME_DATA_ALLOCA' macro.
+     a string, you may need to convert it using one of the conversion
+     macros described in the previous chapter, before passing it
+     further to Lisp.
+
+     Actually, most of the basic system functions that accept
+     '\0'-terminated string arguments, like `stat()' and `open()', have
+     been *encapsulated* so that they are they `always' do internal to
+     external conversion themselves.  This means you must pass
+     internally encoded data, typically the `XSTRING_DATA' of a
+     Lisp_String to these functions.  This is actually a design bug,
+     since it unexpectedly changes the semantics of the system
+     functions.  A better design would be to provide separate versions
+     of these system functions that accepted Lisp_Objects which were
+     lisp strings in place of their current `char *' arguments.
+
+          int stat_lisp (Lisp_Object path, struct stat *buf); /* Implement me */
 
      Also note that many internal functions, such as `make_string',
      accept Bufbytes, which removes the need for them to convert the
@@ -292,7 +238,7 @@ File: internals.info,  Node: An Example of Mule-Aware Code,  Prev: General Guide
 An Example of Mule-Aware Code
 -----------------------------
 
-   As an example of Mule-aware code, we shall will analyze the `string'
+   As an example of Mule-aware code, we will analyze the `string'
 function, which conses up a Lisp string from the character arguments it
 receives.  Here is the definition, pasted from `alloc.c':
 
@@ -340,13 +286,17 @@ File: internals.info,  Node: Techniques for XEmacs Developers,  Prev: Coding for
 Techniques for XEmacs Developers
 ================================
 
-   To make a quantified XEmacs, do: `make quantmacs'.
+   To make a purified XEmacs, do: `make puremacs'.  To make a
+quantified XEmacs, do: `make quantmacs'.
 
-   You simply can't dump Quantified and Purified images.  Run the image
-like so:  `quantmacs -batch -l loadup.el run-temacs XEMACS-ARGS...'.
+   You simply can't dump Quantified and Purified images (unless using
+the portable dumper).  Purify gets confused when xemacs frees memory in
+one process that was allocated in a _different_ process on a different
+machine!.  Run it like so:
+     temacs -batch -l loadup.el run-temacs XEMACS-ARGS...
 
    Before you go through the trouble, are you compiling with all
-debugging and error-checking off?  If not try that first.  Be warned
+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
@@ -382,14 +332,105 @@ out where the cycles are going.  Specific projects:
 Function calls in elisp are especially expensive.  Iterating over a
 long list is going to be 30 times faster implemented in C than in Elisp.
 
+   Heavily used small code fragments need to be fast.  The traditional
+way to implement such code fragments in C is with macros.  But macros
+in C are known to be broken.
+
+   Macro arguments that are repeatedly evaluated may suffer from
+repeated side effects or suboptimal performance.
+
+   Variable names used in macros may collide with caller's variables,
+causing (at least) unwanted compiler warnings.
+
+   In order to solve these problems, and maintain statement semantics,
+one should use the `do { ... } while (0)' trick while trying to
+reference macro arguments exactly once using local variables.
+
+   Let's take a look at this poor macro definition:
+
+     #define MARK_OBJECT(obj) \
+       if (!marked_p (obj)) mark_object (obj), did_mark = 1
+
+   This macro evaluates its argument twice, and also fails if used like
+this:
+       if (flag) MARK_OBJECT (obj); else do_something();
+
+   A much better definition is
+
+     #define MARK_OBJECT(obj) do { \
+       Lisp_Object mo_obj = (obj); \
+       if (!marked_p (mo_obj))     \
+         {                         \
+           mark_object (mo_obj);   \
+           did_mark = 1;           \
+         }                         \
+     } while (0)
+
+   Notice the elimination of double evaluation by using the local
+variable with the obscure name.  Writing safe and efficient macros
+requires great care.  The one problem with macros that cannot be
+portably worked around is, since a C block has no value, a macro used
+as an expression rather than a statement cannot use the techniques just
+described to avoid multiple evaluation.
+
+   In most cases where a macro has function semantics, an inline
+function is a better implementation technique.  Modern compiler
+optimizers tend to inline functions even if they have no `inline'
+keyword, and configure magic ensures that the `inline' keyword can be
+safely used as an additional compiler hint.  Inline functions used in a
+single .c files are easy.  The function must already be defined to be
+`static'.  Just add another `inline' keyword to the definition.
+
+     inline static int
+     heavily_used_small_function (int arg)
+     {
+       ...
+     }
+
+   Inline functions in header files are trickier, because we would like
+to make the following optimization if the function is _not_ inlined
+(for example, because we're compiling for debugging).  We would like the
+function to be defined externally exactly once, and each calling
+translation unit would create an external reference to the function,
+instead of including a definition of the inline function in the object
+code of every translation unit that uses it.  This optimization is
+currently only available for gcc.  But you don't have to worry about the
+trickiness; just define your inline functions in header files using this
+pattern:
+
+     INLINE_HEADER int
+     i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg);
+     INLINE_HEADER int
+     i_used_to_be_a_crufty_macro_but_look_at_me_now (int arg)
+     {
+       ...
+     }
+
+   The declaration right before the definition is to prevent warnings
+when compiling with `gcc -Wmissing-declarations'.  I consider issuing
+this warning for inline functions a gcc bug, but the gcc maintainers
+disagree.
+
+   Every header which contains inline functions, either directly by
+using `INLINE_HEADER' or indirectly by using `DECLARE_LRECORD' must be
+added to `inline.c''s includes to make the optimization described above
+work.  (Optimization note: if all INLINE_HEADER functions are in fact
+inlined in all translation units, then the linker can just discard
+`inline.o', since it contains only unreferenced code).
+
    To get started debugging XEmacs, take a look at the `.gdbinit' and
-`.dbxrc' files in the `src' directory.  *Note Q2.1.15 - How to Debug an
-XEmacs problem with a debugger: (xemacs-faq)Q2.1.15 - How to Debug an
-XEmacs problem with a debugger.
+`.dbxrc' files in the `src' directory.  See the section in the XEmacs
+FAQ on How to Debug an XEmacs problem with a debugger.
 
    After making source code changes, run `make check' to ensure that
-you haven't introduced any regressions.  If you're feeling ambitious,
-you can try to improve the test suite in `tests/automated'.
+you haven't introduced any regressions.  If you want to make xemacs more
+reliable, please improve the test suite in `tests/automated'.
+
+   Did you make sure you didn't introduce any new compiler warnings?
+
+   Before submitting a patch, please try compiling at least once with
+
+     configure --with-mule --with-union-type --error-checking=all
 
    Here are things to know when you create a new source file:
 
@@ -400,7 +441,7 @@ you can try to improve the test suite in `tests/automated'.
      <...>' syntax, not the `#include "..."' syntax.  The generated
      headers are:
 
-     `config.h puresize-adjust.h sheap-adjust.h paths.h Emacs.ad.h'
+     `config.h sheap-adjust.h paths.h Emacs.ad.h'
 
      The basic rule is that you should assume builds using `--srcdir'
      and the `#include <...>' syntax needs to be used when the
@@ -412,15 +453,27 @@ you can try to improve the test suite in `tests/automated'.
    * Header files should _not_ include `<config.h>' and `"lisp.h"'.  It
      is the responsibility of the `.c' files that use it to do so.
 
-   * If the header uses `INLINE', either directly or through
-     `DECLARE_LRECORD', then it must be added to `inline.c''s includes.
 
-   * Try compiling at least once with
+   Here is a checklist of things to do when creating a new lisp object
+type named FOO:
+
+  1. create FOO.h
+
+  2. create FOO.c
+
+  3. add definitions of `syms_of_FOO', etc. to `FOO.c'
+
+  4. add declarations of `syms_of_FOO', etc. to `symsinit.h'
 
-          gcc --with-mule --with-union-type --error-checking=all
+  5. add calls to `syms_of_FOO', etc. to `emacs.c'
 
-   * Did I mention that you should run the test suite?
-          make check
+  6. add definitions of macros like `CHECK_FOO' and `FOOP' to `FOO.h'
+
+  7. add the new type index to `enum lrecord_type'
+
+  8. add a DEFINE_LRECORD_IMPLEMENTATION call to `FOO.c'
+
+  9. add an INIT_LRECORD_IMPLEMENTATION call to `syms_of_FOO.c'
 
 \1f
 File: internals.info,  Node: A Summary of the Various XEmacs Modules,  Next: Allocation of Objects in XEmacs Lisp,  Prev: Rules When Writing New C Code,  Up: Top
@@ -446,7 +499,7 @@ A Summary of the Various XEmacs Modules
 * Modules for Internationalization::
 
 \1f
-File: internals.info,  Node: Low-Level Modules,  Next: Basic Lisp Modules,  Up: A Summary of the Various XEmacs Modules
+File: internals.info,  Node: Low-Level Modules,  Next: Basic Lisp Modules,  Prev: A Summary of the Various XEmacs Modules,  Up: A Summary of the Various XEmacs Modules
 
 Low-Level Modules
 =================
@@ -505,7 +558,7 @@ requires intimate knowledge of the executable format and the memory map
 of the process.) Only one of these modules is actually used; this is
 chosen by `configure'.
 
-     crt0.c
+     ecrt0.c
      lastfile.c
      pre-crt0.c
 
@@ -616,11 +669,6 @@ checks during code development.  This system is not currently used;
 instead the simpler `assert()' macro is used along with the various
 checks provided by the `--error-check-*' configuration options.
 
-     prefix-args.c
-
-   This is actually the source for a small, self-contained program used
-during building.
-
      universe.h
 
    This is not currently used.
@@ -631,7 +679,6 @@ File: internals.info,  Node: Basic Lisp Modules,  Next: Modules for Standard Edi
 Basic Lisp Modules
 ==================
 
-     emacsfns.h
      lisp-disunion.h
      lisp-union.h
      lisp.h
@@ -674,8 +721,6 @@ special-purpose argument types requiring definitions not in `lisp.h'.)
 All initialization functions are prototyped in `symsinit.h'.
 
      alloc.c
-     pure.c
-     puresize.h
 
    The large module `alloc.c' implements all of the basic allocation and
 garbage collection for Lisp objects.  The most commonly used Lisp
@@ -700,33 +745,6 @@ require changes to the generic subsystem code or affect any of the other
 subtypes in the subsystem; this provides a great deal of robustness to
 the XEmacs code.
 
-   `pure.c' contains the declaration of the "purespace" array.  Pure
-space is a hack used to place some constant Lisp data into the code
-segment of the XEmacs executable, even though the data needs to be
-initialized through function calls.  (See above in section VIII for more
-info about this.)  During startup, certain sorts of data is
-automatically copied into pure space, and other data is copied manually
-in some of the basic Lisp files by calling the function `purecopy',
-which copies the object if possible (this only works in temacs, of
-course) and returns the new object.  In particular, while temacs is
-executing, the Lisp reader automatically copies all compiled-function
-objects that it reads into pure space.  Since compiled-function objects
-are large, are never modified, and typically comprise the majority of
-the contents of a compiled-Lisp file, this works well.  While XEmacs is
-running, any attempt to modify an object that resides in pure space
-causes an error.  Objects in pure space are never garbage collected -
-almost all of the time, they're intended to be permanent, and in any
-case you can't write into pure space to set the mark bits.
-
-   `puresize.h' contains the declaration of the size of the pure space
-array.  This depends on the optional features that are compiled in, any
-extra purespace requested by the user at compile time, and certain other
-factors (e.g. 64-bit machines need more pure space because their Lisp
-objects are larger).  The smallest size that suffices should be used, so
-that there's no wasted space.  If there's not enough pure space, you
-will get an error during the build process, specifying how much more
-pure space is needed.
-
      eval.c
      backtrace.h
 
@@ -941,8 +959,12 @@ Editor-Level Control Flow Modules
 =================================
 
      event-Xt.c
+     event-msw.c
      event-stream.c
      event-tty.c
+     events-mod.h
+     gpmevent.c
+     gpmevent.h
      events.c
      events.h
 
@@ -987,9 +1009,9 @@ that associate event descriptions with functions to be called to
 "execute" those events; `dispatch-event' looks up events in the
 relevant keymaps.)
 
-     keyboard.c
+     cmdloop.c
 
-   `keyboard.c' contains functions that implement the actual editor
+   `cmdloop.c' contains functions that implement the actual editor
 command loop--i.e. the event loop that cyclically retrieves and
 dispatches events.  This code is also rather tricky, just like
 `event-stream.c'.
@@ -1020,13 +1042,27 @@ File: internals.info,  Node: Modules for the Basic Displayable Lisp Objects,  Ne
 Modules for the Basic Displayable Lisp Objects
 ==============================================
 
-     device-ns.h
-     device-stream.c
-     device-stream.h
+     console-msw.c
+     console-msw.h
+     console-stream.c
+     console-stream.h
+     console-tty.c
+     console-tty.h
+     console-x.c
+     console-x.h
+     console.c
+     console.h
+
+   These modules implement the "console" Lisp object type.  A console
+contains multiple display devices, but only one keyboard and mouse.
+Most of the time, a console will contain exactly one device.
+
+   Consoles are the top of a lisp object inclusion hierarchy.  Consoles
+contain devices, which contain frames, which contain windows.
+
+     device-msw.c
      device-tty.c
-     device-tty.h
      device-x.c
-     device-x.h
      device.c
      device.h
 
@@ -1043,10 +1079,9 @@ menubar, scrollbar, toolbar, and other displayable-object subsystems.
 The reason for this is that all of these subsystems have the same
 subtypes (X, TTY, NeXTstep, Microsoft Windows, etc.) as devices do.
 
-     frame-ns.h
+     frame-msw.c
      frame-tty.c
      frame-x.c
-     frame-x.h
      frame.c
      frame.h
 
@@ -1087,13 +1122,17 @@ Modules for other Display-Related Lisp Objects
      faces.h
 
      bitmaps.h
-     glyphs-ns.h
+     glyphs-eimage.c
+     glyphs-msw.c
+     glyphs-msw.h
+     glyphs-widget.c
      glyphs-x.c
      glyphs-x.h
      glyphs.c
      glyphs.h
 
-     objects-ns.h
+     objects-msw.c
+     objects-msw.h
      objects-tty.c
      objects-tty.h
      objects-x.c
@@ -1101,14 +1140,20 @@ Modules for other Display-Related Lisp Objects
      objects.c
      objects.h
 
+     menubar-msw.c
+     menubar-msw.h
      menubar-x.c
      menubar.c
+     menubar.h
 
+     scrollbar-msw.c
+     scrollbar-msw.h
      scrollbar-x.c
      scrollbar-x.h
      scrollbar.c
      scrollbar.h
 
+     toolbar-msw.c
      toolbar-x.c
      toolbar.c
      toolbar.h
@@ -1126,6 +1171,7 @@ this is fast.
      gifalloc.c
 
    These modules decode GIF-format image files, for use with glyphs.
+These files were removed due to Unisys patent infringement concerns.
 
 \1f
 File: internals.info,  Node: Modules for the Redisplay Mechanism,  Next: Modules for Interfacing with the File System,  Prev: Modules for other Display-Related Lisp Objects,  Up: A Summary of the Various XEmacs Modules
@@ -1134,6 +1180,7 @@ Modules for the Redisplay Mechanism
 ===================================
 
      redisplay-output.c
+     redisplay-msw.c
      redisplay-tty.c
      redisplay-x.c
      redisplay.c