(M-08360): Separate C3-407E; add mappings for U-0002F87E.

[chise/xemacs-chise.git] / info / emodules.info

diff --git a/info/emodules.info b/info/emodules.info
index 9b95d11..15eb210 100644 (file)
--- a/info/emodules.info
+++ b/info/emodules.info
@@ -1,4 +1,4 @@
-This is ../info/emodules.info, produced by makeinfo version 4.0 from
+This is ../info/emodules.info, produced by makeinfo version 4.0b from

 emodules.texi.
 
    This file documents the module loading technology of XEmacs.
 emodules.texi.
 
    This file documents the module loading technology of XEmacs.

@@ -41,7 +41,7 @@ support documentation.
 * Menu:
 
 * Introduction::                Introducing Emacs Modules
 * Menu:
 
 * Introduction::                Introducing Emacs Modules

-* Annatomy of a Module::        Basic module layout and technology
+* Anatomy of a Module::         Basic module layout and technology

 * Using ellcc::                 How to use the module compiler
 * Defining Functions::          Creating new Lisp primitives
 * Defining Variables::          Creating new Lisp variables
 * Using ellcc::                 How to use the module compiler
 * Defining Functions::          Creating new Lisp primitives
 * Defining Variables::          Creating new Lisp variables

@@ -49,12 +49,12 @@ support documentation.
 
  --- The Detailed Node Listing ---
 
 
  --- The Detailed Node Listing ---
 

-Annatomy of a Module
+Anatomy of a Module

 
 * Required Header File::        Always include <emodules.h>
 * Required Functions::          Functions you must always provide
 * Required Variables::          Variables whose values you must provide
 
 * Required Header File::        Always include <emodules.h>
 * Required Functions::          Functions you must always provide
 * Required Variables::          Variables whose values you must provide

-* Loading other Modules::       How to load dependant modules
+* Loading other Modules::       How to load dependent modules

 
 Using `ellcc'
 
 
 Using `ellcc'
 

@@ -70,7 +70,7 @@ Defining Functions
 * Declaring Functions::         Declaring functions to the Lisp reader
 
 \1f
 * Declaring Functions::         Declaring functions to the Lisp reader
 
 \1f

-File: emodules.info,  Node: Introduction,  Next: Annatomy of a Module,  Prev: Top,  Up: Top
+File: emodules.info,  Node: Introduction,  Next: Anatomy of a Module,  Prev: Top,  Up: Top

 
 Introduction
 ************
 
 Introduction
 ************

@@ -84,7 +84,7 @@ ways than you can imagine, it does have its short-comings.
    Firstly, Elisp is an interpreted language, and this has serious speed
 implications.  Like all other interpreted languages (like Java), Elisp
 is often suitable only for certain types of application or extension.
    Firstly, Elisp is an interpreted language, and this has serious speed
 implications.  Like all other interpreted languages (like Java), Elisp
 is often suitable only for certain types of application or extension.

-So although Elisp is a general purpose language, and very ligh level,
+So although Elisp is a general purpose language, and very high level,

 there are times when it is desirable to descend to a lower level
 compiled language for speed purposes.
 
 there are times when it is desirable to descend to a lower level
 compiled language for speed purposes.
 

@@ -95,8 +95,8 @@ suited to a wider range of applications, especially those that require
 low level access to a system or need to be as quick as possible.
 
    This manual describes a new way of extending XEmacs, by using dynamic
 low level access to a system or need to be as quick as possible.
 
    This manual describes a new way of extending XEmacs, by using dynamic

-loadable modules (also knows as dynamicaly loadable libraries (DLLs),
-dynamic shared objects (DSOs) or just simply shared objectcs), which can
+loadable modules (also known as dynamically loadable libraries (DLLs),
+dynamic shared objects (DSOs) or just simply shared objects), which can

 be written in C or C++ and loaded into XEmacs at any time.  I sometimes
 refer to this technology as "CEmacs", which is short for "C Extensible
 Emacs".
 be written in C or C++ and loaded into XEmacs at any time.  I sometimes
 refer to this technology as "CEmacs", which is short for "C Extensible
 Emacs".

