Module documentation
Stephen J. Turnbull
stephen at xemacs.org
Mon Feb 23 01:01:48 EST 2004
>>>>> "Jerry" == Jerry James <james at xemacs.org> writes:
Jerry> I am embarrassed to admit how long this has been sitting on
Jerry> my TODO list.
Heh. You don't know how much better this makes _me_ feel. ;-)
Jerry> What I have so far is here:
Jerry> http://www.ittc.ku.edu/~james/emodules.texi (about 100KB).
Nice work! Feel free to take a hack at some of the other undocumented
stuff in Internals. :-)
At 100KB, feel free to attach the whole file. Send it to -patches if
you're worried about straining people's mailboxes. (Kyle used to send
audio clips rather than use "frownies" to express disapproval, but
that was considered a waste of bandwidth, to give you some idea of
what the limits are ... boy, I miss Kyle!)
Jerry> my awful texinfo
Wasn't too bad, really.
Here's a ChangeLog describing in detail suggestions I have, and a
patch against the URL above. I can easily do partial patches
corresponding to each log if you like, but I think most of my
suggestions are non-controversial. NB Some of my choices were pretty
arbitrary, like the specific @settitle. I do think they should be
consistent but I'm not wedded to my choice. NB The ChangeLog is just
to document in some detail what I did for your information. Don't
bother with putting that junk into the eventual ChangeLog.
Regarding overall organization, I would (and did) get rid of the
parametrization on Emacsen. ELLs are technically and politically
unlikely to be ported to GNU Emacs. (The internals are different, for
example DEFUN is implemented differently. And rms believes that DSOs
encourage inadvertant violations of the GPL.)
My feeling is that maybe most of the function and variable
descriptions should be replaced by a generic description of C calling
conventions for Lisp-callable functions, and bare prototypes for
functions and declarations for variables. I have not done that, but I
have added a couple lines about function calling conventions. Then
point to the Lisp Reference and Internals Manual. It's probably also
worth reiterating some of the basics of Lisp_Object representation,
including the tags, the immediate representations, and lrecords.
Especially we need to explain about lrecords properly being registered
in the type table.
Also, having the stuff about ellcc immediately follow the introduction
left me kind of cold. I don't really want to know that much about
ellcc at that point, I want to know what modules can do for me, and
what they can't, and how they do what they do.
We need a section about using C++. If you build XEmacs with g++,
could we use the STL etc in a module? I assume so. OTOH, you can't
link a module built with C++ to an XEmacs built with C or vice versa,
right? I guess it can be quite brief, as for "Clean C" ellcc will
actually take care of all that behind the scenes, right? While C++
programmers are presumably used to the issues.
2004-02-23 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Module Interface):
Remove FIXME for syntactic variables.
Fix the syntactic variables.
Describe C calling conventions for Lisp briefly.
Document featurep.
Quote `char *' with @samp, not double quotes.
alloca and malloc don't "convert text," they allocate storage.
Note that XEmacs defines its own abort and assert macros.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Module Interface):
Add FIXME for syntactic variables in @section Lisp.
Deprecate EQ in favor of EQ_WITH_EBOLA_NOTICE.
Give correct explanation of Lisp defconst for DEFVAR_CONST_LISP,
DEFVAR_CONST_INT, and DEFVAR_CONST_BOOL.
Fix many misuses of @code.
Note that QUIT can GC.
Note that intern can create a symbol.
Differentiate between GCPRO and staticpro.
Xref GCPROing in Internals Manual.
Fix typos.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Introduction): Improve descriptions of ellcc and
sample modules.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Anatomy of a Module): Fix typo in name of
`sample' directory.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi: Replace @value{emacs} with XEmacs throughout.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (title, Introduction): Make titles and text refer
to "C and C++ modules" consistently.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Introduction): Remove references to CEmacs.
2004-02-22 Stephen J. Turnbull <stephen at xemacs.org>
* emodules.texi (Permissions): Remove references to FSF and GPL.
--- ../emodules.texi 2004-02-22 19:08:03.000000000 +0900
+++ ./emodules.texi 2004-02-23 14:28:50.000000000 +0900
@@ -2,7 +2,7 @@
@c %**start of header
@setfilename ../info/emodules.info
- at settitle Extending Emacs using C Modules
+ at settitle Extending Emacs Using C and C++ Modules
@direntry
* Emodules: (emodules). XEmacs dynamically loadable module support.
@end direntry
@@ -10,30 +10,8 @@
@c paragraphindent 2
@c %**end of header
- at c
- at c Use some macros so that we can format for either XEmacs
- at c or (shudder) GNU Emacs.
- at c
-
- at ifset XEMACS
- at set emacs XEmacs
- at clear EMACS
- at set HAVE-EMACS
- at end ifset
-
- at ifset EMACS
- at set emacs Emacs
- at clear XEMACS
- at set HAVE-EMACS
- at end ifset
-
- at ifclear HAVE-EMACS
- at set XEMACS
- at set emacs XEmacs
- at end ifclear
-
@ifinfo
-This file documents the module loading technology of @value{emacs}.
+This file documents the module loading technology of XEmacs.
Copyright @copyright{} 1998 J. Kean Johnston.
Copyright @copyright{} 2003 Jerry James.
@@ -81,7 +59,7 @@
@finalout
@titlepage
- at title Extending @value{emacs} using C and C++
+ at title Extending XEmacs Using C and C++ Modules
@subtitle Version 1.1, August 2003
@author J. Kean Johnston
@@ -118,7 +96,7 @@
@ifinfo
@node Top, Introduction, (dir), (dir)
-This Info file contains v1.1 of the @value{emacs} dynamically loadable
+This Info file contains v1.1 of the XEmacs dynamically loadable
module support documentation.
@menu
* Introduction:: Introducing Emacs Modules
@@ -126,7 +104,7 @@
* Using ellcc:: How to use the module compiler
* Defining Functions:: Creating new Lisp primitives
* Defining Variables:: Creating new Lisp variables
-* Module Interface:: @value{emacs} internals visible to modules
+* Module Interface:: XEmacs internals visible to modules
* Concept Index:: Index of module concepts
* Function Index:: Index of interface funcs, vars, and types
@@ -164,10 +142,10 @@
@node Introduction, Anatomy of a Module, Top, Top
@chapter Introduction
- @value{emacs} is a powerful, extensible editor. The traditional way of
-extending the functionality of @value{emacs} is to use its built-in Lisp
+ XEmacs is a powerful, extensible editor. The traditional way of
+extending the functionality of XEmacs is to use its built-in Lisp
language (called Emacs Lisp, or Elisp for short). However, while Elisp
-is a full programming language and capable of extending @value{emacs} in more
+is a full programming language and capable of extending XEmacs in more
ways than you can imagine, it does have its shortcomings.
Firstly, Elisp is an interpreted language, and this has serious speed
@@ -192,38 +170,40 @@
@cindex DLL
@cindex DSO
@cindex shared object
- This manual describes a new way of extending @value{emacs}, by using
+ This manual describes a new way of extending XEmacs, by using
dynamically 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 @value{emacs}
+objects), which can be written in C or C++ and loaded into XEmacs
at any time.
- @value{emacs} modules are configured into and installed with @value{emacs} by
+ XEmacs modules are configured into and installed with XEmacs by
default on all systems that support loading of shared objects. From a
-users perspective, the internals of @value{emacs} modules are irrelevant.
+users perspective, the internals of XEmacs modules are irrelevant.
All a user will ever need to know about shared objects is the name of
the shared object when they want to load a given module. From a
-developer's perspective though, a lot more is provided.
+developer's perspective, though, a lot more is provided.
@itemize @bullet
@item
@pindex ellcc
@cindex compiler
@cindex linker
- Of primary interest is the @code{ellcc} program. This program is
-created during compile time, and is intended to abstract compiler
+ A central feature of the implementation is the @code{ellcc} program.
+This program is automatically generated when XEmacs itself is built.
+It is designed to abstract compiler
specific characteristics from the developer. This program is called to
compile and link all objects that will make up the final shared object,
and accepts all common C compiler flags. @code{ellcc} also sets up the
correct environment for compiling modules by enabling any special
compiler modes (such as PIC mode), setting the correct include paths for
-the location of @value{emacs} internal header files, etc. The program
+the location of XEmacs internal header files, etc. The program
will also invoke the linker correctly to create the final shared object
-which is loaded into @value{emacs}.
+which is loaded into XEmacs. Its final function is to take care of
+extracting on-line documentation, which needs to be treated specially.
@item
@cindex header files
- All of the relevant @value{emacs} internal header
+ All of the relevant XEmacs internal header
files are 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
@@ -236,18 +216,19 @@
migrate to Lisp at some future time will not be exported. Note that we
already limit the exposure of XEmacs internals on Windows platforms, and
will probably do so on ELF platforms in the near future.
- at xref{Top,,,internals, at value{emacs} Internals Manual}, for a more
-complete discussion on how to extend and understand @value{emacs}. All
+ at xref{Top,,,internals,XEmacs Internals Manual}, for a more
+complete discussion on how to extend and understand XEmacs. All
of the rules for C modules are discussed there.
@item
@cindex samples
- Part of the @value{emacs} distribution is a set of modules. On
+ Part of the XEmacs distribution is a set of modules. On
systems that support module building, some of these modules are
installed by default. Others are sample modules, and are neither built
-nor installed, but remain in the @value{emacs} source tree.
-These modules live in the directory @file{modules}, which is a
-subdirectory of the main @value{emacs} source code directory. Please
+nor installed, but remain in the XEmacs source tree.
+The modules distributed with XEmacs
+live in the directory @file{modules}, which is a
+subdirectory of the top XEmacs source code directory. Please
look at the existing modules, and especially the samples, carefully and
use them as a basis for making your own modules. Most of the concepts
required for writing extension modules are covered in the existing
@@ -256,20 +237,21 @@
@item
@cindex documentation
@cindex help
- Last, but not least is this manual. This can be viewed from within
- at value{emacs}, and it can be printed out as well. It is the intention of this
+ Last, but not least, is this manual. This can be viewed from within
+XEmacs, and it can be printed out as well. It is the intention of this
document that it will describe everything you need to know about
-extending @value{emacs} in C. If you do not find this to be the case, please
-contact the author(s).
+extending XEmacs in C or C++. If you do not find this to be the
+case, please contact the author(s), or use @kbd{M-x report-xemacs-bug}
+to inform the XEmacs Development Team.
@end itemize
The rest of this document will discuss the actual mechanics of
- at value{emacs} modules and work through several of the samples. Please be
-sure that you have read the @value{emacs} Internals Manual and understand
+XEmacs modules and work through several of the samples. Please be
+sure that you have read the XEmacs Internals Manual and understand
everything in it. The concepts there apply to all modules. This
-document may have some overlap, but it is the internals manual which
+document may have some overlap, but it is the Internals Manual which
should be considered the final authority. It will also help a great
-deal to look at the actual @value{emacs} source code to see how things are
+deal to look at the actual XEmacs source code to see how things are
done.
@node Anatomy of a Module, Using ellcc, Introduction, Top
@@ -280,12 +262,12 @@
@cindex module format
@cindex format, module
- Each dynamically loadable @value{emacs} extension (hereafter referred to as a
+ 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
- at file{modules/simple/sample.c} in the main @value{emacs} source code tree.
+ at file{modules/sample/sample.c} in the main XEmacs source code tree.
@menu
* Required Header File:: Always include <emodules.h>
@@ -302,7 +284,7 @@
@cindex emodules.h
@cindex config.h
Every module must include the file @file{<emodules.h>}. This
-will include several other @value{emacs} internal header files, and will set up
+will include several other XEmacs internal header files, and will set up
certain vital macros. One of the most important files included by
@file{emodules.h} is the generated @file{config.h} file, which contains
all of the required system abstraction macros and definitions. Most
@@ -311,9 +293,9 @@
familiarize yourself with the macros defined there.
Depending on exactly what your module will be doing, you will probably
-need to include one or more of the @value{emacs} internal header files. When
+need to include one or more of the XEmacs internal header files. When
you @code{#include <emodules.h>}, you will get a few of the most important
- at value{emacs} header files included automatically for you. The files included
+XEmacs header files included automatically for you. The files included
are:
@table @file
@@ -329,7 +311,7 @@
@item window.h
This header file defines the window structures and Lisp types, and
-provides functions and macros for manipulating multiple @value{emacs} windows.
+provides functions and macros for manipulating multiple XEmacs windows.
@item buffer.h
All macros and function declarations for manipulating internal and user
@@ -341,7 +323,7 @@
@item frame.h
Provides the required structure, macro and function definitions for
-manipulating @value{emacs} frames.
+manipulating XEmacs frames.
@end table
@node Required Functions, Required Variables, Required Header File, Anatomy of a Module
@@ -353,18 +335,18 @@
Every module requires several initialization functions. It is the
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
- at value{emacs} Lisp reader. Each of these functions performs a very specific
-task, and they are executed in the correct order by @value{emacs}. All of
+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 @code{void} functions which take no arguments.
Here, briefly, are the required module functions. Note that the actual
-function names do not end with the string @code{_module}, but rather
+function names do not end with the string @samp{_ at var{MODULE}}, but rather
they end with the abbreviated name by which the module is known. There
will be more on the module name and its importance later. Just bear in
-mind that the text @code{_module} in the functions below is simply a
+mind that the text @samp{_ at var{module}} in the functions below is simply a
place-holder, not an actual function name.
@table @code
- at item syms_of_module
+ at item syms_of_ at var{module}
@findex syms_of_module
This required function is responsible for introducing to the Lisp reader
all functions that you have defined in your module using @code{DEFUN()}.
@@ -374,40 +356,40 @@
@code{DEFKEYWORD()}, and all Lisp types defined by your module are
delcared here with @code{INIT_EXTERNAL_LRECORD_IMPLEMENTATION()}.
- at item vars_of_module
+ at item vars_of_ at var{module}
@findex vars_of_module
This required function contains calls to macros such as
@code{DEFVAR_LISP()}, @code{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 @value{emacs} source code. If the module is intended to be
+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. @xref{General Coding Rules,,,internals,
- at value{emacs} Internals Manual}. Also see the comments in
+XEmacs Internals Manual}. Also see the comments in
@file{src/emacs.c} (@code{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.
- at item modules_of_module
+ at item modules_of_ at var{module}
@findex modules_of_module
This optional function should be used to load in any modules which your
-module depends on. The @value{emacs} module loading code makes sure that the
+module depends on. The XEmacs module loading code makes sure that the
same module is not loaded twice, so several modules can safely call the
module load function for the same module. Only one copy of each module
(at a given version) will ever be loaded.
- at item docs_of_module
+ at item docs_of_ at var{module}
@findex docs_of_module
This is a required function, but not one which you need ever write.
This function is created automatically by @code{ellcc} when the module
initialization code is produced. It is required to document all
functions and variables declared in your module.
- at item unload_module
+ at item unload_ at var{module}
@findex unload_module
This optional function is used to clean up when a module is to be
-unloaded. @value{emacs} has a history mechanism by which it remembers
+unloaded. XEmacs has a history mechanism by which it remembers
the variables, functions, etc., declared by your module, so it can clean
those up on its own. However, any Lisp types declared by your module
must be cleaned up here with the @code{UNDEF_LRECORD_IMPLEMENTATION()}
@@ -432,14 +414,14 @@
@table @code
@item emodules_compiler
This is a variable of type @code{long}, and is used to indicate the
-version of the @value{emacs} loading technology that was used to produce the
+version of the XEmacs loading technology that was used to produce the
module being loaded. This version number is completely unrelated to
-the @value{emacs} version number, as a given module may quite well work
-regardless of the version of @value{emacs} that was installed at the time the
+the XEmacs version number, as a given module may quite well work
+regardless of the version of XEmacs that was installed at the time the
module was created.
-The @value{emacs} modules version is used to differentiate between major
-changes in the module loading technology, not versions of @value{emacs}.
+The XEmacs modules version is used to differentiate between major
+changes in the module loading technology, not versions of XEmacs.
@item emodules_name
This is a short (typically 10 characters or less) name for the module,
@@ -473,11 +455,11 @@
@node Loading other Modules, , Required Variables, Anatomy of a Module
@section Loading other Modules
@cindex dependencies
- at findex modules_of_module
+ at findex modules_of_ at var{module}
@findex emodules_load
During the loading of a module, it is the responsibility of the function
- at code{modules_of_module} to load in any modules which the current module
+ at code{modules_of_ at var{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 dependencies, it must call
@@ -539,12 +521,12 @@
Before discussing the anatomy of a module in greater detail, you should
be aware of the steps required in order to correctly compile and link a
-module for use within @value{emacs}. There is little difference between
+module for use within XEmacs. There is little difference between
compiling normal C code and compiling a module. In fact, all that
changes is the command used to compile the module, and a few extra
arguments to the compiler.
- at value{emacs} now ships with a new user utility, called @code{ellcc}. This
+XEmacs now ships with a new user utility, called @code{ellcc}. This
is the @dfn{Emacs Loadable Library C Compiler}. This is a wrapper
program that will invoke the real C compiler with the correct arguments
to compile and link your module. With the exception of a few command
@@ -580,7 +562,7 @@
to @code{ellcc}.
In this mode, @code{ellcc} is simply a front-end to the same C compiler
-that was used to create the @value{emacs} binary itself. All @code{ellcc}
+that was used to create the XEmacs binary itself. All @code{ellcc}
does in this mode is insert a few extra command line arguments before
the arguments you specify to @code{ellcc} itself. @code{ellcc} will
then invoke the C compiler to compile your module, and will return the
@@ -610,18 +592,18 @@
@cindex initialization
@cindex documentation
- at value{emacs} uses a rather bizarre way of documenting variables and
+XEmacs uses a rather bizarre way of documenting variables and
functions. Rather than have the documentation for compiled functions
and variables passed as static strings in the source code, the
documentation is included as a C comment. A special program, called
@file{make-docfile}, is used to scan the source code files and extract
-the documentation from these comments, producing the @value{emacs} @file{DOC}
+the documentation from these comments, producing the XEmacs @file{DOC}
file, which the internal help engine scans when the documentation for a
function or variable is requested.
Due to the internal construction of Lisp objects, subrs and other such
things, adding documentation for a compiled function or variable in a
-compiled module, at any time after @value{emacs} has been @dfn{dumped} is
+compiled module, at any time after XEmacs has been @dfn{dumped} is
somewhat problematic. Fortunately, as a module writer you are insulated
from the difficulties thanks to your friend @code{ellcc} and some
internal trickery in the module loading code. This is all done using
@@ -639,7 +621,7 @@
@code{ellcc} will produce, and you specify this using the
@code{--mod-output=FILENAME} argument. @var{FILENAME} is the name of
the C source code file that will contain the module variables and
- at code{docs_of_module} function.
+ at code{docs_of_ at var{module}} function.
As discussed previously, each module requires a short @dfn{handle} or
module name. This is specified with the @code{--mod-name=NAME} option,
@@ -665,7 +647,7 @@
Following all of these parameters, you need to provide the list of all
source code modules that make up your module. These are the files which
are scanned by @file{make-docfile}, and provide the information required
-to populate the @code{docs_of_module} function. Below is a sample
+to populate the @code{docs_of_ at var{module}} function. Below is a sample
@file{Makefile} fragment which indicates how all of this is used.
@example
@@ -706,11 +688,11 @@
The above @file{Makefile} is, in fact, complete, and would compile the
sample module, and optionally install it. The @code{--mod-location}
argument to @code{ellcc} will produce, on the standard output, the base
-location of the @value{emacs} module directory. Each subdirectory of
+location of the XEmacs module directory. Each subdirectory of
that directory is automatically searched for modules when they are
loaded with @code{load-module}. An alternative location would be
@file{/usr/local/lib/xemacs/site-modules}. That path can change
-depending on the options the person who compiled @value{emacs} chose, so
+depending on the options the person who compiled XEmacs chose, so
you can always determine the correct site location using the
@code{--mod-site-location} option. This directory is treated the same
way as the main module directory. Each subdirectory within it is
@@ -734,7 +716,7 @@
loadable module.
The module has complete access to all exported symbols that were present
-in the dumped @value{emacs}. On some Unix platforms, this means that
+in the dumped XEmacs. On some Unix platforms, this means that
you do not need to link against libraries that were linked in with the
main executable. However, Windows platforms, at least, still need to
link against such libraries if any symbols in those libraries are
@@ -803,10 +785,10 @@
@item --mod-archdir
Prints the name of the root of the architecture-dependent directory that
- at value{emacs} searches for architecture-dependent files.
+XEmacs searches for architecture-dependent files.
@item --mod-config
-Prints the name of the configuration for which @value{emacs} and @code{ellcc}
+Prints the name of the configuration for which XEmacs and @code{ellcc}
were compiled.
@end table
@@ -815,7 +797,7 @@
@cindex environment variables
During its normal operation, @code{ellcc} uses the compiler and linker
-flags that were determined at the time @value{emacs} was configured. In
+flags that were determined at the time XEmacs was configured. In
certain rare circumstances you may wish to override 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 @code{ellcc}
@@ -857,8 +839,8 @@
@cindex @code{ELLMAKEDOC}
Sets the name of the @file{make-docfile} program to use. Usually
@code{ellcc} will use the version that was compiled and installed with
- at value{emacs}, but this option allows you to specify an alternative path.
-Used during the compile phase of @value{emacs} itself.
+XEmacs, but this option allows you to specify an alternative path.
+Used during the compile phase of XEmacs itself.
@end table
@node Defining Functions, Defining Variables, Using ellcc, Top
@@ -872,7 +854,7 @@
function and the way it appears to Lisp, which is a @dfn{subroutine}, or
simply a @dfn{subr}. A Lisp subr is also known as a Lisp primitive, but
that term applies less to dynamic modules. @xref{Writing Lisp
-Primitives,,,internals, at value{emacs} Internals Manual}, for details on how to
+Primitives,,,internals,XEmacs Internals Manual}, for details on how to
declare functions. You should familiarize yourself with the
instructions there. The format of the function declaration is identical
in modules.
@@ -881,20 +863,20 @@
the documentation as a C comment. During the build process, a program
called @file{make-docfile} is run, which extracts all of these comments,
builds up a single large documentation file, and stores pointers to the
-start of each documentation entry in the dumped @value{emacs}. This, of
+start of each documentation entry in the dumped XEmacs. This, of
course, will not work for dynamic modules, as they are loaded long after
- at value{emacs} has been dumped. For this reason, we require a special
+XEmacs has been dumped. For this reason, we require a special
means for adding documentation for new subrs. This is what the macro
@code{CDOCSUBR} is used for; it is used extensively during @code{ellcc}
initialization mode.
- When using @code{DEFUN} in normal @value{emacs} C code, the sixth
+ When using @code{DEFUN} in normal XEmacs C code, the sixth
``parameter'' is a C comment which documents the function. For a
dynamic module, we of course need to convert the C comment to a usable
string, and we need to set the documentation pointer of the subr to this
string. As a module programmer, you don't actually need to do any work
for this to happen. It is all taken care of in the
- at code{docs_of_module} function created by @code{ellcc}. However, note
+ at code{docs_of_ at var{module}} function created by @code{ellcc}. However, note
that omitting a documentation string may cause @file{make-docfile} to
emit strange error messages.
@@ -911,8 +893,8 @@
@cindex functions, defining
The full syntax of a function declaration is discussed in the
- at value{emacs} internals manual in greater depth. @ref{Writing Lisp
-Primitives,,,internals, at value{emacs} Internals Manual}. What follows is
+XEmacs internals manual in greater depth. @ref{Writing Lisp
+Primitives,,,internals,XEmacs Internals Manual}. What follows is
a brief description of how to define and implement a new Lisp primitive
in a module. This is done using the @code{DEFUN} macro. Here is a
small example:
@@ -948,7 +930,7 @@
arguments are passed to the function. Next is the @code{interactive}
definition. If this function is meant to be run by a user
interactively, then you need to specify the argument types and prompts
-in this string. Please consult the @value{emacs} Lisp manual for more
+in this string. Please consult the XEmacs Lisp manual for more
details. Next comes a C comment that is the documentation for this
function. This comment @strong{must} exist. Last comes the list of
function argument names, if any.
@@ -962,13 +944,13 @@
available to the Lisp reader. During module initialization, you must
let the Lisp reader know about the new function. This is done by
calling @code{DEFSUBR} with the name of the function. This is an
-important purpose of the initialization function @code{syms_of_module}.
+important purpose of the initialization function @code{syms_of_ at var{module}}.
@xref{Required Functions}, for more details.
Each call to @code{DEFSUBR} takes as its only argument the name of the
function, which is the same as the second argument to the call to
@code{DEFUN}. Using the example function above, you would insert the
-following code in the @code{syms_of_module} function:
+following code in the @code{syms_of_ at var{module}} function:
@example
@cartouche
@@ -976,7 +958,7 @@
@end cartouche
@end example
-This call instructs @value{emacs} to make the function visible to the
+This call instructs XEmacs to make the function visible to the
Lisp reader and prepares for the insertion of the documentation into the
right place. Once this is done, the user can call the Lisp function
@code{my-function}, if it was defined as an interactive function (which
@@ -984,7 +966,7 @@
That's all there is to defining and announcing new functions. The rules
for what goes inside the functions, and how to write good modules, is
-beyond the scope of this document. Please consult the @value{emacs}
+beyond the scope of this document. Please consult the XEmacs
internals manual for more details.
@node Defining Variables, Module Interface, Defining Functions, Top
@@ -1003,7 +985,7 @@
common to also provide variables which can be used to control the
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 @value{emacs} primitives, and the declaration of the variables
+and internal XEmacs primitives, and the declaration of the variables
is identical.
@xref{Adding Global Lisp Variables,,,internals,XEmacs Internals Manual},
@@ -1011,17 +993,17 @@
Once your variables are defined, you need to initialize them and make
the Lisp reader aware of them. This is done in the
- at code{vars_of_module} initialization function using special @value{emacs}
+ at code{vars_of_ at var{module}} initialization function using special XEmacs
macros such as @code{DEFVAR_LISP}, @code{DEFVAR_BOOL}, @code{DEFVAR_INT},
etc. The best way to see how to use these macros is to look at existing
source code, or read the internals manual.
- One @emph{very} important difference between @value{emacs} variables and
+ One @emph{very} important difference between XEmacs variables and
module variables is how you use pure space. Simply put, you
- at strong{never} use pure space in @value{emacs} modules. The pure space
+ at strong{never} use pure space in XEmacs modules. The pure space
storage is of a limited size, and is initialized properly during the
-dumping of @value{emacs}. Because variables are being added dynamically to
-an already running @value{emacs} when you load a module, you cannot use pure
+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: @strong{do not use pure space in modules. Repeat, do
not use pure space in modules.} Once again, to remove all doubts:
@strong{DO NOT USE PURE SPACE IN MODULES!!!} (Also note, however, that
@@ -1030,7 +1012,7 @@
Below is a small example which declares and initializes two
variables. You will note that this code takes into account the fact
-that this module may very well be compiled into @value{emacs} itself. This
+that this module may very well be compiled into XEmacs itself. This
is a prudent thing to do.
@example
@@ -1039,7 +1021,7 @@
int sample_boolean;
void
-vars_of_module()
+vars_of_sample()
@{
DEFVAR_LISP ("sample-string", &Vsample_string /*
This is a sample string, declared in a module.
@@ -1060,10 +1042,10 @@
@node Module Interface, Index, Defining Variables, Top
@cindex interface
Information hiding is an important principle of program design. The
- at value{emacs} development team recognizes that exposing the entirety of
-the @value{emacs} internals to module programmers will lead to chaos.
+XEmacs development team recognizes that exposing the entirety of
+the XEmacs internals to module programmers will lead to chaos.
As the internals change, more and more module writers will find their
-modules breaking with each new @value{emacs} version. To prevent this
+modules breaking with each new XEmacs version. To prevent this
scenario, limited exposure to the internals is provided. The remainder
of this section describes the interface that has been exposed to module
programmers. Since the module functionality has not yet been ported to
@@ -1081,9 +1063,9 @@
@section Types
@cindex interface, types
-This section documents the internal @value{emacs} types exposed to
+This section documents the internal XEmacs types exposed to
modules, as well as the interface for managing module-defined types.
- at xref{lrecords, lrecords, lrecords, internals, @value{emacs} Internals Manual},
+ at xref{lrecords, lrecords, lrecords, internals, XEmacs Internals Manual},
for more information on type representations.
@subsection Memory allocation
@@ -1361,7 +1343,7 @@
@item DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION (name, c_name, dumpable, marker, printer, nuker, equal, hash, desc, structtype)
This macro appears at the toplevel of a file defining a Lisp-visible
type. The @var{name} is a string naming the type. The @var{c_name} is
-the same name without the quote marks. @var{Dumpable} should be nonzero
+the same name without the quote marks. @var{dumpable} should be nonzero
if the portable dumper can successfully save an image of the type and
restore it. The next 5 parameters are functions that tell how to mark
(for garbage collection), print, finalize, test equality of, and produce
@@ -1370,12 +1352,12 @@
is the name of the C struct describing objects of the type.
@item INIT_LRECORD_IMPLEMENTATION (TYPE)
-This macro appears in the function syms_of_module function for built-in
-modules. It should not be used for new modules.
+This macro appears in the function @code{syms_of_ at var{module}} function
+for built-in modules. It should not be used for new modules.
@item INIT_EXTERNAL_LRECORD_IMPLEMENTATION (TYPE)
-This macro should appear in the syms_of_module function of your module
-for each Lisp-visible type your module defines.
+This macro should appear in the @code{syms_of_ at var{module}} function of
+your module for each Lisp-visible type your module defines.
@end table
@@ -1900,11 +1882,11 @@
@table @code
@item DEFSUBR (Fname)
@findex DEFSUBR
-This macro, which is used in the @code{syms_of_module} function
+This macro, which is used in the @code{syms_of_ at var{module}} function
(@pxref{Required Functions}), takes the C name of a function declared
with @code{DEFUN}; by convention, those names begin with the letter `F'.
Every @code{DEFUN} in your code must have a corresponding @code{DEFSUBR}
-in @code{syms_of_module}.
+in @code{syms_of_ at var{module}}.
@item DEFSUBR_MACRO (Fname)
@findex DEFSUBR_MACRO
@@ -1914,7 +1896,7 @@
@item DEFSYMBOL (name)
@findex DEFSYMBOL
-This macro, which is used in the @code{syms_of_module} function
+This macro, which is used in the @code{syms_of_ at var{module}} function
(@pxref{Required Functions}), takes the name of a variable declared as a
@code{Lisp_Object}. The name of the variable should begin with the
letter `Q'. The name of the variable is transformed by stripping off
@@ -1937,7 +1919,7 @@
@item DEFVAR_LISP (lname, c_location)
@findex DEFVAR_LISP
-This macro is used in the @code{vars_of_module} function
+This macro is used in the @code{vars_of_ at var{module}} function
(@pxref{Required Functions}). The @var{lname} parameter is a C string
naming the Lisp variable. The @var{c_location} parameter is a pointer
to a @code{Lisp_Object}, whose name begins with `V' by convention. For
@@ -1950,7 +1932,10 @@
@item DEFVAR_CONST_LISP (lname, c_location)
@findex DEFVAR_CONST_LISP
This macro is like @code{DEFVAR_LISP}, except that it is the counterpart
-of @code{defconst}; i.e., attempts at setting it in Lisp are refused.
+of @code{defconst}; @emph{i.e.}, it overrides any previous top-level binding
+(unlike @code{defvar} and @code{DEFVAR}, which check if the symbol
+already has a value, and leave it alone if there is one, including
+ at code{nil}).
@item DEFVAR_LISP_MAGIC (lname, c_location, magicfun)
@findex DEFVAR_LISP_MAGIC
@@ -1976,8 +1961,8 @@
@item DEFVAR_CONST_INT (lname, c_location)
@findex DEFVAR_CONST_INT
-This macro is like @code{DEFVAR_INT}, except that attempts at setting it
-in Lisp are refused.
+This macro is like @code{DEFVAR_INT}, except that it will not overwrite
+previous top-level bindings.
@item DEFVAR_INT_MAGIC (lname, c_location, magicfun)
@findex DEFVAR_INT_MAGIC
@@ -1994,8 +1979,8 @@
@item DEFVAR_CONST_BOOL (lname, c_location)
@findex DEFVAR_CONST_BOOL
-This macro is like @code{DEFVAR_BOOL}, except that attempts at setting
-it in Lisp are refused.
+This macro is like @code{DEFVAR_BOOL}, except that it will not overwrite
+previous top-level bindings.
@item DEFVAR_BOOL_MAGIC (lname, c_location, magicfun)
@findex DEFVAR_BOOL_MAGIC
@@ -2004,7 +1989,7 @@
@item DEFERROR (name, message, inherits_from)
@findex DEFERROR
-This macro is used in the @code{syms_of_module} function
+This macro is used in the @code{syms_of_ at var{module}} function
(@pxref{Required Functions}). It declares that @var{name}, which should
be a @code{Lisp_Object} whose name begins with `Q', is an error
condition that inherits from the existing error condition
@@ -2024,6 +2009,18 @@
This section documents parts of the module interface that provide access
to features of the Lisp language, and low-level Lisp functions.
+Note that for most Lisp functions defined in C, all arguments are
+ at code{Lisp_Objects}, and there must be a fixed number of them. The Lisp
+engine ensures that omitted @code{&optional} arguments are initialized
+to @code{nil}. When a Lisp function coded in C takes a @code{&rest}
+argument, it is @code{DEFUN}ed to take @code{MANY} arguments, and its
+actual arguments are a count @var{nargs} and an array of
+ at code{Lisp_Object}s, @var{args}. No function callable from Lisp ever
+takes a variable number of arguments as a C function.
+
+See @code{Ffuncall} and @code{Fappend} below for two typical examples of
+Lisp functions that take a @code{&rest} arguments.
+
@table @code
@item Lisp_Object Fapply (int nargs, Lisp_Object *args)
@@ -2111,110 +2108,122 @@
@item Lisp_Object cons3 (Lisp_Object obj0, Lisp_Object obj1, Lisp_Object obj2)
@findex cons3
-The C equivalent of @code{(cons obj0 (cons obj1 obj2))}.
+The C equivalent of @code{(cons @var{obj0} (cons @var{obj1} @var{obj2}))}.
@item Lisp_Object list1 (Lisp_Object obj0)
@findex list1
-The C equivalent of @code{(list obj0)}.
+The C equivalent of @code{(list @var{obj0})}.
@item Lisp_Object list2 (Lisp_Object obj0, Lisp_Object obj1)
@findex list2
-The C equivalent of @code{(list obj0 obj1)}.
+The C equivalent of @code{(list @var{obj0} @var{obj1})}.
@item Lisp_Object list3 (Lisp_Object obj0, Lisp_Object obj1, Lisp_Object obj2)
@findex list3
-The C equivalent of @code{(list obj0 obj1 obj2)}.
+The C equivalent of @code{(list @var{obj0} @var{obj1} @var{obj2})}.
@item Lisp_Object list4 (Lisp_Object obj0, Lisp_Object obj1, Lisp_Object obj2,
Lisp_Object obj3)
@findex list4
-The C equivalent of @code{(list obj0 obj1 obj2 obj3)}.
+The C equivalent of @code{(list @var{obj0} @var{obj1} @var{obj2} @var{obj3})}.
@item Lisp_Object list5 (Lisp_Object obj0, Lisp_Object obj1, Lisp_Object obj2,
Lisp_Object obj3, Lisp_Object obj4)
@findex list5
-The C equivalent of @code{(list obj0 obj1 obj2 obj3 obj4)}.
+The C equivalent of
+ at code{(list @var{obj0} @var{obj1} @var{obj2} @var{obj3} @var{obj4})}.
@item Lisp_Object list6 (Lisp_Object obj0, Lisp_Object obj1, Lisp_Object obj2,
Lisp_Object obj3, Lisp_Object obj4, Lisp_Object obj5)
@findex list6
-The C equivalent of @code{(list obj0 obj1 obj2 obj3 obj4 obj5)}.
+The C equivalent of @code{(list @var{obj0} @var{obj1} @var{obj2}
+ at var{obj3} @var{obj4} @var{obj5})}.
@item Lisp_Object vector1 (Lisp_Object obj0)
@findex vector1
-The C equivalent of @code{(vector obj0)}.
+The C equivalent of @code{(vector @var{obj0})}.
@item Lisp_Object vector2 (Lisp_Object obj0, Lisp_Object obj1)
@findex vector2
-The C equivalent of @code{(vector obj0 obj1)}.
+The C equivalent of @code{(vector @var{obj0} @var{obj1})}.
@item Lisp_Object vector3 (Lisp_Object obj0, Lisp_Object obj1,
Lisp_Object obj2)
@findex vector3
-The C equivalent of @code{(vector obj0 obj1 obj2)}.
+The C equivalent of @code{(vector @var{obj0} @var{obj1} @var{obj2})}.
@item int EQ (Lisp_Object obj1, Lisp_Object obj2)
@findex EQ
-The C equivalent of @code{(eq obj1 obj2)}.
+The C equivalent of @code{(eq @var{obj1} @var{obj2})}, except that it does not
+trigger a warning when comparing a character with an integer (a
+comparison which is always false). Do not use this without consulting
+the the XEmacs Development Team; use @code{EQ_WITH_EBOLA_NOTICE}.
@item int EQ_WITH_EBOLA_NOTICE (Lisp_Object obj1, Lisp_Object obj2)
@findex EQ_WITH_EBOLA_NOTICE
-Equivalent to @code{(eq obj1 obj2)}, except that comparison of a
+Equivalent to @code{(eq @var{obj1} @var{obj2})}, except that comparison of a
character with an integer triggers a warning.
@item int NILP (Lisp_Object obj)
@findex NILP
-The C equivalent of @code{(null obj)}.
+The C equivalent of @code{(null @var{obj})}.
@item int UNBOUNDP (Lisp_Object obj)
@findex UNBOUNDP
Nonzero if the given object is not bound to a value.
- at item Lisp_Object Fequal (Lisp_Object object1, Lisp_Object object2)
+ at item Lisp_Object Fequal (Lisp_Object obj1, Lisp_Object obj2)
@findex Fequal
-The C equivalent of @code{(equal object1 object2)}.
+The C equivalent of @code{(equal @var{obj1} @var{obj2})}.
@item Lisp_Object Flength (Lisp_Object sequence)
@findex Flength
-The C equivalent of @code{(length sequence)}.
+The C equivalent of @code{(length @var{sequence})}.
@item Lisp_Object Fappend (int nargs, Lisp_Object *args)
@findex Fappend
-The C equivalent of @code{(append args[0] @dots{} args[nargs-1])}.
+The C equivalent of
+ at samp{(append @var{args}[0] @dots{} @var{args}[@var{nargs-1}])}.
@item Lisp_Object Fcons (Lisp_Object car, Lisp_Object cdr)
@findex Fcons
-The C equivalent of @code{(cons car cdr)}.
+The C equivalent of @code{(cons @var{car} @var{cdr})}.
@item Lisp_Object Flist (int nargs, Lisp_Object *args)
@findex Flist
-The C equivalent of @code{(list args[0] @dots{} args[nargs-1])}.
+The C equivalent of
+ at code{(list @var{args}[0] @dots{} @var{args}[@var{nargs-1}])}.
@item Lisp_Object Fvector (int nargs, Lisp_Object *args)
@findex Fvector
-The C equivalent of @code{(vector args[0] @dots{} args[nargs-1])}.
+The C equivalent of
+ at code{(vector @var{args}[0] @dots{} @var{args}[@var{nargs-1}])}.
@item Lisp_Object Freverse (Lisp_Object list)
@findex Freverse
-The C equivalent of @code{(reverse list)}.
+The C equivalent of @code{(reverse @var{list})}.
@item Lisp_Object Fnreverse (Lisp_Object list)
@findex Fnreverse
-The C equivalent of @code{(nreverse list)}.
+The C equivalent of @code{(nreverse @var{list})}.
@item Lisp_Object Fget (Lisp_Object object, Lisp_Object property,
Lisp_Object default)
@findex Fget
-The C equivalent of @code{(get object property default)}.
+The C equivalent of @code{(get @var{object} @var{property} @var{default})}.
@item Lisp_Object Fput (Lisp_Object object, Lisp_Object property,
Lisp_Object value)
@findex Fput
-The C equivalent of @code{(put object property value)}.
+The C equivalent of @code{(put @var{object} @var{property} @var{value})}.
+
+ at item Lisp_Object Ffeaturep (Lisp_Object feature)
+ at findex Ffeaturep
+The C equivalent of @code{(featurep @var{feature})}.
@item Lisp_Object Fprovide (Lisp_Object feature)
@findex Fprovide
-The C equivalent of @code{(provide feature)}.
+The C equivalent of @code{(provide @var{feature})}.
@item Lisp_Object Fcurrent_buffer ()
@findex Fcurrent_buffer
@@ -2255,7 +2264,7 @@
@cindex strings
@cindex coding systems
-Since @value{emacs} has the ability to store strings in various
+Since XEmacs has the ability to store strings in various
character sets (coding systems), converting strings between internal and
external representations is nontrivial. The functions documented here
provide the means of doing so.
@@ -2269,7 +2278,7 @@
@item Lisp_Object build_intstring (const Ibyte *str)
@findex build_intstring
Make a Lisp string object out of a string of internal characters (i.e.,
-characters using an @value{emacs} coding system).
+characters using an XEmacs coding system).
@item Lisp_Object build_msg_intstring (const Ibyte *)
@findex build_msg_intstring
@@ -2279,13 +2288,13 @@
@item Lisp_Object build_msg_string (const CIbyte *)
@findex build_msg_string
Make a Lisp string object out of a string of internal characters that
-have been delcared as ``char *'' for some reason, after using
+have been declared as @samp{char *} for some reason, after using
@code{gettext()} to fetch the actual text.
@item Lisp_Object build_string (const CIbyte *str)
@findex build_string
Make a Lisp string object out of a string of internal characters that
-have been declared as ``char *'' for some reason.
+have been declared as @samp{char *} for some reason.
@item Charcount bytecount_to_charcount (const Ibyte *ptr, Bytecount len)
@findex bytecount_to_charcount
@@ -2311,7 +2320,7 @@
@item Lisp_Object Fmake_string (Lisp_Object length, Lisp_Object character)
@findex Fmake_string
-The C equivalent of @code{(make-string length character)}.
+The C equivalent of @code{(make-string @var{length} @var{character})}.
@item Charcount string_char_length (Lisp_Object s)
@findex string_char_length
@@ -2325,78 +2334,80 @@
@item void C_STRING_TO_EXTERNAL(const char *in, Extbyte *out,
Lisp_Object codesys)
@findex C_STRING_TO_EXTERNAL
-Convert a C (ASCII) string to its external representation using
- at code{alloca}.
+Convert a C (ASCII) string to its external representation, allocating
+storage with @code{alloca}.
@item void C_STRING_TO_EXTERNAL_MALLOC(const char *in, Extbyte *out,
Lisp_Object codesys)
@findex C_STRING_TO_EXTERNAL_MALLOC
-Convert a C (ASCII) string to its external representation using
- at code{malloc}.
+Convert a C (ASCII) string to its external representation, allocating
+storage with @code{malloc}.
@item void C_STRING_TO_SIZED_EXTERNAL(const char *in, Extbyte *out,
Bytecount outlen, Lisp_Object codesys)
@findex C_STRING_TO_SIZED_EXTERNAL
Convert a C (ASCII) string to its external representation of
- at var{outlen} bytes using @code{alloca}.
+ at var{outlen} bytes, allocating storage with @code{alloca}.
@item void SIZED_C_STRING_TO_EXTERNAL(const void *in, Bytecount inlen,
Extbyte *out, Lisp_Object codesys)
@findex SIZED_C_STRING_TO_EXTERNAL
Convert a C (ASCII) string of @var{inlen} bytes to its external
-representation using @code{alloca}.
+representation, allocating storage with @code{alloca}.
@item void SIZED_C_STRING_TO_SIZED_EXTERNAL(const void *in,
Bytecount inlen, Extbyte *out, Bytecount outlen, Lisp_Object codesys)
@findex SIZED_C_STRING_TO_SIZED_EXTERNAL
Convert a C (ASCII) string of @var{inlen} bytes to its external
-representation of @var{outlen} bytes using @code{alloca}.
+representation of @var{outlen} bytes, allocating storage with @code{alloca}.
@item void EXTERNAL_TO_C_STRING (const void *in, Ibyte *out,
Lisp_Object codesys)
@findex EXTERNAL_TO_C_STRING
-Convert a string in an external representation to a C (ASCII) string
-using @code{alloca}.
+Convert a string in an external representation to a C (ASCII) string,
+allocating storage with @code{alloca}.
@item void EXTERNAL_TO_C_STRING_MALLOC (const void *in, Ibyte *out,
Lisp_Object codesys)
@findex EXTERNAL_TO_C_STRING_MALLOC
-Convert a string in an external representation to a C (ASCII) string
-using @code{malloc}.
+Convert a string in an external representation to a C (ASCII) string,
+allocating storage with @code{malloc}.
@item void EXTERNAL_TO_SIZED_C_STRING (const void *in, Ibyte *out,
Bytecount outlen, Lisp_Object codesys)
@findex EXTERNAL_TO_SIZED_C_STRING
Convert a string in an external representation to a C (ASCII) string of
- at var{outlen} bytes using @code{alloca}.
+ at var{outlen} bytes, allocating storage with @code{alloca}.
@item void SIZED_EXTERNAL_TO_C_STRING (const void *in, Bytecount inlen,
Ibyte *out, Lisp_Object codesys)
@findex SIZED_EXTERNAL_TO_C_STRING
Convert a string of @var{inlen} bytes in an external representation to a
-C (ASCII) string using @code{alloca}.
+C (ASCII) string, allocating storage with @code{alloca}.
@item void SIZED_EXTERNAL_TO_SIZED_C_STRING (const void *in, Bytecount inlen,
Ibyte *out, Bytecount outlen, Lisp_Object codesys)
@findex SIZED_EXTERNAL_TO_SIZED_C_STRING
Convert a string of @var{inlen} bytes in an external representation to a
-C (ASCII) string of @var{outlen} bytes using @code{alloca}.
+C (ASCII) string of @var{outlen} bytes, allocating storage with @code{alloca}.
@item void LISP_STRING_TO_EXTERNAL(Lisp_Object in, Extbyte *out,
Lisp_Object codesys)
@findex LISP_STRING_TO_EXTERNAL
-Convert a Lisp string to its external representation using @code{alloca}.
+Convert a Lisp string to its external representation, allocating storage
+with @code{alloca}.
@item void LISP_STRING_TO_EXTERNAL_MALLOC(Lisp_Object in, Extbyte *out,
Lisp_Object codesys)
@findex LISP_STRING_TO_EXTERNAL_MALLOC
-Convert a Lisp string to its external representation using @code{malloc}.
+Convert a Lisp string to its external representation, allocating storage
+with @code{malloc}.
@item void LISP_STRING_TO_SIZED_EXTERNAL(Lisp_Object in, Extbyte *out,
Bytecount outlen, Lisp_Object codesys)
@findex LISP_STRING_TO_SIZED_EXTERNAL
Convert a Lisp string to its external representation of @var{outlen}
-bytes using @code{alloca}.
+bytes, allocating storage with @code{alloca}.
@item TO_INTERNAL_FORMAT (source_type, source, sink_type, sink, codesys)
@findex TO_INTERNAL_FORMAT
@@ -2470,22 +2481,27 @@
@section Event Processing
@cindex events
-See the @value{emacs} Internals Manual for more information on the event
+See the XEmacs Internals Manual for more information on the event
processing system. The functions listed here provide the hooks a module
may need to interact with the event system.
@table @code
@item QUIT
@findex QUIT
-This macro is used to see whether the user pressed C-g. If so, a quit
+This macro is used to see whether the user pressed @kbd{C-g}. If so, a quit
is signaled. Note that @code{QUIT} can cause random side effects to
happen, since it may need to process many asynchronous events to tell
-whether C-g was pressed.
+whether @kbd{C-g} was pressed. @code{QUIT} may also trigger a garbage
+collection, which can take large, and usually perceptible, amounts of
+time. Avoid @code{QUIT}ting in timing-sensitive code, but then ensure
+that @code{QUIT} is called as soon as it is safe, especially if your
+code may call out to Lisp.
@item QUITP
@findex QUITP
-This macro evaluates to true if the user pressed C-g. In that case, the
-user should do whatever cleanup is necssary, then call @code{QUIT}.
+This macro evaluates to true if the user pressed @kbd{C-g}. In that
+case, the user should do whatever cleanup is necessary, then call
+ at code{QUIT}.
@end table
@@ -2598,18 +2614,28 @@
@cindex garbage
Lisp objects are subject to garbage collection unless protected. The
-macros listed in this section provide that protection.
+functions and macros listed in this section provide that protection.
+ at ref{GCPROing, , , Internals}, for details of the GCPRO mechanism.
+
+These functions are used to protect or remove protection from global
+ at code{Lisp_Objects} declared in C.
@table @code
@item void staticpro (Lisp_Object *ptr)
@findex staticpro
-Mark the object pointed to by @var{ptr} as a root object for garbage
+Mark the global object pointed to by @var{ptr} as a root object for garbage
collection.
@item void unstaticpro (Lisp_Object *ptr)
@findex unstaticpro
-Remove the object pointed to by @var{ptr} from the list of root objects.
+Remove the global object pointed to by @var{ptr} from the list of root
+objects.
+ at end table
+These macros are used to protect objects allocated on the C stack
+(@emph{i.e.}, local variables declared @code{Lisp_Object}).
+
+ at table @code
@item GCPRO1 (var1)
@findex GCPRO1
Protect 1 @code{Lisp_Object} from garbage collection.
@@ -2752,24 +2778,27 @@
@section Miscellaneous
This section documents the remaining parts of the module interface.
+Note that XEmacs defines its own versions of @code{abort} and
+ at code{assert} in order to arrange for printing of Lisp backtraces and
+the notorious crash output. This should be transparent to callers.
@table @code
@item void abort(void)
@findex abort
-Abort the @value{emacs} process.
+Abort the XEmacs process.
@item void assert(bool expr)
@findex assert
-Abort the @value{emacs} process if @var{expr} is false.
+Abort the XEmacs process if @var{expr} is false.
@item void assert_at_line(bool expr, const char *file, int line)
@findex assert_at_line
-Abort the @value{emacs} process if @var{expr} is false and notify the
+Abort the XEmacs process if @var{expr} is false and notify the
user that the abort took place at a given line in a file.
@item void assert_with_message(bool expr, const char *msg)
@findex assert_with_message
-Abort the @value{emacs} process if @var{expr} is false and print a message.
+Abort the XEmacs process if @var{expr} is false and print a message.
@item Ibyte *egetenv (const CIbyte *var)
@findex egetenv
@@ -2783,8 +2812,11 @@
@item Lisp_Object intern (const CIbyte *str)
@findex intern
-Return the canonical Lisp object whose name is given by the string
- at var{str}.
+Return the Lisp symbol whose name is given by the string
+ at var{str}. This creates the symbol if it does not already exist. The
+difference between the name of a symbol with no value and a name which
+has not been @code{intern}ed can be detected using the Lisp function
+ at code{intern-soft}.
@item void message (const char *, @dots{)}
@findex message
@@ -2802,18 +2834,18 @@
@item void write_c_string (Lisp_Object stream, const CIbyte *str)
@findex write_c_string
Print an string of internally-formatted characters declared as
-``char *'' on @var{stream}.
+ at samp{char *} on @var{stream}.
@item void write_fmt_string (Lisp_Object stream, const CIbyte *fmt, @dots{})
@findex write_fmt_string
Print an string of internally-formatted characters declared as
-``char *'' on @var{stream}.
+ at samp{char *} on @var{stream}.
@item void write_fmt_string_lisp (Lisp_Object stream, const CIbyte *fmt,
int nargs, @dots{})
@findex write_fmt_string
Print an string of internally-formatted characters declared as
-``char *'' on @var{stream}, where the arguments are Lisp objects rather
+ at samp{char *} on @var{stream}, where the arguments are Lisp objects rather
than C strings or integers.
@item int print_readably
--
Institute of Policy and Planning Sciences http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Ask not how you can "do" free software business;
ask what your business can "do for" free software.
More information about the XEmacs-Beta
mailing list