@@ -121,7 +121,7 @@ perspective though, a lot more is provided.
      XEmacs.
 
    *   CEmacs also makes all of the relevant XEmacs internal header
      XEmacs.
 
    *   CEmacs also makes all of the relevant XEmacs internal header

-     files availible for module authors to use.  This is often required
+     files available for module authors to use.  This is often required

      to get data structure definitions and external variable
      declarations.  The header files installed include the module
      specific header file `emodules.h'.  Due to the nature of dynamic
      to get data structure definitions and external variable
      declarations.  The header files installed include the module
      specific header file `emodules.h'.  Due to the nature of dynamic

@@ -154,13 +154,13 @@ deal to look at the actual XEmacs source code to see how things are
 done.
 
 \1f
 done.
 
 \1f

-File: emodules.info,  Node: Annatomy of a Module,  Next: Using ellcc,  Prev: Introduction,  Up: Top
+File: emodules.info,  Node: Anatomy of a Module,  Next: Using ellcc,  Prev: Introduction,  Up: Top

 
 

-Annatomy of a Module
-********************
+Anatomy of a Module
+*******************

 
 

-   Each dynamically loadable XEmacs extension (hereafter refered to as a
-module) has a certain compulsory format, and must contain several
+   Each dynamically loadable XEmacs extension (hereafter referred to as
+a module) has a certain compulsory format, and must contain several

 pieces of information and several mandatory functions.  This chapter
 describes the basic layout of a module, and provides a very simple
 sample.  The source for this sample can be found in the file
 pieces of information and several mandatory functions.  This chapter
 describes the basic layout of a module, and provides a very simple
 sample.  The source for this sample can be found in the file

@@ -171,10 +171,10 @@ sample.  The source for this sample can be found in the file
 * Required Header File::        Always include <emodules.h>
 * Required Functions::          Functions you must always provide
 * Required Variables::          Variables whose values you must provide
 * Required Header File::        Always include <emodules.h>
 * Required Functions::          Functions you must always provide
 * Required Variables::          Variables whose values you must provide

-* Loading other Modules::       How to load dependant modules
+* Loading other Modules::       How to load dependent modules

 
 \1f
 
 \1f

-File: emodules.info,  Node: Required Header File,  Next: Required Functions,  Prev: Annatomy of a Module,  Up: Annatomy of a Module
+File: emodules.info,  Node: Required Header File,  Next: Required Functions,  Prev: Anatomy of a Module,  Up: Anatomy of a Module

 
 Required Header File
 ====================
 
 Required Header File
 ====================

@@ -200,7 +200,7 @@ files included are:
      variable declarations.
 
 `sysdep.h'
      variable declarations.
 
 `sysdep.h'

-     All system dependant declarations and abstraction macros live
+     All system dependent declarations and abstraction macros live

      here.  You should never call low level system functions directly.
      Rather, you should use the abstraction macros provided in this
      header file.
      here.  You should never call low level system functions directly.
      Rather, you should use the abstraction macros provided in this
      header file.

@@ -223,14 +223,14 @@ files included are:
      manipulating XEmacs frames.
 
 \1f
      manipulating XEmacs frames.
 
 \1f

-File: emodules.info,  Node: Required Functions,  Next: Required Variables,  Prev: Required Header File,  Up: Annatomy of a Module
+File: emodules.info,  Node: Required Functions,  Next: Required Variables,  Prev: Required Header File,  Up: Anatomy of a Module

 
 Required Functions
 ==================
 
    Every module requires several initialization functions.  It is the
 
 Required Functions
 ==================
 
    Every module requires several initialization functions.  It is the

-responsibility of these functions to load in any dependant modules, and
-to declare all variables and functions which are to be made visibile to
+responsibility of these functions to load in any dependent modules, and
+to declare all variables and functions which are to be made visible to

 the XEmacs Lisp reader.  Each of these functions performs a very
 specific task, and they are executed in the correct order by XEmacs.
 All of these functions are `void' functions which take no arguments.
 the XEmacs Lisp reader.  Each of these functions performs a very
 specific task, and they are executed in the correct order by XEmacs.
 All of these functions are `void' functions which take no arguments.

@@ -252,7 +252,14 @@ place-holder, not an actual function name.
      `DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to
      declare and initialize all and any variables that your module
      defines.  They syntax for declaring variables is identical to the
      `DEFVAR_LISP()', `DEFVAR_BOOL()' etc, and its purpose is to
      declare and initialize all and any variables that your module
      defines.  They syntax for declaring variables is identical to the

-     syntax used for all internal XEmacs source code.
+     syntax used for all internal XEmacs source code.  If the module is
+     intended to be usable statically linked into XEmacs, the actions
+     of this function are severely restricted.  *Note General Coding
+     Rules: (internals)General Coding Rules.  Also see the comments in
+     `src/emacs.c' (`main_1').  Modules which perform initializations
+     not permitted by these rules will probably work, but dual-use
+     (dynamic loading and static linking) modules will require very
+     careful, and possibly fragile, coding.

 
 `modules_of_module'
      This optional function should be used to load in any modules which
 
 `modules_of_module'
      This optional function should be used to load in any modules which

@@ -268,7 +275,7 @@ place-holder, not an actual function name.
      functions and variables declared in your module.
 
 \1f
      functions and variables declared in your module.
 
 \1f

-File: emodules.info,  Node: Required Variables,  Next: Loading other Modules,  Prev: Required Functions,  Up: Annatomy of a Module
+File: emodules.info,  Node: Required Variables,  Next: Loading other Modules,  Prev: Required Functions,  Up: Anatomy of a Module

 
 Required Variables
 ==================
 
 Required Variables
 ==================

@@ -296,7 +303,7 @@ discussed here simply for the sake of completeness.
      This is a short (typically 10 characters or less) name for the
      module, and it is used as a suffix for all of the required
      functions.  This is also the name by which the module is
      This is a short (typically 10 characters or less) name for the
      module, and it is used as a suffix for all of the required
      functions.  This is also the name by which the module is

-     recognised when loading dependant modules.  The name does not
+     recognized when loading dependent modules.  The name does not

      necessarily have to be the same as the physical file name,
      although keeping the two names in sync is a pretty good idea.  The
      name must not be empty, and it must be a valid part of a C
      necessarily have to be the same as the physical file name,
      although keeping the two names in sync is a pretty good idea.  The
      name must not be empty, and it must be a valid part of a C

@@ -322,7 +329,7 @@ discussed here simply for the sake of completeness.
      module.  The value is set by the `--mod-title' argument to `ellcc'.
 
 \1f
      module.  The value is set by the `--mod-title' argument to `ellcc'.
 
 \1f

-File: emodules.info,  Node: Loading other Modules,  Prev: Required Variables,  Up: Annatomy of a Module
+File: emodules.info,  Node: Loading other Modules,  Prev: Required Variables,  Up: Anatomy of a Module

 
 Loading other Modules
 =====================
 
 Loading other Modules
 =====================

@@ -331,12 +338,12 @@ Loading other Modules
 function `modules_of_module' to load in any modules which the current
 module depends on.  If the module is stand-alone, and does not depend
 on other modules, then this function can be left empty or even
 function `modules_of_module' to load in any modules which the current
 module depends on.  If the module is stand-alone, and does not depend
 on other modules, then this function can be left empty or even

-undeclared.  However, if it does have dependnacies, it must call
+undeclared.  However, if it does have dependencies, it must call

 `emodules_load':
 
 `emodules_load':
 

-     int emodules_load (CONST char *module,
-                        CONST char *modname,
-                        CONST char *modver)
+     int emodules_load (const char *module,
+                        const char *modname,
+                        const char *modver)

 
    The first argument MODULE is the name of the actual shared object or
 DLL.  You can omit the `.so', `.ell' or `.dll' extension of you wish.
 
    The first argument MODULE is the name of the actual shared object or
 DLL.  You can omit the `.so', `.ell' or `.dll' extension of you wish.

@@ -365,7 +372,7 @@ their parents will also fail to load.  This does not include previous
 successful calls to `emodules_load' at the top level.
 
 \1f
 successful calls to `emodules_load' at the top level.
 
 \1f

-File: emodules.info,  Node: Using ellcc,  Next: Defining Functions,  Prev: Annatomy of a Module,  Up: Top
+File: emodules.info,  Node: Using ellcc,  Next: Defining Functions,  Prev: Anatomy of a Module,  Up: Top

 
 Using `ellcc'
 *************
 
 Using `ellcc'
 *************

@@ -462,8 +469,8 @@ trickery in the module loading code.  This is all done using the
    The result of running `ellcc' in initialization mode is a C source
 file which you compile with (you guessed it) `ellcc' in compile mode.
 Initialization mode is where you set the module name, version, title
    The result of running `ellcc' in initialization mode is a C source
 file which you compile with (you guessed it) `ellcc' in compile mode.
 Initialization mode is where you set the module name, version, title

-and gather together all of the documentaion strings for the functions
-and vairables in your module.  There are several options that you are
+and gather together all of the documentation strings for the functions
+and variables in your module.  There are several options that you are

 required to pass `ellcc' in initialization mode, the first of which is
 the mode switch itself, `--mode=init'.
 
 required to pass `ellcc' in initialization mode, the first of which is
 the mode switch itself, `--mode=init'.
 

@@ -542,7 +549,7 @@ option.  This directory is treated the same way as the main module
 directory.  Each sub-directory within it is searched for a given module
 when the user attempts to load it.  The valid extensions that the
 loader attempts to use are `.so', `.ell' and `.dll'.  You can use any
 directory.  Each sub-directory within it is searched for a given module
 when the user attempts to load it.  The valid extensions that the
 loader attempts to use are `.so', `.ell' and `.dll'.  You can use any

-of these extensions, although `.ell' is the prefered extension.
+of these extensions, although `.ell' is the preferred extension.

 
 \1f
 File: emodules.info,  Node: Link Mode,  Next: Other ellcc options,  Prev: Initialization Mode,  Up: Using ellcc
 
 \1f
 File: emodules.info,  Node: Link Mode,  Next: Other ellcc options,  Prev: Initialization Mode,  Up: Using ellcc

@@ -551,10 +558,10 @@ Link Mode
 =========
 
    Once all of your source code files have been compiled (including the
 =========
 
    Once all of your source code files have been compiled (including the

-generated init file) you need to link them all together to created the
+generated init file) you need to link them all together to create the

 loadable module.  To do this, you invoke `ellcc' in link mode, by
 loadable module.  To do this, you invoke `ellcc' in link mode, by

-pasing the `--mode-link' command.  You need to specify the final output
-file using the `--mod-output=NAME' command, but other than that all
+passing the `--mode=link' option.  You need to specify the final output
+file using the `--mod-output=NAME' option, but other than that all

 other arguments are passed on directly to the system compiler or
 linker, along with any other required arguments to create the loadable
 module.
 other arguments are passed on directly to the system compiler or
 linker, along with any other required arguments to create the loadable
 module.

@@ -599,8 +606,8 @@ variables.  Here is the complete list of options that `ellcc' accepts.
      is displayed.
 
 `--mod-name=NAME'
      is displayed.
 
 `--mod-name=NAME'

-     Sets the short internaml module NAME to the string specified,
-     which must consist only of valid C identifiers.  Required during
+     Sets the short internal module NAME to the string specified, which
+     must consist only of valid C identifiers.  Required during

      initialization mode.
 
 `--mod-version=VERSION'
      initialization mode.
 
 `--mod-version=VERSION'

@@ -629,8 +636,8 @@ variables.  Here is the complete list of options that `ellcc' accepts.
      exit.
 
 `--mod-archdir'
      exit.
 
 `--mod-archdir'

-     Prints the name of the root of the architecture-dependant
-     directory that XEmacs searches for architecture-dependant files.
+     Prints the name of the root of the architecture-dependent
+     directory that XEmacs searches for architecture-dependent files.

 
 `--mod-config'
      Prints the name of the configuration for which XEmacs and `ellcc'
 
 `--mod-config'
      Prints the name of the configuration for which XEmacs and `ellcc'

@@ -647,7 +654,7 @@ flags that were determined at the time XEmacs was configured.  In
 certain rare circumstances you may wish to over-ride the flags passed to
 the compiler or linker, and you can do so using environment variables.
 The table below lists all of the environment variables that `ellcc'
 certain rare circumstances you may wish to over-ride the flags passed to
 the compiler or linker, and you can do so using environment variables.
 The table below lists all of the environment variables that `ellcc'

-recognises.
+recognizes.

 
 `ELLCC'
      This is used to over-ride the name of the C compiler that is
 
 `ELLCC'
      This is used to over-ride the name of the C compiler that is

@@ -737,7 +744,7 @@ module.  This is done using the `DEFUN' macro.  Here is a small example:
      DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
      Sample Emacs primitive function.
      
      DEFUN ("my-function", Fmy_function, 1, 1, "FFile name: ", /*
      Sample Emacs primitive function.
      

-     The specified FILE is frobricated before it is fnozzled.
+     The specified FILE is frobnicated before it is fnozzled.

      */
          (file))
      {
      */
          (file))
      {

@@ -773,7 +780,7 @@ Declaring Functions
 ===================
 
    Simply writing the code for a function is not enough to make it
 ===================
 
    Simply writing the code for a function is not enough to make it

-availible to the Lisp reader.  You have to, during module
+available to the Lisp reader.  You have to, during module

 initialization, let the Lisp reader know about the new function.  This
 is done by calling `DEFSUBR' with the name of the function.  This is
 the sole purpose of the initialization function `syms_of_module'.
 initialization, let the Lisp reader know about the new function.  This
 is done by calling `DEFSUBR' with the name of the function.  This is
 the sole purpose of the initialization function `syms_of_module'.

@@ -805,7 +812,7 @@ Defining Variables
 
    Rarely will you write a module that only contains functions.  It is
 common to also provide variables which can be used to control the
 
    Rarely will you write a module that only contains functions.  It is
 common to also provide variables which can be used to control the

-behaviour of the function, or store the results of the function being
+behavior of the function, or store the results of the function being

 executed.  The actual C variable types are the same for modules and
 internal XEmacs primitives, and the declaration of the variables is
 identical.
 executed.  The actual C variable types are the same for modules and
 internal XEmacs primitives, and the declaration of the variables is
 identical.

@@ -823,7 +830,7 @@ internals manual.
    One _very_ important difference between XEmacs variables and module
 variables is how you use pure space.  Simply put, you *never* use pure
 space in XEmacs modules.  The pure space storage is of a limited size,
    One _very_ important difference between XEmacs variables and module
 variables is how you use pure space.  Simply put, you *never* use pure
 space in XEmacs modules.  The pure space storage is of a limited size,

-and is initialized propperly during the dumping of XEmacs.  Because
+and is initialized properly during the dumping of XEmacs.  Because

 variables are being added dynamically to an already running XEmacs when
 you load a module, you cannot use pure space.  Be warned: *do not use
 pure space in modules.  Repeat, do not use pure space in modules.*
 variables are being added dynamically to an already running XEmacs when
 you load a module, you cannot use pure space.  Be warned: *do not use
 pure space in modules.  Repeat, do not use pure space in modules.*

@@ -862,7 +869,7 @@ Index
 
 * Menu:
 
 
 * Menu:
 

-* annatomy:                              Annatomy of a Module.
+* anatomy:                               Anatomy of a Module.

 * compiler:                              Introduction.
 * compiling:                             Compile Mode.
 * config.h:                              Required Header File.
 * compiler:                              Introduction.
 * compiling:                             Compile Mode.
 * config.h:                              Required Header File.

@@ -874,7 +881,7 @@ Index
 * DEFVAR_BOOL:                           Defining Variables.
 * DEFVAR_INT:                            Defining Variables.
 * DEFVAR_LISP:                           Defining Variables.
 * DEFVAR_BOOL:                           Defining Variables.
 * DEFVAR_INT:                            Defining Variables.
 * DEFVAR_LISP:                           Defining Variables.

-* dependancies:                          Loading other Modules.
+* dependencies:                          Loading other Modules.

 * DLL:                                   Introduction.
 * docs_of_module:                        Required Functions.
 * documentation <1>:                     Initialization Mode.
 * DLL:                                   Introduction.
 * docs_of_module:                        Required Functions.
 * documentation <1>:                     Initialization Mode.

@@ -893,7 +900,7 @@ Index
 * emodules.h:                            Required Header File.
 * emodules_load:                         Loading other Modules.
 * environment variables:                 Environment Variables.
 * emodules.h:                            Required Header File.
 * emodules_load:                         Loading other Modules.
 * environment variables:                 Environment Variables.

-* format, module:                        Annatomy of a Module.
+* format, module:                        Anatomy of a Module.

 * functions, declaring:                  Declaring Functions.
 * functions, defining:                   Using DEFUN.
 * functions, Lisp:                       Using DEFUN.
 * functions, declaring:                  Declaring Functions.
 * functions, defining:                   Using DEFUN.
 * functions, Lisp:                       Using DEFUN.

@@ -907,8 +914,8 @@ Index
 * linker:                                Introduction.
 * linking:                               Link Mode.
 * module compiler:                       Using ellcc.
 * linker:                                Introduction.
 * linking:                               Link Mode.
 * module compiler:                       Using ellcc.

-* module format:                         Annatomy of a Module.
-* module skeleton:                       Annatomy of a Module.
+* module format:                         Anatomy of a Module.
+* module skeleton:                       Anatomy of a Module.

 * modules_of_module <1>:                 Loading other Modules.
 * modules_of_module:                     Required Functions.
 * objects, defining:                     Defining Variables.
 * modules_of_module <1>:                 Loading other Modules.
 * modules_of_module:                     Required Functions.
 * objects, defining:                     Defining Variables.

@@ -919,7 +926,7 @@ Index
 * required variables:                    Required Variables.
 * samples:                               Introduction.
 * shared object:                         Introduction.
 * required variables:                    Required Variables.
 * samples:                               Introduction.
 * shared object:                         Introduction.

-* skeleton, module:                      Annatomy of a Module.
+* skeleton, module:                      Anatomy of a Module.

 * subrs:                                 Using DEFUN.
 * syms_of_module:                        Required Functions.
 * variables, defining:                   Defining Variables.
 * subrs:                                 Using DEFUN.
 * syms_of_module:                        Required Functions.
 * variables, defining:                   Defining Variables.

@@ -930,23 +937,23 @@ Index
 
 \1f
 Tag Table:
 
 \1f
 Tag Table:

-Node: Top\7f1536
+Node: Top\7f1537

 Node: Introduction\7f2884
 Node: Introduction\7f2884

-Node: Annatomy of a Module\7f7393
-Node: Required Header File\7f8209
-Node: Required Functions\7f10130
-Node: Required Variables\7f12379
-Node: Loading other Modules\7f15066
-Node: Using ellcc\7f17124
-Node: Compile Mode\7f18919
-Node: Initialization Mode\7f20287
-Node: Link Mode\7f25319
-Node: Other ellcc options\7f26466
-Node: Environment Variables\7f29046
-Node: Defining Functions\7f30737
-Node: Using DEFUN\7f32748
-Node: Declaring Functions\7f34459
-Node: Defining Variables\7f35802
-Node: Index\7f38047
+Node: Anatomy of a Module\7f7392
+Node: Required Header File\7f8206
+Node: Required Functions\7f10125
+Node: Required Variables\7f12849
+Node: Loading other Modules\7f15535
+Node: Using ellcc\7f17592
+Node: Compile Mode\7f19386
+Node: Initialization Mode\7f20754
+Node: Link Mode\7f25788
+Node: Other ellcc options\7f26933
+Node: Environment Variables\7f29512
+Node: Defining Functions\7f31203
+Node: Using DEFUN\7f33214
+Node: Declaring Functions\7f34925
+Node: Defining Variables\7f36268
+Node: Index\7f38511

 \1f
 End Tag Table
 \1f
 End Tag Table