# This is a patch for xemacs-21.4.2 to update it to xemacs-21.4.3
# 
# To apply this patch:
# STEP 1: Chdir to the source directory.
# STEP 2: Run the 'applypatch' program with this patch file as input.
#
# If you do not have 'applypatch', it is part of the 'makepatch' package
# that you can fetch from the Comprehensive Perl Archive Network:
# http://www.perl.com/CPAN/authors/Johan_Vromans/makepatch-x.y.tar.gz
# In the above URL, 'x' should be 2 or higher.
#
# To apply this patch without the use of 'applypatch':
# STEP 1: Chdir to the source directory.
# If you have a decent Bourne-type shell:
# STEP 2: Run the shell with this file as input.
# If you don't have such a shell, you may need to manually create
# the files as shown below.
# STEP 3: Run the 'patch' program with this file as input.
#
# These are the commands needed to create/delete files/directories:
#
touch './info/cl.info'
chmod 0644 './info/cl.info'
touch './info/cl.info-1'
chmod 0644 './info/cl.info-1'
touch './info/cl.info-2'
chmod 0644 './info/cl.info-2'
touch './info/cl.info-3'
chmod 0644 './info/cl.info-3'
touch './info/cl.info-4'
chmod 0644 './info/cl.info-4'
touch './info/cl.info-5'
chmod 0644 './info/cl.info-5'
touch './info/cl.info-6'
chmod 0644 './info/cl.info-6'
touch './info/custom.info'
chmod 0644 './info/custom.info'
touch './info/emodules.info'
chmod 0644 './info/emodules.info'
touch './info/external-widget.info'
chmod 0644 './info/external-widget.info'
touch './info/info.info'
chmod 0644 './info/info.info'
touch './info/internals.info'
chmod 0644 './info/internals.info'
touch './info/internals.info-1'
chmod 0644 './info/internals.info-1'
touch './info/internals.info-2'
chmod 0644 './info/internals.info-2'
touch './info/internals.info-3'
chmod 0644 './info/internals.info-3'
touch './info/internals.info-4'
chmod 0644 './info/internals.info-4'
touch './info/internals.info-5'
chmod 0644 './info/internals.info-5'
touch './info/internals.info-6'
chmod 0644 './info/internals.info-6'
touch './info/internals.info-7'
chmod 0644 './info/internals.info-7'
touch './info/internals.info-8'
chmod 0644 './info/internals.info-8'
touch './info/internals.info-9'
chmod 0644 './info/internals.info-9'
touch './info/lispref.info'
chmod 0644 './info/lispref.info'
touch './info/lispref.info-1'
chmod 0644 './info/lispref.info-1'
touch './info/lispref.info-10'
chmod 0644 './info/lispref.info-10'
touch './info/lispref.info-11'
chmod 0644 './info/lispref.info-11'
touch './info/lispref.info-12'
chmod 0644 './info/lispref.info-12'
touch './info/lispref.info-13'
chmod 0644 './info/lispref.info-13'
touch './info/lispref.info-14'
chmod 0644 './info/lispref.info-14'
touch './info/lispref.info-15'
chmod 0644 './info/lispref.info-15'
touch './info/lispref.info-16'
chmod 0644 './info/lispref.info-16'
touch './info/lispref.info-17'
chmod 0644 './info/lispref.info-17'
touch './info/lispref.info-18'
chmod 0644 './info/lispref.info-18'
touch './info/lispref.info-19'
chmod 0644 './info/lispref.info-19'
touch './info/lispref.info-2'
chmod 0644 './info/lispref.info-2'
touch './info/lispref.info-20'
chmod 0644 './info/lispref.info-20'
touch './info/lispref.info-21'
chmod 0644 './info/lispref.info-21'
touch './info/lispref.info-22'
chmod 0644 './info/lispref.info-22'
touch './info/lispref.info-23'
chmod 0644 './info/lispref.info-23'
touch './info/lispref.info-24'
chmod 0644 './info/lispref.info-24'
touch './info/lispref.info-25'
chmod 0644 './info/lispref.info-25'
touch './info/lispref.info-26'
chmod 0644 './info/lispref.info-26'
touch './info/lispref.info-27'
chmod 0644 './info/lispref.info-27'
touch './info/lispref.info-28'
chmod 0644 './info/lispref.info-28'
touch './info/lispref.info-29'
chmod 0644 './info/lispref.info-29'
touch './info/lispref.info-3'
chmod 0644 './info/lispref.info-3'
touch './info/lispref.info-30'
chmod 0644 './info/lispref.info-30'
touch './info/lispref.info-31'
chmod 0644 './info/lispref.info-31'
touch './info/lispref.info-32'
chmod 0644 './info/lispref.info-32'
touch './info/lispref.info-33'
chmod 0644 './info/lispref.info-33'
touch './info/lispref.info-34'
chmod 0644 './info/lispref.info-34'
touch './info/lispref.info-35'
chmod 0644 './info/lispref.info-35'
touch './info/lispref.info-36'
chmod 0644 './info/lispref.info-36'
touch './info/lispref.info-37'
chmod 0644 './info/lispref.info-37'
touch './info/lispref.info-38'
chmod 0644 './info/lispref.info-38'
touch './info/lispref.info-39'
chmod 0644 './info/lispref.info-39'
touch './info/lispref.info-4'
chmod 0644 './info/lispref.info-4'
touch './info/lispref.info-40'
chmod 0644 './info/lispref.info-40'
touch './info/lispref.info-41'
chmod 0644 './info/lispref.info-41'
touch './info/lispref.info-42'
chmod 0644 './info/lispref.info-42'
touch './info/lispref.info-43'
chmod 0644 './info/lispref.info-43'
touch './info/lispref.info-44'
chmod 0644 './info/lispref.info-44'
touch './info/lispref.info-45'
chmod 0644 './info/lispref.info-45'
touch './info/lispref.info-46'
chmod 0644 './info/lispref.info-46'
touch './info/lispref.info-47'
chmod 0644 './info/lispref.info-47'
touch './info/lispref.info-48'
chmod 0644 './info/lispref.info-48'
touch './info/lispref.info-5'
chmod 0644 './info/lispref.info-5'
touch './info/lispref.info-6'
chmod 0644 './info/lispref.info-6'
touch './info/lispref.info-7'
chmod 0644 './info/lispref.info-7'
touch './info/lispref.info-8'
chmod 0644 './info/lispref.info-8'
touch './info/lispref.info-9'
chmod 0644 './info/lispref.info-9'
touch './info/new-users-guide.info'
chmod 0644 './info/new-users-guide.info'
touch './info/new-users-guide.info-1'
chmod 0644 './info/new-users-guide.info-1'
touch './info/new-users-guide.info-2'
chmod 0644 './info/new-users-guide.info-2'
touch './info/new-users-guide.info-3'
chmod 0644 './info/new-users-guide.info-3'
touch './info/standards.info'
chmod 0644 './info/standards.info'
touch './info/standards.info-1'
chmod 0644 './info/standards.info-1'
touch './info/standards.info-2'
chmod 0644 './info/standards.info-2'
touch './info/standards.info-3'
chmod 0644 './info/standards.info-3'
touch './info/standards.info-4'
chmod 0644 './info/standards.info-4'
touch './info/term.info'
chmod 0644 './info/term.info'
touch './info/termcap.info'
chmod 0644 './info/termcap.info'
touch './info/termcap.info-1'
chmod 0644 './info/termcap.info-1'
touch './info/termcap.info-2'
chmod 0644 './info/termcap.info-2'
touch './info/termcap.info-3'
chmod 0644 './info/termcap.info-3'
touch './info/texinfo.info'
chmod 0644 './info/texinfo.info'
touch './info/texinfo.info-1'
chmod 0644 './info/texinfo.info-1'
touch './info/texinfo.info-10'
chmod 0644 './info/texinfo.info-10'
touch './info/texinfo.info-11'
chmod 0644 './info/texinfo.info-11'
touch './info/texinfo.info-12'
chmod 0644 './info/texinfo.info-12'
touch './info/texinfo.info-2'
chmod 0644 './info/texinfo.info-2'
touch './info/texinfo.info-3'
chmod 0644 './info/texinfo.info-3'
touch './info/texinfo.info-4'
chmod 0644 './info/texinfo.info-4'
touch './info/texinfo.info-5'
chmod 0644 './info/texinfo.info-5'
touch './info/texinfo.info-6'
chmod 0644 './info/texinfo.info-6'
touch './info/texinfo.info-7'
chmod 0644 './info/texinfo.info-7'
touch './info/texinfo.info-8'
chmod 0644 './info/texinfo.info-8'
touch './info/texinfo.info-9'
chmod 0644 './info/texinfo.info-9'
touch './info/widget.info'
chmod 0644 './info/widget.info'
touch './info/xemacs-faq.info'
chmod 0644 './info/xemacs-faq.info'
touch './info/xemacs-faq.info-1'
chmod 0644 './info/xemacs-faq.info-1'
touch './info/xemacs-faq.info-2'
chmod 0644 './info/xemacs-faq.info-2'
touch './info/xemacs-faq.info-3'
chmod 0644 './info/xemacs-faq.info-3'
touch './info/xemacs-faq.info-4'
chmod 0644 './info/xemacs-faq.info-4'
touch './info/xemacs-faq.info-5'
chmod 0644 './info/xemacs-faq.info-5'
touch './info/xemacs.info'
chmod 0644 './info/xemacs.info'
touch './info/xemacs.info-1'
chmod 0644 './info/xemacs.info-1'
touch './info/xemacs.info-10'
chmod 0644 './info/xemacs.info-10'
touch './info/xemacs.info-11'
chmod 0644 './info/xemacs.info-11'
touch './info/xemacs.info-12'
chmod 0644 './info/xemacs.info-12'
touch './info/xemacs.info-13'
chmod 0644 './info/xemacs.info-13'
touch './info/xemacs.info-14'
chmod 0644 './info/xemacs.info-14'
touch './info/xemacs.info-15'
chmod 0644 './info/xemacs.info-15'
touch './info/xemacs.info-16'
chmod 0644 './info/xemacs.info-16'
touch './info/xemacs.info-17'
chmod 0644 './info/xemacs.info-17'
touch './info/xemacs.info-18'
chmod 0644 './info/xemacs.info-18'
touch './info/xemacs.info-19'
chmod 0644 './info/xemacs.info-19'
touch './info/xemacs.info-2'
chmod 0644 './info/xemacs.info-2'
touch './info/xemacs.info-20'
chmod 0644 './info/xemacs.info-20'
touch './info/xemacs.info-21'
chmod 0644 './info/xemacs.info-21'
touch './info/xemacs.info-22'
chmod 0644 './info/xemacs.info-22'
touch './info/xemacs.info-23'
chmod 0644 './info/xemacs.info-23'
touch './info/xemacs.info-3'
chmod 0644 './info/xemacs.info-3'
touch './info/xemacs.info-4'
chmod 0644 './info/xemacs.info-4'
touch './info/xemacs.info-5'
chmod 0644 './info/xemacs.info-5'
touch './info/xemacs.info-6'
chmod 0644 './info/xemacs.info-6'
touch './info/xemacs.info-7'
chmod 0644 './info/xemacs.info-7'
touch './info/xemacs.info-8'
chmod 0644 './info/xemacs.info-8'
touch './info/xemacs.info-9'
chmod 0644 './info/xemacs.info-9'
#
# This command terminates the shell and need not be executed manually.
exit
#
#### End of Preamble ####

#### Patch data follows ####
diff --text -u 'xemacs-21.4.2/ChangeLog' 'xemacs-21.4.3/ChangeLog'
Index: ././ChangeLog
--- ././ChangeLog	Thu May 10 18:46:45 2001
+++ ././ChangeLog	Thu May 17 23:58:56 2001
@@ -1,3 +1,20 @@
+2001-05-17  Stephen J. Turnbull  <stephen@xemacs.org>
+
+	* XEmacs 21.4.3 "Academic Rigor" is released.
+
+2001-05-10  Paul Stodghill  <stodghil@cs.cornell.edu>
+
+	* configure.in: Reverse the order of Windows and Linux sound tests
+	so that	Cygwin will find Windows first.
+
+2001-05-15  Steve Youngs  <youngs@xemacs.org>
+
+	* etc/photos/{youngs,youngsm}.png:  New photos.
+
+2001-05-15  Steve Youngs  <youngs@xemacs.org>
+
+	* etc/PACKAGES: Update to reflect new package dir tree.
+
 2001-05-10  Stephen J. Turnbull  <stephen@xemacs.org>
 
 	* XEmacs 21.4.2 "Developer-Friendly Unix APIs" is released.
diff --text -u 'xemacs-21.4.2/configure' 'xemacs-21.4.3/configure'
Index: ././configure
--- ././configure	Thu Apr 19 16:35:56 2001
+++ ././configure	Tue May 15 21:18:51 2001
@@ -1503,7 +1503,8 @@
 esac
 
 test -z "$machine" && machine=`echo $canonical | sed 's/-.*$//'`
-test -z "$opsys"   && opsys=`echo $canonical | sed 's/^^-*-^-*-//'`
+
+test -z "$opsys"   && opsys=`uname -s | tr ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz`
 
 if test -r "${srcdir}/src/m/${machine}.h"; then
   machfile="m/${machine}.h"
@@ -1622,7 +1623,7 @@
 # Extract the first word of "gcc", so it can be a program name with args.
 set dummy gcc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1626: checking for $ac_word" >&5
+echo "configure:1627: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1649,7 +1650,7 @@
   # Extract the first word of "cc", so it can be a program name with args.
 set dummy cc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1653: checking for $ac_word" >&5
+echo "configure:1654: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1697,7 +1698,7 @@
       # Extract the first word of "cl", so it can be a program name with args.
 set dummy cl; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1701: checking for $ac_word" >&5
+echo "configure:1702: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1726,7 +1727,7 @@
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
-echo "configure:1730: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:1731: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'
@@ -1739,12 +1740,12 @@
 
 cat > conftest.$ac_ext << EOF
 
-#line 1743 "configure"
+#line 1744 "configure"
 #include "confdefs.h"
 
 main(){return(0);}
 EOF
-if { (eval echo configure:1748: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:1749: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   ac_cv_prog_cc_works=yes
   # If we can't run a trivial program, we are probably using a cross compiler.
   if (./conftest; exit) 2>/dev/null; then
@@ -1772,19 +1773,19 @@
   { echo "configure: error: installation or configuration problem: C compiler cannot create executables." 1>&2; exit 1; }
 fi
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler""... $ac_c" 1>&6
-echo "configure:1776: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:1777: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
 echo "$ac_t""$ac_cv_prog_cc_cross" 1>&6
 cross_compiling=$ac_cv_prog_cc_cross
 
 echo $ac_n "checking whether we are using GNU C""... $ac_c" 1>&6
-echo "configure:1781: checking whether we are using GNU C" >&5
+echo "configure:1782: checking whether we are using GNU C" >&5
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:1788: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
+if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:1789: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no
@@ -1802,7 +1803,7 @@
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
-echo "configure:1806: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:1807: checking whether ${CC-cc} accepts -g" >&5
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
@@ -1835,7 +1836,7 @@
   # Extract the first word of "gcc", so it can be a program name with args.
 set dummy gcc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1839: checking for $ac_word" >&5
+echo "configure:1840: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1862,7 +1863,7 @@
   # Extract the first word of "cc", so it can be a program name with args.
 set dummy cc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1866: checking for $ac_word" >&5
+echo "configure:1867: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1910,7 +1911,7 @@
       # Extract the first word of "cl", so it can be a program name with args.
 set dummy cl; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:1914: checking for $ac_word" >&5
+echo "configure:1915: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -1939,7 +1940,7 @@
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
-echo "configure:1943: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:1944: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'
@@ -1952,12 +1953,12 @@
 
 cat > conftest.$ac_ext << EOF
 
-#line 1956 "configure"
+#line 1957 "configure"
 #include "confdefs.h"
 
 main(){return(0);}
 EOF
-if { (eval echo configure:1961: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:1962: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   ac_cv_prog_cc_works=yes
   # If we can't run a trivial program, we are probably using a cross compiler.
   if (./conftest; exit) 2>/dev/null; then
@@ -1985,19 +1986,19 @@
   { echo "configure: error: installation or configuration problem: C compiler cannot create executables." 1>&2; exit 1; }
 fi
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler""... $ac_c" 1>&6
-echo "configure:1989: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:1990: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
 echo "$ac_t""$ac_cv_prog_cc_cross" 1>&6
 cross_compiling=$ac_cv_prog_cc_cross
 
 echo $ac_n "checking whether we are using GNU C""... $ac_c" 1>&6
-echo "configure:1994: checking whether we are using GNU C" >&5
+echo "configure:1995: checking whether we are using GNU C" >&5
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2001: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
+if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2002: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no
@@ -2015,7 +2016,7 @@
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
-echo "configure:2019: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:2020: checking whether ${CC-cc} accepts -g" >&5
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
@@ -2048,7 +2049,7 @@
   # Extract the first word of "gcc", so it can be a program name with args.
 set dummy gcc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:2052: checking for $ac_word" >&5
+echo "configure:2053: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -2075,7 +2076,7 @@
   # Extract the first word of "cc", so it can be a program name with args.
 set dummy cc; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:2079: checking for $ac_word" >&5
+echo "configure:2080: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -2123,7 +2124,7 @@
       # Extract the first word of "cl", so it can be a program name with args.
 set dummy cl; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:2127: checking for $ac_word" >&5
+echo "configure:2128: checking for $ac_word" >&5
 
 if test -n "$CC"; then
   ac_cv_prog_CC="$CC" # Let the user override the test.
@@ -2152,7 +2153,7 @@
 fi
 
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works""... $ac_c" 1>&6
-echo "configure:2156: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
+echo "configure:2157: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) works" >&5
 
 ac_ext=c
 xe_cppflags='$CPPFLAGS $c_switch_site $c_switch_machine $c_switch_system $c_switch_x_site $X_CFLAGS'
@@ -2165,12 +2166,12 @@
 
 cat > conftest.$ac_ext << EOF
 
-#line 2169 "configure"
+#line 2170 "configure"
 #include "confdefs.h"
 
 main(){return(0);}
 EOF
-if { (eval echo configure:2174: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2175: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   ac_cv_prog_cc_works=yes
   # If we can't run a trivial program, we are probably using a cross compiler.
   if (./conftest; exit) 2>/dev/null; then
@@ -2198,19 +2199,19 @@
   { echo "configure: error: installation or configuration problem: C compiler cannot create executables." 1>&2; exit 1; }
 fi
 echo $ac_n "checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler""... $ac_c" 1>&6
-echo "configure:2202: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
+echo "configure:2203: checking whether the C compiler ($CC $CFLAGS $LDFLAGS) is a cross-compiler" >&5
 echo "$ac_t""$ac_cv_prog_cc_cross" 1>&6
 cross_compiling=$ac_cv_prog_cc_cross
 
 echo $ac_n "checking whether we are using GNU C""... $ac_c" 1>&6
-echo "configure:2207: checking whether we are using GNU C" >&5
+echo "configure:2208: checking whether we are using GNU C" >&5
 
 cat > conftest.c <<EOF
 #ifdef __GNUC__
   yes;
 #endif
 EOF
-if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2214: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
+if { ac_try='${CC-cc} -E conftest.c'; { (eval echo configure:2215: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }; } | egrep yes >/dev/null 2>&1; then
   ac_cv_prog_gcc=yes
 else
   ac_cv_prog_gcc=no
@@ -2228,7 +2229,7 @@
 ac_save_CFLAGS="$CFLAGS"
 CFLAGS=
 echo $ac_n "checking whether ${CC-cc} accepts -g""... $ac_c" 1>&6
-echo "configure:2232: checking whether ${CC-cc} accepts -g" >&5
+echo "configure:2233: checking whether ${CC-cc} accepts -g" >&5
 
 echo 'void f(){}' > conftest.c
 if test -z "`${CC-cc} -g -c conftest.c 2>&1`"; then
@@ -2265,7 +2266,7 @@
 test -n "$NON_GNU_CPP" -a "$GCC" != "yes" -a -z "$CPP" && CPP="$NON_GNU_CPP"
 
 echo $ac_n "checking how to run the C preprocessor""... $ac_c" 1>&6
-echo "configure:2269: checking how to run the C preprocessor" >&5
+echo "configure:2270: checking how to run the C preprocessor" >&5
 # On Suns, sometimes $CPP names a directory.
 if test -n "$CPP" && test -d "$CPP"; then
   CPP=
@@ -2278,13 +2279,13 @@
   # On the NeXT, cc -E runs the code through the compiler's parser,
   # not just through cpp.
   cat > conftest.$ac_ext <<EOF
-#line 2282 "configure"
+#line 2283 "configure"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:2288: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2289: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :
@@ -2295,13 +2296,13 @@
   rm -rf conftest*
   CPP="${CC-cc} -E -traditional-cpp"
   cat > conftest.$ac_ext <<EOF
-#line 2299 "configure"
+#line 2300 "configure"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:2305: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2306: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :
@@ -2312,13 +2313,13 @@
   rm -rf conftest*
   CPP="${CC-cc} -nologo -E"
   cat > conftest.$ac_ext <<EOF
-#line 2316 "configure"
+#line 2317 "configure"
 #include "confdefs.h"
 #include <assert.h>
 Syntax Error
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:2322: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:2323: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   :
@@ -2344,9 +2345,9 @@
 
 
 echo $ac_n "checking for AIX""... $ac_c" 1>&6
-echo "configure:2348: checking for AIX" >&5
+echo "configure:2349: checking for AIX" >&5
 cat > conftest.$ac_ext <<EOF
-#line 2350 "configure"
+#line 2351 "configure"
 #include "confdefs.h"
 #ifdef _AIX
   yes
@@ -2373,9 +2374,9 @@
  
 
 echo $ac_n "checking for GNU libc""... $ac_c" 1>&6
-echo "configure:2377: checking for GNU libc" >&5
+echo "configure:2378: checking for GNU libc" >&5
 cat > conftest.$ac_ext <<EOF
-#line 2379 "configure"
+#line 2380 "configure"
 #include "confdefs.h"
 #include <features.h>
 int main() {
@@ -2387,7 +2388,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:2391: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:2392: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   have_glibc=yes
 else
@@ -2464,7 +2465,7 @@
 esac
 
 cat > conftest.$ac_ext <<EOF
-#line 2468 "configure"
+#line 2469 "configure"
 #include "confdefs.h"
 int main () {
 #if defined __SUNPRO_C
@@ -2478,7 +2479,7 @@
 #endif
 }
 EOF
-if { (eval echo configure:2482: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:2483: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   :
 else
@@ -2712,17 +2713,17 @@
 
 if test "$__USLC__" = yes; then
   echo $ac_n "checking for whether the -Kalloca compiler flag is needed""... $ac_c" 1>&6
-echo "configure:2716: checking for whether the -Kalloca compiler flag is needed" >&5
+echo "configure:2717: checking for whether the -Kalloca compiler flag is needed" >&5
   need_kalloca=no
   cat > conftest.$ac_ext <<EOF
-#line 2719 "configure"
+#line 2720 "configure"
 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF
-if { (eval echo configure:2726: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2727: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   :
 else
@@ -2733,14 +2734,14 @@
     xe_save_c_switch_system="$c_switch_system"
     c_switch_system="$c_switch_system -Kalloca"
     cat > conftest.$ac_ext <<EOF
-#line 2737 "configure"
+#line 2738 "configure"
 #include "confdefs.h"
 
 int main() {
 void *x = alloca(4);
 ; return 0; }
 EOF
-if { (eval echo configure:2744: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2745: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
    need_kalloca=yes 
 else
@@ -2775,7 +2776,7 @@
 
 if test "$GCC" = "yes"; then
 echo $ac_n "checking for buggy gcc versions""... $ac_c" 1>&6
-echo "configure:2779: checking for buggy gcc versions" >&5
+echo "configure:2780: checking for buggy gcc versions" >&5
 GCC_VERSION=`$CC --version`
 case `uname -s`:`uname -m`:$GCC_VERSION in
 		    *:sun4*:2.8.1|*:sun4*:egcs-2.90.*)
@@ -2898,7 +2899,7 @@
  fi
 
 echo $ac_n "checking for dynodump""... $ac_c" 1>&6
-echo "configure:2902: checking for dynodump" >&5
+echo "configure:2903: checking for dynodump" >&5
 if test "$unexec" != "unexsol2.o"; then
   echo "$ac_t""no" 1>&6
 else
@@ -2936,12 +2937,12 @@
   done
   
 echo $ac_n "checking for terminateAndUnload in -lC""... $ac_c" 1>&6
-echo "configure:2940: checking for terminateAndUnload in -lC" >&5
+echo "configure:2941: checking for terminateAndUnload in -lC" >&5
 ac_lib_var=`echo C'_'terminateAndUnload | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lC "
 cat > conftest.$ac_ext <<EOF
-#line 2945 "configure"
+#line 2946 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -2952,7 +2953,7 @@
 terminateAndUnload()
 ; return 0; }
 EOF
-if { (eval echo configure:2956: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:2957: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -3060,7 +3061,7 @@
 
 if test "$add_runtime_path" = "yes"; then
       echo $ac_n "checking "for runtime libraries flag"""... $ac_c" 1>&6
-echo "configure:3064: checking "for runtime libraries flag"" >&5
+echo "configure:3065: checking "for runtime libraries flag"" >&5
   case "$opsys" in
     sol2 ) dash_r="-R" ;;
     decosf* | linux* | irix*) dash_r="-rpath " ;;
@@ -3082,14 +3083,14 @@
   done
 fi
         cat > conftest.$ac_ext <<EOF
-#line 3086 "configure"
+#line 3087 "configure"
 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
-if { (eval echo configure:3093: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3094: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   dash_r="$try_dash_r"
 else
@@ -3190,10 +3191,10 @@
 fi
 after_morecore_hook_exists=yes
 echo $ac_n "checking for malloc_set_state""... $ac_c" 1>&6
-echo "configure:3194: checking for malloc_set_state" >&5
+echo "configure:3195: checking for malloc_set_state" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3197 "configure"
+#line 3198 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char malloc_set_state(); below.  */
@@ -3216,7 +3217,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:3220: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3221: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_malloc_set_state=yes"
 else
@@ -3236,16 +3237,16 @@
 fi
 
 echo $ac_n "checking whether __after_morecore_hook exists""... $ac_c" 1>&6
-echo "configure:3240: checking whether __after_morecore_hook exists" >&5
+echo "configure:3241: checking whether __after_morecore_hook exists" >&5
 cat > conftest.$ac_ext <<EOF
-#line 3242 "configure"
+#line 3243 "configure"
 #include "confdefs.h"
 extern void (* __after_morecore_hook)();
 int main() {
 __after_morecore_hook = 0
 ; return 0; }
 EOF
-if { (eval echo configure:3249: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3250: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else
@@ -3301,7 +3302,7 @@
 # Extract the first word of "ranlib", so it can be a program name with args.
 set dummy ranlib; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:3305: checking for $ac_word" >&5
+echo "configure:3306: checking for $ac_word" >&5
 
 if test -n "$RANLIB"; then
   ac_cv_prog_RANLIB="$RANLIB" # Let the user override the test.
@@ -3356,7 +3357,7 @@
 # SVR4 /usr/ucb/install, which tries to use the nonexistent group "staff"
 # ./install, which can be erroneously created by make from ./install.sh.
 echo $ac_n "checking for a BSD compatible install""... $ac_c" 1>&6
-echo "configure:3360: checking for a BSD compatible install" >&5
+echo "configure:3361: checking for a BSD compatible install" >&5
 if test -z "$INSTALL"; then
 
   IFS="${IFS= 	}"; ac_save_IFS="$IFS"; IFS=":"
@@ -3410,7 +3411,7 @@
 # Extract the first word of "$ac_prog", so it can be a program name with args.
 set dummy $ac_prog; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:3414: checking for $ac_word" >&5
+echo "configure:3415: checking for $ac_word" >&5
 
 if test -n "$YACC"; then
   ac_cv_prog_YACC="$YACC" # Let the user override the test.
@@ -3442,15 +3443,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:3446: checking for $ac_hdr" >&5
+echo "configure:3447: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3449 "configure"
+#line 3450 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:3454: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:3455: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -3480,10 +3481,10 @@
 done
 
 echo $ac_n "checking for sys/wait.h that is POSIX.1 compatible""... $ac_c" 1>&6
-echo "configure:3484: checking for sys/wait.h that is POSIX.1 compatible" >&5
+echo "configure:3485: checking for sys/wait.h that is POSIX.1 compatible" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3487 "configure"
+#line 3488 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/wait.h>
@@ -3499,7 +3500,7 @@
 s = WIFEXITED (s) ? WEXITSTATUS (s) : 1;
 ; return 0; }
 EOF
-if { (eval echo configure:3503: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3504: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_header_sys_wait_h=yes
 else
@@ -3523,10 +3524,10 @@
 fi
 
 echo $ac_n "checking for ANSI C header files""... $ac_c" 1>&6
-echo "configure:3527: checking for ANSI C header files" >&5
+echo "configure:3528: checking for ANSI C header files" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3530 "configure"
+#line 3531 "configure"
 #include "confdefs.h"
 #include <stdlib.h>
 #include <stdarg.h>
@@ -3534,7 +3535,7 @@
 #include <float.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:3538: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:3539: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -3551,7 +3552,7 @@
 if test $ac_cv_header_stdc = yes; then
   # SunOS 4.x string.h does not declare mem*, contrary to ANSI.
 cat > conftest.$ac_ext <<EOF
-#line 3555 "configure"
+#line 3556 "configure"
 #include "confdefs.h"
 #include <string.h>
 EOF
@@ -3569,7 +3570,7 @@
 if test $ac_cv_header_stdc = yes; then
   # ISC 2.0.2 stdlib.h does not declare free, contrary to ANSI.
 cat > conftest.$ac_ext <<EOF
-#line 3573 "configure"
+#line 3574 "configure"
 #include "confdefs.h"
 #include <stdlib.h>
 EOF
@@ -3587,7 +3588,7 @@
 if test $ac_cv_header_stdc = yes; then
   # /bin/cc in Irix-4.0.5 gets non-ANSI ctype macros unless using -ansi.
 cat > conftest.$ac_ext <<EOF
-#line 3591 "configure"
+#line 3592 "configure"
 #include "confdefs.h"
 #include <ctype.h>
 #define ISLOWER(c) ('a' <= (c) && (c) <= 'z')
@@ -3598,7 +3599,7 @@
 exit (0); }
 
 EOF
-if { (eval echo configure:3602: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:3603: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   :
 else
@@ -3624,10 +3625,10 @@
 fi
 
 echo $ac_n "checking whether time.h and sys/time.h may both be included""... $ac_c" 1>&6
-echo "configure:3628: checking whether time.h and sys/time.h may both be included" >&5
+echo "configure:3629: checking whether time.h and sys/time.h may both be included" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3631 "configure"
+#line 3632 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/time.h>
@@ -3636,7 +3637,7 @@
 struct tm *tp;
 ; return 0; }
 EOF
-if { (eval echo configure:3640: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3641: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_header_time=yes
 else
@@ -3660,10 +3661,10 @@
 fi
 
 echo $ac_n "checking for sys_siglist declaration in signal.h or unistd.h""... $ac_c" 1>&6
-echo "configure:3664: checking for sys_siglist declaration in signal.h or unistd.h" >&5
+echo "configure:3665: checking for sys_siglist declaration in signal.h or unistd.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3667 "configure"
+#line 3668 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>
@@ -3675,7 +3676,7 @@
 char *msg = *(sys_siglist + 1);
 ; return 0; }
 EOF
-if { (eval echo configure:3679: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3680: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_decl_sys_siglist=yes
 else
@@ -3701,9 +3702,9 @@
 
 
 echo $ac_n "checking for utime""... $ac_c" 1>&6
-echo "configure:3705: checking for utime" >&5
+echo "configure:3706: checking for utime" >&5
 cat > conftest.$ac_ext <<EOF
-#line 3707 "configure"
+#line 3708 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <utime.h>
@@ -3711,7 +3712,7 @@
 struct utimbuf x; x.actime = x.modtime = 0; utime ("/", &x);
 ; return 0; }
 EOF
-if { (eval echo configure:3715: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3716: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF
@@ -3730,10 +3731,10 @@
       for ac_func in utimes
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:3734: checking for $ac_func" >&5
+echo "configure:3735: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3737 "configure"
+#line 3738 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -3756,7 +3757,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:3760: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:3761: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -3788,10 +3789,10 @@
 
 
 echo $ac_n "checking return type of signal handlers""... $ac_c" 1>&6
-echo "configure:3792: checking return type of signal handlers" >&5
+echo "configure:3793: checking return type of signal handlers" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3795 "configure"
+#line 3796 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <signal.h>
@@ -3808,7 +3809,7 @@
 int i;
 ; return 0; }
 EOF
-if { (eval echo configure:3812: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:3813: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_type_signal=void
 else
@@ -3830,10 +3831,10 @@
 
 
 echo $ac_n "checking for size_t""... $ac_c" 1>&6
-echo "configure:3834: checking for size_t" >&5
+echo "configure:3835: checking for size_t" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3837 "configure"
+#line 3838 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
@@ -3864,10 +3865,10 @@
 fi
 
 echo $ac_n "checking for pid_t""... $ac_c" 1>&6
-echo "configure:3868: checking for pid_t" >&5
+echo "configure:3869: checking for pid_t" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3871 "configure"
+#line 3872 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
@@ -3898,10 +3899,10 @@
 fi
 
 echo $ac_n "checking for uid_t in sys/types.h""... $ac_c" 1>&6
-echo "configure:3902: checking for uid_t in sys/types.h" >&5
+echo "configure:3903: checking for uid_t in sys/types.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3905 "configure"
+#line 3906 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 EOF
@@ -3937,10 +3938,10 @@
 fi
 
 echo $ac_n "checking for mode_t""... $ac_c" 1>&6
-echo "configure:3941: checking for mode_t" >&5
+echo "configure:3942: checking for mode_t" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3944 "configure"
+#line 3945 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
@@ -3971,10 +3972,10 @@
 fi
 
 echo $ac_n "checking for off_t""... $ac_c" 1>&6
-echo "configure:3975: checking for off_t" >&5
+echo "configure:3976: checking for off_t" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 3978 "configure"
+#line 3979 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
@@ -4005,10 +4006,10 @@
 fi
 
 echo $ac_n "checking for ssize_t""... $ac_c" 1>&6
-echo "configure:4009: checking for ssize_t" >&5
+echo "configure:4010: checking for ssize_t" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4012 "configure"
+#line 4013 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #if STDC_HEADERS
@@ -4040,9 +4041,9 @@
 
 
 echo $ac_n "checking for socklen_t""... $ac_c" 1>&6
-echo "configure:4044: checking for socklen_t" >&5
+echo "configure:4045: checking for socklen_t" >&5
 cat > conftest.$ac_ext <<EOF
-#line 4046 "configure"
+#line 4047 "configure"
 #include "confdefs.h"
 #include <sys/socket.h>
 socklen_t x;
@@ -4051,7 +4052,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:4055: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4056: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else
@@ -4060,7 +4061,7 @@
   rm -rf conftest*
   
 cat > conftest.$ac_ext <<EOF
-#line 4064 "configure"
+#line 4065 "configure"
 #include "confdefs.h"
 #include <sys/socket.h>
 int accept (int, struct sockaddr *, size_t *);
@@ -4069,7 +4070,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:4073: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4074: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   
 echo "$ac_t""size_t" 1>&6
@@ -4101,9 +4102,9 @@
 rm -f conftest*
 
 echo $ac_n "checking for struct timeval""... $ac_c" 1>&6
-echo "configure:4105: checking for struct timeval" >&5
+echo "configure:4106: checking for struct timeval" >&5
 cat > conftest.$ac_ext <<EOF
-#line 4107 "configure"
+#line 4108 "configure"
 #include "confdefs.h"
 #ifdef TIME_WITH_SYS_TIME
 #include <sys/time.h>
@@ -4119,7 +4120,7 @@
 static struct timeval x; x.tv_sec = x.tv_usec;
 ; return 0; }
 EOF
-if { (eval echo configure:4123: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4124: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
   HAVE_TIMEVAL=yes
@@ -4141,10 +4142,10 @@
 rm -f conftest*
 
 echo $ac_n "checking whether struct tm is in sys/time.h or time.h""... $ac_c" 1>&6
-echo "configure:4145: checking whether struct tm is in sys/time.h or time.h" >&5
+echo "configure:4146: checking whether struct tm is in sys/time.h or time.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4148 "configure"
+#line 4149 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <time.h>
@@ -4152,7 +4153,7 @@
 struct tm *tp; tp->tm_sec;
 ; return 0; }
 EOF
-if { (eval echo configure:4156: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4157: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_struct_tm=time.h
 else
@@ -4176,10 +4177,10 @@
 fi
 
 echo $ac_n "checking for tm_zone in struct tm""... $ac_c" 1>&6
-echo "configure:4180: checking for tm_zone in struct tm" >&5
+echo "configure:4181: checking for tm_zone in struct tm" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4183 "configure"
+#line 4184 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <$ac_cv_struct_tm>
@@ -4187,7 +4188,7 @@
 struct tm tm; tm.tm_zone;
 ; return 0; }
 EOF
-if { (eval echo configure:4191: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4192: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_struct_tm_zone=yes
 else
@@ -4210,10 +4211,10 @@
 
 else
   echo $ac_n "checking for tzname""... $ac_c" 1>&6
-echo "configure:4214: checking for tzname" >&5
+echo "configure:4215: checking for tzname" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4217 "configure"
+#line 4218 "configure"
 #include "confdefs.h"
 #include <time.h>
 #ifndef tzname /* For SGI.  */
@@ -4223,7 +4224,7 @@
 atoi(*tzname);
 ; return 0; }
 EOF
-if { (eval echo configure:4227: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4228: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   ac_cv_var_tzname=yes
 else
@@ -4249,16 +4250,16 @@
 
 
 echo $ac_n "checking for working const""... $ac_c" 1>&6
-echo "configure:4253: checking for working const" >&5
+echo "configure:4254: checking for working const" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4256 "configure"
+#line 4257 "configure"
 #include "confdefs.h"
 
 int main() {
 
 /* Ultrix mips cc rejects this.  */
-typedef int charset[2]; const charset x = {0,0};
+typedef int charset[2]; const charset x;
 /* SunOS 4.1.1 cc rejects this.  */
 char const *const *ccp;
 char **p;
@@ -4301,7 +4302,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:4305: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4306: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_c_const=yes
 else
@@ -4326,7 +4327,7 @@
 
 
 echo $ac_n "checking whether ${MAKE-make} sets \${MAKE}""... $ac_c" 1>&6
-echo "configure:4330: checking whether ${MAKE-make} sets \${MAKE}" >&5
+echo "configure:4331: checking whether ${MAKE-make} sets \${MAKE}" >&5
 set dummy ${MAKE-make}; ac_make=`echo "$2" | sed 'y%./+-%__p_%'`
 
 cat > conftestmake <<\EOF
@@ -4351,12 +4352,12 @@
 
 
 echo $ac_n "checking whether byte ordering is bigendian""... $ac_c" 1>&6
-echo "configure:4355: checking whether byte ordering is bigendian" >&5
+echo "configure:4356: checking whether byte ordering is bigendian" >&5
 
 ac_cv_c_bigendian=unknown
 # See if sys/param.h defines the BYTE_ORDER macro.
 cat > conftest.$ac_ext <<EOF
-#line 4360 "configure"
+#line 4361 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>
@@ -4367,11 +4368,11 @@
 #endif
 ; return 0; }
 EOF
-if { (eval echo configure:4371: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4372: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   # It does; now see whether it defined to BIG_ENDIAN or not.
 cat > conftest.$ac_ext <<EOF
-#line 4375 "configure"
+#line 4376 "configure"
 #include "confdefs.h"
 #include <sys/types.h>
 #include <sys/param.h>
@@ -4382,7 +4383,7 @@
 #endif
 ; return 0; }
 EOF
-if { (eval echo configure:4386: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:4387: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_c_bigendian=yes
 else
@@ -4399,7 +4400,7 @@
 rm -f conftest*
 if test $ac_cv_c_bigendian = unknown; then
 cat > conftest.$ac_ext <<EOF
-#line 4403 "configure"
+#line 4404 "configure"
 #include "confdefs.h"
 main () {
   /* Are we little or big endian?  From Harbison&Steele.  */
@@ -4412,7 +4413,7 @@
   exit (u.c[sizeof (long) - 1] == 1);
 }
 EOF
-if { (eval echo configure:4416: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4417: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_c_bigendian=no
 else
@@ -4439,12 +4440,13 @@
 
 
 echo $ac_n "checking size of short""... $ac_c" 1>&6
-echo "configure:4443: checking size of short" >&5
+echo "configure:4444: checking size of short" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4446 "configure"
+#line 4447 "configure"
 #include "confdefs.h"
 #include <stdio.h>
+#include <sys/types.h>
 main()
 {
   FILE *f=fopen("conftestval", "w");
@@ -4453,7 +4455,7 @@
   exit(0);
 }
 EOF
-if { (eval echo configure:4457: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4459: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_sizeof_short=`cat conftestval`
 else
@@ -4481,12 +4483,13 @@
   exit 1
 fi
 echo $ac_n "checking size of int""... $ac_c" 1>&6
-echo "configure:4485: checking size of int" >&5
+echo "configure:4487: checking size of int" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4488 "configure"
+#line 4490 "configure"
 #include "confdefs.h"
 #include <stdio.h>
+#include <sys/types.h>
 main()
 {
   FILE *f=fopen("conftestval", "w");
@@ -4495,7 +4498,7 @@
   exit(0);
 }
 EOF
-if { (eval echo configure:4499: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4502: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_sizeof_int=`cat conftestval`
 else
@@ -4517,12 +4520,13 @@
 
 
 echo $ac_n "checking size of long""... $ac_c" 1>&6
-echo "configure:4521: checking size of long" >&5
+echo "configure:4524: checking size of long" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4524 "configure"
+#line 4527 "configure"
 #include "confdefs.h"
 #include <stdio.h>
+#include <sys/types.h>
 main()
 {
   FILE *f=fopen("conftestval", "w");
@@ -4531,7 +4535,7 @@
   exit(0);
 }
 EOF
-if { (eval echo configure:4535: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4539: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_sizeof_long=`cat conftestval`
 else
@@ -4553,12 +4557,13 @@
 
 
 echo $ac_n "checking size of long long""... $ac_c" 1>&6
-echo "configure:4557: checking size of long long" >&5
+echo "configure:4561: checking size of long long" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4560 "configure"
+#line 4564 "configure"
 #include "confdefs.h"
 #include <stdio.h>
+#include <sys/types.h>
 main()
 {
   FILE *f=fopen("conftestval", "w");
@@ -4567,7 +4572,7 @@
   exit(0);
 }
 EOF
-if { (eval echo configure:4571: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4576: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_sizeof_long_long=`cat conftestval`
 else
@@ -4589,12 +4594,13 @@
 
 
 echo $ac_n "checking size of void *""... $ac_c" 1>&6
-echo "configure:4593: checking size of void *" >&5
+echo "configure:4598: checking size of void *" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4596 "configure"
+#line 4601 "configure"
 #include "confdefs.h"
 #include <stdio.h>
+#include <sys/types.h>
 main()
 {
   FILE *f=fopen("conftestval", "w");
@@ -4603,7 +4609,7 @@
   exit(0);
 }
 EOF
-if { (eval echo configure:4607: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:4613: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_sizeof_void_p=`cat conftestval`
 else
@@ -4626,7 +4632,7 @@
 
 
 echo $ac_n "checking for long file names""... $ac_c" 1>&6
-echo "configure:4630: checking for long file names" >&5
+echo "configure:4636: checking for long file names" >&5
 
 ac_cv_sys_long_file_names=yes
 # Test for long file names in all the places we know might matter:
@@ -4672,10 +4678,10 @@
 
 
 echo $ac_n "checking for sin""... $ac_c" 1>&6
-echo "configure:4676: checking for sin" >&5
+echo "configure:4682: checking for sin" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4679 "configure"
+#line 4685 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char sin(); below.  */
@@ -4698,7 +4704,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:4702: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4708: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_sin=yes"
 else
@@ -4716,12 +4722,12 @@
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for sin in -lm""... $ac_c" 1>&6
-echo "configure:4720: checking for sin in -lm" >&5
+echo "configure:4726: checking for sin in -lm" >&5
 ac_lib_var=`echo m'_'sin | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lm "
 cat > conftest.$ac_ext <<EOF
-#line 4725 "configure"
+#line 4731 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -4732,7 +4738,7 @@
 sin()
 ; return 0; }
 EOF
-if { (eval echo configure:4736: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4742: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -4776,14 +4782,14 @@
 
 
 cat > conftest.$ac_ext <<EOF
-#line 4780 "configure"
+#line 4786 "configure"
 #include "confdefs.h"
 #include <math.h>
 int main() {
 return atanh(1.0) + asinh(1.0) + acosh(1.0); 
 ; return 0; }
 EOF
-if { (eval echo configure:4787: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4793: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_INVERSE_HYPERBOLIC
@@ -4800,14 +4806,14 @@
 rm -f conftest*
 
 echo "checking type of mail spool file locking" 1>&6
-echo "configure:4804: checking type of mail spool file locking" >&5
+echo "configure:4810: checking type of mail spool file locking" >&5
 for ac_func in lockf flock
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:4808: checking for $ac_func" >&5
+echo "configure:4814: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 4811 "configure"
+#line 4817 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -4830,7 +4836,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:4834: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4840: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -4912,12 +4918,12 @@
 case "$opsys" in decosf*)
   
 echo $ac_n "checking for cma_open in -lpthreads""... $ac_c" 1>&6
-echo "configure:4916: checking for cma_open in -lpthreads" >&5
+echo "configure:4922: checking for cma_open in -lpthreads" >&5
 ac_lib_var=`echo pthreads'_'cma_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpthreads "
 cat > conftest.$ac_ext <<EOF
-#line 4921 "configure"
+#line 4927 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -4928,7 +4934,7 @@
 cma_open()
 ; return 0; }
 EOF
-if { (eval echo configure:4932: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:4938: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -4964,7 +4970,7 @@
 esac
 
 echo $ac_n "checking whether the -xildoff compiler flag is required""... $ac_c" 1>&6
-echo "configure:4968: checking whether the -xildoff compiler flag is required" >&5
+echo "configure:4974: checking whether the -xildoff compiler flag is required" >&5
 if   ${CC-cc} '-###' -xildon  no_such_file.c 2>&1 | grep '^[^ ]*/ild ' > /dev/null ; then
   if ${CC-cc} '-###' -xildoff no_such_file.c 2>&1 | grep '^[^ ]*/ild ' > /dev/null ;
     then echo "$ac_t""no" 1>&6;
@@ -4976,7 +4982,7 @@
 if test "$opsys" = "sol2"; then
   if test "$os_release" -ge 56; then
     echo $ac_n "checking for \"-z ignore\" linker flag""... $ac_c" 1>&6
-echo "configure:4980: checking for \"-z ignore\" linker flag" >&5
+echo "configure:4986: checking for \"-z ignore\" linker flag" >&5
     case "`ld -h 2>&1`" in
       *-z\ ignore\|record* ) echo "$ac_t""yes" 1>&6
         ld_switch_site="-z ignore $ld_switch_site" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-z ignore\" to \$ld_switch_site"; fi ;;
@@ -4987,7 +4993,7 @@
 
 
 echo "checking "for specified window system"" 1>&6
-echo "configure:4991: checking "for specified window system"" >&5
+echo "configure:4997: checking "for specified window system"" >&5
 
 
 GNOME_CONFIG=no
@@ -4995,7 +5001,7 @@
 
 if test "$with_gnome" != "no"; then
    echo $ac_n "checking for GNOME configuration script""... $ac_c" 1>&6
-echo "configure:4999: checking for GNOME configuration script" >&5
+echo "configure:5005: checking for GNOME configuration script" >&5
    for possible in gnome-config
    do
       possible_version=`${possible} --version 2> /dev/null`
@@ -5026,7 +5032,7 @@
 
 if test "$with_gtk" != "no";then
    echo $ac_n "checking for GTK configuration script""... $ac_c" 1>&6
-echo "configure:5030: checking for GTK configuration script" >&5
+echo "configure:5036: checking for GTK configuration script" >&5
    for possible in gtk12-config gtk14-config gtk-config
    do
       possible_version=`${possible} --version 2> /dev/null`
@@ -5048,37 +5054,37 @@
 
 if test "${GTK_CONFIG}" != "no"; then
       echo $ac_n "checking gtk version""... $ac_c" 1>&6
-echo "configure:5052: checking gtk version" >&5
+echo "configure:5058: checking gtk version" >&5
       GTK_VERSION=`${GTK_CONFIG} --version`
       echo "$ac_t""${GTK_VERSION}" 1>&6
 
       echo $ac_n "checking gtk libs""... $ac_c" 1>&6
-echo "configure:5057: checking gtk libs" >&5
+echo "configure:5063: checking gtk libs" >&5
       GTK_LIBS=`${GTK_CONFIG} --libs`
       libs_gtk="$libs_gtk ${GTK_LIBS}" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"${GTK_LIBS}\" to \$libs_gtk"; fi
       echo "$ac_t""${GTK_LIBS}" 1>&6
 
       echo $ac_n "checking gtk cflags""... $ac_c" 1>&6
-echo "configure:5063: checking gtk cflags" >&5
+echo "configure:5069: checking gtk cflags" >&5
       GTK_CFLAGS=`${GTK_CONFIG} --cflags`
       c_switch_gtk="$c_switch_gtk ${GTK_CFLAGS}" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"${GTK_CFLAGS}\" to \$c_switch_gtk"; fi
       echo "$ac_t""${GTK_CFLAGS}" 1>&6
 
       
 echo $ac_n "checking for main in -lgdk_imlib""... $ac_c" 1>&6
-echo "configure:5070: checking for main in -lgdk_imlib" >&5
+echo "configure:5076: checking for main in -lgdk_imlib" >&5
 ac_lib_var=`echo gdk_imlib'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdk_imlib "
 cat > conftest.$ac_ext <<EOF
-#line 5075 "configure"
+#line 5081 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:5082: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5088: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5100,12 +5106,12 @@
 
       
 echo $ac_n "checking for Imlib_init in -lImlib""... $ac_c" 1>&6
-echo "configure:5104: checking for Imlib_init in -lImlib" >&5
+echo "configure:5110: checking for Imlib_init in -lImlib" >&5
 ac_lib_var=`echo Imlib'_'Imlib_init | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lImlib "
 cat > conftest.$ac_ext <<EOF
-#line 5109 "configure"
+#line 5115 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -5116,7 +5122,7 @@
 Imlib_init()
 ; return 0; }
 EOF
-if { (eval echo configure:5120: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5126: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5139,10 +5145,10 @@
       for ac_func in gdk_imlib_init
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:5143: checking for $ac_func" >&5
+echo "configure:5149: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 5146 "configure"
+#line 5152 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -5165,7 +5171,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:5169: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5175: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -5242,15 +5248,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:5246: checking for $ac_hdr" >&5
+echo "configure:5252: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 5249 "configure"
+#line 5255 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:5254: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:5260: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -5281,19 +5287,19 @@
 
       
 echo $ac_n "checking for main in -lxml""... $ac_c" 1>&6
-echo "configure:5285: checking for main in -lxml" >&5
+echo "configure:5291: checking for main in -lxml" >&5
 ac_lib_var=`echo xml'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lxml "
 cat > conftest.$ac_ext <<EOF
-#line 5290 "configure"
+#line 5296 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:5297: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5303: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5315,19 +5321,19 @@
 
       
 echo $ac_n "checking for main in -lglade""... $ac_c" 1>&6
-echo "configure:5319: checking for main in -lglade" >&5
+echo "configure:5325: checking for main in -lglade" >&5
 ac_lib_var=`echo glade'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lglade "
 cat > conftest.$ac_ext <<EOF
-#line 5324 "configure"
+#line 5330 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:5331: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5337: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5349,19 +5355,19 @@
 
       
 echo $ac_n "checking for main in -lglade-gnome""... $ac_c" 1>&6
-echo "configure:5353: checking for main in -lglade-gnome" >&5
+echo "configure:5359: checking for main in -lglade-gnome" >&5
 ac_lib_var=`echo glade-gnome'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lglade-gnome "
 cat > conftest.$ac_ext <<EOF
-#line 5358 "configure"
+#line 5364 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:5365: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5371: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5382,7 +5388,7 @@
 
 
       cat > conftest.$ac_ext <<EOF
-#line 5386 "configure"
+#line 5392 "configure"
 #include "confdefs.h"
 #include <glade/glade-xml.h>
 EOF
@@ -5440,7 +5446,7 @@
 # Uses ac_ vars as temps to allow command line to override cache and checks.
 # --without-x overrides everything else, but does not touch the cache.
 echo $ac_n "checking for X""... $ac_c" 1>&6
-echo "configure:5444: checking for X" >&5
+echo "configure:5450: checking for X" >&5
 
 # Check whether --with-x or --without-x was given.
 if test "${with_x+set}" = set; then
@@ -5500,12 +5506,12 @@
 
   # First, try using that file with no special directory specified.
 cat > conftest.$ac_ext <<EOF
-#line 5504 "configure"
+#line 5510 "configure"
 #include "confdefs.h"
 #include <$x_direct_test_include>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:5509: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:5515: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -5574,14 +5580,14 @@
   ac_save_LIBS="$LIBS"
   LIBS="-l$x_direct_test_library $LIBS"
 cat > conftest.$ac_ext <<EOF
-#line 5578 "configure"
+#line 5584 "configure"
 #include "confdefs.h"
 
 int main() {
 ${x_direct_test_function}()
 ; return 0; }
 EOF
-if { (eval echo configure:5585: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5591: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   LIBS="$ac_save_LIBS"
 # We can link X programs with no special library path.
@@ -5690,17 +5696,17 @@
     case "`(uname -sr) 2>/dev/null`" in
     "SunOS 5"*)
       echo $ac_n "checking whether -R must be followed by a space""... $ac_c" 1>&6
-echo "configure:5694: checking whether -R must be followed by a space" >&5
+echo "configure:5700: checking whether -R must be followed by a space" >&5
       ac_xsave_LIBS="$LIBS"; LIBS="$LIBS -R$x_libraries"
       cat > conftest.$ac_ext <<EOF
-#line 5697 "configure"
+#line 5703 "configure"
 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
-if { (eval echo configure:5704: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5710: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   ac_R_nospace=yes
 else
@@ -5716,14 +5722,14 @@
       else
 	LIBS="$ac_xsave_LIBS -R $x_libraries"
 	cat > conftest.$ac_ext <<EOF
-#line 5720 "configure"
+#line 5726 "configure"
 #include "confdefs.h"
 
 int main() {
 
 ; return 0; }
 EOF
-if { (eval echo configure:5727: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5733: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   ac_R_space=yes
 else
@@ -5759,12 +5765,12 @@
 else
 
 echo $ac_n "checking for dnet_ntoa in -ldnet""... $ac_c" 1>&6
-echo "configure:5763: checking for dnet_ntoa in -ldnet" >&5
+echo "configure:5769: checking for dnet_ntoa in -ldnet" >&5
 ac_lib_var=`echo dnet'_'dnet_ntoa | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldnet "
 cat > conftest.$ac_ext <<EOF
-#line 5768 "configure"
+#line 5774 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -5775,7 +5781,7 @@
 dnet_ntoa()
 ; return 0; }
 EOF
-if { (eval echo configure:5779: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5785: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5799,12 +5805,12 @@
     if test $ac_cv_lib_dnet_dnet_ntoa = no; then
       
 echo $ac_n "checking for dnet_ntoa in -ldnet_stub""... $ac_c" 1>&6
-echo "configure:5803: checking for dnet_ntoa in -ldnet_stub" >&5
+echo "configure:5809: checking for dnet_ntoa in -ldnet_stub" >&5
 ac_lib_var=`echo dnet_stub'_'dnet_ntoa | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldnet_stub "
 cat > conftest.$ac_ext <<EOF
-#line 5808 "configure"
+#line 5814 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -5815,7 +5821,7 @@
 dnet_ntoa()
 ; return 0; }
 EOF
-if { (eval echo configure:5819: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5825: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5844,10 +5850,10 @@
     # The nsl library prevents programs from opening the X display
     # on Irix 5.2, according to dickey@clark.net.
     echo $ac_n "checking for gethostbyname""... $ac_c" 1>&6
-echo "configure:5848: checking for gethostbyname" >&5
+echo "configure:5854: checking for gethostbyname" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 5851 "configure"
+#line 5857 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char gethostbyname(); below.  */
@@ -5870,7 +5876,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:5874: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5880: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_gethostbyname=yes"
 else
@@ -5891,12 +5897,12 @@
     if test $ac_cv_func_gethostbyname = no; then
       
 echo $ac_n "checking for gethostbyname in -lnsl""... $ac_c" 1>&6
-echo "configure:5895: checking for gethostbyname in -lnsl" >&5
+echo "configure:5901: checking for gethostbyname in -lnsl" >&5
 ac_lib_var=`echo nsl'_'gethostbyname | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lnsl "
 cat > conftest.$ac_ext <<EOF
-#line 5900 "configure"
+#line 5906 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -5907,7 +5913,7 @@
 gethostbyname()
 ; return 0; }
 EOF
-if { (eval echo configure:5911: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5917: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -5937,10 +5943,10 @@
     # -lsocket must be given before -lnsl if both are needed.
     # We assume that if connect needs -lnsl, so does gethostbyname.
     echo $ac_n "checking for connect""... $ac_c" 1>&6
-echo "configure:5941: checking for connect" >&5
+echo "configure:5947: checking for connect" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 5944 "configure"
+#line 5950 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char connect(); below.  */
@@ -5963,7 +5969,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:5967: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:5973: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_connect=yes"
 else
@@ -5986,12 +5992,12 @@
 xe_msg_checking="for connect in -lsocket"
 test -n "$X_EXTRA_LIBS" && xe_msg_checking="$xe_msg_checking using extra libs $X_EXTRA_LIBS"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:5990: checking "$xe_msg_checking"" >&5
+echo "configure:5996: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo socket'_'connect | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lsocket $X_EXTRA_LIBS"
 cat > conftest.$ac_ext <<EOF
-#line 5995 "configure"
+#line 6001 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6002,7 +6008,7 @@
 connect()
 ; return 0; }
 EOF
-if { (eval echo configure:6006: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6012: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6026,10 +6032,10 @@
 
     # gomez@mi.uni-erlangen.de says -lposix is necessary on A/UX.
     echo $ac_n "checking for remove""... $ac_c" 1>&6
-echo "configure:6030: checking for remove" >&5
+echo "configure:6036: checking for remove" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6033 "configure"
+#line 6039 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char remove(); below.  */
@@ -6052,7 +6058,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:6056: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6062: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_remove=yes"
 else
@@ -6073,12 +6079,12 @@
     if test $ac_cv_func_remove = no; then
       
 echo $ac_n "checking for remove in -lposix""... $ac_c" 1>&6
-echo "configure:6077: checking for remove in -lposix" >&5
+echo "configure:6083: checking for remove in -lposix" >&5
 ac_lib_var=`echo posix'_'remove | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lposix "
 cat > conftest.$ac_ext <<EOF
-#line 6082 "configure"
+#line 6088 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6089,7 +6095,7 @@
 remove()
 ; return 0; }
 EOF
-if { (eval echo configure:6093: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6099: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6113,10 +6119,10 @@
 
     # BSDI BSD/OS 2.1 needs -lipc for XOpenDisplay.
     echo $ac_n "checking for shmat""... $ac_c" 1>&6
-echo "configure:6117: checking for shmat" >&5
+echo "configure:6123: checking for shmat" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6120 "configure"
+#line 6126 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char shmat(); below.  */
@@ -6139,7 +6145,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:6143: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6149: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_shmat=yes"
 else
@@ -6160,12 +6166,12 @@
     if test $ac_cv_func_shmat = no; then
       
 echo $ac_n "checking for shmat in -lipc""... $ac_c" 1>&6
-echo "configure:6164: checking for shmat in -lipc" >&5
+echo "configure:6170: checking for shmat in -lipc" >&5
 ac_lib_var=`echo ipc'_'shmat | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lipc "
 cat > conftest.$ac_ext <<EOF
-#line 6169 "configure"
+#line 6175 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6176,7 +6182,7 @@
 shmat()
 ; return 0; }
 EOF
-if { (eval echo configure:6180: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6186: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6212,12 +6218,12 @@
 xe_msg_checking="for IceConnectionNumber in -lICE"
 test -n "$X_EXTRA_LIBS" && xe_msg_checking="$xe_msg_checking using extra libs $X_EXTRA_LIBS"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:6216: checking "$xe_msg_checking"" >&5
+echo "configure:6222: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo ICE'_'IceConnectionNumber | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lICE $X_EXTRA_LIBS"
 cat > conftest.$ac_ext <<EOF
-#line 6221 "configure"
+#line 6227 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6228,7 +6234,7 @@
 IceConnectionNumber()
 ; return 0; }
 EOF
-if { (eval echo configure:6232: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6238: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6395,7 +6401,7 @@
 
 
     echo "checking for X defines extracted by xmkmf" 1>&6
-echo "configure:6399: checking for X defines extracted by xmkmf" >&5
+echo "configure:6405: checking for X defines extracted by xmkmf" >&5
   rm -fr conftestdir
   if mkdir conftestdir; then
     cd conftestdir
@@ -6444,15 +6450,15 @@
 
     ac_safe=`echo "X11/Intrinsic.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Intrinsic.h""... $ac_c" 1>&6
-echo "configure:6448: checking for X11/Intrinsic.h" >&5
+echo "configure:6454: checking for X11/Intrinsic.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6451 "configure"
+#line 6457 "configure"
 #include "confdefs.h"
 #include <X11/Intrinsic.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:6456: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:6462: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -6476,12 +6482,12 @@
 
       
 echo $ac_n "checking for XOpenDisplay in -lX11""... $ac_c" 1>&6
-echo "configure:6480: checking for XOpenDisplay in -lX11" >&5
+echo "configure:6486: checking for XOpenDisplay in -lX11" >&5
 ac_lib_var=`echo X11'_'XOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
-#line 6485 "configure"
+#line 6491 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6492,7 +6498,7 @@
 XOpenDisplay()
 ; return 0; }
 EOF
-if { (eval echo configure:6496: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6502: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6517,12 +6523,12 @@
 xe_msg_checking="for XGetFontProperty in -lX11"
 test -n "-b i486-linuxaout" && xe_msg_checking="$xe_msg_checking using extra libs -b i486-linuxaout"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:6521: checking "$xe_msg_checking"" >&5
+echo "configure:6527: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo X11'_'XGetFontProperty | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 -b i486-linuxaout"
 cat > conftest.$ac_ext <<EOF
-#line 6526 "configure"
+#line 6532 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6533,7 +6539,7 @@
 XGetFontProperty()
 ; return 0; }
 EOF
-if { (eval echo configure:6537: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6543: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6560,12 +6566,12 @@
 
     
 echo $ac_n "checking for XShapeSelectInput in -lXext""... $ac_c" 1>&6
-echo "configure:6564: checking for XShapeSelectInput in -lXext" >&5
+echo "configure:6570: checking for XShapeSelectInput in -lXext" >&5
 ac_lib_var=`echo Xext'_'XShapeSelectInput | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXext "
 cat > conftest.$ac_ext <<EOF
-#line 6569 "configure"
+#line 6575 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6576,7 +6582,7 @@
 XShapeSelectInput()
 ; return 0; }
 EOF
-if { (eval echo configure:6580: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6586: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6599,12 +6605,12 @@
 
     
 echo $ac_n "checking for XtOpenDisplay in -lXt""... $ac_c" 1>&6
-echo "configure:6603: checking for XtOpenDisplay in -lXt" >&5
+echo "configure:6609: checking for XtOpenDisplay in -lXt" >&5
 ac_lib_var=`echo Xt'_'XtOpenDisplay | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXt "
 cat > conftest.$ac_ext <<EOF
-#line 6608 "configure"
+#line 6614 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6615,7 +6621,7 @@
 XtOpenDisplay()
 ; return 0; }
 EOF
-if { (eval echo configure:6619: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6625: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6638,14 +6644,14 @@
 
 
   echo $ac_n "checking the version of X11 being used""... $ac_c" 1>&6
-echo "configure:6642: checking the version of X11 being used" >&5
+echo "configure:6648: checking the version of X11 being used" >&5
   cat > conftest.$ac_ext <<EOF
-#line 6644 "configure"
+#line 6650 "configure"
 #include "confdefs.h"
 #include <X11/Intrinsic.h>
     int main(int c, char *v[]) { return c>1 ? XlibSpecificationRelease : 0; }
 EOF
-if { (eval echo configure:6649: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:6655: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ./conftest foobar; x11_release=$?
 else
@@ -6676,10 +6682,10 @@
   for ac_func in XConvertCase
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:6680: checking for $ac_func" >&5
+echo "configure:6686: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6683 "configure"
+#line 6689 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -6702,7 +6708,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:6706: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6712: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -6734,15 +6740,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:6738: checking for $ac_hdr" >&5
+echo "configure:6744: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6741 "configure"
+#line 6747 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:6746: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:6752: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -6775,10 +6781,10 @@
     for ac_func in XRegisterIMInstantiateCallback
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:6779: checking for $ac_func" >&5
+echo "configure:6785: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 6782 "configure"
+#line 6788 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -6801,7 +6807,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:6805: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6811: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -6829,9 +6835,9 @@
 done
 
   echo $ac_n "checking for standard XRegisterIMInstantiateCallback prototype""... $ac_c" 1>&6
-echo "configure:6833: checking for standard XRegisterIMInstantiateCallback prototype" >&5
+echo "configure:6839: checking for standard XRegisterIMInstantiateCallback prototype" >&5
   cat > conftest.$ac_ext <<EOF
-#line 6835 "configure"
+#line 6841 "configure"
 #include "confdefs.h"
 
 #define NeedFunctionPrototypes 1
@@ -6843,7 +6849,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:6847: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:6853: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
 else
@@ -6864,12 +6870,12 @@
 
     test -z "$with_xmu" && { 
 echo $ac_n "checking for XmuReadBitmapDataFromFile in -lXmu""... $ac_c" 1>&6
-echo "configure:6868: checking for XmuReadBitmapDataFromFile in -lXmu" >&5
+echo "configure:6874: checking for XmuReadBitmapDataFromFile in -lXmu" >&5
 ac_lib_var=`echo Xmu'_'XmuReadBitmapDataFromFile | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXmu "
 cat > conftest.$ac_ext <<EOF
-#line 6873 "configure"
+#line 6879 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -6880,7 +6886,7 @@
 XmuReadBitmapDataFromFile()
 ; return 0; }
 EOF
-if { (eval echo configure:6884: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6890: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6919,19 +6925,19 @@
 
       
 echo $ac_n "checking for main in -lXbsd""... $ac_c" 1>&6
-echo "configure:6923: checking for main in -lXbsd" >&5
+echo "configure:6929: checking for main in -lXbsd" >&5
 ac_lib_var=`echo Xbsd'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXbsd "
 cat > conftest.$ac_ext <<EOF
-#line 6928 "configure"
+#line 6934 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:6935: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6941: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -6968,22 +6974,22 @@
 fi 
 if test "$with_msw" != "no"; then
   echo "checking for MS-Windows" 1>&6
-echo "configure:6972: checking for MS-Windows" >&5
+echo "configure:6978: checking for MS-Windows" >&5
   
 echo $ac_n "checking for main in -lgdi32""... $ac_c" 1>&6
-echo "configure:6975: checking for main in -lgdi32" >&5
+echo "configure:6981: checking for main in -lgdi32" >&5
 ac_lib_var=`echo gdi32'_'main | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdi32 "
 cat > conftest.$ac_ext <<EOF
-#line 6980 "configure"
+#line 6986 "configure"
 #include "confdefs.h"
 
 int main() {
 main()
 ; return 0; }
 EOF
-if { (eval echo configure:6987: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:6993: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7056,12 +7062,12 @@
  fi
     fi
         cat > conftest.$ac_ext <<EOF
-#line 7060 "configure"
+#line 7066 "configure"
 #include "confdefs.h"
 #include <fcntl.h>
     int main() { return (open("/dev/windows", O_RDONLY, 0) > 0)? 0 : 1; }
 EOF
-if { (eval echo configure:7065: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:7071: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_MSG_SELECT
@@ -7125,15 +7131,15 @@
 if test "$with_x11" = "yes"; then
   ac_safe=`echo "X11/extensions/shape.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/extensions/shape.h""... $ac_c" 1>&6
-echo "configure:7129: checking for X11/extensions/shape.h" >&5
+echo "configure:7135: checking for X11/extensions/shape.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7132 "configure"
+#line 7138 "configure"
 #include "confdefs.h"
 #include <X11/extensions/shape.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7137: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7143: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7185,7 +7191,7 @@
 esac
 
 echo "checking for WM_COMMAND option" 1>&6
-echo "configure:7189: checking for WM_COMMAND option" >&5;
+echo "configure:7195: checking for WM_COMMAND option" >&5;
 if test "$with_wmcommand" != "no"; then
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_WMCOMMAND
@@ -7200,15 +7206,15 @@
 test -z "$with_xauth" && test "$window_system" = "none" && with_xauth=no
 test -z "$with_xauth" && { ac_safe=`echo "X11/Xauth.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xauth.h""... $ac_c" 1>&6
-echo "configure:7204: checking for X11/Xauth.h" >&5
+echo "configure:7210: checking for X11/Xauth.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7207 "configure"
+#line 7213 "configure"
 #include "confdefs.h"
 #include <X11/Xauth.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7212: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7218: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7231,12 +7237,12 @@
  }
 test -z "$with_xauth" && { 
 echo $ac_n "checking for XauGetAuthByAddr in -lXau""... $ac_c" 1>&6
-echo "configure:7235: checking for XauGetAuthByAddr in -lXau" >&5
+echo "configure:7241: checking for XauGetAuthByAddr in -lXau" >&5
 ac_lib_var=`echo Xau'_'XauGetAuthByAddr | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXau "
 cat > conftest.$ac_ext <<EOF
-#line 7240 "configure"
+#line 7246 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7247,7 +7253,7 @@
 XauGetAuthByAddr()
 ; return 0; }
 EOF
-if { (eval echo configure:7251: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7257: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7292,15 +7298,15 @@
       for dir in "" "Tt/" "desktop/" ; do
     ac_safe=`echo "${dir}tt_c.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ${dir}tt_c.h""... $ac_c" 1>&6
-echo "configure:7296: checking for ${dir}tt_c.h" >&5
+echo "configure:7302: checking for ${dir}tt_c.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7299 "configure"
+#line 7305 "configure"
 #include "confdefs.h"
 #include <${dir}tt_c.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7304: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7310: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7336,12 +7342,12 @@
 xe_msg_checking="for tt_message_create in -ltt"
 test -n "$extra_libs" && xe_msg_checking="$xe_msg_checking using extra libs $extra_libs"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:7340: checking "$xe_msg_checking"" >&5
+echo "configure:7346: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo tt'_'tt_message_create | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltt $extra_libs"
 cat > conftest.$ac_ext <<EOF
-#line 7345 "configure"
+#line 7351 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7352,7 +7358,7 @@
 tt_message_create()
 ; return 0; }
 EOF
-if { (eval echo configure:7356: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7362: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7409,15 +7415,15 @@
 
 test -z "$with_cde" && { ac_safe=`echo "Dt/Dt.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Dt/Dt.h""... $ac_c" 1>&6
-echo "configure:7413: checking for Dt/Dt.h" >&5
+echo "configure:7419: checking for Dt/Dt.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7416 "configure"
+#line 7422 "configure"
 #include "confdefs.h"
 #include <Dt/Dt.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7421: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7427: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7440,12 +7446,12 @@
  }
 test -z "$with_cde" && { 
 echo $ac_n "checking for DtDndDragStart in -lDtSvc""... $ac_c" 1>&6
-echo "configure:7444: checking for DtDndDragStart in -lDtSvc" >&5
+echo "configure:7450: checking for DtDndDragStart in -lDtSvc" >&5
 ac_lib_var=`echo DtSvc'_'DtDndDragStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lDtSvc "
 cat > conftest.$ac_ext <<EOF
-#line 7449 "configure"
+#line 7455 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7456,7 +7462,7 @@
 DtDndDragStart()
 ; return 0; }
 EOF
-if { (eval echo configure:7460: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7466: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7529,7 +7535,7 @@
 
 if test "$with_dragndrop" != "no" ; then
   echo $ac_n "checking if drag and drop API is needed""... $ac_c" 1>&6
-echo "configure:7533: checking if drag and drop API is needed" >&5
+echo "configure:7539: checking if drag and drop API is needed" >&5
   if test -n "$dragndrop_proto" ; then
     with_dragndrop=yes
     echo "$ac_t""yes (${dragndrop_proto} )" 1>&6
@@ -7549,18 +7555,18 @@
 fi
 
 echo "checking for LDAP" 1>&6
-echo "configure:7553: checking for LDAP" >&5
+echo "configure:7559: checking for LDAP" >&5
 test -z "$with_ldap" && { ac_safe=`echo "ldap.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ldap.h""... $ac_c" 1>&6
-echo "configure:7556: checking for ldap.h" >&5
+echo "configure:7562: checking for ldap.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7559 "configure"
+#line 7565 "configure"
 #include "confdefs.h"
 #include <ldap.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7564: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7570: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7583,15 +7589,15 @@
  }
 test -z "$with_ldap" && { ac_safe=`echo "lber.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for lber.h""... $ac_c" 1>&6
-echo "configure:7587: checking for lber.h" >&5
+echo "configure:7593: checking for lber.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7590 "configure"
+#line 7596 "configure"
 #include "confdefs.h"
 #include <lber.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7595: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7601: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7615,12 +7621,12 @@
 if test "$with_ldap" != "no"; then
   
 echo $ac_n "checking for ldap_search in -lldap""... $ac_c" 1>&6
-echo "configure:7619: checking for ldap_search in -lldap" >&5
+echo "configure:7625: checking for ldap_search in -lldap" >&5
 ac_lib_var=`echo ldap'_'ldap_search | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap "
 cat > conftest.$ac_ext <<EOF
-#line 7624 "configure"
+#line 7630 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7631,7 +7637,7 @@
 ldap_search()
 ; return 0; }
 EOF
-if { (eval echo configure:7635: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7641: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7656,12 +7662,12 @@
 xe_msg_checking="for ldap_open in -lldap"
 test -n "-llber" && xe_msg_checking="$xe_msg_checking using extra libs -llber"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:7660: checking "$xe_msg_checking"" >&5
+echo "configure:7666: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber"
 cat > conftest.$ac_ext <<EOF
-#line 7665 "configure"
+#line 7671 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7672,7 +7678,7 @@
 ldap_open()
 ; return 0; }
 EOF
-if { (eval echo configure:7676: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7682: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7697,12 +7703,12 @@
 xe_msg_checking="for ldap_open in -lldap"
 test -n "-llber -lkrb" && xe_msg_checking="$xe_msg_checking using extra libs -llber -lkrb"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:7701: checking "$xe_msg_checking"" >&5
+echo "configure:7707: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber -lkrb"
 cat > conftest.$ac_ext <<EOF
-#line 7706 "configure"
+#line 7712 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7713,7 +7719,7 @@
 ldap_open()
 ; return 0; }
 EOF
-if { (eval echo configure:7717: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7723: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7738,12 +7744,12 @@
 xe_msg_checking="for ldap_open in -lldap"
 test -n "-llber -lkrb -ldes" && xe_msg_checking="$xe_msg_checking using extra libs -llber -lkrb -ldes"
 echo $ac_n "checking "$xe_msg_checking"""... $ac_c" 1>&6
-echo "configure:7742: checking "$xe_msg_checking"" >&5
+echo "configure:7748: checking "$xe_msg_checking"" >&5
 ac_lib_var=`echo ldap'_'ldap_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lldap -llber -lkrb -ldes"
 cat > conftest.$ac_ext <<EOF
-#line 7747 "configure"
+#line 7753 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7754,7 +7760,7 @@
 ldap_open()
 ; return 0; }
 EOF
-if { (eval echo configure:7758: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7764: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7805,10 +7811,10 @@
   for ac_func in ldap_set_option ldap_get_lderrno ldap_result2error ldap_parse_result
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:7809: checking for $ac_func" >&5
+echo "configure:7815: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7812 "configure"
+#line 7818 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -7831,7 +7837,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:7835: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7841: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -7862,20 +7868,20 @@
 
 if test "$with_postgresql" != "no"; then
   echo "checking for PostgreSQL" 1>&6
-echo "configure:7866: checking for PostgreSQL" >&5
+echo "configure:7872: checking for PostgreSQL" >&5
 
   for header_dir in "" "pgsql/" "postgresql/"; do
     ac_safe=`echo "${header_dir}libpq-fe.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ${header_dir}libpq-fe.h""... $ac_c" 1>&6
-echo "configure:7871: checking for ${header_dir}libpq-fe.h" >&5
+echo "configure:7877: checking for ${header_dir}libpq-fe.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 7874 "configure"
+#line 7880 "configure"
 #include "confdefs.h"
 #include <${header_dir}libpq-fe.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:7879: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:7885: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -7899,12 +7905,12 @@
 
   test -n "$libpq_fe_h_file" && { 
 echo $ac_n "checking for PQconnectdb in -lpq""... $ac_c" 1>&6
-echo "configure:7903: checking for PQconnectdb in -lpq" >&5
+echo "configure:7909: checking for PQconnectdb in -lpq" >&5
 ac_lib_var=`echo pq'_'PQconnectdb | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF
-#line 7908 "configure"
+#line 7914 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7915,7 +7921,7 @@
 PQconnectdb()
 ; return 0; }
 EOF
-if { (eval echo configure:7919: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7925: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -7948,12 +7954,12 @@
 
     
 echo $ac_n "checking for PQconnectStart in -lpq""... $ac_c" 1>&6
-echo "configure:7952: checking for PQconnectStart in -lpq" >&5
+echo "configure:7958: checking for PQconnectStart in -lpq" >&5
 ac_lib_var=`echo pq'_'PQconnectStart | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpq "
 cat > conftest.$ac_ext <<EOF
-#line 7957 "configure"
+#line 7963 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -7964,7 +7970,7 @@
 PQconnectStart()
 ; return 0; }
 EOF
-if { (eval echo configure:7968: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:7974: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8012,15 +8018,15 @@
 
 if test "$window_system" != "none"; then
   echo "checking for graphics libraries" 1>&6
-echo "configure:8016: checking for graphics libraries" >&5
+echo "configure:8022: checking for graphics libraries" >&5
 
     xpm_problem=""
   if test -z "$with_xpm"; then
     echo $ac_n "checking for Xpm - no older than 3.4f""... $ac_c" 1>&6
-echo "configure:8021: checking for Xpm - no older than 3.4f" >&5
+echo "configure:8027: checking for Xpm - no older than 3.4f" >&5
     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF
-#line 8024 "configure"
+#line 8030 "configure"
 #include "confdefs.h"
 #define XPM_NUMBERS
 #include <X11/xpm.h>
@@ -8029,7 +8035,7 @@
       XpmIncludeVersion != XpmLibraryVersion() ? 1 :
       XpmIncludeVersion < 30406 ? 2 : 0 ;}
 EOF
-if { (eval echo configure:8033: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:8039: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ./conftest dummy_arg; xpm_status=$?;
       if test "$xpm_status" = "0"; then
@@ -8071,17 +8077,17 @@
 
     libs_x="-lXpm $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-lXpm\" to \$libs_x"; fi
     echo $ac_n "checking for \"FOR_MSW\" xpm""... $ac_c" 1>&6
-echo "configure:8075: checking for \"FOR_MSW\" xpm" >&5
+echo "configure:8081: checking for \"FOR_MSW\" xpm" >&5
     xe_check_libs=-lXpm
     cat > conftest.$ac_ext <<EOF
-#line 8078 "configure"
+#line 8084 "configure"
 #include "confdefs.h"
 
 int main() {
 XpmCreatePixmapFromData()
 ; return 0; }
 EOF
-if { (eval echo configure:8085: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8091: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   xpm_for_msw=no
 else
@@ -8107,15 +8113,15 @@
 
     test -z "$with_xface" && { ac_safe=`echo "compface.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for compface.h""... $ac_c" 1>&6
-echo "configure:8111: checking for compface.h" >&5
+echo "configure:8117: checking for compface.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8114 "configure"
+#line 8120 "configure"
 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8119: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8125: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8138,12 +8144,12 @@
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6
-echo "configure:8142: checking for UnGenFace in -lcompface" >&5
+echo "configure:8148: checking for UnGenFace in -lcompface" >&5
 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF
-#line 8147 "configure"
+#line 8153 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8154,7 +8160,7 @@
 UnGenFace()
 ; return 0; }
 EOF
-if { (eval echo configure:8158: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8164: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8206,12 +8212,12 @@
       if test "$with_png $with_tiff" != "no no"; then
     
 echo $ac_n "checking for inflate in -lc""... $ac_c" 1>&6
-echo "configure:8210: checking for inflate in -lc" >&5
+echo "configure:8216: checking for inflate in -lc" >&5
 ac_lib_var=`echo c'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lc "
 cat > conftest.$ac_ext <<EOF
-#line 8215 "configure"
+#line 8221 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8222,7 +8228,7 @@
 inflate()
 ; return 0; }
 EOF
-if { (eval echo configure:8226: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8232: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8241,12 +8247,12 @@
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lz""... $ac_c" 1>&6
-echo "configure:8245: checking for inflate in -lz" >&5
+echo "configure:8251: checking for inflate in -lz" >&5
 ac_lib_var=`echo z'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lz "
 cat > conftest.$ac_ext <<EOF
-#line 8250 "configure"
+#line 8256 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8257,7 +8263,7 @@
 inflate()
 ; return 0; }
 EOF
-if { (eval echo configure:8261: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8267: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8276,12 +8282,12 @@
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for inflate in -lgz""... $ac_c" 1>&6
-echo "configure:8280: checking for inflate in -lgz" >&5
+echo "configure:8286: checking for inflate in -lgz" >&5
 ac_lib_var=`echo gz'_'inflate | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgz "
 cat > conftest.$ac_ext <<EOF
-#line 8285 "configure"
+#line 8291 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8292,7 +8298,7 @@
 inflate()
 ; return 0; }
 EOF
-if { (eval echo configure:8296: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8302: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8322,15 +8328,15 @@
 
     test -z "$with_jpeg" && { ac_safe=`echo "jpeglib.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for jpeglib.h""... $ac_c" 1>&6
-echo "configure:8326: checking for jpeglib.h" >&5
+echo "configure:8332: checking for jpeglib.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8329 "configure"
+#line 8335 "configure"
 #include "confdefs.h"
 #include <jpeglib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8334: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8340: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8353,12 +8359,12 @@
  }
   test -z "$with_jpeg" && { 
 echo $ac_n "checking for jpeg_destroy_decompress in -ljpeg""... $ac_c" 1>&6
-echo "configure:8357: checking for jpeg_destroy_decompress in -ljpeg" >&5
+echo "configure:8363: checking for jpeg_destroy_decompress in -ljpeg" >&5
 ac_lib_var=`echo jpeg'_'jpeg_destroy_decompress | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ljpeg "
 cat > conftest.$ac_ext <<EOF
-#line 8362 "configure"
+#line 8368 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8369,7 +8375,7 @@
 jpeg_destroy_decompress()
 ; return 0; }
 EOF
-if { (eval echo configure:8373: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8379: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8405,10 +8411,10 @@
 
     png_problem=""
   test -z "$with_png" && { echo $ac_n "checking for pow""... $ac_c" 1>&6
-echo "configure:8409: checking for pow" >&5
+echo "configure:8415: checking for pow" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8412 "configure"
+#line 8418 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char pow(); below.  */
@@ -8431,7 +8437,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:8435: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8441: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_pow=yes"
 else
@@ -8452,15 +8458,15 @@
  }
   test -z "$with_png" && { ac_safe=`echo "png.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for png.h""... $ac_c" 1>&6
-echo "configure:8456: checking for png.h" >&5
+echo "configure:8462: checking for png.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8459 "configure"
+#line 8465 "configure"
 #include "confdefs.h"
 #include <png.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8464: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8470: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8483,12 +8489,12 @@
  }
   test -z "$with_png" && { 
 echo $ac_n "checking for png_read_image in -lpng""... $ac_c" 1>&6
-echo "configure:8487: checking for png_read_image in -lpng" >&5
+echo "configure:8493: checking for png_read_image in -lpng" >&5
 ac_lib_var=`echo png'_'png_read_image | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lpng "
 cat > conftest.$ac_ext <<EOF
-#line 8492 "configure"
+#line 8498 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8499,7 +8505,7 @@
 png_read_image()
 ; return 0; }
 EOF
-if { (eval echo configure:8503: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8509: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8522,10 +8528,10 @@
  }
   if test -z "$with_png"; then
     echo $ac_n "checking for workable png version information""... $ac_c" 1>&6
-echo "configure:8526: checking for workable png version information" >&5
+echo "configure:8532: checking for workable png version information" >&5
     xe_check_libs="-lpng -lz"
     cat > conftest.$ac_ext <<EOF
-#line 8529 "configure"
+#line 8535 "configure"
 #include "confdefs.h"
 #include <png.h>
     int main(int c, char **v) {
@@ -8533,7 +8539,7 @@
     if (strcmp(png_libpng_ver, PNG_LIBPNG_VER_STRING) != 0) return 1;
     return (PNG_LIBPNG_VER < 10002) ? 2 : 0 ;}
 EOF
-if { (eval echo configure:8537: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:8543: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ./conftest dummy_arg; png_status=$?;
       if test "$png_status" = "0"; then
@@ -8576,15 +8582,15 @@
 
     test -z "$with_tiff" && { ac_safe=`echo "tiffio.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for tiffio.h""... $ac_c" 1>&6
-echo "configure:8580: checking for tiffio.h" >&5
+echo "configure:8586: checking for tiffio.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8583 "configure"
+#line 8589 "configure"
 #include "confdefs.h"
 #include <tiffio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8588: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8594: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8607,12 +8613,12 @@
  }
   test -z "$with_tiff" && { 
 echo $ac_n "checking for TIFFClientOpen in -ltiff""... $ac_c" 1>&6
-echo "configure:8611: checking for TIFFClientOpen in -ltiff" >&5
+echo "configure:8617: checking for TIFFClientOpen in -ltiff" >&5
 ac_lib_var=`echo tiff'_'TIFFClientOpen | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltiff "
 cat > conftest.$ac_ext <<EOF
-#line 8616 "configure"
+#line 8622 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8623,7 +8629,7 @@
 TIFFClientOpen()
 ; return 0; }
 EOF
-if { (eval echo configure:8627: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8633: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8662,15 +8668,15 @@
 if test "$with_gtk" = "yes"; then
     test -z "$with_xface" && { ac_safe=`echo "compface.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for compface.h""... $ac_c" 1>&6
-echo "configure:8666: checking for compface.h" >&5
+echo "configure:8672: checking for compface.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8669 "configure"
+#line 8675 "configure"
 #include "confdefs.h"
 #include <compface.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8674: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8680: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8693,12 +8699,12 @@
  }
   test -z "$with_xface" && { 
 echo $ac_n "checking for UnGenFace in -lcompface""... $ac_c" 1>&6
-echo "configure:8697: checking for UnGenFace in -lcompface" >&5
+echo "configure:8703: checking for UnGenFace in -lcompface" >&5
 ac_lib_var=`echo compface'_'UnGenFace | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcompface "
 cat > conftest.$ac_ext <<EOF
-#line 8702 "configure"
+#line 8708 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8709,7 +8715,7 @@
 UnGenFace()
 ; return 0; }
 EOF
-if { (eval echo configure:8713: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8719: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8749,10 +8755,10 @@
 if test "$with_x11" = "yes"; then
 
   echo "checking for X11 graphics libraries" 1>&6
-echo "configure:8753: checking for X11 graphics libraries" >&5
+echo "configure:8759: checking for X11 graphics libraries" >&5
 
   echo "checking for the Athena widgets" 1>&6
-echo "configure:8756: checking for the Athena widgets" >&5
+echo "configure:8762: checking for the Athena widgets" >&5
 
     case "$with_athena" in
         "xaw" | "")	athena_variant=Xaw	athena_3d=no  ;;
@@ -8766,12 +8772,12 @@
     if test "$athena_3d" = "no"; then
     
 echo $ac_n "checking for XawScrollbarSetThumb in -l$athena_variant""... $ac_c" 1>&6
-echo "configure:8770: checking for XawScrollbarSetThumb in -l$athena_variant" >&5
+echo "configure:8776: checking for XawScrollbarSetThumb in -l$athena_variant" >&5
 ac_lib_var=`echo $athena_variant'_'XawScrollbarSetThumb | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF
-#line 8775 "configure"
+#line 8781 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8782,7 +8788,7 @@
 XawScrollbarSetThumb()
 ; return 0; }
 EOF
-if { (eval echo configure:8786: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8792: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8798,12 +8804,12 @@
   echo "$ac_t""yes" 1>&6
           
 echo $ac_n "checking for threeDClassRec in -l$athena_variant""... $ac_c" 1>&6
-echo "configure:8802: checking for threeDClassRec in -l$athena_variant" >&5
+echo "configure:8808: checking for threeDClassRec in -l$athena_variant" >&5
 ac_lib_var=`echo $athena_variant'_'threeDClassRec | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF
-#line 8807 "configure"
+#line 8813 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8814,7 +8820,7 @@
 threeDClassRec()
 ; return 0; }
 EOF
-if { (eval echo configure:8818: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8824: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8845,12 +8851,12 @@
   else
         
 echo $ac_n "checking for threeDClassRec in -l$athena_variant""... $ac_c" 1>&6
-echo "configure:8849: checking for threeDClassRec in -l$athena_variant" >&5
+echo "configure:8855: checking for threeDClassRec in -l$athena_variant" >&5
 ac_lib_var=`echo $athena_variant'_'threeDClassRec | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$athena_variant "
 cat > conftest.$ac_ext <<EOF
-#line 8854 "configure"
+#line 8860 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8861,7 +8867,7 @@
 threeDClassRec()
 ; return 0; }
 EOF
-if { (eval echo configure:8865: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8871: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8879,12 +8885,12 @@
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for threeDClassRec in -lXaw""... $ac_c" 1>&6
-echo "configure:8883: checking for threeDClassRec in -lXaw" >&5
+echo "configure:8889: checking for threeDClassRec in -lXaw" >&5
 ac_lib_var=`echo Xaw'_'threeDClassRec | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXaw "
 cat > conftest.$ac_ext <<EOF
-#line 8888 "configure"
+#line 8894 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -8895,7 +8901,7 @@
 threeDClassRec()
 ; return 0; }
 EOF
-if { (eval echo configure:8899: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:8905: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -8926,15 +8932,15 @@
     if test "$athena_3d" = "no"; then
     ac_safe=`echo "X11/Xaw/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xaw/ThreeD.h""... $ac_c" 1>&6
-echo "configure:8930: checking for X11/Xaw/ThreeD.h" >&5
+echo "configure:8936: checking for X11/Xaw/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8933 "configure"
+#line 8939 "configure"
 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8938: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8944: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8954,15 +8960,15 @@
   echo "$ac_t""no" 1>&6
 ac_safe=`echo "X11/Xaw/XawInit.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xaw/XawInit.h""... $ac_c" 1>&6
-echo "configure:8958: checking for X11/Xaw/XawInit.h" >&5
+echo "configure:8964: checking for X11/Xaw/XawInit.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8961 "configure"
+#line 8967 "configure"
 #include "confdefs.h"
 #include <X11/Xaw/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:8966: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:8972: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -8988,15 +8994,15 @@
   else
             ac_safe=`echo "X11/$athena_variant/XawInit.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/$athena_variant/XawInit.h""... $ac_c" 1>&6
-echo "configure:8992: checking for X11/$athena_variant/XawInit.h" >&5
+echo "configure:8998: checking for X11/$athena_variant/XawInit.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 8995 "configure"
+#line 9001 "configure"
 #include "confdefs.h"
 #include <X11/$athena_variant/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9000: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9006: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9013,15 +9019,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "X11/$athena_variant/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/$athena_variant/ThreeD.h""... $ac_c" 1>&6
-echo "configure:9017: checking for X11/$athena_variant/ThreeD.h" >&5
+echo "configure:9023: checking for X11/$athena_variant/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9020 "configure"
+#line 9026 "configure"
 #include "confdefs.h"
 #include <X11/$athena_variant/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9025: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9031: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9049,15 +9055,15 @@
         if test -z "$athena_h_path"; then
       ac_safe=`echo "$athena_variant/XawInit.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $athena_variant/XawInit.h""... $ac_c" 1>&6
-echo "configure:9053: checking for $athena_variant/XawInit.h" >&5
+echo "configure:9059: checking for $athena_variant/XawInit.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9056 "configure"
+#line 9062 "configure"
 #include "confdefs.h"
 #include <$athena_variant/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9061: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9067: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9074,15 +9080,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "$athena_variant/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $athena_variant/ThreeD.h""... $ac_c" 1>&6
-echo "configure:9078: checking for $athena_variant/ThreeD.h" >&5
+echo "configure:9084: checking for $athena_variant/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9081 "configure"
+#line 9087 "configure"
 #include "confdefs.h"
 #include <$athena_variant/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9086: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9092: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9111,15 +9117,15 @@
         if test -z "$athena_h_path" -a "$athena_variant" != "Xaw3d"; then
       ac_safe=`echo "X11/Xaw3d/XawInit.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xaw3d/XawInit.h""... $ac_c" 1>&6
-echo "configure:9115: checking for X11/Xaw3d/XawInit.h" >&5
+echo "configure:9121: checking for X11/Xaw3d/XawInit.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9118 "configure"
+#line 9124 "configure"
 #include "confdefs.h"
 #include <X11/Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9123: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9129: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9136,15 +9142,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "X11/Xaw3d/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xaw3d/ThreeD.h""... $ac_c" 1>&6
-echo "configure:9140: checking for X11/Xaw3d/ThreeD.h" >&5
+echo "configure:9146: checking for X11/Xaw3d/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9143 "configure"
+#line 9149 "configure"
 #include "confdefs.h"
 #include <X11/Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9148: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9154: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9176,15 +9182,15 @@
         if test -z "$athena_h_path" -a "$athena_variant" != "Xaw3d"; then
       ac_safe=`echo "Xaw3d/XawInit.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xaw3d/XawInit.h""... $ac_c" 1>&6
-echo "configure:9180: checking for Xaw3d/XawInit.h" >&5
+echo "configure:9186: checking for Xaw3d/XawInit.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9183 "configure"
+#line 9189 "configure"
 #include "confdefs.h"
 #include <Xaw3d/XawInit.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9188: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9194: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9201,15 +9207,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "Xaw3d/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xaw3d/ThreeD.h""... $ac_c" 1>&6
-echo "configure:9205: checking for Xaw3d/ThreeD.h" >&5
+echo "configure:9211: checking for Xaw3d/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9208 "configure"
+#line 9214 "configure"
 #include "confdefs.h"
 #include <Xaw3d/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9213: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9219: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9241,15 +9247,15 @@
             if test -z "$athena_h_path"; then
       ac_safe=`echo "X11/Xaw/ThreeD.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for X11/Xaw/ThreeD.h""... $ac_c" 1>&6
-echo "configure:9245: checking for X11/Xaw/ThreeD.h" >&5
+echo "configure:9251: checking for X11/Xaw/ThreeD.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9248 "configure"
+#line 9254 "configure"
 #include "confdefs.h"
 #include <X11/Xaw/ThreeD.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9253: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9259: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9284,15 +9290,15 @@
 
     ac_safe=`echo "Xm/Xm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for Xm/Xm.h""... $ac_c" 1>&6
-echo "configure:9288: checking for Xm/Xm.h" >&5
+echo "configure:9294: checking for Xm/Xm.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9291 "configure"
+#line 9297 "configure"
 #include "confdefs.h"
 #include <Xm/Xm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9296: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9302: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9309,12 +9315,12 @@
   echo "$ac_t""yes" 1>&6
   
 echo $ac_n "checking for XmStringFree in -lXm""... $ac_c" 1>&6
-echo "configure:9313: checking for XmStringFree in -lXm" >&5
+echo "configure:9319: checking for XmStringFree in -lXm" >&5
 ac_lib_var=`echo Xm'_'XmStringFree | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF
-#line 9318 "configure"
+#line 9324 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -9325,7 +9331,7 @@
 XmStringFree()
 ; return 0; }
 EOF
-if { (eval echo configure:9329: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9335: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -9354,9 +9360,9 @@
 
   if test "$have_motif" = "yes"; then
         echo $ac_n "checking for Lesstif""... $ac_c" 1>&6
-echo "configure:9358: checking for Lesstif" >&5
+echo "configure:9364: checking for Lesstif" >&5
     cat > conftest.$ac_ext <<EOF
-#line 9360 "configure"
+#line 9366 "configure"
 #include "confdefs.h"
 #include <Xm/Xm.h>
 #ifdef LESSTIF_VERSION
@@ -9780,7 +9786,7 @@
 
 if test "$with_mule" = "yes" ; then
   echo "checking for Mule-related features" 1>&6
-echo "configure:9784: checking for Mule-related features" >&5
+echo "configure:9790: checking for Mule-related features" >&5
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining MULE
 EOF
@@ -9805,15 +9811,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:9809: checking for $ac_hdr" >&5
+echo "configure:9815: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 9812 "configure"
+#line 9818 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:9817: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:9823: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -9844,12 +9850,12 @@
 
   
 echo $ac_n "checking for strerror in -lintl""... $ac_c" 1>&6
-echo "configure:9848: checking for strerror in -lintl" >&5
+echo "configure:9854: checking for strerror in -lintl" >&5
 ac_lib_var=`echo intl'_'strerror | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lintl "
 cat > conftest.$ac_ext <<EOF
-#line 9853 "configure"
+#line 9859 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -9860,7 +9866,7 @@
 strerror()
 ; return 0; }
 EOF
-if { (eval echo configure:9864: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9870: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -9893,18 +9899,18 @@
 
 
   echo "checking for Mule input methods" 1>&6
-echo "configure:9897: checking for Mule input methods" >&5
+echo "configure:9903: checking for Mule input methods" >&5
         case "$with_xim" in "" | "yes" )
     echo "checking for XIM" 1>&6
-echo "configure:9900: checking for XIM" >&5
+echo "configure:9906: checking for XIM" >&5
     
 echo $ac_n "checking for XOpenIM in -lX11""... $ac_c" 1>&6
-echo "configure:9903: checking for XOpenIM in -lX11" >&5
+echo "configure:9909: checking for XOpenIM in -lX11" >&5
 ac_lib_var=`echo X11'_'XOpenIM | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
-#line 9908 "configure"
+#line 9914 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -9915,7 +9921,7 @@
 XOpenIM()
 ; return 0; }
 EOF
-if { (eval echo configure:9919: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9925: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -9939,12 +9945,12 @@
         if test "$have_motif $have_lesstif" = "yes no"; then
       
 echo $ac_n "checking for XmImMbLookupString in -lXm""... $ac_c" 1>&6
-echo "configure:9943: checking for XmImMbLookupString in -lXm" >&5
+echo "configure:9949: checking for XmImMbLookupString in -lXm" >&5
 ac_lib_var=`echo Xm'_'XmImMbLookupString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lXm "
 cat > conftest.$ac_ext <<EOF
-#line 9948 "configure"
+#line 9954 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -9955,7 +9961,7 @@
 XmImMbLookupString()
 ; return 0; }
 EOF
-if { (eval echo configure:9959: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:9965: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10020,15 +10026,15 @@
 
     if test "$with_xfs" = "yes" ; then
     echo "checking for XFontSet" 1>&6
-echo "configure:10024: checking for XFontSet" >&5
+echo "configure:10030: checking for XFontSet" >&5
     
 echo $ac_n "checking for XmbDrawString in -lX11""... $ac_c" 1>&6
-echo "configure:10027: checking for XmbDrawString in -lX11" >&5
+echo "configure:10033: checking for XmbDrawString in -lX11" >&5
 ac_lib_var=`echo X11'_'XmbDrawString | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lX11 "
 cat > conftest.$ac_ext <<EOF
-#line 10032 "configure"
+#line 10038 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10039,7 +10045,7 @@
 XmbDrawString()
 ; return 0; }
 EOF
-if { (eval echo configure:10043: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10049: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10079,15 +10085,15 @@
     test "$with_wnn6" = "yes" && with_wnn=yes # wnn6 implies wnn support
   test -z "$with_wnn" && { ac_safe=`echo "wnn/jllib.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for wnn/jllib.h""... $ac_c" 1>&6
-echo "configure:10083: checking for wnn/jllib.h" >&5
+echo "configure:10089: checking for wnn/jllib.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10086 "configure"
+#line 10092 "configure"
 #include "confdefs.h"
 #include <wnn/jllib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10091: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10097: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -10110,15 +10116,15 @@
  }
     test -z "$with_wnn" && { ac_safe=`echo "wnn/commonhd.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for wnn/commonhd.h""... $ac_c" 1>&6
-echo "configure:10114: checking for wnn/commonhd.h" >&5
+echo "configure:10120: checking for wnn/commonhd.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10117 "configure"
+#line 10123 "configure"
 #include "confdefs.h"
 #include <wnn/commonhd.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10122: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10128: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -10143,10 +10149,10 @@
     for ac_func in crypt
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:10147: checking for $ac_func" >&5
+echo "configure:10153: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10150 "configure"
+#line 10156 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -10169,7 +10175,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:10173: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10179: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -10198,12 +10204,12 @@
 
     test "$ac_cv_func_crypt" != "yes" && { 
 echo $ac_n "checking for crypt in -lcrypt""... $ac_c" 1>&6
-echo "configure:10202: checking for crypt in -lcrypt" >&5
+echo "configure:10208: checking for crypt in -lcrypt" >&5
 ac_lib_var=`echo crypt'_'crypt | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcrypt "
 cat > conftest.$ac_ext <<EOF
-#line 10207 "configure"
+#line 10213 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10214,7 +10220,7 @@
 crypt()
 ; return 0; }
 EOF
-if { (eval echo configure:10218: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10224: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10249,12 +10255,12 @@
     if test -z "$with_wnn" -o "$with_wnn" = "yes"; then
     
 echo $ac_n "checking for jl_dic_list_e in -lwnn""... $ac_c" 1>&6
-echo "configure:10253: checking for jl_dic_list_e in -lwnn" >&5
+echo "configure:10259: checking for jl_dic_list_e in -lwnn" >&5
 ac_lib_var=`echo wnn'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn "
 cat > conftest.$ac_ext <<EOF
-#line 10258 "configure"
+#line 10264 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10265,7 +10271,7 @@
 jl_dic_list_e()
 ; return 0; }
 EOF
-if { (eval echo configure:10269: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10275: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10283,12 +10289,12 @@
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn4""... $ac_c" 1>&6
-echo "configure:10287: checking for jl_dic_list_e in -lwnn4" >&5
+echo "configure:10293: checking for jl_dic_list_e in -lwnn4" >&5
 ac_lib_var=`echo wnn4'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn4 "
 cat > conftest.$ac_ext <<EOF
-#line 10292 "configure"
+#line 10298 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10299,7 +10305,7 @@
 jl_dic_list_e()
 ; return 0; }
 EOF
-if { (eval echo configure:10303: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10309: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10317,12 +10323,12 @@
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for jl_dic_list_e in -lwnn6""... $ac_c" 1>&6
-echo "configure:10321: checking for jl_dic_list_e in -lwnn6" >&5
+echo "configure:10327: checking for jl_dic_list_e in -lwnn6" >&5
 ac_lib_var=`echo wnn6'_'jl_dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn6 "
 cat > conftest.$ac_ext <<EOF
-#line 10326 "configure"
+#line 10332 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10333,7 +10339,7 @@
 jl_dic_list_e()
 ; return 0; }
 EOF
-if { (eval echo configure:10337: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10343: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10351,12 +10357,12 @@
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for dic_list_e in -lwnn6_fromsrc""... $ac_c" 1>&6
-echo "configure:10355: checking for dic_list_e in -lwnn6_fromsrc" >&5
+echo "configure:10361: checking for dic_list_e in -lwnn6_fromsrc" >&5
 ac_lib_var=`echo wnn6_fromsrc'_'dic_list_e | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lwnn6_fromsrc "
 cat > conftest.$ac_ext <<EOF
-#line 10360 "configure"
+#line 10366 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10367,7 +10373,7 @@
 dic_list_e()
 ; return 0; }
 EOF
-if { (eval echo configure:10371: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10377: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10415,12 +10421,12 @@
     if test "$with_wnn6" != "no"; then
       
 echo $ac_n "checking for jl_fi_dic_list in -l$libwnn""... $ac_c" 1>&6
-echo "configure:10419: checking for jl_fi_dic_list in -l$libwnn" >&5
+echo "configure:10425: checking for jl_fi_dic_list in -l$libwnn" >&5
 ac_lib_var=`echo $libwnn'_'jl_fi_dic_list | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$libwnn "
 cat > conftest.$ac_ext <<EOF
-#line 10424 "configure"
+#line 10430 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10431,7 +10437,7 @@
 jl_fi_dic_list()
 ; return 0; }
 EOF
-if { (eval echo configure:10435: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10441: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10466,15 +10472,15 @@
   if test "$with_canna" != "no"; then
     ac_safe=`echo "canna/jrkanji.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for canna/jrkanji.h""... $ac_c" 1>&6
-echo "configure:10470: checking for canna/jrkanji.h" >&5
+echo "configure:10476: checking for canna/jrkanji.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10473 "configure"
+#line 10479 "configure"
 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10478: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10484: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -10501,15 +10507,15 @@
     c_switch_site="$c_switch_site -I/usr/local/canna/include"
     ac_safe=`echo "canna/jrkanji.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for canna/jrkanji.h""... $ac_c" 1>&6
-echo "configure:10505: checking for canna/jrkanji.h" >&5
+echo "configure:10511: checking for canna/jrkanji.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10508 "configure"
+#line 10514 "configure"
 #include "confdefs.h"
 #include <canna/jrkanji.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10513: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10519: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -10537,15 +10543,15 @@
 
   test -z "$with_canna" && { ac_safe=`echo "canna/RK.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for canna/RK.h""... $ac_c" 1>&6
-echo "configure:10541: checking for canna/RK.h" >&5
+echo "configure:10547: checking for canna/RK.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10544 "configure"
+#line 10550 "configure"
 #include "confdefs.h"
 #include <canna/RK.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10549: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:10555: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -10568,12 +10574,12 @@
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for RkBgnBun in -lRKC""... $ac_c" 1>&6
-echo "configure:10572: checking for RkBgnBun in -lRKC" >&5
+echo "configure:10578: checking for RkBgnBun in -lRKC" >&5
 ac_lib_var=`echo RKC'_'RkBgnBun | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lRKC "
 cat > conftest.$ac_ext <<EOF
-#line 10577 "configure"
+#line 10583 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10584,7 +10590,7 @@
 RkBgnBun()
 ; return 0; }
 EOF
-if { (eval echo configure:10588: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10594: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10607,12 +10613,12 @@
  }
   test -z "$with_canna" && { 
 echo $ac_n "checking for jrKanjiControl in -lcanna""... $ac_c" 1>&6
-echo "configure:10611: checking for jrKanjiControl in -lcanna" >&5
+echo "configure:10617: checking for jrKanjiControl in -lcanna" >&5
 ac_lib_var=`echo canna'_'jrKanjiControl | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcanna "
 cat > conftest.$ac_ext <<EOF
-#line 10616 "configure"
+#line 10622 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10623,7 +10629,7 @@
 jrKanjiControl()
 ; return 0; }
 EOF
-if { (eval echo configure:10627: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10633: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10672,12 +10678,12 @@
   libs_x="-lXm $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-lXm\" to \$libs_x"; fi
     
 echo $ac_n "checking for layout_object_getvalue in -li18n""... $ac_c" 1>&6
-echo "configure:10676: checking for layout_object_getvalue in -li18n" >&5
+echo "configure:10682: checking for layout_object_getvalue in -li18n" >&5
 ac_lib_var=`echo i18n'_'layout_object_getvalue | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -li18n "
 cat > conftest.$ac_ext <<EOF
-#line 10681 "configure"
+#line 10687 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10688,7 +10694,7 @@
 layout_object_getvalue()
 ; return 0; }
 EOF
-if { (eval echo configure:10692: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10698: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10774,10 +10780,10 @@
 for ac_func in cbrt closedir dup2 eaccess fmod fpathconf frexp ftime getaddrinfo gethostname getnameinfo getpagesize gettimeofday getcwd getwd logb lrand48 matherr mkdir mktime perror poll random rename res_init rint rmdir select setitimer setpgid setlocale setsid sigblock sighold sigprocmask snprintf stpcpy strerror tzset ulimit usleep waitpid vsnprintf fsync ftruncate umask
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:10778: checking for $ac_func" >&5
+echo "configure:10784: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10781 "configure"
+#line 10787 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -10800,7 +10806,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:10804: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10810: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -10832,10 +10838,10 @@
 for ac_func in getpt _getpty grantpt unlockpt ptsname killpg tcgetpgrp
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:10836: checking for $ac_func" >&5
+echo "configure:10842: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10839 "configure"
+#line 10845 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -10858,7 +10864,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:10862: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10868: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -10887,10 +10893,10 @@
 
 
 echo $ac_n "checking for openpty""... $ac_c" 1>&6
-echo "configure:10891: checking for openpty" >&5
+echo "configure:10897: checking for openpty" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10894 "configure"
+#line 10900 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char openpty(); below.  */
@@ -10913,7 +10919,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:10917: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10923: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_openpty=yes"
 else
@@ -10932,12 +10938,12 @@
 
   
 echo $ac_n "checking for openpty in -lutil""... $ac_c" 1>&6
-echo "configure:10936: checking for openpty in -lutil" >&5
+echo "configure:10942: checking for openpty in -lutil" >&5
 ac_lib_var=`echo util'_'openpty | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lutil "
 cat > conftest.$ac_ext <<EOF
-#line 10941 "configure"
+#line 10947 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -10948,7 +10954,7 @@
 openpty()
 ; return 0; }
 EOF
-if { (eval echo configure:10952: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:10958: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -10983,15 +10989,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:10987: checking for $ac_hdr" >&5
+echo "configure:10993: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 10990 "configure"
+#line 10996 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:10995: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11001: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11027,15 +11033,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:11031: checking for $ac_hdr" >&5
+echo "configure:11037: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11034 "configure"
+#line 11040 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:11039: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11045: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11068,10 +11074,10 @@
   for ac_func in isastream
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:11072: checking for $ac_func" >&5
+echo "configure:11078: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11075 "configure"
+#line 11081 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -11094,7 +11100,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:11098: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11104: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -11125,15 +11131,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:11129: checking for $ac_hdr" >&5
+echo "configure:11135: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11132 "configure"
+#line 11138 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:11137: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11143: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11170,10 +11176,10 @@
 for ac_func in getloadavg
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:11174: checking for $ac_func" >&5
+echo "configure:11180: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11177 "configure"
+#line 11183 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -11196,7 +11202,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:11200: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11206: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -11229,15 +11235,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:11233: checking for $ac_hdr" >&5
+echo "configure:11239: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11236 "configure"
+#line 11242 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:11241: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11247: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11273,12 +11279,12 @@
 
     
 echo $ac_n "checking for kstat_open in -lkstat""... $ac_c" 1>&6
-echo "configure:11277: checking for kstat_open in -lkstat" >&5
+echo "configure:11283: checking for kstat_open in -lkstat" >&5
 ac_lib_var=`echo kstat'_'kstat_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lkstat "
 cat > conftest.$ac_ext <<EOF
-#line 11282 "configure"
+#line 11288 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -11289,7 +11295,7 @@
 kstat_open()
 ; return 0; }
 EOF
-if { (eval echo configure:11293: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11299: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -11324,15 +11330,15 @@
 do
 ac_safe=`echo "$ac_hdr" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for $ac_hdr""... $ac_c" 1>&6
-echo "configure:11328: checking for $ac_hdr" >&5
+echo "configure:11334: checking for $ac_hdr" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11331 "configure"
+#line 11337 "configure"
 #include "confdefs.h"
 #include <$ac_hdr>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:11336: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11342: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11364,12 +11370,12 @@
 
     
 echo $ac_n "checking for kvm_read in -lkvm""... $ac_c" 1>&6
-echo "configure:11368: checking for kvm_read in -lkvm" >&5
+echo "configure:11374: checking for kvm_read in -lkvm" >&5
 ac_lib_var=`echo kvm'_'kvm_read | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lkvm "
 cat > conftest.$ac_ext <<EOF
-#line 11373 "configure"
+#line 11379 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -11380,7 +11386,7 @@
 kvm_read()
 ; return 0; }
 EOF
-if { (eval echo configure:11384: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11390: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -11414,16 +11420,16 @@
 fi
 
 echo $ac_n "checking whether netdb declares h_errno""... $ac_c" 1>&6
-echo "configure:11418: checking whether netdb declares h_errno" >&5
+echo "configure:11424: checking whether netdb declares h_errno" >&5
 cat > conftest.$ac_ext <<EOF
-#line 11420 "configure"
+#line 11426 "configure"
 #include "confdefs.h"
 #include <netdb.h>
 int main() {
 return h_errno;
 ; return 0; }
 EOF
-if { (eval echo configure:11427: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11433: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF
@@ -11443,16 +11449,16 @@
 rm -f conftest*
 
 echo $ac_n "checking for sigsetjmp""... $ac_c" 1>&6
-echo "configure:11447: checking for sigsetjmp" >&5
+echo "configure:11453: checking for sigsetjmp" >&5
 cat > conftest.$ac_ext <<EOF
-#line 11449 "configure"
+#line 11455 "configure"
 #include "confdefs.h"
 #include <setjmp.h>
 int main() {
 sigjmp_buf bar; sigsetjmp (bar, 0);
 ; return 0; }
 EOF
-if { (eval echo configure:11456: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:11462: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6
    { test "$extra_verbose" = "yes" && cat << \EOF
@@ -11472,11 +11478,11 @@
 rm -f conftest*
 
 echo $ac_n "checking whether localtime caches TZ""... $ac_c" 1>&6
-echo "configure:11476: checking whether localtime caches TZ" >&5
+echo "configure:11482: checking whether localtime caches TZ" >&5
 
 if test "$ac_cv_func_tzset" = "yes"; then
 cat > conftest.$ac_ext <<EOF
-#line 11480 "configure"
+#line 11486 "configure"
 #include "confdefs.h"
 #include <time.h>
 #if STDC_HEADERS
@@ -11511,7 +11517,7 @@
   exit (0);
 }
 EOF
-if { (eval echo configure:11515: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:11521: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   emacs_cv_localtime_cache=no
 else
@@ -11541,9 +11547,9 @@
 
 if test "$HAVE_TIMEVAL" = "yes"; then
 echo $ac_n "checking whether gettimeofday accepts one or two arguments""... $ac_c" 1>&6
-echo "configure:11545: checking whether gettimeofday accepts one or two arguments" >&5
+echo "configure:11551: checking whether gettimeofday accepts one or two arguments" >&5
 cat > conftest.$ac_ext <<EOF
-#line 11547 "configure"
+#line 11553 "configure"
 #include "confdefs.h"
 
 #ifdef TIME_WITH_SYS_TIME
@@ -11564,7 +11570,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:11568: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11574: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   echo "$ac_t""two" 1>&6
 else
@@ -11586,19 +11592,19 @@
 
 
 echo $ac_n "checking for inline""... $ac_c" 1>&6
-echo "configure:11590: checking for inline" >&5
+echo "configure:11596: checking for inline" >&5
 
 ac_cv_c_inline=no
 for ac_kw in inline __inline__ __inline; do
   cat > conftest.$ac_ext <<EOF
-#line 11595 "configure"
+#line 11601 "configure"
 #include "confdefs.h"
 
 int main() {
-} int $ac_kw foo() {
+} $ac_kw foo() {
 ; return 0; }
 EOF
-if { (eval echo configure:11602: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:11608: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   ac_cv_c_inline=$ac_kw; break
 else
@@ -11639,17 +11645,17 @@
   # The Ultrix 4.2 mips builtin alloca declared by alloca.h only works
 # for constant arguments.  Useless!
 echo $ac_n "checking for working alloca.h""... $ac_c" 1>&6
-echo "configure:11643: checking for working alloca.h" >&5
+echo "configure:11649: checking for working alloca.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11646 "configure"
+#line 11652 "configure"
 #include "confdefs.h"
 #include <alloca.h>
 int main() {
-void *p = alloca(2 * sizeof(int));
+char *p = alloca(2 * sizeof(int));
 ; return 0; }
 EOF
-if { (eval echo configure:11653: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11659: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   ac_cv_header_alloca_h=yes
 else
@@ -11673,10 +11679,10 @@
 fi
 
 echo $ac_n "checking for alloca""... $ac_c" 1>&6
-echo "configure:11677: checking for alloca" >&5
+echo "configure:11683: checking for alloca" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11680 "configure"
+#line 11686 "configure"
 #include "confdefs.h"
 
 #ifdef __GNUC__
@@ -11704,7 +11710,7 @@
 char *p = (char *) alloca(1);
 ; return 0; }
 EOF
-if { (eval echo configure:11708: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11714: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   ac_cv_func_alloca_works=yes
 else
@@ -11743,10 +11749,10 @@
 
 
 echo $ac_n "checking whether alloca needs Cray hooks""... $ac_c" 1>&6
-echo "configure:11747: checking whether alloca needs Cray hooks" >&5
+echo "configure:11753: checking whether alloca needs Cray hooks" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11750 "configure"
+#line 11756 "configure"
 #include "confdefs.h"
 #if defined(CRAY) && ! defined(CRAY2)
 webecray
@@ -11770,10 +11776,10 @@
 if test $ac_cv_os_cray = yes; then
 for ac_func in _getb67 GETB67 getb67; do
   echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:11774: checking for $ac_func" >&5
+echo "configure:11780: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11777 "configure"
+#line 11783 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -11796,7 +11802,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:11800: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:11806: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -11826,10 +11832,10 @@
 fi
 
 echo $ac_n "checking stack direction for C alloca""... $ac_c" 1>&6
-echo "configure:11830: checking stack direction for C alloca" >&5
+echo "configure:11836: checking stack direction for C alloca" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11833 "configure"
+#line 11839 "configure"
 #include "confdefs.h"
 find_stack_direction ()
 {
@@ -11848,7 +11854,7 @@
   exit (find_stack_direction() < 0);
 }
 EOF
-if { (eval echo configure:11852: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:11858: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_c_stack_direction=1
 else
@@ -11878,15 +11884,15 @@
 
 ac_safe=`echo "vfork.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for vfork.h""... $ac_c" 1>&6
-echo "configure:11882: checking for vfork.h" >&5
+echo "configure:11888: checking for vfork.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11885 "configure"
+#line 11891 "configure"
 #include "confdefs.h"
 #include <vfork.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:11890: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:11896: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -11914,10 +11920,10 @@
 fi
 
 echo $ac_n "checking for working vfork""... $ac_c" 1>&6
-echo "configure:11918: checking for working vfork" >&5
+echo "configure:11924: checking for working vfork" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 11921 "configure"
+#line 11927 "configure"
 #include "confdefs.h"
 /* Thanks to Paul Eggert for this test.  */
 #include <stdio.h>
@@ -12012,7 +12018,7 @@
   }
 }
 EOF
-if { (eval echo configure:12016: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12022: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_func_vfork_works=yes
 else
@@ -12038,10 +12044,10 @@
 
 
 echo $ac_n "checking for working strcoll""... $ac_c" 1>&6
-echo "configure:12042: checking for working strcoll" >&5
+echo "configure:12048: checking for working strcoll" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12045 "configure"
+#line 12051 "configure"
 #include "confdefs.h"
 #include <string.h>
 main ()
@@ -12051,7 +12057,7 @@
 	strcoll ("123", "456") >= 0);
 }
 EOF
-if { (eval echo configure:12055: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12061: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_func_strcoll_works=yes
 else
@@ -12079,10 +12085,10 @@
 for ac_func in getpgrp
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:12083: checking for $ac_func" >&5
+echo "configure:12089: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12086 "configure"
+#line 12092 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -12105,7 +12111,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:12109: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12115: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -12133,10 +12139,10 @@
 done
 
 echo $ac_n "checking whether getpgrp takes no argument""... $ac_c" 1>&6
-echo "configure:12137: checking whether getpgrp takes no argument" >&5
+echo "configure:12143: checking whether getpgrp takes no argument" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12140 "configure"
+#line 12146 "configure"
 #include "confdefs.h"
 
 /*
@@ -12191,7 +12197,7 @@
 }
 
 EOF
-if { (eval echo configure:12195: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12201: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   ac_cv_func_getpgrp_void=yes
 else
@@ -12218,10 +12224,10 @@
 
 
 echo $ac_n "checking for working mmap""... $ac_c" 1>&6
-echo "configure:12222: checking for working mmap" >&5
+echo "configure:12228: checking for working mmap" >&5
 case "$opsys" in ultrix* ) have_mmap=no ;; *)
 cat > conftest.$ac_ext <<EOF
-#line 12225 "configure"
+#line 12231 "configure"
 #include "confdefs.h"
 #include <stdio.h>
 #include <unistd.h>
@@ -12254,7 +12260,7 @@
   return 1;
 }
 EOF
-if { (eval echo configure:12258: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:12264: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   have_mmap=yes
 else
@@ -12283,9 +12289,9 @@
 if test "$rel_alloc $have_mmap" = "default yes"; then
   if test "$doug_lea_malloc" = "yes"; then
         echo $ac_n "checking for M_MMAP_THRESHOLD""... $ac_c" 1>&6
-echo "configure:12287: checking for M_MMAP_THRESHOLD" >&5
+echo "configure:12293: checking for M_MMAP_THRESHOLD" >&5
     cat > conftest.$ac_ext <<EOF
-#line 12289 "configure"
+#line 12295 "configure"
 #include "confdefs.h"
 #include <malloc.h>
 int main() {
@@ -12297,7 +12303,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:12301: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:12307: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   rel_alloc=no; echo "$ac_t""yes" 1>&6;
 else
@@ -12322,15 +12328,15 @@
 
 ac_safe=`echo "termios.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for termios.h""... $ac_c" 1>&6
-echo "configure:12326: checking for termios.h" >&5
+echo "configure:12332: checking for termios.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12329 "configure"
+#line 12335 "configure"
 #include "confdefs.h"
 #include <termios.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12334: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12340: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12373,15 +12379,15 @@
   echo "$ac_t""no" 1>&6
 ac_safe=`echo "termio.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for termio.h""... $ac_c" 1>&6
-echo "configure:12377: checking for termio.h" >&5
+echo "configure:12383: checking for termio.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12380 "configure"
+#line 12386 "configure"
 #include "confdefs.h"
 #include <termio.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12385: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12391: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12413,10 +12419,10 @@
 
 
 echo $ac_n "checking for socket""... $ac_c" 1>&6
-echo "configure:12417: checking for socket" >&5
+echo "configure:12423: checking for socket" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12420 "configure"
+#line 12426 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char socket(); below.  */
@@ -12439,7 +12445,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:12443: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12449: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_socket=yes"
 else
@@ -12454,15 +12460,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "netinet/in.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for netinet/in.h""... $ac_c" 1>&6
-echo "configure:12458: checking for netinet/in.h" >&5
+echo "configure:12464: checking for netinet/in.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12461 "configure"
+#line 12467 "configure"
 #include "confdefs.h"
 #include <netinet/in.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12466: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12472: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12479,15 +12485,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "arpa/inet.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for arpa/inet.h""... $ac_c" 1>&6
-echo "configure:12483: checking for arpa/inet.h" >&5
+echo "configure:12489: checking for arpa/inet.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12486 "configure"
+#line 12492 "configure"
 #include "confdefs.h"
 #include <arpa/inet.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12491: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12497: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12512,9 +12518,9 @@
 }
 
       echo $ac_n "checking "for sun_len member in struct sockaddr_un"""... $ac_c" 1>&6
-echo "configure:12516: checking "for sun_len member in struct sockaddr_un"" >&5
+echo "configure:12522: checking "for sun_len member in struct sockaddr_un"" >&5
       cat > conftest.$ac_ext <<EOF
-#line 12518 "configure"
+#line 12524 "configure"
 #include "confdefs.h"
 
 #include <sys/types.h>
@@ -12525,7 +12531,7 @@
 static struct sockaddr_un x; x.sun_len = 1;
 ; return 0; }
 EOF
-if { (eval echo configure:12529: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12535: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_SOCKADDR_SUN_LEN
@@ -12543,9 +12549,9 @@
 fi
 rm -f conftest*
       echo $ac_n "checking "for ip_mreq struct in netinet/in.h"""... $ac_c" 1>&6
-echo "configure:12547: checking "for ip_mreq struct in netinet/in.h"" >&5
+echo "configure:12553: checking "for ip_mreq struct in netinet/in.h"" >&5
       cat > conftest.$ac_ext <<EOF
-#line 12549 "configure"
+#line 12555 "configure"
 #include "confdefs.h"
 
 #include <sys/types.h>
@@ -12555,7 +12561,7 @@
 static struct ip_mreq x;
 ; return 0; }
 EOF
-if { (eval echo configure:12559: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12565: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   echo "$ac_t""yes" 1>&6; { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_MULTICAST
@@ -12586,10 +12592,10 @@
 
 
 echo $ac_n "checking for msgget""... $ac_c" 1>&6
-echo "configure:12590: checking for msgget" >&5
+echo "configure:12596: checking for msgget" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12593 "configure"
+#line 12599 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char msgget(); below.  */
@@ -12612,7 +12618,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:12616: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12622: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_msgget=yes"
 else
@@ -12627,15 +12633,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "sys/ipc.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for sys/ipc.h""... $ac_c" 1>&6
-echo "configure:12631: checking for sys/ipc.h" >&5
+echo "configure:12637: checking for sys/ipc.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12634 "configure"
+#line 12640 "configure"
 #include "confdefs.h"
 #include <sys/ipc.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12639: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12645: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12652,15 +12658,15 @@
   echo "$ac_t""yes" 1>&6
   ac_safe=`echo "sys/msg.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for sys/msg.h""... $ac_c" 1>&6
-echo "configure:12656: checking for sys/msg.h" >&5
+echo "configure:12662: checking for sys/msg.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12659 "configure"
+#line 12665 "configure"
 #include "confdefs.h"
 #include <sys/msg.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12664: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12670: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12698,15 +12704,15 @@
 
 ac_safe=`echo "dirent.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dirent.h""... $ac_c" 1>&6
-echo "configure:12702: checking for dirent.h" >&5
+echo "configure:12708: checking for dirent.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12705 "configure"
+#line 12711 "configure"
 #include "confdefs.h"
 #include <dirent.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12710: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12716: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12733,15 +12739,15 @@
   echo "$ac_t""no" 1>&6
 ac_safe=`echo "sys/dir.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for sys/dir.h""... $ac_c" 1>&6
-echo "configure:12737: checking for sys/dir.h" >&5
+echo "configure:12743: checking for sys/dir.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12740 "configure"
+#line 12746 "configure"
 #include "confdefs.h"
 #include <sys/dir.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12745: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12751: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12774,15 +12780,15 @@
 
 ac_safe=`echo "nlist.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for nlist.h""... $ac_c" 1>&6
-echo "configure:12778: checking for nlist.h" >&5
+echo "configure:12784: checking for nlist.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12781 "configure"
+#line 12787 "configure"
 #include "confdefs.h"
 #include <nlist.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12786: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12792: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12812,22 +12818,22 @@
 
 
 echo "checking "for sound support"" 1>&6
-echo "configure:12816: checking "for sound support"" >&5
+echo "configure:12822: checking "for sound support"" >&5
 test -z "$with_native_sound" -a -n "$native_sound_lib" && with_native_sound=yes
 
 if test "$with_native_sound" != "no"; then
     if test -n "$native_sound_lib"; then
     ac_safe=`echo "multimedia/audio_device.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for multimedia/audio_device.h""... $ac_c" 1>&6
-echo "configure:12823: checking for multimedia/audio_device.h" >&5
+echo "configure:12829: checking for multimedia/audio_device.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12826 "configure"
+#line 12832 "configure"
 #include "confdefs.h"
 #include <multimedia/audio_device.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12831: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:12837: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -12875,12 +12881,12 @@
       if test -z "$native_sound_lib"; then
         
 echo $ac_n "checking for ALopenport in -laudio""... $ac_c" 1>&6
-echo "configure:12879: checking for ALopenport in -laudio" >&5
+echo "configure:12885: checking for ALopenport in -laudio" >&5
 ac_lib_var=`echo audio'_'ALopenport | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF
-#line 12884 "configure"
+#line 12890 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -12891,7 +12897,7 @@
 ALopenport()
 ; return 0; }
 EOF
-if { (eval echo configure:12895: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12901: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -12922,12 +12928,12 @@
       if test -z "$native_sound_lib"; then
 	
 echo $ac_n "checking for AOpenAudio in -lAlib""... $ac_c" 1>&6
-echo "configure:12926: checking for AOpenAudio in -lAlib" >&5
+echo "configure:12932: checking for AOpenAudio in -lAlib" >&5
 ac_lib_var=`echo Alib'_'AOpenAudio | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lAlib "
 cat > conftest.$ac_ext <<EOF
-#line 12931 "configure"
+#line 12937 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -12938,7 +12944,7 @@
 AOpenAudio()
 ; return 0; }
 EOF
-if { (eval echo configure:12942: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:12948: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -12973,18 +12979,25 @@
   fi
 
     if test -z "$sound_found"; then
+    if test "$with_msw" = "yes"; then
+    sound_found=yes
+    native_sound_lib=
+    fi
+  fi
+
+    if test -z "$sound_found"; then
     for dir in "machine" "sys" "linux"; do
       ac_safe=`echo "${dir}/soundcard.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ${dir}/soundcard.h""... $ac_c" 1>&6
-echo "configure:12980: checking for ${dir}/soundcard.h" >&5
+echo "configure:12993: checking for ${dir}/soundcard.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 12983 "configure"
+#line 12996 "configure"
 #include "confdefs.h"
 #include <${dir}/soundcard.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:12988: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13001: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13020,13 +13033,6 @@
     done
   fi
 
-    if test -z "$sound_found"; then
-    if test "$with_msw" = "yes"; then
-    sound_found=yes
-    native_sound_lib=
-    fi
-  fi
-
   test "$sound_found" = "yes" && with_native_sound=yes
 fi
 
@@ -13045,15 +13051,15 @@
 if test "$with_nas_sound" != "no"; then
   ac_safe=`echo "audio/audiolib.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for audio/audiolib.h""... $ac_c" 1>&6
-echo "configure:13049: checking for audio/audiolib.h" >&5
+echo "configure:13055: checking for audio/audiolib.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13052 "configure"
+#line 13058 "configure"
 #include "confdefs.h"
 #include <audio/audiolib.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13057: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13063: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13071,12 +13077,12 @@
   
     
 echo $ac_n "checking for AuOpenServer in -laudio""... $ac_c" 1>&6
-echo "configure:13075: checking for AuOpenServer in -laudio" >&5
+echo "configure:13081: checking for AuOpenServer in -laudio" >&5
 ac_lib_var=`echo audio'_'AuOpenServer | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -laudio "
 cat > conftest.$ac_ext <<EOF
-#line 13080 "configure"
+#line 13086 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13087,7 +13093,7 @@
 AuOpenServer()
 ; return 0; }
 EOF
-if { (eval echo configure:13091: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13097: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13126,7 +13132,7 @@
  fi
     libs_x="-laudio $libs_x" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"-laudio\" to \$libs_x"; fi
             cat > conftest.$ac_ext <<EOF
-#line 13130 "configure"
+#line 13136 "configure"
 #include "confdefs.h"
 #include <audio/Xtutil.h>
 EOF
@@ -13157,7 +13163,7 @@
   # Extract the first word of "esd-config", so it can be a program name with args.
 set dummy esd-config; ac_word=$2
 echo $ac_n "checking for $ac_word""... $ac_c" 1>&6
-echo "configure:13161: checking for $ac_word" >&5
+echo "configure:13167: checking for $ac_word" >&5
 
 if test -n "$have_esd_config"; then
   ac_cv_prog_have_esd_config="$have_esd_config" # Let the user override the test.
@@ -13186,10 +13192,10 @@
     c_switch_site="$c_switch_site `esd-config --cflags`" &&  if test "$extra_verbose" = "yes"; then echo "    Appending \"`esd-config --cflags`\" to \$c_switch_site"; fi
     LIBS="`esd-config --libs` $LIBS" &&  if test "$extra_verbose" = "yes"; then echo "    Prepending \"`esd-config --libs`\" to \$LIBS"; fi
     echo $ac_n "checking for esd_play_stream""... $ac_c" 1>&6
-echo "configure:13190: checking for esd_play_stream" >&5
+echo "configure:13196: checking for esd_play_stream" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13193 "configure"
+#line 13199 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char esd_play_stream(); below.  */
@@ -13212,7 +13218,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:13216: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13222: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_esd_play_stream=yes"
 else
@@ -13263,7 +13269,7 @@
 
 if test "$with_tty" = "yes"  ; then
   echo "checking for TTY-related features" 1>&6
-echo "configure:13267: checking for TTY-related features" >&5
+echo "configure:13273: checking for TTY-related features" >&5
   { test "$extra_verbose" = "yes" && cat << \EOF
     Defining HAVE_TTY
 EOF
@@ -13279,12 +13285,12 @@
     if test -z "$with_ncurses"; then
     
 echo $ac_n "checking for tgetent in -lncurses""... $ac_c" 1>&6
-echo "configure:13283: checking for tgetent in -lncurses" >&5
+echo "configure:13289: checking for tgetent in -lncurses" >&5
 ac_lib_var=`echo ncurses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lncurses "
 cat > conftest.$ac_ext <<EOF
-#line 13288 "configure"
+#line 13294 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13295,7 +13301,7 @@
 tgetent()
 ; return 0; }
 EOF
-if { (eval echo configure:13299: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13305: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13328,15 +13334,15 @@
 
     ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6
-echo "configure:13332: checking for ncurses/curses.h" >&5
+echo "configure:13338: checking for ncurses/curses.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13335 "configure"
+#line 13341 "configure"
 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13340: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13346: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13358,15 +13364,15 @@
 
     ac_safe=`echo "ncurses/term.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/term.h""... $ac_c" 1>&6
-echo "configure:13362: checking for ncurses/term.h" >&5
+echo "configure:13368: checking for ncurses/term.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13365 "configure"
+#line 13371 "configure"
 #include "confdefs.h"
 #include <ncurses/term.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13370: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13376: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13396,15 +13402,15 @@
       c_switch_site="$c_switch_site -I/usr/include/ncurses"
       ac_safe=`echo "ncurses/curses.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ncurses/curses.h""... $ac_c" 1>&6
-echo "configure:13400: checking for ncurses/curses.h" >&5
+echo "configure:13406: checking for ncurses/curses.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13403 "configure"
+#line 13409 "configure"
 #include "confdefs.h"
 #include <ncurses/curses.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13408: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13414: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13439,12 +13445,12 @@
 	for lib in curses termlib termcap; do
 	  
 echo $ac_n "checking for tgetent in -l$lib""... $ac_c" 1>&6
-echo "configure:13443: checking for tgetent in -l$lib" >&5
+echo "configure:13449: checking for tgetent in -l$lib" >&5
 ac_lib_var=`echo $lib'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -l$lib "
 cat > conftest.$ac_ext <<EOF
-#line 13448 "configure"
+#line 13454 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13455,7 +13461,7 @@
 tgetent()
 ; return 0; }
 EOF
-if { (eval echo configure:13459: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13465: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13486,12 +13492,12 @@
       else
 	
 echo $ac_n "checking for tgetent in -lcurses""... $ac_c" 1>&6
-echo "configure:13490: checking for tgetent in -lcurses" >&5
+echo "configure:13496: checking for tgetent in -lcurses" >&5
 ac_lib_var=`echo curses'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lcurses "
 cat > conftest.$ac_ext <<EOF
-#line 13495 "configure"
+#line 13501 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13502,7 +13508,7 @@
 tgetent()
 ; return 0; }
 EOF
-if { (eval echo configure:13506: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13512: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13520,12 +13526,12 @@
 else
   echo "$ac_t""no" 1>&6
 echo $ac_n "checking for tgetent in -ltermcap""... $ac_c" 1>&6
-echo "configure:13524: checking for tgetent in -ltermcap" >&5
+echo "configure:13530: checking for tgetent in -ltermcap" >&5
 ac_lib_var=`echo termcap'_'tgetent | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ltermcap "
 cat > conftest.$ac_ext <<EOF
-#line 13529 "configure"
+#line 13535 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13536,7 +13542,7 @@
 tgetent()
 ; return 0; }
 EOF
-if { (eval echo configure:13540: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13546: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13584,15 +13590,15 @@
 
     test -z "$with_gpm" && { ac_safe=`echo "gpm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for gpm.h""... $ac_c" 1>&6
-echo "configure:13588: checking for gpm.h" >&5
+echo "configure:13594: checking for gpm.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13591 "configure"
+#line 13597 "configure"
 #include "confdefs.h"
 #include <gpm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13596: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13602: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13615,12 +13621,12 @@
  }
   test -z "$with_gpm" && { 
 echo $ac_n "checking for Gpm_Open in -lgpm""... $ac_c" 1>&6
-echo "configure:13619: checking for Gpm_Open in -lgpm" >&5
+echo "configure:13625: checking for Gpm_Open in -lgpm" >&5
 ac_lib_var=`echo gpm'_'Gpm_Open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgpm "
 cat > conftest.$ac_ext <<EOF
-#line 13624 "configure"
+#line 13630 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13631,7 +13637,7 @@
 Gpm_Open()
 ; return 0; }
 EOF
-if { (eval echo configure:13635: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13641: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13681,20 +13687,20 @@
 
 test "$with_database_gdbm $with_database_dbm $with_database_berkdb" \
   != "no no no" && echo "checking for database support" 1>&6
-echo "configure:13685: checking for database support" >&5
+echo "configure:13691: checking for database support" >&5
 
 if test "$with_database_gdbm $with_database_dbm" != "no no"; then
   ac_safe=`echo "ndbm.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for ndbm.h""... $ac_c" 1>&6
-echo "configure:13690: checking for ndbm.h" >&5
+echo "configure:13696: checking for ndbm.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13693 "configure"
+#line 13699 "configure"
 #include "confdefs.h"
 #include <ndbm.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:13698: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:13704: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -13724,12 +13730,12 @@
 if test "$with_database_gdbm" != "no"; then
   
 echo $ac_n "checking for dbm_open in -lgdbm""... $ac_c" 1>&6
-echo "configure:13728: checking for dbm_open in -lgdbm" >&5
+echo "configure:13734: checking for dbm_open in -lgdbm" >&5
 ac_lib_var=`echo gdbm'_'dbm_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lgdbm "
 cat > conftest.$ac_ext <<EOF
-#line 13733 "configure"
+#line 13739 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13740,7 +13746,7 @@
 dbm_open()
 ; return 0; }
 EOF
-if { (eval echo configure:13744: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13750: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13768,10 +13774,10 @@
 
 if test "$with_database_dbm" != "no"; then
   echo $ac_n "checking for dbm_open""... $ac_c" 1>&6
-echo "configure:13772: checking for dbm_open" >&5
+echo "configure:13778: checking for dbm_open" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13775 "configure"
+#line 13781 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char dbm_open(); below.  */
@@ -13794,7 +13800,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:13798: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13804: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_dbm_open=yes"
 else
@@ -13813,12 +13819,12 @@
 
     
 echo $ac_n "checking for dbm_open in -ldbm""... $ac_c" 1>&6
-echo "configure:13817: checking for dbm_open in -ldbm" >&5
+echo "configure:13823: checking for dbm_open in -ldbm" >&5
 ac_lib_var=`echo dbm'_'dbm_open | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldbm "
 cat > conftest.$ac_ext <<EOF
-#line 13822 "configure"
+#line 13828 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -13829,7 +13835,7 @@
 dbm_open()
 ; return 0; }
 EOF
-if { (eval echo configure:13833: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13839: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -13870,10 +13876,10 @@
 
 if test "$with_database_berkdb" != "no"; then
   echo $ac_n "checking for Berkeley db.h""... $ac_c" 1>&6
-echo "configure:13874: checking for Berkeley db.h" >&5
+echo "configure:13880: checking for Berkeley db.h" >&5
   for header in "db/db.h" "db.h"; do
     cat > conftest.$ac_ext <<EOF
-#line 13877 "configure"
+#line 13883 "configure"
 #include "confdefs.h"
 
 #include <stdlib.h>
@@ -13895,7 +13901,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:13899: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:13905: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   db_h_file="$header"; break
 else
@@ -13911,9 +13917,9 @@
 
   if test "$with_database_berkdb" != "no"; then
     echo $ac_n "checking for Berkeley DB version""... $ac_c" 1>&6
-echo "configure:13915: checking for Berkeley DB version" >&5
+echo "configure:13921: checking for Berkeley DB version" >&5
     cat > conftest.$ac_ext <<EOF
-#line 13917 "configure"
+#line 13923 "configure"
 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 1
@@ -13925,7 +13931,7 @@
   egrep "yes" >/dev/null 2>&1; then
   rm -rf conftest*
   cat > conftest.$ac_ext <<EOF
-#line 13929 "configure"
+#line 13935 "configure"
 #include "confdefs.h"
 #include <$db_h_file>
 #if DB_VERSION_MAJOR > 2
@@ -13952,10 +13958,10 @@
 rm -f conftest*
 
     echo $ac_n "checking for $dbfunc""... $ac_c" 1>&6
-echo "configure:13956: checking for $dbfunc" >&5
+echo "configure:13962: checking for $dbfunc" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 13959 "configure"
+#line 13965 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $dbfunc(); below.  */
@@ -13978,7 +13984,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:13982: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:13988: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$dbfunc=yes"
 else
@@ -13997,12 +14003,12 @@
 
     
 echo $ac_n "checking for $dbfunc in -ldb""... $ac_c" 1>&6
-echo "configure:14001: checking for $dbfunc in -ldb" >&5
+echo "configure:14007: checking for $dbfunc in -ldb" >&5
 ac_lib_var=`echo db'_'$dbfunc | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldb "
 cat > conftest.$ac_ext <<EOF
-#line 14006 "configure"
+#line 14012 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -14013,7 +14019,7 @@
 $dbfunc()
 ; return 0; }
 EOF
-if { (eval echo configure:14017: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14023: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -14077,12 +14083,12 @@
 if test "$with_socks" = "yes"; then
   
 echo $ac_n "checking for SOCKSinit in -lsocks""... $ac_c" 1>&6
-echo "configure:14081: checking for SOCKSinit in -lsocks" >&5
+echo "configure:14087: checking for SOCKSinit in -lsocks" >&5
 ac_lib_var=`echo socks'_'SOCKSinit | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -lsocks "
 cat > conftest.$ac_ext <<EOF
-#line 14086 "configure"
+#line 14092 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -14093,7 +14099,7 @@
 SOCKSinit()
 ; return 0; }
 EOF
-if { (eval echo configure:14097: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14103: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -14148,22 +14154,22 @@
 
 if test "$with_modules" != "no"; then
   echo "checking for module support" 1>&6
-echo "configure:14152: checking for module support" >&5
+echo "configure:14158: checking for module support" >&5
 
     if test "$with_msw" = "yes"; then
     have_dl=yes;
   else
         ac_safe=`echo "dlfcn.h" | sed 'y%./+-%__p_%'`
 echo $ac_n "checking for dlfcn.h""... $ac_c" 1>&6
-echo "configure:14159: checking for dlfcn.h" >&5
+echo "configure:14165: checking for dlfcn.h" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 14162 "configure"
+#line 14168 "configure"
 #include "confdefs.h"
 #include <dlfcn.h>
 EOF
 ac_try="$ac_cpp conftest.$ac_ext >/dev/null 2>conftest.out"
-{ (eval echo configure:14167: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
+{ (eval echo configure:14173: \"$ac_try\") 1>&5; (eval $ac_try) 2>&5; }
 ac_err=`grep -v '^ *+' conftest.out | grep -v "^conftest.${ac_ext}\$"`
 if test -z "$ac_err"; then
   rm -rf conftest*
@@ -14180,16 +14186,16 @@
   echo "$ac_t""yes" 1>&6
   
       echo $ac_n "checking for dlopen in -lc""... $ac_c" 1>&6
-echo "configure:14184: checking for dlopen in -lc" >&5
+echo "configure:14190: checking for dlopen in -lc" >&5
       cat > conftest.$ac_ext <<EOF
-#line 14186 "configure"
+#line 14192 "configure"
 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
 	dlopen ("", 0);
 ; return 0; }
 EOF
-if { (eval echo configure:14193: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14199: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
    have_dl=yes 
 else
@@ -14198,18 +14204,18 @@
   rm -rf conftest*
   
       echo $ac_n "checking for dlopen in -ldl""... $ac_c" 1>&6
-echo "configure:14202: checking for dlopen in -ldl" >&5
+echo "configure:14208: checking for dlopen in -ldl" >&5
       ac_save_LIBS="$LIBS"
       LIBS="-ldl $LIBS"
       cat > conftest.$ac_ext <<EOF
-#line 14206 "configure"
+#line 14212 "configure"
 #include "confdefs.h"
 #include <dlfcn.h>
 int main() {
 	dlopen ("", 0);
 ; return 0; }
 EOF
-if { (eval echo configure:14213: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14219: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
    have_dl=yes 
 else
@@ -14238,12 +14244,12 @@
     else
       
 echo $ac_n "checking for shl_load in -ldld""... $ac_c" 1>&6
-echo "configure:14242: checking for shl_load in -ldld" >&5
+echo "configure:14248: checking for shl_load in -ldld" >&5
 ac_lib_var=`echo dld'_'shl_load | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldld "
 cat > conftest.$ac_ext <<EOF
-#line 14247 "configure"
+#line 14253 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -14254,7 +14260,7 @@
 shl_load()
 ; return 0; }
 EOF
-if { (eval echo configure:14258: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14264: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -14281,12 +14287,12 @@
   echo "$ac_t""no" 1>&6
 
 echo $ac_n "checking for dld_init in -ldld""... $ac_c" 1>&6
-echo "configure:14285: checking for dld_init in -ldld" >&5
+echo "configure:14291: checking for dld_init in -ldld" >&5
 ac_lib_var=`echo dld'_'dld_init | sed 'y%./+-%__p_%'`
 
 xe_check_libs=" -ldld "
 cat > conftest.$ac_ext <<EOF
-#line 14290 "configure"
+#line 14296 "configure"
 #include "confdefs.h"
 /* Override any gcc2 internal prototype to avoid an error.  */
 /* We use char because int might match the return type of a gcc2
@@ -14297,7 +14303,7 @@
 dld_init()
 ; return 0; }
 EOF
-if { (eval echo configure:14301: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14307: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_lib_$ac_lib_var=yes"
 else
@@ -14342,7 +14348,7 @@
 xealias=$internal_configuration
 
 echo "checking how to build dynamic libraries for ${xehost}" 1>&6
-echo "configure:14346: checking how to build dynamic libraries for ${xehost}" >&5
+echo "configure:14352: checking how to build dynamic libraries for ${xehost}" >&5
 # Transform *-*-linux* to *-*-linux-gnu*, to support old configure scripts.
 case "$xehost" in
 *-*-linux-gnu*) ;;
@@ -14370,9 +14376,9 @@
   XEGCC=yes
 else
   echo $ac_n "checking checking whether we are using GNU C""... $ac_c" 1>&6
-echo "configure:14374: checking checking whether we are using GNU C" >&5
+echo "configure:14380: checking checking whether we are using GNU C" >&5
   cat > conftest.$ac_ext <<EOF
-#line 14376 "configure"
+#line 14382 "configure"
 #include "confdefs.h"
 
 #ifdef __GNUC__
@@ -14394,7 +14400,7 @@
 fi
 
 echo $ac_n "checking how to produce PIC code""... $ac_c" 1>&6
-echo "configure:14398: checking how to produce PIC code" >&5
+echo "configure:14404: checking how to produce PIC code" >&5
 wl=
 
 can_build_shared=yes
@@ -14495,18 +14501,18 @@
 
   # Check to make sure the dll_cflags actually works.
   echo $ac_n "checking if PIC flag ${dll_cflags} really works""... $ac_c" 1>&6
-echo "configure:14499: checking if PIC flag ${dll_cflags} really works" >&5
+echo "configure:14505: checking if PIC flag ${dll_cflags} really works" >&5
   save_CFLAGS="$CFLAGS"
   CFLAGS="$CFLAGS $dll_cflags -DPIC"
   cat > conftest.$ac_ext <<EOF
-#line 14503 "configure"
+#line 14509 "configure"
 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF
-if { (eval echo configure:14510: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
+if { (eval echo configure:14516: \"$ac_compile\") 1>&5; (eval $ac_compile) 2>&5; }; then
   rm -rf conftest*
   
     # On HP-UX, the stripped-down bundled CC doesn't accept +Z, but also
@@ -14537,7 +14543,7 @@
 xldf=
 xcldf=
 echo $ac_n "checking if C compiler can produce shared libraries""... $ac_c" 1>&6
-echo "configure:14541: checking if C compiler can produce shared libraries" >&5
+echo "configure:14547: checking if C compiler can produce shared libraries" >&5
 if test "$XEGCC" = yes; then
   xcldf="-shared"
   xldf="-shared"
@@ -14588,14 +14594,14 @@
   xe_libs=
   ac_link='${CC-cc} -o conftest $CFLAGS '"$xe_cppflags $xe_ldflags"' conftest.$ac_ext '"$xe_libs"' 1>&5'
   cat > conftest.$ac_ext <<EOF
-#line 14592 "configure"
+#line 14598 "configure"
 #include "confdefs.h"
 
 int main() {
 int x=0;
 ; return 0; }
 EOF
-if { (eval echo configure:14599: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14605: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   cc_produces_so=yes
 else
@@ -14620,7 +14626,7 @@
   if test "$XEGCC" = yes; then
     # Check if gcc -print-prog-name=ld gives a path.
     echo $ac_n "checking for ld used by GCC""... $ac_c" 1>&6
-echo "configure:14624: checking for ld used by GCC" >&5
+echo "configure:14630: checking for ld used by GCC" >&5
     ac_prog=`($CC -print-prog-name=ld) 2>&5`
     case "$ac_prog" in
     # Accept absolute paths.
@@ -14645,7 +14651,7 @@
     esac
   else
     echo $ac_n "checking for GNU ld""... $ac_c" 1>&6
-echo "configure:14649: checking for GNU ld" >&5
+echo "configure:14655: checking for GNU ld" >&5
   fi
 
   if test -z "$LTLD"; then
@@ -14683,7 +14689,7 @@
 
 # Check to see if it really is or isn't GNU ld.
 echo $ac_n "checking if the linker is GNU ld""... $ac_c" 1>&6
-echo "configure:14687: checking if the linker is GNU ld" >&5
+echo "configure:14693: checking if the linker is GNU ld" >&5
 # I'd rather use --version here, but apparently some GNU ld's only accept -v.
 if $LTLD -v 2>&1 </dev/null | egrep '(GNU|with BFD)' 1>&5; then
   xe_gnu_ld=yes
@@ -14711,7 +14717,7 @@
   # OK - only NOW do we futz about with ld.
   # See if the linker supports building shared libraries.
   echo $ac_n "checking whether the linker supports shared libraries""... $ac_c" 1>&6
-echo "configure:14715: checking whether the linker supports shared libraries" >&5
+echo "configure:14721: checking whether the linker supports shared libraries" >&5
   dll_ld=$CC
   dll_ldflags=$LDFLAGS
   ld_shlibs=yes
@@ -14922,10 +14928,10 @@
     for ac_func in dlerror _dlerror
 do
 echo $ac_n "checking for $ac_func""... $ac_c" 1>&6
-echo "configure:14926: checking for $ac_func" >&5
+echo "configure:14932: checking for $ac_func" >&5
 
 cat > conftest.$ac_ext <<EOF
-#line 14929 "configure"
+#line 14935 "configure"
 #include "confdefs.h"
 /* System header to define __stub macros and hopefully few prototypes,
     which can conflict with char $ac_func(); below.  */
@@ -14948,7 +14954,7 @@
 
 ; return 0; }
 EOF
-if { (eval echo configure:14952: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
+if { (eval echo configure:14958: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest${ac_exeext}; then
   rm -rf conftest*
   eval "ac_cv_func_$ac_func=yes"
 else
@@ -14987,11 +14993,11 @@
 fi
 
 cat > conftest.$ac_ext <<EOF
-#line 14991 "configure"
+#line 14997 "configure"
 #include "confdefs.h"
 int main(int c,char *v[]){return 0;}
 EOF
-if { (eval echo configure:14995: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
+if { (eval echo configure:15001: \"$ac_link\") 1>&5; (eval $ac_link) 2>&5; } && test -s conftest && (./conftest; exit $?) 2>&5
 then
   :
 else
diff --text -u 'xemacs-21.4.2/configure.in' 'xemacs-21.4.3/configure.in'
Index: ././configure.in
--- ././configure.in	Wed May  9 19:02:59 2001
+++ ././configure.in	Tue May 15 21:18:50 2001
@@ -4040,6 +4040,14 @@
     esac
   fi
 
+  dnl Win32 Native uses native sound
+  if test -z "$sound_found"; then
+    if test "$with_msw" = "yes"; then
+    sound_found=yes
+    native_sound_lib=
+    fi
+  fi
+
   dnl Check for Linux/BSD native sound
   if test -z "$sound_found"; then
     for dir in "machine" "sys" "linux"; do
@@ -4050,14 +4058,6 @@
         [AC_DEFINE_UNQUOTED(SOUNDCARD_H_FILE, "${dir}/soundcard.h")]
         break)
     done
-  fi
-
-  dnl Win32 Native uses native sound
-  if test -z "$sound_found"; then
-    if test "$with_msw" = "yes"; then
-    sound_found=yes
-    native_sound_lib=
-    fi
   fi
 
   test "$sound_found" = "yes" && with_native_sound=yes
diff --text -u 'xemacs-21.4.2/etc/PACKAGES' 'xemacs-21.4.3/etc/PACKAGES'
Index: ././etc/PACKAGES
--- ././etc/PACKAGES	Mon Jan 22 05:14:58 2001
+++ ././etc/PACKAGES	Tue May 15 21:13:40 2001
@@ -7,123 +7,145 @@
 
 For general XEmacs navigation tips: Press C-h t
 
-Description of available packages by category
-=============================================
-This data is up-to-date as of January 17, 2001.
-
-** Library Packages (libs)
-==========================
-These packages are required to build and support most of the rest of
-XEmacs.  By design, xemacs-base is a `regular' package.  Use restraint 
-when adding new files there as it is required by almost everything.
+Description of available packages
+=================================
+Up-to-date as of May 15, 2001.
+
+** Normal Packages
+==================
+A very broad collection of elisp packages.
 
 *** Sun
 Support for Sparcworks.
 
+*** ada
+Ada language support.
+
 *** apel
 A Portable Emacs Library.  Used by XEmacs MIME support.
 
-*** dired
-The DIRectory EDitor is for manipulating, and running commands on
-files in a directory.
+*** auctex
+Basic TeX/LaTeX support.
 
-*** edebug
-A Lisp debugger.
+*** bbdb
+The Big Brother Data Base
 
-*** efs
-Treat files on remote systems the same as local files.
+*** build
+Build XEmacs using custom widgets.
 
-*** elib
-Portable Emacs Lisp utilities library.
+*** c-support
+Basic single-file add-ons for editing C code.
 
-*** fsf-compat
-FSF Emacs compatibility files.
+*** calc
+Emacs calculator.
 
-*** mail-lib
-Fundamental lisp files for providing email support.
+*** calendar
+Calendar and diary support.
 
-*** sounds-au
-XEmacs Sun sound files.
+*** cc-mode
+C, C++ and Java language support.
 
-*** sounds-wav
-XEmacs Microsoft sound files.
+*** cookie
+Spook and Yow (Zippy quotes).
 
-*** tooltalk
-Support for building with Tooltalk.
+*** crisp
+Crisp/Brief emulation.
 
-*** xemacs-base
-Fundamental XEmacs support.  Install this unless you wish a totally
-naked XEmacs.
+*** debug
+GUD, gdb, dbx debugging support.
 
-*** xemacs-devel
-XEmacs Lisp developer support.  This package contains utilities for
-supporting Lisp development.  It is a single-file package so it may be 
-tailored.
+*** dired
+The DIRectory EDitor is for manipulating, and running commands on
+files in a directory.
 
-** Communications Packages (comm)
-=================================
-These packages provide support for various communications, primarily
-email and usenet.
+*** edebug
+A Lisp debugger.
 
-*** bbdb
-The Big Brother Data Base
+*** ediff
+Interface over patch.
+
+*** edit-utils
+Single file lisp packages for various XEmacs goodies.  Load this and
+weed out the junk you don't want.
+
+*** edt
+DEC EDIT/EDT emulation.
+
+*** efs
+Treat files on remote systems the same as local files.
 
 *** eicq
 ICQ Client developed and tested on Linux x86; 
 only supported on that platform
 
+*** eieio
+Enhanced Implementation of Emacs Interpreted Objects
+
+*** elib
+Portable Emacs Lisp utilities library.
+
+*** emerge
+Another interface over patch.
+
+*** eshell
+Command shell implemented entirely in Emacs Lisp.
+
+*** eterm
+Terminal emulator.
+
 *** eudc
 Emacs Unified Directory Client (LDAP, PH).
 
 *** footnote
 Footnoting in mail message editing modes.
 
+*** forms
+Forms editing support (obsolete, use the built-in Widget instead).
+
+*** frame-icon
+Provide a WM icon based on major mode.
+
+*** fsf-compat
+FSF Emacs compatibility files.
+
+*** games
+Tetris, Sokoban, and Snake.
+
 *** gnats
 XEmacs bug reports.
 
 *** gnus
 The Gnus Newsreader and Mailreader.
 
-*** mailcrypt
-Support for messaging encryption with PGP.
-
-*** mew
-Messaging in an Emacs World.
-
-*** mh-e
-Front end support for MH.
-
-*** net-utils
-Miscellaneous Networking Utilities.  This is a single-file package and 
-files may be deleted at will.
+*** hm--html-menus
+HTML editing.
 
-*** rmail
-An obsolete Emacs mailer.  If you do not already use it don't start.
+*** idlwave
+Editing and Shell mode for the Interactive Data Language.
 
-*** supercite
-An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.
+*** igrep
+Enhanced front-end for Grep.
 
-*** tm
-Emacs MIME support. Not needed for Gnus >= 5.8.0
+*** ilisp
+Front-end for Inferior Lisp.
 
-*** vm
-An Emacs mailer.
+*** ispell
+Spell-checking with ispell.
 
-*** w3
-A Web browser.
+*** jde
+Java language and development support.
 
-*** zenirc
-ZENIRC IRC Client.
+*** mail-lib
+Fundamental lisp files for providing email support.
 
-** Games and Amusements (games)
-===============================
-All work and no play...
+*** mailcrypt
+Support for messaging encryption with PGP.
 
-*** cookie
-Spook and Yow (Zippy quotes).
+*** mew
+Messaging in an Emacs World.
 
-*** games
-Tetris, Sokoban, and Snake.
+*** mh-e
+Front end support for MH.
 
 *** mine
 Minehunt.
@@ -131,194 +153,156 @@
 *** misc-games
 Other amusements and diversions.
 
-** Mule Support (mule)
-======================
-MULti-lingual Enhancement.  Support for world scripts such as
-Latin, Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc.
-To use these packages your XEmacs must be compiled with Mule
-support.
-
-*** edict
-Lisp Interface to EDICT, Kanji Dictionary.
-
-*** egg-its
-Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
-XEmacs build.
-
-*** leim
-Quail.  Used for everything other than English and Japanese.
-
-*** locale
-Used for localized menubars (French and Japanese) and localized splash
-screens (Japanese).
-
-*** lookup
-Dictionary support
-
-*** mule-base
-Basic Mule support.  Must be installed prior to building with Mule.
+*** net-utils
+Miscellaneous Networking Utilities.  This is a single-file package and 
+files may be deleted at will.
 
-*** skk
-Another Japanese Language Input Method.  Can be used without a
-separate process running as a dictionary server.
+*** os-utils
+Miscellaneous single-file O/S utilities, for printing, archiving,
+compression, remote shells, etc.
 
-** Productivity Packages (oa)
-=============================
-Things to make life a little easier.
+*** pc
+PC style interface emulation.
 
-*** calc
-Emacs calculator.
+*** pcl-cvs
+CVS frontend.
 
-*** calendar
-Calendar and diary support.
+*** pcomplete
+Provides programmatic completion.
 
-*** edit-utils
-Single file lisp packages for various XEmacs goodies.  Load this and
-weed out the junk you don't want.
+*** prog-modes
+Miscellaneous single-file lisp files for various programming languages.
 
-*** forms
-Forms editing support (obsolete, use the built-in Widget instead).
+*** ps-print-nomule
+Old, but no-Mule safe ps-print.
 
-*** frame-icon
-Provide a WM icon based on major mode.
+*** psgml
+Validated HTML/SGML editing.
 
-*** hm--html-menus
-HTML editing.
+*** reftex
+Emacs support for LaTeX cross-references, citations.
 
-*** ispell
-Spell-checking with ispell.
+*** rmail
+An obsolete Emacs mailer.  If you do not already use it don't start.
 
-*** pc
-PC style interface emulation.
+*** scheme
+Front-end support for Inferior Scheme.
 
-*** psgml
-Validated HTML/SGML editing.
+*** semantic
+Semantic bovinator.
 
 *** sgml
 SGML/Linuxdoc-SGML editing.
 
+*** sh-script
+Support for editing shell scripts.
+
 *** slider
 User interface tool.
 
+*** sounds-au
+XEmacs Sun sound files.
+
+*** sounds-wav
+XEmacs Microsoft sound files.
+
 *** speedbar
 Provides a separate frame with convenient references.
 
 *** strokes
 Mouse enhancement utility.
 
+*** supercite
+An Emacs citation tool.  Useful with all Emacs Mailers and Newsreaders.
+
+*** texinfo
+XEmacs TeXinfo support.
+
 *** text-modes
 Various single file lisp packages for editing text files.
 
+*** textools
+Single-file TeX support.
+
 *** time
 Display time & date on the modeline.
 
-** Operating System Utilities (os)
-==================================
-Tools for working with the operating system.
-
-*** eshell
-Command shell implemented entirely in Emacs Lisp.
-
-*** eterm
-Terminal emulator.
+*** tm
+Emacs MIME support. Not needed for Gnus >= 5.8.0
 
-*** igrep
-Enhanced front-end for Grep.
+*** tooltalk
+Support for building with Tooltalk.
 
-*** ilisp
-Front-end for Inferior Lisp.
+*** tpu
+DEC EDIT/TPU support.
 
-*** os-utils
-Miscellaneous single-file O/S utilities, for printing, archiving,
-compression, remote shells, etc.
+*** vc
+Version Control for Free systems.
 
-*** pcomplete
-Provides programmatic completion.
+*** vc-cc
+Version Control for ClearCase.  This package will shortly be
+replaced with clearcase.el
 
-*** ps-print-nomule
-Old, but no-Mule safe ps-print.
+*** vhdl
+Support for VHDL.
 
 *** view-process
 A Unix process browsing tool.
 
-** Program Editing Support (prog)
-=================================
-XEmacs supports a multitude of programming languages.  These
-packages will help your coding.
-
-*** ada
-Ada language support.
-
-*** c-support
-Basic single-file add-ons for editing C code.
-
-*** cc-mode
-C, C++ and Java language support.
-
-*** debug
-GUD, gdb, dbx debugging support.
-
-*** ediff
-Interface over patch.
-
-*** emerge
-Another interface over patch.
-
-*** idlwave
-Editing and Shell mode for the Interactive Data Language.
-
-*** jde
-Java language and development support.
+*** viper
+VI emulation support.
 
-*** pcl-cvs
-CVS frontend.
 
-*** prog-modes
-Miscellaneous single-file lisp files for various programming languages.
-
-*** scheme
-Front-end support for Inferior Scheme.
+*** vm
+An Emacs mailer.
 
-*** semantic
-Semantic bovinator.
+*** w3
+A Web browser.
 
-*** sh-script
-Support for editing shell scripts.
+*** xemacs-base
+Fundamental XEmacs support.  Install this unless you wish a totally
+naked XEmacs.
 
-*** vc
-Version Control for Free systems.
+*** xemacs-devel
+XEmacs Lisp developer support.  This package contains utilities for
+supporting Lisp development.  It is a single-file package so it may be 
+tailored.
 
-*** vc-cc
-Version Control for ClearCase.  This package will shortly be
-replaced with clearcase.el
+*** xslt-process
+A minor mode for (X)Emacs which allows running an XSLT processor on a
+buffer.
 
-*** vhdl
-Support for VHDL.
+*** zenirc
+ZENIRC IRC Client.
 
-** Word Processing (wp)
-=======================
-Working with text.
+** Mule Support (mule)
+======================
+MULti-lingual Enhancement.  Support for world scripts such as
+Latin, Arabic, Cyrillic, Chinese, Japanese, Greek, Hebrew etc.
+To use these packages your XEmacs must be compiled with Mule
+support.
 
-*** auctex
-Basic TeX/LaTeX support.
+*** edict
+Lisp Interface to EDICT, Kanji Dictionary.
 
-*** crisp
-Crisp/Brief emulation.
+*** egg-its
+Wnn (4.2 and 6) support.  SJ3 support.  Must be installed prior to
+XEmacs build.
 
-*** edt
-DEC EDIT/EDT emulation.
+*** leim
+Quail.  Used for everything other than English and Japanese.
 
-*** reftex
-Emacs support for LaTeX cross-references, citations.
+*** locale
+Used for localized menubars (French and Japanese) and localized splash
+screens (Japanese).
 
-*** texinfo
-XEmacs TeXinfo support.
+*** lookup
+Dictionary support
 
-*** textools
-Single-file TeX support.
+*** mule-base
+Basic Mule support.  Must be installed prior to building with Mule.
 
-*** tpu
-DEC EDIT/TPU support.
+*** skk
+Another Japanese Language Input Method.  Can be used without a
+separate process running as a dictionary server.
 
-*** viper
-VI emulation support.
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info'
Index: ././info/cl.info
--- ././info/cl.info	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info	Thu May 17 23:26:51 2001
@@ -0,0 +1,106 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+Indirect:
+cl.info-1: 1164
+cl.info-2: 46305
+cl.info-3: 89086
+cl.info-4: 137809
+cl.info-5: 175805
+cl.info-6: 218388
+
+Tag Table:
+(Indirect)
+Node: Top1164
+Node: Overview2716
+Node: Usage4995
+Node: Organization5645
+Node: Installation7468
+Node: Naming Conventions8621
+Node: Program Structure10748
+Node: Argument Lists11216
+Node: Time of Evaluation20999
+Node: Function Aliases26979
+Node: Predicates27563
+Node: Type Predicates27883
+Node: Equality Predicates32925
+Node: Control Structure35701
+Node: Assignment36505
+Node: Generalized Variables37746
+Node: Basic Setf39053
+Node: Modify Macros46305
+Node: Customizing Setf53514
+Node: Variable Bindings60803
+Node: Dynamic Bindings61384
+Node: Lexical Bindings62274
+Node: Function Bindings66378
+Node: Macro Bindings68765
+Node: Conditionals71688
+Node: Blocks and Exits74771
+Node: Iteration77827
+Node: Loop Facility83300
+Node: Loop Basics84227
+Node: Loop Examples86827
+Node: For Clauses89086
+Node: Iteration Clauses100963
+Node: Accumulation Clauses102804
+Node: Other Clauses105148
+Node: Multiple Values111217
+Node: Macros113110
+Node: Declarations116328
+Node: Symbols124814
+Node: Property Lists125095
+Node: Creating Symbols127286
+Node: Numbers129364
+Node: Predicates on Numbers129844
+Node: Numerical Functions130873
+Node: Random Numbers135100
+Node: Implementation Parameters137809
+Node: Sequences141381
+Node: Sequence Basics142054
+Node: Mapping over Sequences145632
+Node: Sequence Functions151486
+Node: Searching Sequences157661
+Node: Sorting Sequences160698
+Node: Lists163246
+Node: List Functions163671
+Node: Substitution of Expressions167934
+Node: Lists as Sets169820
+Node: Association Lists173882
+Node: Hash Tables175585
+Node: Structures175805
+Node: Assertions190588
+Node: Efficiency Concerns193511
+Node: Common Lisp Compatibility199838
+Node: Old CL Compatibility202994
+Node: Porting Common Lisp207377
+Node: Function Index218388
+Node: Variable Index229537
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-1'
Index: ././info/cl.info-1
--- ././info/cl.info-1	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-1	Thu May 17 23:26:51 2001
@@ -0,0 +1,1038 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: Top,  Next: Overview,  Up: (dir)
+
+Common Lisp Extensions
+**********************
+
+This document describes a set of Emacs Lisp facilities borrowed from
+Common Lisp.  All the facilities are described here in detail; for more
+discussion and examples, Guy L. Steele's `Common Lisp, the Language',
+second edition, is the definitive book on Common Lisp.  While this
+document does not assume any prior knowledge of Common Lisp, it does
+assume a basic familiarity with Emacs Lisp.
+
+* Menu:
+
+* Overview::             Installation, usage, etc.
+* Program Structure::    Arglists, `eval-when', `defalias'
+* Predicates::           `typep', `eql', and `equalp'
+* Control Structure::    `setf', `when', `do', `loop', etc.
+* Macros::               Destructuring, `define-compiler-macro'
+* Declarations::         `proclaim', `declare', etc.
+* Symbols::              Property lists, `gensym'
+* Numbers::              Predicates, functions, random numbers
+* Sequences::            Mapping, functions, searching, sorting
+* Lists::                `cadr', `sublis', `member*', `assoc*', etc.
+* Hash Tables::          `make-hash-table', `gethash', etc.
+* Structures::           `defstruct'
+* Assertions::           `check-type', `assert', `ignore-errors'.
+
+* Efficiency Concerns::         Hints and techniques
+* Common Lisp Compatibility::   All known differences with Steele
+* Old CL Compatibility::        All known differences with old cl.el
+* Porting Common Lisp::         Hints for porting Common Lisp code
+
+* Function Index::
+* Variable Index::
+
+
+File: cl.info,  Node: Overview,  Next: Program Structure,  Prev: Top,  Up: Top
+
+Overview
+********
+
+Common Lisp is a huge language, and Common Lisp systems tend to be
+massive and extremely complex.  Emacs Lisp, by contrast, is rather
+minimalist in the choice of Lisp features it offers the programmer.  As
+Emacs Lisp programmers have grown in number, and the applications they
+write have grown more ambitious, it has become clear that Emacs Lisp
+could benefit from many of the conveniences of Common Lisp.
+
+   The "CL" package adds a number of Common Lisp functions and control
+structures to Emacs Lisp.  While not a 100% complete implementation of
+Common Lisp, "CL" adds enough functionality to make Emacs Lisp
+programming significantly more convenient.
+
+   Some Common Lisp features have been omitted from this package for
+various reasons:
+
+   * Some features are too complex or bulky relative to their benefit
+     to Emacs Lisp programmers.  CLOS and Common Lisp streams are fine
+     examples of this group.
+
+   * Other features cannot be implemented without modification to the
+     Emacs Lisp interpreter itself, such as multiple return values,
+     lexical scoping, case-insensitive symbols, and complex numbers.
+     The "CL" package generally makes no attempt to emulate these
+     features.
+
+   * Some features conflict with existing things in Emacs Lisp.  For
+     example, Emacs' `assoc' function is incompatible with the Common
+     Lisp `assoc'.  In such cases, this package usually adds the suffix
+     `*' to the function name of the Common Lisp version of the
+     function (e.g., `assoc*').
+
+   The package described here was written by Dave Gillespie,
+`daveg@synaptics.com'.  It is a total rewrite of the original 1986
+`cl.el' package by Cesar Quiroz.  Most features of the Quiroz package
+have been retained; any incompatibilities are noted in the descriptions
+below.  Care has been taken in this version to ensure that each
+function is defined efficiently, concisely, and with minimal impact on
+the rest of the Emacs environment.
+
+* Menu:
+
+* Usage::                How to use the CL package
+* Organization::         The package's five component files
+* Installation::         Compiling and installing CL
+* Naming Conventions::   Notes on CL function names
+
+
+File: cl.info,  Node: Usage,  Next: Organization,  Prev: Overview,  Up: Overview
+
+Usage
+=====
+
+Lisp code that uses features from the "CL" package should include at
+the beginning:
+
+     (require 'cl)
+
+If you want to ensure that the new (Gillespie) version of "CL" is the
+one that is present, add an additional `(require 'cl-19)' call:
+
+     (require 'cl)
+     (require 'cl-19)
+
+The second call will fail (with "`cl-19.el' not found") if the old
+`cl.el' package was in use.
+
+   It is safe to arrange to load "CL" at all times, e.g., in your
+`.emacs' file.  But it's a good idea, for portability, to `(require
+'cl)' in your code even if you do this.
+
+
+File: cl.info,  Node: Organization,  Next: Installation,  Prev: Usage,  Up: Overview
+
+Organization
+============
+
+The Common Lisp package is organized into four files:
+
+`cl.el'
+     This is the "main" file, which contains basic functions and
+     information about the package.  This file is relatively
+     compact--about 700 lines.
+
+`cl-extra.el'
+     This file contains the larger, more complex or unusual functions.
+     It is kept separate so that packages which only want to use Common
+     Lisp fundamentals like the `cadr' function won't need to pay the
+     overhead of loading the more advanced functions.
+
+`cl-seq.el'
+     This file contains most of the advanced functions for operating on
+     sequences or lists, such as `delete-if' and `assoc*'.
+
+`cl-macs.el'
+     This file contains the features of the packages which are macros
+     instead of functions.  Macros expand when the caller is compiled,
+     not when it is run, so the macros generally only need to be
+     present when the byte-compiler is running (or when the macros are
+     used in uncompiled code such as a `.emacs' file).  Most of the
+     macros of this package are isolated in `cl-macs.el' so that they
+     won't take up memory unless you are compiling.
+
+   The file `cl.el' includes all necessary `autoload' commands for the
+functions and macros in the other three files.  All you have to do is
+`(require 'cl)', and `cl.el' will take care of pulling in the other
+files when they are needed.
+
+   There is another file, `cl-compat.el', which defines some routines
+from the older `cl.el' package that are no longer present in the new
+package.  This includes internal routines like `setelt' and
+`zip-lists', deprecated features like `defkeyword', and an emulation of
+the old-style multiple-values feature.  *Note Old CL Compatibility::.
+
+
+File: cl.info,  Node: Installation,  Next: Naming Conventions,  Prev: Organization,  Up: Overview
+
+Installation
+============
+
+Installation of the "CL" package is simple:  Just put the byte-compiled
+files `cl.elc', `cl-extra.elc', `cl-seq.elc', `cl-macs.elc', and
+`cl-compat.elc' into a directory on your `load-path'.
+
+   There are no special requirements to compile this package: The files
+do not have to be loaded before they are compiled, nor do they need to
+be compiled in any particular order.
+
+   You may choose to put the files into your main `lisp/' directory,
+replacing the original `cl.el' file there.  Or, you could put them into
+a directory that comes before `lisp/' on your `load-path' so that the
+old `cl.el' is effectively hidden.
+
+   Also, format the `cl.texinfo' file and put the resulting Info files
+in the `info/' directory or another suitable place.
+
+   You may instead wish to leave this package's components all in their
+own directory, and then add this directory to your `load-path' and
+(Emacs 19 only) `Info-directory-list'.  Add the directory to the front
+of the list so the old "CL" package and its documentation are hidden.
+
+
+File: cl.info,  Node: Naming Conventions,  Prev: Installation,  Up: Overview
+
+Naming Conventions
+==================
+
+Except where noted, all functions defined by this package have the same
+names and calling conventions as their Common Lisp counterparts.
+
+   Following is a complete list of functions whose names were changed
+from Common Lisp, usually to avoid conflicts with Emacs.  In each case,
+a `*' has been appended to the Common Lisp name to obtain the Emacs
+name:
+
+     defun*        defsubst*     defmacro*     function*
+     member*       assoc*        rassoc*       remove*
+     delete*       mapcar*       sort*         floor*
+     ceiling*      truncate*     round*        mod*
+     rem*          random*
+
+   Internal function and variable names in the package are prefixed by
+`cl-'.  Here is a complete list of functions _not_ prefixed by `cl-'
+which were not taken from Common Lisp:
+
+     member        delete        remove        remq
+     rassoc        floatp-safe   lexical-let   lexical-let*
+     callf         callf2        letf          letf*
+     defsubst*     defalias      add-hook      eval-when-compile
+
+(Most of these are Emacs 19 features provided to Emacs 18 users, or
+introduced, like `remq', for reasons of symmetry with similar features.)
+
+   The following simple functions and macros are defined in `cl.el';
+they do not cause other components like `cl-extra' to be loaded.
+
+     eql           floatp-safe   abs           endp
+     evenp         oddp          plusp         minusp
+     last          butlast       nbutlast      caar .. cddddr
+     list*         ldiff         rest          first .. tenth
+     member [1]    copy-list     subst         mapcar* [2]
+     adjoin [3]    acons         pairlis       when
+     unless        pop [4]       push [4]      pushnew [3,4]
+     incf [4]      decf [4]      proclaim      declaim
+     add-hook
+
+[1] This is the Emacs 19-compatible function, not `member*'.
+
+[2] Only for one sequence argument or two list arguments.
+
+[3] Only if `:test' is `eq', `equal', or unspecified, and `:key' is not
+used.
+
+[4] Only when PLACE is a plain variable name.
+
+
+File: cl.info,  Node: Program Structure,  Next: Predicates,  Prev: Overview,  Up: Top
+
+Program Structure
+*****************
+
+This section describes features of the "CL" package which have to do
+with programs as a whole: advanced argument lists for functions, and
+the `eval-when' construct.
+
+* Menu:
+
+* Argument Lists::       `&key', `&aux', `defun*', `defmacro*'.
+* Time of Evaluation::   The `eval-when' construct.
+* Function Aliases::     The `defalias' function.
+
+
+File: cl.info,  Node: Argument Lists,  Next: Time of Evaluation,  Prev: Program Structure,  Up: Program Structure
+
+Argument Lists
+==============
+
+Emacs Lisp's notation for argument lists of functions is a subset of
+the Common Lisp notation.  As well as the familiar `&optional' and
+`&rest' markers, Common Lisp allows you to specify default values for
+optional arguments, and it provides the additional markers `&key' and
+`&aux'.
+
+   Since argument parsing is built-in to Emacs, there is no way for
+this package to implement Common Lisp argument lists seamlessly.
+Instead, this package defines alternates for several Lisp forms which
+you must use if you need Common Lisp argument lists.
+
+ - Special Form: defun* name arglist body...
+     This form is identical to the regular `defun' form, except that
+     ARGLIST is allowed to be a full Common Lisp argument list.  Also,
+     the function body is enclosed in an implicit block called NAME;
+     *note Blocks and Exits::.
+
+ - Special Form: defsubst* name arglist body...
+     This is just like `defun*', except that the function that is
+     defined is automatically proclaimed `inline', i.e., calls to it
+     may be expanded into in-line code by the byte compiler.  This is
+     analogous to the `defsubst' form in Emacs 19; `defsubst*' uses a
+     different method (compiler macros) which works in all version of
+     Emacs, and also generates somewhat more efficient inline
+     expansions.  In particular, `defsubst*' arranges for the
+     processing of keyword arguments, default values, etc., to be done
+     at compile-time whenever possible.
+
+ - Special Form: defmacro* name arglist body...
+     This is identical to the regular `defmacro' form, except that
+     ARGLIST is allowed to be a full Common Lisp argument list.  The
+     `&environment' keyword is supported as described in Steele.  The
+     `&whole' keyword is supported only within destructured lists (see
+     below); top-level `&whole' cannot be implemented with the current
+     Emacs Lisp interpreter.  The macro expander body is enclosed in an
+     implicit block called NAME.
+
+ - Special Form: function* symbol-or-lambda
+     This is identical to the regular `function' form, except that if
+     the argument is a `lambda' form then that form may use a full
+     Common Lisp argument list.
+
+   Also, all forms (such as `defsetf' and `flet') defined in this
+package that include ARGLISTs in their syntax allow full Common Lisp
+argument lists.
+
+   Note that it is _not_ necessary to use `defun*' in order to have
+access to most "CL" features in your function.  These features are
+always present; `defun*''s only difference from `defun' is its more
+flexible argument lists and its implicit block.
+
+   The full form of a Common Lisp argument list is
+
+     (VAR...
+      &optional (VAR INITFORM SVAR)...
+      &rest VAR
+      &key ((KEYWORD VAR) INITFORM SVAR)...
+      &aux (VAR INITFORM)...)
+
+   Each of the five argument list sections is optional.  The SVAR,
+INITFORM, and KEYWORD parts are optional; if they are omitted, then
+`(VAR)' may be written simply `VAR'.
+
+   The first section consists of zero or more "required" arguments.
+These arguments must always be specified in a call to the function;
+there is no difference between Emacs Lisp and Common Lisp as far as
+required arguments are concerned.
+
+   The second section consists of "optional" arguments.  These
+arguments may be specified in the function call; if they are not,
+INITFORM specifies the default value used for the argument.  (No
+INITFORM means to use `nil' as the default.)  The INITFORM is evaluated
+with the bindings for the preceding arguments already established; `(a
+&optional (b (1+ a)))' matches one or two arguments, with the second
+argument defaulting to one plus the first argument.  If the SVAR is
+specified, it is an auxiliary variable which is bound to `t' if the
+optional argument was specified, or to `nil' if the argument was
+omitted.  If you don't use an SVAR, then there will be no way for your
+function to tell whether it was called with no argument, or with the
+default value passed explicitly as an argument.
+
+   The third section consists of a single "rest" argument.  If more
+arguments were passed to the function than are accounted for by the
+required and optional arguments, those extra arguments are collected
+into a list and bound to the "rest" argument variable.  Common Lisp's
+`&rest' is equivalent to that of Emacs Lisp.  Common Lisp accepts
+`&body' as a synonym for `&rest' in macro contexts; this package
+accepts it all the time.
+
+   The fourth section consists of "keyword" arguments.  These are
+optional arguments which are specified by name rather than positionally
+in the argument list.  For example,
+
+     (defun* foo (a &optional b &key c d (e 17)))
+
+defines a function which may be called with one, two, or more
+arguments.  The first two arguments are bound to `a' and `b' in the
+usual way.  The remaining arguments must be pairs of the form `:c',
+`:d', or `:e' followed by the value to be bound to the corresponding
+argument variable.  (Symbols whose names begin with a colon are called
+"keywords", and they are self-quoting in the same way as `nil' and `t'.)
+
+   For example, the call `(foo 1 2 :d 3 :c 4)' sets the five arguments
+to 1, 2, 4, 3, and 17, respectively.  If the same keyword appears more
+than once in the function call, the first occurrence takes precedence
+over the later ones.  Note that it is not possible to specify keyword
+arguments without specifying the optional argument `b' as well, since
+`(foo 1 :c 2)' would bind `b' to the keyword `:c', then signal an error
+because `2' is not a valid keyword.
+
+   If a KEYWORD symbol is explicitly specified in the argument list as
+shown in the above diagram, then that keyword will be used instead of
+just the variable name prefixed with a colon.  You can specify a
+KEYWORD symbol which does not begin with a colon at all, but such
+symbols will not be self-quoting; you will have to quote them
+explicitly with an apostrophe in the function call.
+
+   Ordinarily it is an error to pass an unrecognized keyword to a
+function, e.g., `(foo 1 2 :c 3 :goober 4)'.  You can ask Lisp to ignore
+unrecognized keywords, either by adding the marker `&allow-other-keys'
+after the keyword section of the argument list, or by specifying an
+`:allow-other-keys' argument in the call whose value is non-`nil'.  If
+the function uses both `&rest' and `&key' at the same time, the "rest"
+argument is bound to the keyword list as it appears in the call.  For
+example:
+
+     (defun* find-thing (thing &rest rest &key need &allow-other-keys)
+       (or (apply 'member* thing thing-list :allow-other-keys t rest)
+           (if need (error "Thing not found"))))
+
+This function takes a `:need' keyword argument, but also accepts other
+keyword arguments which are passed on to the `member*' function.
+`allow-other-keys' is used to keep both `find-thing' and `member*' from
+complaining about each others' keywords in the arguments.
+
+   As a (significant) performance optimization, this package implements
+the scan for keyword arguments by calling `memq' to search for keywords
+in a "rest" argument.  Technically speaking, this is incorrect, since
+`memq' looks at the odd-numbered values as well as the even-numbered
+keywords.  The net effect is that if you happen to pass a keyword symbol
+as the _value_ of another keyword argument, where that keyword symbol
+happens to equal the name of a valid keyword argument of the same
+function, then the keyword parser will become confused.  This minor bug
+can only affect you if you use keyword symbols as general-purpose data
+in your program; this practice is strongly discouraged in Emacs Lisp.
+
+   The fifth section of the argument list consists of "auxiliary
+variables".  These are not really arguments at all, but simply
+variables which are bound to `nil' or to the specified INITFORMS during
+execution of the function.  There is no difference between the
+following two functions, except for a matter of stylistic taste:
+
+     (defun* foo (a b &aux (c (+ a b)) d)
+       BODY)
+     
+     (defun* foo (a b)
+       (let ((c (+ a b)) d)
+         BODY))
+
+   Argument lists support "destructuring".  In Common Lisp,
+destructuring is only allowed with `defmacro'; this package allows it
+with `defun*' and other argument lists as well.  In destructuring, any
+argument variable (VAR in the above diagram) can be replaced by a list
+of variables, or more generally, a recursive argument list.  The
+corresponding argument value must be a list whose elements match this
+recursive argument list.  For example:
+
+     (defmacro* dolist ((var listform &optional resultform)
+                        &rest body)
+       ...)
+
+   This says that the first argument of `dolist' must be a list of two
+or three items; if there are other arguments as well as this list, they
+are stored in `body'.  All features allowed in regular argument lists
+are allowed in these recursive argument lists.  In addition, the clause
+`&whole VAR' is allowed at the front of a recursive argument list.  It
+binds VAR to the whole list being matched; thus `(&whole all a b)'
+matches a list of two things, with `a' bound to the first thing, `b'
+bound to the second thing, and `all' bound to the list itself.  (Common
+Lisp allows `&whole' in top-level `defmacro' argument lists as well,
+but Emacs Lisp does not support this usage.)
+
+   One last feature of destructuring is that the argument list may be
+dotted, so that the argument list `(a b . c)' is functionally
+equivalent to `(a b &rest c)'.
+
+   If the optimization quality `safety' is set to 0 (*note
+Declarations::), error checking for wrong number of arguments and
+invalid keyword arguments is disabled.  By default, argument lists are
+rigorously checked.
+
+
+File: cl.info,  Node: Time of Evaluation,  Next: Function Aliases,  Prev: Argument Lists,  Up: Program Structure
+
+Time of Evaluation
+==================
+
+Normally, the byte-compiler does not actually execute the forms in a
+file it compiles.  For example, if a file contains `(setq foo t)', the
+act of compiling it will not actually set `foo' to `t'.  This is true
+even if the `setq' was a top-level form (i.e., not enclosed in a
+`defun' or other form).  Sometimes, though, you would like to have
+certain top-level forms evaluated at compile-time.  For example, the
+compiler effectively evaluates `defmacro' forms at compile-time so that
+later parts of the file can refer to the macros that are defined.
+
+ - Special Form: eval-when (situations...) forms...
+     This form controls when the body FORMS are evaluated.  The
+     SITUATIONS list may contain any set of the symbols `compile',
+     `load', and `eval' (or their long-winded ANSI equivalents,
+     `:compile-toplevel', `:load-toplevel', and `:execute').
+
+     The `eval-when' form is handled differently depending on whether
+     or not it is being compiled as a top-level form.  Specifically, it
+     gets special treatment if it is being compiled by a command such
+     as `byte-compile-file' which compiles files or buffers of code,
+     and it appears either literally at the top level of the file or
+     inside a top-level `progn'.
+
+     For compiled top-level `eval-when's, the body FORMS are executed
+     at compile-time if `compile' is in the SITUATIONS list, and the
+     FORMS are written out to the file (to be executed at load-time) if
+     `load' is in the SITUATIONS list.
+
+     For non-compiled-top-level forms, only the `eval' situation is
+     relevant.  (This includes forms executed by the interpreter, forms
+     compiled with `byte-compile' rather than `byte-compile-file', and
+     non-top-level forms.)  The `eval-when' acts like a `progn' if
+     `eval' is specified, and like `nil' (ignoring the body FORMS) if
+     not.
+
+     The rules become more subtle when `eval-when's are nested; consult
+     Steele (second edition) for the gruesome details (and some
+     gruesome examples).
+
+     Some simple examples:
+
+          ;; Top-level forms in foo.el:
+          (eval-when (compile)           (setq foo1 'bar))
+          (eval-when (load)              (setq foo2 'bar))
+          (eval-when (compile load)      (setq foo3 'bar))
+          (eval-when (eval)              (setq foo4 'bar))
+          (eval-when (eval compile)      (setq foo5 'bar))
+          (eval-when (eval load)         (setq foo6 'bar))
+          (eval-when (eval compile load) (setq foo7 'bar))
+
+     When `foo.el' is compiled, these variables will be set during the
+     compilation itself:
+
+          foo1  foo3  foo5  foo7      ; `compile'
+
+     When `foo.elc' is loaded, these variables will be set:
+
+          foo2  foo3  foo6  foo7      ; `load'
+
+     And if `foo.el' is loaded uncompiled, these variables will be set:
+
+          foo4  foo5  foo6  foo7      ; `eval'
+
+     If these seven `eval-when's had been, say, inside a `defun', then
+     the first three would have been equivalent to `nil' and the last
+     four would have been equivalent to the corresponding `setq's.
+
+     Note that `(eval-when (load eval) ...)' is equivalent to `(progn
+     ...)' in all contexts.  The compiler treats certain top-level
+     forms, like `defmacro' (sort-of) and `require', as if they were
+     wrapped in `(eval-when (compile load eval) ...)'.
+
+   Emacs 19 includes two special forms related to `eval-when'.  One of
+these, `eval-when-compile', is not quite equivalent to any `eval-when'
+construct and is described below.  This package defines a version of
+`eval-when-compile' for the benefit of Emacs 18 users.
+
+   The other form, `(eval-and-compile ...)', is exactly equivalent to
+`(eval-when (compile load eval) ...)' and so is not itself defined by
+this package.
+
+ - Special Form: eval-when-compile forms...
+     The FORMS are evaluated at compile-time; at execution time, this
+     form acts like a quoted constant of the resulting value.  Used at
+     top-level, `eval-when-compile' is just like `eval-when (compile
+     eval)'.  In other contexts, `eval-when-compile' allows code to be
+     evaluated once at compile-time for efficiency or other reasons.
+
+     This form is similar to the `#.' syntax of true Common Lisp.
+
+ - Special Form: load-time-value form
+     The FORM is evaluated at load-time; at execution time, this form
+     acts like a quoted constant of the resulting value.
+
+     Early Common Lisp had a `#,' syntax that was similar to this, but
+     ANSI Common Lisp replaced it with `load-time-value' and gave it
+     more well-defined semantics.
+
+     In a compiled file, `load-time-value' arranges for FORM to be
+     evaluated when the `.elc' file is loaded and then used as if it
+     were a quoted constant.  In code compiled by `byte-compile' rather
+     than `byte-compile-file', the effect is identical to
+     `eval-when-compile'.  In uncompiled code, both `eval-when-compile'
+     and `load-time-value' act exactly like `progn'.
+
+          (defun report ()
+            (insert "This function was executed on: "
+                    (current-time-string)
+                    ", compiled on: "
+                    (eval-when-compile (current-time-string))
+                    ;; or '#.(current-time-string) in real Common Lisp
+                    ", and loaded on: "
+                    (load-time-value (current-time-string))))
+
+     Byte-compiled, the above defun will result in the following code
+     (or its compiled equivalent, of course) in the `.elc' file:
+
+          (setq --temp-- (current-time-string))
+          (defun report ()
+            (insert "This function was executed on: "
+                    (current-time-string)
+                    ", compiled on: "
+                    '"Wed Jun 23 18:33:43 1993"
+                    ", and loaded on: "
+                    --temp--))
+
+
+File: cl.info,  Node: Function Aliases,  Prev: Time of Evaluation,  Up: Program Structure
+
+Function Aliases
+================
+
+This section describes a feature from GNU Emacs 19 which this package
+makes available in other versions of Emacs.
+
+ - Function: defalias symbol function
+     This function sets SYMBOL's function cell to FUNCTION.  It is
+     equivalent to `fset', except that in GNU Emacs 19 it also records
+     the setting in `load-history' so that it can be undone by a later
+     `unload-feature'.
+
+     In other versions of Emacs, `defalias' is a synonym for `fset'.
+
+
+File: cl.info,  Node: Predicates,  Next: Control Structure,  Prev: Program Structure,  Up: Top
+
+Predicates
+**********
+
+This section describes functions for testing whether various facts are
+true or false.
+
+* Menu:
+
+* Type Predicates::      `typep', `deftype', and `coerce'
+* Equality Predicates::  `eql' and `equalp'
+
+
+File: cl.info,  Node: Type Predicates,  Next: Equality Predicates,  Prev: Predicates,  Up: Predicates
+
+Type Predicates
+===============
+
+The "CL" package defines a version of the Common Lisp `typep' predicate.
+
+ - Function: typep object type
+     Check if OBJECT is of type TYPE, where TYPE is a (quoted) type
+     name of the sort used by Common Lisp.  For example, `(typep foo
+     'integer)' is equivalent to `(integerp foo)'.
+
+   The TYPE argument to the above function is either a symbol or a list
+beginning with a symbol.
+
+   * If the type name is a symbol, Emacs appends `-p' to the symbol
+     name to form the name of a predicate function for testing the
+     type.  (Built-in predicates whose names end in `p' rather than
+     `-p' are used when appropriate.)
+
+   * The type symbol `t' stands for the union of all types.  `(typep
+     OBJECT t)' is always true.  Likewise, the type symbol `nil' stands
+     for nothing at all, and `(typep OBJECT nil)' is always false.
+
+   * The type symbol `null' represents the symbol `nil'.  Thus `(typep
+     OBJECT 'null)' is equivalent to `(null OBJECT)'.
+
+   * The type symbol `real' is a synonym for `number', and `fixnum' is
+     a synonym for `integer'.
+
+   * The type symbols `character' and `string-char' match characters.
+     In Emacs-19 and XEmacs-19, characters are the same thing as
+     integers in the range 0-255.  In XEmacs-20, where characters are a
+     first-class data type, this checks for actual characters, and
+     `(typep 8BIT-INTEGER 'character)' will return `nil'.
+
+   * The type symbol `float' uses the `floatp-safe' predicate defined
+     by this package rather than `floatp', so it will work correctly
+     even in Emacs versions without floating-point support.
+
+   * The type list `(integer LOW HIGH)' represents all integers between
+     LOW and HIGH, inclusive.  Either bound may be a list of a single
+     integer to specify an exclusive limit, or a `*' to specify no
+     limit.  The type `(integer * *)' is thus equivalent to `integer'.
+
+   * Likewise, lists beginning with `float', `real', or `number'
+     represent numbers of that type falling in a particular range.
+
+   * Lists beginning with `and', `or', and `not' form combinations of
+     types.  For example, `(or integer (float 0 *))' represents all
+     objects that are integers or non-negative floats.
+
+   * Lists beginning with `member' or `member*' represent objects `eql'
+     to any of the following values.  For example, `(member 1 2 3 4)'
+     is equivalent to `(integer 1 4)', and `(member nil)' is equivalent
+     to `null'.
+
+   * Lists of the form `(satisfies PREDICATE)' represent all objects
+     for which PREDICATE returns true when called with that object as
+     an argument.
+
+   The following function and macro (not technically predicates) are
+related to `typep'.
+
+ - Function: coerce object type
+     This function attempts to convert OBJECT to the specified TYPE.
+     If OBJECT is already of that type as determined by `typep', it is
+     simply returned.  Otherwise, certain types of conversions will be
+     made:  If TYPE is any sequence type (`string', `list', etc.) then
+     OBJECT will be converted to that type if possible.  If TYPE is
+     `character', then strings of length one and symbols with
+     one-character names can be coerced.  If TYPE is `float', then
+     integers can be coerced in versions of Emacs that support floats.
+     In all other circumstances, `coerce' signals an error.
+
+ - Special Form: deftype name arglist forms...
+     This macro defines a new type called NAME.  It is similar to
+     `defmacro' in many ways; when NAME is encountered as a type name,
+     the body FORMS are evaluated and should return a type specifier
+     that is equivalent to the type.  The ARGLIST is a Common Lisp
+     argument list of the sort accepted by `defmacro*'.  The type
+     specifier `(NAME ARGS...)' is expanded by calling the expander
+     with those arguments; the type symbol `NAME' is expanded by
+     calling the expander with no arguments.  The ARGLIST is processed
+     the same as for `defmacro*' except that optional arguments without
+     explicit defaults use `*' instead of `nil' as the "default"
+     default.  Some examples:
+
+          (deftype null () '(satisfies null))    ; predefined
+          (deftype list () '(or null cons))      ; predefined
+          (deftype unsigned-byte (&optional bits)
+            (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits)))))
+          (unsigned-byte 8)  ==  (integer 0 255)
+          (unsigned-byte)  ==  (integer 0 *)
+          unsigned-byte  ==  (integer 0 *)
+
+     The last example shows how the Common Lisp `unsigned-byte' type
+     specifier could be implemented if desired; this package does not
+     implement `unsigned-byte' by default.
+
+   The `typecase' and `check-type' macros also use type names.  *Note
+Conditionals::.  *Note Assertions::.  The `map', `concatenate', and
+`merge' functions take type-name arguments to specify the type of
+sequence to return.  *Note Sequences::.
+
+
+File: cl.info,  Node: Equality Predicates,  Prev: Type Predicates,  Up: Predicates
+
+Equality Predicates
+===================
+
+This package defines two Common Lisp predicates, `eql' and `equalp'.
+
+ - Function: eql a b
+     This function is almost the same as `eq', except that if A and B
+     are numbers of the same type, it compares them for numeric
+     equality (as if by `equal' instead of `eq').  This makes a
+     difference only for versions of Emacs that are compiled with
+     floating-point support, such as Emacs 19.  Emacs floats are
+     allocated objects just like cons cells, which means that `(eq 3.0
+     3.0)' will not necessarily be true--if the two `3.0's were
+     allocated separately, the pointers will be different even though
+     the numbers are the same.  But `(eql 3.0 3.0)' will always be true.
+
+     The types of the arguments must match, so `(eql 3 3.0)' is still
+     false.
+
+     Note that Emacs integers are "direct" rather than allocated, which
+     basically means `(eq 3 3)' will always be true.  Thus `eq' and
+     `eql' behave differently only if floating-point numbers are
+     involved, and are indistinguishable on Emacs versions that don't
+     support floats.
+
+     There is a slight inconsistency with Common Lisp in the treatment
+     of positive and negative zeros.  Some machines, notably those with
+     IEEE standard arithmetic, represent `+0' and `-0' as distinct
+     values.  Normally this doesn't matter because the standard
+     specifies that `(= 0.0 -0.0)' should always be true, and this is
+     indeed what Emacs Lisp and Common Lisp do.  But the Common Lisp
+     standard states that `(eql 0.0 -0.0)' and `(equal 0.0 -0.0)' should
+     be false on IEEE-like machines; Emacs Lisp does not do this, and in
+     fact the only known way to distinguish between the two zeros in
+     Emacs Lisp is to `format' them and check for a minus sign.
+
+ - Function: equalp a b
+     This function is a more flexible version of `equal'.  In
+     particular, it compares strings and characters case-insensitively,
+     and it compares numbers without regard to type (so that `(equalp 3
+     3.0)' is true).  Vectors and conses are compared recursively.  All
+     other objects are compared as if by `equal'.
+
+     This function differs from Common Lisp `equalp' in several
+     respects.  In keeping with the idea that strings are less
+     vector-like in Emacs Lisp, this package's `equalp' also will not
+     compare strings against vectors of integers.
+
+   Also note that the Common Lisp functions `member' and `assoc' use
+`eql' to compare elements, whereas Emacs Lisp follows the MacLisp
+tradition and uses `equal' for these two functions.  In Emacs, use
+`member*' and `assoc*' to get functions which use `eql' for comparisons.
+
+
+File: cl.info,  Node: Control Structure,  Next: Macros,  Prev: Predicates,  Up: Top
+
+Control Structure
+*****************
+
+The features described in the following sections implement various
+advanced control structures, including the powerful `setf' facility and
+a number of looping and conditional constructs.
+
+* Menu:
+
+* Assignment::             The `psetq' form
+* Generalized Variables::  `setf', `incf', `push', etc.
+* Variable Bindings::      `progv', `lexical-let', `flet', `macrolet'
+* Conditionals::           `when', `unless', `case', `typecase'
+* Blocks and Exits::       `block', `return', `return-from'
+* Iteration::              `do', `dotimes', `dolist', `do-symbols'
+* Loop Facility::          The Common Lisp `loop' macro
+* Multiple Values::        `values', `multiple-value-bind', etc.
+
+
+File: cl.info,  Node: Assignment,  Next: Generalized Variables,  Prev: Control Structure,  Up: Control Structure
+
+Assignment
+==========
+
+The `psetq' form is just like `setq', except that multiple assignments
+are done in parallel rather than sequentially.
+
+ - Special Form: psetq [symbol form]...
+     This special form (actually a macro) is used to assign to several
+     variables simultaneously.  Given only one SYMBOL and FORM, it has
+     the same effect as `setq'.  Given several SYMBOL and FORM pairs,
+     it evaluates all the FORMs in advance and then stores the
+     corresponding variables afterwards.
+
+          (setq x 2 y 3)
+          (setq x (+ x y)  y (* x y))
+          x
+               => 5
+          y                     ; `y' was computed after `x' was set.
+               => 15
+          (setq x 2 y 3)
+          (psetq x (+ x y)  y (* x y))
+          x
+               => 5
+          y                     ; `y' was computed before `x' was set.
+               => 6
+
+     The simplest use of `psetq' is `(psetq x y y x)', which exchanges
+     the values of two variables.  (The `rotatef' form provides an even
+     more convenient way to swap two variables; *note Modify Macros::.)
+
+     `psetq' always returns `nil'.
+
+
+File: cl.info,  Node: Generalized Variables,  Next: Variable Bindings,  Prev: Assignment,  Up: Control Structure
+
+Generalized Variables
+=====================
+
+A "generalized variable" or "place form" is one of the many places in
+Lisp memory where values can be stored.  The simplest place form is a
+regular Lisp variable.  But the cars and cdrs of lists, elements of
+arrays, properties of symbols, and many other locations are also places
+where Lisp values are stored.
+
+   The `setf' form is like `setq', except that it accepts arbitrary
+place forms on the left side rather than just symbols.  For example,
+`(setf (car a) b)' sets the car of `a' to `b', doing the same operation
+as `(setcar a b)' but without having to remember two separate functions
+for setting and accessing every type of place.
+
+   Generalized variables are analogous to "lvalues" in the C language,
+where `x = a[i]' gets an element from an array and `a[i] = x' stores an
+element using the same notation.  Just as certain forms like `a[i]' can
+be lvalues in C, there is a set of forms that can be generalized
+variables in Lisp.
+
+* Menu:
+
+* Basic Setf::         `setf' and place forms
+* Modify Macros::      `incf', `push', `rotatef', `letf', `callf', etc.
+* Customizing Setf::   `define-modify-macro', `defsetf', `define-setf-method'
+
+
+File: cl.info,  Node: Basic Setf,  Next: Modify Macros,  Prev: Generalized Variables,  Up: Generalized Variables
+
+Basic Setf
+----------
+
+The `setf' macro is the most basic way to operate on generalized
+variables.
+
+ - Special Form: setf [place form]...
+     This macro evaluates FORM and stores it in PLACE, which must be a
+     valid generalized variable form.  If there are several PLACE and
+     FORM pairs, the assignments are done sequentially just as with
+     `setq'.  `setf' returns the value of the last FORM.
+
+     The following Lisp forms will work as generalized variables, and
+     so may legally appear in the PLACE argument of `setf':
+
+        * A symbol naming a variable.  In other words, `(setf x y)' is
+          exactly equivalent to `(setq x y)', and `setq' itself is
+          strictly speaking redundant now that `setf' exists.  Many
+          programmers continue to prefer `setq' for setting simple
+          variables, though, purely for stylistic or historical reasons.
+          The form `(setf x y)' actually expands to `(setq x y)', so
+          there is no performance penalty for using it in compiled code.
+
+        * A call to any of the following Lisp functions:
+
+               car                 cdr                 caar .. cddddr
+               nth                 rest                first .. tenth
+               aref                elt                 nthcdr
+               symbol-function     symbol-value        symbol-plist
+               get                 getf                gethash
+               subseq
+
+          Note that for `nthcdr' and `getf', the list argument of the
+          function must itself be a valid PLACE form.  For example,
+          `(setf (nthcdr 0 foo) 7)' will set `foo' itself to 7.  Note
+          that `push' and `pop' on an `nthcdr' place can be used to
+          insert or delete at any position in a list.  The use of
+          `nthcdr' as a PLACE form is an extension to standard Common
+          Lisp.
+
+        * The following Emacs-specific functions are also `setf'-able.
+          (Some of these are defined only in Emacs 19 or only in
+          XEmacs.)
+
+               buffer-file-name                  marker-position
+               buffer-modified-p                 match-data
+               buffer-name                       mouse-position
+               buffer-string                     overlay-end
+               buffer-substring                  overlay-get
+               current-buffer                    overlay-start
+               current-case-table                point
+               current-column                    point-marker
+               current-global-map                point-max
+               current-input-mode                point-min
+               current-local-map                 process-buffer
+               current-window-configuration      process-filter
+               default-file-modes                process-sentinel
+               default-value                     read-mouse-position
+               documentation-property            screen-height
+               extent-data                       screen-menubar
+               extent-end-position               screen-width
+               extent-start-position             selected-window
+               face-background                   selected-screen
+               face-background-pixmap            selected-frame
+               face-font                         standard-case-table
+               face-foreground                   syntax-table
+               face-underline-p                  window-buffer
+               file-modes                        window-dedicated-p
+               frame-height                      window-display-table
+               frame-parameters                  window-height
+               frame-visible-p                   window-hscroll
+               frame-width                       window-point
+               get-register                      window-start
+               getenv                            window-width
+               global-key-binding                x-get-cut-buffer
+               keymap-parent                     x-get-cutbuffer
+               local-key-binding                 x-get-secondary-selection
+               mark                              x-get-selection
+               mark-marker
+
+          Most of these have directly corresponding "set" functions,
+          like `use-local-map' for `current-local-map', or `goto-char'
+          for `point'.  A few, like `point-min', expand to longer
+          sequences of code when they are `setf''d (`(narrow-to-region
+          x (point-max))' in this case).
+
+        * A call of the form `(substring SUBPLACE N [M])', where
+          SUBPLACE is itself a legal generalized variable whose current
+          value is a string, and where the value stored is also a
+          string.  The new string is spliced into the specified part of
+          the destination string.  For example:
+
+               (setq a (list "hello" "world"))
+                    => ("hello" "world")
+               (cadr a)
+                    => "world"
+               (substring (cadr a) 2 4)
+                    => "rl"
+               (setf (substring (cadr a) 2 4) "o")
+                    => "o"
+               (cadr a)
+                    => "wood"
+               a
+                    => ("hello" "wood")
+
+          The generalized variable `buffer-substring', listed above,
+          also works in this way by replacing a portion of the current
+          buffer.
+
+        * A call of the form `(apply 'FUNC ...)' or `(apply (function
+          FUNC) ...)', where FUNC is a `setf'-able function whose store
+          function is "suitable" in the sense described in Steele's
+          book; since none of the standard Emacs place functions are
+          suitable in this sense, this feature is only interesting when
+          used with places you define yourself with
+          `define-setf-method' or the long form of `defsetf'.
+
+        * A macro call, in which case the macro is expanded and `setf'
+          is applied to the resulting form.
+
+        * Any form for which a `defsetf' or `define-setf-method' has
+          been made.
+
+     Using any forms other than these in the PLACE argument to `setf'
+     will signal an error.
+
+     The `setf' macro takes care to evaluate all subforms in the proper
+     left-to-right order; for example,
+
+          (setf (aref vec (incf i)) i)
+
+     looks like it will evaluate `(incf i)' exactly once, before the
+     following access to `i'; the `setf' expander will insert temporary
+     variables as necessary to ensure that it does in fact work this
+     way no matter what setf-method is defined for `aref'.  (In this
+     case, `aset' would be used and no such steps would be necessary
+     since `aset' takes its arguments in a convenient order.)
+
+     However, if the PLACE form is a macro which explicitly evaluates
+     its arguments in an unusual order, this unusual order will be
+     preserved.  Adapting an example from Steele, given
+
+          (defmacro wrong-order (x y) (list 'aref y x))
+
+     the form `(setf (wrong-order A B) 17)' will evaluate B first, then
+     A, just as in an actual call to `wrong-order'.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-2'
Index: ././info/cl.info-2
--- ././info/cl.info-2	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-2	Thu May 17 23:26:51 2001
@@ -0,0 +1,1030 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: Modify Macros,  Next: Customizing Setf,  Prev: Basic Setf,  Up: Generalized Variables
+
+Modify Macros
+-------------
+
+This package defines a number of other macros besides `setf' that
+operate on generalized variables.  Many are interesting and useful even
+when the PLACE is just a variable name.
+
+ - Special Form: psetf [place form]...
+     This macro is to `setf' what `psetq' is to `setq': When several
+     PLACEs and FORMs are involved, the assignments take place in
+     parallel rather than sequentially.  Specifically, all subforms are
+     evaluated from left to right, then all the assignments are done
+     (in an undefined order).
+
+ - Special Form: incf place &optional x
+     This macro increments the number stored in PLACE by one, or by X
+     if specified.  The incremented value is returned.  For example,
+     `(incf i)' is equivalent to `(setq i (1+ i))', and `(incf (car x)
+     2)' is equivalent to `(setcar x (+ (car x) 2))'.
+
+     Once again, care is taken to preserve the "apparent" order of
+     evaluation.  For example,
+
+          (incf (aref vec (incf i)))
+
+     appears to increment `i' once, then increment the element of `vec'
+     addressed by `i'; this is indeed exactly what it does, which means
+     the above form is _not_ equivalent to the "obvious" expansion,
+
+          (setf (aref vec (incf i)) (1+ (aref vec (incf i))))   ; Wrong!
+
+     but rather to something more like
+
+          (let ((temp (incf i)))
+            (setf (aref vec temp) (1+ (aref vec temp))))
+
+     Again, all of this is taken care of automatically by `incf' and
+     the other generalized-variable macros.
+
+     As a more Emacs-specific example of `incf', the expression `(incf
+     (point) N)' is essentially equivalent to `(forward-char N)'.
+
+ - Special Form: decf place &optional x
+     This macro decrements the number stored in PLACE by one, or by X
+     if specified.
+
+ - Special Form: pop place
+     This macro removes and returns the first element of the list stored
+     in PLACE.  It is analogous to `(prog1 (car PLACE) (setf PLACE (cdr
+     PLACE)))', except that it takes care to evaluate all subforms only
+     once.
+
+ - Special Form: push x place
+     This macro inserts X at the front of the list stored in PLACE.  It
+     is analogous to `(setf PLACE (cons X PLACE))', except for
+     evaluation of the subforms.
+
+ - Special Form: pushnew x place &key :test :test-not :key
+     This macro inserts X at the front of the list stored in PLACE, but
+     only if X was not `eql' to any existing element of the list.  The
+     optional keyword arguments are interpreted in the same way as for
+     `adjoin'.  *Note Lists as Sets::.
+
+ - Special Form: shiftf place... newvalue
+     This macro shifts the PLACEs left by one, shifting in the value of
+     NEWVALUE (which may be any Lisp expression, not just a generalized
+     variable), and returning the value shifted out of the first PLACE.
+     Thus, `(shiftf A B C D)' is equivalent to
+
+          (prog1
+              A
+            (psetf A B
+                   B C
+                   C D))
+
+     except that the subforms of A, B, and C are actually evaluated
+     only once each and in the apparent order.
+
+ - Special Form: rotatef place...
+     This macro rotates the PLACEs left by one in circular fashion.
+     Thus, `(rotatef A B C D)' is equivalent to
+
+          (psetf A B
+                 B C
+                 C D
+                 D A)
+
+     except for the evaluation of subforms.  `rotatef' always returns
+     `nil'.  Note that `(rotatef A B)' conveniently exchanges A and B.
+
+   The following macros were invented for this package; they have no
+analogues in Common Lisp.
+
+ - Special Form: letf (bindings...) forms...
+     This macro is analogous to `let', but for generalized variables
+     rather than just symbols.  Each BINDING should be of the form
+     `(PLACE VALUE)'; the original contents of the PLACEs are saved,
+     the VALUEs are stored in them, and then the body FORMs are
+     executed.  Afterwards, the PLACES are set back to their original
+     saved contents.  This cleanup happens even if the FORMs exit
+     irregularly due to a `throw' or an error.
+
+     For example,
+
+          (letf (((point) (point-min))
+                 (a 17))
+            ...)
+
+     moves "point" in the current buffer to the beginning of the buffer,
+     and also binds `a' to 17 (as if by a normal `let', since `a' is
+     just a regular variable).  After the body exits, `a' is set back
+     to its original value and point is moved back to its original
+     position.
+
+     Note that `letf' on `(point)' is not quite like a
+     `save-excursion', as the latter effectively saves a marker which
+     tracks insertions and deletions in the buffer.  Actually, a `letf'
+     of `(point-marker)' is much closer to this behavior.  (`point' and
+     `point-marker' are equivalent as `setf' places; each will accept
+     either an integer or a marker as the stored value.)
+
+     Since generalized variables look like lists, `let''s shorthand of
+     using `foo' for `(foo nil)' as a BINDING would be ambiguous in
+     `letf' and is not allowed.
+
+     However, a BINDING specifier may be a one-element list `(PLACE)',
+     which is similar to `(PLACE PLACE)'.  In other words, the PLACE is
+     not disturbed on entry to the body, and the only effect of the
+     `letf' is to restore the original value of PLACE afterwards.  (The
+     redundant access-and-store suggested by the `(PLACE PLACE)'
+     example does not actually occur.)
+
+     In most cases, the PLACE must have a well-defined value on entry
+     to the `letf' form.  The only exceptions are plain variables and
+     calls to `symbol-value' and `symbol-function'.  If the symbol is
+     not bound on entry, it is simply made unbound by `makunbound' or
+     `fmakunbound' on exit.
+
+ - Special Form: letf* (bindings...) forms...
+     This macro is to `letf' what `let*' is to `let': It does the
+     bindings in sequential rather than parallel order.
+
+ - Special Form: callf FUNCTION PLACE ARGS...
+     This is the "generic" modify macro.  It calls FUNCTION, which
+     should be an unquoted function name, macro name, or lambda.  It
+     passes PLACE and ARGS as arguments, and assigns the result back to
+     PLACE.  For example, `(incf PLACE N)' is the same as `(callf +
+     PLACE N)'.  Some more examples:
+
+          (callf abs my-number)
+          (callf concat (buffer-name) "<" (int-to-string n) ">")
+          (callf union happy-people (list joe bob) :test 'same-person)
+
+     *Note Customizing Setf::, for `define-modify-macro', a way to
+     create even more concise notations for modify macros.  Note again
+     that `callf' is an extension to standard Common Lisp.
+
+ - Special Form: callf2 FUNCTION ARG1 PLACE ARGS...
+     This macro is like `callf', except that PLACE is the _second_
+     argument of FUNCTION rather than the first.  For example, `(push X
+     PLACE)' is equivalent to `(callf2 cons X PLACE)'.
+
+   The `callf' and `callf2' macros serve as building blocks for other
+macros like `incf', `pushnew', and `define-modify-macro'.  The `letf'
+and `letf*' macros are used in the processing of symbol macros; *note
+Macro Bindings::.
+
+
+File: cl.info,  Node: Customizing Setf,  Prev: Modify Macros,  Up: Generalized Variables
+
+Customizing Setf
+----------------
+
+Common Lisp defines three macros, `define-modify-macro', `defsetf', and
+`define-setf-method', that allow the user to extend generalized
+variables in various ways.
+
+ - Special Form: define-modify-macro name arglist function [doc-string]
+     This macro defines a "read-modify-write" macro similar to `incf'
+     and `decf'.  The macro NAME is defined to take a PLACE argument
+     followed by additional arguments described by ARGLIST.  The call
+
+          (NAME PLACE ARGS...)
+
+     will be expanded to
+
+          (callf FUNC PLACE ARGS...)
+
+     which in turn is roughly equivalent to
+
+          (setf PLACE (FUNC PLACE ARGS...))
+
+     For example:
+
+          (define-modify-macro incf (&optional (n 1)) +)
+          (define-modify-macro concatf (&rest args) concat)
+
+     Note that `&key' is not allowed in ARGLIST, but `&rest' is
+     sufficient to pass keywords on to the function.
+
+     Most of the modify macros defined by Common Lisp do not exactly
+     follow the pattern of `define-modify-macro'.  For example, `push'
+     takes its arguments in the wrong order, and `pop' is completely
+     irregular.  You can define these macros "by hand" using
+     `get-setf-method', or consult the source file `cl-macs.el' to see
+     how to use the internal `setf' building blocks.
+
+ - Special Form: defsetf access-fn update-fn
+     This is the simpler of two `defsetf' forms.  Where ACCESS-FN is
+     the name of a function which accesses a place, this declares
+     UPDATE-FN to be the corresponding store function.  From now on,
+
+          (setf (ACCESS-FN ARG1 ARG2 ARG3) VALUE)
+
+     will be expanded to
+
+          (UPDATE-FN ARG1 ARG2 ARG3 VALUE)
+
+     The UPDATE-FN is required to be either a true function, or a macro
+     which evaluates its arguments in a function-like way.  Also, the
+     UPDATE-FN is expected to return VALUE as its result.  Otherwise,
+     the above expansion would not obey the rules for the way `setf' is
+     supposed to behave.
+
+     As a special (non-Common-Lisp) extension, a third argument of `t'
+     to `defsetf' says that the `update-fn''s return value is not
+     suitable, so that the above `setf' should be expanded to something
+     more like
+
+          (let ((temp VALUE))
+            (UPDATE-FN ARG1 ARG2 ARG3 temp)
+            temp)
+
+     Some examples of the use of `defsetf', drawn from the standard
+     suite of setf methods, are:
+
+          (defsetf car setcar)
+          (defsetf symbol-value set)
+          (defsetf buffer-name rename-buffer t)
+
+ - Special Form: defsetf access-fn arglist (store-var) forms...
+     This is the second, more complex, form of `defsetf'.  It is rather
+     like `defmacro' except for the additional STORE-VAR argument.  The
+     FORMS should return a Lisp form which stores the value of
+     STORE-VAR into the generalized variable formed by a call to
+     ACCESS-FN with arguments described by ARGLIST.  The FORMS may
+     begin with a string which documents the `setf' method (analogous
+     to the doc string that appears at the front of a function).
+
+     For example, the simple form of `defsetf' is shorthand for
+
+          (defsetf ACCESS-FN (&rest args) (store)
+            (append '(UPDATE-FN) args (list store)))
+
+     The Lisp form that is returned can access the arguments from
+     ARGLIST and STORE-VAR in an unrestricted fashion; macros like
+     `setf' and `incf' which invoke this setf-method will insert
+     temporary variables as needed to make sure the apparent order of
+     evaluation is preserved.
+
+     Another example drawn from the standard package:
+
+          (defsetf nth (n x) (store)
+            (list 'setcar (list 'nthcdr n x) store))
+
+ - Special Form: define-setf-method access-fn arglist forms...
+     This is the most general way to create new place forms.  When a
+     `setf' to ACCESS-FN with arguments described by ARGLIST is
+     expanded, the FORMS are evaluated and must return a list of five
+     items:
+
+       1. A list of "temporary variables".
+
+       2. A list of "value forms" corresponding to the temporary
+          variables above.  The temporary variables will be bound to
+          these value forms as the first step of any operation on the
+          generalized variable.
+
+       3. A list of exactly one "store variable" (generally obtained
+          from a call to `gensym').
+
+       4. A Lisp form which stores the contents of the store variable
+          into the generalized variable, assuming the temporaries have
+          been bound as described above.
+
+       5. A Lisp form which accesses the contents of the generalized
+          variable, assuming the temporaries have been bound.
+
+     This is exactly like the Common Lisp macro of the same name,
+     except that the method returns a list of five values rather than
+     the five values themselves, since Emacs Lisp does not support
+     Common Lisp's notion of multiple return values.
+
+     Once again, the FORMS may begin with a documentation string.
+
+     A setf-method should be maximally conservative with regard to
+     temporary variables.  In the setf-methods generated by `defsetf',
+     the second return value is simply the list of arguments in the
+     place form, and the first return value is a list of a
+     corresponding number of temporary variables generated by `gensym'.
+     Macros like `setf' and `incf' which use this setf-method will
+     optimize away most temporaries that turn out to be unnecessary, so
+     there is little reason for the setf-method itself to optimize.
+
+ - Function: get-setf-method place &optional env
+     This function returns the setf-method for PLACE, by invoking the
+     definition previously recorded by `defsetf' or
+     `define-setf-method'.  The result is a list of five values as
+     described above.  You can use this function to build your own
+     `incf'-like modify macros.  (Actually, it is better to use the
+     internal functions `cl-setf-do-modify' and `cl-setf-do-store',
+     which are a bit easier to use and which also do a number of
+     optimizations; consult the source code for the `incf' function for
+     a simple example.)
+
+     The argument ENV specifies the "environment" to be passed on to
+     `macroexpand' if `get-setf-method' should need to expand a macro
+     in PLACE.  It should come from an `&environment' argument to the
+     macro or setf-method that called `get-setf-method'.
+
+     See also the source code for the setf-methods for `apply' and
+     `substring', each of which works by calling `get-setf-method' on a
+     simpler case, then massaging the result in various ways.
+
+   Modern Common Lisp defines a second, independent way to specify the
+`setf' behavior of a function, namely "`setf' functions" whose names
+are lists `(setf NAME)' rather than symbols.  For example, `(defun
+(setf foo) ...)' defines the function that is used when `setf' is
+applied to `foo'.  This package does not currently support `setf'
+functions.  In particular, it is a compile-time error to use `setf' on
+a form which has not already been `defsetf''d or otherwise declared; in
+newer Common Lisps, this would not be an error since the function
+`(setf FUNC)' might be defined later.
+
+
+File: cl.info,  Node: Variable Bindings,  Next: Conditionals,  Prev: Generalized Variables,  Up: Control Structure
+
+Variable Bindings
+=================
+
+These Lisp forms make bindings to variables and function names,
+analogous to Lisp's built-in `let' form.
+
+   *Note Modify Macros::, for the `letf' and `letf*' forms which are
+also related to variable bindings.
+
+* Menu:
+
+* Dynamic Bindings::     The `progv' form
+* Lexical Bindings::     `lexical-let' and lexical closures
+* Function Bindings::    `flet' and `labels'
+* Macro Bindings::       `macrolet' and `symbol-macrolet'
+
+
+File: cl.info,  Node: Dynamic Bindings,  Next: Lexical Bindings,  Prev: Variable Bindings,  Up: Variable Bindings
+
+Dynamic Bindings
+----------------
+
+The standard `let' form binds variables whose names are known at
+compile-time.  The `progv' form provides an easy way to bind variables
+whose names are computed at run-time.
+
+ - Special Form: progv symbols values forms...
+     This form establishes `let'-style variable bindings on a set of
+     variables computed at run-time.  The expressions SYMBOLS and
+     VALUES are evaluated, and must return lists of symbols and values,
+     respectively.  The symbols are bound to the corresponding values
+     for the duration of the body FORMs.  If VALUES is shorter than
+     SYMBOLS, the last few symbols are made unbound (as if by
+     `makunbound') inside the body.  If SYMBOLS is shorter than VALUES,
+     the excess values are ignored.
+
+
+File: cl.info,  Node: Lexical Bindings,  Next: Function Bindings,  Prev: Dynamic Bindings,  Up: Variable Bindings
+
+Lexical Bindings
+----------------
+
+The "CL" package defines the following macro which more closely follows
+the Common Lisp `let' form:
+
+ - Special Form: lexical-let (bindings...) forms...
+     This form is exactly like `let' except that the bindings it
+     establishes are purely lexical.  Lexical bindings are similar to
+     local variables in a language like C:  Only the code physically
+     within the body of the `lexical-let' (after macro expansion) may
+     refer to the bound variables.
+
+          (setq a 5)
+          (defun foo (b) (+ a b))
+          (let ((a 2)) (foo a))
+               => 4
+          (lexical-let ((a 2)) (foo a))
+               => 7
+
+     In this example, a regular `let' binding of `a' actually makes a
+     temporary change to the global variable `a', so `foo' is able to
+     see the binding of `a' to 2.  But `lexical-let' actually creates a
+     distinct local variable `a' for use within its body, without any
+     effect on the global variable of the same name.
+
+     The most important use of lexical bindings is to create "closures".
+     A closure is a function object that refers to an outside lexical
+     variable.  For example:
+
+          (defun make-adder (n)
+            (lexical-let ((n n))
+              (function (lambda (m) (+ n m)))))
+          (setq add17 (make-adder 17))
+          (funcall add17 4)
+               => 21
+
+     The call `(make-adder 17)' returns a function object which adds 17
+     to its argument.  If `let' had been used instead of `lexical-let',
+     the function object would have referred to the global `n', which
+     would have been bound to 17 only during the call to `make-adder'
+     itself.
+
+          (defun make-counter ()
+            (lexical-let ((n 0))
+              (function* (lambda (&optional (m 1)) (incf n m)))))
+          (setq count-1 (make-counter))
+          (funcall count-1 3)
+               => 3
+          (funcall count-1 14)
+               => 17
+          (setq count-2 (make-counter))
+          (funcall count-2 5)
+               => 5
+          (funcall count-1 2)
+               => 19
+          (funcall count-2)
+               => 6
+
+     Here we see that each call to `make-counter' creates a distinct
+     local variable `n', which serves as a private counter for the
+     function object that is returned.
+
+     Closed-over lexical variables persist until the last reference to
+     them goes away, just like all other Lisp objects.  For example,
+     `count-2' refers to a function object which refers to an instance
+     of the variable `n'; this is the only reference to that variable,
+     so after `(setq count-2 nil)' the garbage collector would be able
+     to delete this instance of `n'.  Of course, if a `lexical-let'
+     does not actually create any closures, then the lexical variables
+     are free as soon as the `lexical-let' returns.
+
+     Many closures are used only during the extent of the bindings they
+     refer to; these are known as "downward funargs" in Lisp parlance.
+     When a closure is used in this way, regular Emacs Lisp dynamic
+     bindings suffice and will be more efficient than `lexical-let'
+     closures:
+
+          (defun add-to-list (x list)
+            (mapcar (function (lambda (y) (+ x y))) list))
+          (add-to-list 7 '(1 2 5))
+               => (8 9 12)
+
+     Since this lambda is only used while `x' is still bound, it is not
+     necessary to make a true closure out of it.
+
+     You can use `defun' or `flet' inside a `lexical-let' to create a
+     named closure.  If several closures are created in the body of a
+     single `lexical-let', they all close over the same instance of the
+     lexical variable.
+
+     The `lexical-let' form is an extension to Common Lisp.  In true
+     Common Lisp, all bindings are lexical unless declared otherwise.
+
+ - Special Form: lexical-let* (bindings...) forms...
+     This form is just like `lexical-let', except that the bindings are
+     made sequentially in the manner of `let*'.
+
+
+File: cl.info,  Node: Function Bindings,  Next: Macro Bindings,  Prev: Lexical Bindings,  Up: Variable Bindings
+
+Function Bindings
+-----------------
+
+These forms make `let'-like bindings to functions instead of variables.
+
+ - Special Form: flet (bindings...) forms...
+     This form establishes `let'-style bindings on the function cells
+     of symbols rather than on the value cells.  Each BINDING must be a
+     list of the form `(NAME ARGLIST FORMS...)', which defines a
+     function exactly as if it were a `defun*' form.  The function NAME
+     is defined accordingly for the duration of the body of the `flet';
+     then the old function definition, or lack thereof, is restored.
+
+     While `flet' in Common Lisp establishes a lexical binding of NAME,
+     Emacs Lisp `flet' makes a dynamic binding.  The result is that
+     `flet' affects indirect calls to a function as well as calls
+     directly inside the `flet' form itself.
+
+     You can use `flet' to disable or modify the behavior of a function
+     in a temporary fashion.  This will even work on Emacs primitives,
+     although note that some calls to primitive functions internal to
+     Emacs are made without going through the symbol's function cell,
+     and so will not be affected by `flet'.  For example,
+
+          (flet ((message (&rest args) (push args saved-msgs)))
+            (do-something))
+
+     This code attempts to replace the built-in function `message' with
+     a function that simply saves the messages in a list rather than
+     displaying them.  The original definition of `message' will be
+     restored after `do-something' exits.  This code will work fine on
+     messages generated by other Lisp code, but messages generated
+     directly inside Emacs will not be caught since they make direct
+     C-language calls to the message routines rather than going through
+     the Lisp `message' function.
+
+     Functions defined by `flet' may use the full Common Lisp argument
+     notation supported by `defun*'; also, the function body is
+     enclosed in an implicit block as if by `defun*'.  *Note Program
+     Structure::.
+
+ - Special Form: labels (bindings...) forms...
+     The `labels' form is a synonym for `flet'.  (In Common Lisp,
+     `labels' and `flet' differ in ways that depend on their lexical
+     scoping; these distinctions vanish in dynamically scoped Emacs
+     Lisp.)
+
+
+File: cl.info,  Node: Macro Bindings,  Prev: Function Bindings,  Up: Variable Bindings
+
+Macro Bindings
+--------------
+
+These forms create local macros and "symbol macros."
+
+ - Special Form: macrolet (bindings...) forms...
+     This form is analogous to `flet', but for macros instead of
+     functions.  Each BINDING is a list of the same form as the
+     arguments to `defmacro*' (i.e., a macro name, argument list, and
+     macro-expander forms).  The macro is defined accordingly for use
+     within the body of the `macrolet'.
+
+     Because of the nature of macros, `macrolet' is lexically scoped
+     even in Emacs Lisp:  The `macrolet' binding will affect only calls
+     that appear physically within the body FORMS, possibly after
+     expansion of other macros in the body.
+
+ - Special Form: symbol-macrolet (bindings...) forms...
+     This form creates "symbol macros", which are macros that look like
+     variable references rather than function calls.  Each BINDING is a
+     list `(VAR EXPANSION)'; any reference to VAR within the body FORMS
+     is replaced by EXPANSION.
+
+          (setq bar '(5 . 9))
+          (symbol-macrolet ((foo (car bar)))
+            (incf foo))
+          bar
+               => (6 . 9)
+
+     A `setq' of a symbol macro is treated the same as a `setf'.  I.e.,
+     `(setq foo 4)' in the above would be equivalent to `(setf foo 4)',
+     which in turn expands to `(setf (car bar) 4)'.
+
+     Likewise, a `let' or `let*' binding a symbol macro is treated like
+     a `letf' or `letf*'.  This differs from true Common Lisp, where
+     the rules of lexical scoping cause a `let' binding to shadow a
+     `symbol-macrolet' binding.  In this package, only `lexical-let'
+     and `lexical-let*' will shadow a symbol macro.
+
+     There is no analogue of `defmacro' for symbol macros; all symbol
+     macros are local.  A typical use of `symbol-macrolet' is in the
+     expansion of another macro:
+
+          (defmacro* my-dolist ((x list) &rest body)
+            (let ((var (gensym)))
+              (list 'loop 'for var 'on list 'do
+                    (list* 'symbol-macrolet (list (list x (list 'car var)))
+                           body))))
+          
+          (setq mylist '(1 2 3 4))
+          (my-dolist (x mylist) (incf x))
+          mylist
+               => (2 3 4 5)
+
+     In this example, the `my-dolist' macro is similar to `dolist'
+     (*note Iteration::) except that the variable `x' becomes a true
+     reference onto the elements of the list.  The `my-dolist' call
+     shown here expands to
+
+          (loop for G1234 on mylist do
+                (symbol-macrolet ((x (car G1234)))
+                  (incf x)))
+
+     which in turn expands to
+
+          (loop for G1234 on mylist do (incf (car G1234)))
+
+     *Note Loop Facility::, for a description of the `loop' macro.
+     This package defines a nonstandard `in-ref' loop clause that works
+     much like `my-dolist'.
+
+
+File: cl.info,  Node: Conditionals,  Next: Blocks and Exits,  Prev: Variable Bindings,  Up: Control Structure
+
+Conditionals
+============
+
+These conditional forms augment Emacs Lisp's simple `if', `and', `or',
+and `cond' forms.
+
+ - Special Form: when test forms...
+     This is a variant of `if' where there are no "else" forms, and
+     possibly several "then" forms.  In particular,
+
+          (when TEST A B C)
+
+     is entirely equivalent to
+
+          (if TEST (progn A B C) nil)
+
+ - Special Form: unless test forms...
+     This is a variant of `if' where there are no "then" forms, and
+     possibly several "else" forms:
+
+          (unless TEST A B C)
+
+     is entirely equivalent to
+
+          (when (not TEST) A B C)
+
+ - Special Form: case keyform clause...
+     This macro evaluates KEYFORM, then compares it with the key values
+     listed in the various CLAUSEs.  Whichever clause matches the key
+     is executed; comparison is done by `eql'.  If no clause matches,
+     the `case' form returns `nil'.  The clauses are of the form
+
+          (KEYLIST BODY-FORMS...)
+
+     where KEYLIST is a list of key values.  If there is exactly one
+     value, and it is not a cons cell or the symbol `nil' or `t', then
+     it can be used by itself as a KEYLIST without being enclosed in a
+     list.  All key values in the `case' form must be distinct.  The
+     final clauses may use `t' in place of a KEYLIST to indicate a
+     default clause that should be taken if none of the other clauses
+     match.  (The symbol `otherwise' is also recognized in place of
+     `t'.  To make a clause that matches the actual symbol `t', `nil',
+     or `otherwise', enclose the symbol in a list.)
+
+     For example, this expression reads a keystroke, then does one of
+     four things depending on whether it is an `a', a `b', a <RET> or
+     <LFD>, or anything else.
+
+          (case (read-char)
+            (?a (do-a-thing))
+            (?b (do-b-thing))
+            ((?\r ?\n) (do-ret-thing))
+            (t (do-other-thing)))
+
+ - Special Form: ecase keyform clause...
+     This macro is just like `case', except that if the key does not
+     match any of the clauses, an error is signalled rather than simply
+     returning `nil'.
+
+ - Special Form: typecase keyform clause...
+     This macro is a version of `case' that checks for types rather
+     than values.  Each CLAUSE is of the form `(TYPE BODY...)'.  *Note
+     Type Predicates::, for a description of type specifiers.  For
+     example,
+
+          (typecase x
+            (integer (munch-integer x))
+            (float (munch-float x))
+            (string (munch-integer (string-to-int x)))
+            (t (munch-anything x)))
+
+     The type specifier `t' matches any type of object; the word
+     `otherwise' is also allowed.  To make one clause match any of
+     several types, use an `(or ...)' type specifier.
+
+ - Special Form: etypecase keyform clause...
+     This macro is just like `typecase', except that if the key does
+     not match any of the clauses, an error is signalled rather than
+     simply returning `nil'.
+
+
+File: cl.info,  Node: Blocks and Exits,  Next: Iteration,  Prev: Conditionals,  Up: Control Structure
+
+Blocks and Exits
+================
+
+Common Lisp "blocks" provide a non-local exit mechanism very similar to
+`catch' and `throw', but lexically rather than dynamically scoped.
+This package actually implements `block' in terms of `catch'; however,
+the lexical scoping allows the optimizing byte-compiler to omit the
+costly `catch' step if the body of the block does not actually
+`return-from' the block.
+
+ - Special Form: block name forms...
+     The FORMS are evaluated as if by a `progn'.  However, if any of
+     the FORMS execute `(return-from NAME)', they will jump out and
+     return directly from the `block' form.  The `block' returns the
+     result of the last FORM unless a `return-from' occurs.
+
+     The `block'/`return-from' mechanism is quite similar to the
+     `catch'/`throw' mechanism.  The main differences are that block
+     NAMEs are unevaluated symbols, rather than forms (such as quoted
+     symbols) which evaluate to a tag at run-time; and also that blocks
+     are lexically scoped whereas `catch'/`throw' are dynamically
+     scoped.  This means that functions called from the body of a
+     `catch' can also `throw' to the `catch', but the `return-from'
+     referring to a block name must appear physically within the FORMS
+     that make up the body of the block.  They may not appear within
+     other called functions, although they may appear within macro
+     expansions or `lambda's in the body.  Block names and `catch'
+     names form independent name-spaces.
+
+     In true Common Lisp, `defun' and `defmacro' surround the function
+     or expander bodies with implicit blocks with the same name as the
+     function or macro.  This does not occur in Emacs Lisp, but this
+     package provides `defun*' and `defmacro*' forms which do create
+     the implicit block.
+
+     The Common Lisp looping constructs defined by this package, such
+     as `loop' and `dolist', also create implicit blocks just as in
+     Common Lisp.
+
+     Because they are implemented in terms of Emacs Lisp `catch' and
+     `throw', blocks have the same overhead as actual `catch'
+     constructs (roughly two function calls).  However, Zawinski and
+     Furuseth's optimizing byte compiler (standard in Emacs 19) will
+     optimize away the `catch' if the block does not in fact contain
+     any `return' or `return-from' calls that jump to it.  This means
+     that `do' loops and `defun*' functions which don't use `return'
+     don't pay the overhead to support it.
+
+ - Special Form: return-from name [result]
+     This macro returns from the block named NAME, which must be an
+     (unevaluated) symbol.  If a RESULT form is specified, it is
+     evaluated to produce the result returned from the `block'.
+     Otherwise, `nil' is returned.
+
+ - Special Form: return [result]
+     This macro is exactly like `(return-from nil RESULT)'.  Common
+     Lisp loops like `do' and `dolist' implicitly enclose themselves in
+     `nil' blocks.
+
+
+File: cl.info,  Node: Iteration,  Next: Loop Facility,  Prev: Blocks and Exits,  Up: Control Structure
+
+Iteration
+=========
+
+The macros described here provide more sophisticated, high-level
+looping constructs to complement Emacs Lisp's basic `while' loop.
+
+ - Special Form: loop forms...
+     The "CL" package supports both the simple, old-style meaning of
+     `loop' and the extremely powerful and flexible feature known as
+     the "Loop Facility" or "Loop Macro".  This more advanced facility
+     is discussed in the following section; *note Loop Facility::.  The
+     simple form of `loop' is described here.
+
+     If `loop' is followed by zero or more Lisp expressions, then
+     `(loop EXPRS...)' simply creates an infinite loop executing the
+     expressions over and over.  The loop is enclosed in an implicit
+     `nil' block.  Thus,
+
+          (loop (foo)  (if (no-more) (return 72))  (bar))
+
+     is exactly equivalent to
+
+          (block nil (while t (foo)  (if (no-more) (return 72))  (bar)))
+
+     If any of the expressions are plain symbols, the loop is instead
+     interpreted as a Loop Macro specification as described later.
+     (This is not a restriction in practice, since a plain symbol in
+     the above notation would simply access and throw away the value of
+     a variable.)
+
+ - Special Form: do (spec...) (end-test [result...]) forms...
+     This macro creates a general iterative loop.  Each SPEC is of the
+     form
+
+          (VAR [INIT [STEP]])
+
+     The loop works as follows:  First, each VAR is bound to the
+     associated INIT value as if by a `let' form.  Then, in each
+     iteration of the loop, the END-TEST is evaluated; if true, the
+     loop is finished.  Otherwise, the body FORMS are evaluated, then
+     each VAR is set to the associated STEP expression (as if by a
+     `psetq' form) and the next iteration begins.  Once the END-TEST
+     becomes true, the RESULT forms are evaluated (with the VARs still
+     bound to their values) to produce the result returned by `do'.
+
+     The entire `do' loop is enclosed in an implicit `nil' block, so
+     that you can use `(return)' to break out of the loop at any time.
+
+     If there are no RESULT forms, the loop returns `nil'.  If a given
+     VAR has no STEP form, it is bound to its INIT value but not
+     otherwise modified during the `do' loop (unless the code
+     explicitly modifies it); this case is just a shorthand for putting
+     a `(let ((VAR INIT)) ...)' around the loop.  If INIT is also
+     omitted it defaults to `nil', and in this case a plain `VAR' can
+     be used in place of `(VAR)', again following the analogy with
+     `let'.
+
+     This example (from Steele) illustrates a loop which applies the
+     function `f' to successive pairs of values from the lists `foo'
+     and `bar'; it is equivalent to the call `(mapcar* 'f foo bar)'.
+     Note that this loop has no body FORMS at all, performing all its
+     work as side effects of the rest of the loop.
+
+          (do ((x foo (cdr x))
+               (y bar (cdr y))
+               (z nil (cons (f (car x) (car y)) z)))
+            ((or (null x) (null y))
+             (nreverse z)))
+
+ - Special Form: do* (spec...) (end-test [result...]) forms...
+     This is to `do' what `let*' is to `let'.  In particular, the
+     initial values are bound as if by `let*' rather than `let', and
+     the steps are assigned as if by `setq' rather than `psetq'.
+
+     Here is another way to write the above loop:
+
+          (do* ((xp foo (cdr xp))
+                (yp bar (cdr yp))
+                (x (car xp) (car xp))
+                (y (car yp) (car yp))
+                z)
+            ((or (null xp) (null yp))
+             (nreverse z))
+            (push (f x y) z))
+
+ - Special Form: dolist (var list [result]) forms...
+     This is a more specialized loop which iterates across the elements
+     of a list.  LIST should evaluate to a list; the body FORMS are
+     executed with VAR bound to each element of the list in turn.
+     Finally, the RESULT form (or `nil') is evaluated with VAR bound to
+     `nil' to produce the result returned by the loop.  The loop is
+     surrounded by an implicit `nil' block.
+
+ - Special Form: dotimes (var count [result]) forms...
+     This is a more specialized loop which iterates a specified number
+     of times.  The body is executed with VAR bound to the integers
+     from zero (inclusive) to COUNT (exclusive), in turn.  Then the
+     `result' form is evaluated with VAR bound to the total number of
+     iterations that were done (i.e., `(max 0 COUNT)') to get the
+     return value for the loop form.  The loop is surrounded by an
+     implicit `nil' block.
+
+ - Special Form: do-symbols (var [obarray [result]]) forms...
+     This loop iterates over all interned symbols.  If OBARRAY is
+     specified and is not `nil', it loops over all symbols in that
+     obarray.  For each symbol, the body FORMS are evaluated with VAR
+     bound to that symbol.  The symbols are visited in an unspecified
+     order.  Afterward the RESULT form, if any, is evaluated (with VAR
+     bound to `nil') to get the return value.  The loop is surrounded
+     by an implicit `nil' block.
+
+ - Special Form: do-all-symbols (var [result]) forms...
+     This is identical to `do-symbols' except that the OBARRAY argument
+     is omitted; it always iterates over the default obarray.
+
+   *Note Mapping over Sequences::, for some more functions for
+iterating over vectors or lists.
+
+
+File: cl.info,  Node: Loop Facility,  Next: Multiple Values,  Prev: Iteration,  Up: Control Structure
+
+Loop Facility
+=============
+
+A common complaint with Lisp's traditional looping constructs is that
+they are either too simple and limited, such as Common Lisp's `dotimes'
+or Emacs Lisp's `while', or too unreadable and obscure, like Common
+Lisp's `do' loop.
+
+   To remedy this, recent versions of Common Lisp have added a new
+construct called the "Loop Facility" or "`loop' macro," with an
+easy-to-use but very powerful and expressive syntax.
+
+* Menu:
+
+* Loop Basics::           `loop' macro, basic clause structure
+* Loop Examples::         Working examples of `loop' macro
+* For Clauses::           Clauses introduced by `for' or `as'
+* Iteration Clauses::     `repeat', `while', `thereis', etc.
+* Accumulation Clauses::  `collect', `sum', `maximize', etc.
+* Other Clauses::         `with', `if', `initially', `finally'
+
+
+File: cl.info,  Node: Loop Basics,  Next: Loop Examples,  Prev: Loop Facility,  Up: Loop Facility
+
+Loop Basics
+-----------
+
+The `loop' macro essentially creates a mini-language within Lisp that
+is specially tailored for describing loops.  While this language is a
+little strange-looking by the standards of regular Lisp, it turns out
+to be very easy to learn and well-suited to its purpose.
+
+   Since `loop' is a macro, all parsing of the loop language takes
+place at byte-compile time; compiled `loop's are just as efficient as
+the equivalent `while' loops written longhand.
+
+ - Special Form: loop clauses...
+     A loop construct consists of a series of CLAUSEs, each introduced
+     by a symbol like `for' or `do'.  Clauses are simply strung
+     together in the argument list of `loop', with minimal extra
+     parentheses.  The various types of clauses specify
+     initializations, such as the binding of temporary variables,
+     actions to be taken in the loop, stepping actions, and final
+     cleanup.
+
+     Common Lisp specifies a certain general order of clauses in a loop:
+
+          (loop NAME-CLAUSE
+                VAR-CLAUSES...
+                ACTION-CLAUSES...)
+
+     The NAME-CLAUSE optionally gives a name to the implicit block that
+     surrounds the loop.  By default, the implicit block is named
+     `nil'.  The VAR-CLAUSES specify what variables should be bound
+     during the loop, and how they should be modified or iterated
+     throughout the course of the loop.  The ACTION-CLAUSES are things
+     to be done during the loop, such as computing, collecting, and
+     returning values.
+
+     The Emacs version of the `loop' macro is less restrictive about
+     the order of clauses, but things will behave most predictably if
+     you put the variable-binding clauses `with', `for', and `repeat'
+     before the action clauses.  As in Common Lisp, `initially' and
+     `finally' clauses can go anywhere.
+
+     Loops generally return `nil' by default, but you can cause them to
+     return a value by using an accumulation clause like `collect', an
+     end-test clause like `always', or an explicit `return' clause to
+     jump out of the implicit block.  (Because the loop body is
+     enclosed in an implicit block, you can also use regular Lisp
+     `return' or `return-from' to break out of the loop.)
+
+   The following sections give some examples of the Loop Macro in
+action, and describe the particular loop clauses in great detail.
+Consult the second edition of Steele's "Common Lisp, the Language", for
+additional discussion and examples of the `loop' macro.
+
+
+File: cl.info,  Node: Loop Examples,  Next: For Clauses,  Prev: Loop Basics,  Up: Loop Facility
+
+Loop Examples
+-------------
+
+Before listing the full set of clauses that are allowed, let's look at
+a few example loops just to get a feel for the `loop' language.
+
+     (loop for buf in (buffer-list)
+           collect (buffer-file-name buf))
+
+This loop iterates over all Emacs buffers, using the list returned by
+`buffer-list'.  For each buffer `buf', it calls `buffer-file-name' and
+collects the results into a list, which is then returned from the
+`loop' construct.  The result is a list of the file names of all the
+buffers in Emacs' memory.  The words `for', `in', and `collect' are
+reserved words in the `loop' language.
+
+     (loop repeat 20 do (insert "Yowsa\n"))
+
+This loop inserts the phrase "Yowsa" twenty times in the current buffer.
+
+     (loop until (eobp) do (munch-line) (forward-line 1))
+
+This loop calls `munch-line' on every line until the end of the buffer.
+If point is already at the end of the buffer, the loop exits
+immediately.
+
+     (loop do (munch-line) until (eobp) do (forward-line 1))
+
+This loop is similar to the above one, except that `munch-line' is
+always called at least once.
+
+     (loop for x from 1 to 100
+           for y = (* x x)
+           until (>= y 729)
+           finally return (list x (= y 729)))
+
+This more complicated loop searches for a number `x' whose square is
+729.  For safety's sake it only examines `x' values up to 100; dropping
+the phrase `to 100' would cause the loop to count upwards with no
+limit.  The second `for' clause defines `y' to be the square of `x'
+within the loop; the expression after the `=' sign is reevaluated each
+time through the loop.  The `until' clause gives a condition for
+terminating the loop, and the `finally' clause says what to do when the
+loop finishes.  (This particular example was written less concisely
+than it could have been, just for the sake of illustration.)
+
+   Note that even though this loop contains three clauses (two `for's
+and an `until') that would have been enough to define loops all by
+themselves, it still creates a single loop rather than some sort of
+triple-nested loop.  You must explicitly nest your `loop' constructs if
+you want nested loops.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-3'
Index: ././info/cl.info-3
--- ././info/cl.info-3	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-3	Thu May 17 23:26:51 2001
@@ -0,0 +1,1125 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: For Clauses,  Next: Iteration Clauses,  Prev: Loop Examples,  Up: Loop Facility
+
+For Clauses
+-----------
+
+Most loops are governed by one or more `for' clauses.  A `for' clause
+simultaneously describes variables to be bound, how those variables are
+to be stepped during the loop, and usually an end condition based on
+those variables.
+
+   The word `as' is a synonym for the word `for'.  This word is
+followed by a variable name, then a word like `from' or `across' that
+describes the kind of iteration desired.  In Common Lisp, the phrase
+`being the' sometimes precedes the type of iteration; in this package
+both `being' and `the' are optional.  The word `each' is a synonym for
+`the', and the word that follows it may be singular or plural:  `for x
+being the elements of y' or `for x being each element of y'.  Which
+form you use is purely a matter of style.
+
+   The variable is bound around the loop as if by `let':
+
+     (setq i 'happy)
+     (loop for i from 1 to 10 do (do-something-with i))
+     i
+          => happy
+
+`for VAR from EXPR1 to EXPR2 by EXPR3'
+     This type of `for' clause creates a counting loop.  Each of the
+     three sub-terms is optional, though there must be at least one
+     term so that the clause is marked as a counting clause.
+
+     The three expressions are the starting value, the ending value, and
+     the step value, respectively, of the variable.  The loop counts
+     upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
+     inclusively.  If you omit the `from' term, the loop counts from
+     zero; if you omit the `to' term, the loop counts forever without
+     stopping (unless stopped by some other loop clause, of course); if
+     you omit the `by' term, the loop counts in steps of one.
+
+     You can replace the word `from' with `upfrom' or `downfrom' to
+     indicate the direction of the loop.  Likewise, you can replace
+     `to' with `upto' or `downto'.  For example, `for x from 5 downto
+     1' executes five times with `x' taking on the integers from 5 down
+     to 1 in turn.  Also, you can replace `to' with `below' or `above',
+     which are like `upto' and `downto' respectively except that they
+     are exclusive rather than inclusive limits:
+
+          (loop for x to 10 collect x)
+               => (0 1 2 3 4 5 6 7 8 9 10)
+          (loop for x below 10 collect x)
+               => (0 1 2 3 4 5 6 7 8 9)
+
+     The `by' value is always positive, even for downward-counting
+     loops.  Some sort of `from' value is required for downward loops;
+     `for x downto 5' is not a legal loop clause all by itself.
+
+`for VAR in LIST by FUNCTION'
+     This clause iterates VAR over all the elements of LIST, in turn.
+     If you specify the `by' term, then FUNCTION is used to traverse
+     the list instead of `cdr'; it must be a function taking one
+     argument.  For example:
+
+          (loop for x in '(1 2 3 4 5 6) collect (* x x))
+               => (1 4 9 16 25 36)
+          (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
+               => (1 9 25)
+
+`for VAR on LIST by FUNCTION'
+     This clause iterates VAR over all the cons cells of LIST.
+
+          (loop for x on '(1 2 3 4) collect x)
+               => ((1 2 3 4) (2 3 4) (3 4) (4))
+
+     With `by', there is no real reason that the `on' expression must
+     be a list.  For example:
+
+          (loop for x on first-animal by 'next-animal collect x)
+
+     where `(next-animal x)' takes an "animal" X and returns the next
+     in the (assumed) sequence of animals, or `nil' if X was the last
+     animal in the sequence.
+
+`for VAR in-ref LIST by FUNCTION'
+     This is like a regular `in' clause, but VAR becomes a `setf'-able
+     "reference" onto the elements of the list rather than just a
+     temporary variable.  For example,
+
+          (loop for x in-ref my-list do (incf x))
+
+     increments every element of `my-list' in place.  This clause is an
+     extension to standard Common Lisp.
+
+`for VAR across ARRAY'
+     This clause iterates VAR over all the elements of ARRAY, which may
+     be a vector or a string.
+
+          (loop for x across "aeiou"
+                do (use-vowel (char-to-string x)))
+
+`for VAR across-ref ARRAY'
+     This clause iterates over an array, with VAR a `setf'-able
+     reference onto the elements; see `in-ref' above.
+
+`for VAR being the elements of SEQUENCE'
+     This clause iterates over the elements of SEQUENCE, which may be a
+     list, vector, or string.  Since the type must be determined at
+     run-time, this is somewhat less efficient than `in' or `across'.
+     The clause may be followed by the additional term `using (index
+     VAR2)' to cause VAR2 to be bound to the successive indices
+     (starting at 0) of the elements.
+
+     This clause type is taken from older versions of the `loop' macro,
+     and is not present in modern Common Lisp.  The `using (sequence
+     ...)' term of the older macros is not supported.
+
+`for VAR being the elements of-ref SEQUENCE'
+     This clause iterates over a sequence, with VAR a `setf'-able
+     reference onto the elements; see `in-ref' above.
+
+`for VAR being the symbols [of OBARRAY]'
+     This clause iterates over symbols, either over all interned symbols
+     or over all symbols in OBARRAY.  The loop is executed with VAR
+     bound to each symbol in turn.  The symbols are visited in an
+     unspecified order.
+
+     As an example,
+
+          (loop for sym being the symbols
+                when (fboundp sym)
+                when (string-match "^map" (symbol-name sym))
+                collect sym)
+
+     returns a list of all the functions whose names begin with `map'.
+
+     The Common Lisp words `external-symbols' and `present-symbols' are
+     also recognized but are equivalent to `symbols' in Emacs Lisp.
+
+     Due to a minor implementation restriction, it will not work to have
+     more than one `for' clause iterating over symbols, hash tables,
+     keymaps, overlays, or intervals in a given `loop'.  Fortunately,
+     it would rarely if ever be useful to do so.  It _is_ legal to mix
+     one of these types of clauses with other clauses like `for ... to'
+     or `while'.
+
+`for VAR being the hash-keys of HASH-TABLE'
+     This clause iterates over the entries in HASH-TABLE.  For each
+     hash table entry, VAR is bound to the entry's key.  If you write
+     `the hash-values' instead, VAR is bound to the values of the
+     entries.  The clause may be followed by the additional term `using
+     (hash-values VAR2)' (where `hash-values' is the opposite word of
+     the word following `the') to cause VAR and VAR2 to be bound to the
+     two parts of each hash table entry.
+
+`for VAR being the key-codes of KEYMAP'
+     This clause iterates over the entries in KEYMAP.  In GNU Emacs 18
+     and 19, keymaps are either alists or vectors, and key-codes are
+     integers or symbols.  In XEmacs, keymaps are a special new data
+     type, and key-codes are symbols or lists of symbols.  The
+     iteration does not enter nested keymaps or inherited (parent)
+     keymaps.  You can use `the key-bindings' to access the commands
+     bound to the keys rather than the key codes, and you can add a
+     `using' clause to access both the codes and the bindings together.
+
+`for VAR being the key-seqs of KEYMAP'
+     This clause iterates over all key sequences defined by KEYMAP and
+     its nested keymaps, where VAR takes on values which are strings in
+     Emacs 18 or vectors in Emacs 19.  The strings or vectors are
+     reused for each iteration, so you must copy them if you wish to
+     keep them permanently.  You can add a `using (key-bindings ...)'
+     clause to get the command bindings as well.
+
+`for VAR being the overlays [of BUFFER] ...'
+     This clause iterates over the Emacs 19 "overlays" or XEmacs
+     "extents" of a buffer (the clause `extents' is synonymous with
+     `overlays').  Under Emacs 18, this clause iterates zero times.  If
+     the `of' term is omitted, the current buffer is used.  This clause
+     also accepts optional `from POS' and `to POS' terms, limiting the
+     clause to overlays which overlap the specified region.
+
+`for VAR being the intervals [of BUFFER] ...'
+     This clause iterates over all intervals of a buffer with constant
+     text properties.  The variable VAR will be bound to conses of
+     start and end positions, where one start position is always equal
+     to the previous end position.  The clause allows `of', `from',
+     `to', and `property' terms, where the latter term restricts the
+     search to just the specified property.  The `of' term may specify
+     either a buffer or a string.  This clause is useful only in GNU
+     Emacs 19; in other versions, all buffers and strings consist of a
+     single interval.
+
+`for VAR being the frames'
+     This clause iterates over all frames, i.e., X window system windows
+     open on Emacs files.  This clause works only under Emacs 19.  The
+     clause `screens' is a synonym for `frames'.  The frames are
+     visited in `next-frame' order starting from `selected-frame'.
+
+`for VAR being the windows [of FRAME]'
+     This clause iterates over the windows (in the Emacs sense) of the
+     current frame, or of the specified FRAME.  (In Emacs 18 there is
+     only ever one frame, and the `of' term is not allowed there.)
+
+`for VAR being the buffers'
+     This clause iterates over all buffers in Emacs.  It is equivalent
+     to `for VAR in (buffer-list)'.
+
+`for VAR = EXPR1 then EXPR2'
+     This clause does a general iteration.  The first time through the
+     loop, VAR will be bound to EXPR1.  On the second and successive
+     iterations it will be set by evaluating EXPR2 (which may refer to
+     the old value of VAR).  For example, these two loops are
+     effectively the same:
+
+          (loop for x on my-list by 'cddr do ...)
+          (loop for x = my-list then (cddr x) while x do ...)
+
+     Note that this type of `for' clause does not imply any sort of
+     terminating condition; the above example combines it with a
+     `while' clause to tell when to end the loop.
+
+     If you omit the `then' term, EXPR1 is used both for the initial
+     setting and for successive settings:
+
+          (loop for x = (random) when (> x 0) return x)
+
+     This loop keeps taking random numbers from the `(random)' function
+     until it gets a positive one, which it then returns.
+
+   If you include several `for' clauses in a row, they are treated
+sequentially (as if by `let*' and `setq').  You can instead use the
+word `and' to link the clauses, in which case they are processed in
+parallel (as if by `let' and `psetq').
+
+     (loop for x below 5 for y = nil then x collect (list x y))
+          => ((0 nil) (1 1) (2 2) (3 3) (4 4))
+     (loop for x below 5 and y = nil then x collect (list x y))
+          => ((0 nil) (1 0) (2 1) (3 2) (4 3))
+
+In the first loop, `y' is set based on the value of `x' that was just
+set by the previous clause; in the second loop, `x' and `y' are set
+simultaneously so `y' is set based on the value of `x' left over from
+the previous time through the loop.
+
+   Another feature of the `loop' macro is "destructuring", similar in
+concept to the destructuring provided by `defmacro'.  The VAR part of
+any `for' clause can be given as a list of variables instead of a
+single variable.  The values produced during loop execution must be
+lists; the values in the lists are stored in the corresponding
+variables.
+
+     (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
+          => (5 9 13)
+
+   In loop destructuring, if there are more values than variables the
+trailing values are ignored, and if there are more variables than
+values the trailing variables get the value `nil'.  If `nil' is used as
+a variable name, the corresponding values are ignored.  Destructuring
+may be nested, and dotted lists of variables like `(x . y)' are allowed.
+
+
+File: cl.info,  Node: Iteration Clauses,  Next: Accumulation Clauses,  Prev: For Clauses,  Up: Loop Facility
+
+Iteration Clauses
+-----------------
+
+Aside from `for' clauses, there are several other loop clauses that
+control the way the loop operates.  They might be used by themselves,
+or in conjunction with one or more `for' clauses.
+
+`repeat INTEGER'
+     This clause simply counts up to the specified number using an
+     internal temporary variable.  The loops
+
+          (loop repeat n do ...)
+          (loop for temp to n do ...)
+
+     are identical except that the second one forces you to choose a
+     name for a variable you aren't actually going to use.
+
+`while CONDITION'
+     This clause stops the loop when the specified condition (any Lisp
+     expression) becomes `nil'.  For example, the following two loops
+     are equivalent, except for the implicit `nil' block that surrounds
+     the second one:
+
+          (while COND FORMS...)
+          (loop while COND do FORMS...)
+
+`until CONDITION'
+     This clause stops the loop when the specified condition is true,
+     i.e., non-`nil'.
+
+`always CONDITION'
+     This clause stops the loop when the specified condition is `nil'.
+     Unlike `while', it stops the loop using `return nil' so that the
+     `finally' clauses are not executed.  If all the conditions were
+     non-`nil', the loop returns `t':
+
+          (if (loop for size in size-list always (> size 10))
+              (some-big-sizes)
+            (no-big-sizes))
+
+`never CONDITION'
+     This clause is like `always', except that the loop returns `t' if
+     any conditions were false, or `nil' otherwise.
+
+`thereis CONDITION'
+     This clause stops the loop when the specified form is non-`nil';
+     in this case, it returns that non-`nil' value.  If all the values
+     were `nil', the loop returns `nil'.
+
+
+File: cl.info,  Node: Accumulation Clauses,  Next: Other Clauses,  Prev: Iteration Clauses,  Up: Loop Facility
+
+Accumulation Clauses
+--------------------
+
+These clauses cause the loop to accumulate information about the
+specified Lisp FORM.  The accumulated result is returned from the loop
+unless overridden, say, by a `return' clause.
+
+`collect FORM'
+     This clause collects the values of FORM into a list.  Several
+     examples of `collect' appear elsewhere in this manual.
+
+     The word `collecting' is a synonym for `collect', and likewise for
+     the other accumulation clauses.
+
+`append FORM'
+     This clause collects lists of values into a result list using
+     `append'.
+
+`nconc FORM'
+     This clause collects lists of values into a result list by
+     destructively modifying the lists rather than copying them.
+
+`concat FORM'
+     This clause concatenates the values of the specified FORM into a
+     string.  (It and the following clause are extensions to standard
+     Common Lisp.)
+
+`vconcat FORM'
+     This clause concatenates the values of the specified FORM into a
+     vector.
+
+`count FORM'
+     This clause counts the number of times the specified FORM
+     evaluates to a non-`nil' value.
+
+`sum FORM'
+     This clause accumulates the sum of the values of the specified
+     FORM, which must evaluate to a number.
+
+`maximize FORM'
+     This clause accumulates the maximum value of the specified FORM,
+     which must evaluate to a number.  The return value is undefined if
+     `maximize' is executed zero times.
+
+`minimize FORM'
+     This clause accumulates the minimum value of the specified FORM.
+
+   Accumulation clauses can be followed by `into VAR' to cause the data
+to be collected into variable VAR (which is automatically `let'-bound
+during the loop) rather than an unnamed temporary variable.  Also,
+`into' accumulations do not automatically imply a return value.  The
+loop must use some explicit mechanism, such as `finally return', to
+return the accumulated result.
+
+   It is legal for several accumulation clauses of the same type to
+accumulate into the same place.  From Steele:
+
+     (loop for name in '(fred sue alice joe june)
+           for kids in '((bob ken) () () (kris sunshine) ())
+           collect name
+           append kids)
+          => (fred bob ken sue alice joe kris sunshine june)
+
+
+File: cl.info,  Node: Other Clauses,  Prev: Accumulation Clauses,  Up: Loop Facility
+
+Other Clauses
+-------------
+
+This section describes the remaining loop clauses.
+
+`with VAR = VALUE'
+     This clause binds a variable to a value around the loop, but
+     otherwise leaves the variable alone during the loop.  The following
+     loops are basically equivalent:
+
+          (loop with x = 17 do ...)
+          (let ((x 17)) (loop do ...))
+          (loop for x = 17 then x do ...)
+
+     Naturally, the variable VAR might be used for some purpose in the
+     rest of the loop.  For example:
+
+          (loop for x in my-list  with res = nil  do (push x res)
+                finally return res)
+
+     This loop inserts the elements of `my-list' at the front of a new
+     list being accumulated in `res', then returns the list `res' at
+     the end of the loop.  The effect is similar to that of a `collect'
+     clause, but the list gets reversed by virtue of the fact that
+     elements are being pushed onto the front of `res' rather than the
+     end.
+
+     If you omit the `=' term, the variable is initialized to `nil'.
+     (Thus the `= nil' in the above example is unnecessary.)
+
+     Bindings made by `with' are sequential by default, as if by
+     `let*'.  Just like `for' clauses, `with' clauses can be linked
+     with `and' to cause the bindings to be made by `let' instead.
+
+`if CONDITION CLAUSE'
+     This clause executes the following loop clause only if the
+     specified condition is true.  The following CLAUSE should be an
+     accumulation, `do', `return', `if', or `unless' clause.  Several
+     clauses may be linked by separating them with `and'.  These
+     clauses may be followed by `else' and a clause or clauses to
+     execute if the condition was false.  The whole construct may
+     optionally be followed by the word `end' (which may be used to
+     disambiguate an `else' or `and' in a nested `if').
+
+     The actual non-`nil' value of the condition form is available by
+     the name `it' in the "then" part.  For example:
+
+          (setq funny-numbers '(6 13 -1))
+               => (6 13 -1)
+          (loop for x below 10
+                if (oddp x)
+                  collect x into odds
+                  and if (memq x funny-numbers) return (cdr it) end
+                else
+                  collect x into evens
+                finally return (vector odds evens))
+               => [(1 3 5 7 9) (0 2 4 6 8)]
+          (setq funny-numbers '(6 7 13 -1))
+               => (6 7 13 -1)
+          (loop <same thing again>)
+               => (13 -1)
+
+     Note the use of `and' to put two clauses into the "then" part, one
+     of which is itself an `if' clause.  Note also that `end', while
+     normally optional, was necessary here to make it clear that the
+     `else' refers to the outermost `if' clause.  In the first case,
+     the loop returns a vector of lists of the odd and even values of
+     X.  In the second case, the odd number 7 is one of the
+     `funny-numbers' so the loop returns early; the actual returned
+     value is based on the result of the `memq' call.
+
+`when CONDITION CLAUSE'
+     This clause is just a synonym for `if'.
+
+`unless CONDITION CLAUSE'
+     The `unless' clause is just like `if' except that the sense of the
+     condition is reversed.
+
+`named NAME'
+     This clause gives a name other than `nil' to the implicit block
+     surrounding the loop.  The NAME is the symbol to be used as the
+     block name.
+
+`initially [do] FORMS...'
+     This keyword introduces one or more Lisp forms which will be
+     executed before the loop itself begins (but after any variables
+     requested by `for' or `with' have been bound to their initial
+     values).  `initially' clauses can appear anywhere; if there are
+     several, they are executed in the order they appear in the loop.
+     The keyword `do' is optional.
+
+`finally [do] FORMS...'
+     This introduces Lisp forms which will be executed after the loop
+     finishes (say, on request of a `for' or `while').  `initially' and
+     `finally' clauses may appear anywhere in the loop construct, but
+     they are executed (in the specified order) at the beginning or
+     end, respectively, of the loop.
+
+`finally return FORM'
+     This says that FORM should be executed after the loop is done to
+     obtain a return value.  (Without this, or some other clause like
+     `collect' or `return', the loop will simply return `nil'.)
+     Variables bound by `for', `with', or `into' will still contain
+     their final values when FORM is executed.
+
+`do FORMS...'
+     The word `do' may be followed by any number of Lisp expressions
+     which are executed as an implicit `progn' in the body of the loop.
+     Many of the examples in this section illustrate the use of `do'.
+
+`return FORM'
+     This clause causes the loop to return immediately.  The following
+     Lisp form is evaluated to give the return value of the `loop'
+     form.  The `finally' clauses, if any, are not executed.  Of
+     course, `return' is generally used inside an `if' or `unless', as
+     its use in a top-level loop clause would mean the loop would never
+     get to "loop" more than once.
+
+     The clause `return FORM' is equivalent to `do (return FORM)' (or
+     `return-from' if the loop was named).  The `return' clause is
+     implemented a bit more efficiently, though.
+
+   While there is no high-level way to add user extensions to `loop'
+(comparable to `defsetf' for `setf', say), this package does offer two
+properties called `cl-loop-handler' and `cl-loop-for-handler' which are
+functions to be called when a given symbol is encountered as a
+top-level loop clause or `for' clause, respectively.  Consult the
+source code in file `cl-macs.el' for details.
+
+   This package's `loop' macro is compatible with that of Common Lisp,
+except that a few features are not implemented:  `loop-finish' and
+data-type specifiers.  Naturally, the `for' clauses which iterate over
+keymaps, overlays, intervals, frames, windows, and buffers are
+Emacs-specific extensions.
+
+
+File: cl.info,  Node: Multiple Values,  Prev: Loop Facility,  Up: Control Structure
+
+Multiple Values
+===============
+
+Common Lisp functions can return zero or more results.  Emacs Lisp
+functions, by contrast, always return exactly one result.  This package
+makes no attempt to emulate Common Lisp multiple return values; Emacs
+versions of Common Lisp functions that return more than one value
+either return just the first value (as in `compiler-macroexpand') or
+return a list of values (as in `get-setf-method').  This package _does_
+define placeholders for the Common Lisp functions that work with
+multiple values, but in Emacs Lisp these functions simply operate on
+lists instead.  The `values' form, for example, is a synonym for `list'
+in Emacs.
+
+ - Special Form: multiple-value-bind (var...) values-form forms...
+     This form evaluates VALUES-FORM, which must return a list of
+     values.  It then binds the VARs to these respective values, as if
+     by `let', and then executes the body FORMS.  If there are more
+     VARs than values, the extra VARs are bound to `nil'.  If there are
+     fewer VARs than values, the excess values are ignored.
+
+ - Special Form: multiple-value-setq (var...) form
+     This form evaluates FORM, which must return a list of values.  It
+     then sets the VARs to these respective values, as if by `setq'.
+     Extra VARs or values are treated the same as in
+     `multiple-value-bind'.
+
+   The older Quiroz package attempted a more faithful (but still
+imperfect) emulation of Common Lisp multiple values.  The old method
+"usually" simulated true multiple values quite well, but under certain
+circumstances would leave spurious return values in memory where a
+later, unrelated `multiple-value-bind' form would see them.
+
+   Since a perfect emulation is not feasible in Emacs Lisp, this
+package opts to keep it as simple and predictable as possible.
+
+
+File: cl.info,  Node: Macros,  Next: Declarations,  Prev: Control Structure,  Up: Top
+
+Macros
+******
+
+This package implements the various Common Lisp features of `defmacro',
+such as destructuring, `&environment', and `&body'.  Top-level `&whole'
+is not implemented for `defmacro' due to technical difficulties.  *Note
+Argument Lists::.
+
+   Destructuring is made available to the user by way of the following
+macro:
+
+ - Special Form: destructuring-bind arglist expr forms...
+     This macro expands to code which executes FORMS, with the
+     variables in ARGLIST bound to the list of values returned by EXPR.
+     The ARGLIST can include all the features allowed for `defmacro'
+     argument lists, including destructuring.  (The `&environment'
+     keyword is not allowed.)  The macro expansion will signal an error
+     if EXPR returns a list of the wrong number of arguments or with
+     incorrect keyword arguments.
+
+   This package also includes the Common Lisp `define-compiler-macro'
+facility, which allows you to define compile-time expansions and
+optimizations for your functions.
+
+ - Special Form: define-compiler-macro name arglist forms...
+     This form is similar to `defmacro', except that it only expands
+     calls to NAME at compile-time; calls processed by the Lisp
+     interpreter are not expanded, nor are they expanded by the
+     `macroexpand' function.
+
+     The argument list may begin with a `&whole' keyword and a
+     variable.  This variable is bound to the macro-call form itself,
+     i.e., to a list of the form `(NAME ARGS...)'.  If the macro
+     expander returns this form unchanged, then the compiler treats it
+     as a normal function call.  This allows compiler macros to work as
+     optimizers for special cases of a function, leaving complicated
+     cases alone.
+
+     For example, here is a simplified version of a definition that
+     appears as a standard part of this package:
+
+          (define-compiler-macro member* (&whole form a list &rest keys)
+            (if (and (null keys)
+                     (eq (car-safe a) 'quote)
+                     (not (floatp-safe (cadr a))))
+                (list 'memq a list)
+              form))
+
+     This definition causes `(member* A LIST)' to change to a call to
+     the faster `memq' in the common case where A is a
+     non-floating-point constant; if A is anything else, or if there
+     are any keyword arguments in the call, then the original `member*'
+     call is left intact.  (The actual compiler macro for `member*'
+     optimizes a number of other cases, including common `:test'
+     predicates.)
+
+ - Function: compiler-macroexpand form
+     This function is analogous to `macroexpand', except that it
+     expands compiler macros rather than regular macros.  It returns
+     FORM unchanged if it is not a call to a function for which a
+     compiler macro has been defined, or if that compiler macro decided
+     to punt by returning its `&whole' argument.  Like `macroexpand',
+     it expands repeatedly until it reaches a form for which no further
+     expansion is possible.
+
+   *Note Macro Bindings::, for descriptions of the `macrolet' and
+`symbol-macrolet' forms for making "local" macro definitions.
+
+
+File: cl.info,  Node: Declarations,  Next: Symbols,  Prev: Macros,  Up: Top
+
+Declarations
+************
+
+Common Lisp includes a complex and powerful "declaration" mechanism
+that allows you to give the compiler special hints about the types of
+data that will be stored in particular variables, and about the ways
+those variables and functions will be used.  This package defines
+versions of all the Common Lisp declaration forms: `declare',
+`locally', `proclaim', `declaim', and `the'.
+
+   Most of the Common Lisp declarations are not currently useful in
+Emacs Lisp, as the byte-code system provides little opportunity to
+benefit from type information, and `special' declarations are redundant
+in a fully dynamically-scoped Lisp.  A few declarations are meaningful
+when the optimizing Emacs 19 byte compiler is being used, however.
+Under the earlier non-optimizing compiler, these declarations will
+effectively be ignored.
+
+ - Function: proclaim decl-spec
+     This function records a "global" declaration specified by
+     DECL-SPEC.  Since `proclaim' is a function, DECL-SPEC is evaluated
+     and thus should normally be quoted.
+
+ - Special Form: declaim decl-specs...
+     This macro is like `proclaim', except that it takes any number of
+     DECL-SPEC arguments, and the arguments are unevaluated and
+     unquoted.  The `declaim' macro also puts an `(eval-when (compile
+     load eval) ...)' around the declarations so that they will be
+     registered at compile-time as well as at run-time.  (This is vital,
+     since normally the declarations are meant to influence the way the
+     compiler treats the rest of the file that contains the `declaim'
+     form.)
+
+ - Special Form: declare decl-specs...
+     This macro is used to make declarations within functions and other
+     code.  Common Lisp allows declarations in various locations,
+     generally at the beginning of any of the many "implicit `progn's"
+     throughout Lisp syntax, such as function bodies, `let' bodies,
+     etc.  Currently the only declaration understood by `declare' is
+     `special'.
+
+ - Special Form: locally declarations... forms...
+     In this package, `locally' is no different from `progn'.
+
+ - Special Form: the type form
+     Type information provided by `the' is ignored in this package; in
+     other words, `(the TYPE FORM)' is equivalent to FORM.  Future
+     versions of the optimizing byte-compiler may make use of this
+     information.
+
+     For example, `mapcar' can map over both lists and arrays.  It is
+     hard for the compiler to expand `mapcar' into an in-line loop
+     unless it knows whether the sequence will be a list or an array
+     ahead of time.  With `(mapcar 'car (the vector foo))', a future
+     compiler would have enough information to expand the loop in-line.
+     For now, Emacs Lisp will treat the above code as exactly equivalent
+     to `(mapcar 'car foo)'.
+
+   Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a
+list beginning with a symbol that says what kind of declaration it is.
+This package currently understands `special', `inline', `notinline',
+`optimize', and `warn' declarations.  (The `warn' declaration is an
+extension of standard Common Lisp.)  Other Common Lisp declarations,
+such as `type' and `ftype', are silently ignored.
+
+`special'
+     Since all variables in Emacs Lisp are "special" (in the Common
+     Lisp sense), `special' declarations are only advisory.  They
+     simply tell the optimizing byte compiler that the specified
+     variables are intentionally being referred to without being bound
+     in the body of the function.  The compiler normally emits warnings
+     for such references, since they could be typographical errors for
+     references to local variables.
+
+     The declaration `(declare (special VAR1 VAR2))' is equivalent to
+     `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to
+     nothing at all in older compilers (which do not warn for non-local
+     references).
+
+     In top-level contexts, it is generally better to write `(defvar
+     VAR)' than `(declaim (special VAR))', since `defvar' makes your
+     intentions clearer.  But the older byte compilers can not handle
+     `defvar's appearing inside of functions, while `(declare (special
+     VAR))' takes care to work correctly with all compilers.
+
+`inline'
+     The `inline' DECL-SPEC lists one or more functions whose bodies
+     should be expanded "in-line" into calling functions whenever the
+     compiler is able to arrange for it.  For example, the Common Lisp
+     function `cadr' is declared `inline' by this package so that the
+     form `(cadr X)' will expand directly into `(car (cdr X))' when it
+     is called in user functions, for a savings of one (relatively
+     expensive) function call.
+
+     The following declarations are all equivalent.  Note that the
+     `defsubst' form is a convenient way to define a function and
+     declare it inline all at once, but it is available only in Emacs
+     19.
+
+          (declaim (inline foo bar))
+          (eval-when (compile load eval) (proclaim '(inline foo bar)))
+          (proclaim-inline foo bar)   ; XEmacs only
+          (defsubst foo (...) ...)    ; instead of defun; Emacs 19 only
+
+     *Please note:*  This declaration remains in effect after the
+     containing source file is done.  It is correct to use it to
+     request that a function you have defined should be inlined, but it
+     is impolite to use it to request inlining of an external function.
+
+     In Common Lisp, it is possible to use `(declare (inline ...))'
+     before a particular call to a function to cause just that call to
+     be inlined; the current byte compilers provide no way to implement
+     this, so `(declare (inline ...))' is currently ignored by this
+     package.
+
+`notinline'
+     The `notinline' declaration lists functions which should not be
+     inlined after all; it cancels a previous `inline' declaration.
+
+`optimize'
+     This declaration controls how much optimization is performed by
+     the compiler.  Naturally, it is ignored by the earlier
+     non-optimizing compilers.
+
+     The word `optimize' is followed by any number of lists like
+     `(speed 3)' or `(safety 2)'.  Common Lisp defines several
+     optimization "qualities"; this package ignores all but `speed' and
+     `safety'.  The value of a quality should be an integer from 0 to
+     3, with 0 meaning "unimportant" and 3 meaning "very important."
+     The default level for both qualities is 1.
+
+     In this package, with the Emacs 19 optimizing compiler, the
+     `speed' quality is tied to the `byte-compile-optimize' flag, which
+     is set to `nil' for `(speed 0)' and to `t' for higher settings;
+     and the `safety' quality is tied to the
+     `byte-compile-delete-errors' flag, which is set to `t' for
+     `(safety 3)' and to `nil' for all lower settings.  (The latter
+     flag controls whether the compiler is allowed to optimize out code
+     whose only side-effect could be to signal an error, e.g.,
+     rewriting `(progn foo bar)' to `bar' when it is not known whether
+     `foo' will be bound at run-time.)
+
+     Note that even compiling with `(safety 0)', the Emacs byte-code
+     system provides sufficient checking to prevent real harm from
+     being done.  For example, barring serious bugs in Emacs itself,
+     Emacs will not crash with a segmentation fault just because of an
+     error in a fully-optimized Lisp program.
+
+     The `optimize' declaration is normally used in a top-level
+     `proclaim' or `declaim' in a file; Common Lisp allows it to be
+     used with `declare' to set the level of optimization locally for a
+     given form, but this will not work correctly with the current
+     version of the optimizing compiler.  (The `declare' will set the
+     new optimization level, but that level will not automatically be
+     unset after the enclosing form is done.)
+
+`warn'
+     This declaration controls what sorts of warnings are generated by
+     the byte compiler.  Again, only the optimizing compiler generates
+     warnings.  The word `warn' is followed by any number of "warning
+     qualities," similar in form to optimization qualities.  The
+     currently supported warning types are `redefine', `callargs',
+     `unresolved', and `free-vars'; in the current system, a value of 0
+     will disable these warnings and any higher value will enable them.
+     See the documentation for the optimizing byte compiler for details.
+
+
+File: cl.info,  Node: Symbols,  Next: Numbers,  Prev: Declarations,  Up: Top
+
+Symbols
+*******
+
+This package defines several symbol-related features that were missing
+from Emacs Lisp.
+
+* Menu:
+
+* Property Lists::       `getf', `remf'
+* Creating Symbols::     `gensym', `gentemp'
+
+
+File: cl.info,  Node: Property Lists,  Next: Creating Symbols,  Prev: Symbols,  Up: Symbols
+
+Property Lists
+==============
+
+These functions augment the standard Emacs Lisp functions `get' and
+`put' for operating on properties attached to objects.  There are also
+functions for working with property lists as first-class data
+structures not attached to particular objects.
+
+ - Function: getf place property &optional default
+     This function scans the list PLACE as if it were a property list,
+     i.e., a list of alternating property names and values.  If an
+     even-numbered element of PLACE is found which is `eq' to PROPERTY,
+     the following odd-numbered element is returned.  Otherwise,
+     DEFAULT is returned (or `nil' if no default is given).
+
+     In particular,
+
+          (get sym prop)  ==  (getf (symbol-plist sym) prop)
+
+     It is legal to use `getf' as a `setf' place, in which case its
+     PLACE argument must itself be a legal `setf' place.  The DEFAULT
+     argument, if any, is ignored in this context.  The effect is to
+     change (via `setcar') the value cell in the list that corresponds
+     to PROPERTY, or to cons a new property-value pair onto the list if
+     the property is not yet present.
+
+          (put sym prop val)  ==  (setf (getf (symbol-plist sym) prop) val)
+
+     The `get' function is also `setf'-able.  The fact that `default'
+     is ignored can sometimes be useful:
+
+          (incf (get 'foo 'usage-count 0))
+
+     Here, symbol `foo''s `usage-count' property is incremented if it
+     exists, or set to 1 (an incremented 0) otherwise.
+
+     When not used as a `setf' form, `getf' is just a regular function
+     and its PLACE argument can actually be any Lisp expression.
+
+ - Special Form: remf place property
+     This macro removes the property-value pair for PROPERTY from the
+     property list stored at PLACE, which is any `setf'-able place
+     expression.  It returns true if the property was found.  Note that
+     if PROPERTY happens to be first on the list, this will effectively
+     do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this
+     simply uses `setcdr' to splice out the property and value cells.
+
+
+File: cl.info,  Node: Creating Symbols,  Prev: Property Lists,  Up: Symbols
+
+Creating Symbols
+================
+
+These functions create unique symbols, typically for use as temporary
+variables.
+
+ - Function: gensym &optional x
+     This function creates a new, uninterned symbol (using
+     `make-symbol') with a unique name.  (The name of an uninterned
+     symbol is relevant only if the symbol is printed.)  By default,
+     the name is generated from an increasing sequence of numbers,
+     `G1000', `G1001', `G1002', etc.  If the optional argument X is a
+     string, that string is used as a prefix instead of `G'.
+     Uninterned symbols are used in macro expansions for temporary
+     variables, to ensure that their names will not conflict with
+     "real" variables in the user's code.
+
+ - Variable: *gensym-counter*
+     This variable holds the counter used to generate `gensym' names.
+     It is incremented after each use by `gensym'.  In Common Lisp this
+     is initialized with 0, but this package initializes it with a
+     random (time-dependent) value to avoid trouble when two files that
+     each used `gensym' in their compilation are loaded together.
+
+     *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains
+     uninterned even after being dumped to bytecode.  Older versions of
+     Emacs didn't distinguish the printed representation of interned
+     and uninterned symbols, so their names had to be treated more
+     carefully.
+
+ - Function: gentemp &optional x
+     This function is like `gensym', except that it produces a new
+     _interned_ symbol.  If the symbol that is generated already
+     exists, the function keeps incrementing the counter and trying
+     again until a new symbol is generated.
+
+   The Quiroz `cl.el' package also defined a `defkeyword' form for
+creating self-quoting keyword symbols.  This package automatically
+creates all keywords that are called for by `&key' argument specifiers,
+and discourages the use of keywords as data unrelated to keyword
+arguments, so the `defkeyword' form has been discontinued.
+
+
+File: cl.info,  Node: Numbers,  Next: Sequences,  Prev: Symbols,  Up: Top
+
+Numbers
+*******
+
+This section defines a few simple Common Lisp operations on numbers
+which were left out of Emacs Lisp.
+
+* Menu:
+
+* Predicates on Numbers::       `plusp', `oddp', `floatp-safe', etc.
+* Numerical Functions::         `abs', `expt', `floor*', etc.
+* Random Numbers::              `random*', `make-random-state'
+* Implementation Parameters::   `most-positive-fixnum', `most-positive-float'
+
+
+File: cl.info,  Node: Predicates on Numbers,  Next: Numerical Functions,  Prev: Numbers,  Up: Numbers
+
+Predicates on Numbers
+=====================
+
+These functions return `t' if the specified condition is true of the
+numerical argument, or `nil' otherwise.
+
+ - Function: plusp number
+     This predicate tests whether NUMBER is positive.  It is an error
+     if the argument is not a number.
+
+ - Function: minusp number
+     This predicate tests whether NUMBER is negative.  It is an error
+     if the argument is not a number.
+
+ - Function: oddp integer
+     This predicate tests whether INTEGER is odd.  It is an error if
+     the argument is not an integer.
+
+ - Function: evenp integer
+     This predicate tests whether INTEGER is even.  It is an error if
+     the argument is not an integer.
+
+ - Function: floatp-safe object
+     This predicate tests whether OBJECT is a floating-point number.
+     On systems that support floating-point, this is equivalent to
+     `floatp'.  On other systems, this always returns `nil'.
+
+
+File: cl.info,  Node: Numerical Functions,  Next: Random Numbers,  Prev: Predicates on Numbers,  Up: Numbers
+
+Numerical Functions
+===================
+
+These functions perform various arithmetic operations on numbers.
+
+ - Function: abs number
+     This function returns the absolute value of NUMBER.  (Newer
+     versions of Emacs provide this as a built-in function; this package
+     defines `abs' only for Emacs 18 versions which don't provide it as
+     a primitive.)
+
+ - Function: expt base power
+     This function returns BASE raised to the power of NUMBER.  (Newer
+     versions of Emacs provide this as a built-in function; this
+     package defines `expt' only for Emacs 18 versions which don't
+     provide it as a primitive.)
+
+ - Function: gcd &rest integers
+     This function returns the Greatest Common Divisor of the arguments.
+     For one argument, it returns the absolute value of that argument.
+     For zero arguments, it returns zero.
+
+ - Function: lcm &rest integers
+     This function returns the Least Common Multiple of the arguments.
+     For one argument, it returns the absolute value of that argument.
+     For zero arguments, it returns one.
+
+ - Function: isqrt integer
+     This function computes the "integer square root" of its integer
+     argument, i.e., the greatest integer less than or equal to the true
+     square root of the argument.
+
+ - Function: floor* number &optional divisor
+     This function implements the Common Lisp `floor' function.  It is
+     called `floor*' to avoid name conflicts with the simpler `floor'
+     function built-in to Emacs 19.
+
+     With one argument, `floor*' returns a list of two numbers: The
+     argument rounded down (toward minus infinity) to an integer, and
+     the "remainder" which would have to be added back to the first
+     return value to yield the argument again.  If the argument is an
+     integer X, the result is always the list `(X 0)'.  If the argument
+     is an Emacs 19 floating-point number, the first result is a Lisp
+     integer and the second is a Lisp float between 0 (inclusive) and 1
+     (exclusive).
+
+     With two arguments, `floor*' divides NUMBER by DIVISOR, and
+     returns the floor of the quotient and the corresponding remainder
+     as a list of two numbers.  If `(floor* X Y)' returns `(Q R)', then
+     `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive).
+     Also, note that `(floor* X)' is exactly equivalent to `(floor* X
+     1)'.
+
+     This function is entirely compatible with Common Lisp's `floor'
+     function, except that it returns the two results in a list since
+     Emacs Lisp does not support multiple-valued functions.
+
+ - Function: ceiling* number &optional divisor
+     This function implements the Common Lisp `ceiling' function, which
+     is analogous to `floor' except that it rounds the argument or
+     quotient of the arguments up toward plus infinity.  The remainder
+     will be between 0 and minus R.
+
+ - Function: truncate* number &optional divisor
+     This function implements the Common Lisp `truncate' function,
+     which is analogous to `floor' except that it rounds the argument
+     or quotient of the arguments toward zero.  Thus it is equivalent
+     to `floor*' if the argument or quotient is positive, or to
+     `ceiling*' otherwise.  The remainder has the same sign as NUMBER.
+
+ - Function: round* number &optional divisor
+     This function implements the Common Lisp `round' function, which
+     is analogous to `floor' except that it rounds the argument or
+     quotient of the arguments to the nearest integer.  In the case of
+     a tie (the argument or quotient is exactly halfway between two
+     integers), it rounds to the even integer.
+
+ - Function: mod* number divisor
+     This function returns the same value as the second return value of
+     `floor'.
+
+ - Function: rem* number divisor
+     This function returns the same value as the second return value of
+     `truncate'.
+
+   These definitions are compatible with those in the Quiroz `cl.el'
+package, except that this package appends `*' to certain function names
+to avoid conflicts with existing Emacs 19 functions, and that the
+mechanism for returning multiple values is different.
+
+
+File: cl.info,  Node: Random Numbers,  Next: Implementation Parameters,  Prev: Numerical Functions,  Up: Numbers
+
+Random Numbers
+==============
+
+This package also provides an implementation of the Common Lisp random
+number generator.  It uses its own additive-congruential algorithm,
+which is much more likely to give statistically clean random numbers
+than the simple generators supplied by many operating systems.
+
+ - Function: random* number &optional state
+     This function returns a random nonnegative number less than
+     NUMBER, and of the same type (either integer or floating-point).
+     The STATE argument should be a `random-state' object which holds
+     the state of the random number generator.  The function modifies
+     this state object as a side effect.  If STATE is omitted, it
+     defaults to the variable `*random-state*', which contains a
+     pre-initialized `random-state' object.
+
+ - Variable: *random-state*
+     This variable contains the system "default" `random-state' object,
+     used for calls to `random*' that do not specify an alternative
+     state object.  Since any number of programs in the Emacs process
+     may be accessing `*random-state*' in interleaved fashion, the
+     sequence generated from this variable will be irreproducible for
+     all intents and purposes.
+
+ - Function: make-random-state &optional state
+     This function creates or copies a `random-state' object.  If STATE
+     is omitted or `nil', it returns a new copy of `*random-state*'.
+     This is a copy in the sense that future sequences of calls to
+     `(random* N)' and `(random* N S)' (where S is the new random-state
+     object) will return identical sequences of random numbers.
+
+     If STATE is a `random-state' object, this function returns a copy
+     of that object.  If STATE is `t', this function returns a new
+     `random-state' object seeded from the date and time.  As an
+     extension to Common Lisp, STATE may also be an integer in which
+     case the new object is seeded from that integer; each different
+     integer seed will result in a completely different sequence of
+     random numbers.
+
+     It is legal to print a `random-state' object to a buffer or file
+     and later read it back with `read'.  If a program wishes to use a
+     sequence of pseudo-random numbers which can be reproduced later
+     for debugging, it can call `(make-random-state t)' to get a new
+     sequence, then print this sequence to a file.  When the program is
+     later rerun, it can read the original run's random-state from the
+     file.
+
+ - Function: random-state-p object
+     This predicate returns `t' if OBJECT is a `random-state' object,
+     or `nil' otherwise.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-4'
Index: ././info/cl.info-4
--- ././info/cl.info-4	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-4	Thu May 17 23:26:51 2001
@@ -0,0 +1,851 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: Implementation Parameters,  Prev: Random Numbers,  Up: Numbers
+
+Implementation Parameters
+=========================
+
+This package defines several useful constants having to with numbers.
+
+ - Variable: most-positive-fixnum
+     This constant equals the largest value a Lisp integer can hold.
+     It is typically `2^23-1' or `2^25-1'.
+
+ - Variable: most-negative-fixnum
+     This constant equals the smallest (most negative) value a Lisp
+     integer can hold.
+
+   The following parameters have to do with floating-point numbers.
+This package determines their values by exercising the computer's
+floating-point arithmetic in various ways.  Because this operation
+might be slow, the code for initializing them is kept in a separate
+function that must be called before the parameters can be used.
+
+ - Function: cl-float-limits
+     This function makes sure that the Common Lisp floating-point
+     parameters like `most-positive-float' have been initialized.
+     Until it is called, these parameters will be `nil'.  If this
+     version of Emacs does not support floats (e.g., most versions of
+     Emacs 18), the parameters will remain `nil'.  If the parameters
+     have already been initialized, the function returns immediately.
+
+     The algorithm makes assumptions that will be valid for most modern
+     machines, but will fail if the machine's arithmetic is extremely
+     unusual, e.g., decimal.
+
+   Since true Common Lisp supports up to four different floating-point
+precisions, it has families of constants like
+`most-positive-single-float', `most-positive-double-float',
+`most-positive-long-float', and so on.  Emacs has only one
+floating-point precision, so this package omits the precision word from
+the constants' names.
+
+ - Variable: most-positive-float
+     This constant equals the largest value a Lisp float can hold.  For
+     those systems whose arithmetic supports infinities, this is the
+     largest _finite_ value.  For IEEE machines, the value is
+     approximately `1.79e+308'.
+
+ - Variable: most-negative-float
+     This constant equals the most-negative value a Lisp float can hold.
+     (It is assumed to be equal to `(- most-positive-float)'.)
+
+ - Variable: least-positive-float
+     This constant equals the smallest Lisp float value greater than
+     zero.  For IEEE machines, it is about `4.94e-324' if denormals are
+     supported or `2.22e-308' if not.
+
+ - Variable: least-positive-normalized-float
+     This constant equals the smallest _normalized_ Lisp float greater
+     than zero, i.e., the smallest value for which IEEE denormalization
+     will not result in a loss of precision.  For IEEE machines, this
+     value is about `2.22e-308'.  For machines that do not support the
+     concept of denormalization and gradual underflow, this constant
+     will always equal `least-positive-float'.
+
+ - Variable: least-negative-float
+     This constant is the negative counterpart of
+     `least-positive-float'.
+
+ - Variable: least-negative-normalized-float
+     This constant is the negative counterpart of
+     `least-positive-normalized-float'.
+
+ - Variable: float-epsilon
+     This constant is the smallest positive Lisp float that can be added
+     to 1.0 to produce a distinct value.  Adding a smaller number to 1.0
+     will yield 1.0 again due to roundoff.  For IEEE machines, epsilon
+     is about `2.22e-16'.
+
+ - Variable: float-negative-epsilon
+     This is the smallest positive value that can be subtracted from
+     1.0 to produce a distinct value.  For IEEE machines, it is about
+     `1.11e-16'.
+
+
+File: cl.info,  Node: Sequences,  Next: Lists,  Prev: Numbers,  Up: Top
+
+Sequences
+*********
+
+Common Lisp defines a number of functions that operate on "sequences",
+which are either lists, strings, or vectors.  Emacs Lisp includes a few
+of these, notably `elt' and `length'; this package defines most of the
+rest.
+
+* Menu:
+
+* Sequence Basics::          Arguments shared by all sequence functions
+* Mapping over Sequences::   `mapcar*', `mapcan', `map', `every', etc.
+* Sequence Functions::       `subseq', `remove*', `substitute', etc.
+* Searching Sequences::      `find', `position', `count', `search', etc.
+* Sorting Sequences::        `sort*', `stable-sort', `merge'
+
+
+File: cl.info,  Node: Sequence Basics,  Next: Mapping over Sequences,  Prev: Sequences,  Up: Sequences
+
+Sequence Basics
+===============
+
+Many of the sequence functions take keyword arguments; *note Argument
+Lists::.  All keyword arguments are optional and, if specified, may
+appear in any order.
+
+   The `:key' argument should be passed either `nil', or a function of
+one argument.  This key function is used as a filter through which the
+elements of the sequence are seen; for example, `(find x y :key 'car)'
+is similar to `(assoc* x y)': It searches for an element of the list
+whose `car' equals `x', rather than for an element which equals `x'
+itself.  If `:key' is omitted or `nil', the filter is effectively the
+identity function.
+
+   The `:test' and `:test-not' arguments should be either `nil', or
+functions of two arguments.  The test function is used to compare two
+sequence elements, or to compare a search value with sequence elements.
+(The two values are passed to the test function in the same order as
+the original sequence function arguments from which they are derived,
+or, if they both come from the same sequence, in the same order as they
+appear in that sequence.)  The `:test' argument specifies a function
+which must return true (non-`nil') to indicate a match; instead, you
+may use `:test-not' to give a function which returns _false_ to
+indicate a match.  The default test function is `:test 'eql'.
+
+   Many functions which take ITEM and `:test' or `:test-not' arguments
+also come in `-if' and `-if-not' varieties, where a PREDICATE function
+is passed instead of ITEM, and sequence elements match if the predicate
+returns true on them (or false in the case of `-if-not').  For example:
+
+     (remove* 0 seq :test '=)  ==  (remove-if 'zerop seq)
+
+to remove all zeros from sequence `seq'.
+
+   Some operations can work on a subsequence of the argument sequence;
+these function take `:start' and `:end' arguments which default to zero
+and the length of the sequence, respectively.  Only elements between
+START (inclusive) and END (exclusive) are affected by the operation.
+The END argument may be passed `nil' to signify the length of the
+sequence; otherwise, both START and END must be integers, with `0 <=
+START <= END <= (length SEQ)'.  If the function takes two sequence
+arguments, the limits are defined by keywords `:start1' and `:end1' for
+the first, and `:start2' and `:end2' for the second.
+
+   A few functions accept a `:from-end' argument, which, if non-`nil',
+causes the operation to go from right-to-left through the sequence
+instead of left-to-right, and a `:count' argument, which specifies an
+integer maximum number of elements to be removed or otherwise processed.
+
+   The sequence functions make no guarantees about the order in which
+the `:test', `:test-not', and `:key' functions are called on various
+elements.  Therefore, it is a bad idea to depend on side effects of
+these functions.  For example, `:from-end' may cause the sequence to be
+scanned actually in reverse, or it may be scanned forwards but
+computing a result "as if" it were scanned backwards.  (Some functions,
+like `mapcar*' and `every', _do_ specify exactly the order in which the
+function is called so side effects are perfectly acceptable in those
+cases.)
+
+   Strings in GNU Emacs 19 may contain "text properties" as well as
+character data.  Except as noted, it is undefined whether or not text
+properties are preserved by sequence functions.  For example, `(remove*
+?A STR)' may or may not preserve the properties of the characters
+copied from STR into the result.
+
+
+File: cl.info,  Node: Mapping over Sequences,  Next: Sequence Functions,  Prev: Sequence Basics,  Up: Sequences
+
+Mapping over Sequences
+======================
+
+These functions "map" the function you specify over the elements of
+lists or arrays.  They are all variations on the theme of the built-in
+function `mapcar'.
+
+ - Function: mapcar* function seq &rest more-seqs
+     This function calls FUNCTION on successive parallel sets of
+     elements from its argument sequences.  Given a single SEQ argument
+     it is equivalent to `mapcar'; given N sequences, it calls the
+     function with the first elements of each of the sequences as the N
+     arguments to yield the first element of the result list, then with
+     the second elements, and so on.  The mapping stops as soon as the
+     shortest sequence runs out.  The argument sequences may be any
+     mixture of lists, strings, and vectors; the return sequence is
+     always a list.
+
+     Common Lisp's `mapcar' accepts multiple arguments but works only
+     on lists; Emacs Lisp's `mapcar' accepts a single sequence
+     argument.  This package's `mapcar*' works as a compatible superset
+     of both.
+
+ - Function: map result-type function seq &rest more-seqs
+     This function maps FUNCTION over the argument sequences, just like
+     `mapcar*', but it returns a sequence of type RESULT-TYPE rather
+     than a list.  RESULT-TYPE must be one of the following symbols:
+     `vector', `string', `list' (in which case the effect is the same
+     as for `mapcar*'), or `nil' (in which case the results are thrown
+     away and `map' returns `nil').
+
+ - Function: maplist function list &rest more-lists
+     This function calls FUNCTION on each of its argument lists, then
+     on the `cdr's of those lists, and so on, until the shortest list
+     runs out.  The results are returned in the form of a list.  Thus,
+     `maplist' is like `mapcar*' except that it passes in the list
+     pointers themselves rather than the `car's of the advancing
+     pointers.
+
+ - Function: mapc function seq &rest more-seqs
+     This function is like `mapcar*', except that the values returned
+     by FUNCTION are ignored and thrown away rather than being
+     collected into a list.  The return value of `mapc' is SEQ, the
+     first sequence.
+
+ - Function: mapl function list &rest more-lists
+     This function is like `maplist', except that it throws away the
+     values returned by FUNCTION.
+
+ - Function: mapcan function seq &rest more-seqs
+     This function is like `mapcar*', except that it concatenates the
+     return values (which must be lists) using `nconc', rather than
+     simply collecting them into a list.
+
+ - Function: mapcon function list &rest more-lists
+     This function is like `maplist', except that it concatenates the
+     return values using `nconc'.
+
+ - Function: some predicate seq &rest more-seqs
+     This function calls PREDICATE on each element of SEQ in turn; if
+     PREDICATE returns a non-`nil' value, `some' returns that value,
+     otherwise it returns `nil'.  Given several sequence arguments, it
+     steps through the sequences in parallel until the shortest one
+     runs out, just as in `mapcar*'.  You can rely on the left-to-right
+     order in which the elements are visited, and on the fact that
+     mapping stops immediately as soon as PREDICATE returns non-`nil'.
+
+ - Function: every predicate seq &rest more-seqs
+     This function calls PREDICATE on each element of the sequence(s)
+     in turn; it returns `nil' as soon as PREDICATE returns `nil' for
+     any element, or `t' if the predicate was true for all elements.
+
+ - Function: notany predicate seq &rest more-seqs
+     This function calls PREDICATE on each element of the sequence(s)
+     in turn; it returns `nil' as soon as PREDICATE returns a non-`nil'
+     value for any element, or `t' if the predicate was `nil' for all
+     elements.
+
+ - Function: notevery predicate seq &rest more-seqs
+     This function calls PREDICATE on each element of the sequence(s)
+     in turn; it returns a non-`nil' value as soon as PREDICATE returns
+     `nil' for any element, or `t' if the predicate was true for all
+     elements.
+
+ - Function: reduce function seq &key :from-end :start :end
+          :initial-value :key
+     This function combines the elements of SEQ using an associative
+     binary operation.  Suppose FUNCTION is `*' and SEQ is the list `(2
+     3 4 5)'.  The first two elements of the list are combined with `(*
+     2 3) = 6'; this is combined with the next element, `(* 6 4) = 24',
+     and that is combined with the final element: `(* 24 5) = 120'.
+     Note that the `*' function happens to be self-reducing, so that
+     `(* 2 3 4 5)' has the same effect as an explicit call to `reduce'.
+
+     If `:from-end' is true, the reduction is right-associative instead
+     of left-associative:
+
+          (reduce '- '(1 2 3 4))
+               == (- (- (- 1 2) 3) 4) => -8
+          (reduce '- '(1 2 3 4) :from-end t)
+               == (- 1 (- 2 (- 3 4))) => -2
+
+     If `:key' is specified, it is a function of one argument which is
+     called on each of the sequence elements in turn.
+
+     If `:initial-value' is specified, it is effectively added to the
+     front (or rear in the case of `:from-end') of the sequence.  The
+     `:key' function is _not_ applied to the initial value.
+
+     If the sequence, including the initial value, has exactly one
+     element then that element is returned without ever calling
+     FUNCTION.  If the sequence is empty (and there is no initial
+     value), then FUNCTION is called with no arguments to obtain the
+     return value.
+
+   All of these mapping operations can be expressed conveniently in
+terms of the `loop' macro.  In compiled code, `loop' will be faster
+since it generates the loop as in-line code with no function calls.
+
+
+File: cl.info,  Node: Sequence Functions,  Next: Searching Sequences,  Prev: Mapping over Sequences,  Up: Sequences
+
+Sequence Functions
+==================
+
+This section describes a number of Common Lisp functions for operating
+on sequences.
+
+ - Function: subseq sequence start &optional end
+     This function returns a given subsequence of the argument
+     SEQUENCE, which may be a list, string, or vector.  The indices
+     START and END must be in range, and START must be no greater than
+     END.  If END is omitted, it defaults to the length of the
+     sequence.  The return value is always a copy; it does not share
+     structure with SEQUENCE.
+
+     As an extension to Common Lisp, START and/or END may be negative,
+     in which case they represent a distance back from the end of the
+     sequence.  This is for compatibility with Emacs' `substring'
+     function.  Note that `subseq' is the _only_ sequence function that
+     allows negative START and END.
+
+     You can use `setf' on a `subseq' form to replace a specified range
+     of elements with elements from another sequence.  The replacement
+     is done as if by `replace', described below.
+
+ - Function: concatenate result-type &rest seqs
+     This function concatenates the argument sequences together to form
+     a result sequence of type RESULT-TYPE, one of the symbols
+     `vector', `string', or `list'.  The arguments are always copied,
+     even in cases such as `(concatenate 'list '(1 2 3))' where the
+     result is identical to an argument.
+
+ - Function: fill seq item &key :start :end
+     This function fills the elements of the sequence (or the specified
+     part of the sequence) with the value ITEM.
+
+ - Function: replace seq1 seq2 &key :start1 :end1 :start2 :end2
+     This function copies part of SEQ2 into part of SEQ1.  The sequence
+     SEQ1 is not stretched or resized; the amount of data copied is
+     simply the shorter of the source and destination (sub)sequences.
+     The function returns SEQ1.
+
+     If SEQ1 and SEQ2 are `eq', then the replacement will work
+     correctly even if the regions indicated by the start and end
+     arguments overlap.  However, if SEQ1 and SEQ2 are lists which
+     share storage but are not `eq', and the start and end arguments
+     specify overlapping regions, the effect is undefined.
+
+ - Function: remove* item seq &key :test :test-not :key :count :start
+          :end :from-end
+     This returns a copy of SEQ with all elements matching ITEM
+     removed.  The result may share storage with or be `eq' to SEQ in
+     some circumstances, but the original SEQ will not be modified.
+     The `:test', `:test-not', and `:key' arguments define the matching
+     test that is used; by default, elements `eql' to ITEM are removed.
+     The `:count' argument specifies the maximum number of matching
+     elements that can be removed (only the leftmost COUNT matches are
+     removed).  The `:start' and `:end' arguments specify a region in
+     SEQ in which elements will be removed; elements outside that
+     region are not matched or removed.  The `:from-end' argument, if
+     true, says that elements should be deleted from the end of the
+     sequence rather than the beginning (this matters only if COUNT was
+     also specified).
+
+ - Function: delete* item seq &key :test :test-not :key :count :start
+          :end :from-end
+     This deletes all elements of SEQ which match ITEM.  It is a
+     destructive operation.  Since Emacs Lisp does not support
+     stretchable strings or vectors, this is the same as `remove*' for
+     those sequence types.  On lists, `remove*' will copy the list if
+     necessary to preserve the original list, whereas `delete*' will
+     splice out parts of the argument list.  Compare `append' and
+     `nconc', which are analogous non-destructive and destructive list
+     operations in Emacs Lisp.
+
+   The predicate-oriented functions `remove-if', `remove-if-not',
+`delete-if', and `delete-if-not' are defined similarly.
+
+ - Function: delete item list
+     This MacLisp-compatible function deletes from LIST all elements
+     which are `equal' to ITEM.  The `delete' function is built-in to
+     Emacs 19; this package defines it equivalently in Emacs 18.
+
+ - Function: remove item list
+     This function removes from LIST all elements which are `equal' to
+     ITEM.  This package defines it for symmetry with `delete', even
+     though `remove' is not built-in to Emacs 19.
+
+ - Function: remq item list
+     This function removes from LIST all elements which are `eq' to
+     ITEM.  This package defines it for symmetry with `delq', even
+     though `remq' is not built-in to Emacs 19.
+
+ - Function: remove-duplicates seq &key :test :test-not :key :start
+          :end :from-end
+     This function returns a copy of SEQ with duplicate elements
+     removed.  Specifically, if two elements from the sequence match
+     according to the `:test', `:test-not', and `:key' arguments, only
+     the rightmost one is retained.  If `:from-end' is true, the
+     leftmost one is retained instead.  If `:start' or `:end' is
+     specified, only elements within that subsequence are examined or
+     removed.
+
+ - Function: delete-duplicates seq &key :test :test-not :key :start
+          :end :from-end
+     This function deletes duplicate elements from SEQ.  It is a
+     destructive version of `remove-duplicates'.
+
+ - Function: substitute new old seq &key :test :test-not :key :count
+          :start :end :from-end
+     This function returns a copy of SEQ, with all elements matching
+     OLD replaced with NEW.  The `:count', `:start', `:end', and
+     `:from-end' arguments may be used to limit the number of
+     substitutions made.
+
+ - Function: nsubstitute new old seq &key :test :test-not :key :count
+          :start :end :from-end
+     This is a destructive version of `substitute'; it performs the
+     substitution using `setcar' or `aset' rather than by returning a
+     changed copy of the sequence.
+
+   The `substitute-if', `substitute-if-not', `nsubstitute-if', and
+`nsubstitute-if-not' functions are defined similarly.  For these, a
+PREDICATE is given in place of the OLD argument.
+
+
+File: cl.info,  Node: Searching Sequences,  Next: Sorting Sequences,  Prev: Sequence Functions,  Up: Sequences
+
+Searching Sequences
+===================
+
+These functions search for elements or subsequences in a sequence.
+(See also `member*' and `assoc*'; *note Lists::.)
+
+ - Function: find item seq &key :test :test-not :key :start :end
+          :from-end
+     This function searches SEQ for an element matching ITEM.  If it
+     finds a match, it returns the matching element.  Otherwise, it
+     returns `nil'.  It returns the leftmost match, unless `:from-end'
+     is true, in which case it returns the rightmost match.  The
+     `:start' and `:end' arguments may be used to limit the range of
+     elements that are searched.
+
+ - Function: position item seq &key :test :test-not :key :start :end
+          :from-end
+     This function is like `find', except that it returns the integer
+     position in the sequence of the matching item rather than the item
+     itself.  The position is relative to the start of the sequence as
+     a whole, even if `:start' is non-zero.  The function returns `nil'
+     if no matching element was found.
+
+ - Function: count item seq &key :test :test-not :key :start :end
+     This function returns the number of elements of SEQ which match
+     ITEM.  The result is always a nonnegative integer.
+
+   The `find-if', `find-if-not', `position-if', `position-if-not',
+`count-if', and `count-if-not' functions are defined similarly.
+
+ - Function: mismatch seq1 seq2 &key :test :test-not :key :start1 :end1
+          :start2 :end2 :from-end
+     This function compares the specified parts of SEQ1 and SEQ2.  If
+     they are the same length and the corresponding elements match
+     (according to `:test', `:test-not', and `:key'), the function
+     returns `nil'.  If there is a mismatch, the function returns the
+     index (relative to SEQ1) of the first mismatching element.  This
+     will be the leftmost pair of elements which do not match, or the
+     position at which the shorter of the two otherwise-matching
+     sequences runs out.
+
+     If `:from-end' is true, then the elements are compared from right
+     to left starting at `(1- END1)' and `(1- END2)'.  If the sequences
+     differ, then one plus the index of the rightmost difference
+     (relative to SEQ1) is returned.
+
+     An interesting example is `(mismatch str1 str2 :key 'upcase)',
+     which compares two strings case-insensitively.
+
+ - Function: search seq1 seq2 &key :test :test-not :key :from-end
+          :start1 :end1 :start2 :end2
+     This function searches SEQ2 for a subsequence that matches SEQ1
+     (or part of it specified by `:start1' and `:end1'.)  Only matches
+     which fall entirely within the region defined by `:start2' and
+     `:end2' will be considered.  The return value is the index of the
+     leftmost element of the leftmost match, relative to the start of
+     SEQ2, or `nil' if no matches were found.  If `:from-end' is true,
+     the function finds the _rightmost_ matching subsequence.
+
+
+File: cl.info,  Node: Sorting Sequences,  Prev: Searching Sequences,  Up: Sequences
+
+Sorting Sequences
+=================
+
+ - Function: sort* seq predicate &key :key
+     This function sorts SEQ into increasing order as determined by
+     using PREDICATE to compare pairs of elements.  PREDICATE should
+     return true (non-`nil') if and only if its first argument is less
+     than (not equal to) its second argument.  For example, `<' and
+     `string-lessp' are suitable predicate functions for sorting
+     numbers and strings, respectively; `>' would sort numbers into
+     decreasing rather than increasing order.
+
+     This function differs from Emacs' built-in `sort' in that it can
+     operate on any type of sequence, not just lists.  Also, it accepts
+     a `:key' argument which is used to preprocess data fed to the
+     PREDICATE function.  For example,
+
+          (setq data (sort data 'string-lessp :key 'downcase))
+
+     sorts DATA, a sequence of strings, into increasing alphabetical
+     order without regard to case.  A `:key' function of `car' would be
+     useful for sorting association lists.
+
+     The `sort*' function is destructive; it sorts lists by actually
+     rearranging the `cdr' pointers in suitable fashion.
+
+ - Function: stable-sort seq predicate &key :key
+     This function sorts SEQ "stably", meaning two elements which are
+     equal in terms of PREDICATE are guaranteed not to be rearranged
+     out of their original order by the sort.
+
+     In practice, `sort*' and `stable-sort' are equivalent in Emacs
+     Lisp because the underlying `sort' function is stable by default.
+     However, this package reserves the right to use non-stable methods
+     for `sort*' in the future.
+
+ - Function: merge type seq1 seq2 predicate &key :key
+     This function merges two sequences SEQ1 and SEQ2 by interleaving
+     their elements.  The result sequence, of type TYPE (in the sense
+     of `concatenate'), has length equal to the sum of the lengths of
+     the two input sequences.  The sequences may be modified
+     destructively.  Order of elements within SEQ1 and SEQ2 is
+     preserved in the interleaving; elements of the two sequences are
+     compared by PREDICATE (in the sense of `sort') and the lesser
+     element goes first in the result.  When elements are equal, those
+     from SEQ1 precede those from SEQ2 in the result.  Thus, if SEQ1
+     and SEQ2 are both sorted according to PREDICATE, then the result
+     will be a merged sequence which is (stably) sorted according to
+     PREDICATE.
+
+
+File: cl.info,  Node: Lists,  Next: Hash Tables,  Prev: Sequences,  Up: Top
+
+Lists
+*****
+
+The functions described here operate on lists.
+
+* Menu:
+
+* List Functions::                `caddr', `first', `last', `list*', etc.
+* Substitution of Expressions::   `subst', `sublis', etc.
+* Lists as Sets::                 `member*', `adjoin', `union', etc.
+* Association Lists::             `assoc*', `rassoc*', `acons', `pairlis'
+
+
+File: cl.info,  Node: List Functions,  Next: Substitution of Expressions,  Prev: Lists,  Up: Lists
+
+List Functions
+==============
+
+This section describes a number of simple operations on lists, i.e.,
+chains of cons cells.
+
+ - Function: caddr x
+     This function is equivalent to `(car (cdr (cdr X)))'.  Likewise,
+     this package defines all 28 `cXXXr' functions where XXX is up to
+     four `a's and/or `d's.  All of these functions are `setf'-able,
+     and calls to them are expanded inline by the byte-compiler for
+     maximum efficiency.
+
+ - Function: first x
+     This function is a synonym for `(car X)'.  Likewise, the functions
+     `second', `third', ..., through `tenth' return the given element
+     of the list X.
+
+ - Function: rest x
+     This function is a synonym for `(cdr X)'.
+
+ - Function: endp x
+     Common Lisp defines this function to act like `null', but
+     signalling an error if `x' is neither a `nil' nor a cons cell.
+     This package simply defines `endp' as a synonym for `null'.
+
+ - Function: list-length x
+     This function returns the length of list X, exactly like `(length
+     X)', except that if X is a circular list (where the cdr-chain
+     forms a loop rather than terminating with `nil'), this function
+     returns `nil'.  (The regular `length' function would get stuck if
+     given a circular list.)
+
+ - Function: last x &optional n
+     This function returns the last cons, or the Nth-to-last cons, of
+     the list X.  If N is omitted it defaults to 1.  The "last cons"
+     means the first cons cell of the list whose `cdr' is not another
+     cons cell.  (For normal lists, the `cdr' of the last cons will be
+     `nil'.)  This function returns `nil' if X is `nil' or shorter than
+     N.  Note that the last _element_ of the list is `(car (last X))'.
+
+ - Function: butlast x &optional n
+     This function returns the list X with the last element, or the
+     last N elements, removed.  If N is greater than zero it makes a
+     copy of the list so as not to damage the original list.  In
+     general, `(append (butlast X N) (last X N))' will return a list
+     equal to X.
+
+ - Function: nbutlast x &optional n
+     This is a version of `butlast' that works by destructively
+     modifying the `cdr' of the appropriate element, rather than making
+     a copy of the list.
+
+ - Function: list* arg &rest others
+     This function constructs a list of its arguments.  The final
+     argument becomes the `cdr' of the last cell constructed.  Thus,
+     `(list* A B C)' is equivalent to `(cons A (cons B C))', and
+     `(list* A B nil)' is equivalent to `(list A B)'.
+
+     (Note that this function really is called `list*' in Common Lisp;
+     it is not a name invented for this package like `member*' or
+     `defun*'.)
+
+ - Function: ldiff list sublist
+     If SUBLIST is a sublist of LIST, i.e., is `eq' to one of the cons
+     cells of LIST, then this function returns a copy of the part of
+     LIST up to but not including SUBLIST.  For example, `(ldiff x
+     (cddr x))' returns the first two elements of the list `x'.  The
+     result is a copy; the original LIST is not modified.  If SUBLIST
+     is not a sublist of LIST, a copy of the entire LIST is returned.
+
+ - Function: copy-list list
+     This function returns a copy of the list LIST.  It copies dotted
+     lists like `(1 2 . 3)' correctly.
+
+ - Function: copy-tree x &optional vecp
+     This function returns a copy of the tree of cons cells X.  Unlike
+     `copy-sequence' (and its alias `copy-list'), which copies only
+     along the `cdr' direction, this function copies (recursively)
+     along both the `car' and the `cdr' directions.  If X is not a cons
+     cell, the function simply returns X unchanged.  If the optional
+     VECP argument is true, this function copies vectors (recursively)
+     as well as cons cells.
+
+ - Function: tree-equal x y &key :test :test-not :key
+     This function compares two trees of cons cells.  If X and Y are
+     both cons cells, their `car's and `cdr's are compared recursively.
+     If neither X nor Y is a cons cell, they are compared by `eql', or
+     according to the specified test.  The `:key' function, if
+     specified, is applied to the elements of both trees.  *Note
+     Sequences::.
+
+
+File: cl.info,  Node: Substitution of Expressions,  Next: Lists as Sets,  Prev: List Functions,  Up: Lists
+
+Substitution of Expressions
+===========================
+
+These functions substitute elements throughout a tree of cons cells.
+(*Note Sequence Functions::, for the `substitute' function, which works
+on just the top-level elements of a list.)
+
+ - Function: subst new old tree &key :test :test-not :key
+     This function substitutes occurrences of OLD with NEW in TREE, a
+     tree of cons cells.  It returns a substituted tree, which will be
+     a copy except that it may share storage with the argument TREE in
+     parts where no substitutions occurred.  The original TREE is not
+     modified.  This function recurses on, and compares against OLD,
+     both `car's and `cdr's of the component cons cells.  If OLD is
+     itself a cons cell, then matching cells in the tree are
+     substituted as usual without recursively substituting in that
+     cell.  Comparisons with OLD are done according to the specified
+     test (`eql' by default).  The `:key' function is applied to the
+     elements of the tree but not to OLD.
+
+ - Function: nsubst new old tree &key :test :test-not :key
+     This function is like `subst', except that it works by destructive
+     modification (by `setcar' or `setcdr') rather than copying.
+
+   The `subst-if', `subst-if-not', `nsubst-if', and `nsubst-if-not'
+functions are defined similarly.
+
+ - Function: sublis alist tree &key :test :test-not :key
+     This function is like `subst', except that it takes an association
+     list ALIST of OLD-NEW pairs.  Each element of the tree (after
+     applying the `:key' function, if any), is compared with the `car's
+     of ALIST; if it matches, it is replaced by the corresponding `cdr'.
+
+ - Function: nsublis alist tree &key :test :test-not :key
+     This is a destructive version of `sublis'.
+
+
+File: cl.info,  Node: Lists as Sets,  Next: Association Lists,  Prev: Substitution of Expressions,  Up: Lists
+
+Lists as Sets
+=============
+
+These functions perform operations on lists which represent sets of
+elements.
+
+ - Function: member item list
+     This MacLisp-compatible function searches LIST for an element
+     which is `equal' to ITEM.  The `member' function is built-in to
+     Emacs 19; this package defines it equivalently in Emacs 18.  See
+     the following function for a Common-Lisp compatible version.
+
+ - Function: member* item list &key :test :test-not :key
+     This function searches LIST for an element matching ITEM.  If a
+     match is found, it returns the cons cell whose `car' was the
+     matching element.  Otherwise, it returns `nil'.  Elements are
+     compared by `eql' by default; you can use the `:test',
+     `:test-not', and `:key' arguments to modify this behavior.  *Note
+     Sequences::.
+
+     Note that this function's name is suffixed by `*' to avoid the
+     incompatible `member' function defined in Emacs 19.  (That
+     function uses `equal' for comparisons; it is equivalent to
+     `(member* ITEM LIST :test 'equal)'.)
+
+   The `member-if' and `member-if-not' functions analogously search for
+elements which satisfy a given predicate.
+
+ - Function: tailp sublist list
+     This function returns `t' if SUBLIST is a sublist of LIST, i.e.,
+     if SUBLIST is `eql' to LIST or to any of its `cdr's.
+
+ - Function: adjoin item list &key :test :test-not :key
+     This function conses ITEM onto the front of LIST, like `(cons ITEM
+     LIST)', but only if ITEM is not already present on the list (as
+     determined by `member*').  If a `:key' argument is specified, it
+     is applied to ITEM as well as to the elements of LIST during the
+     search, on the reasoning that ITEM is "about" to become part of
+     the list.
+
+ - Function: union list1 list2 &key :test :test-not :key
+     This function combines two lists which represent sets of items,
+     returning a list that represents the union of those two sets.  The
+     result list will contain all items which appear in LIST1 or LIST2,
+     and no others.  If an item appears in both LIST1 and LIST2 it will
+     be copied only once.  If an item is duplicated in LIST1 or LIST2,
+     it is undefined whether or not that duplication will survive in the
+     result list.  The order of elements in the result list is also
+     undefined.
+
+ - Function: nunion list1 list2 &key :test :test-not :key
+     This is a destructive version of `union'; rather than copying, it
+     tries to reuse the storage of the argument lists if possible.
+
+ - Function: intersection list1 list2 &key :test :test-not :key
+     This function computes the intersection of the sets represented by
+     LIST1 and LIST2.  It returns the list of items which appear in
+     both LIST1 and LIST2.
+
+ - Function: nintersection list1 list2 &key :test :test-not :key
+     This is a destructive version of `intersection'.  It tries to
+     reuse storage of LIST1 rather than copying.  It does _not_ reuse
+     the storage of LIST2.
+
+ - Function: set-difference list1 list2 &key :test :test-not :key
+     This function computes the "set difference" of LIST1 and LIST2,
+     i.e., the set of elements that appear in LIST1 but _not_ in LIST2.
+
+ - Function: nset-difference list1 list2 &key :test :test-not :key
+     This is a destructive `set-difference', which will try to reuse
+     LIST1 if possible.
+
+ - Function: set-exclusive-or list1 list2 &key :test :test-not :key
+     This function computes the "set exclusive or" of LIST1 and LIST2,
+     i.e., the set of elements that appear in exactly one of LIST1 and
+     LIST2.
+
+ - Function: nset-exclusive-or list1 list2 &key :test :test-not :key
+     This is a destructive `set-exclusive-or', which will try to reuse
+     LIST1 and LIST2 if possible.
+
+ - Function: subsetp list1 list2 &key :test :test-not :key
+     This function checks whether LIST1 represents a subset of LIST2,
+     i.e., whether every element of LIST1 also appears in LIST2.
+
+
+File: cl.info,  Node: Association Lists,  Prev: Lists as Sets,  Up: Lists
+
+Association Lists
+=================
+
+An "association list" is a list representing a mapping from one set of
+values to another; any list whose elements are cons cells is an
+association list.
+
+ - Function: assoc* item a-list &key :test :test-not :key
+     This function searches the association list A-LIST for an element
+     whose `car' matches (in the sense of `:test', `:test-not', and
+     `:key', or by comparison with `eql') a given ITEM.  It returns the
+     matching element, if any, otherwise `nil'.  It ignores elements of
+     A-LIST which are not cons cells.  (This corresponds to the
+     behavior of `assq' and `assoc' in Emacs Lisp; Common Lisp's
+     `assoc' ignores `nil's but considers any other non-cons elements
+     of A-LIST to be an error.)
+
+ - Function: rassoc* item a-list &key :test :test-not :key
+     This function searches for an element whose `cdr' matches ITEM.
+     If A-LIST represents a mapping, this applies the inverse of the
+     mapping to ITEM.
+
+ - Function: rassoc item a-list
+     This function searches like `rassoc*' with a `:test' argument of
+     `equal'.  It is analogous to Emacs Lisp's standard `assoc'
+     function, which derives from the MacLisp rather than the Common
+     Lisp tradition.
+
+   The `assoc-if', `assoc-if-not', `rassoc-if', and `rassoc-if-not'
+functions are defined similarly.
+
+   Two simple functions for constructing association lists are:
+
+ - Function: acons key value alist
+     This is equivalent to `(cons (cons KEY VALUE) ALIST)'.
+
+ - Function: pairlis keys values &optional alist
+     This is equivalent to `(nconc (mapcar* 'cons KEYS VALUES) ALIST)'.
+
+
+File: cl.info,  Node: Hash Tables,  Next: Structures,  Prev: Lists,  Up: Top
+
+Hash Tables
+***********
+
+Hash tables are now implemented directly in the C code and documented in
+*Note Hash Tables: (lispref)Hash Tables.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-5'
Index: ././info/cl.info-5
--- ././info/cl.info-5	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-5	Thu May 17 23:26:51 2001
@@ -0,0 +1,913 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: Structures,  Next: Assertions,  Prev: Hash Tables,  Up: Top
+
+Structures
+**********
+
+The Common Lisp "structure" mechanism provides a general way to define
+data types similar to C's `struct' types.  A structure is a Lisp object
+containing some number of "slots", each of which can hold any Lisp data
+object.  Functions are provided for accessing and setting the slots,
+creating or copying structure objects, and recognizing objects of a
+particular structure type.
+
+   In true Common Lisp, each structure type is a new type distinct from
+all existing Lisp types.  Since the underlying Emacs Lisp system
+provides no way to create new distinct types, this package implements
+structures as vectors (or lists upon request) with a special "tag"
+symbol to identify them.
+
+ - Special Form: defstruct name slots...
+     The `defstruct' form defines a new structure type called NAME,
+     with the specified SLOTS.  (The SLOTS may begin with a string
+     which documents the structure type.)  In the simplest case, NAME
+     and each of the SLOTS are symbols.  For example,
+
+          (defstruct person name age sex)
+
+     defines a struct type called `person' which contains three slots.
+     Given a `person' object P, you can access those slots by calling
+     `(person-name P)', `(person-age P)', and `(person-sex P)'.  You
+     can also change these slots by using `setf' on any of these place
+     forms:
+
+          (incf (person-age birthday-boy))
+
+     You can create a new `person' by calling `make-person', which
+     takes keyword arguments `:name', `:age', and `:sex' to specify the
+     initial values of these slots in the new object.  (Omitting any of
+     these arguments leaves the corresponding slot "undefined,"
+     according to the Common Lisp standard; in Emacs Lisp, such
+     uninitialized slots are filled with `nil'.)
+
+     Given a `person', `(copy-person P)' makes a new object of the same
+     type whose slots are `eq' to those of P.
+
+     Given any Lisp object X, `(person-p X)' returns true if X looks
+     like a `person', false otherwise.  (Again, in Common Lisp this
+     predicate would be exact; in Emacs Lisp the best it can do is
+     verify that X is a vector of the correct length which starts with
+     the correct tag symbol.)
+
+     Accessors like `person-name' normally check their arguments
+     (effectively using `person-p') and signal an error if the argument
+     is the wrong type.  This check is affected by `(optimize (safety
+     ...))' declarations.  Safety level 1, the default, uses a somewhat
+     optimized check that will detect all incorrect arguments, but may
+     use an uninformative error message (e.g., "expected a vector"
+     instead of "expected a `person'").  Safety level 0 omits all
+     checks except as provided by the underlying `aref' call; safety
+     levels 2 and 3 do rigorous checking that will always print a
+     descriptive error message for incorrect inputs.  *Note
+     Declarations::.
+
+          (setq dave (make-person :name "Dave" :sex 'male))
+               => [cl-struct-person "Dave" nil male]
+          (setq other (copy-person dave))
+               => [cl-struct-person "Dave" nil male]
+          (eq dave other)
+               => nil
+          (eq (person-name dave) (person-name other))
+               => t
+          (person-p dave)
+               => t
+          (person-p [1 2 3 4])
+               => nil
+          (person-p "Bogus")
+               => nil
+          (person-p '[cl-struct-person counterfeit person object])
+               => t
+
+     In general, NAME is either a name symbol or a list of a name
+     symbol followed by any number of "struct options"; each SLOT is
+     either a slot symbol or a list of the form `(SLOT-NAME
+     DEFAULT-VALUE SLOT-OPTIONS...)'.  The DEFAULT-VALUE is a Lisp form
+     which is evaluated any time an instance of the structure type is
+     created without specifying that slot's value.
+
+     Common Lisp defines several slot options, but the only one
+     implemented in this package is `:read-only'.  A non-`nil' value
+     for this option means the slot should not be `setf'-able; the
+     slot's value is determined when the object is created and does not
+     change afterward.
+
+          (defstruct person
+            (name nil :read-only t)
+            age
+            (sex 'unknown))
+
+     Any slot options other than `:read-only' are ignored.
+
+     For obscure historical reasons, structure options take a different
+     form than slot options.  A structure option is either a keyword
+     symbol, or a list beginning with a keyword symbol possibly followed
+     by arguments.  (By contrast, slot options are key-value pairs not
+     enclosed in lists.)
+
+          (defstruct (person (:constructor create-person)
+                             (:type list)
+                             :named)
+            name age sex)
+
+     The following structure options are recognized.
+
+    `:conc-name'
+          The argument is a symbol whose print name is used as the
+          prefix for the names of slot accessor functions.  The default
+          is the name of the struct type followed by a hyphen.  The
+          option `(:conc-name p-)' would change this prefix to `p-'.
+          Specifying `nil' as an argument means no prefix, so that the
+          slot names themselves are used to name the accessor functions.
+
+    `:constructor'
+          In the simple case, this option takes one argument which is an
+          alternate name to use for the constructor function.  The
+          default is `make-NAME', e.g., `make-person'.  The above
+          example changes this to `create-person'.  Specifying `nil' as
+          an argument means that no standard constructor should be
+          generated at all.
+
+          In the full form of this option, the constructor name is
+          followed by an arbitrary argument list.  *Note Program
+          Structure::, for a description of the format of Common Lisp
+          argument lists.  All options, such as `&rest' and `&key', are
+          supported.  The argument names should match the slot names;
+          each slot is initialized from the corresponding argument.
+          Slots whose names do not appear in the argument list are
+          initialized based on the DEFAULT-VALUE in their slot
+          descriptor.  Also, `&optional' and `&key' arguments which
+          don't specify defaults take their defaults from the slot
+          descriptor.  It is legal to include arguments which don't
+          correspond to slot names; these are useful if they are
+          referred to in the defaults for optional, keyword, or `&aux'
+          arguments which _do_ correspond to slots.
+
+          You can specify any number of full-format `:constructor'
+          options on a structure.  The default constructor is still
+          generated as well unless you disable it with a simple-format
+          `:constructor' option.
+
+               (defstruct
+                (person
+                 (:constructor nil)   ; no default constructor
+                 (:constructor new-person (name sex &optional (age 0)))
+                 (:constructor new-hound (&key (name "Rover")
+                                               (dog-years 0)
+                                          &aux (age (* 7 dog-years))
+                                               (sex 'canine))))
+                name age sex)
+
+          The first constructor here takes its arguments positionally
+          rather than by keyword.  (In official Common Lisp
+          terminology, constructors that work By Order of Arguments
+          instead of by keyword are called "BOA constructors."  No, I'm
+          not making this up.)  For example, `(new-person "Jane"
+          'female)' generates a person whose slots are `"Jane"', 0, and
+          `female', respectively.
+
+          The second constructor takes two keyword arguments, `:name',
+          which initializes the `name' slot and defaults to `"Rover"',
+          and `:dog-years', which does not itself correspond to a slot
+          but which is used to initialize the `age' slot.  The `sex'
+          slot is forced to the symbol `canine' with no syntax for
+          overriding it.
+
+    `:copier'
+          The argument is an alternate name for the copier function for
+          this type.  The default is `copy-NAME'.  `nil' means not to
+          generate a copier function.  (In this implementation, all
+          copier functions are simply synonyms for `copy-sequence'.)
+
+    `:predicate'
+          The argument is an alternate name for the predicate which
+          recognizes objects of this type.  The default is `NAME-p'.
+          `nil' means not to generate a predicate function.  (If the
+          `:type' option is used without the `:named' option, no
+          predicate is ever generated.)
+
+          In true Common Lisp, `typep' is always able to recognize a
+          structure object even if `:predicate' was used.  In this
+          package, `typep' simply looks for a function called
+          `TYPENAME-p', so it will work for structure types only if
+          they used the default predicate name.
+
+    `:include'
+          This option implements a very limited form of C++-style
+          inheritance.  The argument is the name of another structure
+          type previously created with `defstruct'.  The effect is to
+          cause the new structure type to inherit all of the included
+          structure's slots (plus, of course, any new slots described
+          by this struct's slot descriptors).  The new structure is
+          considered a "specialization" of the included one.  In fact,
+          the predicate and slot accessors for the included type will
+          also accept objects of the new type.
+
+          If there are extra arguments to the `:include' option after
+          the included-structure name, these options are treated as
+          replacement slot descriptors for slots in the included
+          structure, possibly with modified default values.  Borrowing
+          an example from Steele:
+
+               (defstruct person name (age 0) sex)
+                    => person
+               (defstruct (astronaut (:include person (age 45)))
+                 helmet-size
+                 (favorite-beverage 'tang))
+                    => astronaut
+               
+               (setq joe (make-person :name "Joe"))
+                    => [cl-struct-person "Joe" 0 nil]
+               (setq buzz (make-astronaut :name "Buzz"))
+                    => [cl-struct-astronaut "Buzz" 45 nil nil tang]
+               
+               (list (person-p joe) (person-p buzz))
+                    => (t t)
+               (list (astronaut-p joe) (astronaut-p buzz))
+                    => (nil t)
+               
+               (person-name buzz)
+                    => "Buzz"
+               (astronaut-name joe)
+                    => error: "astronaut-name accessing a non-astronaut"
+
+          Thus, if `astronaut' is a specialization of `person', then
+          every `astronaut' is also a `person' (but not the other way
+          around).  Every `astronaut' includes all the slots of a
+          `person', plus extra slots that are specific to astronauts.
+          Operations that work on people (like `person-name') work on
+          astronauts just like other people.
+
+    `:print-function'
+          In full Common Lisp, this option allows you to specify a
+          function which is called to print an instance of the
+          structure type.  The Emacs Lisp system offers no hooks into
+          the Lisp printer which would allow for such a feature, so
+          this package simply ignores `:print-function'.
+
+    `:type'
+          The argument should be one of the symbols `vector' or `list'.
+          This tells which underlying Lisp data type should be used to
+          implement the new structure type.  Vectors are used by
+          default, but `(:type list)' will cause structure objects to
+          be stored as lists instead.
+
+          The vector representation for structure objects has the
+          advantage that all structure slots can be accessed quickly,
+          although creating vectors is a bit slower in Emacs Lisp.
+          Lists are easier to create, but take a relatively long time
+          accessing the later slots.
+
+    `:named'
+          This option, which takes no arguments, causes a
+          characteristic "tag" symbol to be stored at the front of the
+          structure object.  Using `:type' without also using `:named'
+          will result in a structure type stored as plain vectors or
+          lists with no identifying features.
+
+          The default, if you don't specify `:type' explicitly, is to
+          use named vectors.  Therefore, `:named' is only useful in
+          conjunction with `:type'.
+
+               (defstruct (person1) name age sex)
+               (defstruct (person2 (:type list) :named) name age sex)
+               (defstruct (person3 (:type list)) name age sex)
+               
+               (setq p1 (make-person1))
+                    => [cl-struct-person1 nil nil nil]
+               (setq p2 (make-person2))
+                    => (person2 nil nil nil)
+               (setq p3 (make-person3))
+                    => (nil nil nil)
+               
+               (person1-p p1)
+                    => t
+               (person2-p p2)
+                    => t
+               (person3-p p3)
+                    => error: function person3-p undefined
+
+          Since unnamed structures don't have tags, `defstruct' is not
+          able to make a useful predicate for recognizing them.  Also,
+          accessors like `person3-name' will be generated but they will
+          not be able to do any type checking.  The `person3-name'
+          function, for example, will simply be a synonym for `car' in
+          this case.  By contrast, `person2-name' is able to verify
+          that its argument is indeed a `person2' object before
+          proceeding.
+
+    `:initial-offset'
+          The argument must be a nonnegative integer.  It specifies a
+          number of slots to be left "empty" at the front of the
+          structure.  If the structure is named, the tag appears at the
+          specified position in the list or vector; otherwise, the first
+          slot appears at that position.  Earlier positions are filled
+          with `nil' by the constructors and ignored otherwise.  If the
+          type `:include's another type, then `:initial-offset'
+          specifies a number of slots to be skipped between the last
+          slot of the included type and the first new slot.
+
+   Except as noted, the `defstruct' facility of this package is
+entirely compatible with that of Common Lisp.
+
+
+File: cl.info,  Node: Assertions,  Next: Efficiency Concerns,  Prev: Structures,  Up: Top
+
+Assertions and Errors
+*********************
+
+This section describes two macros that test "assertions", i.e.,
+conditions which must be true if the program is operating correctly.
+Assertions never add to the behavior of a Lisp program; they simply
+make "sanity checks" to make sure everything is as it should be.
+
+   If the optimization property `speed' has been set to 3, and `safety'
+is less than 3, then the byte-compiler will optimize away the following
+assertions.  Because assertions might be optimized away, it is a bad
+idea for them to include side-effects.
+
+ - Special Form: assert test-form [show-args string args...]
+     This form verifies that TEST-FORM is true (i.e., evaluates to a
+     non-`nil' value).  If so, it returns `nil'.  If the test is not
+     satisfied, `assert' signals an error.
+
+     A default error message will be supplied which includes TEST-FORM.
+     You can specify a different error message by including a STRING
+     argument plus optional extra arguments.  Those arguments are simply
+     passed to `error' to signal the error.
+
+     If the optional second argument SHOW-ARGS is `t' instead of `nil',
+     then the error message (with or without STRING) will also include
+     all non-constant arguments of the top-level FORM.  For example:
+
+          (assert (> x 10) t "x is too small: %d")
+
+     This usage of SHOW-ARGS is a change to Common Lisp.  In true
+     Common Lisp, the second argument gives a list of PLACES which can
+     be `setf''d by the user before continuing from the error.
+
+ - Special Form: check-type place type &optional string
+     This form verifies that PLACE evaluates to a value of type TYPE.
+     If so, it returns `nil'.  If not, `check-type' signals a
+     continuable `wrong-type-argument' error.  The default error
+     message lists the erroneous value along with TYPE and PLACE
+     themselves.  If STRING is specified, it is included in the error
+     message in place of TYPE.  For example:
+
+          (check-type x (integer 1 *) "a positive integer")
+
+     *Note Type Predicates::, for a description of the type specifiers
+     that may be used for TYPE.
+
+     Note that as in Common Lisp, the first argument to `check-type'
+     should be a PLACE suitable for use by `setf', because `check-type'
+     signals a continuable error that allows the user to modify PLACE,
+     most simply by returning a value from the debugger.
+
+   The following error-related macro is also defined:
+
+ - Special Form: ignore-errors forms...
+     This executes FORMS exactly like a `progn', except that errors are
+     ignored during the FORMS.  More precisely, if an error is
+     signalled then `ignore-errors' immediately aborts execution of the
+     FORMS and returns `nil'.  If the FORMS complete successfully,
+     `ignore-errors' returns the result of the last FORM.
+
+
+File: cl.info,  Node: Efficiency Concerns,  Next: Common Lisp Compatibility,  Prev: Assertions,  Up: Top
+
+Efficiency Concerns
+*******************
+
+Macros
+======
+
+Many of the advanced features of this package, such as `defun*',
+`loop', and `setf', are implemented as Lisp macros.  In byte-compiled
+code, these complex notations will be expanded into equivalent Lisp
+code which is simple and efficient.  For example, the forms
+
+     (incf i n)
+     (push x (car p))
+
+are expanded at compile-time to the Lisp forms
+
+     (setq i (+ i n))
+     (setcar p (cons x (car p)))
+
+which are the most efficient ways of doing these respective operations
+in Lisp.  Thus, there is no performance penalty for using the more
+readable `incf' and `push' forms in your compiled code.
+
+   _Interpreted_ code, on the other hand, must expand these macros
+every time they are executed.  For this reason it is strongly
+recommended that code making heavy use of macros be compiled.  (The
+features labelled "Special Form" instead of "Function" in this manual
+are macros.)  A loop using `incf' a hundred times will execute
+considerably faster if compiled, and will also garbage-collect less
+because the macro expansion will not have to be generated, used, and
+thrown away a hundred times.
+
+   You can find out how a macro expands by using the `cl-prettyexpand'
+function.
+
+ - Function: cl-prettyexpand form &optional full
+     This function takes a single Lisp form as an argument and inserts
+     a nicely formatted copy of it in the current buffer (which must be
+     in Lisp mode so that indentation works properly).  It also expands
+     all Lisp macros which appear in the form.  The easiest way to use
+     this function is to go to the `*scratch*' buffer and type, say,
+
+          (cl-prettyexpand '(loop for x below 10 collect x))
+
+     and type `C-x C-e' immediately after the closing parenthesis; the
+     expansion
+
+          (block nil
+            (let* ((x 0)
+                   (G1004 nil))
+              (while (< x 10)
+                (setq G1004 (cons x G1004))
+                (setq x (+ x 1)))
+              (nreverse G1004)))
+
+     will be inserted into the buffer.  (The `block' macro is expanded
+     differently in the interpreter and compiler, so `cl-prettyexpand'
+     just leaves it alone.  The temporary variable `G1004' was created
+     by `gensym'.)
+
+     If the optional argument FULL is true, then _all_ macros are
+     expanded, including `block', `eval-when', and compiler macros.
+     Expansion is done as if FORM were a top-level form in a file being
+     compiled.  For example,
+
+          (cl-prettyexpand '(pushnew 'x list))
+               -| (setq list (adjoin 'x list))
+          (cl-prettyexpand '(pushnew 'x list) t)
+               -| (setq list (if (memq 'x list) list (cons 'x list)))
+          (cl-prettyexpand '(caddr (member* 'a list)) t)
+               -| (car (cdr (cdr (memq 'a list))))
+
+     Note that `adjoin', `caddr', and `member*' all have built-in
+     compiler macros to optimize them in common cases.
+
+
+Error Checking
+==============
+
+Common Lisp compliance has in general not been sacrificed for the sake
+of efficiency.  A few exceptions have been made for cases where
+substantial gains were possible at the expense of marginal
+incompatibility.  One example is the use of `memq' (which is treated
+very efficiently by the byte-compiler) to scan for keyword arguments;
+this can become confused in rare cases when keyword symbols are used as
+both keywords and data values at once.  This is extremely unlikely to
+occur in practical code, and the use of `memq' allows functions with
+keyword arguments to be nearly as fast as functions that use
+`&optional' arguments.
+
+   The Common Lisp standard (as embodied in Steele's book) uses the
+phrase "it is an error if" to indicate a situation which is not
+supposed to arise in complying programs; implementations are strongly
+encouraged but not required to signal an error in these situations.
+This package sometimes omits such error checking in the interest of
+compactness and efficiency.  For example, `do' variable specifiers are
+supposed to be lists of one, two, or three forms; extra forms are
+ignored by this package rather than signalling a syntax error.  The
+`endp' function is simply a synonym for `null' in this package.
+Functions taking keyword arguments will accept an odd number of
+arguments, treating the trailing keyword as if it were followed by the
+value `nil'.
+
+   Argument lists (as processed by `defun*' and friends) _are_ checked
+rigorously except for the minor point just mentioned; in particular,
+keyword arguments are checked for validity, and `&allow-other-keys' and
+`:allow-other-keys' are fully implemented.  Keyword validity checking
+is slightly time consuming (though not too bad in byte-compiled code);
+you can use `&allow-other-keys' to omit this check.  Functions defined
+in this package such as `find' and `member*' do check their keyword
+arguments for validity.
+
+
+Optimizing Compiler
+===================
+
+The byte-compiler that comes with Emacs 18 normally fails to expand
+macros that appear in top-level positions in the file (i.e., outside of
+`defun's or other enclosing forms).  This would have disastrous
+consequences to programs that used such top-level macros as `defun*',
+`eval-when', and `defstruct'.  To work around this problem, the "CL"
+package patches the Emacs 18 compiler to expand top-level macros.  This
+patch will apply to your own macros, too, if they are used in a
+top-level context.  The patch will not harm versions of the Emacs 18
+compiler which have already had a similar patch applied, nor will it
+affect the optimizing Emacs 19 byte-compiler written by Jamie Zawinski
+and Hallvard Furuseth.  The patch is applied to the byte compiler's
+code in Emacs' memory, _not_ to the `bytecomp.elc' file stored on disk.
+
+   The Emacs 19 compiler (for Emacs 18) is available from various Emacs
+Lisp archive sites such as `archive.cis.ohio-state.edu'.  Its use is
+highly recommended; many of the Common Lisp macros emit code which can
+be improved by optimization.  In particular, `block's (whether explicit
+or implicit in constructs like `defun*' and `loop') carry a fair
+run-time penalty; the optimizing compiler removes `block's which are
+not actually referenced by `return' or `return-from' inside the block.
+
+
+File: cl.info,  Node: Common Lisp Compatibility,  Next: Old CL Compatibility,  Prev: Efficiency Concerns,  Up: Top
+
+Common Lisp Compatibility
+*************************
+
+Following is a list of all known incompatibilities between this package
+and Common Lisp as documented in Steele (2nd edition).
+
+   Certain function names, such as `member', `assoc', and `floor', were
+already taken by (incompatible) Emacs Lisp functions; this package
+appends `*' to the names of its Common Lisp versions of these functions.
+
+   The word `defun*' is required instead of `defun' in order to use
+extended Common Lisp argument lists in a function.  Likewise,
+`defmacro*' and `function*' are versions of those forms which
+understand full-featured argument lists.  The `&whole' keyword does not
+work in `defmacro' argument lists (except inside recursive argument
+lists).
+
+   In order to allow an efficient implementation, keyword arguments use
+a slightly cheesy parser which may be confused if a keyword symbol is
+passed as the _value_ of another keyword argument.  (Specifically,
+`(memq :KEYWORD REST-OF-ARGUMENTS)' is used to scan for `:KEYWORD'
+among the supplied keyword arguments.)
+
+   The `eql' and `equal' predicates do not distinguish between IEEE
+floating-point plus and minus zero.  The `equalp' predicate has several
+differences with Common Lisp; *note Predicates::.
+
+   The `setf' mechanism is entirely compatible, except that
+setf-methods return a list of five values rather than five values
+directly.  Also, the new "`setf' function" concept (typified by `(defun
+(setf foo) ...)') is not implemented.
+
+   The `do-all-symbols' form is the same as `do-symbols' with no
+OBARRAY argument.  In Common Lisp, this form would iterate over all
+symbols in all packages.  Since Emacs obarrays are not a first-class
+package mechanism, there is no way for `do-all-symbols' to locate any
+but the default obarray.
+
+   The `loop' macro is complete except that `loop-finish' and type
+specifiers are unimplemented.
+
+   The multiple-value return facility treats lists as multiple values,
+since Emacs Lisp cannot support multiple return values directly.  The
+macros will be compatible with Common Lisp if `values' or `values-list'
+is always used to return to a `multiple-value-bind' or other
+multiple-value receiver; if `values' is used without
+`multiple-value-...' or vice-versa the effect will be different from
+Common Lisp.
+
+   Many Common Lisp declarations are ignored, and others match the
+Common Lisp standard in concept but not in detail.  For example, local
+`special' declarations, which are purely advisory in Emacs Lisp, do not
+rigorously obey the scoping rules set down in Steele's book.
+
+   The variable `*gensym-counter*' starts out with a pseudo-random
+value rather than with zero.  This is to cope with the fact that
+generated symbols become interned when they are written to and loaded
+back from a file.
+
+   The `defstruct' facility is compatible, except that structures are
+of type `:type vector :named' by default rather than some special,
+distinct type.  Also, the `:type' slot option is ignored.
+
+   The second argument of `check-type' is treated differently.
+
+
+File: cl.info,  Node: Old CL Compatibility,  Next: Porting Common Lisp,  Prev: Common Lisp Compatibility,  Up: Top
+
+Old CL Compatibility
+********************
+
+Following is a list of all known incompatibilities between this package
+and the older Quiroz `cl.el' package.
+
+   This package's emulation of multiple return values in functions is
+incompatible with that of the older package.  That package attempted to
+come as close as possible to true Common Lisp multiple return values;
+unfortunately, it could not be 100% reliable and so was prone to
+occasional surprises if used freely.  This package uses a simpler
+method, namely replacing multiple values with lists of values, which is
+more predictable though more noticeably different from Common Lisp.
+
+   The `defkeyword' form and `keywordp' function are not implemented in
+this package.
+
+   The `member', `floor', `ceiling', `truncate', `round', `mod', and
+`rem' functions are suffixed by `*' in this package to avoid collision
+with existing functions in Emacs 18 or Emacs 19.  The older package
+simply redefined these functions, overwriting the built-in meanings and
+causing serious portability problems with Emacs 19.  (Some more recent
+versions of the Quiroz package changed the names to `cl-member', etc.;
+this package defines the latter names as aliases for `member*', etc.)
+
+   Certain functions in the old package which were buggy or inconsistent
+with the Common Lisp standard are incompatible with the conforming
+versions in this package.  For example, `eql' and `member' were
+synonyms for `eq' and `memq' in that package, `setf' failed to preserve
+correct order of evaluation of its arguments, etc.
+
+   Finally, unlike the older package, this package is careful to prefix
+all of its internal names with `cl-'.  Except for a few functions which
+are explicitly defined as additional features (such as `floatp-safe'
+and `letf'), this package does not export any non-`cl-' symbols which
+are not also part of Common Lisp.
+
+
+The `cl-compat' package
+=======================
+
+The "CL" package includes emulations of some features of the old
+`cl.el', in the form of a compatibility package `cl-compat'.  To use
+it, put `(require 'cl-compat)' in your program.
+
+   The old package defined a number of internal routines without `cl-'
+prefixes or other annotations.  Call to these routines may have crept
+into existing Lisp code.  `cl-compat' provides emulations of the
+following internal routines: `pair-with-newsyms', `zip-lists',
+`unzip-lists', `reassemble-arglists', `duplicate-symbols-p',
+`safe-idiv'.
+
+   Some `setf' forms translated into calls to internal functions that
+user code might call directly.  The functions `setnth', `setnthcdr',
+and `setelt' fall in this category; they are defined by `cl-compat',
+but the best fix is to change to use `setf' properly.
+
+   The `cl-compat' file defines the keyword functions `keywordp',
+`keyword-of', and `defkeyword', which are not defined by the new "CL"
+package because the use of keywords as data is discouraged.
+
+   The `build-klist' mechanism for parsing keyword arguments is
+emulated by `cl-compat'; the `with-keyword-args' macro is not, however,
+and in any case it's best to change to use the more natural keyword
+argument processing offered by `defun*'.
+
+   Multiple return values are treated differently by the two Common
+Lisp packages.  The old package's method was more compatible with true
+Common Lisp, though it used heuristics that caused it to report
+spurious multiple return values in certain cases.  The `cl-compat'
+package defines a set of multiple-value macros that are compatible with
+the old CL package; again, they are heuristic in nature, but they are
+guaranteed to work in any case where the old package's macros worked.
+To avoid name collision with the "official" multiple-value facilities,
+the ones in `cl-compat' have capitalized names:  `Values',
+`Values-list', `Multiple-value-bind', etc.
+
+   The functions `cl-floor', `cl-ceiling', `cl-truncate', and
+`cl-round' are defined by `cl-compat' to use the old-style
+multiple-value mechanism, just as they did in the old package.  The
+newer `floor*' and friends return their two results in a list rather
+than as multiple values.  Note that older versions of the old package
+used the unadorned names `floor', `ceiling', etc.; `cl-compat' cannot
+use these names because they conflict with Emacs 19 built-ins.
+
+
+File: cl.info,  Node: Porting Common Lisp,  Next: Function Index,  Prev: Old CL Compatibility,  Up: Top
+
+Porting Common Lisp
+*******************
+
+This package is meant to be used as an extension to Emacs Lisp, not as
+an Emacs implementation of true Common Lisp.  Some of the remaining
+differences between Emacs Lisp and Common Lisp make it difficult to
+port large Common Lisp applications to Emacs.  For one, some of the
+features in this package are not fully compliant with ANSI or Steele;
+*note Common Lisp Compatibility::.  But there are also quite a few
+features that this package does not provide at all.  Here are some
+major omissions that you will want watch out for when bringing Common
+Lisp code into Emacs.
+
+   * Case-insensitivity.  Symbols in Common Lisp are case-insensitive
+     by default.  Some programs refer to a function or variable as
+     `foo' in one place and `Foo' or `FOO' in another.  Emacs Lisp will
+     treat these as three distinct symbols.
+
+     Some Common Lisp code is written in all upper-case.  While Emacs
+     is happy to let the program's own functions and variables use this
+     convention, calls to Lisp builtins like `if' and `defun' will have
+     to be changed to lower-case.
+
+   * Lexical scoping.  In Common Lisp, function arguments and `let'
+     bindings apply only to references physically within their bodies
+     (or within macro expansions in their bodies).  Emacs Lisp, by
+     contrast, uses "dynamic scoping" wherein a binding to a variable
+     is visible even inside functions called from the body.
+
+     Variables in Common Lisp can be made dynamically scoped by
+     declaring them `special' or using `defvar'.  In Emacs Lisp it is
+     as if all variables were declared `special'.
+
+     Often you can use code that was written for lexical scoping even
+     in a dynamically scoped Lisp, but not always.  Here is an example
+     of a Common Lisp code fragment that would fail in Emacs Lisp:
+
+          (defun map-odd-elements (func list)
+            (loop for x in list
+                  for flag = t then (not flag)
+                  collect (if flag x (funcall func x))))
+          
+          (defun add-odd-elements (list x)
+            (map-odd-elements (function (lambda (a) (+ a x))) list))
+
+     In Common Lisp, the two functions' usages of `x' are completely
+     independent.  In Emacs Lisp, the binding to `x' made by
+     `add-odd-elements' will have been hidden by the binding in
+     `map-odd-elements' by the time the `(+ a x)' function is called.
+
+     (This package avoids such problems in its own mapping functions by
+     using names like `cl-x' instead of `x' internally; as long as you
+     don't use the `cl-' prefix for your own variables no collision can
+     occur.)
+
+     *Note Lexical Bindings::, for a description of the `lexical-let'
+     form which establishes a Common Lisp-style lexical binding, and
+     some examples of how it differs from Emacs' regular `let'.
+
+   * Common Lisp allows the shorthand `#'x' to stand for `(function
+     x)', just as `'x' stands for `(quote x)'.  In Common Lisp, one
+     traditionally uses `#'' notation when referring to the name of a
+     function.  In Emacs Lisp, it works just as well to use a regular
+     quote:
+
+          (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp
+          (loop for x in y by 'cddr collect (mapcar 'plusp x))   ; Emacs Lisp
+
+     When `#'' introduces a `lambda' form, it is best to write out
+     `(function ...)' longhand in Emacs Lisp.  You can use a regular
+     quote, but then the byte-compiler won't know that the `lambda'
+     expression is code that can be compiled.
+
+          (mapcar #'(lambda (x) (* x 2)) list)            ; Common Lisp
+          (mapcar (function (lambda (x) (* x 2))) list)   ; Emacs Lisp
+
+     XEmacs supports `#'' notation starting with version 19.8.
+
+   * Reader macros.  Common Lisp includes a second type of macro that
+     works at the level of individual characters.  For example, Common
+     Lisp implements the quote notation by a reader macro called `'',
+     whereas Emacs Lisp's parser just treats quote as a special case.
+     Some Lisp packages use reader macros to create special syntaxes
+     for themselves, which the Emacs parser is incapable of reading.
+
+   * Other syntactic features.  Common Lisp provides a number of
+     notations beginning with `#' that the Emacs Lisp parser won't
+     understand.  For example, `#| ... |#' is an alternate comment
+     notation, and `#+lucid (foo)' tells the parser to ignore the
+     `(foo)' except in Lucid Common Lisp.
+
+     The number prefixes `#b', `#o', and `#x', however, are supported
+     by the Emacs Lisp parser to represent numbers in binary, octal,
+     and hexadecimal notation (or radix), just like in Common Lisp.
+
+   * Packages.  In Common Lisp, symbols are divided into "packages".
+     Symbols that are Lisp built-ins are typically stored in one
+     package; symbols that are vendor extensions are put in another,
+     and each application program would have a package for its own
+     symbols.  Certain symbols are "exported" by a package and others
+     are internal; certain packages "use" or import the exported symbols
+     of other packages.  To access symbols that would not normally be
+     visible due to this importing and exporting, Common Lisp provides
+     a syntax like `package:symbol' or `package::symbol'.
+
+     Emacs Lisp has a single namespace for all interned symbols, and
+     then uses a naming convention of putting a prefix like `cl-' in
+     front of the name.  Some Emacs packages adopt the Common Lisp-like
+     convention of using `cl:' or `cl::' as the prefix.  However, the
+     Emacs parser does not understand colons and just treats them as
+     part of the symbol name.  Thus, while `mapcar' and `lisp:mapcar'
+     may refer to the same symbol in Common Lisp, they are totally
+     distinct in Emacs Lisp.  Common Lisp programs which refer to a
+     symbol by the full name sometimes and the short name other times
+     will not port cleanly to Emacs.
+
+     Emacs Lisp does have a concept of "obarrays," which are
+     package-like collections of symbols, but this feature is not
+     strong enough to be used as a true package mechanism.
+
+   * Keywords.  The notation `:test-not' in Common Lisp really is a
+     shorthand for `keyword:test-not'; keywords are just symbols in a
+     built-in `keyword' package with the special property that all its
+     symbols are automatically self-evaluating.  Common Lisp programs
+     often use keywords liberally to avoid having to use quotes.
+
+     In Emacs Lisp a keyword is just a symbol whose name begins with a
+     colon; since the Emacs parser does not treat them specially, they
+     have to be explicitly made self-evaluating by a statement like
+     `(setq :test-not ':test-not)'.  This package arranges to execute
+     such a statement whenever `defun*' or some other form sees a
+     keyword being used as an argument.  Common Lisp code that assumes
+     that a symbol `:mumble' will be self-evaluating even though it was
+     never introduced by a `defun*' will have to be fixed.
+
+   * The `format' function is quite different between Common Lisp and
+     Emacs Lisp.  It takes an additional "destination" argument before
+     the format string.  A destination of `nil' means to format to a
+     string as in Emacs Lisp; a destination of `t' means to write to
+     the terminal (similar to `message' in Emacs).  Also, format
+     control strings are utterly different; `~' is used instead of `%'
+     to introduce format codes, and the set of available codes is much
+     richer.  There are no notations like `\n' for string literals;
+     instead, `format' is used with the "newline" format code, `~%'.
+     More advanced formatting codes provide such features as paragraph
+     filling, case conversion, and even loops and conditionals.
+
+     While it would have been possible to implement most of Common Lisp
+     `format' in this package (under the name `format*', of course), it
+     was not deemed worthwhile.  It would have required a huge amount
+     of code to implement even a decent subset of `format*', yet the
+     functionality it would provide over Emacs Lisp's `format' would
+     rarely be useful.
+
+   * Vector constants use square brackets in Emacs Lisp, but `#(a b c)'
+     notation in Common Lisp.  To further complicate matters, Emacs 19
+     introduces its own `#(' notation for something entirely
+     different--strings with properties.
+
+   * Characters are distinct from integers in Common Lisp.  The
+     notation for character constants is also different:  `#\A' instead
+     of `?A'.  Also, `string=' and `string-equal' are synonyms in Emacs
+     Lisp whereas the latter is case-insensitive in Common Lisp.
+
+   * Data types.  Some Common Lisp data types do not exist in Emacs
+     Lisp.  Rational numbers and complex numbers are not present, nor
+     are large integers (all integers are "fixnums").  All arrays are
+     one-dimensional.  There are no readtables or pathnames; streams
+     are a set of existing data types rather than a new data type of
+     their own.  Hash tables, random-states, structures, and packages
+     (obarrays) are built from Lisp vectors or lists rather than being
+     distinct types.
+
+   * The Common Lisp Object System (CLOS) is not implemented, nor is
+     the Common Lisp Condition System.
+
+   * Common Lisp features that are completely redundant with Emacs Lisp
+     features of a different name generally have not been implemented.
+     For example, Common Lisp writes `defconstant' where Emacs Lisp
+     uses `defconst'.  Similarly, `make-list' takes its arguments in
+     different ways in the two Lisps but does exactly the same thing,
+     so this package has not bothered to implement a Common Lisp-style
+     `make-list'.
+
+   * A few more notable Common Lisp features not included in this
+     package:  `compiler-let', `tagbody', `prog', `ldb/dpb',
+     `parse-integer', `cerror'.
+
+   * Recursion.  While recursion works in Emacs Lisp just like it does
+     in Common Lisp, various details of the Emacs Lisp system and
+     compiler make recursion much less efficient than it is in most
+     Lisps.  Some schools of thought prefer to use recursion in Lisp
+     over other techniques; they would sum a list of numbers using
+     something like
+
+          (defun sum-list (list)
+            (if list
+                (+ (car list) (sum-list (cdr list)))
+              0))
+
+     where a more iteratively-minded programmer might write one of
+     these forms:
+
+          (let ((total 0)) (dolist (x my-list) (incf total x)) total)
+          (loop for x in my-list sum x)
+
+     While this would be mainly a stylistic choice in most Common Lisps,
+     in Emacs Lisp you should be aware that the iterative forms are
+     much faster than recursion.  Also, Lisp programmers will want to
+     note that the current Emacs Lisp compiler does not optimize tail
+     recursion.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/cl.info-6'
Index: ././info/cl.info-6
--- ././info/cl.info-6	Thu Jan  1 09:00:00 1970
+++ ././info/cl.info-6	Thu May 17 23:26:51 2001
@@ -0,0 +1,245 @@
+This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Common Lisp: (cl).		GNU Emacs Common Lisp emulation package.
+END-INFO-DIR-ENTRY
+
+   This file documents the GNU Emacs Common Lisp emulation package.
+
+   Copyright (C) 1993 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the author instead of in
+the original English.
+
+
+File: cl.info,  Node: Function Index,  Next: Variable Index,  Prev: Porting Common Lisp,  Up: Top
+
+Function Index
+**************
+
+* Menu:
+
+* abs:                                   Numerical Functions.
+* acons:                                 Association Lists.
+* adjoin:                                Lists as Sets.
+* assert:                                Assertions.
+* assoc*:                                Association Lists.
+* assoc-if:                              Association Lists.
+* assoc-if-not:                          Association Lists.
+* block:                                 Blocks and Exits.
+* butlast:                               List Functions.
+* caddr:                                 List Functions.
+* callf:                                 Modify Macros.
+* callf2:                                Modify Macros.
+* case:                                  Conditionals.
+* ceiling*:                              Numerical Functions.
+* check-type:                            Assertions.
+* cl-float-limits:                       Implementation Parameters.
+* cl-prettyexpand:                       Efficiency Concerns.
+* coerce:                                Type Predicates.
+* compiler-macroexpand:                  Macros.
+* concatenate:                           Sequence Functions.
+* copy-list:                             List Functions.
+* copy-tree:                             List Functions.
+* count:                                 Searching Sequences.
+* count-if:                              Searching Sequences.
+* count-if-not:                          Searching Sequences.
+* decf:                                  Modify Macros.
+* declaim:                               Declarations.
+* declare:                               Declarations.
+* defalias:                              Function Aliases.
+* define-compiler-macro:                 Macros.
+* define-modify-macro:                   Customizing Setf.
+* define-setf-method:                    Customizing Setf.
+* defmacro*:                             Argument Lists.
+* defsetf:                               Customizing Setf.
+* defstruct:                             Structures.
+* defsubst*:                             Argument Lists.
+* deftype:                               Type Predicates.
+* defun*:                                Argument Lists.
+* delete:                                Sequence Functions.
+* delete*:                               Sequence Functions.
+* delete-duplicates:                     Sequence Functions.
+* delete-if:                             Sequence Functions.
+* delete-if-not:                         Sequence Functions.
+* destructuring-bind:                    Macros.
+* do:                                    Iteration.
+* do*:                                   Iteration.
+* do-all-symbols:                        Iteration.
+* do-symbols:                            Iteration.
+* dolist:                                Iteration.
+* dotimes:                               Iteration.
+* ecase:                                 Conditionals.
+* endp:                                  List Functions.
+* eql:                                   Equality Predicates.
+* equalp:                                Equality Predicates.
+* etypecase:                             Conditionals.
+* eval-when:                             Time of Evaluation.
+* eval-when-compile:                     Time of Evaluation.
+* evenp:                                 Predicates on Numbers.
+* every:                                 Mapping over Sequences.
+* expt:                                  Numerical Functions.
+* fill:                                  Sequence Functions.
+* find:                                  Searching Sequences.
+* find-if:                               Searching Sequences.
+* find-if-not:                           Searching Sequences.
+* first:                                 List Functions.
+* flet:                                  Function Bindings.
+* floatp-safe:                           Predicates on Numbers.
+* floor*:                                Numerical Functions.
+* function*:                             Argument Lists.
+* gcd:                                   Numerical Functions.
+* gensym:                                Creating Symbols.
+* gentemp:                               Creating Symbols.
+* get-setf-method:                       Customizing Setf.
+* getf:                                  Property Lists.
+* ignore-errors:                         Assertions.
+* incf:                                  Modify Macros.
+* intersection:                          Lists as Sets.
+* isqrt:                                 Numerical Functions.
+* labels:                                Function Bindings.
+* last:                                  List Functions.
+* lcm:                                   Numerical Functions.
+* ldiff:                                 List Functions.
+* letf:                                  Modify Macros.
+* letf*:                                 Modify Macros.
+* lexical-let:                           Lexical Bindings.
+* lexical-let*:                          Lexical Bindings.
+* list*:                                 List Functions.
+* list-length:                           List Functions.
+* load-time-value:                       Time of Evaluation.
+* locally:                               Declarations.
+* loop <1>:                              Loop Basics.
+* loop:                                  Iteration.
+* macrolet:                              Macro Bindings.
+* make-random-state:                     Random Numbers.
+* map:                                   Mapping over Sequences.
+* mapc:                                  Mapping over Sequences.
+* mapcan:                                Mapping over Sequences.
+* mapcar*:                               Mapping over Sequences.
+* mapcon:                                Mapping over Sequences.
+* mapl:                                  Mapping over Sequences.
+* maplist:                               Mapping over Sequences.
+* member:                                Lists as Sets.
+* member*:                               Lists as Sets.
+* member-if:                             Lists as Sets.
+* member-if-not:                         Lists as Sets.
+* merge:                                 Sorting Sequences.
+* minusp:                                Predicates on Numbers.
+* mismatch:                              Searching Sequences.
+* mod*:                                  Numerical Functions.
+* multiple-value-bind:                   Multiple Values.
+* multiple-value-setq:                   Multiple Values.
+* nbutlast:                              List Functions.
+* nintersection:                         Lists as Sets.
+* notany:                                Mapping over Sequences.
+* notevery:                              Mapping over Sequences.
+* nset-difference:                       Lists as Sets.
+* nset-exclusive-or:                     Lists as Sets.
+* nsublis:                               Substitution of Expressions.
+* nsubst:                                Substitution of Expressions.
+* nsubst-if:                             Substitution of Expressions.
+* nsubst-if-not:                         Substitution of Expressions.
+* nsubstitute:                           Sequence Functions.
+* nsubstitute-if:                        Sequence Functions.
+* nsubstitute-if-not:                    Sequence Functions.
+* nunion:                                Lists as Sets.
+* oddp:                                  Predicates on Numbers.
+* pairlis:                               Association Lists.
+* plusp:                                 Predicates on Numbers.
+* pop:                                   Modify Macros.
+* position:                              Searching Sequences.
+* position-if:                           Searching Sequences.
+* position-if-not:                       Searching Sequences.
+* proclaim:                              Declarations.
+* progv:                                 Dynamic Bindings.
+* psetf:                                 Modify Macros.
+* psetq:                                 Assignment.
+* push:                                  Modify Macros.
+* pushnew:                               Modify Macros.
+* random*:                               Random Numbers.
+* random-state-p:                        Random Numbers.
+* rassoc:                                Association Lists.
+* rassoc*:                               Association Lists.
+* rassoc-if:                             Association Lists.
+* rassoc-if-not:                         Association Lists.
+* reduce:                                Mapping over Sequences.
+* rem*:                                  Numerical Functions.
+* remf:                                  Property Lists.
+* remove:                                Sequence Functions.
+* remove*:                               Sequence Functions.
+* remove-duplicates:                     Sequence Functions.
+* remove-if:                             Sequence Functions.
+* remove-if-not:                         Sequence Functions.
+* remq:                                  Sequence Functions.
+* replace:                               Sequence Functions.
+* rest:                                  List Functions.
+* return:                                Blocks and Exits.
+* return-from:                           Blocks and Exits.
+* rotatef:                               Modify Macros.
+* round*:                                Numerical Functions.
+* search:                                Searching Sequences.
+* set-difference:                        Lists as Sets.
+* set-exclusive-or:                      Lists as Sets.
+* setf:                                  Basic Setf.
+* shiftf:                                Modify Macros.
+* some:                                  Mapping over Sequences.
+* sort*:                                 Sorting Sequences.
+* stable-sort:                           Sorting Sequences.
+* sublis:                                Substitution of Expressions.
+* subseq:                                Sequence Functions.
+* subsetp:                               Lists as Sets.
+* subst:                                 Substitution of Expressions.
+* subst-if:                              Substitution of Expressions.
+* subst-if-not:                          Substitution of Expressions.
+* substitute:                            Sequence Functions.
+* substitute-if:                         Sequence Functions.
+* substitute-if-not:                     Sequence Functions.
+* symbol-macrolet:                       Macro Bindings.
+* tailp:                                 Lists as Sets.
+* the:                                   Declarations.
+* tree-equal:                            List Functions.
+* truncate*:                             Numerical Functions.
+* typecase:                              Conditionals.
+* typep:                                 Type Predicates.
+* union:                                 Lists as Sets.
+* unless:                                Conditionals.
+* when:                                  Conditionals.
+
+
+File: cl.info,  Node: Variable Index,  Prev: Function Index,  Up: Top
+
+Variable Index
+**************
+
+* Menu:
+
+* *gensym-counter*:                      Creating Symbols.
+* *random-state*:                        Random Numbers.
+* float-epsilon:                         Implementation Parameters.
+* float-negative-epsilon:                Implementation Parameters.
+* least-negative-float:                  Implementation Parameters.
+* least-negative-normalized-float:       Implementation Parameters.
+* least-positive-float:                  Implementation Parameters.
+* least-positive-normalized-float:       Implementation Parameters.
+* most-negative-fixnum:                  Implementation Parameters.
+* most-negative-float:                   Implementation Parameters.
+* most-positive-fixnum:                  Implementation Parameters.
+* most-positive-float:                   Implementation Parameters.
+
+
diff --text -u /dev/null 'xemacs-21.4.3/info/custom.info'
Index: ././info/custom.info
--- ././info/custom.info	Thu Jan  1 09:00:00 1970
+++ ././info/custom.info	Thu May 17 23:26:51 2001
@@ -0,0 +1,393 @@
+This is ../info/custom.info, produced by makeinfo version 4.0 from
+custom.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Customizations: (custom).	Customization Library.
+END-INFO-DIR-ENTRY
+
+
+File: custom.info,  Node: Top,  Next: Declaring Groups,  Prev: (dir),  Up: (dir)
+
+The Customization Library
+*************************
+
+   This manual describes how to declare customization groups, variables,
+and faces.  It doesn't contain any examples, but please look at the file
+`cus-edit.el' which contains many declarations you can learn from.
+
+* Menu:
+
+* Declaring Groups::
+* Declaring Variables::
+* Declaring Faces::
+* Usage for Package Authors::
+* Utilities::
+* The Init File::
+* Wishlist::
+
+   All the customization declarations can be changes by keyword
+arguments.  Groups, variables, and faces all share these common
+keywords:
+
+`:group'
+     VALUE should be a customization group.  Add SYMBOL to that group.
+
+`:link'
+     VALUE should be a widget type.  Add VALUE to the external links
+     for this customization option.  Useful widget types include
+     `custom-manual', `info-link', and `url-link'.
+
+`:load'
+     Add VALUE to the files that should be loaded before displaying
+     this customization option.  The value should be either a string,
+     which should be a string which will be loaded with `load-library'
+     unless present in `load-history', or a symbol which will be loaded
+     with `require'.
+
+`:tag'
+     VALUE should be a short string used for identifying the option in
+     customization menus and buffers.  By default the tag will be
+     automatically created from the options name.
+
+
+File: custom.info,  Node: Declaring Groups,  Next: Declaring Variables,  Prev: Top,  Up: Top
+
+Declaring Groups
+================
+
+   Use `defgroup' to declare new customization groups.
+
+ - Function: defgroup symbol members doc [keyword value]...
+     Declare SYMBOL as a customization group containing MEMBERS.
+     SYMBOL does not need to be quoted.
+
+     DOC is the group documentation.
+
+     MEMBERS should be an alist of the form ((NAME WIDGET)...) where
+     NAME is a symbol and WIDGET is a widget for editing that symbol.
+     Useful widgets are `custom-variable' for editing variables,
+     `custom-face' for editing faces, and `custom-group' for editing
+     groups.
+
+     Internally, custom uses the symbol property `custom-group' to keep
+     track of the group members, and `group-documentation' for the
+     documentation string.
+
+     The following additional KEYWORD's are defined:
+
+    `:prefix'
+          VALUE should be a string.  If the string is a prefix for the
+          name of a member of the group, that prefix will be ignored
+          when creating a tag for that member.
+
+
+File: custom.info,  Node: Declaring Variables,  Next: Declaring Faces,  Prev: Declaring Groups,  Up: Top
+
+Declaring Variables
+===================
+
+   Use `defcustom' to declare user editable variables.
+
+ - Function: defcustom symbol value doc [keyword value]...
+     Declare SYMBOL as a customizable variable that defaults to VALUE.
+     Neither SYMBOL nor VALUE needs to be quoted.  If SYMBOL is not
+     already bound, initialize it to VALUE.
+
+     DOC is the variable documentation.
+
+     The following additional KEYWORD's are defined:
+
+    `:type'
+          VALUE should be a widget type.
+
+    `:options'
+          VALUE should be a list of possible members of the specified
+          type.  For hooks, this is a list of function names.
+
+    `:initialize'
+          VALUE should be a function used to initialize the variable.
+          It takes two arguments, the symbol and value given in the
+          `defcustom' call.  Some predefined functions are:
+
+         `custom-initialize-set'
+               Use the `:set' method to initialize the variable.  Do not
+               initialize it if already bound.  This is the default
+               `:initialize' method.
+
+         `custom-initialize-default'
+               Always use `set-default' to initialize the variable,
+               even if a `:set' method has been specified.
+
+         `custom-initialize-reset'
+               If the variable is already bound, reset it by calling
+               the `:set' method with the value returned by the `:get'
+               method.
+
+         `custom-initialize-changed'
+               Like `custom-initialize-reset', but use `set-default' to
+               initialize the variable if it is not bound and has not
+               been set already.
+
+    `:set'
+          VALUE should be a function to set the value of the symbol.  It
+          takes two arguments, the symbol to set and the value to give
+          it.  The default is `set-default'.
+
+    `:get'
+          VALUE should be a function to extract the value of symbol.
+          The function takes one argument, a symbol, and should return
+          the current value for that symbol.  The default is
+          `default-value'.
+
+    `:require'
+          VALUE should be a feature symbol.  Each feature will be
+          required when the `defcustom' is evaluated, or when Emacs is
+          started if the user has saved this option.
+
+     *Note Sexp Types: (widget)Sexp Types, for information about
+     widgets to use together with the `:type' keyword.
+
+   Internally, custom uses the symbol property `custom-type' to keep
+track of the variables type, `standard-value' for the program specified
+default value, `saved-value' for a value saved by the user, and
+`variable-documentation' for the documentation string.
+
+   Use `custom-add-option' to specify that a specific function is
+useful as an member of a hook.
+
+ - Function: custom-add-option symbol option
+     To the variable SYMBOL add OPTION.
+
+     If SYMBOL is a hook variable, OPTION should be a hook member.  For
+     other types variables, the effect is undefined."
+
+
+File: custom.info,  Node: Declaring Faces,  Next: Usage for Package Authors,  Prev: Declaring Variables,  Up: Top
+
+Declaring Faces
+===============
+
+   Faces are declared with `defface'.
+
+ - Function: defface face spec doc [keyword value]...
+     Declare FACE as a customizable face that defaults to SPEC.  FACE
+     does not need to be quoted.
+
+     If FACE has been set with `custom-set-face', set the face
+     attributes as specified by that function, otherwise set the face
+     attributes according to SPEC.
+
+     DOC is the face documentation.
+
+     SPEC should be an alist of the form `((DISPLAY ATTS)...)'.
+
+     ATTS is a list of face attributes and their values.  The possible
+     attributes are defined in the variable `custom-face-attributes'.
+
+     The ATTS of the first entry in SPEC where the DISPLAY matches the
+     frame should take effect in that frame.  DISPLAY can either be the
+     symbol `t', which will match all frames, or an alist of the form
+     `((REQ ITEM...)...)'
+
+     For the DISPLAY to match a FRAME, the REQ property of the frame
+     must match one of the ITEM.  The following REQ are defined:
+
+    `type'
+          (the value of (window-system))
+          Should be one of `x' or `tty'.
+
+    `class'
+          (the frame's color support)
+          Should be one of `color', `grayscale', or `mono'.
+
+    `background'
+          (what color is used for the background text)
+          Should be one of `light' or `dark'.
+
+     Internally, custom uses the symbol property `face-defface-spec' for
+     the program specified default face properties, `saved-face' for
+     properties saved by the user, and `face-documentation' for the
+     documentation string.
+
+
+
+File: custom.info,  Node: Usage for Package Authors,  Next: Utilities,  Prev: Declaring Faces,  Up: Top
+
+Usage for Package Authors
+=========================
+
+   The recommended usage for the author of a typical emacs lisp package
+is to create one group identifying the package, and make all user
+options and faces members of that group.  If the package has more than
+around 20 such options, they should be divided into a number of
+subgroups, with each subgroup being member of the top level group.
+
+   The top level group for the package should itself be member of one or
+more of the standard customization groups.  There exists a group for
+each _finder_ keyword.  Press `C-h p' to see a list of finder keywords,
+and add you group to each of them, using the `:group' keyword.
+
+
+File: custom.info,  Node: Utilities,  Next: The Init File,  Prev: Usage for Package Authors,  Up: Top
+
+Utilities
+=========
+
+   These utilities can come in handy when adding customization support.
+
+ - Widget: custom-manual
+     Widget type for specifying the info manual entry for a
+     customization option.  It takes one argument, an info address.
+
+ - Function: custom-add-to-group group member widget
+     To existing GROUP add a new MEMBER of type WIDGET, If there
+     already is an entry for that member, overwrite it.
+
+ - Function: custom-add-link symbol widget
+     To the custom option SYMBOL add the link WIDGET.
+
+ - Function: custom-add-load symbol load
+     To the custom option SYMBOL add the dependency LOAD.  LOAD should
+     be either a library file name, or a feature name.
+
+ - Function: customize-menu-create symbol &optional name
+     Create menu for customization group SYMBOL.  If optional NAME is
+     given, use that as the name of the menu.  Otherwise the menu will
+     be named `Customize'.  The menu is in a format applicable to
+     `easy-menu-define'.
+
+
+File: custom.info,  Node: The Init File,  Next: Wishlist,  Prev: Utilities,  Up: Top
+
+The Init File
+=============
+
+   When you save the customizations, call to `custom-set-variables',
+`custom-set-faces' are inserted into the file specified by
+`custom-file'.  By default `custom-file' is your `.emacs' file.  If you
+use another file, you must explicitly load it yourself.  The two
+functions will initialize variables and faces as you have specified.
+
+
+File: custom.info,  Node: Wishlist,  Prev: The Init File,  Up: Top
+
+Wishlist
+========
+
+   * Better support for keyboard operations in the customize buffer.
+
+   * Integrate with `w3' so you can get customization buffers with much
+     better formatting.  I'm thinking about adding a
+     <custom>name</custom> tag.  The latest w3 have some support for
+     this, so come up with a convincing example.
+
+   * Add an `examples' section, with explained examples of custom type
+     definitions.
+
+   * Support selectable color themes.  I.e., change many faces by
+     setting one variable.
+
+   * Support undo using lmi's `gnus-undo.el'.
+
+   * Make it possible to append to `choice', `radio', and `set' options.
+
+   * Ask whether set or modified variables should be saved in
+     `kill-buffer-hook'.
+
+     Ditto for `kill-emacs-query-functions'.
+
+   * Command to check if there are any customization options that does
+     not belong to an existing group.
+
+   * Optionally disable the point-cursor and instead highlight the
+     selected item in XEmacs.  This is like the *Completions* buffer in
+     XEmacs.  Suggested by Jens Lautenbacher
+     `<jens@lemming0.lem.uni-karlsruhe.de>'.
+
+   * Explain why it is necessary that all choices have different default
+     values.
+
+   * Add some direct support for meta variables, i.e. make it possible
+     to specify that this variable should be reset when that variable is
+     changed.
+
+   * Add tutorial.
+
+   * Describe the `:type' syntax in this manual.
+
+   * Find a place is this manual for the following text:
+
+     *Radio vs. Buttons*
+
+     Use a radio if you can't find a good way to describe the item in
+     the choice menu text.  I.e. it is better to use a radio if you
+     expect the user would otherwise manually select each item from the
+     choice menu in turn to see what it expands too.
+
+     Avoid radios if some of the items expands to complex structures.
+
+     I mostly use radios when most of the items are of type
+     `function-item' or `variable-item'.
+
+   * Update customize buffers when `custom-set-variable' or
+     `custom-save-customized' is called.
+
+   * Better handling of saved but uninitialized items.
+
+   * Detect when faces have been changed outside customize.
+
+   * Enable mouse help in Emacs by default.
+
+   * Add an easy way to display the standard settings when an item is
+     modified.
+
+   * See if it is feasible to scan files for customization information
+     instead of loading them,
+
+   * Add hint message when user push a non-pushable tag.
+
+     Suggest that the user unhide if hidden, and edit the value directly
+     otherwise.
+
+   * Use checkboxes and radio buttons in the state menus.
+
+   * Add option to hide `[hide]' for short options.  Default, on.
+
+   * Add option to hide `[state]' for options with their standard
+     settings.
+
+   * There should be a way to specify site defaults for user options.
+
+   * There should be more buffer styles.  The default `nested style,
+     the old `outline' style, a `numeric' style with numbers instead of
+     stars, an `empty' style with just the group name, and `compact'
+     with only one line per item.
+
+   * Newline and tab should be displayed as `^J' and `^I' in the
+     `regexp' and `file' widgets.  I think this can be done in XEmacs
+     by adding a display table to the face.
+
+   * Use glyphs to draw the `customize-browse' tree.
+
+     Add echo and balloon help.  You should be able to read the
+     documentation simply by moving the mouse pointer above the name.
+
+     Add parent links.
+
+     Add colors.
+
+
+
+
+Tag Table:
+Node: Top204
+Node: Declaring Groups1625
+Node: Declaring Variables2726
+Node: Declaring Faces5817
+Node: Usage for Package Authors7515
+Node: Utilities8294
+Node: The Init File9378
+Node: Wishlist9830
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/emodules.info'
Index: ././info/emodules.info
--- ././info/emodules.info	Thu Jan  1 09:00:00 1970
+++ ././info/emodules.info	Thu May 17 23:26:51 2001
@@ -0,0 +1,959 @@
+This is ../info/emodules.info, produced by makeinfo version 4.0 from
+emodules.texi.
+
+   This file documents the module loading technology of XEmacs.
+
+   Copyright (C) 1998 J. Kean Johnston.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: emodules.info,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
+
+   This Info file contains v1.0 of the XEmacs dynamic loadable module
+support documentation.
+
+* Menu:
+
+* Introduction::                Introducing Emacs Modules
+* 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
+* Index::                       Concept Index
+
+ --- The Detailed Node Listing ---
+
+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
+* Loading other Modules::       How to load dependent modules
+
+Using `ellcc'
+
+* Compile Mode::                Compiling modules using ellcc
+* Initialization Mode::         Generating documentation and variables
+* Link Mode::                   Creating the final loadable module
+* Other ellcc options::         Other useful options
+* Environment Variables::       How to control ellcc
+
+Defining Functions
+
+* Using DEFUN::                 Using the DEFUN macro to define functions
+* Declaring Functions::         Declaring functions to the Lisp reader
+
+
+File: emodules.info,  Node: Introduction,  Next: Anatomy of a Module,  Prev: Top,  Up: Top
+
+Introduction
+************
+
+   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 XEmacs in more
+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.
+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.
+
+   Secondly, Elisp (or Lisp in general) is not a very common language
+any more, except for certain circles in the computer industry.  C is a
+far more commonly known language, and because it is compiled, more
+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
+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".
+
+   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 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 developers
+perspective though, a lot more is provided.
+
+   *   Of primary interest is the `ellcc' program.  This program is
+     created during compile time, and is intended 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.  `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 XEmacs internal
+     header files etc.  The program will also invoke the linker
+     correctly to created the final shared object which is loaded into
+     XEmacs.
+
+   *   CEmacs also makes all of the relevant XEmacs internal header
+     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
+     modules, most of the internals of XEmacs are exposed.  *Note Top:
+     (internals)Top, for a more complete discussion on how to extend
+     and understand XEmacs.  All of the rules for C modules are
+     discussed there.
+
+   *   Part of the XEmacs distribution is a set of sample modules.
+     These are not installed when XEmacs is, but remain in the XEmacs
+     source tree.  These modules live in the directory `modules', which
+     is a sub-directory of the main XEmacs source code directory.
+     Please look at the samples carefully, and maybe even use them as a
+     basis for making your own modules.  Most of the concepts required
+     for writing extension modules are covered in the samples.
+
+   *   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 XEmacs in C.  If you do not find this
+     to be the case, please contact the author(s).
+
+   The rest of this document will discuss the actual mechanics of
+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
+should be considered the final authority.  It will also help a great
+deal to look at the actual XEmacs source code to see how things are
+done.
+
+
+File: emodules.info,  Node: Anatomy of a Module,  Next: Using ellcc,  Prev: Introduction,  Up: Top
+
+Anatomy of a Module
+*******************
+
+   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
+`modules/simple/sample.c' in the main XEmacs source code tree.
+
+* Menu:
+
+* 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 dependent modules
+
+
+File: emodules.info,  Node: Required Header File,  Next: Required Functions,  Prev: Anatomy of a Module,  Up: Anatomy of a Module
+
+Required Header File
+====================
+
+   Every module must include the file `<emodules.h>'.  This will
+include several other XEmacs internal header files, and will set up
+certain vital macros.  One of the most important files included by
+`emodules.h' is the generated `config.h' file, which contains all of
+the required system abstraction macros and definitions.  Most modules
+will probably require some pre-processor conditionals based on
+constants defined in `config.h'.  Please read that file to 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 XEmacs internal header
+files.  When you `#include <emodules.h>', you will get a few of the
+most important XEmacs header files included automatically for you.  The
+files included are:
+
+`lisp.h'
+     This file contains most of the macros required for declaring Lisp
+     object types, macros for accessing Lisp objects, and global
+     variable declarations.
+
+`sysdep.h'
+     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.
+
+`window.h'
+     This header file defines the window structures and Lisp types, and
+     provides functions and macros for manipulating multiple XEmacs
+     windows.
+
+`buffer.h'
+     All macros and function declarations for manipulating internal and
+     user visible buffers appear in this file.
+
+`insdel.h'
+     This header provides the information required for performing text
+     insertion and deletion.
+
+`frame.h'
+     Provides the required structure, macro and function definitions for
+     manipulating XEmacs frames.
+
+
+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
+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.
+Here, briefly, are the required module functions.  Note that the actual
+function names do not end with the string `_module', but rather they
+end with the abbreviated module name by which the module is known.
+More on the module name and its importance later.  Just bear in mind
+that the text `_module' in the functions below is simply a
+place-holder, not an actual function name.
+
+`syms_of_module'
+     This required function is responsible for introducing to the Lisp
+     reader all functions that you have defined in your module using
+     `DEFUN()'.  Note that _only_ functions are declared here, using
+     the `DEFSUBR()' macro.  No variables are declared.
+
+`vars_of_module'
+     This required function contains calls to macros such as
+     `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.  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
+     your 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.
+
+`docs_of_module'
+     This is a required function, but not one which you need ever write.
+     This function is created automatically by `ellcc' when the module
+     initialization code is produced.  It is required to document all
+     functions and variables declared in your module.
+
+
+File: emodules.info,  Node: Required Variables,  Next: Loading other Modules,  Prev: Required Functions,  Up: Anatomy of a Module
+
+Required Variables
+==================
+
+   Not only does a module need to declare the initialization functions
+mentioned above, it is also required to provide certain variables which
+the module loading code searches for in order to determine the viability
+of a module.  You are _not_ required to provide these variables in your
+source files.  They are automatically set up in the module
+initialization file by the `ellcc' compiler.  These variables are
+discussed here simply for the sake of completeness.
+
+`emodules_compiler'
+     This is a variable of type `long', and is used to indicate the
+     version of the XEmacs loading technology that was used to produce
+     the module being loaded.  This version number is completely
+     unrelated to 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 XEmacs modules version is used to differentiate between major
+     changes in the module loading technology, not versions of XEmacs.
+
+`emodules_name'
+     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
+     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
+     function name.  The value of this variable is appended to the
+     function names `syms_of_', `vars_of_', `modules_of_' and
+     `docs_of_' to form the actual function names that the module
+     loading code looks for when loading a module.
+
+     This variable is set by the `--mod-name' argument to `ellcc'.
+
+`emodules_version'
+     This string variable is used to load specific versions of a module.
+     Rarely will two or more versions of a module be left lying around,
+     but just in case this does happen, this variable can be used to
+     control exactly which module should be loaded.  See the Lisp
+     function `load-module' for more details.  This variable is set by
+     the `--mod-version' argument to `ellcc'.
+
+`emodules_title'
+     This is a string which describes the module, and can contain
+     spaces or other special characters.  It is used solely for
+     descriptive purposes, and does not affect the loading of the
+     module.  The value is set by the `--mod-title' argument to `ellcc'.
+
+
+File: emodules.info,  Node: Loading other Modules,  Prev: Required Variables,  Up: Anatomy of a Module
+
+Loading other Modules
+=====================
+
+   During the loading of a module, it is the responsibility of the
+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 dependencies, it must call
+`emodules_load':
+
+     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.
+If you do not specify an absolute path name, then the same rules as
+apply to loading Lisp modules are applied when searching for the
+module.  If the module cannot be found in any of the standard places,
+and an absolute path name was not specified, `emodules_load' will
+signal an error and loading of the module will stop.
+
+   The second argument (MODNAME) is the module name to load, and must
+match the contents of the variable EMODULE_NAME in the module to be
+loaded. A mis-match will cause the module load to fail.  If this
+parameter is `NULL' or empty, then no checks are performed against the
+target module's EMODULE_NAME variable.
+
+   The last argument, MODVER, is the desired version of the module to
+load, and is compared to the target module's EMODULE_VERSION value.  If
+this parameter is not `NULL' or empty, and the match fails, then the
+load of the module will fail.
+
+   `emodules_load' can be called recursively.  If, at any point during
+the loading of modules a failure is encountered, then all modules that
+were loaded since the top level call to `emodules_load' will be
+unloaded.  This means that if any child modules fail to load, then
+their parents will also fail to load.  This does not include previous
+successful calls to `emodules_load' at the top level.
+
+
+File: emodules.info,  Node: Using ellcc,  Next: Defining Functions,  Prev: Anatomy of a Module,  Up: Top
+
+Using `ellcc'
+*************
+
+   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 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.
+
+   XEmacs now ships with a new user utility, called `ellcc'.  This is
+the "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 line
+options, this program can be considered a replacement for your C
+compiler.  It accepts all of the same flags and arguments that your C
+compiler does, so in many cases you can simply set the `make' variable
+`CC' to `ellcc' and your code will be compiled as an Emacs module
+rather than a static C object.
+
+   `ellcc' has three distinct modes of operation.  It can be run in
+compile, link or initialization mode.  These modes are discussed in more
+detail below.  If you want `ellcc' to show the commands it is
+executing, you can specify the option `--mode=verbose' to `ellcc'.
+Specifying this option twice will enable certain extra debugging
+messages to be displayed on the standard output.
+
+* Menu:
+
+* Compile Mode::                Compiling modules using ellcc
+* Initialization Mode::         Generating documentation and variables
+* Link Mode::                   Creating the final loadable module
+* Other ellcc options::         Other useful options
+* Environment Variables::       How to control ellcc
+
+
+File: emodules.info,  Node: Compile Mode,  Next: Initialization Mode,  Prev: Using ellcc,  Up: Using ellcc
+
+Compile Mode
+============
+
+   By default, `ellcc' is in "compile" mode.  This means that it
+assumes that all of the command line arguments are C compiler arguments,
+and that you want to compile the specified source file or files.  You
+can force compile mode by specifying the `--mode=compile' argument to
+`ellcc'.
+
+   In this mode, `ellcc' is simply a front-end to the same C compiler
+that was used to create the XEmacs binary itself.  All `ellcc' does in
+this mode is insert a few extra command line arguments before the
+arguments you specify to `ellcc' itself.  `ellcc' will then invoke the
+C compiler to compile your module, and will return the same exit codes
+and messages that your C compiler does.
+
+   By far the easiest way to compile modules is to construct a
+`Makefile' as you would for a normal program, and simply insert, at
+some appropriate place something similar to:
+
+     CC=ellcc --mode=compile
+     
+     .c.o:
+         $(CC) $(CFLAGS) -c $<
+
+   After this, all you need to do is provide simple `make' rules for
+compiling your module source files.  Since modules are most useful when
+they are small and self-contained, most modules will have a single
+source file, aside from the module specific initialization file (see
+below for details).
+
+
+File: emodules.info,  Node: Initialization Mode,  Next: Link Mode,  Prev: Compile Mode,  Up: Using ellcc
+
+Initialization Mode
+===================
+
+   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
+`make-docfile', is used to scan the source code files and extract the
+documentation from these comments, producing the XEmacs `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 XEmacs has been "dumped" is
+somewhat problematic.  Fortunately, as a module writer you are insulated
+from the difficulties thanks to your friend `ellcc' and some internal
+trickery in the module loading code.  This is all done using the
+"initialization" mode of `ellcc'.
+
+   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 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'.
+
+   Next, you need to specify the name of the C source code file that
+`ellcc' will produce, and you specify this using the
+`--mod-output=FILENAME' argument.  FILENAME is the name of the C source
+code file that will contain the module variables and `docs_of_module'
+function.
+
+   As discussed previously, each module requires a short "handle" or
+module name.  This is specified with the `--mod-name=NAME' option,
+where NAME is the abbreviated module name.  This NAME must consist only
+of characters that are valid in C function and variable names.
+
+   The module version is specified using `--mod-version=VERSION'
+argument, with VERSION being any arbitrary version string.  This
+version can be passed as an optional second argument to the Lisp
+function `load-module', and as the third argument to the internal
+module loading command `emodules_load'.  This version string is used to
+distinguish between different versions of the same module, and to
+ensure that the module is loaded at a specific version.
+
+   Last, but not least, is the module title.  Specified using the
+`--mod-title=TITLE' option, the specified TITLE is used when the list
+of loaded modules is displayed.  The module title serves no purpose
+other than to inform the user of the function of the module.  This
+string should be brief, as it has to be formatted to fit the screen.
+
+   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 `make-docfile', and provide the information
+required to populate the `docs_of_module' function.  Below is a sample
+`Makefile' fragment which indicates how all of this is used.
+
+     CC=ellcc --mode=compile
+     LD=ellcc --mode=link
+     MODINIT=ellcc --mode=init
+     CFLAGS=-O2 -DSOME_STUFF
+     
+     .c.o:
+         $(CC) $(CFLAGS) -c $<
+     
+     MODNAME=sample
+     MODVER=1.0.0
+     MODTITLE="Small sample module"
+     
+     SRCS=modfile1.c modfile2.c modfile3.c
+     OBJS=$(SRCS:.c=.o)
+     
+     all: sample.ell
+     clean:
+         rm -f $(OBJS) sample_init.o sample.ell
+     
+     install: all
+         mkdir `ellcc --mod-location`/mymods > /dev/null
+         cp sample.ell `ellcc --mod-location`/mymods/sample.ell
+     
+     sample.ell: $(OBJS) sample_init.o
+         $(LD) --mod-output=$ $(OBJS) sample_init.o
+     
+     sample_init.o: sample_init.c
+     sample_init.c: $(SRCS)
+         $(MODINIT) --mod-name=$(MODNAME) --mod-version=$(MODVER) \
+         --mod-title=$(MODTITLE) --mod-output=$ $(SRCS)
+
+   The above `Makefile' is, in fact, complete, and would compile the
+sample module, and optionally install it.  The `--mod-location'
+argument to `ellcc' will produce, on the standard output, the base
+location of the XEmacs module directory.  Each sub-directory of that
+directory is automatically searched for for modules when they are loaded
+with `load-module'.  An alternative location would be
+`/usr/local/lib/xemacs/site-modules'.  That path can change depending
+on the options the person who compiled XEmacs chose, so you can always
+determine the correct site location using the `--mod-site-location'
+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
+of these extensions, although `.ell' is the preferred extension.
+
+
+File: emodules.info,  Node: Link Mode,  Next: Other ellcc options,  Prev: Initialization Mode,  Up: Using ellcc
+
+Link Mode
+=========
+
+   Once all of your source code files have been compiled (including 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
+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.
+
+   The module has complete access to all symbols that were present in
+the dumped XEmacs, so you do not need to link against libraries that
+were linked in with the main executable.  If your library uses some
+other extra libraries, you will need to link with those.  There is
+nothing particularly complicated about link mode.  All you need to do
+is make sure you invoke it correctly in the `Makefile'.  See the sample
+`Makefile' above for an example of a well constructed `Makefile' that
+invoked the linker correctly.
+
+
+File: emodules.info,  Node: Other ellcc options,  Next: Environment Variables,  Prev: Link Mode,  Up: Using ellcc
+
+Other `ellcc' options
+=====================
+
+   Aside from the three main `ellcc' modes described above, `ellcc' can
+accept several other options.  These are typically used in a `Makefile'
+to determine installation paths.  `ellcc' also allows you to over-ride
+several of its built-in compiler and linker options using environment
+variables.  Here is the complete list of options that `ellcc' accepts.
+
+`--mode=compile'
+     Enables compilation mode.  Use this to compile source modules.
+
+`--mode=link'
+     Enabled link edit mode.  Use this to create the final module.
+
+`--mode=init'
+     Used to create the documentation function and to initialize other
+     required variables.  Produces a C source file that must be
+     compiled with `ellcc' in compile mode before linking the final
+     module.
+
+`--mode=verbose'
+     Enables verbose mode.  This will show you the commands that are
+     being executed, as well as the version number of `ellcc'.  If you
+     specify this option twice, then some extra debugging information
+     is displayed.
+
+`--mod-name=NAME'
+     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'
+     Sets the internal module VERSION to the specified string.
+     Required during initialization mode.
+
+`--mod-title=TITLE'
+     Sets the module descriptive TITLE to the string specified.  This
+     string can contain any printable characters, but should not be too
+     long.  It is required during initialization mode.
+
+`--mod-output=FILENAME'
+     Used to control the output file name.  This is used during
+     initialization mode to set the name of the C source file that will
+     be created to FILENAME.  During link mode, it sets the name of the
+     final loadable module to FILENAME.
+
+`--mod-location'
+     This will print the name of the standard module installation path
+     on the standard output and immediately exit `ellcc'.  Use this
+     option to determine the directory prefix of where you should
+     install your modules.
+
+`--mod-site-location'
+     This will print the name of the site specific module location and
+     exit.
+
+`--mod-archdir'
+     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'
+     were compiled.
+
+
+File: emodules.info,  Node: Environment Variables,  Prev: Other ellcc options,  Up: Using ellcc
+
+Environment Variables
+=====================
+
+   During its normal operation, `ellcc' uses the compiler and linker
+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'
+recognizes.
+
+`ELLCC'
+     This is used to over-ride the name of the C compiler that is
+     invoked by `ellcc'.
+
+`ELLLD'
+     Sets the name of the link editor to use to created the final
+     module.
+
+`ELLCFLAGS'
+     Sets the compiler flags passed on when compiling source modules.
+     This only sets the basic C compiler flags.  There are certain
+     hard-coded flags that will always be passed.
+
+`ELLLDFLAGS'
+     Sets the flags passed on to the linker.  This does *not* include
+     the flags for enabling PIC mode.  This just sets basic linker
+     flags.
+
+`ELLDLLFLAGS'
+     Sets the flags passed to the linker that are required to created
+     shared and loadable objects.
+
+`ELLPICFLAGS'
+     Sets the C compiler option required to produce an object file that
+     is suitable for including in a shared library.  This option should
+     turn on PIC mode, or the moral equivalent thereof on the target
+     system.
+
+`ELLMAKEDOC'
+     Sets the name of the `make-docfile' program to use.  Usually
+     `ellcc' will use the version that was compiled and installed with
+     XEmacs, but this option allows you to specify an alternative path.
+     Used during the compile phase of XEmacs itself.
+
+
+File: emodules.info,  Node: Defining Functions,  Next: Defining Variables,  Prev: Using ellcc,  Up: Top
+
+Defining Functions
+******************
+
+   One of the main reasons you would ever write a module is to provide
+one or more "functions" for the user or the editor to use.  The term
+"function" is a bit overloaded here, as it refers to both a C function
+and the way it appears to Lisp, which is a "subroutine", or simply a
+"subr".  A Lisp subr is also known as a Lisp primitive, but that term
+applies less to dynamic modules.  *Note Writing Lisp Primitives:
+(internals)Writing Lisp Primitives, 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.
+
+   Normal Lisp primitives document the functions they defining by
+including the documentation as a C comment.  During the build process,
+a program called `make-docfile' is run, which will extract all of these
+comments, build up a single large documentation file, and will store
+pointers to the start of each documentation entry in the dumped XEmacs.
+This, of course, will not work for dynamic modules, as they are loaded
+long after XEmacs has been dumped.  For this reason, we require a
+special means for adding documentation for new subrs.  This is what the
+macro `CDOCSUBR' is used for, and this is used extensively during
+`ellcc' initialization mode.
+
+   When using `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 `docs_of_module' function created by
+`ellcc'.
+
+* Menu:
+
+* Using DEFUN::                 Using the DEFUN macro to define functions
+* Declaring Functions::         Declaring functions to the Lisp reader
+
+
+File: emodules.info,  Node: Using DEFUN,  Next: Declaring Functions,  Prev: Defining Functions,  Up: Defining Functions
+
+Using `DEFUN'
+=============
+
+   Although the full syntax of a function declaration is discussed in
+the XEmacs internals manual in greater depth, what follows is a brief
+description of how to define and implement a new Lisp primitive in a
+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.
+     
+     The specified FILE is frobnicated before it is fnozzled.
+     */
+         (file))
+     {
+       char *filename;
+     
+       if (NILP(file))
+         return Qnil;
+     
+       filename = (char *)XSTRING_DATA(file);
+       frob(filename);
+       return Qt;
+     }
+
+   The first argument is the name of the function as it will appear to
+the Lisp reader.  This must be provided as a string.  The second
+argument is the name of the actual C function that will be created.
+This is typically the Lisp function name with a preceding capital `F',
+with hyphens converted to underscores.  This must be a valid C function
+name.  Next come the minimum and maximum number of arguments,
+respectively.  This is used to ensure that the correct number of
+arguments are passed to the function.  Next is the `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 XEmacs Lisp manual for more
+details.  Next comes a C comment that is the documentation for this
+function.  This comment *must* exist.  Last comes the list of function
+argument names, if any.
+
+
+File: emodules.info,  Node: Declaring Functions,  Prev: Using DEFUN,  Up: Defining Functions
+
+Declaring Functions
+===================
+
+   Simply writing the code for a function is not enough to make it
+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'.
+*Note Required Functions::, for more details.
+
+   Each call to `DEFSUBR' takes as its only argument the name of the
+function, which is the same as the second argument to the call to
+`DEFUN'.  Using the example function above, you would insert the
+following code in the `syms_of_module' function:
+
+     DEFSUBR(Fmy_function);
+
+   This call will instruct XEmacs to make the function visible to the
+Lisp reader and will prepare for the insertion of the documentation into
+the right place.  Once this is done, the user can call the Lisp
+function `my-function', if it was defined as an interactive function
+(which in this case it was).
+
+   Thats 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
+XEmacs internals manual for more details.
+
+
+File: emodules.info,  Node: Defining Variables,  Next: Index,  Prev: Defining Functions,  Up: Top
+
+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
+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.
+
+   *Note Adding Global Lisp Variables: (internals)Adding Global Lisp
+Variables, for more information on variables and naming conventions.
+
+   Once your variables are defined, you need to initialize them and make
+the Lisp reader aware of them.  This is done in the `vars_of_module'
+initialization function using special XEmacs macros such as
+`DEFVAR_LISP', `DEFVAR_BOOL', `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 _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 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.*
+Once again, to remove all doubts: *DO NOT USE PURE SPACE IN MODULES!!!*
+
+   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 XEmacs itself.  This is
+a prudent thing to do.
+
+     Lisp_Object Vsample_string;
+     int sample_boolean;
+     
+     void
+     vars_of_module()
+     {
+       DEFVAR_LISP ("sample-string", &Vsample_string /*
+     This is a sample string, declared in a module.
+     
+     Nothing magical about it.
+     */);
+     
+       DEFVAR_BOOL("sample-boolean", &sample_boolean /*
+     *Sample user-settable boolean.
+     */);
+     
+       sample_boolean = 0;
+       Vsample_string = build_string("My string");
+     }
+
+
+File: emodules.info,  Node: Index,  Prev: Defining Variables,  Up: Top
+
+Index
+*****
+
+* Menu:
+
+* anatomy:                               Anatomy of a Module.
+* compiler:                              Introduction.
+* compiling:                             Compile Mode.
+* config.h:                              Required Header File.
+* defining functions:                    Defining Functions.
+* defining objects:                      Defining Variables.
+* defining variables:                    Defining Variables.
+* DEFSUBR:                               Declaring Functions.
+* DEFUN:                                 Using DEFUN.
+* DEFVAR_BOOL:                           Defining Variables.
+* DEFVAR_INT:                            Defining Variables.
+* DEFVAR_LISP:                           Defining Variables.
+* dependencies:                          Loading other Modules.
+* DLL:                                   Introduction.
+* docs_of_module:                        Required Functions.
+* documentation <1>:                     Initialization Mode.
+* documentation:                         Introduction.
+* DSO:                                   Introduction.
+* ELLCC:                                 Environment Variables.
+* ellcc <1>:                             Using ellcc.
+* ellcc:                                 Introduction.
+* ELLCFLAGS:                             Environment Variables.
+* ELLDLLFLAGS:                           Environment Variables.
+* ELLLD:                                 Environment Variables.
+* ELLLDFLAGS:                            Environment Variables.
+* ELLMAKEDOC:                            Environment Variables.
+* ELLPICFLAGS:                           Environment Variables.
+* Emacs Modules:                         Introduction.
+* emodules.h:                            Required Header File.
+* emodules_load:                         Loading other Modules.
+* environment variables:                 Environment Variables.
+* format, module:                        Anatomy of a Module.
+* functions, declaring:                  Declaring Functions.
+* functions, defining:                   Using DEFUN.
+* functions, Lisp:                       Using DEFUN.
+* functions, required:                   Required Functions.
+* header files:                          Introduction.
+* help:                                  Introduction.
+* include files:                         Required Header File.
+* initialization <1>:                    Initialization Mode.
+* initialization <2>:                    Required Variables.
+* initialization:                        Required Functions.
+* linker:                                Introduction.
+* linking:                               Link Mode.
+* module compiler:                       Using ellcc.
+* 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.
+* objects, Lisp:                         Defining Variables.
+* paths:                                 Other ellcc options.
+* required functions:                    Required Functions.
+* required header:                       Required Header File.
+* required variables:                    Required Variables.
+* samples:                               Introduction.
+* shared object:                         Introduction.
+* skeleton, module:                      Anatomy of a Module.
+* subrs:                                 Using DEFUN.
+* syms_of_module:                        Required Functions.
+* variables, defining:                   Defining Variables.
+* variables, Lisp:                       Defining Variables.
+* variables, required:                   Required Variables.
+* vars_of_module:                        Required Functions.
+
+
+
+Tag Table:
+Node: Top1536
+Node: Introduction2883
+Node: Anatomy of a Module7391
+Node: Required Header File8205
+Node: Required Functions10124
+Node: Required Variables12848
+Node: Loading other Modules15534
+Node: Using ellcc17591
+Node: Compile Mode19385
+Node: Initialization Mode20753
+Node: Link Mode25787
+Node: Other ellcc options26932
+Node: Environment Variables29511
+Node: Defining Functions31202
+Node: Using DEFUN33213
+Node: Declaring Functions34924
+Node: Defining Variables36267
+Node: Index38510
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/external-widget.info'
Index: ././info/external-widget.info
--- ././info/external-widget.info	Thu Jan  1 09:00:00 1970
+++ ././info/external-widget.info	Thu May 17 23:26:51 2001
@@ -0,0 +1,137 @@
+This is ../info/external-widget.info, produced by makeinfo version 4.0
+from external-widget.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* External Widget: (external-widget) External Client Widget.
+END-INFO-DIR-ENTRY
+
+
+File: external-widget.info,  Node: Top,  Next: Using an External Client Widget,  Up: (dir)
+
+   An "external client widget" is a widget that is part of another
+program but functions as an Emacs frame.  This is intended to be a more
+powerful replacement for standard text widgets.
+
+* Menu:
+
+* Using an External Client Widget::
+* External Client Widget Resource Settings::
+* Motif-Specific Info About the External Client Widget::
+
+
+File: external-widget.info,  Node: Using an External Client Widget,  Next: External Client Widget Resource Settings,  Prev: Top,  Up: Top
+
+Using an External Client Widget
+*******************************
+
+   There are three different implementations of the external client
+widget.  One is designed for use in Motif applications and is linked
+with the option `-lextcli_Xm'.  Another is designed for non-Motif
+applications that still use the X toolkit; it is linked with the option
+`-lextcli_Xt'.  The third is designed for applications that do not use
+the X toolkit; it is linked with the option `-lextcli_Xlib'.  In order
+to use an external client widget in a client program that uses the X
+toolkit (i.e. either of the first two options described above), simply
+create an instance of widget type ExternalClient and link your program
+with the appropriate library.  The corresponding header file is called
+`ExternalClient.h'.
+
+   Documentation still needs to be provided for using the raw Xlib
+version of the external client widget.
+
+   The external client widget will not do anything until an instance of
+Emacs is told about this particular widget.  To do that, call the
+function `make-frame', specifying a value for the frame parameter
+`window-id'.  This value should be a string containing the decimal
+representation of the widget's X window ID number (this can be obtained
+by the Xt function `XtWindow()').  In order for the client program to
+communicate this information to Emacs, a method such as sending a
+ToolTalk message needs to be used.
+
+   Once `make-frame' has been called, Emacs will create a frame that
+occupies the client widget's window.  This frame can be used just like
+any other frame in Emacs.
+
+
+File: external-widget.info,  Node: External Client Widget Resource Settings,  Next: Motif-Specific Info About the External Client Widget,  Prev: Using an External Client Widget,  Up: Top
+
+External Client Widget Resource Settings
+****************************************
+
+   The external client widget is a subclass of the Motif widget
+XmPrimitive and thus inherits all its resources.  In addition, the
+following new resources are defined:
+
+`deadShell (class DeadShell)'
+     A boolean resource indicating whether the last request to the
+     ExternalShell widget that contains the frame corresponding to this
+     widget timed out.  If true, no further requests will be made (all
+     requests will automatically fail) until a response to the last
+     request is received.  This resource should normally not be set by
+     the user.
+
+`shellTimeout (class ShellTimeout)'
+     A value specifying how long (in milliseconds) the client should
+     wait for a response when making a request to the corresponding
+     ExternalShell widget.  If this timeout is exceeded, the client
+     will assume that the shell is dead and will fail the request and
+     all subsequent requests until a response to the request is
+     received.  Default value is 5000, or 5 seconds.
+
+   The shell that contains the frame corresponding to an external client
+widget is of type ExternalShell, as opposed to standard frames, whose
+shell is of type TopLevelShell.  The ExternalShell widget is a direct
+subclass of Shell and thus inherits its resources.  In addition, the
+following new resources are defined:
+
+`window (class Window)'
+     The X window ID of the widget to use for this Emacs frame.  This is
+     normally set by the call to `x-create-frame' and should not be
+     modified by the user.
+
+`deadClient (class DeadClient)'
+     A boolean resource indicating whether the last request to the
+     corresponding ExternalClient widget timed out.  If true, no further
+     requests will be made (all requests will automatically fail) until
+     a response to the last request is received.  This resource should
+     normally not be set by the user.
+
+`ClientTimeout (class ClientTimeout)'
+     A value specifying how long (in milliseconds) the shell should wait
+     for a response when making a request to the corresponding
+     ExternalClient widget.  If this timeout is exceeded, the shell
+     will assume that the client is dead and will fail the request and
+     all subsequent requests until a response to the request is
+     received.  Default value is 5000, or 5 seconds.
+
+   Note that the requests that are made between the client and the shell
+are primarily for handling query-geometry and geometry-manager requests
+made by parent or child widgets.
+
+
+File: external-widget.info,  Node: Motif-Specific Info About the External Client Widget,  Prev: External Client Widget Resource Settings,  Up: Top
+
+Motif-Specific Info About the External Client Widget
+****************************************************
+
+   By default, the external client widget has navigation type
+`XmTAB_GROUP'.
+
+   The widget traversal keystrokes are modified slightly from the
+standard XmPrimitive keystrokes.  In particular, `<TAB>' alone does not
+traverse to the next widget (`Ctrl-<TAB>' must be used instead), but
+functions like a normal <TAB> in Emacs.  This follows the semantics of
+the Motif text widget.  The traversal keystrokes `Ctrl-<TAB>' and
+`Shift-<TAB>' are silently filtered by the external client widget and
+are not seen by Emacs.
+
+
+
+Tag Table:
+Node: Top232
+Node: Using an External Client Widget662
+Node: External Client Widget Resource Settings2377
+Node: Motif-Specific Info About the External Client Widget5120
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/info.info'
Index: ././info/info.info
--- ././info/info.info	Thu Jan  1 09:00:00 1970
+++ ././info/info.info	Thu May 17 23:26:51 2001
@@ -0,0 +1,840 @@
+This is ../info/info.info, produced by makeinfo version 4.0 from
+info.texi.
+
+INFO-DIR-SECTION Texinfo documentation system
+START-INFO-DIR-ENTRY
+* Info: (info).                 Documentation browsing system.
+END-INFO-DIR-ENTRY
+
+   This file describes how to use Info, the on-line, menu-driven GNU
+documentation system.
+
+   Copyright (C) 1989, 92, 96, 97, 98, 99 Free Software Foundation, Inc.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Free Software Foundation.
+
+
+File: info.info,  Node: Top,  Next: Getting Started,  Up: (dir)
+
+Info: An Introduction
+*********************
+
+   Info is a program for reading documentation, which you might be using
+now to read this.
+
+   To learn how to use Info, type the command `h' while using the Info
+program.  It brings you to a programmed instruction sequence.
+
+* Menu:
+
+* Getting Started::             Getting started using an Info reader.
+* Advanced Info::               Advanced commands within Info.
+* Creating an Info File::       How to make your own Info file.
+
+
+File: info.info,  Node: Getting Started,  Next: Advanced Info,  Prev: Top,  Up: Top
+
+Getting Started
+***************
+
+   This first part of the Info manual describes how to get around inside
+of Info.  The second part of the manual describes various advanced Info
+commands, and how to write an Info as distinct from a Texinfo file.
+The third part is about how to generate Info files from Texinfo files.
+
+* Menu:
+
+* Help-Small-Screen::   Starting Info on a Small Screen
+* Help::                How to use Info
+* Help-P::              Returning to the Previous node
+* Help-^L::             The Space, Rubout, B and ^L commands.
+* Help-M::              Menus
+* Help-Adv::            Some advanced Info commands
+* Help-Q::              Quitting Info
+
+
+File: info.info,  Node: Help-Small-Screen,  Next: Help,  Up: Getting Started
+
+Starting Info on a Small Screen
+===============================
+
+   Since your terminal has an unusually small number of lines on its
+screen, it is necessary to give you special advice at the beginning.
+
+   If you see the text `--All----' at near the bottom right corner of
+the screen, it means the entire text you are looking at fits on the
+screen.  If you see `--Top----' instead, it means that there is more
+text below that does not fit.  To move forward through the text and see
+another screen full, press the Space bar, <SPC>.  To move back up,
+press the key labeled `Backspace' or <Delete>.
+
+   Here are 40 lines of junk, so you can try Spaces and Deletes and see
+what they do.  At the end are instructions of what you should do next.
+
+   This is line 17
+This is line 18
+This is line 19
+This is line 20
+This is line 21
+This is line 22
+This is line 23
+This is line 24
+This is line 25
+This is line 26
+This is line 27
+This is line 28
+This is line 29
+This is line 30
+This is line 31
+This is line 32
+This is line 33
+This is line 34
+This is line 35
+This is line 36
+This is line 37
+This is line 38
+This is line 39
+This is line 40
+This is line 41
+This is line 42
+This is line 43
+This is line 44
+This is line 45
+This is line 46
+This is line 47
+This is line 48
+This is line 49
+This is line 50
+This is line 51
+This is line 52
+This is line 53
+This is line 54
+This is line 55
+This is line 56
+If you have managed to get here, go back to the beginning with Delete,
+and come back here again, then you understand Space and Delete.  So now
+type an `n' --just one character; don't type the quotes and don't type
+the Return key afterward-- to get to the normal start of the course.
+
+
+File: info.info,  Node: Help,  Next: Help-P,  Prev: Help-Small-Screen,  Up: Getting Started
+
+How to use Info
+===============
+
+   You are talking to the program Info, for reading documentation.
+
+   Right now you are looking at one "Node" of Information.  A node
+contains text describing a specific topic at a specific level of
+detail.  This node's topic is "how to use Info".
+
+   The top line of a node is its "header".  This node's header (look at
+it now) says that it is the node named `Help' in the file `info'.  It
+says that the `Next' node after this one is the node called `Help-P'.
+An advanced Info command lets you go to any node whose name you know.
+
+   Besides a `Next', a node can have a `Previous' or an `Up'.  This
+node has a `Previous' but no `Up', as you can see.
+
+   Now it is time to move on to the `Next' node, named `Help-P'.
+
+   >> Type `n' to move there.  Type just one character;    do not type
+the quotes and do not type a <RET> afterward.
+
+   `>>' in the margin means it is really time to try a command.
+
+
+File: info.info,  Node: Help-P,  Next: Help-^L,  Prev: Help,  Up: Getting Started
+
+Returning to the Previous node
+==============================
+
+   This node is called `Help-P'.  The `Previous' node, as you see, is
+`Help', which is the one you just came from using the `n' command.
+Another `n' command now would take you to the next node, `Help-^L'.
+
+   >> But do not do that yet.  First, try the `p' command, which takes
+ you to the `Previous' node.  When you get there, you can do an    `n'
+again to return here.
+
+   This all probably seems insultingly simple so far, but _do not_ be
+led into skimming.  Things will get more complicated soon.  Also, do
+not try a new command until you are told it is time to.  Otherwise, you
+may make Info skip past an important warning that was coming up.
+
+   >> Now do an `n' to get to the node `Help-^L' and learn more.
+
+
+File: info.info,  Node: Help-^L,  Next: Help-M,  Prev: Help-P,  Up: Getting Started
+
+The Space, Delete, B and ^L commands.
+=====================================
+
+   This node's header tells you that you are now at node `Help-^L', and
+that `p' would get you back to `Help-P'.  The node's title is
+underlined; it says what the node is about (most nodes have titles).
+
+   This is a big node and it does not all fit on your display screen.
+You can tell that there is more that is not visible because you can see
+the string `--Top-----' rather than `--All----' near the bottom right
+corner of the screen.
+
+   The Space, Delete and `B' commands exist to allow you to "move
+around" in a node that does not all fit on the screen at once.  Space
+moves forward, to show what was below the bottom of the screen.  Delete
+moves backward, to show what was above the top of the screen (there is
+not anything above the top until you have typed some spaces).
+
+   >> Now try typing a Space (afterward, type a Delete to return here).
+
+   When you type the space, the two lines that were at the bottom of
+the screen appear at the top, followed by more lines.  Delete takes the
+two lines from the top and moves them to the bottom, _usually_, but if
+there are not a full screen's worth of lines above them they may not
+make it all the way to the bottom.
+
+   If you type Space when there is no more to see, it rings the bell
+and otherwise does nothing.  The same goes for Delete when the header
+of the node is visible.
+
+   If your screen is ever garbaged, you can tell Info to print it out
+again by typing `C-l' (`Control-L', that is--hold down "Control" and
+type an <L> or `l').
+
+   >> Type `C-l' now.
+
+   To move back to the beginning of the node you are on, you can type a
+lot of Deletes.  You can also type simply `b' for beginning.  >> Try
+that now.  (We have put in enough verbiage to push this past the first
+screenful, but screens are so big nowadays that perhaps it isn't
+enough.  You may need to shrink your Emacs or Info window.)  Then come
+back, with Spaces.
+
+   If your screen is very tall, all of this node might fit at once.  In
+that case, "b" won't do anything.  Sorry; what can we do?
+
+   You have just learned a considerable number of commands.  If you
+want to use one but have trouble remembering which, you should type a
+<?> which prints out a brief list of commands.  When you are finished
+looking at the list, make it go away by pressing <SPC> repeatedly.
+
+   >> Type a <?> now.  Press <SPC> to see consecutive screenfuls of >>
+the list until finished.
+
+   From now on, you will encounter large nodes without warning, and
+will be expected to know how to use Space and Delete to move around in
+them without being told.  Since not all terminals have the same size
+screen, it would be impossible to warn you anyway.
+
+   >> Now type `n' to see the description of the `m' command.
+
+
+File: info.info,  Node: Help-M,  Next: Help-Adv,  Prev: Help-^L,  Up: Getting Started
+
+Menus
+=====
+
+   Menus and the `m' command
+
+   With only the `n' and `p' commands for moving between nodes, nodes
+are restricted to a linear sequence.  Menus allow a branching
+structure.  A menu is a list of other nodes you can move to.  It is
+actually just part of the text of the node formatted specially so that
+Info can interpret it.  The beginning of a menu is always identified by
+a line which starts with `* Menu:'.  A node contains a menu if and only
+if it has a line in it which starts that way.  The only menu you can
+use at any moment is the one in the node you are in.  To use a menu in
+any other node, you must move to that node first.
+
+   After the start of the menu, each line that starts with a `*'
+identifies one subtopic.  The line usually contains a brief name for
+the subtopic (followed by a `:'), the name of the node that talks about
+that subtopic, and optionally some further description of the subtopic.
+Lines in the menu that do not start with a `*' have no special
+meaning--they are only for the human reader's benefit and do not define
+additional subtopics.  Here is an example:
+
+     * Foo:  FOO's Node      This tells about FOO
+
+   The subtopic name is Foo, and the node describing it is `FOO's Node'.
+The rest of the line is just for the reader's Information.  [[ But this
+line is not a real menu item, simply because there is no line above it
+which starts with `* Menu:'.]]
+
+   When you use a menu to go to another node (in a way that will be
+described soon), what you specify is the subtopic name, the first thing
+in the menu line.  Info uses it to find the menu line, extracts the
+node name from it, and goes to that node.  The reason that there is
+both a subtopic name and a node name is that the node name must be
+meaningful to the computer and may therefore have to be ugly looking.
+The subtopic name can be chosen just to be convenient for the user to
+specify.  Often the node name is convenient for the user to specify and
+so both it and the subtopic name are the same.  There is an
+abbreviation for this:
+
+     * Foo::   This tells about FOO
+
+This means that the subtopic name and node name are the same; they are
+both `Foo'.
+
+   >> Now use Spaces to find the menu in this node, then come back to
+the front with a `b' and some Spaces.  As you see, a menu is
+actually visible in its node.  If you cannot find a menu in a node
+by looking at it, then the node does not have a menu and the    `m'
+command is not available.
+
+   The command to go to one of the subnodes is `m'--but _do not do it
+yet!_  Before you use `m', you must understand the difference between
+commands and arguments.  So far, you have learned several commands that
+do not need arguments.  When you type one, Info processes it and is
+instantly ready for another command.  The `m' command is different: it
+is incomplete without the "name of the subtopic".  Once you have typed
+`m', Info tries to read the subtopic name.
+
+   Now look for the line containing many dashes near the bottom of the
+screen.  There is one more line beneath that one, but usually it is
+blank.  If it is empty, Info is ready for a command, such as `n' or `b'
+or Space or `m'.  If that line contains text ending in a colon, it
+means Info is trying to read the "argument" to a command.  At such
+times, commands do not work, because Info tries to use them as the
+argument.  You must either type the argument and finish the command you
+started, or type `Control-g' to cancel the command.  When you have done
+one of those things, the line becomes blank again.
+
+   The command to go to a subnode via a menu is `m'.  After you type
+the `m', the line at the bottom of the screen says `Menu item: '.  You
+must then type the name of the subtopic you want, and end it with a
+<RET>.
+
+   You can abbreviate the subtopic name.  If the abbreviation is not
+unique, the first matching subtopic is chosen.  Some menus put the
+shortest possible abbreviation for each subtopic name in capital
+letters, so you can see how much you need to type.  It does not matter
+whether you use upper case or lower case when you type the subtopic.
+You should not put any spaces at the end, or inside of the item name,
+except for one space where a space appears in the item in the menu.
+
+   You can also use the "completion" feature to help enter the subtopic
+name.  If you type the Tab key after entering part of a name, it will
+magically fill in more of the name--as much as follows uniquely from
+what you have entered.
+
+   If you move the cursor to one of the menu subtopic lines, then you do
+not need to type the argument: you just type a Return, and it stands for
+the subtopic of the line you are on.
+
+   Here is a menu to give you a chance to practice.  This menu gives you
+three ways of going to one place, Help-FOO:
+
+* Menu:
+
+* Foo:  Help-FOO.       A node you can visit for fun.
+* Bar:  Help-FOO.       Strange!  two ways to get to the same place.
+* Help-FOO::            And yet another!
+
+   >>  Now type just an `m' and see what happens:
+
+   Now you are "inside" an `m' command.  Commands cannot be used now;
+the next thing you will type must be the name of a subtopic.
+
+   You can change your mind about doing the `m' by typing Control-g.
+
+   >> Try that now;  notice the bottom line clear.
+
+   >> Then type another `m'.
+
+   >> Now type `BAR' item name.  Do not type Return yet.
+
+   While you are typing the item name, you can use the Delete key to
+cancel one character at a time if you make a mistake.
+
+   >> Type one to cancel the `R'.  You could type another `R' to
+replace it.  You do not have to, since `BA' is a valid abbreviation.
+
+   >> Now you are ready to go.  Type a <RET>.
+
+   After visiting Help-FOO, you should return here.
+
+   >> Type `n' to see more commands.
+
+   Here is another way to get to  Help-FOO, a menu.  You can ignore this
+if you want, or else try it (but then please come back to here).
+
+* Menu:
+
+* Help-FOO::
+
+
+File: info.info,  Node: Help-FOO,  Up: Help-M
+
+The `u' command
+---------------
+
+   Congratulations!  This is the node `Help-FOO'.  Unlike the other
+nodes you have seen, this one has an `Up': `Help-M', the node you just
+came from via the `m' command.  This is the usual convention--the nodes
+you reach from a menu have `Up' nodes that lead back to the menu.
+Menus move Down in the tree, and `Up' moves Up.  `Previous', on the
+other hand, is usually used to "stay on the same level but go backwards"
+
+   You can go back to the node `Help-M' by typing the command `u' for
+"Up".  That puts you at the _front_ of the node--to get back to where
+you were reading you have to type some <SPC>s.
+
+   >> Now type `u' to move back up to `Help-M'.
+
+
+File: info.info,  Node: Help-Adv,  Next: Help-Q,  Prev: Help-M,  Up: Getting Started
+
+Some advanced Info commands
+===========================
+
+   The course is almost over, so please stick with it to the end.
+
+   If you have been moving around to different nodes and wish to
+retrace your steps, the `l' command (`l' for "last") will do that, one
+node-step at a time.  As you move from node to node, Info records the
+nodes where you have been in a special history list.  The `l' command
+revisits nodes in the history list; each successive `l' command moves
+one step back through the history.
+
+   If you have been following directions, ad `l' command now will get
+you back to `Help-M'.  Another `l' command would undo the `u' and get
+you back to `Help-FOO'.  Another `l' would undo the `m' and get you
+back to `Help-M'.
+
+   >> Try typing three `l''s, pausing in between to see what each
+`l' does.
+
+   Then follow directions again and you will end up back here.
+
+   Note the difference between `l' and `p': `l' moves to where _you_
+last were, whereas `p' always moves to the node which the header says
+is the `Previous' node (from this node, to `Help-M').
+
+   The `d' command gets you instantly to the Directory node.  This
+node, which is the first one you saw when you entered Info, has a menu
+which leads (directly, or indirectly through other menus), to all the
+nodes that exist.
+
+   >> Try doing a `d', then do an `l' to return here (yes,    _do_
+return).
+
+   Sometimes, in Info documentation, you will see a cross reference.
+Cross references look like this: *Note Cross: Help-Cross.  That is a
+real, live cross reference which is named `Cross' and points at the
+node named `Help-Cross'.
+
+   If you wish to follow a cross reference, you must use the `f'
+command.  The `f' must be followed by the cross reference name (in this
+case, `Cross').  While you enter the name, you can use the Delete key
+to edit your input.  If you change your mind about following any
+reference, you can use `Control-g' to cancel the command.
+
+   Completion is available in the `f' command; you can complete among
+all the cross reference names in the current node by typing a Tab.
+
+   >> Type `f', followed by `Cross', and a <RET>.
+
+   To get a list of all the cross references in the current node, you
+can type `?' after an `f'.  The `f' continues to await a cross
+reference name even after printing the list, so if you don't actually
+want to follow a reference, you should type a `Control-g' to cancel the
+`f'.
+
+   >> Type "f?" to get a list of the cross references in this node.
+Then    type a `Control-g' and see how the `f' gives up.
+
+   >> Now type `n' to see the last node of the course.
+
+
+File: info.info,  Node: Help-Cross,  Up: Help-Adv
+
+The node reached by the cross reference in Info
+-----------------------------------------------
+
+   This is the node reached by the cross reference named `Cross'.
+
+   While this node is specifically intended to be reached by a cross
+reference, most cross references lead to nodes that "belong" someplace
+else far away in the structure of Info.  So you cannot expect the
+footnote to have a `Next', `Previous' or `Up' pointing back to where
+you came from.  In general, the `l' (el) command is the only way to get
+back there.
+
+   >> Type `l' to return to the node where the cross reference was.
+
+
+File: info.info,  Node: Help-Q,  Prev: Help-Adv,  Up: Getting Started
+
+Quitting Info
+=============
+
+   To get out of Info, back to what you were doing before, type `q' for
+"Quit".
+
+   This is the end of the course on using Info.  There are some other
+commands that are meant for experienced users; they are useful, and you
+can find them by looking in the directory node for documentation on
+Info.  Finding them will be a good exercise in using Info in the usual
+manner.
+
+   >> Type `d' to go to the Info directory node; then type    `mInfo'
+and Return, to get to the node about Info and    see what other help is
+available.
+
+
+File: info.info,  Node: Advanced Info,  Next: Creating an Info File,  Prev: Getting Started,  Up: Top
+
+Info for Experts
+****************
+
+   This chapter describes various advanced Info commands, and how to
+write an Info as distinct from a Texinfo file.  (However, in most
+cases, writing a Texinfo file is better, since you can use it _both_ to
+generate an Info file and to make a printed manual.  *Note Overview of
+Texinfo: (texinfo)Top.)
+
+* Menu:
+
+* Expert::               Advanced Info commands: g, s, e, and 1 - 5.
+* Add::                  Describes how to add new nodes to the hierarchy.
+                           Also tells what nodes look like.
+* Menus::                How to add to or create menus in Info nodes.
+* Cross-refs::           How to add cross-references to Info nodes.
+* Tags::                 How to make tag tables for Info files.
+* Checking::             Checking an Info File
+* Emacs Info Variables:: Variables modifying the behavior of Emacs Info.
+
+
+File: info.info,  Node: Expert,  Next: Add,  Up: Advanced Info
+
+Advanced Info Commands
+======================
+
+   `g', `s', `1', - `9', and `e'
+
+   If you know a node's name, you can go there by typing `g', the name,
+and <RET>.  Thus, `gTop<RET>' would go to the node called `Top' in this
+file (its directory node).  `gExpert<RET>' would come back here.
+
+   Unlike `m', `g' does not allow the use of abbreviations.
+
+   To go to a node in another file, you can include the filename in the
+node name by putting it at the front, in parentheses.  Thus,
+`g(dir)Top<RET>' would go to the Info Directory node, which is node
+`Top' in the file `dir'.
+
+   The node name `*' specifies the whole file.  So you can look at all
+of the current file by typing `g*<RET>' or all of any other file with
+`g(FILENAME)<RET>'.
+
+   The `s' command allows you to search a whole file for a string.  It
+switches to the next node if and when that is necessary.  You type `s'
+followed by the string to search for, terminated by <RET>.  To search
+for the same string again, just `s' followed by <RET> will do.  The
+file's nodes are scanned in the order they are in in the file, which
+has no necessary relationship to the order that they may be in in the
+tree structure of menus and `next' pointers.  But normally the two
+orders are not very different.  In any case, you can always do a `b' to
+find out what node you have reached, if the header is not visible (this
+can happen, because `s' puts your cursor at the occurrence of the
+string, not at the beginning of the node).
+
+   If you grudge the system each character of type-in it requires, you
+might like to use the commands `1', `2', `3', `4', ...  `9'.  They are
+short for the `m' command together with an argument.  `1' goes through
+the first item in the current node's menu; `2' goes through the second
+item, etc.
+
+   If your display supports multiple fonts, and you are using Emacs'
+Info mode to read Info files, the `*' for the fifth menu item is
+underlined, and so is the `*' for the ninth item; these underlines make
+it easy to see at a glance which number to use for an item.
+
+   On ordinary terminals, you won't have underlining.  If you need to
+actually count items, it is better to use `m' instead, and specify the
+name.
+
+   The Info command `e' changes from Info mode to an ordinary Emacs
+editing mode, so that you can edit the text of the current node.  Type
+`C-c C-c' to switch back to Info.  The `e' command is allowed only if
+the variable `Info-enable-edit' is non-`nil'.
+
+
+File: info.info,  Node: Add,  Next: Menus,  Prev: Expert,  Up: Advanced Info
+
+Adding a new node to Info
+=========================
+
+   To add a new topic to the list in the Info directory, you must:
+  1. Create some nodes, in some file, to document that topic.
+
+  2. Put that topic in the menu in the directory.  *Note Menu: Menus.
+
+   Usually, the way to create the nodes is with Texinfo (*note Overview
+of Texinfo: (texinfo)Top.); this has the advantage that you can also
+make a printed manual from them.  However, if you want to edit an Info
+file, here is how.
+
+   The new node can live in an existing documentation file, or in a new
+one.  It must have a <^_> character before it (invisible to the user;
+this node has one but you cannot see it), and it ends with either a
+<^_>, a <^L>, or the end of file.  Note: If you put in a <^L> to end a
+new node, be sure that there is a <^_> after it to start the next one,
+since <^L> cannot _start_ a node.  Also, a nicer way to make a node
+boundary be a page boundary as well is to put a <^L> _right after_ the
+<^_>.
+
+   The <^_> starting a node must be followed by a newline or a <^L>
+newline, after which comes the node's header line.  The header line
+must give the node's name (by which Info finds it), and state the names
+of the `Next', `Previous', and `Up' nodes (if there are any).  As you
+can see, this node's `Up' node is the node `Top', which points at all
+the documentation for Info.  The `Next' node is `Menus'.
+
+   The keywords "Node", "Previous", "Up", and "Next", may appear in any
+order, anywhere in the header line, but the recommended order is the
+one in this sentence.  Each keyword must be followed by a colon, spaces
+and tabs, and then the appropriate name.  The name may be terminated
+with a tab, a comma, or a newline.  A space does not end it; node names
+may contain spaces.  The case of letters in the names is insignificant.
+
+   A node name has two forms.  A node in the current file is named by
+what appears after the `Node: ' in that node's first line.  For
+example, this node's name is `Add'.  A node in another file is named by
+`(FILENAME)NODE-WITHIN-FILE', as in `(info)Add' for this node.  If the
+file name starts with "./", then it is relative to the current
+directory; otherwise, it is relative starting from the standard Info
+file directory of your site.  The name `(FILENAME)Top' can be
+abbreviated to just `(FILENAME)'.  By convention, the name `Top' is
+used for the "highest" node in any single file--the node whose `Up'
+points out of the file.  The Directory node is `(dir)'.  The `Top' node
+of a document file listed in the Directory should have an `Up: (dir)'
+in it.
+
+   The node name `*' is special: it refers to the entire file.  Thus,
+`g*' shows you the whole current file.  The use of the node `*' is to
+make it possible to make old-fashioned, unstructured files into nodes
+of the tree.
+
+   The `Node:' name, in which a node states its own name, must not
+contain a filename, since Info when searching for a node does not expect
+one to be there.  The `Next', `Previous' and `Up' names may contain
+them.  In this node, since the `Up' node is in the same file, it was
+not necessary to use one.
+
+   Note that the nodes in this file have a file name in the header
+line.  The file names are ignored by Info, but they serve as comments
+to help identify the node for the user.
+
+
+File: info.info,  Node: Menus,  Next: Cross-refs,  Prev: Add,  Up: Advanced Info
+
+How to Create Menus
+===================
+
+   Any node in the Info hierarchy may have a "menu"--a list of subnodes.
+The `m' command searches the current node's menu for the topic which it
+reads from the terminal.
+
+   A menu begins with a line starting with `* Menu:'.  The rest of the
+line is a comment.  After the starting line, every line that begins
+with a `* ' lists a single topic.  The name of the topic-the argument
+that the user must give to the `m' command to select this topic--comes
+right after the star and space, and is followed by a colon, spaces and
+tabs, and the name of the node which discusses that topic.  The node
+name, like node names following `Next', `Previous' and `Up', may be
+terminated with a tab, comma, or newline; it may also be terminated
+with a period.
+
+   If the node name and topic name are the same, then rather than
+giving the name twice, the abbreviation `* NAME::' may be used (and
+should be used, whenever possible, as it reduces the visual clutter in
+the menu).
+
+   It is considerate to choose the topic names so that they differ from
+each other very near the beginning--this allows the user to type short
+abbreviations.  In a long menu, it is a good idea to capitalize the
+beginning of each item name which is the minimum acceptable
+abbreviation for it (a long menu is more than 5 or so entries).
+
+   The nodes listed in a node's menu are called its "subnodes", and it
+is their "superior".  They should each have an `Up:' pointing at the
+superior.  It is often useful to arrange all or most of the subnodes in
+a sequence of `Next' and `Previous' pointers so that someone who wants
+to see them all need not keep revisiting the Menu.
+
+   The Info Directory is simply the menu of the node `(dir)Top'--that
+is, node `Top' in file `.../info/dir'.  You can put new entries in that
+menu just like any other menu.  The Info Directory is _not_ the same as
+the file directory called `info'.  It happens that many of Info's files
+live on that file directory, but they do not have to; and files on that
+directory are not automatically listed in the Info Directory node.
+
+   Also, although the Info node graph is claimed to be a "hierarchy",
+in fact it can be _any_ directed graph.  Shared structures and pointer
+cycles are perfectly possible, and can be used if they are appropriate
+to the meaning to be expressed.  There is no need for all the nodes in
+a file to form a connected structure.  In fact, this file has two
+connected components.  You are in one of them, which is under the node
+`Top'; the other contains the node `Help' which the `h' command goes
+to.  In fact, since there is no garbage collector, nothing terrible
+happens if a substructure is not pointed to, but such a substructure is
+rather useless since nobody can ever find out that it exists.
+
+
+File: info.info,  Node: Cross-refs,  Next: Tags,  Prev: Menus,  Up: Advanced Info
+
+Creating Cross References
+=========================
+
+   A cross reference can be placed anywhere in the text, unlike a menu
+item which must go at the front of a line.  A cross reference looks
+like a menu item except that it has `*note' instead of `*'.  It
+_cannot_ be terminated by a `)', because `)''s are so often part of
+node names.  If you wish to enclose a cross reference in parentheses,
+terminate it with a period first.  Here are two examples of cross
+references pointers:
+
+     *Note details: commands.  (See *note 3: Full Proof.)
+
+   They are just examples.  The places they "lead to" do not really
+exist!
+
+
+File: info.info,  Node: Tags,  Next: Checking,  Prev: Cross-refs,  Up: Advanced Info
+
+Tag Tables for Info Files
+=========================
+
+   You can speed up the access to nodes of a large Info file by giving
+it a tag table.  Unlike the tag table for a program, the tag table for
+an Info file lives inside the file itself and is used automatically
+whenever Info reads in the file.
+
+   To make a tag table, go to a node in the file using Emacs Info mode
+and type `M-x Info-tagify'.  Then you must use `C-x C-s' to save the
+file.
+
+   Once the Info file has a tag table, you must make certain it is up
+to date.  If, as a result of deletion of text, any node moves back more
+than a thousand characters in the file from the position recorded in
+the tag table, Info will no longer be able to find that node.  To
+update the tag table, use the `Info-tagify' command again.
+
+   An Info file tag table appears at the end of the file and looks like
+this:
+
+     ^_
+     Tag Table:
+     File: info, Node: Cross-refs^?21419
+     File: info,  Node: Tags^?22145
+     ^_
+     End Tag Table
+
+Note that it contains one line per node, and this line contains the
+beginning of the node's header (ending just after the node name), a
+Delete character, and the character position in the file of the
+beginning of the node.
+
+
+File: info.info,  Node: Checking,  Next: Emacs Info Variables,  Prev: Tags,  Up: Advanced Info
+
+Checking an Info File
+=====================
+
+   When creating an Info file, it is easy to forget the name of a node
+when you are making a pointer to it from another node.  If you put in
+the wrong name for a node, this is not detected until someone tries to
+go through the pointer using Info.  Verification of the Info file is an
+automatic process which checks all pointers to nodes and reports any
+pointers which are invalid.  Every `Next', `Previous', and `Up' is
+checked, as is every menu item and every cross reference.  In addition,
+any `Next' which does not have a `Previous' pointing back is reported.
+Only pointers within the file are checked, because checking pointers to
+other files would be terribly slow.  But those are usually few.
+
+   To check an Info file, do `M-x Info-validate' while looking at any
+node of the file with Emacs Info mode.
+
+
+File: info.info,  Node: Emacs Info Variables,  Prev: Checking,  Up: Advanced Info
+
+Emacs Info-mode Variables
+=========================
+
+   The following variables may modify the behavior of Info-mode in
+Emacs; you may wish to set one or several of these variables
+interactively, or in your `~/.emacs' init file.  *Note Examining and
+Setting Variables: (xemacs)Examining.
+
+`Info-enable-edit'
+     Set to `nil', disables the `e' (`Info-edit') command.  A non-`nil'
+     value enables it.  *Note Edit: Add.
+
+`Info-enable-active-nodes'
+     When set to a non-`nil' value, allows Info to execute Lisp code
+     associated with nodes.  The Lisp code is executed when the node is
+     selected.
+
+`Info-directory-list'
+     The list of directories to search for Info files.  Each element is
+     a string (directory name) or `nil' (try default directory).
+
+`Info-directory'
+     The standard directory for Info documentation files.  Only used
+     when the function `Info-directory' is called.
+
+
+File: info.info,  Node: Creating an Info File,  Prev: Advanced Info,  Up: Top
+
+Creating an Info File
+*********************
+
+   *Note Overview of Texinfo: (texinfo)Top, to learn how to write a
+Texinfo file.
+
+   *Note Creating an Info File: (texinfo)Create an Info File, to learn
+how to create an Info file from a Texinfo file.
+
+   *Note Installing an Info File: (texinfo)Install an Info File, to
+learn how to install an Info file after you have created one.
+
+
+
+Tag Table:
+Node: Top1067
+Node: Getting Started1612
+Node: Help-Small-Screen2360
+Node: Help4109
+Node: Help-P5139
+Node: Help-^L6001
+Node: Help-M8879
+Node: Help-FOO14859
+Node: Help-Adv15597
+Node: Help-Cross18272
+Node: Help-Q18918
+Node: Advanced Info19545
+Node: Expert20523
+Node: Add23037
+Node: Menus26397
+Node: Cross-refs29271
+Node: Tags29973
+Node: Checking31275
+Node: Emacs Info Variables32228
+Node: Creating an Info File33217
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info'
Index: ././info/internals.info
--- ././info/internals.info	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info	Thu May 17 23:26:54 2001
@@ -0,0 +1,199 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+Indirect:
+internals.info-1: 1776
+internals.info-2: 51581
+internals.info-3: 100531
+internals.info-4: 150232
+internals.info-5: 192457
+internals.info-6: 241581
+internals.info-7: 288078
+internals.info-8: 335143
+internals.info-9: 384278
+
+Tag Table:
+(Indirect)
+Node: Top1776
+Node: A History of Emacs7052
+Node: Through Version 188577
+Node: Lucid Emacs11998
+Node: GNU Emacs 1916042
+Node: GNU Emacs 2018225
+Node: XEmacs18652
+Node: XEmacs From the Outside25764
+Node: The Lisp Language27531
+Node: XEmacs From the Perspective of Building37074
+Node: XEmacs From the Inside43199
+Node: The XEmacs Object System (Abstractly Speaking)51581
+Node: How Lisp Objects Are Represented in C65667
+Node: Rules When Writing New C Code70344
+Node: General Coding Rules71207
+Node: Writing Lisp Primitives76979
+Node: Writing Good Comments88141
+Node: Adding Global Lisp Variables91680
+Node: Proper Use of Unsigned Types95329
+Node: Coding for Mule96579
+Node: Character-Related Data Types97558
+Node: Working With Character and Byte Positions100531
+Node: Conversion to and from External Data104296
+Node: General Guidelines for Writing Mule-Aware Code110437
+Node: An Example of Mule-Aware Code113125
+Node: Techniques for XEmacs Developers115106
+Node: A Summary of the Various XEmacs Modules123053
+Node: Low-Level Modules123873
+Node: Basic Lisp Modules131286
+Node: Modules for Standard Editing Operations137880
+Node: Editor-Level Control Flow Modules143768
+Node: Modules for the Basic Displayable Lisp Objects147279
+Node: Modules for other Display-Related Lisp Objects150232
+Node: Modules for the Redisplay Mechanism151573
+Node: Modules for Interfacing with the File System153945
+Node: Modules for Other Aspects of the Lisp Interpreter and Object System157643
+Node: Modules for Interfacing with the Operating System163096
+Node: Modules for Interfacing with X Windows170652
+Node: Modules for Internationalization174135
+Node: Allocation of Objects in XEmacs Lisp176772
+Node: Introduction to Allocation177293
+Node: Garbage Collection180934
+Node: GCPROing182090
+Node: Garbage Collection - Step by Step189094
+Node: Invocation189486
+Node: garbage_collect_1192457
+Node: mark_object201939
+Node: gc_sweep203751
+Node: sweep_lcrecords_1208814
+Node: compact_string_chars209809
+Node: sweep_strings211989
+Node: sweep_bit_vectors_1212954
+Node: Integers and Characters213630
+Node: Allocation from Frob Blocks214382
+Node: lrecords215986
+Node: Low-level allocation228212
+Node: Cons232319
+Node: Vector233045
+Node: Bit Vector233622
+Node: Symbol234115
+Node: Marker234469
+Node: String235024
+Node: Compiled Function238637
+Node: Dumping238806
+Node: Overview241027
+Node: Data descriptions241581
+Node: Dumping phase243586
+Node: Object inventory243989
+Node: Address allocation246903
+Node: The header248292
+Node: Data dumping248737
+Node: Pointers dumping249398
+Node: Reloading phase250788
+Node: Remaining issues252342
+Node: Events and the Event Loop253303
+Node: Introduction to Events253753
+Node: Main Loop255668
+Node: Specifics of the Event Gathering Mechanism259243
+Node: Specifics About the Emacs Event271696
+Node: The Event Stream Callback Routines271951
+Node: Other Event Loop Functions272196
+Node: Converting Events273336
+Node: Dispatching Events; The Command Builder273945
+Node: Evaluation; Stack Frames; Bindings274180
+Node: Evaluation274522
+Node: Dynamic Binding; The specbinding Stack; Unwind-Protects281034
+Node: Simple Special Forms283418
+Node: Catch and Throw284201
+Node: Symbols and Variables286776
+Node: Introduction to Symbols287040
+Node: Obarrays288078
+Node: Symbol Values291611
+Node: Buffers and Textual Representation293899
+Node: Introduction to Buffers294557
+Node: The Text in a Buffer297220
+Node: Buffer Lists304370
+Node: Markers and Extents306321
+Node: Bufbytes and Emchars308586
+Node: The Buffer Object308801
+Node: MULE Character Sets and Encodings312281
+Node: Character Sets313343
+Node: Encodings316786
+Node: Japanese EUC (Extended Unix Code)317853
+Node: JIS7318667
+Node: Internal Mule Encodings320017
+Node: Internal String Encoding321847
+Node: Internal Character Encoding323960
+Node: CCL325684
+Node: The Lisp Reader and Compiler332437
+Node: Lstreams332650
+Node: Creating an Lstream333681
+Node: Lstream Types334891
+Node: Lstream Functions335143
+Node: Lstream Methods338709
+Node: Consoles; Devices; Frames; Windows341851
+Node: Introduction to Consoles; Devices; Frames; Windows342166
+Node: Point344656
+Node: Window Hierarchy345935
+Node: The Window Object350387
+Node: The Redisplay Mechanism353824
+Node: Critical Redisplay Sections354616
+Node: Line Start Cache355571
+Node: Redisplay Piece by Piece358807
+Node: Extents360844
+Node: Introduction to Extents361378
+Node: Extent Ordering362504
+Node: Format of the Extent Info363745
+Node: Zero-Length Extents365632
+Node: Mathematics of Extent Ordering367032
+Node: Extent Fragments371789
+Node: Faces372875
+Node: Glyphs372991
+Node: Specifiers379624
+Node: Menus379753
+Node: Subprocesses382011
+Node: Interface to the X Window System383997
+Node: Lucid Widget Library384278
+Node: Generic Widget Interface385569
+Node: Scrollbars389128
+Node: Menubars389271
+Node: Checkboxes and Radio Buttons389414
+Node: Progress Bars389600
+Node: Tab Controls389760
+Node: Index389881
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-1'
Index: ././info/internals.info-1
--- ././info/internals.info-1	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-1	Thu May 17 23:26:54 2001
@@ -0,0 +1,1284 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Top,  Next: A History of Emacs,  Prev: (dir),  Up: (dir)
+
+   This Info file contains v1.4 of the XEmacs Internals Manual, March
+2001.
+
+* Menu:
+
+* A History of Emacs::          Times, dates, important events.
+* XEmacs From the Outside::     A broad conceptual overview.
+* The Lisp Language::           An overview.
+* XEmacs From the Perspective of Building::
+* XEmacs From the Inside::
+* The XEmacs Object System (Abstractly Speaking)::
+* How Lisp Objects Are Represented in C::
+* Rules When Writing New C Code::
+* A Summary of the Various XEmacs Modules::
+* Allocation of Objects in XEmacs Lisp::
+* Dumping::
+* Events and the Event Loop::
+* Evaluation; Stack Frames; Bindings::
+* Symbols and Variables::
+* Buffers and Textual Representation::
+* MULE Character Sets and Encodings::
+* The Lisp Reader and Compiler::
+* Lstreams::
+* Consoles; Devices; Frames; Windows::
+* The Redisplay Mechanism::
+* Extents::
+* Faces::
+* Glyphs::
+* Specifiers::
+* Menus::
+* Subprocesses::
+* Interface to the X Window System::
+* Index::
+
+
+--- The Detailed Node Listing ---
+
+A History of Emacs
+
+* Through Version 18::          Unification prevails.
+* Lucid Emacs::                 One version 19 Emacs.
+* GNU Emacs 19::                The other version 19 Emacs.
+* GNU Emacs 20::                The other version 20 Emacs.
+* XEmacs::                      The continuation of Lucid Emacs.
+
+Rules When Writing New C Code
+
+* General Coding Rules::
+* Writing Lisp Primitives::
+* Adding Global Lisp Variables::
+* Coding for Mule::
+* Techniques for XEmacs Developers::
+
+Coding for Mule
+
+* Character-Related Data Types::
+* Working With Character and Byte Positions::
+* Conversion to and from External Data::
+* General Guidelines for Writing Mule-Aware Code::
+* An Example of Mule-Aware Code::
+
+A Summary of the Various XEmacs Modules
+
+* Low-Level Modules::
+* Basic Lisp Modules::
+* Modules for Standard Editing Operations::
+* Editor-Level Control Flow Modules::
+* Modules for the Basic Displayable Lisp Objects::
+* Modules for other Display-Related Lisp Objects::
+* Modules for the Redisplay Mechanism::
+* Modules for Interfacing with the File System::
+* Modules for Other Aspects of the Lisp Interpreter and Object System::
+* Modules for Interfacing with the Operating System::
+* Modules for Interfacing with X Windows::
+* Modules for Internationalization::
+
+Allocation of Objects in XEmacs Lisp
+
+* Introduction to Allocation::
+* Garbage Collection::
+* GCPROing::
+* Garbage Collection - Step by Step::
+* Integers and Characters::
+* Allocation from Frob Blocks::
+* lrecords::
+* Low-level allocation::
+* Cons::
+* Vector::
+* Bit Vector::
+* Symbol::
+* Marker::
+* String::
+* Compiled Function::
+
+Garbage Collection - Step by Step
+
+* Invocation::
+* garbage_collect_1::
+* mark_object::
+* gc_sweep::
+* sweep_lcrecords_1::
+* compact_string_chars::
+* sweep_strings::
+* sweep_bit_vectors_1::
+
+Dumping
+
+* Overview::
+* Data descriptions::
+* Dumping phase::
+* Reloading phase::
+
+Dumping phase
+
+* Object inventory::
+* Address allocation::
+* The header::
+* Data dumping::
+* Pointers dumping::
+
+Events and the Event Loop
+
+* Introduction to Events::
+* Main Loop::
+* Specifics of the Event Gathering Mechanism::
+* Specifics About the Emacs Event::
+* The Event Stream Callback Routines::
+* Other Event Loop Functions::
+* Converting Events::
+* Dispatching Events; The Command Builder::
+
+Evaluation; Stack Frames; Bindings
+
+* Evaluation::
+* Dynamic Binding; The specbinding Stack; Unwind-Protects::
+* Simple Special Forms::
+* Catch and Throw::
+
+Symbols and Variables
+
+* Introduction to Symbols::
+* Obarrays::
+* Symbol Values::
+
+Buffers and Textual Representation
+
+* Introduction to Buffers::     A buffer holds a block of text such as a file.
+* The Text in a Buffer::        Representation of the text in a buffer.
+* Buffer Lists::                Keeping track of all buffers.
+* Markers and Extents::         Tagging locations within a buffer.
+* Bufbytes and Emchars::        Representation of individual characters.
+* The Buffer Object::           The Lisp object corresponding to a buffer.
+
+MULE Character Sets and Encodings
+
+* Character Sets::
+* Encodings::
+* Internal Mule Encodings::
+* CCL::
+
+Encodings
+
+* Japanese EUC (Extended Unix Code)::
+* JIS7::
+
+Internal Mule Encodings
+
+* Internal String Encoding::
+* Internal Character Encoding::
+
+Lstreams
+
+* Creating an Lstream::         Creating an lstream object.
+* Lstream Types::               Different sorts of things that are streamed.
+* Lstream Functions::           Functions for working with lstreams.
+* Lstream Methods::             Creating new lstream types.
+
+Consoles; Devices; Frames; Windows
+
+* Introduction to Consoles; Devices; Frames; Windows::
+* Point::
+* Window Hierarchy::
+* The Window Object::
+
+The Redisplay Mechanism
+
+* Critical Redisplay Sections::
+* Line Start Cache::
+* Redisplay Piece by Piece::
+
+Extents
+
+* Introduction to Extents::     Extents are ranges over text, with properties.
+* Extent Ordering::             How extents are ordered internally.
+* Format of the Extent Info::   The extent information in a buffer or string.
+* Zero-Length Extents::         A weird special case.
+* Mathematics of Extent Ordering::  A rigorous foundation.
+* Extent Fragments::            Cached information useful for redisplay.
+
+
+File: internals.info,  Node: A History of Emacs,  Next: XEmacs From the Outside,  Prev: Top,  Up: Top
+
+A History of Emacs
+******************
+
+   XEmacs is a powerful, customizable text editor and development
+environment.  It began as Lucid Emacs, which was in turn derived from
+GNU Emacs, a program written by Richard Stallman of the Free Software
+Foundation.  GNU Emacs dates back to the 1970's, and was modelled after
+a package called "Emacs", written in 1976, that was a set of macros on
+top of TECO, an old, old text editor written at MIT on the DEC PDP 10
+under one of the earliest time-sharing operating systems, ITS
+(Incompatible Timesharing System). (ITS dates back well before Unix.)
+ITS, TECO, and Emacs were products of a group of people at MIT who
+called themselves "hackers", who shared an idealistic belief system
+about the free exchange of information and were fanatical in their
+devotion to and time spent with computers. (The hacker subculture dates
+back to the late 1950's at MIT and is described in detail in Steven
+Levy's book `Hackers'.  This book also includes a lot of information
+about Stallman himself and the development of Lisp, a programming
+language developed at MIT that underlies Emacs.)
+
+* Menu:
+
+* Through Version 18::          Unification prevails.
+* Lucid Emacs::                 One version 19 Emacs.
+* GNU Emacs 19::                The other version 19 Emacs.
+* GNU Emacs 20::                The other version 20 Emacs.
+* XEmacs::                      The continuation of Lucid Emacs.
+
+
+File: internals.info,  Node: Through Version 18,  Next: Lucid Emacs,  Up: A History of Emacs
+
+Through Version 18
+==================
+
+   Although the history of the early versions of GNU Emacs is unclear,
+the history is well-known from the middle of 1985.  A time line is:
+
+   * GNU Emacs version 15 (15.34) was released sometime in 1984 or 1985
+     and shared some code with a version of Emacs written by James
+     Gosling (the same James Gosling who later created the Java
+     language).
+
+   * GNU Emacs version 16 (first released version was 16.56) was
+     released on July 15, 1985.  All Gosling code was removed due to
+     potential copyright problems with the code.
+
+   * version 16.57: released on September 16, 1985.
+
+   * versions 16.58, 16.59: released on September 17, 1985.
+
+   * version 16.60: released on September 19, 1985.  These later
+     version 16's incorporated patches from the net, esp. for getting
+     Emacs to work under System V.
+
+   * version 17.36 (first official v17 release) released on December 20,
+     1985.  Included a TeX-able user manual.  First official unpatched
+     version that worked on vanilla System V machines.
+
+   * version 17.43 (second official v17 release) released on January 25,
+     1986.
+
+   * version 17.45 released on January 30, 1986.
+
+   * version 17.46 released on February 4, 1986.
+
+   * version 17.48 released on February 10, 1986.
+
+   * version 17.49 released on February 12, 1986.
+
+   * version 17.55 released on March 18, 1986.
+
+   * version 17.57 released on March 27, 1986.
+
+   * version 17.58 released on April 4, 1986.
+
+   * version 17.61 released on April 12, 1986.
+
+   * version 17.63 released on May 7, 1986.
+
+   * version 17.64 released on May 12, 1986.
+
+   * version 18.24 (a beta version) released on October 2, 1986.
+
+   * version 18.30 (a beta version) released on November 15, 1986.
+
+   * version 18.31 (a beta version) released on November 23, 1986.
+
+   * version 18.32 (a beta version) released on December 7, 1986.
+
+   * version 18.33 (a beta version) released on December 12, 1986.
+
+   * version 18.35 (a beta version) released on January 5, 1987.
+
+   * version 18.36 (a beta version) released on January 21, 1987.
+
+   * January 27, 1987: The Great Usenet Renaming.  net.emacs is now
+     comp.emacs.
+
+   * version 18.37 (a beta version) released on February 12, 1987.
+
+   * version 18.38 (a beta version) released on March 3, 1987.
+
+   * version 18.39 (a beta version) released on March 14, 1987.
+
+   * version 18.40 (a beta version) released on March 18, 1987.
+
+   * version 18.41 (the first "official" release) released on March 22,
+     1987.
+
+   * version 18.45 released on June 2, 1987.
+
+   * version 18.46 released on June 9, 1987.
+
+   * version 18.47 released on June 18, 1987.
+
+   * version 18.48 released on September 3, 1987.
+
+   * version 18.49 released on September 18, 1987.
+
+   * version 18.50 released on February 13, 1988.
+
+   * version 18.51 released on May 7, 1988.
+
+   * version 18.52 released on September 1, 1988.
+
+   * version 18.53 released on February 24, 1989.
+
+   * version 18.54 released on April 26, 1989.
+
+   * version 18.55 released on August 23, 1989.  This is the earliest
+     version that is still available by FTP.
+
+   * version 18.56 released on January 17, 1991.
+
+   * version 18.57 released late January, 1991.
+
+   * version 18.58 released ?????.
+
+   * version 18.59 released October 31, 1992.
+
+
+File: internals.info,  Node: Lucid Emacs,  Next: GNU Emacs 19,  Prev: Through Version 18,  Up: A History of Emacs
+
+Lucid Emacs
+===========
+
+   Lucid Emacs was developed by the (now-defunct) Lucid Inc., a maker of
+C++ and Lisp development environments.  It began when Lucid decided they
+wanted to use Emacs as the editor and cornerstone of their C++
+development environment (called "Energize").  They needed many features
+that were not available in the existing version of GNU Emacs (version
+18.5something), in particular good and integrated support for GUI
+elements such as mouse support, multiple fonts, multiple window-system
+windows, etc.  A branch of GNU Emacs called Epoch, written at the
+University of Illinois, existed that supplied many of these features;
+however, Lucid needed more than what existed in Epoch.  At the time, the
+Free Software Foundation was working on version 19 of Emacs (this was
+sometime around 1991), which was planned to have similar features, and
+so Lucid decided to work with the Free Software Foundation.  Their plan
+was to add features that they needed, and coordinate with the FSF so
+that the features would get included back into Emacs version 19.
+
+   Delays in the release of version 19 occurred, however (resulting in
+it finally being released more than a year after what was initially
+planned), and Lucid encountered unexpected technical resistance in
+getting their changes merged back into version 19, so they decided to
+release their own version of Emacs, which became Lucid Emacs 19.0.
+
+   The initial authors of Lucid Emacs were Matthieu Devin, Harlan
+Sexton, and Eric Benson, and the work was later taken over by Jamie
+Zawinski, who became "Mr. Lucid Emacs" for many releases.
+
+   A time line for Lucid Emacs is
+
+   * version 19.0 shipped with Energize 1.0, April 1992.
+
+   * version 19.1 released June 4, 1992.
+
+   * version 19.2 released June 19, 1992.
+
+   * version 19.3 released September 9, 1992.
+
+   * version 19.4 released January 21, 1993.
+
+   * version 19.5 was a repackaging of 19.4 with a few bug fixes and
+     shipped with Energize 2.0.  Never released to the net.
+
+   * version 19.6 released April 9, 1993.
+
+   * version 19.7 was a repackaging of 19.6 with a few bug fixes and
+     shipped with Energize 2.1.  Never released to the net.
+
+   * version 19.8 released September 6, 1993.
+
+   * version 19.9 released January 12, 1994.
+
+   * version 19.10 released May 27, 1994.
+
+   * version 19.11 (first XEmacs) released September 13, 1994.
+
+   * version 19.12 released June 23, 1995.
+
+   * version 19.13 released September 1, 1995.
+
+   * version 19.14 released June 23, 1996.
+
+   * version 20.0 released February 9, 1997.
+
+   * version 19.15 released March 28, 1997.
+
+   * version 20.1 (not released to the net) April 15, 1997.
+
+   * version 20.2 released May 16, 1997.
+
+   * version 19.16 released October 31, 1997.
+
+   * version 20.3 (the first stable version of XEmacs 20.x) released
+     November 30, 1997.
+
+   * version 20.4 released February 28, 1998.
+
+   * version 21.1.2 released May 14, 1999. (The version naming scheme
+     was changed at this point: [a] the second version number is odd
+     for stable versions, even for beta versions; [b] a third version
+     number is added, replacing the "beta xxx" ending for beta versions
+     and allowing for periodic maintenance releases for stable
+     versions.  Therefore, 21.0 was never "officially" released;
+     similarly for 21.2, etc.)
+
+   * version 21.1.3 released June 26, 1999.
+
+   * version 21.1.4 released July 8, 1999.
+
+   * version 21.1.6 released August 14, 1999. (There was no 21.1.5.)
+
+   * version 21.1.7 released September 26, 1999.
+
+   * version 21.1.8 released November 2, 1999.
+
+   * version 21.1.9 released February 13, 2000.
+
+   * version 21.1.10 released May 7, 2000.
+
+   * version 21.1.10a released June 24, 2000.
+
+   * version 21.1.11 released July 18, 2000.
+
+   * version 21.1.12 released August 5, 2000.
+
+   * version 21.1.13 released January 7, 2001.
+
+   * version 21.1.14 released January 27, 2001.
+
+
+File: internals.info,  Node: GNU Emacs 19,  Next: GNU Emacs 20,  Prev: Lucid Emacs,  Up: A History of Emacs
+
+GNU Emacs 19
+============
+
+   About a year after the initial release of Lucid Emacs, the FSF
+released a beta of their version of Emacs 19 (referred to here as "GNU
+Emacs").  By this time, the current version of Lucid Emacs was 19.6.
+(Strangely, the first released beta from the FSF was GNU Emacs 19.7.) A
+time line for GNU Emacs version 19 is
+
+   * version 19.8 (beta) released May 27, 1993.
+
+   * version 19.9 (beta) released May 27, 1993.
+
+   * version 19.10 (beta) released May 30, 1993.
+
+   * version 19.11 (beta) released June 1, 1993.
+
+   * version 19.12 (beta) released June 2, 1993.
+
+   * version 19.13 (beta) released June 8, 1993.
+
+   * version 19.14 (beta) released June 17, 1993.
+
+   * version 19.15 (beta) released June 19, 1993.
+
+   * version 19.16 (beta) released July 6, 1993.
+
+   * version 19.17 (beta) released late July, 1993.
+
+   * version 19.18 (beta) released August 9, 1993.
+
+   * version 19.19 (beta) released August 15, 1993.
+
+   * version 19.20 (beta) released November 17, 1993.
+
+   * version 19.21 (beta) released November 17, 1993.
+
+   * version 19.22 (beta) released November 28, 1993.
+
+   * version 19.23 (beta) released May 17, 1994.
+
+   * version 19.24 (beta) released May 16, 1994.
+
+   * version 19.25 (beta) released June 3, 1994.
+
+   * version 19.26 (beta) released September 11, 1994.
+
+   * version 19.27 (beta) released September 14, 1994.
+
+   * version 19.28 (first "official" release) released November 1, 1994.
+
+   * version 19.29 released June 21, 1995.
+
+   * version 19.30 released November 24, 1995.
+
+   * version 19.31 released May 25, 1996.
+
+   * version 19.32 released July 31, 1996.
+
+   * version 19.33 released August 11, 1996.
+
+   * version 19.34 released August 21, 1996.
+
+   * version 19.34b released September 6, 1996.
+
+   In some ways, GNU Emacs 19 was better than Lucid Emacs; in some ways,
+worse.  Lucid soon began incorporating features from GNU Emacs 19 into
+Lucid Emacs; the work was mostly done by Richard Mlynarik, who had been
+working on and using GNU Emacs for a long time (back as far as version
+16 or 17).
+
+
+File: internals.info,  Node: GNU Emacs 20,  Next: XEmacs,  Prev: GNU Emacs 19,  Up: A History of Emacs
+
+GNU Emacs 20
+============
+
+   On February 2, 1997 work began on GNU Emacs to integrate Mule.  The
+first release was made in September of that year.
+
+   A timeline for Emacs 20 is
+
+   * version 20.1 released September 17, 1997.
+
+   * version 20.2 released September 20, 1997.
+
+   * version 20.3 released August 19, 1998.
+
+
+File: internals.info,  Node: XEmacs,  Prev: GNU Emacs 20,  Up: A History of Emacs
+
+XEmacs
+======
+
+   Around the time that Lucid was developing Energize, Sun Microsystems
+was developing their own development environment (called "SPARCWorks")
+and also decided to use Emacs.  They joined forces with the Epoch team
+at the University of Illinois and later with Lucid.  The maintainer of
+the last-released version of Epoch was Marc Andreessen, but he dropped
+out and the Epoch project, headed by Simon Kaplan, lured Chuck Thompson
+away from a system administration job to become the primary Lucid Emacs
+author for Epoch and Sun.  Chuck's area of specialty became the
+redisplay engine (he replaced the old Lucid Emacs redisplay engine with
+a ported version from Epoch and then later rewrote it from scratch).
+Sun also hired Ben Wing (the author of Win-Emacs, a port of Lucid Emacs
+to Microsoft Windows 3.1) in 1993, for what was initially a one-month
+contract to fix some event problems but later became a many-year
+involvement, punctuated by a six-month contract with Amdahl Corporation.
+
+   In 1994, Sun and Lucid agreed to rename Lucid Emacs to XEmacs (a name
+not favorable to either company); the first release called XEmacs was
+version 19.11.  In June 1994, Lucid folded and Jamie quit to work for
+the newly formed Mosaic Communications Corp., later Netscape
+Communications Corp. (co-founded by the same Marc Andreessen, who had
+quit his Epoch job to work on a graphical browser for the World Wide
+Web).  Chuck then become the primary maintainer of XEmacs, and put out
+versions 19.11 through 19.14 in conjunction with Ben.  For 19.12 and
+19.13, Chuck added the new redisplay and many other display improvements
+and Ben added MULE support (support for Asian and other languages) and
+redesigned most of the internal Lisp subsystems to better support the
+MULE work and the various other features being added to XEmacs.  After
+19.14 Chuck retired as primary maintainer and Steve Baur stepped in.
+
+   Soon after 19.13 was released, work began in earnest on the MULE
+internationalization code and the source tree was divided into two
+development paths.  The MULE version was initially called 19.20, but was
+soon renamed to 20.0.  In 1996 Martin Buchholz of Sun Microsystems took
+over the care and feeding of it and worked on it in parallel with the
+19.14 development that was occurring at the same time.  After much work
+by Martin, it was decided to release 20.0 ahead of 19.15 in February
+1997.  The source tree remained divided until 20.2 when the version 19
+source was finally retired at version 19.16.
+
+   In 1997, Sun finally dropped all pretense of support for XEmacs and
+Martin Buchholz left the company in November.  Since then, and mostly
+for the previous year, because Steve Baur was never paid to work on
+XEmacs, XEmacs has existed solely on the contributions of volunteers
+from the Free Software Community.  Starting from 1997, Hrvoje Niksic and
+Kyle Jones have figured prominently in XEmacs development.
+
+   Many attempts have been made to merge XEmacs and GNU Emacs, but they
+have consistently failed.
+
+   A more detailed history is contained in the XEmacs About page.
+
+   A time line for XEmacs is
+
+   * version 19.11 (first XEmacs) released September 13, 1994.
+
+   * version 19.12 released June 23, 1995.
+
+   * version 19.13 released September 1, 1995.
+
+   * version 19.14 released June 23, 1996.
+
+   * version 20.0 released February 9, 1997.
+
+   * version 19.15 released March 28, 1997.
+
+   * version 20.1 (not released to the net) April 15, 1997.
+
+   * version 20.2 released May 16, 1997.
+
+   * version 19.16 released October 31, 1997.
+
+   * version 20.3 (the first stable version of XEmacs 20.x) released
+     November 30, 1997.
+
+   * version 20.4 released February 28, 1998.
+
+   * version 21.0.60 released December 10, 1998. (The version naming
+     scheme was changed at this point: [a] the second version number is
+     odd for stable versions, even for beta versions; [b] a third
+     version number is added, replacing the "beta xxx" ending for beta
+     versions and allowing for periodic maintenance releases for stable
+     versions.  Therefore, 21.0 was never "officially" released;
+     similarly for 21.2, etc.)
+
+   * version 21.0.61 released January 4, 1999.
+
+   * version 21.0.63 released February 3, 1999.
+
+   * version 21.0.64 released March 1, 1999.
+
+   * version 21.0.65 released March 5, 1999.
+
+   * version 21.0.66 released March 12, 1999.
+
+   * version 21.0.67 released March 25, 1999.
+
+   * version 21.1.2 released May 14, 1999. (This is the followup to
+     21.0.67.  The second version number was bumped to indicate the
+     beginning of the "stable" series.)
+
+   * version 21.1.3 released June 26, 1999.
+
+   * version 21.1.4 released July 8, 1999.
+
+   * version 21.1.6 released August 14, 1999. (There was no 21.1.5.)
+
+   * version 21.1.7 released September 26, 1999.
+
+   * version 21.1.8 released November 2, 1999.
+
+   * version 21.1.9 released February 13, 2000.
+
+   * version 21.1.10 released May 7, 2000.
+
+   * version 21.1.10a released June 24, 2000.
+
+   * version 21.1.11 released July 18, 2000.
+
+   * version 21.1.12 released August 5, 2000.
+
+   * version 21.1.13 released January 7, 2001.
+
+   * version 21.1.14 released January 27, 2001.
+
+   * version 21.2.9 released February 3, 1999.
+
+   * version 21.2.10 released February 5, 1999.
+
+   * version 21.2.11 released March 1, 1999.
+
+   * version 21.2.12 released March 5, 1999.
+
+   * version 21.2.13 released March 12, 1999.
+
+   * version 21.2.14 released May 14, 1999.
+
+   * version 21.2.15 released June 4, 1999.
+
+   * version 21.2.16 released June 11, 1999.
+
+   * version 21.2.17 released June 22, 1999.
+
+   * version 21.2.18 released July 14, 1999.
+
+   * version 21.2.19 released July 30, 1999.
+
+   * version 21.2.20 released November 10, 1999.
+
+   * version 21.2.21 released November 28, 1999.
+
+   * version 21.2.22 released November 29, 1999.
+
+   * version 21.2.23 released December 7, 1999.
+
+   * version 21.2.24 released December 14, 1999.
+
+   * version 21.2.25 released December 24, 1999.
+
+   * version 21.2.26 released December 31, 1999.
+
+   * version 21.2.27 released January 18, 2000.
+
+   * version 21.2.28 released February 7, 2000.
+
+   * version 21.2.29 released February 16, 2000.
+
+   * version 21.2.30 released February 21, 2000.
+
+   * version 21.2.31 released February 23, 2000.
+
+   * version 21.2.32 released March 20, 2000.
+
+   * version 21.2.33 released May 1, 2000.
+
+   * version 21.2.34 released May 28, 2000.
+
+   * version 21.2.35 released July 19, 2000.
+
+   * version 21.2.36 released October 4, 2000.
+
+   * version 21.2.37 released November 14, 2000.
+
+   * version 21.2.38 released December 5, 2000.
+
+   * version 21.2.39 released December 31, 2000.
+
+   * version 21.2.40 released January 8, 2001.
+
+   * version 21.2.41 released January 17, 2001.
+
+   * version 21.2.42 released January 20, 2001.
+
+   * version 21.2.43 released January 26, 2001.
+
+   * version 21.2.44 released February 8, 2001.
+
+   * version 21.2.45 released February 23, 2001.
+
+   * version 21.2.46 released March 21, 2001.
+
+
+File: internals.info,  Node: XEmacs From the Outside,  Next: The Lisp Language,  Prev: A History of Emacs,  Up: Top
+
+XEmacs From the Outside
+***********************
+
+   XEmacs appears to the outside world as an editor, but it is really a
+Lisp environment.  At its heart is a Lisp interpreter; it also
+"happens" to contain many specialized object types (e.g. buffers,
+windows, frames, events) that are useful for implementing an editor.
+Some of these objects (in particular windows and frames) have
+displayable representations, and XEmacs provides a function
+`redisplay()' that ensures that the display of all such objects matches
+their internal state.  Most of the time, a standard Lisp environment is
+in a "read-eval-print" loop--i.e. "read some Lisp code, execute it, and
+print the results".  XEmacs has a similar loop:
+
+   * read an event
+
+   * dispatch the event (i.e. "do it")
+
+   * redisplay
+
+   Reading an event is done using the Lisp function `next-event', which
+waits for something to happen (typically, the user presses a key or
+moves the mouse) and returns an event object describing this.
+Dispatching an event is done using the Lisp function `dispatch-event',
+which looks up the event in a keymap object (a particular kind of
+object that associates an event with a Lisp function) and calls that
+function.  The function "does" what the user has requested by changing
+the state of particular frame objects, buffer objects, etc.  Finally,
+`redisplay()' is called, which updates the display to reflect those
+changes just made.  Thus is an "editor" born.
+
+   Note that you do not have to use XEmacs as an editor; you could just
+as well make it do your taxes, compute pi, play bridge, etc.  You'd just
+have to write functions to do those operations in Lisp.
+
+
+File: internals.info,  Node: The Lisp Language,  Next: XEmacs From the Perspective of Building,  Prev: XEmacs From the Outside,  Up: Top
+
+The Lisp Language
+*****************
+
+   Lisp is a general-purpose language that is higher-level than C and in
+many ways more powerful than C.  Powerful dialects of Lisp such as
+Common Lisp are probably much better languages for writing very large
+applications than is C. (Unfortunately, for many non-technical reasons
+C and its successor C++ have become the dominant languages for
+application development.  These languages are both inadequate for
+extremely large applications, which is evidenced by the fact that newer,
+larger programs are becoming ever harder to write and are requiring ever
+more programmers despite great increases in C development environments;
+and by the fact that, although hardware speeds and reliability have been
+growing at an exponential rate, most software is still generally
+considered to be slow and buggy.)
+
+   The new Java language holds promise as a better general-purpose
+development language than C.  Java has many features in common with
+Lisp that are not shared by C (this is not a coincidence, since Java
+was designed by James Gosling, a former Lisp hacker).  This will be
+discussed more later.
+
+   For those used to C, here is a summary of the basic differences
+between C and Lisp:
+
+  1. Lisp has an extremely regular syntax.  Every function, expression,
+     and control statement is written in the form
+
+             (FUNC ARG1 ARG2 ...)
+
+     This is as opposed to C, which writes functions as
+
+             func(ARG1, ARG2, ...)
+
+     but writes expressions involving operators as (e.g.)
+
+             ARG1 + ARG2
+
+     and writes control statements as (e.g.)
+
+             while (EXPR) { STATEMENT1; STATEMENT2; ... }
+
+     Lisp equivalents of the latter two would be
+
+             (+ ARG1 ARG2 ...)
+
+     and
+
+             (while EXPR STATEMENT1 STATEMENT2 ...)
+
+  2. Lisp is a safe language.  Assuming there are no bugs in the Lisp
+     interpreter/compiler, it is impossible to write a program that
+     "core dumps" or otherwise causes the machine to execute an illegal
+     instruction.  This is very different from C, where perhaps the most
+     common outcome of a bug is exactly such a crash.  A corollary of
+     this is that the C operation of casting a pointer is impossible
+     (and unnecessary) in Lisp, and that it is impossible to access
+     memory outside the bounds of an array.
+
+  3. Programs and data are written in the same form.  The
+     parenthesis-enclosing form described above for statements is the
+     same form used for the most common data type in Lisp, the list.
+     Thus, it is possible to represent any Lisp program using Lisp data
+     types, and for one program to construct Lisp statements and then
+     dynamically "evaluate" them, or cause them to execute.
+
+  4. All objects are "dynamically typed".  This means that part of every
+     object is an indication of what type it is.  A Lisp program can
+     manipulate an object without knowing what type it is, and can
+     query an object to determine its type.  This means that,
+     correspondingly, variables and function parameters can hold
+     objects of any type and are not normally declared as being of any
+     particular type.  This is opposed to the "static typing" of C,
+     where variables can hold exactly one type of object and must be
+     declared as such, and objects do not contain an indication of
+     their type because it's implicit in the variables they are stored
+     in.  It is possible in C to have a variable hold different types
+     of objects (e.g. through the use of `void *' pointers or
+     variable-argument functions), but the type information must then be
+     passed explicitly in some other fashion, leading to additional
+     program complexity.
+
+  5. Allocated memory is automatically reclaimed when it is no longer
+     in use.  This operation is called "garbage collection" and
+     involves looking through all variables to see what memory is being
+     pointed to, and reclaiming any memory that is not pointed to and
+     is thus "inaccessible" and out of use.  This is as opposed to C,
+     in which allocated memory must be explicitly reclaimed using
+     `free()'.  If you simply drop all pointers to memory without
+     freeing it, it becomes "leaked" memory that still takes up space.
+     Over a long period of time, this can cause your program to grow
+     and grow until it runs out of memory.
+
+  6. Lisp has built-in facilities for handling errors and exceptions.
+     In C, when an error occurs, usually either the program exits
+     entirely or the routine in which the error occurs returns a value
+     indicating this.  If an error occurs in a deeply-nested routine,
+     then every routine currently called must unwind itself normally
+     and return an error value back up to the next routine.  This means
+     that every routine must explicitly check for an error in all the
+     routines it calls; if it does not do so, unexpected and often
+     random behavior results.  This is an extremely common source of
+     bugs in C programs.  An alternative would be to do a non-local
+     exit using `longjmp()', but that is often very dangerous because
+     the routines that were exited past had no opportunity to clean up
+     after themselves and may leave things in an inconsistent state,
+     causing a crash shortly afterwards.
+
+     Lisp provides mechanisms to make such non-local exits safe.  When
+     an error occurs, a routine simply signals that an error of a
+     particular class has occurred, and a non-local exit takes place.
+     Any routine can trap errors occurring in routines it calls by
+     registering an error handler for some or all classes of errors.
+     (If no handler is registered, a default handler, generally
+     installed by the top-level event loop, is executed; this prints
+     out the error and continues.) Routines can also specify cleanup
+     code (called an "unwind-protect") that will be called when control
+     exits from a block of code, no matter how that exit occurs--i.e.
+     even if a function deeply nested below it causes a non-local exit
+     back to the top level.
+
+     Note that this facility has appeared in some recent vintages of C,
+     in particular Visual C++ and other PC compilers written for the
+     Microsoft Win32 API.
+
+  7. In Emacs Lisp, local variables are "dynamically scoped".  This
+     means that if you declare a local variable in a particular
+     function, and then call another function, that subfunction can
+     "see" the local variable you declared.  This is actually
+     considered a bug in Emacs Lisp and in all other early dialects of
+     Lisp, and was corrected in Common Lisp. (In Common Lisp, you can
+     still declare dynamically scoped variables if you want to--they
+     are sometimes useful--but variables by default are "lexically
+     scoped" as in C.)
+
+   For those familiar with Lisp, Emacs Lisp is modelled after MacLisp,
+an early dialect of Lisp developed at MIT (no relation to the Macintosh
+computer).  There is a Common Lisp compatibility package available for
+Emacs that provides many of the features of Common Lisp.
+
+   The Java language is derived in many ways from C, and shares a
+similar syntax, but has the following features in common with Lisp (and
+different from C):
+
+  1. Java is a safe language, like Lisp.
+
+  2. Java provides garbage collection, like Lisp.
+
+  3. Java has built-in facilities for handling errors and exceptions,
+     like Lisp.
+
+  4. Java has a type system that combines the best advantages of both
+     static and dynamic typing.  Objects (except very simple types) are
+     explicitly marked with their type, as in dynamic typing; but there
+     is a hierarchy of types and functions are declared to accept only
+     certain types, thus providing the increased compile-time
+     error-checking of static typing.
+
+   The Java language also has some negative attributes:
+
+  1. Java uses the edit/compile/run model of software development.  This
+     makes it hard to use interactively.  For example, to use Java like
+     `bc' it is necessary to write a special purpose, albeit tiny,
+     application.  In Emacs Lisp, a calculator comes built-in without
+     any effort - one can always just type an expression in the
+     `*scratch*' buffer.
+
+  2. Java tries too hard to enforce, not merely enable, portability,
+     making ordinary access to standard OS facilities painful.  Java
+     has an "agenda".  I think this is why `chdir' is not part of
+     standard Java, which is inexcusable.
+
+   Unfortunately, there is no perfect language.  Static typing allows a
+compiler to catch programmer errors and produce more efficient code, but
+makes programming more tedious and less fun.  For the foreseeable
+future, an Ideal Editing and Programming Environment (and that is what
+XEmacs aspires to) will be programmable in multiple languages: high
+level ones like Lisp for user customization and prototyping, and lower
+level ones for infrastructure and industrial strength applications.  If
+I had my way, XEmacs would be friendly towards the Python, Scheme, C++,
+ML, etc... communities.  But there are serious technical difficulties to
+achieving that goal.
+
+   The word "application" in the previous paragraph was used
+intentionally.  XEmacs implements an API for programs written in Lisp
+that makes it a full-fledged application platform, very much like an OS
+inside the real OS.
+
+
+File: internals.info,  Node: XEmacs From the Perspective of Building,  Next: XEmacs From the Inside,  Prev: The Lisp Language,  Up: Top
+
+XEmacs From the Perspective of Building
+***************************************
+
+   The heart of XEmacs is the Lisp environment, which is written in C.
+This is contained in the `src/' subdirectory.  Underneath `src/' are
+two subdirectories of header files: `s/' (header files for particular
+operating systems) and `m/' (header files for particular machine
+types).  In practice the distinction between the two types of header
+files is blurred.  These header files define or undefine certain
+preprocessor constants and macros to indicate particular
+characteristics of the associated machine or operating system.  As part
+of the configure process, one `s/' file and one `m/' file is identified
+for the particular environment in which XEmacs is being built.
+
+   XEmacs also contains a great deal of Lisp code.  This implements the
+operations that make XEmacs useful as an editor as well as just a Lisp
+environment, and also contains many add-on packages that allow XEmacs to
+browse directories, act as a mail and Usenet news reader, compile Lisp
+code, etc.  There is actually more Lisp code than C code associated with
+XEmacs, but much of the Lisp code is peripheral to the actual operation
+of the editor.  The Lisp code all lies in subdirectories underneath the
+`lisp/' directory.
+
+   The `lwlib/' directory contains C code that implements a generalized
+interface onto different X widget toolkits and also implements some
+widgets of its own that behave like Motif widgets but are faster, free,
+and in some cases more powerful.  The code in this directory compiles
+into a library and is mostly independent from XEmacs.
+
+   The `etc/' directory contains various data files associated with
+XEmacs.  Some of them are actually read by XEmacs at startup; others
+merely contain useful information of various sorts.
+
+   The `lib-src/' directory contains C code for various auxiliary
+programs that are used in connection with XEmacs.  Some of them are used
+during the build process; others are used to perform certain functions
+that cannot conveniently be placed in the XEmacs executable (e.g. the
+`movemail' program for fetching mail out of `/var/spool/mail', which
+must be setgid to `mail' on many systems; and the `gnuclient' program,
+which allows an external script to communicate with a running XEmacs
+process).
+
+   The `man/' directory contains the sources for the XEmacs
+documentation.  It is mostly in a form called Texinfo, which can be
+converted into either a printed document (by passing it through TeX) or
+into on-line documentation called "info files".
+
+   The `info/' directory contains the results of formatting the XEmacs
+documentation as "info files", for on-line use.  These files are used
+when you enter the Info system using `C-h i' or through the Help menu.
+
+   The `dynodump/' directory contains auxiliary code used to build
+XEmacs on Solaris platforms.
+
+   The other directories contain various miscellaneous code and
+information that is not normally used or needed.
+
+   The first step of building involves running the `configure' program
+and passing it various parameters to specify any optional features you
+want and compiler arguments and such, as described in the `INSTALL'
+file.  This determines what the build environment is, chooses the
+appropriate `s/' and `m/' file, and runs a series of tests to determine
+many details about your environment, such as which library functions
+are available and exactly how they work.  The reason for running these
+tests is that it allows XEmacs to be compiled on a much wider variety
+of platforms than those that the XEmacs developers happen to be
+familiar with, including various sorts of hybrid platforms.  This is
+especially important now that many operating systems give you a great
+deal of control over exactly what features you want installed, and allow
+for easy upgrading of parts of a system without upgrading the rest.  It
+would be impossible to pre-determine and pre-specify the information for
+all possible configurations.
+
+   In fact, the `s/' and `m/' files are basically _evil_, since they
+contain unmaintainable platform-specific hard-coded information.
+XEmacs has been moving in the direction of having all system-specific
+information be determined dynamically by `configure'.  Perhaps someday
+we can `rm -rf src/s src/m'.
+
+   When configure is done running, it generates `Makefile's and
+`GNUmakefile's and the file `src/config.h' (which describes the
+features of your system) from template files.  You then run `make',
+which compiles the auxiliary code and programs in `lib-src/' and
+`lwlib/' and the main XEmacs executable in `src/'.  The result of
+compiling and linking is an executable called `temacs', which is _not_
+the final XEmacs executable.  `temacs' by itself is not intended to
+function as an editor or even display any windows on the screen, and if
+you simply run it, it will exit immediately.  The `Makefile' runs
+`temacs' with certain options that cause it to initialize itself, read
+in a number of basic Lisp files, and then dump itself out into a new
+executable called `xemacs'.  This new executable has been
+pre-initialized and contains pre-digested Lisp code that is necessary
+for the editor to function (this includes most basic editing functions,
+e.g. `kill-line', that can be defined in terms of other Lisp
+primitives; some initialization code that is called when certain
+objects, such as frames, are created; and all of the standard
+keybindings and code for the actions they result in).  This executable,
+`xemacs', is the executable that you run to use the XEmacs editor.
+
+   Although `temacs' is not intended to be run as an editor, it can, by
+using the incantation `temacs -batch -l loadup.el run-temacs'.  This is
+useful when the dumping procedure described above is broken, or when
+using certain program debugging tools such as Purify.  These tools get
+mighty confused by the tricks played by the XEmacs build process, such
+as allocation memory in one process, and freeing it in the next.
+
+
+File: internals.info,  Node: XEmacs From the Inside,  Next: The XEmacs Object System (Abstractly Speaking),  Prev: XEmacs From the Perspective of Building,  Up: Top
+
+XEmacs From the Inside
+**********************
+
+   Internally, XEmacs is quite complex, and can be very confusing.  To
+simplify things, it can be useful to think of XEmacs as containing an
+event loop that "drives" everything, and a number of other subsystems,
+such as a Lisp engine and a redisplay mechanism.  Each of these other
+subsystems exists simultaneously in XEmacs, and each has a certain
+state.  The flow of control continually passes in and out of these
+different subsystems in the course of normal operation of the editor.
+
+   It is important to keep in mind that, most of the time, the editor is
+"driven" by the event loop.  Except during initialization and batch
+mode, all subsystems are entered directly or indirectly through the
+event loop, and ultimately, control exits out of all subsystems back up
+to the event loop.  This cycle of entering a subsystem, exiting back out
+to the event loop, and starting another iteration of the event loop
+occurs once each keystroke, mouse motion, etc.
+
+   If you're trying to understand a particular subsystem (other than the
+event loop), think of it as a "daemon" process or "servant" that is
+responsible for one particular aspect of a larger system, and
+periodically receives commands or environment changes that cause it to
+do something.  Ultimately, these commands and environment changes are
+always triggered by the event loop.  For example:
+
+   * The window and frame mechanism is responsible for keeping track of
+     what windows and frames exist, what buffers are in them, etc.  It
+     is periodically given commands (usually from the user) to make a
+     change to the current window/frame state: i.e. create a new frame,
+     delete a window, etc.
+
+   * The buffer mechanism is responsible for keeping track of what
+     buffers exist and what text is in them.  It is periodically given
+     commands (usually from the user) to insert or delete text, create
+     a buffer, etc.  When it receives a text-change command, it
+     notifies the redisplay mechanism.
+
+   * The redisplay mechanism is responsible for making sure that
+     windows and frames are displayed correctly.  It is periodically
+     told (by the event loop) to actually "do its job", i.e. snoop
+     around and see what the current state of the environment (mostly
+     of the currently-existing windows, frames, and buffers) is, and
+     make sure that that state matches what's actually displayed.  It
+     keeps lots and lots of information around (such as what is
+     actually being displayed currently, and what the environment was
+     last time it checked) so that it can minimize the work it has to
+     do.  It is also helped along in that whenever a relevant change to
+     the environment occurs, the redisplay mechanism is told about
+     this, so it has a pretty good idea of where it has to look to find
+     possible changes and doesn't have to look everywhere.
+
+   * The Lisp engine is responsible for executing the Lisp code in
+     which most user commands are written.  It is entered through a
+     call to `eval' or `funcall', which occurs as a result of
+     dispatching an event from the event loop.  The functions it calls
+     issue commands to the buffer mechanism, the window/frame
+     subsystem, etc.
+
+   * The Lisp allocation subsystem is responsible for keeping track of
+     Lisp objects.  It is given commands from the Lisp engine to
+     allocate objects, garbage collect, etc.
+
+   etc.
+
+   The important idea here is that there are a number of independent
+subsystems each with its own responsibility and persistent state, just
+like different employees in a company, and each subsystem is
+periodically given commands from other subsystems.  Commands can flow
+from any one subsystem to any other, but there is usually some sort of
+hierarchy, with all commands originating from the event subsystem.
+
+   XEmacs is entered in `main()', which is in `emacs.c'.  When this is
+called the first time (in a properly-invoked `temacs'), it does the
+following:
+
+  1. It does some very basic environment initializations, such as
+     determining where it and its directories (e.g. `lisp/' and `etc/')
+     reside and setting up signal handlers.
+
+  2. It initializes the entire Lisp interpreter.
+
+  3. It sets the initial values of many built-in variables (including
+     many variables that are visible to Lisp programs), such as the
+     global keymap object and the built-in faces (a face is an object
+     that describes the display characteristics of text).  This
+     involves creating Lisp objects and thus is dependent on step (2).
+
+  4. It performs various other initializations that are relevant to the
+     particular environment it is running in, such as retrieving
+     environment variables, determining the current date and the user
+     who is running the program, examining its standard input, creating
+     any necessary file descriptors, etc.
+
+  5. At this point, the C initialization is complete.  A Lisp program
+     that was specified on the command line (usually `loadup.el') is
+     called (temacs is normally invoked as `temacs -batch -l loadup.el
+     dump').  `loadup.el' loads all of the other Lisp files that are
+     needed for the operation of the editor, calls the `dump-emacs'
+     function to write out `xemacs', and then kills the temacs process.
+
+   When `xemacs' is then run, it only redoes steps (1) and (4) above;
+all variables already contain the values they were set to when the
+executable was dumped, and all memory that was allocated with
+`malloc()' is still around. (XEmacs knows whether it is being run as
+`xemacs' or `temacs' because it sets the global variable `initialized'
+to 1 after step (4) above.) At this point, `xemacs' calls a Lisp
+function to do any further initialization, which includes parsing the
+command-line (the C code can only do limited command-line parsing,
+which includes looking for the `-batch' and `-l' flags and a few other
+flags that it needs to know about before initialization is complete),
+creating the first frame (or "window" in standard window-system
+parlance), running the user's init file (usually the file `.emacs' in
+the user's home directory), etc.  The function to do this is usually
+called `normal-top-level'; `loadup.el' tells the C code about this
+function by setting its name as the value of the Lisp variable
+`top-level'.
+
+   When the Lisp initialization code is done, the C code enters the
+event loop, and stays there for the duration of the XEmacs process.
+The code for the event loop is contained in `cmdloop.c', and is called
+`Fcommand_loop_1()'.  Note that this event loop could very well be
+written in Lisp, and in fact a Lisp version exists; but apparently,
+doing this makes XEmacs run noticeably slower.
+
+   Notice how much of the initialization is done in Lisp, not in C.  In
+general, XEmacs tries to move as much code as is possible into Lisp.
+Code that remains in C is code that implements the Lisp interpreter
+itself, or code that needs to be very fast, or code that needs to do
+system calls or other such stuff that needs to be done in C, or code
+that needs to have access to "forbidden" structures. (One conscious
+aspect of the design of Lisp under XEmacs is a clean separation between
+the external interface to a Lisp object's functionality and its internal
+implementation.  Part of this design is that Lisp programs are
+forbidden from accessing the contents of the object other than through
+using a standard API.  In this respect, XEmacs Lisp is similar to
+modern Lisp dialects but differs from GNU Emacs, which tends to expose
+the implementation and allow Lisp programs to look at it directly.  The
+major advantage of hiding the implementation is that it allows the
+implementation to be redesigned without affecting any Lisp programs,
+including those that might want to be "clever" by looking directly at
+the object's contents and possibly manipulating them.)
+
+   Moving code into Lisp makes the code easier to debug and maintain and
+makes it much easier for people who are not XEmacs developers to
+customize XEmacs, because they can make a change with much less chance
+of obscure and unwanted interactions occurring than if they were to
+change the C code.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-2'
Index: ././info/internals.info-2
--- ././info/internals.info-2	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-2	Thu May 17 23:26:54 2001
@@ -0,0 +1,1089 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: The XEmacs Object System (Abstractly Speaking),  Next: How Lisp Objects Are Represented in C,  Prev: XEmacs From the Inside,  Up: Top
+
+The XEmacs Object System (Abstractly Speaking)
+**********************************************
+
+   At the heart of the Lisp interpreter is its management of objects.
+XEmacs Lisp contains many built-in objects, some of which are simple
+and others of which can be very complex; and some of which are very
+common, and others of which are rarely used or are only used
+internally. (Since the Lisp allocation system, with its automatic
+reclamation of unused storage, is so much more convenient than
+`malloc()' and `free()', the C code makes extensive use of it in its
+internal operations.)
+
+   The basic Lisp objects are
+
+`integer'
+     28 or 31 bits of precision, or 60 or 63 bits on 64-bit machines;
+     the reason for this is described below when the internal Lisp
+     object representation is described.
+
+`float'
+     Same precision as a double in C.
+
+`cons'
+     A simple container for two Lisp objects, used to implement lists
+     and most other data structures in Lisp.
+
+`char'
+     An object representing a single character of text; chars behave
+     like integers in many ways but are logically considered text
+     rather than numbers and have a different read syntax. (the read
+     syntax for a char contains the char itself or some textual
+     encoding of it--for example, a Japanese Kanji character might be
+     encoded as `^[$(B#&^[(B' using the ISO-2022 encoding
+     standard--rather than the numerical representation of the char;
+     this way, if the mapping between chars and integers changes, which
+     is quite possible for Kanji characters and other extended
+     characters, the same character will still be created.  Note that
+     some primitives confuse chars and integers.  The worst culprit is
+     `eq', which makes a special exception and considers a char to be
+     `eq' to its integer equivalent, even though in no other case are
+     objects of two different types `eq'.  The reason for this
+     monstrosity is compatibility with existing code; the separation of
+     char from integer came fairly recently.)
+
+`symbol'
+     An object that contains Lisp objects and is referred to by name;
+     symbols are used to implement variables and named functions and to
+     provide the equivalent of preprocessor constants in C.
+
+`vector'
+     A one-dimensional array of Lisp objects providing constant-time
+     access to any of the objects; access to an arbitrary object in a
+     vector is faster than for lists, but the operations that can be
+     done on a vector are more limited.
+
+`string'
+     Self-explanatory; behaves much like a vector of chars but has a
+     different read syntax and is stored and manipulated more compactly.
+
+`bit-vector'
+     A vector of bits; similar to a string in spirit.
+
+`compiled-function'
+     An object containing compiled Lisp code, known as "byte code".
+
+`subr'
+     A Lisp primitive, i.e. a Lisp-callable function implemented in C.
+
+   Note that there is no basic "function" type, as in more powerful
+versions of Lisp (where it's called a "closure").  XEmacs Lisp does not
+provide the closure semantics implemented by Common Lisp and Scheme.
+The guts of a function in XEmacs Lisp are represented in one of four
+ways: a symbol specifying another function (when one function is an
+alias for another), a list (whose first element must be the symbol
+`lambda') containing the function's source code, a compiled-function
+object, or a subr object. (In other words, given a symbol specifying
+the name of a function, calling `symbol-function' to retrieve the
+contents of the symbol's function cell will return one of these types
+of objects.)
+
+   XEmacs Lisp also contains numerous specialized objects used to
+implement the editor:
+
+`buffer'
+     Stores text like a string, but is optimized for insertion and
+     deletion and has certain other properties that can be set.
+
+`frame'
+     An object with various properties whose displayable representation
+     is a "window" in window-system parlance.
+
+`window'
+     A section of a frame that displays the contents of a buffer; often
+     called a "pane" in window-system parlance.
+
+`window-configuration'
+     An object that represents a saved configuration of windows in a
+     frame.
+
+`device'
+     An object representing a screen on which frames can be displayed;
+     equivalent to a "display" in the X Window System and a "TTY" in
+     character mode.
+
+`face'
+     An object specifying the appearance of text or graphics; it has
+     properties such as font, foreground color, and background color.
+
+`marker'
+     An object that refers to a particular position in a buffer and
+     moves around as text is inserted and deleted to stay in the same
+     relative position to the text around it.
+
+`extent'
+     Similar to a marker but covers a range of text in a buffer; can
+     also specify properties of the text, such as a face in which the
+     text is to be displayed, whether the text is invisible or
+     unmodifiable, etc.
+
+`event'
+     Generated by calling `next-event' and contains information
+     describing a particular event happening in the system, such as the
+     user pressing a key or a process terminating.
+
+`keymap'
+     An object that maps from events (described using lists, vectors,
+     and symbols rather than with an event object because the mapping
+     is for classes of events, rather than individual events) to
+     functions to execute or other events to recursively look up; the
+     functions are described by name, using a symbol, or using lists to
+     specify the function's code.
+
+`glyph'
+     An object that describes the appearance of an image (e.g.  pixmap)
+     on the screen; glyphs can be attached to the beginning or end of
+     extents and in some future version of XEmacs will be able to be
+     inserted directly into a buffer.
+
+`process'
+     An object that describes a connection to an externally-running
+     process.
+
+   There are some other, less-commonly-encountered general objects:
+
+`hash-table'
+     An object that maps from an arbitrary Lisp object to another
+     arbitrary Lisp object, using hashing for fast lookup.
+
+`obarray'
+     A limited form of hash-table that maps from strings to symbols;
+     obarrays are used to look up a symbol given its name and are not
+     actually their own object type but are kludgily represented using
+     vectors with hidden fields (this representation derives from GNU
+     Emacs).
+
+`specifier'
+     A complex object used to specify the value of a display property; a
+     default value is given and different values can be specified for
+     particular frames, buffers, windows, devices, or classes of device.
+
+`char-table'
+     An object that maps from chars or classes of chars to arbitrary
+     Lisp objects; internally char tables use a complex nested-vector
+     representation that is optimized to the way characters are
+     represented as integers.
+
+`range-table'
+     An object that maps from ranges of integers to arbitrary Lisp
+     objects.
+
+   And some strange special-purpose objects:
+
+`charset'
+`coding-system'
+     Objects used when MULE, or multi-lingual/Asian-language, support is
+     enabled.
+
+`color-instance'
+`font-instance'
+`image-instance'
+     An object that encapsulates a window-system resource; instances are
+     mostly used internally but are exposed on the Lisp level for
+     cleanness of the specifier model and because it's occasionally
+     useful for Lisp program to create or query the properties of
+     instances.
+
+`subwindow'
+     An object that encapsulate a "subwindow" resource, i.e. a
+     window-system child window that is drawn into by an external
+     process; this object should be integrated into the glyph system
+     but isn't yet, and may change form when this is done.
+
+`tooltalk-message'
+`tooltalk-pattern'
+     Objects that represent resources used in the ToolTalk interprocess
+     communication protocol.
+
+`toolbar-button'
+     An object used in conjunction with the toolbar.
+
+   And objects that are only used internally:
+
+`opaque'
+     A generic object for encapsulating arbitrary memory; this allows
+     you the generality of `malloc()' and the convenience of the Lisp
+     object system.
+
+`lstream'
+     A buffering I/O stream, used to provide a unified interface to
+     anything that can accept output or provide input, such as a file
+     descriptor, a stdio stream, a chunk of memory, a Lisp buffer, a
+     Lisp string, etc.; it's a Lisp object to make its memory
+     management more convenient.
+
+`char-table-entry'
+     Subsidiary objects in the internal char-table representation.
+
+`extent-auxiliary'
+`menubar-data'
+`toolbar-data'
+     Various special-purpose objects that are basically just used to
+     encapsulate memory for particular subsystems, similar to the more
+     general "opaque" object.
+
+`symbol-value-forward'
+`symbol-value-buffer-local'
+`symbol-value-varalias'
+`symbol-value-lisp-magic'
+     Special internal-only objects that are placed in the value cell of
+     a symbol to indicate that there is something special with this
+     variable - e.g. it has no value, it mirrors another variable, or
+     it mirrors some C variable; there is really only one kind of
+     object, called a "symbol-value-magic", but it is sort-of halfway
+     kludged into semi-different object types.
+
+   Some types of objects are "permanent", meaning that once created,
+they do not disappear until explicitly destroyed, using a function such
+as `delete-buffer', `delete-window', `delete-frame', etc.  Others will
+disappear once they are not longer used, through the garbage collection
+mechanism.  Buffers, frames, windows, devices, and processes are among
+the objects that are permanent.  Note that some objects can go both
+ways: Faces can be created either way; extents are normally permanent,
+but detached extents (extents not referring to any text, as happens to
+some extents when the text they are referring to is deleted) are
+temporary.  Note that some permanent objects, such as faces and coding
+systems, cannot be deleted.  Note also that windows are unique in that
+they can be _undeleted_ after having previously been deleted. (This
+happens as a result of restoring a window configuration.)
+
+   Note that many types of objects have a "read syntax", i.e. a way of
+specifying an object of that type in Lisp code.  When you load a Lisp
+file, or type in code to be evaluated, what really happens is that the
+function `read' is called, which reads some text and creates an object
+based on the syntax of that text; then `eval' is called, which possibly
+does something special; then this loop repeats until there's no more
+text to read. (`eval' only actually does something special with
+symbols, which causes the symbol's value to be returned, similar to
+referencing a variable; and with conses [i.e. lists], which cause a
+function invocation.  All other values are returned unchanged.)
+
+   The read syntax
+
+     17297
+
+   converts to an integer whose value is 17297.
+
+     1.983e-4
+
+   converts to a float whose value is 1.983e-4, or .0001983.
+
+     ?b
+
+   converts to a char that represents the lowercase letter b.
+
+     ?^[$(B#&^[(B
+
+   (where `^[' actually is an `ESC' character) converts to a particular
+Kanji character when using an ISO2022-based coding system for input.
+(To decode this goo: `ESC' begins an escape sequence; `ESC $ (' is a
+class of escape sequences meaning "switch to a 94x94 character set";
+`ESC $ ( B' means "switch to Japanese Kanji"; `#' and `&' collectively
+index into a 94-by-94 array of characters [subtract 33 from the ASCII
+value of each character to get the corresponding index]; `ESC (' is a
+class of escape sequences meaning "switch to a 94 character set"; `ESC
+(B' means "switch to US ASCII".  It is a coincidence that the letter
+`B' is used to denote both Japanese Kanji and US ASCII.  If the first
+`B' were replaced with an `A', you'd be requesting a Chinese Hanzi
+character from the GB2312 character set.)
+
+     "foobar"
+
+   converts to a string.
+
+     foobar
+
+   converts to a symbol whose name is `"foobar"'.  This is done by
+looking up the string equivalent in the global variable `obarray',
+whose contents should be an obarray.  If no symbol is found, a new
+symbol with the name `"foobar"' is automatically created and added to
+`obarray'; this process is called "interning" the symbol.
+
+     (foo . bar)
+
+   converts to a cons cell containing the symbols `foo' and `bar'.
+
+     (1 a 2.5)
+
+   converts to a three-element list containing the specified objects
+(note that a list is actually a set of nested conses; see the XEmacs
+Lisp Reference).
+
+     [1 a 2.5]
+
+   converts to a three-element vector containing the specified objects.
+
+     #[... ... ... ...]
+
+   converts to a compiled-function object (the actual contents are not
+shown since they are not relevant here; look at a file that ends with
+`.elc' for examples).
+
+     #*01110110
+
+   converts to a bit-vector.
+
+     #s(hash-table ... ...)
+
+   converts to a hash table (the actual contents are not shown).
+
+     #s(range-table ... ...)
+
+   converts to a range table (the actual contents are not shown).
+
+     #s(char-table ... ...)
+
+   converts to a char table (the actual contents are not shown).
+
+   Note that the `#s()' syntax is the general syntax for structures,
+which are not really implemented in XEmacs Lisp but should be.
+
+   When an object is printed out (using `print' or a related function),
+the read syntax is used, so that the same object can be read in again.
+
+   The other objects do not have read syntaxes, usually because it does
+not really make sense to create them in this fashion (i.e.  processes,
+where it doesn't make sense to have a subprocess created as a side
+effect of reading some Lisp code), or because they can't be created at
+all (e.g. subrs).  Permanent objects, as a rule, do not have a read
+syntax; nor do most complex objects, which contain too much state to be
+easily initialized through a read syntax.
+
+
+File: internals.info,  Node: How Lisp Objects Are Represented in C,  Next: Rules When Writing New C Code,  Prev: The XEmacs Object System (Abstractly Speaking),  Up: Top
+
+How Lisp Objects Are Represented in C
+*************************************
+
+   Lisp objects are represented in C using a 32-bit or 64-bit machine
+word (depending on the processor; i.e. DEC Alphas use 64-bit Lisp
+objects and most other processors use 32-bit Lisp objects).  The
+representation stuffs a pointer together with a tag, as follows:
+
+      [ 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 ]
+      [ 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 ]
+     
+        <---------------------------------------------------------> <->
+                 a pointer to a structure, or an integer            tag
+
+   A tag of 00 is used for all pointer object types, a tag of 10 is used
+for characters, and the other two tags 01 and 11 are joined together to
+form the integer object type.  This representation gives us 31 bit
+integers and 30 bit characters, while pointers are represented directly
+without any bit masking or shifting.  This representation, though,
+assumes that pointers to structs are always aligned to multiples of 4,
+so the lower 2 bits are always zero.
+
+   Lisp objects use the typedef `Lisp_Object', but the actual C type
+used for the Lisp object can vary.  It can be either a simple type
+(`long' on the DEC Alpha, `int' on other machines) or a structure whose
+fields are bit fields that line up properly (actually, a union of
+structures is used).  Generally the simple integral type is preferable
+because it ensures that the compiler will actually use a machine word
+to represent the object (some compilers will use more general and less
+efficient code for unions and structs even if they can fit in a machine
+word).  The union type, however, has the advantage of stricter type
+checking.  If you accidentally pass an integer where a Lisp object is
+desired, you get a compile error.  The choice of which type to use is
+determined by the preprocessor constant `USE_UNION_TYPE' which is
+defined via the `--use-union-type' option to `configure'.
+
+   Various macros are used to convert between Lisp_Objects and the
+corresponding C type.  Macros of the form `XINT()', `XCHAR()',
+`XSTRING()', `XSYMBOL()', do any required bit shifting and/or masking
+and cast it to the appropriate type.  `XINT()' needs to be a bit tricky
+so that negative numbers are properly sign-extended.  Since integers
+are stored left-shifted, if the right-shift operator does an arithmetic
+shift (i.e. it leaves the most-significant bit as-is rather than
+shifting in a zero, so that it mimics a divide-by-two even for negative
+numbers) the shift to remove the tag bit is enough.  This is the case
+on all the systems we support.
+
+   Note that when `ERROR_CHECK_TYPECHECK' is defined, the converter
+macros become more complicated--they check the tag bits and/or the type
+field in the first four bytes of a record type to ensure that the
+object is really of the correct type.  This is great for catching places
+where an incorrect type is being dereferenced--this typically results
+in a pointer being dereferenced as the wrong type of structure, with
+unpredictable (and sometimes not easily traceable) results.
+
+   There are similar `XSETTYPE()' macros that construct a Lisp object.
+These macros are of the form `XSETTYPE (LVALUE, RESULT)', i.e. they
+have to be a statement rather than just used in an expression.  The
+reason for this is that standard C doesn't let you "construct" a
+structure (but GCC does).  Granted, this sometimes isn't too
+convenient; for the case of integers, at least, you can use the
+function `make_int()', which constructs and _returns_ an integer Lisp
+object.  Note that the `XSETTYPE()' macros are also affected by
+`ERROR_CHECK_TYPECHECK' and make sure that the structure is of the
+right type in the case of record types, where the type is contained in
+the structure.
+
+   The C programmer is responsible for *guaranteeing* that a
+Lisp_Object is the correct type before using the `XTYPE' macros.  This
+is especially important in the case of lists.  Use `XCAR' and `XCDR' if
+a Lisp_Object is certainly a cons cell, else use `Fcar()' and `Fcdr()'.
+Trust other C code, but not Lisp code.  On the other hand, if XEmacs
+has an internal logic error, it's better to crash immediately, so
+sprinkle `assert()'s and "unreachable" `abort()'s liberally about the
+source code.  Where performance is an issue, use `type_checking_assert',
+`bufpos_checking_assert', and `gc_checking_assert', which do nothing
+unless the corresponding configure error checking flag was specified.
+
+
+File: internals.info,  Node: Rules When Writing New C Code,  Next: A Summary of the Various XEmacs Modules,  Prev: How Lisp Objects Are Represented in C,  Up: Top
+
+Rules When Writing New C Code
+*****************************
+
+   The XEmacs C Code is extremely complex and intricate, and there are
+many rules that are more or less consistently followed throughout the
+code.  Many of these rules are not obvious, so they are explained here.
+It is of the utmost importance that you follow them.  If you don't,
+you may get something that appears to work, but which will crash in odd
+situations, often in code far away from where the actual breakage is.
+
+* Menu:
+
+* General Coding Rules::
+* Writing Lisp Primitives::
+* Writing Good Comments::
+* Adding Global Lisp Variables::
+* Proper Use of Unsigned Types::
+* Coding for Mule::
+* Techniques for XEmacs Developers::
+
+
+File: internals.info,  Node: General Coding Rules,  Next: Writing Lisp Primitives,  Up: Rules When Writing New C Code
+
+General Coding Rules
+====================
+
+   The C code is actually written in a dialect of C called "Clean C",
+meaning that it can be compiled, mostly warning-free, with either a C or
+C++ compiler.  Coding in Clean C has several advantages over plain C.
+C++ compilers are more nit-picking, and a number of coding errors have
+been found by compiling with C++.  The ability to use both C and C++
+tools means that a greater variety of development tools are available to
+the developer.
+
+   Every module includes `<config.h>' (angle brackets so that
+`--srcdir' works correctly; `config.h' may or may not be in the same
+directory as the C sources) and `lisp.h'.  `config.h' must always be
+included before any other header files (including system header files)
+to ensure that certain tricks played by various `s/' and `m/' files
+work out correctly.
+
+   When including header files, always use angle brackets, not double
+quotes, except when the file to be included is always in the same
+directory as the including file.  If either file is a generated file,
+then that is not likely to be the case.  In order to understand why we
+have this rule, imagine what happens when you do a build in the source
+directory using `./configure' and another build in another directory
+using `../work/configure'.  There will be two different `config.h'
+files.  Which one will be used if you `#include "config.h"'?
+
+   Almost every module contains a `syms_of_*()' function and a
+`vars_of_*()' function.  The former declares any Lisp primitives you
+have defined and defines any symbols you will be using.  The latter
+declares any global Lisp variables you have added and initializes global
+C variables in the module.  *Important*: There are stringent
+requirements on exactly what can go into these functions.  See the
+comment in `emacs.c'.  The reason for this is to avoid obscure unwanted
+interactions during initialization.  If you don't follow these rules,
+you'll be sorry!  If you want to do anything that isn't allowed, create
+a `complex_vars_of_*()' function for it.  Doing this is tricky, though:
+you have to make sure your function is called at the right time so that
+all the initialization dependencies work out.
+
+   Declare each function of these kinds in `symsinit.h'.  Make sure
+it's called in the appropriate place in `emacs.c'.  You never need to
+include `symsinit.h' directly, because it is included by `lisp.h'.
+
+   *All global and static variables that are to be modifiable must be
+declared uninitialized.*  This means that you may not use the "declare
+with initializer" form for these variables, such as `int some_variable
+= 0;'.  The reason for this has to do with some kludges done during the
+dumping process: If possible, the initialized data segment is re-mapped
+so that it becomes part of the (unmodifiable) code segment in the
+dumped executable.  This allows this memory to be shared among multiple
+running XEmacs processes.  XEmacs is careful to place as much constant
+data as possible into initialized variables during the `temacs' phase.
+
+   *Please note:* This kludge only works on a few systems nowadays, and
+is rapidly becoming irrelevant because most modern operating systems
+provide "copy-on-write" semantics.  All data is initially shared
+between processes, and a private copy is automatically made (on a
+page-by-page basis) when a process first attempts to write to a page of
+memory.
+
+   Formerly, there was a requirement that static variables not be
+declared inside of functions.  This had to do with another hack along
+the same vein as what was just described: old USG systems put
+statically-declared variables in the initialized data space, so those
+header files had a `#define static' declaration. (That way, the
+data-segment remapping described above could still work.) This fails
+badly on static variables inside of functions, which suddenly become
+automatic variables; therefore, you weren't supposed to have any of
+them.  This awful kludge has been removed in XEmacs because
+
+  1. almost all of the systems that used this kludge ended up having to
+     disable the data-segment remapping anyway;
+
+  2. the only systems that didn't were extremely outdated ones;
+
+  3. this hack completely messed up inline functions.
+
+   The C source code makes heavy use of C preprocessor macros.  One
+popular macro style is:
+
+     #define FOO(var, value) do {            \
+       Lisp_Object FOO_value = (value);      \
+       ... /* compute using FOO_value */     \
+       (var) = bar;                          \
+     } while (0)
+
+   The `do {...} while (0)' is a standard trick to allow FOO to have
+statement semantics, so that it can safely be used within an `if'
+statement in C, for example.  Multiple evaluation is prevented by
+copying a supplied argument into a local variable, so that
+`FOO(var,fun(1))' only calls `fun' once.
+
+   Lisp lists are popular data structures in the C code as well as in
+Elisp.  There are two sets of macros that iterate over lists.
+`EXTERNAL_LIST_LOOP_N' should be used when the list has been supplied
+by the user, and cannot be trusted to be acyclic and `nil'-terminated.
+A `malformed-list' or `circular-list' error will be generated if the
+list being iterated over is not entirely kosher.  `LIST_LOOP_N', on the
+other hand, is faster and less safe, and can be used only on trusted
+lists.
+
+   Related macros are `GET_EXTERNAL_LIST_LENGTH' and `GET_LIST_LENGTH',
+which calculate the length of a list, and in the case of
+`GET_EXTERNAL_LIST_LENGTH', validating the properness of the list.  The
+macros `EXTERNAL_LIST_LOOP_DELETE_IF' and `LIST_LOOP_DELETE_IF' delete
+elements from a lisp list satisfying some predicate.
+
+
+File: internals.info,  Node: Writing Lisp Primitives,  Next: Writing Good Comments,  Prev: General Coding Rules,  Up: Rules When Writing New C Code
+
+Writing Lisp Primitives
+=======================
+
+   Lisp primitives are Lisp functions implemented in C.  The details of
+interfacing the C function so that Lisp can call it are handled by a few
+C macros.  The only way to really understand how to write new C code is
+to read the source, but we can explain some things here.
+
+   An example of a special form is the definition of `prog1', from
+`eval.c'.  (An ordinary function would have the same general
+appearance.)
+
+     DEFUN ("prog1", Fprog1, 1, UNEVALLED, 0, /*
+     Similar to `progn', but the value of the first form is returned.
+     \(prog1 FIRST BODY...): All the arguments are evaluated sequentially.
+     The value of FIRST is saved during evaluation of the remaining args,
+     whose values are discarded.
+     */
+            (args))
+     {
+       /* This function can GC */
+       REGISTER Lisp_Object val, form, tail;
+       struct gcpro gcpro1;
+     
+       val = Feval (XCAR (args));
+     
+       GCPRO1 (val);
+     
+       LIST_LOOP_3 (form, XCDR (args), tail)
+         Feval (form);
+     
+       UNGCPRO;
+       return val;
+     }
+
+   Let's start with a precise explanation of the arguments to the
+`DEFUN' macro.  Here is a template for them:
+
+     DEFUN (LNAME, FNAME, MIN_ARGS, MAX_ARGS, INTERACTIVE, /*
+     DOCSTRING
+     */
+        (ARGLIST))
+
+LNAME
+     This string is the name of the Lisp symbol to define as the
+     function name; in the example above, it is `"prog1"'.
+
+FNAME
+     This is the C function name for this function.  This is the name
+     that is used in C code for calling the function.  The name is, by
+     convention, `F' prepended to the Lisp name, with all dashes (`-')
+     in the Lisp name changed to underscores.  Thus, to call this
+     function from C code, call `Fprog1'.  Remember that the arguments
+     are of type `Lisp_Object'; various macros and functions for
+     creating values of type `Lisp_Object' are declared in the file
+     `lisp.h'.
+
+     Primitives whose names are special characters (e.g. `+' or `<')
+     are named by spelling out, in some fashion, the special character:
+     e.g. `Fplus()' or `Flss()'.  Primitives whose names begin with
+     normal alphanumeric characters but also contain special characters
+     are spelled out in some creative way, e.g. `let*' becomes
+     `FletX()'.
+
+     Each function also has an associated structure that holds the data
+     for the subr object that represents the function in Lisp.  This
+     structure conveys the Lisp symbol name to the initialization
+     routine that will create the symbol and store the subr object as
+     its definition.  The C variable name of this structure is always
+     `S' prepended to the FNAME.  You hardly ever need to be aware of
+     the existence of this structure, since `DEFUN' plus `DEFSUBR'
+     takes care of all the details.
+
+MIN_ARGS
+     This is the minimum number of arguments that the function
+     requires.  The function `prog1' allows a minimum of one argument.
+
+MAX_ARGS
+     This is the maximum number of arguments that the function accepts,
+     if there is a fixed maximum.  Alternatively, it can be `UNEVALLED',
+     indicating a special form that receives unevaluated arguments, or
+     `MANY', indicating an unlimited number of evaluated arguments (the
+     C equivalent of `&rest').  Both `UNEVALLED' and `MANY' are macros.
+     If MAX_ARGS is a number, it may not be less than MIN_ARGS and it
+     may not be greater than 8. (If you need to add a function with
+     more than 8 arguments, use the `MANY' form.  Resist the urge to
+     edit the definition of `DEFUN' in `lisp.h'.  If you do it anyways,
+     make sure to also add another clause to the switch statement in
+     `primitive_funcall().')
+
+INTERACTIVE
+     This is an interactive specification, a string such as might be
+     used as the argument of `interactive' in a Lisp function.  In the
+     case of `prog1', it is 0 (a null pointer), indicating that `prog1'
+     cannot be called interactively.  A value of `""' indicates a
+     function that should receive no arguments when called
+     interactively.
+
+DOCSTRING
+     This is the documentation string.  It is written just like a
+     documentation string for a function defined in Lisp; in
+     particular, the first line should be a single sentence.  Note how
+     the documentation string is enclosed in a comment, none of the
+     documentation is placed on the same lines as the comment-start and
+     comment-end characters, and the comment-start characters are on
+     the same line as the interactive specification.  `make-docfile',
+     which scans the C files for documentation strings, is very
+     particular about what it looks for, and will not properly extract
+     the doc string if it's not in this exact format.
+
+     In order to make both `etags' and `make-docfile' happy, make sure
+     that the `DEFUN' line contains the LNAME and FNAME, and that the
+     comment-start characters for the doc string are on the same line
+     as the interactive specification, and put a newline directly after
+     them (and before the comment-end characters).
+
+ARGLIST
+     This is the comma-separated list of arguments to the C function.
+     For a function with a fixed maximum number of arguments, provide a
+     C argument for each Lisp argument.  In this case, unlike regular C
+     functions, the types of the arguments are not declared; they are
+     simply always of type `Lisp_Object'.
+
+     The names of the C arguments will be used as the names of the
+     arguments to the Lisp primitive as displayed in its documentation,
+     modulo the same concerns described above for `F...' names (in
+     particular, underscores in the C arguments become dashes in the
+     Lisp arguments).
+
+     There is one additional kludge: A trailing `_' on the C argument is
+     discarded when forming the Lisp argument.  This allows C language
+     reserved words (like `default') or global symbols (like `dirname')
+     to be used as argument names without compiler warnings or errors.
+
+     A Lisp function with MAX_ARGS = `UNEVALLED' is a "special form";
+     its arguments are not evaluated.  Instead it receives one argument
+     of type `Lisp_Object', a (Lisp) list of the unevaluated arguments,
+     conventionally named `(args)'.
+
+     When a Lisp function has no upper limit on the number of arguments,
+     specify MAX_ARGS = `MANY'.  In this case its implementation in C
+     actually receives exactly two arguments: the number of Lisp
+     arguments (an `int') and the address of a block containing their
+     values (a `Lisp_Object *').  In this case only are the C types
+     specified in the ARGLIST: `(int nargs, Lisp_Object *args)'.
+
+   Within the function `Fprog1' itself, note the use of the macros
+`GCPRO1' and `UNGCPRO'.  `GCPRO1' is used to "protect" a variable from
+garbage collection--to inform the garbage collector that it must look
+in that variable and regard the object pointed at by its contents as an
+accessible object.  This is necessary whenever you call `Feval' or
+anything that can directly or indirectly call `Feval' (this includes
+the `QUIT' macro!).  At such a time, any Lisp object that you intend to
+refer to again must be protected somehow.  `UNGCPRO' cancels the
+protection of the variables that are protected in the current function.
+It is necessary to do this explicitly.
+
+   The macro `GCPRO1' protects just one local variable.  If you want to
+protect two, use `GCPRO2' instead; repeating `GCPRO1' will not work.
+Macros `GCPRO3' and `GCPRO4' also exist.
+
+   These macros implicitly use local variables such as `gcpro1'; you
+must declare these explicitly, with type `struct gcpro'.  Thus, if you
+use `GCPRO2', you must declare `gcpro1' and `gcpro2'.
+
+   Note also that the general rule is "caller-protects"; i.e. you are
+only responsible for protecting those Lisp objects that you create.  Any
+objects passed to you as arguments should have been protected by whoever
+created them, so you don't in general have to protect them.
+
+   In particular, the arguments to any Lisp primitive are always
+automatically `GCPRO'ed, when called "normally" from Lisp code or
+bytecode.  So only a few Lisp primitives that are called frequently from
+C code, such as `Fprogn' protect their arguments as a service to their
+caller.  You don't need to protect your arguments when writing a new
+`DEFUN'.
+
+   `GCPRO'ing is perhaps the trickiest and most error-prone part of
+XEmacs coding.  It is *extremely* important that you get this right and
+use a great deal of discipline when writing this code.  *Note
+`GCPRO'ing: GCPROing, for full details on how to do this.
+
+   What `DEFUN' actually does is declare a global structure of type
+`Lisp_Subr' whose name begins with capital `SF' and which contains
+information about the primitive (e.g. a pointer to the function, its
+minimum and maximum allowed arguments, a string describing its Lisp
+name); `DEFUN' then begins a normal C function declaration using the
+`F...' name.  The Lisp subr object that is the function definition of a
+primitive (i.e. the object in the function slot of the symbol that
+names the primitive) actually points to this `SF' structure; when
+`Feval' encounters a subr, it looks in the structure to find out how to
+call the C function.
+
+   Defining the C function is not enough to make a Lisp primitive
+available; you must also create the Lisp symbol for the primitive (the
+symbol is "interned"; *note Obarrays::) and store a suitable subr
+object in its function cell. (If you don't do this, the primitive won't
+be seen by Lisp code.) The code looks like this:
+
+     DEFSUBR (FNAME);
+
+Here FNAME is the same name you used as the second argument to `DEFUN'.
+
+   This call to `DEFSUBR' should go in the `syms_of_*()' function at
+the end of the module.  If no such function exists, create it and make
+sure to also declare it in `symsinit.h' and call it from the
+appropriate spot in `main()'.  *Note General Coding Rules::.
+
+   Note that C code cannot call functions by name unless they are
+defined in C.  The way to call a function written in Lisp from C is to
+use `Ffuncall', which embodies the Lisp function `funcall'.  Since the
+Lisp function `funcall' accepts an unlimited number of arguments, in C
+it takes two: the number of Lisp-level arguments, and a one-dimensional
+array containing their values.  The first Lisp-level argument is the
+Lisp function to call, and the rest are the arguments to pass to it.
+Since `Ffuncall' can call the evaluator, you must protect pointers from
+garbage collection around the call to `Ffuncall'. (However, `Ffuncall'
+explicitly protects all of its parameters, so you don't have to protect
+any pointers passed as parameters to it.)
+
+   The C functions `call0', `call1', `call2', and so on, provide handy
+ways to call a Lisp function conveniently with a fixed number of
+arguments.  They work by calling `Ffuncall'.
+
+   `eval.c' is a very good file to look through for examples; `lisp.h'
+contains the definitions for important macros and functions.
+
+
+File: internals.info,  Node: Writing Good Comments,  Next: Adding Global Lisp Variables,  Prev: Writing Lisp Primitives,  Up: Rules When Writing New C Code
+
+Writing Good Comments
+=====================
+
+   Comments are a lifeline for programmers trying to understand tricky
+code.  In general, the less obvious it is what you are doing, the more
+you need a comment, and the more detailed it needs to be.  You should
+always be on guard when you're writing code for stuff that's tricky, and
+should constantly be putting yourself in someone else's shoes and asking
+if that person could figure out without much difficulty what's going
+on. (Assume they are a competent programmer who understands the
+essentials of how the XEmacs code is structured but doesn't know much
+about the module you're working on or any algorithms you're using.) If
+you're not sure whether they would be able to, add a comment.  Always
+err on the side of more comments, rather than less.
+
+   Generally, when making comments, there is no need to attribute them
+with your name or initials.  This especially goes for small,
+easy-to-understand, non-opinionated ones.  Also, comments indicating
+where, when, and by whom a file was changed are _strongly_ discouraged,
+and in general will be removed as they are discovered.  This is exactly
+what `ChangeLogs' are there for.  However, it can occasionally be
+useful to mark exactly where (but not when or by whom) changes are
+made, particularly when making small changes to a file imported from
+elsewhere.  These marks help when later on a newer version of the file
+is imported and the changes need to be merged. (If everything were
+always kept in CVS, there would be no need for this.  But in practice,
+this often doesn't happen, or the CVS repository is later on lost or
+unavailable to the person doing the update.)
+
+   When putting in an explicit opinion in a comment, you should
+_always_ attribute it with your name, and optionally the date.  This
+also goes for long, complex comments explaining in detail the workings
+of something - by putting your name there, you make it possible for
+someone who has questions about how that thing works to determine who
+wrote the comment so they can write to them.  Preferably, use your
+actual name and not your initials, unless your initials are generally
+recognized (e.g. `jwz').  You can use only your first name if it's
+obvious who you are; otherwise, give first and last name.  If you're
+not a regular contributor, you might consider putting your email
+address in - it may be in the ChangeLog, but after awhile ChangeLogs
+have a tendency of disappearing or getting muddled. (E.g. your comment
+may get copied somewhere else or even into another program, and
+tracking down the proper ChangeLog may be very difficult.)
+
+   If you come across an opinion that is not or no longer valid, or you
+come across any comment that no longer applies but you want to keep it
+around, enclose it in `[[ ' and ` ]]' marks and add a comment
+afterwards explaining why the preceding comment is no longer valid.  Put
+your name on this comment, as explained above.
+
+   Just as comments are a lifeline to programmers, incorrect comments
+are death.  If you come across an incorrect comment, *immediately*
+correct it or flag it as incorrect, as described in the previous
+paragraph.  Whenever you work on a section of code, _always_ make sure
+to update any comments to be correct - or, at the very least, flag them
+as incorrect.
+
+   To indicate a "todo" or other problem, use four pound signs - i.e.
+`####'.
+
+
+File: internals.info,  Node: Adding Global Lisp Variables,  Next: Proper Use of Unsigned Types,  Prev: Writing Good Comments,  Up: Rules When Writing New C Code
+
+Adding Global Lisp Variables
+============================
+
+   Global variables whose names begin with `Q' are constants whose
+value is a symbol of a particular name.  The name of the variable should
+be derived from the name of the symbol using the same rules as for Lisp
+primitives.  These variables are initialized using a call to
+`defsymbol()' in the `syms_of_*()' function. (This call interns a
+symbol, sets the C variable to the resulting Lisp object, and calls
+`staticpro()' on the C variable to tell the garbage-collection
+mechanism about this variable.  What `staticpro()' does is add a
+pointer to the variable to a large global array; when
+garbage-collection happens, all pointers listed in the array are used
+as starting points for marking Lisp objects.  This is important because
+it's quite possible that the only current reference to the object is
+the C variable.  In the case of symbols, the `staticpro()' doesn't
+matter all that much because the symbol is contained in `obarray',
+which is itself `staticpro()'ed.  However, it's possible that a naughty
+user could do something like uninterning the symbol out of `obarray' or
+even setting `obarray' to a different value [although this is likely to
+make XEmacs crash!].)
+
+   *Please note:* It is potentially deadly if you declare a `Q...'
+variable in two different modules.  The two calls to `defsymbol()' are
+no problem, but some linkers will complain about multiply-defined
+symbols.  The most insidious aspect of this is that often the link will
+succeed anyway, but then the resulting executable will sometimes crash
+in obscure ways during certain operations!  To avoid this problem,
+declare any symbols with common names (such as `text') that are not
+obviously associated with this particular module in the module
+`general.c'.
+
+   Global variables whose names begin with `V' are variables that
+contain Lisp objects.  The convention here is that all global variables
+of type `Lisp_Object' begin with `V', and all others don't (including
+integer and boolean variables that have Lisp equivalents). Most of the
+time, these variables have equivalents in Lisp, but some don't.  Those
+that do are declared this way by a call to `DEFVAR_LISP()' in the
+`vars_of_*()' initializer for the module.  What this does is create a
+special "symbol-value-forward" Lisp object that contains a pointer to
+the C variable, intern a symbol whose name is as specified in the call
+to `DEFVAR_LISP()', and set its value to the symbol-value-forward Lisp
+object; it also calls `staticpro()' on the C variable to tell the
+garbage-collection mechanism about the variable.  When `eval' (or
+actually `symbol-value') encounters this special object in the process
+of retrieving a variable's value, it follows the indirection to the C
+variable and gets its value.  `setq' does similar things so that the C
+variable gets changed.
+
+   Whether or not you `DEFVAR_LISP()' a variable, you need to
+initialize it in the `vars_of_*()' function; otherwise it will end up
+as all zeroes, which is the integer 0 (_not_ `nil'), and this is
+probably not what you want.  Also, if the variable is not
+`DEFVAR_LISP()'ed, *you must call* `staticpro()' on the C variable in
+the `vars_of_*()' function.  Otherwise, the garbage-collection
+mechanism won't know that the object in this variable is in use, and
+will happily collect it and reuse its storage for another Lisp object,
+and you will be the one who's unhappy when you can't figure out how
+your variable got overwritten.
+
+
+File: internals.info,  Node: Proper Use of Unsigned Types,  Next: Coding for Mule,  Prev: Adding Global Lisp Variables,  Up: Rules When Writing New C Code
+
+Proper Use of Unsigned Types
+============================
+
+   Avoid using `unsigned int' and `unsigned long' whenever possible.
+Unsigned types are viral - any arithmetic or comparisons involving
+mixed signed and unsigned types are automatically converted to
+unsigned, which is almost certainly not what you want.  Many subtle and
+hard-to-find bugs are created by careless use of unsigned types.  In
+general, you should almost _never_ use an unsigned type to hold a
+regular quantity of any sort.  The only exceptions are
+
+  1. When there's a reasonable possibility you will actually need all
+     32 or 64 bits to store the quantity.
+
+  2. When calling existing API's that require unsigned types.  In this
+     case, you should still do all manipulation using signed types, and
+     do the conversion at the very threshold of the API call.
+
+  3. In existing code that you don't want to modify because you don't
+     maintain it.
+
+  4. In bit-field structures.
+
+   Other reasonable uses of `unsigned int' and `unsigned long' are
+representing non-quantities - e.g. bit-oriented flags and such.
+
+
+File: internals.info,  Node: Coding for Mule,  Next: Techniques for XEmacs Developers,  Prev: Proper Use of Unsigned Types,  Up: Rules When Writing New C Code
+
+Coding for Mule
+===============
+
+   Although Mule support is not compiled by default in XEmacs, many
+people are using it, and we consider it crucial that new code works
+correctly with multibyte characters.  This is not hard; it is only a
+matter of following several simple user-interface guidelines.  Even if
+you never compile with Mule, with a little practice you will find it
+quite easy to code Mule-correctly.
+
+   Note that these guidelines are not necessarily tied to the current
+Mule implementation; they are also a good idea to follow on the grounds
+of code generalization for future I18N work.
+
+* Menu:
+
+* Character-Related Data Types::
+* Working With Character and Byte Positions::
+* Conversion to and from External Data::
+* General Guidelines for Writing Mule-Aware Code::
+* An Example of Mule-Aware Code::
+
+
+File: internals.info,  Node: Character-Related Data Types,  Next: Working With Character and Byte Positions,  Up: Coding for Mule
+
+Character-Related Data Types
+----------------------------
+
+   First, let's review the basic character-related datatypes used by
+XEmacs.  Note that the separate `typedef's are not mandatory in the
+current implementation (all of them boil down to `unsigned char' or
+`int'), but they improve clarity of code a great deal, because one
+glance at the declaration can tell the intended use of the variable.
+
+`Emchar'
+     An `Emchar' holds a single Emacs character.
+
+     Obviously, the equality between characters and bytes is lost in
+     the Mule world.  Characters can be represented by one or more
+     bytes in the buffer, and `Emchar' is the C type large enough to
+     hold any character.
+
+     Without Mule support, an `Emchar' is equivalent to an `unsigned
+     char'.
+
+`Bufbyte'
+     The data representing the text in a buffer or string is logically
+     a set of `Bufbyte's.
+
+     XEmacs does not work with the same character formats all the time;
+     when reading characters from the outside, it decodes them to an
+     internal format, and likewise encodes them when writing.
+     `Bufbyte' (in fact `unsigned char') is the basic unit of XEmacs
+     internal buffers and strings format.  A `Bufbyte *' is the type
+     that points at text encoded in the variable-width internal
+     encoding.
+
+     One character can correspond to one or more `Bufbyte's.  In the
+     current Mule implementation, an ASCII character is represented by
+     the same `Bufbyte', and other characters are represented by a
+     sequence of two or more `Bufbyte's.
+
+     Without Mule support, there are exactly 256 characters, implicitly
+     Latin-1, and each character is represented using one `Bufbyte', and
+     there is a one-to-one correspondence between `Bufbyte's and
+     `Emchar's.
+
+`Bufpos'
+`Charcount'
+     A `Bufpos' represents a character position in a buffer or string.
+     A `Charcount' represents a number (count) of characters.
+     Logically, subtracting two `Bufpos' values yields a `Charcount'
+     value.  Although all of these are `typedef'ed to `EMACS_INT', we
+     use them in preference to `EMACS_INT' to make it clear what sort
+     of position is being used.
+
+     `Bufpos' and `Charcount' values are the only ones that are ever
+     visible to Lisp.
+
+`Bytind'
+`Bytecount'
+     A `Bytind' represents a byte position in a buffer or string.  A
+     `Bytecount' represents the distance between two positions, in
+     bytes.  The relationship between `Bytind' and `Bytecount' is the
+     same as the relationship between `Bufpos' and `Charcount'.
+
+`Extbyte'
+`Extcount'
+     When dealing with the outside world, XEmacs works with `Extbyte's,
+     which are equivalent to `unsigned char'.  Obviously, an `Extcount'
+     is the distance between two `Extbyte's.  Extbytes and Extcounts
+     are not all that frequent in XEmacs code.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-3'
Index: ././info/internals.info-3
--- ././info/internals.info-3	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-3	Thu May 17 23:26:54 2001
@@ -0,0 +1,1213 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+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 to
+     represent an Emacs character in the variable width internal
+     encoding.  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);
+
+
+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
+------------------------------------
+
+   When an external function, such as a C library function, returns a
+`char' pointer, you should almost never treat it as `Bufbyte'.  This is
+because these returned strings may contain 8bit characters which can be
+misinterpreted by XEmacs, and cause a crash.  Likewise, when exporting
+a piece of internal text to the outside world, you should always
+convert it to an appropriate external encoding, lest the internal stuff
+(such as the infamous \201 characters) leak out.
+
+   The interface to conversion between the internal and external
+representations of text are the numerous conversion macros defined in
+`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 `~'.
+
+`Qfile_name'
+     Format used for filenames.  This is user-definable via either the
+     `file-name-coding-system' or `pathname-coding-system' (now
+     obsolete) variables.
+
+`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
+
+   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.
+
+
+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
+
+General Guidelines for Writing Mule-Aware Code
+----------------------------------------------
+
+   This section contains some general guidance on how to write
+Mule-aware code, as well as some pitfalls you should avoid.
+
+_Never use `char' and `char *'._
+     In XEmacs, the use of `char' and `char *' is almost always a
+     mistake.  If you want to manipulate an Emacs character from "C",
+     use `Emchar'.  If you want to examine a specific octet in the
+     internal format, use `Bufbyte'.  If you want a Lisp-visible
+     character, use a `Lisp_Object' and `make_char'.  If you want a
+     pointer to move through the internal text, use `Bufbyte *'.  Also
+     note that you almost certainly do not need `Emchar *'.
+
+_Be careful not to confuse `Charcount', `Bytecount', and `Bufpos'._
+     The whole point of using different types is to avoid confusion
+     about the use of certain variables.  Lest this effect be
+     nullified, you need to be careful about using the right types.
+
+_Always convert external data_
+     It is extremely important to always convert external data, because
+     XEmacs can crash if unexpected 8bit sequences are copied to its
+     internal buffers literally.
+
+     This means that when a system function, such as `readdir', returns
+     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
+     data they receive.  This increases efficiency because that way
+     external data needs to be decoded only once, when it is read.
+     After that, it is passed around in internal format.
+
+
+File: internals.info,  Node: An Example of Mule-Aware Code,  Prev: General Guidelines for Writing Mule-Aware Code,  Up: Coding for Mule
+
+An Example of Mule-Aware Code
+-----------------------------
+
+   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':
+
+     DEFUN ("string", Fstring, 0, MANY, 0, /*
+     Concatenate all the argument characters and make the result a string.
+     */
+            (int nargs, Lisp_Object *args))
+     {
+       Bufbyte *storage = alloca_array (Bufbyte, nargs * MAX_EMCHAR_LEN);
+       Bufbyte *p = storage;
+     
+       for (; nargs; nargs--, args++)
+         {
+           Lisp_Object lisp_char = *args;
+           CHECK_CHAR_COERCE_INT (lisp_char);
+           p += set_charptr_emchar (p, XCHAR (lisp_char));
+         }
+       return make_string (storage, p - storage);
+     }
+
+   Now we can analyze the source line by line.
+
+   Obviously, string will be as long as there are arguments to the
+function.  This is why we allocate `MAX_EMCHAR_LEN' * NARGS bytes on
+the stack, i.e. the worst-case number of bytes for NARGS `Emchar's to
+fit in the string.
+
+   Then, the loop checks that each element is a character, converting
+integers in the process.  Like many other functions in XEmacs, this
+function silently accepts integers where characters are expected, for
+historical and compatibility reasons.  Unless you know what you are
+doing, `CHECK_CHAR' will also suffice.  `XCHAR (lisp_char)' extracts
+the `Emchar' from the `Lisp_Object', and `set_charptr_emchar' stores it
+to storage, increasing `p' in the process.
+
+   Other instructive examples of correct coding under Mule can be found
+all over the XEmacs code.  For starters, I recommend
+`Fnormalize_menu_item_name' in `menubar.c'.  After you have understood
+this section of the manual and studied the examples, you can proceed
+writing new Mule-aware code.
+
+
+File: internals.info,  Node: Techniques for XEmacs Developers,  Prev: Coding for Mule,  Up: Rules When Writing New C Code
+
+Techniques for XEmacs Developers
+================================
+
+   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 (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
+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
+task.
+
+   Also, if you're still willing to do some runs make sure you configure
+with the `--quantify' flag.  That will keep Quantify from starting to
+record data until after the loadup is completed and will shut off
+recording right before it shuts down (which generates enough bogus data
+to throw most results off).  It also enables three additional elisp
+commands: `quantify-start-recording-data',
+`quantify-stop-recording-data' and `quantify-clear-data'.
+
+   If you want to make XEmacs faster, target your favorite slow
+benchmark, run a profiler like Quantify, `gprof', or `tcov', and figure
+out where the cycles are going.  Specific projects:
+
+   * Make the garbage collector faster.  Figure out how to write an
+     incremental garbage collector.
+
+   * Write a compiler that takes bytecode and spits out C code.
+     Unfortunately, you will then need a C compiler and a more fully
+     developed module system.
+
+   * Speed up redisplay.
+
+   * Speed up syntax highlighting.  Maybe moving some of the syntax
+     highlighting capabilities into C would make a difference.
+
+   * Implement tail recursion in Emacs Lisp (hard!).
+
+   Unfortunately, Emacs Lisp is slow, and is going to stay slow.
+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.  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 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:
+
+   * All `.c' files should `#include <config.h>' first.  Almost all
+     `.c' files should `#include "lisp.h"' second.
+
+   * Generated header files should be included using the `#include
+     <...>' syntax, not the `#include "..."' syntax.  The generated
+     headers are:
+
+     `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
+     to-be-included generated file is in a potentially different
+     directory _at compile time_.  The non-obvious C rule is that
+     `#include "..."' means to search for the included file in the same
+     directory as the including file, _not_ in the current directory.
+
+   * Header files should _not_ include `<config.h>' and `"lisp.h"'.  It
+     is the responsibility of the `.c' files that use it to do so.
+
+
+   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'
+
+  5. add calls to `syms_of_FOO', etc. to `emacs.c'
+
+  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'
+
+
+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
+
+A Summary of the Various XEmacs Modules
+***************************************
+
+   This is accurate as of XEmacs 20.0.
+
+* Menu:
+
+* Low-Level Modules::
+* Basic Lisp Modules::
+* Modules for Standard Editing Operations::
+* Editor-Level Control Flow Modules::
+* Modules for the Basic Displayable Lisp Objects::
+* Modules for other Display-Related Lisp Objects::
+* Modules for the Redisplay Mechanism::
+* Modules for Interfacing with the File System::
+* Modules for Other Aspects of the Lisp Interpreter and Object System::
+* Modules for Interfacing with the Operating System::
+* Modules for Interfacing with X Windows::
+* Modules for Internationalization::
+
+
+File: internals.info,  Node: Low-Level Modules,  Next: Basic Lisp Modules,  Up: A Summary of the Various XEmacs Modules
+
+Low-Level Modules
+=================
+
+     config.h
+
+   This is automatically generated from `config.h.in' based on the
+results of configure tests and user-selected optional features and
+contains preprocessor definitions specifying the nature of the
+environment in which XEmacs is being compiled.
+
+     paths.h
+
+   This is automatically generated from `paths.h.in' based on supplied
+configure values, and allows for non-standard installed configurations
+of the XEmacs directories.  It's currently broken, though.
+
+     emacs.c
+     signal.c
+
+   `emacs.c' contains `main()' and other code that performs the most
+basic environment initializations and handles shutting down the XEmacs
+process (this includes `kill-emacs', the normal way that XEmacs is
+exited; `dump-emacs', which is used during the build process to write
+out the XEmacs executable; `run-emacs-from-temacs', which can be used
+to start XEmacs directly when temacs has finished loading all the Lisp
+code; and emergency code to handle crashes [XEmacs tries to auto-save
+all files before it crashes]).
+
+   Low-level code that directly interacts with the Unix signal
+mechanism, however, is in `signal.c'.  Note that this code does not
+handle system dependencies in interfacing to signals; that is handled
+using the `syssignal.h' header file, described in section J below.
+
+     unexaix.c
+     unexalpha.c
+     unexapollo.c
+     unexconvex.c
+     unexec.c
+     unexelf.c
+     unexelfsgi.c
+     unexencap.c
+     unexenix.c
+     unexfreebsd.c
+     unexfx2800.c
+     unexhp9k3.c
+     unexhp9k800.c
+     unexmips.c
+     unexnext.c
+     unexsol2.c
+     unexsunos4.c
+
+   These modules contain code dumping out the XEmacs executable on
+various different systems. (This process is highly machine-specific and
+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'.
+
+     ecrt0.c
+     lastfile.c
+     pre-crt0.c
+
+   These modules are used in conjunction with the dump mechanism.  On
+some systems, an alternative version of the C startup code (the actual
+code that receives control from the operating system when the process is
+started, and which calls `main()') is required so that the dumping
+process works properly; `crt0.c' provides this.
+
+   `pre-crt0.c' and `lastfile.c' should be the very first and very last
+file linked, respectively. (Actually, this is not really true.
+`lastfile.c' should be after all Emacs modules whose initialized data
+should be made constant, and before all other Emacs files and all
+libraries.  In particular, the allocation modules `gmalloc.c',
+`alloca.c', etc. are normally placed past `lastfile.c', and all of the
+files that implement Xt widget classes _must_ be placed after
+`lastfile.c' because they contain various structures that must be
+statically initialized and into which Xt writes at various times.)
+`pre-crt0.c' and `lastfile.c' contain exported symbols that are used to
+determine the start and end of XEmacs' initialized data space when
+dumping.
+
+     alloca.c
+     free-hook.c
+     getpagesize.h
+     gmalloc.c
+     malloc.c
+     mem-limits.h
+     ralloc.c
+     vm-limit.c
+
+   These handle basic C allocation of memory.  `alloca.c' is an
+emulation of the stack allocation function `alloca()' on machines that
+lack this. (XEmacs makes extensive use of `alloca()' in its code.)
+
+   `gmalloc.c' and `malloc.c' are two implementations of the standard C
+functions `malloc()', `realloc()' and `free()'.  They are often used in
+place of the standard system-provided `malloc()' because they usually
+provide a much faster implementation, at the expense of additional
+memory use.  `gmalloc.c' is a newer implementation that is much more
+memory-efficient for large allocations than `malloc.c', and should
+always be preferred if it works. (At one point, `gmalloc.c' didn't work
+on some systems where `malloc.c' worked; but this should be fixed now.)
+
+   `ralloc.c' is the "relocating allocator".  It provides functions
+similar to `malloc()', `realloc()' and `free()' that allocate memory
+that can be dynamically relocated in memory.  The advantage of this is
+that allocated memory can be shuffled around to place all the free
+memory at the end of the heap, and the heap can then be shrunk,
+releasing the memory back to the operating system.  The use of this can
+be controlled with the configure option `--rel-alloc'; if enabled,
+memory allocated for buffers will be relocatable, so that if a very
+large file is visited and the buffer is later killed, the memory can be
+released to the operating system.  (The disadvantage of this mechanism
+is that it can be very slow.  On systems with the `mmap()' system call,
+the XEmacs version of `ralloc.c' uses this to move memory around
+without actually having to block-copy it, which can speed things up;
+but it can still cause noticeable performance degradation.)
+
+   `free-hook.c' contains some debugging functions for checking for
+invalid arguments to `free()'.
+
+   `vm-limit.c' contains some functions that warn the user when memory
+is getting low.  These are callback functions that are called by
+`gmalloc.c' and `malloc.c' at appropriate times.
+
+   `getpagesize.h' provides a uniform interface for retrieving the size
+of a page in virtual memory.  `mem-limits.h' provides a uniform
+interface for retrieving the total amount of available virtual memory.
+Both are similar in spirit to the `sys*.h' files described in section
+J, below.
+
+     blocktype.c
+     blocktype.h
+     dynarr.c
+
+   These implement a couple of basic C data types to facilitate memory
+allocation.  The `Blocktype' type efficiently manages the allocation of
+fixed-size blocks by minimizing the number of times that `malloc()' and
+`free()' are called.  It allocates memory in large chunks, subdivides
+the chunks into blocks of the proper size, and returns the blocks as
+requested.  When blocks are freed, they are placed onto a linked list,
+so they can be efficiently reused.  This data type is not much used in
+XEmacs currently, because it's a fairly new addition.
+
+   The `Dynarr' type implements a "dynamic array", which is similar to
+a standard C array but has no fixed limit on the number of elements it
+can contain.  Dynamic arrays can hold elements of any type, and when
+you add a new element, the array automatically resizes itself if it
+isn't big enough.  Dynarrs are extensively used in the redisplay
+mechanism.
+
+     inline.c
+
+   This module is used in connection with inline functions (available in
+some compilers).  Often, inline functions need to have a corresponding
+non-inline function that does the same thing.  This module is where they
+reside.  It contains no actual code, but defines some special flags that
+cause inline functions defined in header files to be rendered as actual
+functions.  It then includes all header files that contain any inline
+function definitions, so that each one gets a real function equivalent.
+
+     debug.c
+     debug.h
+
+   These functions provide a system for doing internal consistency
+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.
+
+     universe.h
+
+   This is not currently used.
+
+
+File: internals.info,  Node: Basic Lisp Modules,  Next: Modules for Standard Editing Operations,  Prev: Low-Level Modules,  Up: A Summary of the Various XEmacs Modules
+
+Basic Lisp Modules
+==================
+
+     lisp-disunion.h
+     lisp-union.h
+     lisp.h
+     lrecord.h
+     symsinit.h
+
+   These are the basic header files for all XEmacs modules.  Each module
+includes `lisp.h', which brings the other header files in.  `lisp.h'
+contains the definitions of the structures and extractor and
+constructor macros for the basic Lisp objects and various other basic
+definitions for the Lisp environment, as well as some general-purpose
+definitions (e.g. `min()' and `max()').  `lisp.h' includes either
+`lisp-disunion.h' or `lisp-union.h', depending on whether
+`USE_UNION_TYPE' is defined.  These files define the typedef of the
+Lisp object itself (as described above) and the low-level macros that
+hide the actual implementation of the Lisp object.  All extractor and
+constructor macros for particular types of Lisp objects are defined in
+terms of these low-level macros.
+
+   As a general rule, all typedefs should go into the typedefs section
+of `lisp.h' rather than into a module-specific header file even if the
+structure is defined elsewhere.  This allows function prototypes that
+use the typedef to be placed into other header files.  Forward structure
+declarations (i.e. a simple declaration like `struct foo;' where the
+structure itself is defined elsewhere) should be placed into the
+typedefs section as necessary.
+
+   `lrecord.h' contains the basic structures and macros that implement
+all record-type Lisp objects--i.e. all objects whose type is a field in
+their C structure, which includes all objects except the few most basic
+ones.
+
+   `lisp.h' contains prototypes for most of the exported functions in
+the various modules.  Lisp primitives defined using `DEFUN' that need
+to be called by C code should be declared using `EXFUN'.  Other
+function prototypes should be placed either into the appropriate
+section of `lisp.h', or into a module-specific header file, depending
+on how general-purpose the function is and whether it has
+special-purpose argument types requiring definitions not in `lisp.h'.)
+All initialization functions are prototyped in `symsinit.h'.
+
+     alloc.c
+
+   The large module `alloc.c' implements all of the basic allocation and
+garbage collection for Lisp objects.  The most commonly used Lisp
+objects are allocated in chunks, similar to the Blocktype data type
+described above; others are allocated in individually `malloc()'ed
+blocks.  This module provides the foundation on which all other aspects
+of the Lisp environment sit, and is the first module initialized at
+startup.
+
+   Note that `alloc.c' provides a series of generic functions that are
+not dependent on any particular object type, and interfaces to
+particular types of objects using a standardized interface of
+type-specific methods.  This scheme is a fundamental principle of
+object-oriented programming and is heavily used throughout XEmacs.  The
+great advantage of this is that it allows for a clean separation of
+functionality into different modules--new classes of Lisp objects, new
+event interfaces, new device types, new stream interfaces, etc. can be
+added transparently without affecting code anywhere else in XEmacs.
+Because the different subsystems are divided into general and specific
+code, adding a new subtype within a subsystem will in general not
+require changes to the generic subsystem code or affect any of the other
+subtypes in the subsystem; this provides a great deal of robustness to
+the XEmacs code.
+
+     eval.c
+     backtrace.h
+
+   This module contains all of the functions to handle the flow of
+control.  This includes the mechanisms of defining functions, calling
+functions, traversing stack frames, and binding variables; the control
+primitives and other special forms such as `while', `if', `eval',
+`let', `and', `or', `progn', etc.; handling of non-local exits,
+unwind-protects, and exception handlers; entering the debugger; methods
+for the subr Lisp object type; etc.  It does _not_ include the `read'
+function, the `print' function, or the handling of symbols and obarrays.
+
+   `backtrace.h' contains some structures related to stack frames and
+the flow of control.
+
+     lread.c
+
+   This module implements the Lisp reader and the `read' function,
+which converts text into Lisp objects, according to the read syntax of
+the objects, as described above.  This is similar to the parser that is
+a part of all compilers.
+
+     print.c
+
+   This module implements the Lisp print mechanism and the `print'
+function and related functions.  This is the inverse of the Lisp reader
+- it converts Lisp objects to a printed, textual representation.
+(Hopefully something that can be read back in using `read' to get an
+equivalent object.)
+
+     general.c
+     symbols.c
+     symeval.h
+
+   `symbols.c' implements the handling of symbols, obarrays, and
+retrieving the values of symbols.  Much of the code is devoted to
+handling the special "symbol-value-magic" objects that define special
+types of variables--this includes buffer-local variables, variable
+aliases, variables that forward into C variables, etc.  This module is
+initialized extremely early (right after `alloc.c'), because it is here
+that the basic symbols `t' and `nil' are created, and those symbols are
+used everywhere throughout XEmacs.
+
+   `symeval.h' contains the definitions of symbol structures and the
+`DEFVAR_LISP()' and related macros for declaring variables.
+
+     data.c
+     floatfns.c
+     fns.c
+
+   These modules implement the methods and standard Lisp primitives for
+all the basic Lisp object types other than symbols (which are described
+above).  `data.c' contains all the predicates (primitives that return
+whether an object is of a particular type); the integer arithmetic
+functions; and the basic accessor and mutator primitives for the various
+object types.  `fns.c' contains all the standard predicates for working
+with sequences (where, abstractly speaking, a sequence is an ordered set
+of objects, and can be represented by a list, string, vector, or
+bit-vector); it also contains `equal', perhaps on the grounds that bulk
+of the operation of `equal' is comparing sequences.  `floatfns.c'
+contains methods and primitives for floats and floating-point
+arithmetic.
+
+     bytecode.c
+     bytecode.h
+
+   `bytecode.c' implements the byte-code interpreter and
+compiled-function objects, and `bytecode.h' contains associated
+structures.  Note that the byte-code _compiler_ is written in Lisp.
+
+
+File: internals.info,  Node: Modules for Standard Editing Operations,  Next: Editor-Level Control Flow Modules,  Prev: Basic Lisp Modules,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Standard Editing Operations
+=======================================
+
+     buffer.c
+     buffer.h
+     bufslots.h
+
+   `buffer.c' implements the "buffer" Lisp object type.  This includes
+functions that create and destroy buffers; retrieve buffers by name or
+by other properties; manipulate lists of buffers (remember that buffers
+are permanent objects and stored in various ordered lists); retrieve or
+change buffer properties; etc.  It also contains the definitions of all
+the built-in buffer-local variables (which can be viewed as buffer
+properties).  It does _not_ contain code to manipulate buffer-local
+variables (that's in `symbols.c', described above); or code to
+manipulate the text in a buffer.
+
+   `buffer.h' defines the structures associated with a buffer and the
+various macros for retrieving text from a buffer and special buffer
+positions (e.g. `point', the default location for text insertion).  It
+also contains macros for working with buffer positions and converting
+between their representations as character offsets and as byte offsets
+(under MULE, they are different, because characters can be multi-byte).
+It is one of the largest header files.
+
+   `bufslots.h' defines the fields in the buffer structure that
+correspond to the built-in buffer-local variables.  It is its own
+header file because it is included many times in `buffer.c', as a way
+of iterating over all the built-in buffer-local variables.
+
+     insdel.c
+     insdel.h
+
+   `insdel.c' contains low-level functions for inserting and deleting
+text in a buffer, keeping track of changed regions for use by
+redisplay, and calling any before-change and after-change functions
+that may have been registered for the buffer.  It also contains the
+actual functions that convert between byte offsets and character
+offsets.
+
+   `insdel.h' contains associated headers.
+
+     marker.c
+
+   This module implements the "marker" Lisp object type, which
+conceptually is a pointer to a text position in a buffer that moves
+around as text is inserted and deleted, so as to remain in the same
+relative position.  This module doesn't actually move the markers around
+- that's handled in `insdel.c'.  This module just creates them and
+implements the primitives for working with them.  As markers are simple
+objects, this does not entail much.
+
+   Note that the standard arithmetic primitives (e.g. `+') accept
+markers in place of integers and automatically substitute the value of
+`marker-position' for the marker, i.e. an integer describing the
+current buffer position of the marker.
+
+     extents.c
+     extents.h
+
+   This module implements the "extent" Lisp object type, which is like
+a marker that works over a range of text rather than a single position.
+Extents are also much more complex and powerful than markers and have a
+more efficient (and more algorithmically complex) implementation.  The
+implementation is described in detail in comments in `extents.c'.
+
+   The code in `extents.c' works closely with `insdel.c' so that
+extents are properly moved around as text is inserted and deleted.
+There is also code in `extents.c' that provides information needed by
+the redisplay mechanism for efficient operation. (Remember that extents
+can have display properties that affect [sometimes drastically, as in
+the `invisible' property] the display of the text they cover.)
+
+     editfns.c
+
+   `editfns.c' contains the standard Lisp primitives for working with a
+buffer's text, and calls the low-level functions in `insdel.c'.  It
+also contains primitives for working with `point' (the default buffer
+insertion location).
+
+   `editfns.c' also contains functions for retrieving various
+characteristics from the external environment: the current time, the
+process ID of the running XEmacs process, the name of the user who ran
+this XEmacs process, etc.  It's not clear why this code is in
+`editfns.c'.
+
+     callint.c
+     cmds.c
+     commands.h
+
+   These modules implement the basic "interactive" commands, i.e.
+user-callable functions.  Commands, as opposed to other functions, have
+special ways of getting their parameters interactively (by querying the
+user), as opposed to having them passed in a normal function
+invocation.  Many commands are not really meant to be called from other
+Lisp functions, because they modify global state in a way that's often
+undesired as part of other Lisp functions.
+
+   `callint.c' implements the mechanism for querying the user for
+parameters and calling interactive commands.  The bulk of this module is
+code that parses the interactive spec that is supplied with an
+interactive command.
+
+   `cmds.c' implements the basic, most commonly used editing commands:
+commands to move around the current buffer and insert and delete
+characters.  These commands are implemented using the Lisp primitives
+defined in `editfns.c'.
+
+   `commands.h' contains associated structure definitions and
+prototypes.
+
+     regex.c
+     regex.h
+     search.c
+
+   `search.c' implements the Lisp primitives for searching for text in
+a buffer, and some of the low-level algorithms for doing this.  In
+particular, the fast fixed-string Boyer-Moore search algorithm is
+implemented in `search.c'.  The low-level algorithms for doing
+regular-expression searching, however, are implemented in `regex.c' and
+`regex.h'.  These two modules are largely independent of XEmacs, and
+are similar to (and based upon) the regular-expression routines used in
+`grep' and other GNU utilities.
+
+     doprnt.c
+
+   `doprnt.c' implements formatted-string processing, similar to
+`printf()' command in C.
+
+     undo.c
+
+   This module implements the undo mechanism for tracking buffer
+changes.  Most of this could be implemented in Lisp.
+
+
+File: internals.info,  Node: Editor-Level Control Flow Modules,  Next: Modules for the Basic Displayable Lisp Objects,  Prev: Modules for Standard Editing Operations,  Up: A Summary of the Various XEmacs Modules
+
+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
+
+   These implement the handling of events (user input and other system
+notifications).
+
+   `events.c' and `events.h' define the "event" Lisp object type and
+primitives for manipulating it.
+
+   `event-stream.c' implements the basic functions for working with
+event queues, dispatching an event by looking it up in relevant keymaps
+and such, and handling timeouts; this includes the primitives
+`next-event' and `dispatch-event', as well as related primitives such
+as `sit-for', `sleep-for', and `accept-process-output'.
+(`event-stream.c' is one of the hairiest and trickiest modules in
+XEmacs.  Beware!  You can easily mess things up here.)
+
+   `event-Xt.c' and `event-tty.c' implement the low-level interfaces
+onto retrieving events from Xt (the X toolkit) and from TTY's (using
+`read()' and `select()'), respectively.  The event interface enforces a
+clean separation between the specific code for interfacing with the
+operating system and the generic code for working with events, by
+defining an API of basic, low-level event methods; `event-Xt.c' and
+`event-tty.c' are two different implementations of this API.  To add
+support for a new operating system (e.g. NeXTstep), one merely needs to
+provide another implementation of those API functions.
+
+   Note that the choice of whether to use `event-Xt.c' or `event-tty.c'
+is made at compile time!  Or at the very latest, it is made at startup
+time.  `event-Xt.c' handles events for _both_ X and TTY frames;
+`event-tty.c' is only used when X support is not compiled into XEmacs.
+The reason for this is that there is only one event loop in XEmacs:
+thus, it needs to be able to receive events from all different kinds of
+frames.
+
+     keymap.c
+     keymap.h
+
+   `keymap.c' and `keymap.h' define the "keymap" Lisp object type and
+associated methods and primitives. (Remember that keymaps are objects
+that associate event descriptions with functions to be called to
+"execute" those events; `dispatch-event' looks up events in the
+relevant keymaps.)
+
+     cmdloop.c
+
+   `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'.
+
+     macros.c
+     macros.h
+
+   These two modules contain the basic code for defining keyboard
+macros.  These functions don't actually do much; most of the code that
+handles keyboard macros is mixed in with the event-handling code in
+`event-stream.c'.
+
+     minibuf.c
+
+   This contains some miscellaneous code related to the minibuffer
+(most of the minibuffer code was moved into Lisp by Richard Mlynarik).
+This includes the primitives for completion (although filename
+completion is in `dired.c'), the lowest-level interface to the
+minibuffer (if the command loop were cleaned up, this too could be in
+Lisp), and code for dealing with the echo area (this, too, was mostly
+moved into Lisp, and the only code remaining is code to call out to
+Lisp or provide simple bootstrapping implementations early in temacs,
+before the echo-area Lisp code is loaded).
+
+
+File: internals.info,  Node: Modules for the Basic Displayable Lisp Objects,  Next: Modules for other Display-Related Lisp Objects,  Prev: Editor-Level Control Flow Modules,  Up: A Summary of the Various XEmacs Modules
+
+Modules for the Basic Displayable Lisp Objects
+==============================================
+
+     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-x.c
+     device.c
+     device.h
+
+   These modules implement the "device" Lisp object type.  This
+abstracts a particular screen or connection on which frames are
+displayed.  As with Lisp objects, event interfaces, and other
+subsystems, the device code is separated into a generic component that
+contains a standardized interface (in the form of a set of methods) onto
+particular device types.
+
+   The device subsystem defines all the methods and provides method
+services for not only device operations but also for the frame, window,
+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-msw.c
+     frame-tty.c
+     frame-x.c
+     frame.c
+     frame.h
+
+   Each device contains one or more frames in which objects (e.g. text)
+are displayed.  A frame corresponds to a window in the window system;
+usually this is a top-level window but it could potentially be one of a
+number of overlapping child windows within a top-level window, using the
+MDI (Multiple Document Interface) protocol in Microsoft Windows or a
+similar scheme.
+
+   The `frame-*' files implement the "frame" Lisp object type and
+provide the generic and device-type-specific operations on frames (e.g.
+raising, lowering, resizing, moving, etc.).
+
+     window.c
+     window.h
+
+   Each frame consists of one or more non-overlapping "windows" (better
+known as "panes" in standard window-system terminology) in which a
+buffer's text can be displayed.  Windows can also have scrollbars
+displayed around their edges.
+
+   `window.c' and `window.h' implement the "window" Lisp object type
+and provide code to manage windows.  Since windows have no associated
+resources in the window system (the window system knows only about the
+frame; no child windows or anything are used for XEmacs windows), there
+is no device-type-specific code here; all of that code is part of the
+redisplay mechanism or the code for particular object types such as
+scrollbars.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-4'
Index: ././info/internals.info-4
--- ././info/internals.info-4	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-4	Thu May 17 23:26:54 2001
@@ -0,0 +1,1042 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Modules for other Display-Related Lisp Objects,  Next: Modules for the Redisplay Mechanism,  Prev: Modules for the Basic Displayable Lisp Objects,  Up: A Summary of the Various XEmacs Modules
+
+Modules for other Display-Related Lisp Objects
+==============================================
+
+     faces.c
+     faces.h
+
+     bitmaps.h
+     glyphs-eimage.c
+     glyphs-msw.c
+     glyphs-msw.h
+     glyphs-widget.c
+     glyphs-x.c
+     glyphs-x.h
+     glyphs.c
+     glyphs.h
+
+     objects-msw.c
+     objects-msw.h
+     objects-tty.c
+     objects-tty.h
+     objects-x.c
+     objects-x.h
+     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
+
+     font-lock.c
+
+   This file provides C support for syntax highlighting--i.e.
+highlighting different syntactic constructs of a source file in
+different colors, for easy reading.  The C support is provided so that
+this is fast.
+
+     dgif_lib.c
+     gif_err.c
+     gif_lib.h
+     gifalloc.c
+
+   These modules decode GIF-format image files, for use with glyphs.
+These files were removed due to Unisys patent infringement concerns.
+
+
+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
+
+Modules for the Redisplay Mechanism
+===================================
+
+     redisplay-output.c
+     redisplay-msw.c
+     redisplay-tty.c
+     redisplay-x.c
+     redisplay.c
+     redisplay.h
+
+   These files provide the redisplay mechanism.  As with many other
+subsystems in XEmacs, there is a clean separation between the general
+and device-specific support.
+
+   `redisplay.c' contains the bulk of the redisplay engine.  These
+functions update the redisplay structures (which describe how the screen
+is to appear) to reflect any changes made to the state of any
+displayable objects (buffer, frame, window, etc.) since the last time
+that redisplay was called.  These functions are highly optimized to
+avoid doing more work than necessary (since redisplay is called
+extremely often and is potentially a huge time sink), and depend heavily
+on notifications from the objects themselves that changes have occurred,
+so that redisplay doesn't explicitly have to check each possible object.
+The redisplay mechanism also contains a great deal of caching to further
+speed things up; some of this caching is contained within the various
+displayable objects.
+
+   `redisplay-output.c' goes through the redisplay structures and
+converts them into calls to device-specific methods to actually output
+the screen changes.
+
+   `redisplay-x.c' and `redisplay-tty.c' are two implementations of
+these redisplay output methods, for X frames and TTY frames,
+respectively.
+
+     indent.c
+
+   This module contains various functions and Lisp primitives for
+converting between buffer positions and screen positions.  These
+functions call the redisplay mechanism to do most of the work, and then
+examine the redisplay structures to get the necessary information.  This
+module needs work.
+
+     termcap.c
+     terminfo.c
+     tparam.c
+
+   These files contain functions for working with the termcap
+(BSD-style) and terminfo (System V style) databases of terminal
+capabilities and escape sequences, used when XEmacs is displaying in a
+TTY.
+
+     cm.c
+     cm.h
+
+   These files provide some miscellaneous TTY-output functions and
+should probably be merged into `redisplay-tty.c'.
+
+
+File: internals.info,  Node: Modules for Interfacing with the File System,  Next: Modules for Other Aspects of the Lisp Interpreter and Object System,  Prev: Modules for the Redisplay Mechanism,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with the File System
+============================================
+
+     lstream.c
+     lstream.h
+
+   These modules implement the "stream" Lisp object type.  This is an
+internal-only Lisp object that implements a generic buffering stream.
+The idea is to provide a uniform interface onto all sources and sinks of
+data, including file descriptors, stdio streams, chunks of memory, Lisp
+buffers, Lisp strings, etc.  That way, I/O functions can be written to
+the stream interface and can transparently handle all possible sources
+and sinks.  (For example, the `read' function can read data from a
+file, a string, a buffer, or even a function that is called repeatedly
+to return data, without worrying about where the data is coming from or
+what-size chunks it is returned in.)
+
+   Note that in the C code, streams are called "lstreams" (for "Lisp
+streams") to distinguish them from other kinds of streams, e.g. stdio
+streams and C++ I/O streams.
+
+   Similar to other subsystems in XEmacs, lstreams are separated into
+generic functions and a set of methods for the different types of
+lstreams.  `lstream.c' provides implementations of many different types
+of streams; others are provided, e.g., in `file-coding.c'.
+
+     fileio.c
+
+   This implements the basic primitives for interfacing with the file
+system.  This includes primitives for reading files into buffers,
+writing buffers into files, checking for the presence or accessibility
+of files, canonicalizing file names, etc.  Note that these primitives
+are usually not invoked directly by the user: There is a great deal of
+higher-level Lisp code that implements the user commands such as
+`find-file' and `save-buffer'.  This is similar to the distinction
+between the lower-level primitives in `editfns.c' and the higher-level
+user commands in `commands.c' and `simple.el'.
+
+     filelock.c
+
+   This file provides functions for detecting clashes between different
+processes (e.g. XEmacs and some external process, or two different
+XEmacs processes) modifying the same file.  (XEmacs can optionally use
+the `lock/' subdirectory to provide a form of "locking" between
+different XEmacs processes.)  This module is also used by the low-level
+functions in `insdel.c' to ensure that, if the first modification is
+being made to a buffer whose corresponding file has been externally
+modified, the user is made aware of this so that the buffer can be
+synched up with the external changes if necessary.
+
+     filemode.c
+
+   This file provides some miscellaneous functions that construct a
+`rwxr-xr-x'-type permissions string (as might appear in an `ls'-style
+directory listing) given the information returned by the `stat()'
+system call.
+
+     dired.c
+     ndir.h
+
+   These files implement the XEmacs interface to directory searching.
+This includes a number of primitives for determining the files in a
+directory and for doing filename completion. (Remember that generic
+completion is handled by a different mechanism, in `minibuf.c'.)
+
+   `ndir.h' is a header file used for the directory-searching emulation
+functions provided in `sysdep.c' (see section J below), for systems
+that don't provide any directory-searching functions. (On those
+systems, directories can be read directly as files, and parsed.)
+
+     realpath.c
+
+   This file provides an implementation of the `realpath()' function
+for expanding symbolic links, on systems that don't implement it or have
+a broken implementation.
+
+
+File: internals.info,  Node: Modules for Other Aspects of the Lisp Interpreter and Object System,  Next: Modules for Interfacing with the Operating System,  Prev: Modules for Interfacing with the File System,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Other Aspects of the Lisp Interpreter and Object System
+===================================================================
+
+     elhash.c
+     elhash.h
+     hash.c
+     hash.h
+
+   These files provide two implementations of hash tables.  Files
+`hash.c' and `hash.h' provide a generic C implementation of hash tables
+which can stand independently of XEmacs.  Files `elhash.c' and
+`elhash.h' provide a separate implementation of hash tables that can
+store only Lisp objects, and knows about Lispy things like garbage
+collection, and implement the "hash-table" Lisp object type.
+
+     specifier.c
+     specifier.h
+
+   This module implements the "specifier" Lisp object type.  This is
+primarily used for displayable properties, and allows for values that
+are specific to a particular buffer, window, frame, device, or device
+class, as well as a default value existing.  This is used, for example,
+to control the height of the horizontal scrollbar or the appearance of
+the `default', `bold', or other faces.  The specifier object consists
+of a number of specifications, each of which maps from a buffer,
+window, etc. to a value.  The function `specifier-instance' looks up a
+value given a window (from which a buffer, frame, and device can be
+derived).
+
+     chartab.c
+     chartab.h
+     casetab.c
+
+   `chartab.c' and `chartab.h' implement the "char table" Lisp object
+type, which maps from characters or certain sorts of character ranges
+to Lisp objects.  The implementation of this object type is optimized
+for the internal representation of characters.  Char tables come in
+different types, which affect the allowed object types to which a
+character can be mapped and also dictate certain other properties of
+the char table.
+
+   `casetab.c' implements one sort of char table, the "case table",
+which maps characters to other characters of possibly different case.
+These are used by XEmacs to implement case-changing primitives and to
+do case-insensitive searching.
+
+     syntax.c
+     syntax.h
+
+   This module implements "syntax tables", another sort of char table
+that maps characters into syntax classes that define the syntax of these
+characters (e.g. a parenthesis belongs to a class of `open' characters
+that have corresponding `close' characters and can be nested).  This
+module also implements the Lisp "scanner", a set of primitives for
+scanning over text based on syntax tables.  This is used, for example,
+to find the matching parenthesis in a command such as `forward-sexp',
+and by `font-lock.c' to locate quoted strings, comments, etc.
+
+     casefiddle.c
+
+   This module implements various Lisp primitives for upcasing,
+downcasing and capitalizing strings or regions of buffers.
+
+     rangetab.c
+
+   This module implements the "range table" Lisp object type, which
+provides for a mapping from ranges of integers to arbitrary Lisp
+objects.
+
+     opaque.c
+     opaque.h
+
+   This module implements the "opaque" Lisp object type, an
+internal-only Lisp object that encapsulates an arbitrary block of memory
+so that it can be managed by the Lisp allocation system.  To create an
+opaque object, you call `make_opaque()', passing a pointer to a block
+of memory.  An object is created that is big enough to hold the memory,
+which is copied into the object's storage.  The object will then stick
+around as long as you keep pointers to it, after which it will be
+automatically reclaimed.
+
+   Opaque objects can also have an arbitrary "mark method" associated
+with them, in case the block of memory contains other Lisp objects that
+need to be marked for garbage-collection purposes. (If you need other
+object methods, such as a finalize method, you should just go ahead and
+create a new Lisp object type--it's not hard.)
+
+     abbrev.c
+
+   This function provides a few primitives for doing dynamic
+abbreviation expansion.  In XEmacs, most of the code for this has been
+moved into Lisp.  Some C code remains for speed and because the
+primitive `self-insert-command' (which is executed for all
+self-inserting characters) hooks into the abbrev mechanism.
+(`self-insert-command' is itself in C only for speed.)
+
+     doc.c
+
+   This function provides primitives for retrieving the documentation
+strings of functions and variables.  These documentation strings contain
+certain special markers that get dynamically expanded (e.g. a
+reverse-lookup is performed on some named functions to retrieve their
+current key bindings).  Some documentation strings (in particular, for
+the built-in primitives and pre-loaded Lisp functions) are stored
+externally in a file `DOC' in the `lib-src/' directory and need to be
+fetched from that file. (Part of the build stage involves building this
+file, and another part involves constructing an index for this file and
+embedding it into the executable, so that the functions in `doc.c' do
+not have to search the entire `DOC' file to find the appropriate
+documentation string.)
+
+     md5.c
+
+   This function provides a Lisp primitive that implements the MD5
+secure hashing scheme, used to create a large hash value of a string of
+data such that the data cannot be derived from the hash value.  This is
+used for various security applications on the Internet.
+
+
+File: internals.info,  Node: Modules for Interfacing with the Operating System,  Next: Modules for Interfacing with X Windows,  Prev: Modules for Other Aspects of the Lisp Interpreter and Object System,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with the Operating System
+=================================================
+
+     callproc.c
+     process.c
+     process.h
+
+   These modules allow XEmacs to spawn and communicate with subprocesses
+and network connections.
+
+   `callproc.c' implements (through the `call-process' primitive) what
+are called "synchronous subprocesses".  This means that XEmacs runs a
+program, waits till it's done, and retrieves its output.  A typical
+example might be calling the `ls' program to get a directory listing.
+
+   `process.c' and `process.h' implement "asynchronous subprocesses".
+This means that XEmacs starts a program and then continues normally,
+not waiting for the process to finish.  Data can be sent to the process
+or retrieved from it as it's running.  This is used for the `shell'
+command (which provides a front end onto a shell program such as
+`csh'), the mail and news readers implemented in XEmacs, etc.  The
+result of calling `start-process' to start a subprocess is a process
+object, a particular kind of object used to communicate with the
+subprocess.  You can send data to the process by passing the process
+object and the data to `send-process', and you can specify what happens
+to data retrieved from the process by setting properties of the process
+object. (When the process sends data, XEmacs receives a process event,
+which says that there is data ready.  When `dispatch-event' is called
+on this event, it reads the data from the process and does something
+with it, as specified by the process object's properties.  Typically,
+this means inserting the data into a buffer or calling a function.)
+Another property of the process object is called the "sentinel", which
+is a function that is called when the process terminates.
+
+   Process objects are also used for network connections (connections
+to a process running on another machine).  Network connections are
+started with `open-network-stream' but otherwise work just like
+subprocesses.
+
+     sysdep.c
+     sysdep.h
+
+   These modules implement most of the low-level, messy operating-system
+interface code.  This includes various device control (ioctl) operations
+for file descriptors, TTY's, pseudo-terminals, etc. (usually this stuff
+is fairly system-dependent; thus the name of this module), and emulation
+of standard library functions and system calls on systems that don't
+provide them or have broken versions.
+
+     sysdir.h
+     sysfile.h
+     sysfloat.h
+     sysproc.h
+     syspwd.h
+     syssignal.h
+     systime.h
+     systty.h
+     syswait.h
+
+   These header files provide consistent interfaces onto
+system-dependent header files and system calls.  The idea is that,
+instead of including a standard header file like `<sys/param.h>' (which
+may or may not exist on various systems) or having to worry about
+whether all system provide a particular preprocessor constant, or
+having to deal with the four different paradigms for manipulating
+signals, you just include the appropriate `sys*.h' header file, which
+includes all the right system header files, defines and missing
+preprocessor constants, provides a uniform interface onto system calls,
+etc.
+
+   `sysdir.h' provides a uniform interface onto directory-querying
+functions. (In some cases, this is in conjunction with emulation
+functions in `sysdep.c'.)
+
+   `sysfile.h' includes all the necessary header files for standard
+system calls (e.g. `read()'), ensures that all necessary `open()' and
+`stat()' preprocessor constants are defined, and possibly (usually)
+substitutes sugared versions of `read()', `write()', etc. that
+automatically restart interrupted I/O operations.
+
+   `sysfloat.h' includes the necessary header files for floating-point
+operations.
+
+   `sysproc.h' includes the necessary header files for calling
+`select()', `fork()', `execve()', socket operations, and the like, and
+ensures that the `FD_*()' macros for descriptor-set manipulations are
+available.
+
+   `syspwd.h' includes the necessary header files for obtaining
+information from `/etc/passwd' (the functions are emulated under VMS).
+
+   `syssignal.h' includes the necessary header files for
+signal-handling and provides a uniform interface onto the different
+signal-handling and signal-blocking paradigms.
+
+   `systime.h' includes the necessary header files and provides uniform
+interfaces for retrieving the time of day, setting file
+access/modification times, getting the amount of time used by the XEmacs
+process, etc.
+
+   `systty.h' buffers against the infinitude of different ways of
+controlling TTY's.
+
+   `syswait.h' provides a uniform way of retrieving the exit status
+from a `wait()'ed-on process (some systems use a union, others use an
+int).
+
+     hpplay.c
+     libsst.c
+     libsst.h
+     libst.h
+     linuxplay.c
+     nas.c
+     sgiplay.c
+     sound.c
+     sunplay.c
+
+   These files implement the ability to play various sounds on some
+types of computers.  You have to configure your XEmacs with sound
+support in order to get this capability.
+
+   `sound.c' provides the generic interface.  It implements various
+Lisp primitives and variables that let you specify which sounds should
+be played in certain conditions. (The conditions are identified by
+symbols, which are passed to `ding' to make a sound.  Various standard
+functions call this function at certain times; if sound support does
+not exist, a simple beep results.
+
+   `sgiplay.c', `sunplay.c', `hpplay.c', and `linuxplay.c' interface to
+the machine's speaker for various different kind of machines.  This is
+called "native" sound.
+
+   `nas.c' interfaces to a computer somewhere else on the network using
+the NAS (Network Audio Server) protocol, playing sounds on that
+machine.  This allows you to run XEmacs on a remote machine, with its
+display set to your local machine, and have the sounds be made on your
+local machine, provided that you have a NAS server running on your local
+machine.
+
+   `libsst.c', `libsst.h', and `libst.h' provide some additional
+functions for playing sound on a Sun SPARC but are not currently in use.
+
+     tooltalk.c
+     tooltalk.h
+
+   These two modules implement an interface to the ToolTalk protocol,
+which is an interprocess communication protocol implemented on some
+versions of Unix.  ToolTalk is a high-level protocol that allows
+processes to register themselves as providers of particular services;
+other processes can then request a service without knowing or caring
+exactly who is providing the service.  It is similar in spirit to the
+DDE protocol provided under Microsoft Windows.  ToolTalk is a part of
+the new CDE (Common Desktop Environment) specification and is used to
+connect the parts of the SPARCWorks development environment.
+
+     getloadavg.c
+
+   This module provides the ability to retrieve the system's current
+load average. (The way to do this is highly system-specific,
+unfortunately, and requires a lot of special-case code.)
+
+     sunpro.c
+
+   This module provides a small amount of code used internally at Sun to
+keep statistics on the usage of XEmacs.
+
+     broken-sun.h
+     strcmp.c
+     strcpy.c
+     sunOS-fix.c
+
+   These files provide replacement functions and prototypes to fix
+numerous bugs in early releases of SunOS 4.1.
+
+     hftctl.c
+
+   This module provides some terminal-control code necessary on
+versions of AIX prior to 4.1.
+
+
+File: internals.info,  Node: Modules for Interfacing with X Windows,  Next: Modules for Internationalization,  Prev: Modules for Interfacing with the Operating System,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Interfacing with X Windows
+======================================
+
+     Emacs.ad.h
+
+   A file generated from `Emacs.ad', which contains XEmacs-supplied
+fallback resources (so that XEmacs has pretty defaults).
+
+     EmacsFrame.c
+     EmacsFrame.h
+     EmacsFrameP.h
+
+   These modules implement an Xt widget class that encapsulates a frame.
+This is for ease in integrating with Xt.  The EmacsFrame widget covers
+the entire X window except for the menubar; the scrollbars are
+positioned on top of the EmacsFrame widget.
+
+   *Warning:* Abandon hope, all ye who enter here.  This code took an
+ungodly amount of time to get right, and is likely to fall apart
+mercilessly at the slightest change.  Such is life under Xt.
+
+     EmacsManager.c
+     EmacsManager.h
+     EmacsManagerP.h
+
+   These modules implement a simple Xt manager (i.e. composite) widget
+class that simply lets its children set whatever geometry they want.
+It's amazing that Xt doesn't provide this standardly, but on second
+thought, it makes sense, considering how amazingly broken Xt is.
+
+     EmacsShell-sub.c
+     EmacsShell.c
+     EmacsShell.h
+     EmacsShellP.h
+
+   These modules implement two Xt widget classes that are subclasses of
+the TopLevelShell and TransientShell classes.  This is necessary to deal
+with more brokenness that Xt has sadistically thrust onto the backs of
+developers.
+
+     xgccache.c
+     xgccache.h
+
+   These modules provide functions for maintenance and caching of GC's
+(graphics contexts) under the X Window System.  This code is junky and
+needs to be rewritten.
+
+     select-msw.c
+     select-x.c
+     select.c
+     select.h
+
+   This module provides an interface to the X Window System's concept of
+"selections", the standard way for X applications to communicate with
+each other.
+
+     xintrinsic.h
+     xintrinsicp.h
+     xmmanagerp.h
+     xmprimitivep.h
+
+   These header files are similar in spirit to the `sys*.h' files and
+buffer against different implementations of Xt and Motif.
+
+   * `xintrinsic.h' should be included in place of `<Intrinsic.h>'.
+
+   * `xintrinsicp.h' should be included in place of `<IntrinsicP.h>'.
+
+   * `xmmanagerp.h' should be included in place of `<XmManagerP.h>'.
+
+   * `xmprimitivep.h' should be included in place of `<XmPrimitiveP.h>'.
+
+     xmu.c
+     xmu.h
+
+   These files provide an emulation of the Xmu library for those systems
+(i.e. HPUX) that don't provide it as a standard part of X.
+
+     ExternalClient-Xlib.c
+     ExternalClient.c
+     ExternalClient.h
+     ExternalClientP.h
+     ExternalShell.c
+     ExternalShell.h
+     ExternalShellP.h
+     extw-Xlib.c
+     extw-Xlib.h
+     extw-Xt.c
+     extw-Xt.h
+
+   These files provide the "external widget" interface, which allows an
+XEmacs frame to appear as a widget in another application.  To do this,
+you have to configure with `--external-widget'.
+
+   `ExternalShell*' provides the server (XEmacs) side of the connection.
+
+   `ExternalClient*' provides the client (other application) side of
+the connection.  These files are not compiled into XEmacs but are
+compiled into libraries that are then linked into your application.
+
+   `extw-*' is common code that is used for both the client and server.
+
+   Don't touch this code; something is liable to break if you do.
+
+
+File: internals.info,  Node: Modules for Internationalization,  Prev: Modules for Interfacing with X Windows,  Up: A Summary of the Various XEmacs Modules
+
+Modules for Internationalization
+================================
+
+     mule-canna.c
+     mule-ccl.c
+     mule-charset.c
+     mule-charset.h
+     file-coding.c
+     file-coding.h
+     mule-mcpath.c
+     mule-mcpath.h
+     mule-wnnfns.c
+     mule.c
+
+   These files implement the MULE (Asian-language) support.  Note that
+MULE actually provides a general interface for all sorts of languages,
+not just Asian languages (although they are generally the most
+complicated to support).  This code is still in beta.
+
+   `mule-charset.*' and `file-coding.*' provide the heart of the XEmacs
+MULE support.  `mule-charset.*' implements the "charset" Lisp object
+type, which encapsulates a character set (an ordered one- or
+two-dimensional set of characters, such as US ASCII or JISX0208 Japanese
+Kanji).
+
+   `file-coding.*' implements the "coding-system" Lisp object type,
+which encapsulates a method of converting between different encodings.
+An encoding is a representation of a stream of characters, possibly
+from multiple character sets, using a stream of bytes or words, and
+defines (e.g.) which escape sequences are used to specify particular
+character sets, how the indices for a character are converted into bytes
+(sometimes this involves setting the high bit; sometimes complicated
+rearranging of the values takes place, as in the Shift-JIS encoding),
+etc.
+
+   `mule-ccl.c' provides the CCL (Code Conversion Language)
+interpreter.  CCL is similar in spirit to Lisp byte code and is used to
+implement converters for custom encodings.
+
+   `mule-canna.c' and `mule-wnnfns.c' implement interfaces to external
+programs used to implement the Canna and WNN input methods,
+respectively.  This is currently in beta.
+
+   `mule-mcpath.c' provides some functions to allow for pathnames
+containing extended characters.  This code is fragmentary, obsolete, and
+completely non-working.  Instead, PATHNAME-CODING-SYSTEM is used to
+specify conversions of names of files and directories.  The standard C
+I/O functions like `open()' are wrapped so that conversion occurs
+automatically.
+
+   `mule.c' provides a few miscellaneous things that should probably be
+elsewhere.
+
+     intl.c
+
+   This provides some miscellaneous internationalization code for
+implementing message translation and interfacing to the Ximp input
+method.  None of this code is currently working.
+
+     iso-wide.h
+
+   This contains leftover code from an earlier implementation of
+Asian-language support, and is not currently used.
+
+
+File: internals.info,  Node: Allocation of Objects in XEmacs Lisp,  Next: Dumping,  Prev: A Summary of the Various XEmacs Modules,  Up: Top
+
+Allocation of Objects in XEmacs Lisp
+************************************
+
+* Menu:
+
+* Introduction to Allocation::
+* Garbage Collection::
+* GCPROing::
+* Garbage Collection - Step by Step::
+* Integers and Characters::
+* Allocation from Frob Blocks::
+* lrecords::
+* Low-level allocation::
+* Cons::
+* Vector::
+* Bit Vector::
+* Symbol::
+* Marker::
+* String::
+* Compiled Function::
+
+
+File: internals.info,  Node: Introduction to Allocation,  Next: Garbage Collection,  Up: Allocation of Objects in XEmacs Lisp
+
+Introduction to Allocation
+==========================
+
+   Emacs Lisp, like all Lisps, has garbage collection.  This means that
+the programmer never has to explicitly free (destroy) an object; it
+happens automatically when the object becomes inaccessible.  Most
+experts agree that garbage collection is a necessity in a modern,
+high-level language.  Its omission from C stems from the fact that C was
+originally designed to be a nice abstract layer on top of assembly
+language, for writing kernels and basic system utilities rather than
+large applications.
+
+   Lisp objects can be created by any of a number of Lisp primitives.
+Most object types have one or a small number of basic primitives for
+creating objects.  For conses, the basic primitive is `cons'; for
+vectors, the primitives are `make-vector' and `vector'; for symbols,
+the primitives are `make-symbol' and `intern'; etc.  Some Lisp objects,
+especially those that are primarily used internally, have no
+corresponding Lisp primitives.  Every Lisp object, though, has at least
+one C primitive for creating it.
+
+   Recall from section (VII) that a Lisp object, as stored in a 32-bit
+or 64-bit word, has a few tag bits, and a "value" that occupies the
+remainder of the bits.  We can separate the different Lisp object types
+into three broad categories:
+
+   * (a) Those for whom the value directly represents the contents of
+     the Lisp object.  Only two types are in this category: integers and
+     characters.  No special allocation or garbage collection is
+     necessary for such objects.  Lisp objects of these types do not
+     need to be `GCPRO'ed.
+
+   In the remaining two categories, the type is stored in the object
+itself.  The tag for all such objects is the generic "lrecord"
+(Lisp_Type_Record) tag.  The first bytes of the object's structure are
+an integer (actually a char) characterising the object's type and some
+flags, in particular the mark bit used for garbage collection.  A
+structure describing the type is accessible thru the
+lrecord_implementation_table indexed with said integer.  This structure
+includes the method pointers and a pointer to a string naming the type.
+
+   * (b) Those lrecords that are allocated in frob blocks (see above).
+     This includes the objects that are most common and relatively
+     small, and includes conses, strings, subrs, floats, compiled
+     functions, symbols, extents, events, and markers.  With the
+     cleanup of frob blocks done in 19.12, it's not terribly hard to
+     add more objects to this category, but it's a bit trickier than
+     adding an object type to type (c) (esp. if the object needs a
+     finalization method), and is not likely to save much space unless
+     the object is small and there are many of them. (In fact, if there
+     are very few of them, it might actually waste space.)
+
+   * (c) Those lrecords that are individually `malloc()'ed.  These are
+     called "lcrecords".  All other types are in this category.  Adding
+     a new type to this category is comparatively easy, and all types
+     added since 19.8 (when the current allocation scheme was devised,
+     by Richard Mlynarik), with the exception of the character type,
+     have been in this category.
+
+   Note that bit vectors are a bit of a special case.  They are simple
+lrecords as in category (b), but are individually `malloc()'ed like
+vectors.  You can basically view them as exactly like vectors except
+that their type is stored in lrecord fashion rather than in
+directly-tagged fashion.
+
+
+File: internals.info,  Node: Garbage Collection,  Next: GCPROing,  Prev: Introduction to Allocation,  Up: Allocation of Objects in XEmacs Lisp
+
+Garbage Collection
+==================
+
+   Garbage collection is simple in theory but tricky to implement.
+Emacs Lisp uses the oldest garbage collection method, called "mark and
+sweep".  Garbage collection begins by starting with all accessible
+locations (i.e. all variables and other slots where Lisp objects might
+occur) and recursively traversing all objects accessible from those
+slots, marking each one that is found.  We then go through all of
+memory and free each object that is not marked, and unmarking each
+object that is marked.  Note that "all of memory" means all currently
+allocated objects.  Traversing all these objects means traversing all
+frob blocks, all vectors (which are chained in one big list), and all
+lcrecords (which are likewise chained).
+
+   Garbage collection can be invoked explicitly by calling
+`garbage-collect' but is also called automatically by `eval', once a
+certain amount of memory has been allocated since the last garbage
+collection (according to `gc-cons-threshold').
+
+
+File: internals.info,  Node: GCPROing,  Next: Garbage Collection - Step by Step,  Prev: Garbage Collection,  Up: Allocation of Objects in XEmacs Lisp
+
+`GCPRO'ing
+==========
+
+   `GCPRO'ing is one of the ugliest and trickiest parts of Emacs
+internals.  The basic idea is that whenever garbage collection occurs,
+all in-use objects must be reachable somehow or other from one of the
+roots of accessibility.  The roots of accessibility are:
+
+  1. All objects that have been `staticpro()'d or
+     `staticpro_nodump()'ed.  This is used for any global C variables
+     that hold Lisp objects.  A call to `staticpro()' happens implicitly
+     as a result of any symbols declared with `defsymbol()' and any
+     variables declared with `DEFVAR_FOO()'.  You need to explicitly
+     call `staticpro()' (in the `vars_of_foo()' method of a module) for
+     other global C variables holding Lisp objects. (This typically
+     includes internal lists and such things.).  Use
+     `staticpro_nodump()' only in the rare cases when you do not want
+     the pointed variable to be saved at dump time but rather recompute
+     it at startup.
+
+     Note that `obarray' is one of the `staticpro()'d things.
+     Therefore, all functions and variables get marked through this.
+
+  2. Any shadowed bindings that are sitting on the `specpdl' stack.
+
+  3. Any objects sitting in currently active (Lisp) stack frames,
+     catches, and condition cases.
+
+  4. A couple of special-case places where active objects are located.
+
+  5. Anything currently marked with `GCPRO'.
+
+   Marking with `GCPRO' is necessary because some C functions (quite a
+lot, in fact), allocate objects during their operation.  Quite
+frequently, there will be no other pointer to the object while the
+function is running, and if a garbage collection occurs and the object
+needs to be referenced again, bad things will happen.  The solution is
+to mark those objects with `GCPRO'.  Unfortunately this is easy to
+forget, and there is basically no way around this problem.  Here are
+some rules, though:
+
+  1. For every `GCPRON', there have to be declarations of `struct gcpro
+     gcpro1, gcpro2', etc.
+
+  2. You _must_ `UNGCPRO' anything that's `GCPRO'ed, and you _must not_
+     `UNGCPRO' if you haven't `GCPRO'ed.  Getting either of these wrong
+     will lead to crashes, often in completely random places unrelated
+     to where the problem lies.
+
+  3. The way this actually works is that all currently active `GCPRO's
+     are chained through the `struct gcpro' local variables, with the
+     variable `gcprolist' pointing to the head of the list and the nth
+     local `gcpro' variable pointing to the first `gcpro' variable in
+     the next enclosing stack frame.  Each `GCPRO'ed thing is an
+     lvalue, and the `struct gcpro' local variable contains a pointer to
+     this lvalue.  This is why things will mess up badly if you don't
+     pair up the `GCPRO's and `UNGCPRO's--you will end up with
+     `gcprolist's containing pointers to `struct gcpro's or local
+     `Lisp_Object' variables in no-longer-active stack frames.
+
+  4. It is actually possible for a single `struct gcpro' to protect a
+     contiguous array of any number of values, rather than just a
+     single lvalue.  To effect this, call `GCPRON' as usual on the
+     first object in the array and then set `gcproN.nvars'.
+
+  5. *Strings are relocated.*  What this means in practice is that the
+     pointer obtained using `XSTRING_DATA()' is liable to change at any
+     time, and you should never keep it around past any function call,
+     or pass it as an argument to any function that might cause a
+     garbage collection.  This is why a number of functions accept
+     either a "non-relocatable" `char *' pointer or a relocatable Lisp
+     string, and only access the Lisp string's data at the very last
+     minute.  In some cases, you may end up having to `alloca()' some
+     space and copy the string's data into it.
+
+  6. By convention, if you have to nest `GCPRO''s, use `NGCPRON' (along
+     with `struct gcpro ngcpro1, ngcpro2', etc.), `NNGCPRON', etc.
+     This avoids compiler warnings about shadowed locals.
+
+  7. It is _always_ better to err on the side of extra `GCPRO's rather
+     than too few.  The extra cycles spent on this are almost never
+     going to make a whit of difference in the speed of anything.
+
+  8. The general rule to follow is that caller, not callee, `GCPRO's.
+     That is, you should not have to explicitly `GCPRO' any Lisp objects
+     that are passed in as parameters.
+
+     One exception from this rule is if you ever plan to change the
+     parameter value, and store a new object in it.  In that case, you
+     _must_ `GCPRO' the parameter, because otherwise the new object
+     will not be protected.
+
+     So, if you create any Lisp objects (remember, this happens in all
+     sorts of circumstances, e.g. with `Fcons()', etc.), you are
+     responsible for `GCPRO'ing them, unless you are _absolutely sure_
+     that there's no possibility that a garbage-collection can occur
+     while you need to use the object.  Even then, consider `GCPRO'ing.
+
+  9. A garbage collection can occur whenever anything calls `Feval', or
+     whenever a QUIT can occur where execution can continue past this.
+     (Remember, this is almost anywhere.)
+
+ 10. If you have the _least smidgeon of doubt_ about whether you need
+     to `GCPRO', you should `GCPRO'.
+
+ 11. Beware of `GCPRO'ing something that is uninitialized.  If you have
+     any shade of doubt about this, initialize all your variables to
+     `Qnil'.
+
+ 12. Be careful of traps, like calling `Fcons()' in the argument to
+     another function.  By the "caller protects" law, you should be
+     `GCPRO'ing the newly-created cons, but you aren't.  A certain
+     number of functions that are commonly called on freshly created
+     stuff (e.g. `nconc2()', `Fsignal()'), break the "caller protects"
+     law and go ahead and `GCPRO' their arguments so as to simplify
+     things, but make sure and check if it's OK whenever doing
+     something like this.
+
+ 13. Once again, remember to `GCPRO'!  Bugs resulting from insufficient
+     `GCPRO'ing are intermittent and extremely difficult to track down,
+     often showing up in crashes inside of `garbage-collect' or in
+     weirdly corrupted objects or even in incorrect values in a totally
+     different section of code.
+
+   Given the extremely error-prone nature of the `GCPRO' scheme, and
+the difficulties in tracking down, it should be considered a deficiency
+in the XEmacs code.  A solution to this problem would involve
+implementing so-called "conservative" garbage collection for the C
+stack.  That involves looking through all of stack memory and treating
+anything that looks like a reference to an object as a reference.  This
+will result in a few objects not getting collected when they should, but
+it obviates the need for `GCPRO'ing, and allows garbage collection to
+happen at any point at all, such as during object allocation.
+
+
+File: internals.info,  Node: Garbage Collection - Step by Step,  Next: Integers and Characters,  Prev: GCPROing,  Up: Allocation of Objects in XEmacs Lisp
+
+Garbage Collection - Step by Step
+=================================
+
+* Menu:
+
+* Invocation::
+* garbage_collect_1::
+* mark_object::
+* gc_sweep::
+* sweep_lcrecords_1::
+* compact_string_chars::
+* sweep_strings::
+* sweep_bit_vectors_1::
+
+
+File: internals.info,  Node: Invocation,  Next: garbage_collect_1,  Up: Garbage Collection - Step by Step
+
+Invocation
+----------
+
+   The first thing that anyone should know about garbage collection is:
+when and how the garbage collector is invoked. One might think that this
+could happen every time new memory is allocated, e.g. new objects are
+created, but this is _not_ the case. Instead, we have the following
+situation:
+
+   The entry point of any process of garbage collection is an invocation
+of the function `garbage_collect_1' in file `alloc.c'. The invocation
+can occur _explicitly_ by calling the function `Fgarbage_collect' (in
+addition this function provides information about the freed memory), or
+can occur _implicitly_ in four different situations:
+  1. In function `main_1' in file `emacs.c'. This function is called at
+     each startup of xemacs. The garbage collection is invoked after all
+     initial creations are completed, but only if a special internal
+     error checking-constant `ERROR_CHECK_GC' is defined.
+
+  2. In function `disksave_object_finalization' in file `alloc.c'. The
+     only purpose of this function is to clear the objects from memory
+     which need not be stored with xemacs when we dump out an
+     executable. This is only done by `Fdump_emacs' or by
+     `Fdump_emacs_data' respectively (both in `emacs.c'). The actual
+     clearing is accomplished by making these objects unreachable and
+     starting a garbage collection. The function is only used while
+     building xemacs.
+
+  3. In function `Feval / eval' in file `eval.c'. Each time the well
+     known and often used function eval is called to evaluate a form,
+     one of the first things that could happen, is a potential call of
+     `garbage_collect_1'. There exist three global variables,
+     `consing_since_gc' (counts the created cons-cells since the last
+     garbage collection), `gc_cons_threshold' (a specified threshold
+     after which a garbage collection occurs) and `always_gc'. If
+     `always_gc' is set or if the threshold is exceeded, the garbage
+     collection will start.
+
+  4. In function `Ffuncall / funcall' in file `eval.c'. This function
+     evaluates calls of elisp functions and works according to `Feval'.
+
+   The upshot is that garbage collection can basically occur everywhere
+`Feval', respectively `Ffuncall', is used - either directly or through
+another function. Since calls to these two functions are hidden in
+various other functions, many calls to `garbage_collect_1' are not
+obviously foreseeable, and therefore unexpected. Instances where they
+are used that are worth remembering are various elisp commands, as for
+example `or', `and', `if', `cond', `while', `setq', etc., miscellaneous
+`gui_item_...' functions, everything related to `eval' (`Feval_buffer',
+`call0', ...) and inside `Fsignal'. The latter is used to handle
+signals, as for example the ones raised by every `QUIT'-macro triggered
+after pressing Ctrl-g.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-5'
Index: ././info/internals.info-5
--- ././info/internals.info-5	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-5	Thu May 17 23:26:54 2001
@@ -0,0 +1,1004 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: garbage_collect_1,  Next: mark_object,  Prev: Invocation,  Up: Garbage Collection - Step by Step
+
+`garbage_collect_1'
+-------------------
+
+   We can now describe exactly what happens after the invocation takes
+place.
+  1. There are several cases in which the garbage collector is left
+     immediately: when we are already garbage collecting
+     (`gc_in_progress'), when the garbage collection is somehow
+     forbidden (`gc_currently_forbidden'), when we are currently
+     displaying something (`in_display') or when we are preparing for
+     the armageddon of the whole system (`preparing_for_armageddon').
+
+  2. Next the correct frame in which to put all the output occurring
+     during garbage collecting is determined. In order to be able to
+     restore the old display's state after displaying the message, some
+     data about the current cursor position has to be saved. The
+     variables `pre_gc_cursor' and `cursor_changed' take care of that.
+
+  3. The state of `gc_currently_forbidden' must be restored after the
+     garbage collection, no matter what happens during the process. We
+     accomplish this by `record_unwind_protect'ing the suitable function
+     `restore_gc_inhibit' together with the current value of
+     `gc_currently_forbidden'.
+
+  4. If we are concurrently running an interactive xemacs session, the
+     next step is simply to show the garbage collector's cursor/message.
+
+  5. The following steps are the intrinsic steps of the garbage
+     collector, therefore `gc_in_progress' is set.
+
+  6. For debugging purposes, it is possible to copy the current C stack
+     frame. However, this seems to be a currently unused feature.
+
+  7. Before actually starting to go over all live objects, references to
+     objects that are no longer used are pruned. We only have to do
+     this for events (`clear_event_resource') and for specifiers
+     (`cleanup_specifiers').
+
+  8. Now the mark phase begins and marks all accessible elements. In
+     order to start from all slots that serve as roots of
+     accessibility, the function `mark_object' is called for each root
+     individually to go out from there to mark all reachable objects.
+     All roots that are traversed are shown in their processed order:
+        * all constant symbols and static variables that are registered
+          via `staticpro' in the dynarr `staticpros'.  *Note Adding
+          Global Lisp Variables::.
+
+        * all Lisp objects that are created in C functions and that
+          must be protected from freeing them. They are registered in
+          the global list `gcprolist'.  *Note GCPROing::.
+
+        * all local variables (i.e. their name fields `symbol' and old
+          values `old_values') that are bound during the evaluation by
+          the Lisp engine. They are stored in `specbinding' structs
+          pushed on a stack called `specpdl'.  *Note Dynamic Binding;
+          The specbinding Stack; Unwind-Protects::.
+
+        * all catch blocks that the Lisp engine encounters during the
+          evaluation cause the creation of structs `catchtag' inserted
+          in the list `catchlist'. Their tag (`tag') and value (`val'
+          fields are freshly created objects and therefore have to be
+          marked.  *Note Catch and Throw::.
+
+        * every function application pushes new structs `backtrace' on
+          the call stack of the Lisp engine (`backtrace_list'). The
+          unique parts that have to be marked are the fields for each
+          function (`function') and all their arguments (`args').
+          *Note Evaluation::.
+
+        * all objects that are used by the redisplay engine that must
+          not be freed are marked by a special function called
+          `mark_redisplay' (in `redisplay.c').
+
+        * all objects created for profiling purposes are allocated by C
+          functions instead of using the lisp allocation mechanisms. In
+          order to receive the right ones during the sweep phase, they
+          also have to be marked manually. That is done by the function
+          `mark_profiling_info'
+
+  9. Hash tables in XEmacs belong to a kind of special objects that
+     make use of a concept often called 'weak pointers'.  To make a
+     long story short, these kind of pointers are not followed during
+     the estimation of the live objects during garbage collection.  Any
+     object referenced only by weak pointers is collected anyway, and
+     the reference to it is cleared. In hash tables there are different
+     usage patterns of them, manifesting in different types of hash
+     tables, namely 'non-weak', 'weak', 'key-weak' and 'value-weak'
+     (internally also 'key-car-weak' and 'value-car-weak') hash tables,
+     each clearing entries depending on different conditions. More
+     information can be found in the documentation to the function
+     `make-hash-table'.
+
+     Because there are complicated dependency rules about when and what
+     to mark while processing weak hash tables, the standard `marker'
+     method is only active if it is marking non-weak hash tables. As
+     soon as a weak component is in the table, the hash table entries
+     are ignored while marking. Instead their marking is done each
+     separately by the function `finish_marking_weak_hash_tables'. This
+     function iterates over each hash table entry `hentries' for each
+     weak hash table in `Vall_weak_hash_tables'. Depending on the type
+     of a table, the appropriate action is performed.  If a table is
+     acting as `HASH_TABLE_KEY_WEAK', and a key already marked,
+     everything reachable from the `value' component is marked. If it is
+     acting as a `HASH_TABLE_VALUE_WEAK' and the value component is
+     already marked, the marking starts beginning only from the `key'
+     component.  If it is a `HASH_TABLE_KEY_CAR_WEAK' and the car of
+     the key entry is already marked, we mark both the `key' and
+     `value' components.  Finally, if the table is of the type
+     `HASH_TABLE_VALUE_CAR_WEAK' and the car of the value components is
+     already marked, again both the `key' and the `value' components
+     get marked.
+
+     Again, there are lists with comparable properties called weak
+     lists. There exist different peculiarities of their types called
+     `simple', `assoc', `key-assoc' and `value-assoc'. You can find
+     further details about them in the description to the function
+     `make-weak-list'. The scheme of their marking is similar: all weak
+     lists are listed in `Qall_weak_lists', therefore we iterate over
+     them. The marking is advanced until we hit an already marked pair.
+     Then we know that during a former run all the rest has been marked
+     completely. Again, depending on the special type of the weak list,
+     our jobs differ. If it is a `WEAK_LIST_SIMPLE' and the elem is
+     marked, we mark the `cons' part. If it is a `WEAK_LIST_ASSOC' and
+     not a pair or a pair with both marked car and cdr, we mark the
+     `cons' and the `elem'. If it is a `WEAK_LIST_KEY_ASSOC' and not a
+     pair or a pair with a marked car of the elem, we mark the `cons'
+     and the `elem'. Finally, if it is a `WEAK_LIST_VALUE_ASSOC' and
+     not a pair or a pair with a marked cdr of the elem, we mark both
+     the `cons' and the `elem'.
+
+     Since, by marking objects in reach from weak hash tables and weak
+     lists, other objects could get marked, this perhaps implies
+     further marking of other weak objects, both finishing functions
+     are redone as long as yet unmarked objects get freshly marked.
+
+ 10. After completing the special marking for the weak hash tables and
+     for the weak lists, all entries that point to objects that are
+     going to be swept in the further process are useless, and
+     therefore have to be removed from the table or the list.
+
+     The function `prune_weak_hash_tables' does the job for weak hash
+     tables. Totally unmarked hash tables are removed from the list
+     `Vall_weak_hash_tables'. The other ones are treated more carefully
+     by scanning over all entries and removing one as soon as one of
+     the components `key' and `value' is unmarked.
+
+     The same idea applies to the weak lists. It is accomplished by
+     `prune_weak_lists': An unmarked list is pruned from
+     `Vall_weak_lists' immediately. A marked list is treated more
+     carefully by going over it and removing just the unmarked pairs.
+
+ 11. The function `prune_specifiers' checks all listed specifiers held
+     in `Vall_specifiers' and removes the ones from the lists that are
+     unmarked.
+
+ 12. All syntax tables are stored in a list called
+     `Vall_syntax_tables'. The function `prune_syntax_tables' walks
+     through it and unlinks the tables that are unmarked.
+
+ 13. Next, we will attack the complete sweeping - the function
+     `gc_sweep' which holds the predominance.
+
+ 14. First, all the variables with respect to garbage collection are
+     reset. `consing_since_gc' - the counter of the created cells since
+     the last garbage collection - is set back to 0, and
+     `gc_in_progress' is not `true' anymore.
+
+ 15. In case the session is interactive, the displayed cursor and
+     message are removed again.
+
+ 16. The state of `gc_inhibit' is restored to the former value by
+     unwinding the stack.
+
+ 17. A small memory reserve is always held back that can be reached by
+     `breathing_space'. If nothing more is left, we create a new reserve
+     and exit.
+
+
+File: internals.info,  Node: mark_object,  Next: gc_sweep,  Prev: garbage_collect_1,  Up: Garbage Collection - Step by Step
+
+`mark_object'
+-------------
+
+   The first thing that is checked while marking an object is whether
+the object is a real Lisp object `Lisp_Type_Record' or just an integer
+or a character. Integers and characters are the only two types that are
+stored directly - without another level of indirection, and therefore
+they don't have to be marked and collected.  *Note How Lisp Objects Are
+Represented in C::.
+
+   The second case is the one we have to handle. It is the one when we
+are dealing with a pointer to a Lisp object. But, there exist also three
+possibilities, that prevent us from doing anything while marking: The
+object is read only which prevents it from being garbage collected,
+i.e. marked (`C_READONLY_RECORD_HEADER'). The object in question is
+already marked, and need not be marked for the second time (checked by
+`MARKED_RECORD_HEADER_P'). If it is a special, unmarkable object
+(`UNMARKABLE_RECORD_HEADER_P', apparently, these are objects that sit
+in some const space, and can therefore not be marked, see
+`this_one_is_unmarkable' in `alloc.c').
+
+   Now, the actual marking is feasible. We do so by once using the macro
+`MARK_RECORD_HEADER' to mark the object itself (actually the special
+flag in the lrecord header), and calling its special marker "method"
+`marker' if available. The marker method marks every other object that
+is in reach from our current object. Note, that these marker methods
+should not call `mark_object' recursively, but instead should return
+the next object from where further marking has to be performed.
+
+   In case another object was returned, as mentioned before, we
+reiterate the whole `mark_object' process beginning with this next
+object.
+
+
+File: internals.info,  Node: gc_sweep,  Next: sweep_lcrecords_1,  Prev: mark_object,  Up: Garbage Collection - Step by Step
+
+`gc_sweep'
+----------
+
+   The job of this function is to free all unmarked records from
+memory. As we know, there are different types of objects implemented
+and managed, and consequently different ways to free them from memory.
+*Note Introduction to Allocation::.
+
+   We start with all objects stored through `lcrecords'. All bulkier
+objects are allocated and handled using that scheme of `lcrecords'.
+Each object is `malloc'ed separately instead of placing it in one of
+the contiguous frob blocks. All types that are currently stored using
+`lcrecords''s  `alloc_lcrecord' and `make_lcrecord_list' are the types:
+vectors, buffers, char-table, char-table-entry, console, weak-list,
+database, device, ldap, hash-table, command-builder, extent-auxiliary,
+extent-info, face, coding-system, frame, image-instance, glyph,
+popup-data, gui-item, keymap, charset, color_instance, font_instance,
+opaque, opaque-list, process, range-table, specifier,
+symbol-value-buffer-local, symbol-value-lisp-magic,
+symbol-value-varalias, toolbar-button, tooltalk-message,
+tooltalk-pattern, window, and window-configuration. We take care of
+them in the fist place in order to be able to handle and to finalize
+items stored in them more easily. The function `sweep_lcrecords_1' as
+described below is doing the whole job for us.  For a description about
+the internals: *Note lrecords::.
+
+   Our next candidates are the other objects that behave quite
+differently than everything else: the strings. They consists of two
+parts, a fixed-size portion (`struct Lisp_String') holding the string's
+length, its property list and a pointer to the second part, and the
+actual string data, which is stored in string-chars blocks comparable to
+frob blocks. In this block, the data is not only freed, but also a
+compression of holes is made, i.e. all strings are relocated together.
+*Note String::. This compacting phase is performed by the function
+`compact_string_chars', the actual sweeping by the function
+`sweep_strings' is described below.
+
+   After that, the other types are swept step by step using functions
+`sweep_conses', `sweep_bit_vectors_1', `sweep_compiled_functions',
+`sweep_floats', `sweep_symbols', `sweep_extents', `sweep_markers' and
+`sweep_extents'.  They are the fixed-size types cons, floats,
+compiled-functions, symbol, marker, extent, and event stored in
+so-called "frob blocks", and therefore we can basically do the same on
+every type objects, using the same macros, especially defined only to
+handle everything with respect to fixed-size blocks. The only fixed-size
+type that is not handled here are the fixed-size portion of strings,
+because we took special care of them earlier.
+
+   The only big exceptions are bit vectors stored differently and
+therefore treated differently by the function `sweep_bit_vectors_1'
+described later.
+
+   At first, we need some brief information about how these fixed-size
+types are managed in general, in order to understand how the sweeping
+is done. They have all a fixed size, and are therefore stored in big
+blocks of memory - allocated at once - that can hold a certain amount
+of objects of one type. The macro `DECLARE_FIXED_TYPE_ALLOC' creates
+the suitable structures for every type. More precisely, we have the
+block struct (holding a pointer to the previous block `prev' and the
+objects in `block[]'), a pointer to current block
+(`current_..._block)') and its last index (`current_..._block_index'),
+and a pointer to the free list that will be created. Also a macro
+`FIXED_TYPE_FROM_BLOCK' plus some related macros exists that are used
+to obtain a new object, either from the free list
+`ALLOCATE_FIXED_TYPE_1' if there is an unused object of that type
+stored or by allocating a completely new block using
+`ALLOCATE_FIXED_TYPE_FROM_BLOCK'.
+
+   The rest works as follows: all of them define a macro `UNMARK_...'
+that is used to unmark the object. They define a macro
+`ADDITIONAL_FREE_...' that defines additional work that has to be done
+when converting an object from in use to not in use (so far, only
+markers use it in order to unchain them). Then, they all call the macro
+`SWEEP_FIXED_TYPE_BLOCK' instantiated with their type name and their
+struct name.
+
+   This call in particular does the following: we go over all blocks
+starting with the current moving towards the oldest.  For each block,
+we look at every object in it. If the object already freed (checked
+with `FREE_STRUCT_P' using the first pointer of the object), or if it is
+set to read only (`C_READONLY_RECORD_HEADER_P', nothing must be done.
+If it is unmarked (checked with `MARKED_RECORD_HEADER_P'), it is put in
+the free list and set free (using the macro `FREE_FIXED_TYPE',
+otherwise it stays in the block, but is unmarked (by `UNMARK_...').
+While going through one block, we note if the whole block is empty. If
+so, the whole block is freed (using `xfree') and the free list state is
+set to the state it had before handling this block.
+
+
+File: internals.info,  Node: sweep_lcrecords_1,  Next: compact_string_chars,  Prev: gc_sweep,  Up: Garbage Collection - Step by Step
+
+`sweep_lcrecords_1'
+-------------------
+
+   After nullifying the complete lcrecord statistics, we go over all
+lcrecords two separate times. They are all chained together in a list
+with a head called `all_lcrecords'.
+
+   The first loop calls for each object its `finalizer' method, but only
+in the case that it is not read only (`C_READONLY_RECORD_HEADER_P)', it
+is not already marked (`MARKED_RECORD_HEADER_P'), it is not already in
+a free list (list of freed objects, field `free') and finally it owns a
+finalizer method.
+
+   The second loop actually frees the appropriate objects again by
+iterating through the whole list. In case an object is read only or
+marked, it has to persist, otherwise it is manually freed by calling
+`xfree'. During this loop, the lcrecord statistics are kept up to date
+by calling `tick_lcrecord_stats' with the right arguments,
+
+
+File: internals.info,  Node: compact_string_chars,  Next: sweep_strings,  Prev: sweep_lcrecords_1,  Up: Garbage Collection - Step by Step
+
+`compact_string_chars'
+----------------------
+
+   The purpose of this function is to compact all the data parts of the
+strings that are held in so-called `string_chars_block', i.e. the
+strings that do not exceed a certain maximal length.
+
+   The procedure with which this is done is as follows. We are keeping
+two positions in the `string_chars_block's using two pointer/integer
+pairs, namely `from_sb'/`from_pos' and `to_sb'/`to_pos'. They stand for
+the actual positions, from where to where, to copy the actually handled
+string.
+
+   While going over all chained `string_char_block's and their held
+strings, staring at `first_string_chars_block', both pointers are
+advanced and eventually a string is copied from `from_sb' to `to_sb',
+depending on the status of the pointed at strings.
+
+   More precisely, we can distinguish between the following actions.
+   * The string at `from_sb''s position could be marked as free, which
+     is indicated by an invalid pointer to the pointer that should
+     point back to the fixed size string object, and which is checked by
+     `FREE_STRUCT_P'. In this case, the `from_sb'/`from_pos' is
+     advanced to the next string, and nothing has to be copied.
+
+   * Also, if a string object itself is unmarked, nothing has to be
+     copied. We likewise advance the `from_sb'/`from_pos' pair as
+     described above.
+
+   * In all other cases, we have a marked string at hand. The string
+     data must be moved from the from-position to the to-position. In
+     case there is not enough space in the actual `to_sb'-block, we
+     advance this pointer to the beginning of the next block before
+     copying. In case the from and to positions are different, we
+     perform the actual copying using the library function `memmove'.
+
+   After compacting, the pointer to the current `string_chars_block',
+sitting in `current_string_chars_block', is reset on the last block to
+which we moved a string, i.e. `to_block', and all remaining blocks (we
+know that they just carry garbage) are explicitly `xfree'd.
+
+
+File: internals.info,  Node: sweep_strings,  Next: sweep_bit_vectors_1,  Prev: compact_string_chars,  Up: Garbage Collection - Step by Step
+
+`sweep_strings'
+---------------
+
+   The sweeping for the fixed sized string objects is essentially
+exactly the same as it is for all other fixed size types. As before,
+the freeing into the suitable free list is done by using the macro
+`SWEEP_FIXED_SIZE_BLOCK' after defining the right macros
+`UNMARK_string' and `ADDITIONAL_FREE_string'. These two definitions are
+a little bit special compared to the ones used for the other fixed size
+types.
+
+   `UNMARK_string' is defined the same way except some additional code
+used for updating the bookkeeping information.
+
+   For strings, `ADDITIONAL_FREE_string' has to do something in
+addition: in case, the string was not allocated in a
+`string_chars_block' because it exceeded the maximal length, and
+therefore it was `malloc'ed separately, we know also `xfree' it
+explicitly.
+
+
+File: internals.info,  Node: sweep_bit_vectors_1,  Prev: sweep_strings,  Up: Garbage Collection - Step by Step
+
+`sweep_bit_vectors_1'
+---------------------
+
+   Bit vectors are also one of the rare types that are `malloc'ed
+individually. Consequently, while sweeping, all further needless bit
+vectors must be freed by hand. This is done, as one might imagine, the
+expected way: since they are all registered in a list called
+`all_bit_vectors', all elements of that list are traversed, all
+unmarked bit vectors are unlinked by calling `xfree' and all of them
+become unmarked.  In addition, the bookkeeping information used for
+garbage collector's output purposes is updated.
+
+
+File: internals.info,  Node: Integers and Characters,  Next: Allocation from Frob Blocks,  Prev: Garbage Collection - Step by Step,  Up: Allocation of Objects in XEmacs Lisp
+
+Integers and Characters
+=======================
+
+   Integer and character Lisp objects are created from integers using
+the macros `XSETINT()' and `XSETCHAR()' or the equivalent functions
+`make_int()' and `make_char()'. (These are actually macros on most
+systems.)  These functions basically just do some moving of bits
+around, since the integral value of the object is stored directly in
+the `Lisp_Object'.
+
+   `XSETINT()' and the like will truncate values given to them that are
+too big; i.e. you won't get the value you expected but the tag bits
+will at least be correct.
+
+
+File: internals.info,  Node: Allocation from Frob Blocks,  Next: lrecords,  Prev: Integers and Characters,  Up: Allocation of Objects in XEmacs Lisp
+
+Allocation from Frob Blocks
+===========================
+
+   The uninitialized memory required by a `Lisp_Object' of a particular
+type is allocated using `ALLOCATE_FIXED_TYPE()'.  This only occurs
+inside of the lowest-level object-creating functions in `alloc.c':
+`Fcons()', `make_float()', `Fmake_byte_code()', `Fmake_symbol()',
+`allocate_extent()', `allocate_event()', `Fmake_marker()', and
+`make_uninit_string()'.  The idea is that, for each type, there are a
+number of frob blocks (each 2K in size); each frob block is divided up
+into object-sized chunks.  Each frob block will have some of these
+chunks that are currently assigned to objects, and perhaps some that are
+free. (If a frob block has nothing but free chunks, it is freed at the
+end of the garbage collection cycle.)  The free chunks are stored in a
+free list, which is chained by storing a pointer in the first four bytes
+of the chunk. (Except for the free chunks at the end of the last frob
+block, which are handled using an index which points past the end of the
+last-allocated chunk in the last frob block.)  `ALLOCATE_FIXED_TYPE()'
+first tries to retrieve a chunk from the free list; if that fails, it
+calls `ALLOCATE_FIXED_TYPE_FROM_BLOCK()', which looks at the end of the
+last frob block for space, and creates a new frob block if there is
+none. (There are actually two versions of these macros, one of which is
+more defensive but less efficient and is used for error-checking.)
+
+
+File: internals.info,  Node: lrecords,  Next: Low-level allocation,  Prev: Allocation from Frob Blocks,  Up: Allocation of Objects in XEmacs Lisp
+
+lrecords
+========
+
+   [see `lrecord.h']
+
+   All lrecords have at the beginning of their structure a `struct
+lrecord_header'.  This just contains a type number and some flags,
+including the mark bit.  All builtin type numbers are defined as
+constants in `enum lrecord_type', to allow the compiler to generate
+more efficient code for `TYPEP'.  The type number, thru the
+`lrecord_implementation_table', gives access to a `struct
+lrecord_implementation', which is a structure containing method pointers
+and such.  There is one of these for each type, and it is a global,
+constant, statically-declared structure that is declared in the
+`DEFINE_LRECORD_IMPLEMENTATION()' macro.
+
+   Simple lrecords (of type (b) above) just have a `struct
+lrecord_header' at their beginning.  lcrecords, however, actually have a
+`struct lcrecord_header'.  This, in turn, has a `struct lrecord_header'
+at its beginning, so sanity is preserved; but it also has a pointer
+used to chain all lcrecords together, and a special ID field used to
+distinguish one lcrecord from another. (This field is used only for
+debugging and could be removed, but the space gain is not significant.)
+
+   Simple lrecords are created using `ALLOCATE_FIXED_TYPE()', just like
+for other frob blocks.  The only change is that the implementation
+pointer must be initialized correctly. (The implementation structure for
+an lrecord, or rather the pointer to it, is named `lrecord_float',
+`lrecord_extent', `lrecord_buffer', etc.)
+
+   lcrecords are created using `alloc_lcrecord()'.  This takes a size
+to allocate and an implementation pointer. (The size needs to be passed
+because some lcrecords, such as window configurations, are of variable
+size.) This basically just `malloc()'s the storage, initializes the
+`struct lcrecord_header', and chains the lcrecord onto the head of the
+list of all lcrecords, which is stored in the variable `all_lcrecords'.
+The calls to `alloc_lcrecord()' generally occur in the lowest-level
+allocation function for each lrecord type.
+
+   Whenever you create an lrecord, you need to call either
+`DEFINE_LRECORD_IMPLEMENTATION()' or
+`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()'.  This needs to be specified
+in a `.c' file, at the top level.  What this actually does is define
+and initialize the implementation structure for the lrecord. (And
+possibly declares a function `error_check_foo()' that implements the
+`XFOO()' macro when error-checking is enabled.)  The arguments to the
+macros are the actual type name (this is used to construct the C
+variable name of the lrecord implementation structure and related
+structures using the `##' macro concatenation operator), a string that
+names the type on the Lisp level (this may not be the same as the C
+type name; typically, the C type name has underscores, while the Lisp
+string has dashes), various method pointers, and the name of the C
+structure that contains the object.  The methods are used to
+encapsulate type-specific information about the object, such as how to
+print it or mark it for garbage collection, so that it's easy to add
+new object types without having to add a specific case for each new
+type in a bunch of different places.
+
+   The difference between `DEFINE_LRECORD_IMPLEMENTATION()' and
+`DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION()' is that the former is used
+for fixed-size object types and the latter is for variable-size object
+types.  Most object types are fixed-size; some complex types, however
+(e.g. window configurations), are variable-size.  Variable-size object
+types have an extra method, which is called to determine the actual
+size of a particular object of that type.  (Currently this is only used
+for keeping allocation statistics.)
+
+   For the purpose of keeping allocation statistics, the allocation
+engine keeps a list of all the different types that exist.  Note that,
+since `DEFINE_LRECORD_IMPLEMENTATION()' is a macro that is specified at
+top-level, there is no way for it to initialize the global data
+structures containing type information, like
+`lrecord_implementations_table'.  For this reason a call to
+`INIT_LRECORD_IMPLEMENTATION' must be added to the same source file
+containing `DEFINE_LRECORD_IMPLEMENTATION', but instead of to the top
+level, to one of the init functions, typically `syms_of_FOO.c'.
+`INIT_LRECORD_IMPLEMENTATION' must be called before an object of this
+type is used.
+
+   The type number is also used to index into an array holding the
+number of objects of each type and the total memory allocated for
+objects of that type.  The statistics in this array are computed during
+the sweep stage.  These statistics are returned by the call to
+`garbage-collect'.
+
+   Note that for every type defined with a `DEFINE_LRECORD_*()' macro,
+there needs to be a `DECLARE_LRECORD_IMPLEMENTATION()' somewhere in a
+`.h' file, and this `.h' file needs to be included by `inline.c'.
+
+   Furthermore, there should generally be a set of `XFOOBAR()',
+`FOOBARP()', etc. macros in a `.h' (or occasionally `.c') file.  To
+create one of these, copy an existing model and modify as necessary.
+
+   *Please note:* If you define an lrecord in an external
+dynamically-loaded module, you must use `DECLARE_EXTERNAL_LRECORD',
+`DEFINE_EXTERNAL_LRECORD_IMPLEMENTATION', and
+`DEFINE_EXTERNAL_LRECORD_SEQUENCE_IMPLEMENTATION' instead of the
+non-EXTERNAL forms. These macros will dynamically add new type numbers
+to the global enum that records them, whereas the non-EXTERNAL forms
+assume that the programmer has already inserted the correct type numbers
+into the enum's code at compile-time.
+
+   The various methods in the lrecord implementation structure are:
+
+  1. A "mark" method.  This is called during the marking stage and
+     passed a function pointer (usually the `mark_object()' function),
+     which is used to mark an object.  All Lisp objects that are
+     contained within the object need to be marked by applying this
+     function to them.  The mark method should also return a Lisp
+     object, which should be either `nil' or an object to mark. (This
+     can be used in lieu of calling `mark_object()' on the object, to
+     reduce the recursion depth, and consequently should be the most
+     heavily nested sub-object, such as a long list.)
+
+     *Please note:* When the mark method is called, garbage collection
+     is in progress, and special precautions need to be taken when
+     accessing objects; see section (B) above.
+
+     If your mark method does not need to do anything, it can be `NULL'.
+
+  2. A "print" method.  This is called to create a printed
+     representation of the object, whenever `princ', `prin1', or the
+     like is called.  It is passed the object, a stream to which the
+     output is to be directed, and an `escapeflag' which indicates
+     whether the object's printed representation should be "escaped" so
+     that it is readable. (This corresponds to the difference between
+     `princ' and `prin1'.) Basically, "escaped" means that strings will
+     have quotes around them and confusing characters in the strings
+     such as quotes, backslashes, and newlines will be backslashed; and
+     that special care will be taken to make symbols print in a
+     readable fashion (e.g. symbols that look like numbers will be
+     backslashed).  Other readable objects should perhaps pass
+     `escapeflag' on when sub-objects are printed, so that readability
+     is preserved when necessary (or if not, always pass in a 1 for
+     `escapeflag').  Non-readable objects should in general ignore
+     `escapeflag', except that some use it as an indication that more
+     verbose output should be given.
+
+     Sub-objects are printed using `print_internal()', which takes
+     exactly the same arguments as are passed to the print method.
+
+     Literal C strings should be printed using `write_c_string()', or
+     `write_string_1()' for non-null-terminated strings.
+
+     Functions that do not have a readable representation should check
+     the `print_readably' flag and signal an error if it is set.
+
+     If you specify NULL for the print method, the
+     `default_object_printer()' will be used.
+
+  3. A "finalize" method.  This is called at the beginning of the sweep
+     stage on lcrecords that are about to be freed, and should be used
+     to perform any extra object cleanup.  This typically involves
+     freeing any extra `malloc()'ed memory associated with the object,
+     releasing any operating-system and window-system resources
+     associated with the object (e.g. pixmaps, fonts), etc.
+
+     The finalize method can be NULL if nothing needs to be done.
+
+     WARNING #1: The finalize method is also called at the end of the
+     dump phase; this time with the for_disksave parameter set to
+     non-zero.  The object is _not_ about to disappear, so you have to
+     make sure to _not_ free any extra `malloc()'ed memory if you're
+     going to need it later.  (Also, signal an error if there are any
+     operating-system and window-system resources here, because they
+     can't be dumped.)
+
+     Finalize methods should, as a rule, set to zero any pointers after
+     they've been freed, and check to make sure pointers are not zero
+     before freeing.  Although I'm pretty sure that finalize methods
+     are not called twice on the same object (except for the
+     `for_disksave' proviso), we've gotten nastily burned in some cases
+     by not doing this.
+
+     WARNING #2: The finalize method is _only_ called for lcrecords,
+     _not_ for simply lrecords.  If you need a finalize method for
+     simple lrecords, you have to stick it in the
+     `ADDITIONAL_FREE_foo()' macro in `alloc.c'.
+
+     WARNING #3: Things are in an _extremely_ bizarre state when
+     `ADDITIONAL_FREE_foo()' is called, so you have to be incredibly
+     careful when writing one of these functions.  See the comment in
+     `gc_sweep()'.  If you ever have to add one of these, consider
+     using an lcrecord or dealing with the problem in a different
+     fashion.
+
+  4. An "equal" method.  This compares the two objects for similarity,
+     when `equal' is called.  It should compare the contents of the
+     objects in some reasonable fashion.  It is passed the two objects
+     and a "depth" value, which is used to catch circular objects.  To
+     compare sub-Lisp-objects, call `internal_equal()' and bump the
+     depth value by one.  If this value gets too high, a
+     `circular-object' error will be signaled.
+
+     If this is NULL, objects are `equal' only when they are `eq', i.e.
+     identical.
+
+  5. A "hash" method.  This is used to hash objects when they are to be
+     compared with `equal'.  The rule here is that if two objects are
+     `equal', they _must_ hash to the same value; i.e. your hash
+     function should use some subset of the sub-fields of the object
+     that are compared in the "equal" method.  If you specify this
+     method as `NULL', the object's pointer will be used as the hash,
+     which will _fail_ if the object has an `equal' method, so don't do
+     this.
+
+     To hash a sub-Lisp-object, call `internal_hash()'.  Bump the depth
+     by one, just like in the "equal" method.
+
+     To convert a Lisp object directly into a hash value (using its
+     pointer), use `LISP_HASH()'.  This is what happens when the hash
+     method is NULL.
+
+     To hash two or more values together into a single value, use
+     `HASH2()', `HASH3()', `HASH4()', etc.
+
+  6. "getprop", "putprop", "remprop", and "plist" methods.  These are
+     used for object types that have properties.  I don't feel like
+     documenting them here.  If you create one of these objects, you
+     have to use different macros to define them, i.e.
+     `DEFINE_LRECORD_IMPLEMENTATION_WITH_PROPS()' or
+     `DEFINE_LRECORD_SEQUENCE_IMPLEMENTATION_WITH_PROPS()'.
+
+  7. A "size_in_bytes" method, when the object is of variable-size.
+     (i.e. declared with a `_SEQUENCE_IMPLEMENTATION' macro.)  This
+     should simply return the object's size in bytes, exactly as you
+     might expect.  For an example, see the methods for window
+     configurations and opaques.
+
+
+File: internals.info,  Node: Low-level allocation,  Next: Cons,  Prev: lrecords,  Up: Allocation of Objects in XEmacs Lisp
+
+Low-level allocation
+====================
+
+   Memory that you want to allocate directly should be allocated using
+`xmalloc()' rather than `malloc()'.  This implements error-checking on
+the return value, and once upon a time did some more vital stuff (i.e.
+`BLOCK_INPUT', which is no longer necessary).  Free using `xfree()',
+and realloc using `xrealloc()'.  Note that `xmalloc()' will do a
+non-local exit if the memory can't be allocated. (Many functions,
+however, do not expect this, and thus XEmacs will likely crash if this
+happens.  *This is a bug.*  If you can, you should strive to make your
+function handle this OK.  However, it's difficult in the general
+circumstance, perhaps requiring extra unwind-protects and such.)
+
+   Note that XEmacs provides two separate replacements for the standard
+`malloc()' library function.  These are called "old GNU malloc"
+(`malloc.c') and "new GNU malloc" (`gmalloc.c'), respectively.  New GNU
+malloc is better in pretty much every way than old GNU malloc, and
+should be used if possible.  (It used to be that on some systems, the
+old one worked but the new one didn't.  I think this was due
+specifically to a bug in SunOS, which the new one now works around; so
+I don't think the old one ever has to be used any more.) The primary
+difference between both of these mallocs and the standard system malloc
+is that they are much faster, at the expense of increased space.  The
+basic idea is that memory is allocated in fixed chunks of powers of
+two.  This allows for basically constant malloc time, since the various
+chunks can just be kept on a number of free lists. (The standard system
+malloc typically allocates arbitrary-sized chunks and has to spend some
+time, sometimes a significant amount of time, walking the heap looking
+for a free block to use and cleaning things up.)  The new GNU malloc
+improves on things by allocating large objects in chunks of 4096 bytes
+rather than in ever larger powers of two, which results in ever larger
+wastage.  There is a slight speed loss here, but it's of doubtful
+significance.
+
+   NOTE: Apparently there is a third-generation GNU malloc that is
+significantly better than the new GNU malloc, and should probably be
+included in XEmacs.
+
+   There is also the relocating allocator, `ralloc.c'.  This actually
+moves blocks of memory around so that the `sbrk()' pointer shrunk and
+virtual memory released back to the system.  On some systems, this is a
+big win.  On all systems, it causes a noticeable (and sometimes huge)
+speed penalty, so I turn it off by default.  `ralloc.c' only works with
+the new GNU malloc in `gmalloc.c'.  There are also two versions of
+`ralloc.c', one that uses `mmap()' rather than block copies to move
+data around.  This purports to be faster, although that depends on the
+amount of data that would have had to be block copied and the
+system-call overhead for `mmap()'.  I don't know exactly how this
+works, except that the relocating-allocation routines are pretty much
+used only for the memory allocated for a buffer, which is the biggest
+consumer of space, esp. of space that may get freed later.
+
+   Note that the GNU mallocs have some "memory warning" facilities.
+XEmacs taps into them and issues a warning through the standard warning
+system, when memory gets to 75%, 85%, and 95% full.  (On some systems,
+the memory warnings are not functional.)
+
+   Allocated memory that is going to be used to make a Lisp object is
+created using `allocate_lisp_storage()'.  This just calls `xmalloc()'.
+It used to verify that the pointer to the memory can fit into a Lisp
+word, before the current Lisp object representation was introduced.
+`allocate_lisp_storage()' is called by `alloc_lcrecord()',
+`ALLOCATE_FIXED_TYPE()', and the vector and bit-vector creation
+routines.  These routines also call `INCREMENT_CONS_COUNTER()' at the
+appropriate times; this keeps statistics on how much memory is
+allocated, so that garbage-collection can be invoked when the threshold
+is reached.
+
+
+File: internals.info,  Node: Cons,  Next: Vector,  Prev: Low-level allocation,  Up: Allocation of Objects in XEmacs Lisp
+
+Cons
+====
+
+   Conses are allocated in standard frob blocks.  The only thing to
+note is that conses can be explicitly freed using `free_cons()' and
+associated functions `free_list()' and `free_alist()'.  This
+immediately puts the conses onto the cons free list, and decrements the
+statistics on memory allocation appropriately.  This is used to good
+effect by some extremely commonly-used code, to avoid generating extra
+objects and thereby triggering GC sooner.  However, you have to be
+_extremely_ careful when doing this.  If you mess this up, you will get
+BADLY BURNED, and it has happened before.
+
+
+File: internals.info,  Node: Vector,  Next: Bit Vector,  Prev: Cons,  Up: Allocation of Objects in XEmacs Lisp
+
+Vector
+======
+
+   As mentioned above, each vector is `malloc()'ed individually, and
+all are threaded through the variable `all_vectors'.  Vectors are
+marked strangely during garbage collection, by kludging the size field.
+Note that the `struct Lisp_Vector' is declared with its `contents'
+field being a _stretchy_ array of one element.  It is actually
+`malloc()'ed with the right size, however, and access to any element
+through the `contents' array works fine.
+
+
+File: internals.info,  Node: Bit Vector,  Next: Symbol,  Prev: Vector,  Up: Allocation of Objects in XEmacs Lisp
+
+Bit Vector
+==========
+
+   Bit vectors work exactly like vectors, except for more complicated
+code to access an individual bit, and except for the fact that bit
+vectors are lrecords while vectors are not. (The only difference here is
+that there's an lrecord implementation pointer at the beginning and the
+tag field in bit vector Lisp words is "lrecord" rather than "vector".)
+
+
+File: internals.info,  Node: Symbol,  Next: Marker,  Prev: Bit Vector,  Up: Allocation of Objects in XEmacs Lisp
+
+Symbol
+======
+
+   Symbols are also allocated in frob blocks.  Symbols in the awful
+horrible obarray structure are chained through their `next' field.
+
+   Remember that `intern' looks up a symbol in an obarray, creating one
+if necessary.
+
+
+File: internals.info,  Node: Marker,  Next: String,  Prev: Symbol,  Up: Allocation of Objects in XEmacs Lisp
+
+Marker
+======
+
+   Markers are allocated in frob blocks, as usual.  They are kept in a
+buffer unordered, but in a doubly-linked list so that they can easily
+be removed. (Formerly this was a singly-linked list, but in some cases
+garbage collection took an extraordinarily long time due to the O(N^2)
+time required to remove lots of markers from a buffer.) Markers are
+removed from a buffer in the finalize stage, in
+`ADDITIONAL_FREE_marker()'.
+
+
+File: internals.info,  Node: String,  Next: Compiled Function,  Prev: Marker,  Up: Allocation of Objects in XEmacs Lisp
+
+String
+======
+
+   As mentioned above, strings are a special case.  A string is
+logically two parts, a fixed-size object (containing the length,
+property list, and a pointer to the actual data), and the actual data
+in the string.  The fixed-size object is a `struct Lisp_String' and is
+allocated in frob blocks, as usual.  The actual data is stored in
+special "string-chars blocks", which are 8K blocks of memory.
+Currently-allocated strings are simply laid end to end in these
+string-chars blocks, with a pointer back to the `struct Lisp_String'
+stored before each string in the string-chars block.  When a new string
+needs to be allocated, the remaining space at the end of the last
+string-chars block is used if there's enough, and a new string-chars
+block is created otherwise.
+
+   There are never any holes in the string-chars blocks due to the
+string compaction and relocation that happens at the end of garbage
+collection.  During the sweep stage of garbage collection, when objects
+are reclaimed, the garbage collector goes through all string-chars
+blocks, looking for unused strings.  Each chunk of string data is
+preceded by a pointer to the corresponding `struct Lisp_String', which
+indicates both whether the string is used and how big the string is,
+i.e. how to get to the next chunk of string data.  Holes are compressed
+by block-copying the next string into the empty space and relocating the
+pointer stored in the corresponding `struct Lisp_String'.  *This means
+you have to be careful with strings in your code.* See the section
+above on `GCPRO'ing.
+
+   Note that there is one situation not handled: a string that is too
+big to fit into a string-chars block.  Such strings, called "big
+strings", are all `malloc()'ed as their own block. (#### Although it
+would make more sense for the threshold for big strings to be somewhat
+lower, e.g. 1/2 or 1/4 the size of a string-chars block.  It seems that
+this was indeed the case formerly--indeed, the threshold was set at
+1/8--but Mly forgot about this when rewriting things for 19.8.)
+
+   Note also that the string data in string-chars blocks is padded as
+necessary so that proper alignment constraints on the `struct
+Lisp_String' back pointers are maintained.
+
+   Finally, strings can be resized.  This happens in Mule when a
+character is substituted with a different-length character, or during
+modeline frobbing. (You could also export this to Lisp, but it's not
+done so currently.) Resizing a string is a potentially tricky process.
+If the change is small enough that the padding can absorb it, nothing
+other than a simple memory move needs to be done.  Keep in mind,
+however, that the string can't shrink too much because the offset to the
+next string in the string-chars block is computed by looking at the
+length and rounding to the nearest multiple of four or eight.  If the
+string would shrink or expand beyond the correct padding, new string
+data needs to be allocated at the end of the last string-chars block and
+the data moved appropriately.  This leaves some dead string data, which
+is marked by putting a special marker of 0xFFFFFFFF in the `struct
+Lisp_String' pointer before the data (there's no real `struct
+Lisp_String' to point to and relocate), and storing the size of the dead
+string data (which would normally be obtained from the now-non-existent
+`struct Lisp_String') at the beginning of the dead string data gap.
+The string compactor recognizes this special 0xFFFFFFFF marker and
+handles it correctly.
+
+
+File: internals.info,  Node: Compiled Function,  Prev: String,  Up: Allocation of Objects in XEmacs Lisp
+
+Compiled Function
+=================
+
+   Not yet documented.
+
+
+File: internals.info,  Node: Dumping,  Next: Events and the Event Loop,  Prev: Allocation of Objects in XEmacs Lisp,  Up: Top
+
+Dumping
+*******
+
+What is dumping and its justification
+=====================================
+
+   The C code of XEmacs is just a Lisp engine with a lot of built-in
+primitives useful for writing an editor.  The editor itself is written
+mostly in Lisp, and represents around 100K lines of code.  Loading and
+executing the initialization of all this code takes a bit a time (five
+to ten times the usual startup time of current xemacs) and requires
+having all the lisp source files around.  Having to reload them each
+time the editor is started would not be acceptable.
+
+   The traditional solution to this problem is called dumping: the build
+process first creates the lisp engine under the name `temacs', then
+runs it until it has finished loading and initializing all the lisp
+code, and eventually creates a new executable called `xemacs' including
+both the object code in `temacs' and all the contents of the memory
+after the initialization.
+
+   This solution, while working, has a huge problem: the creation of the
+new executable from the actual contents of memory is an extremely
+system-specific process, quite error-prone, and which interferes with a
+lot of system libraries (like malloc).  It is even getting worse
+nowadays with libraries using constructors which are automatically
+called when the program is started (even before main()) which tend to
+crash when they are called multiple times, once before dumping and once
+after (IRIX 6.x libz.so pulls in some C++ image libraries thru
+dependencies which have this problem).  Writing the dumper is also one
+of the most difficult parts of porting XEmacs to a new operating system.
+Basically, `dumping' is an operation that is just not officially
+supported on many operating systems.
+
+   The aim of the portable dumper is to solve the same problem as the
+system-specific dumper, that is to be able to reload quickly, using only
+a small number of files, the fully initialized lisp part of the editor,
+without any system-specific hacks.
+
+* Menu:
+
+* Overview::
+* Data descriptions::
+* Dumping phase::
+* Reloading phase::
+* Remaining issues::
+
+
+File: internals.info,  Node: Overview,  Next: Data descriptions,  Up: Dumping
+
+Overview
+========
+
+   The portable dumping system has to:
+
+  1. At dump time, write all initialized, non-quickly-rebuildable data
+     to a file [Note: currently named `xemacs.dmp', but the name will
+     change], along with all informations needed for the reloading.
+
+  2. When starting xemacs, reload the dump file, relocate it to its new
+     starting address if needed, and reinitialize all pointers to this
+     data.  Also, rebuild all the quickly rebuildable data.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-6'
Index: ././info/internals.info-6
--- ././info/internals.info-6	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-6	Thu May 17 23:26:54 2001
@@ -0,0 +1,1058 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Data descriptions,  Next: Dumping phase,  Prev: Overview,  Up: Dumping
+
+Data descriptions
+=================
+
+   The more complex task of the dumper is to be able to write lisp
+objects (lrecords) and C structs to disk and reload them at a different
+address, updating all the pointers they include in the process.  This
+is done by using external data descriptions that give information about
+the layout of the structures in memory.
+
+   The specification of these descriptions is in lrecord.h.  A
+description of an lrecord is an array of struct lrecord_description.
+Each of these structs include a type, an offset in the structure and
+some optional parameters depending on the type.  For instance, here is
+the string description:
+
+     static const struct lrecord_description string_description[] = {
+       { XD_BYTECOUNT,         offsetof (Lisp_String, size) },
+       { XD_OPAQUE_DATA_PTR,   offsetof (Lisp_String, data), XD_INDIRECT(0, 1) },
+       { XD_LISP_OBJECT,       offsetof (Lisp_String, plist) },
+       { XD_END }
+     };
+
+   The first line indicates a member of type Bytecount, which is used by
+the next, indirect directive.  The second means "there is a pointer to
+some opaque data in the field `data'".  The length of said data is
+given by the expression `XD_INDIRECT(0, 1)', which means "the value in
+the 0th line of the description (welcome to C) plus one".  The third
+line means "there is a Lisp_Object member `plist' in the Lisp_String
+structure".  `XD_END' then ends the description.
+
+   This gives us all the information we need to move around what is
+pointed to by a structure (C or lrecord) and, by transitivity,
+everything that it points to.  The only missing information for dumping
+is the size of the structure.  For lrecords, this is part of the
+lrecord_implementation, so we don't need to duplicate it.  For C
+structures we use a struct struct_description, which includes a size
+field and a pointer to an associated array of lrecord_description.
+
+
+File: internals.info,  Node: Dumping phase,  Next: Reloading phase,  Prev: Data descriptions,  Up: Dumping
+
+Dumping phase
+=============
+
+   Dumping is done by calling the function pdump() (in dumper.c) which
+is invoked from Fdump_emacs (in emacs.c).  This function performs a
+number of tasks.
+
+* Menu:
+
+* Object inventory::
+* Address allocation::
+* The header::
+* Data dumping::
+* Pointers dumping::
+
+
+File: internals.info,  Node: Object inventory,  Next: Address allocation,  Up: Dumping phase
+
+Object inventory
+----------------
+
+   The first task is to build the list of the objects to dump.  This
+includes:
+
+   * lisp objects
+
+   * C structures
+
+   We end up with one `pdump_entry_list_elmt' per object group (arrays
+of C structs are kept together) which includes a pointer to the first
+object of the group, the per-object size and the count of objects in the
+group, along with some other information which is initialized later.
+
+   These entries are linked together in `pdump_entry_list' structures
+and can be enumerated thru either:
+
+  1. the `pdump_object_table', an array of `pdump_entry_list', one per
+     lrecord type, indexed by type number.
+
+  2. the `pdump_opaque_data_list', used for the opaque data which does
+     not include pointers, and hence does not need descriptions.
+
+  3. the `pdump_struct_table', which is a vector of
+     `struct_description'/`pdump_entry_list' pairs, used for non-opaque
+     C structures.
+
+   This uses a marking strategy similar to the garbage collector.  Some
+differences though:
+
+  1. We do not use the mark bit (which does not exist for C structures
+     anyway); we use a big hash table instead.
+
+  2. We do not use the mark function of lrecords but instead rely on the
+     external descriptions.  This happens essentially because we need to
+     follow pointers to C structures and opaque data in addition to
+     Lisp_Object members.
+
+   This is done by `pdump_register_object()', which handles Lisp_Object
+variables, and `pdump_register_struct()' which handles C structures,
+which both delegate the description management to
+`pdump_register_sub()'.
+
+   The hash table doubles as a map object to pdump_entry_list_elmt (i.e.
+allows us to look up a pdump_entry_list_elmt with the object it points
+to).  Entries are added with `pdump_add_entry()' and looked up with
+`pdump_get_entry()'.  There is no need for entry removal.  The hash
+value is computed quite simply from the object pointer by
+`pdump_make_hash()'.
+
+   The roots for the marking are:
+
+  1. the `staticpro''ed variables (there is a special
+     `staticpro_nodump()' call for protected variables we do not want
+     to dump).
+
+  2. the variables registered via `dump_add_root_object' (`staticpro()'
+     is equivalent to `staticpro_nodump()' + `dump_add_root_object()').
+
+  3. the variables registered via `dump_add_root_struct_ptr', each of
+     which points to a C structure.
+
+   This does not include the GCPRO'ed variables, the specbinds, the
+catchtags, the backlist, the redisplay or the profiling info, since we
+do not want to rebuild the actual chain of lisp calls which end up to
+the dump-emacs call, only the global variables.
+
+   Weak lists and weak hash tables are dumped as if they were their
+non-weak equivalent (without changing their type, of course).  This has
+not yet been a problem.
+
+
+File: internals.info,  Node: Address allocation,  Next: The header,  Prev: Object inventory,  Up: Dumping phase
+
+Address allocation
+------------------
+
+   The next step is to allocate the offsets of each of the objects in
+the final dump file.  This is done by `pdump_allocate_offset()' which
+is called indirectly by `pdump_scan_by_alignment()'.
+
+   The strategy to deal with alignment problems uses these facts:
+
+  1. real world alignment requirements are powers of two.
+
+  2. the C compiler is required to adjust the size of a struct so that
+     you can have an array of them next to each other.  This means you
+     can have an upper bound of the alignment requirements of a given
+     structure by looking at which power of two its size is a multiple.
+
+  3. the non-variant part of variable size lrecords has an alignment
+     requirement of 4.
+
+   Hence, for each lrecord type, C struct type or opaque data block the
+alignment requirement is computed as a power of two, with a minimum of
+2^2 for lrecords.  `pdump_scan_by_alignment()' then scans all the
+`pdump_entry_list_elmt''s, the ones with the highest requirements
+first.  This ensures the best packing.
+
+   The maximum alignment requirement we take into account is 2^8.
+
+   `pdump_allocate_offset()' only has to do a linear allocation,
+starting at offset 256 (this leaves room for the header and keeps the
+alignments happy).
+
+
+File: internals.info,  Node: The header,  Next: Data dumping,  Prev: Address allocation,  Up: Dumping phase
+
+The header
+----------
+
+   The next step creates the file and writes a header with a signature
+and some random information in it.  The `reloc_address' field, which
+indicates at which address the file should be loaded if we want to avoid
+post-reload relocation, is set to 0.  It then seeks to offset 256 (base
+offset for the objects).
+
+
+File: internals.info,  Node: Data dumping,  Next: Pointers dumping,  Prev: The header,  Up: Dumping phase
+
+Data dumping
+------------
+
+   The data is dumped in the same order as the addresses were allocated
+by `pdump_dump_data()', called from `pdump_scan_by_alignment()'.  This
+function copies the data to a temporary buffer, relocates all pointers
+in the object to the addresses allocated in step Address Allocation,
+and writes it to the file.  Using the same order means that, if we are
+careful with lrecords whose size is not a multiple of 4, we are ensured
+that the object is always written at the offset in the file allocated
+in step Address Allocation.
+
+
+File: internals.info,  Node: Pointers dumping,  Prev: Data dumping,  Up: Dumping phase
+
+Pointers dumping
+----------------
+
+   A bunch of tables needed to reassign properly the global pointers are
+then written.  They are:
+
+  1. the pdump_root_struct_ptrs dynarr
+
+  2. the pdump_opaques dynarr
+
+  3. a vector of all the offsets to the objects in the file that
+     include a description (for faster relocation at reload time)
+
+  4. the pdump_root_objects and pdump_weak_object_chains dynarrs.
+
+   For each of the dynarrs we write both the pointer to the variables
+and the relocated offset of the object they point to.  Since these
+variables are global, the pointers are still valid when restarting the
+program and are used to regenerate the global pointers.
+
+   The `pdump_weak_object_chains' dynarr is a special case.  The
+variables it points to are the head of weak linked lists of lisp objects
+of the same type.  Not all objects of this list are dumped so the
+relocated pointer we associate with them points to the first dumped
+object of the list, or Qnil if none is available.  This is also the
+reason why they are not used as roots for the purpose of object
+enumeration.
+
+   Some very important information like the `staticpros' and
+`lrecord_implementations_table' are handled indirectly using
+`dump_add_opaque' or `dump_add_root_struct_ptr'.
+
+   This is the end of the dumping part.
+
+
+File: internals.info,  Node: Reloading phase,  Next: Remaining issues,  Prev: Dumping phase,  Up: Dumping
+
+Reloading phase
+===============
+
+File loading
+------------
+
+   The file is mmap'ed in memory (which ensures a PAGESIZE alignment, at
+least 4096), or if mmap is unavailable or fails, a 256-bytes aligned
+malloc is done and the file is loaded.
+
+   Some variables are reinitialized from the values found in the header.
+
+   The difference between the actual loading address and the
+reloc_address is computed and will be used for all the relocations.
+
+Putting back the pdump_opaques
+------------------------------
+
+   The memory contents are restored in the obvious and trivial way.
+
+Putting back the pdump_root_struct_ptrs
+---------------------------------------
+
+   The variables pointed to by pdump_root_struct_ptrs in the dump phase
+are reset to the right relocated object addresses.
+
+Object relocation
+-----------------
+
+   All the objects are relocated using their description and their
+offset by `pdump_reloc_one'.  This step is unnecessary if the
+reloc_address is equal to the file loading address.
+
+Putting back the pdump_root_objects and pdump_weak_object_chains
+----------------------------------------------------------------
+
+   Same as Putting back the pdump_root_struct_ptrs.
+
+Reorganize the hash tables
+--------------------------
+
+   Since some of the hash values in the lisp hash tables are
+address-dependent, their layout is now wrong.  So we go through each of
+them and have them resorted by calling `pdump_reorganize_hash_table'.
+
+
+File: internals.info,  Node: Remaining issues,  Prev: Reloading phase,  Up: Dumping
+
+Remaining issues
+================
+
+   The build process will have to start a post-dump xemacs, ask it the
+loading address (which will, hopefully, be always the same between
+different xemacs invocations) and relocate the file to the new address.
+This way the object relocation phase will not have to be done, which
+means no writes in the objects and that, because of the use of mmap, the
+dumped data will be shared between all the xemacs running on the
+computer.
+
+   Some executable signature will be necessary to ensure that a given
+dump file is really associated with a given executable, or random
+crashes will occur.  Maybe a random number set at compile or configure
+time thru a define.  This will also allow for having
+differently-compiled xemacsen on the same system (mule and no-mule
+comes to mind).
+
+   The DOC file contents should probably end up in the dump file.
+
+
+File: internals.info,  Node: Events and the Event Loop,  Next: Evaluation; Stack Frames; Bindings,  Prev: Dumping,  Up: Top
+
+Events and the Event Loop
+*************************
+
+* Menu:
+
+* Introduction to Events::
+* Main Loop::
+* Specifics of the Event Gathering Mechanism::
+* Specifics About the Emacs Event::
+* The Event Stream Callback Routines::
+* Other Event Loop Functions::
+* Converting Events::
+* Dispatching Events; The Command Builder::
+
+
+File: internals.info,  Node: Introduction to Events,  Next: Main Loop,  Up: Events and the Event Loop
+
+Introduction to Events
+======================
+
+   An event is an object that encapsulates information about an
+interesting occurrence in the operating system.  Events are generated
+either by user action, direct (e.g. typing on the keyboard or moving
+the mouse) or indirect (moving another window, thereby generating an
+expose event on an Emacs frame), or as a result of some other typically
+asynchronous action happening, such as output from a subprocess being
+ready or a timer expiring.  Events come into the system in an
+asynchronous fashion (typically through a callback being called) and
+are converted into a synchronous event queue (first-in, first-out) in a
+process that we will call "collection".
+
+   Note that each application has its own event queue. (It is
+immaterial whether the collection process directly puts the events in
+the proper application's queue, or puts them into a single system
+queue, which is later split up.)
+
+   The most basic level of event collection is done by the operating
+system or window system.  Typically, XEmacs does its own event
+collection as well.  Often there are multiple layers of collection in
+XEmacs, with events from various sources being collected into a queue,
+which is then combined with other sources to go into another queue
+(i.e. a second level of collection), with perhaps another level on top
+of this, etc.
+
+   XEmacs has its own types of events (called "Emacs events"), which
+provides an abstract layer on top of the system-dependent nature of the
+most basic events that are received.  Part of the complex nature of the
+XEmacs event collection process involves converting from the
+operating-system events into the proper Emacs events--there may not be
+a one-to-one correspondence.
+
+   Emacs events are documented in `events.h'; I'll discuss them later.
+
+
+File: internals.info,  Node: Main Loop,  Next: Specifics of the Event Gathering Mechanism,  Prev: Introduction to Events,  Up: Events and the Event Loop
+
+Main Loop
+=========
+
+   The "command loop" is the top-level loop that the editor is always
+running.  It loops endlessly, calling `next-event' to retrieve an event
+and `dispatch-event' to execute it. `dispatch-event' does the
+appropriate thing with non-user events (process, timeout, magic, eval,
+mouse motion); this involves calling a Lisp handler function, redrawing
+a newly-exposed part of a frame, reading subprocess output, etc.  For
+user events, `dispatch-event' looks up the event in relevant keymaps or
+menubars; when a full key sequence or menubar selection is reached, the
+appropriate function is executed. `dispatch-event' may have to keep
+state across calls; this is done in the "command-builder" structure
+associated with each console (remember, there's usually only one
+console), and the engine that looks up keystrokes and constructs full
+key sequences is called the "command builder".  This is documented
+elsewhere.
+
+   The guts of the command loop are in `command_loop_1()'.  This
+function doesn't catch errors, though--that's the job of
+`command_loop_2()', which is a condition-case (i.e. error-trapping)
+wrapper around `command_loop_1()'.  `command_loop_1()' never returns,
+but may get thrown out of.
+
+   When an error occurs, `cmd_error()' is called, which usually invokes
+the Lisp error handler in `command-error'; however, a default error
+handler is provided if `command-error' is `nil' (e.g. during startup).
+The purpose of the error handler is simply to display the error message
+and do associated cleanup; it does not need to throw anywhere.  When
+the error handler finishes, the condition-case in `command_loop_2()'
+will finish and `command_loop_2()' will reinvoke `command_loop_1()'.
+
+   `command_loop_2()' is invoked from three places: from
+`initial_command_loop()' (called from `main()' at the end of internal
+initialization), from the Lisp function `recursive-edit', and from
+`call_command_loop()'.
+
+   `call_command_loop()' is called when a macro is started and when the
+minibuffer is entered; normal termination of the macro or minibuffer
+causes a throw out of the recursive command loop. (To
+`execute-kbd-macro' for macros and `exit' for minibuffers.  Note also
+that the low-level minibuffer-entering function,
+`read-minibuffer-internal', provides its own error handling and does
+not need `command_loop_2()''s error encapsulation; so it tells
+`call_command_loop()' to invoke `command_loop_1()' directly.)
+
+   Note that both read-minibuffer-internal and recursive-edit set up a
+catch for `exit'; this is why `abort-recursive-edit', which throws to
+this catch, exits out of either one.
+
+   `initial_command_loop()', called from `main()', sets up a catch for
+`top-level' when invoking `command_loop_2()', allowing functions to
+throw all the way to the top level if they really need to.  Before
+invoking `command_loop_2()', `initial_command_loop()' calls
+`top_level_1()', which handles all of the startup stuff (creating the
+initial frame, handling the command-line options, loading the user's
+`.emacs' file, etc.).  The function that actually does this is in Lisp
+and is pointed to by the variable `top-level'; normally this function is
+`normal-top-level'.  `top_level_1()' is just an error-handling wrapper
+similar to `command_loop_2()'.  Note also that `initial_command_loop()'
+sets up a catch for `top-level' when invoking `top_level_1()', just
+like when it invokes `command_loop_2()'.
+
+
+File: internals.info,  Node: Specifics of the Event Gathering Mechanism,  Next: Specifics About the Emacs Event,  Prev: Main Loop,  Up: Events and the Event Loop
+
+Specifics of the Event Gathering Mechanism
+==========================================
+
+   Here is an approximate diagram of the collection processes at work
+in XEmacs, under TTY's (TTY's are simpler than X so we'll look at this
+first):
+
+      asynch.      asynch.    asynch.   asynch.             [Collectors in
+     kbd events  kbd events   process   process                the OS]
+           |         |         output    output
+           |         |           |         |
+           |         |           |         |      SIGINT,   [signal handlers
+           |         |           |         |      SIGQUIT,     in XEmacs]
+           V         V           V         V      SIGWINCH,
+          file      file        file      file    SIGALRM
+          desc.     desc.       desc.     desc.     |
+          (TTY)     (TTY)       (pipe)    (pipe)    |
+           |          |          |         |      fake    timeouts
+           |          |          |         |      file        |
+           |          |          |         |      desc.       |
+           |          |          |         |      (pipe)      |
+           |          |          |         |        |         |
+           |          |          |         |        |         |
+           |          |          |         |        |         |
+           V          V          V         V        V         V
+           ------>-----------<----------------<----------------
+                       |
+                       |
+                       | [collected using select() in emacs_tty_next_event()
+                       |  and converted to the appropriate Emacs event]
+                       |
+                       |
+                       V          (above this line is TTY-specific)
+                     Emacs -----------------------------------------------
+                     event (below this line is the generic event mechanism)
+                       |
+                       |
+     was there     if not, call
+     a SIGINT?  emacs_tty_next_event()
+         |             |
+         |             |
+         |             |
+         V             V
+         --->------<----
+                |
+                |     [collected in event_stream_next_event();
+                |      SIGINT is converted using maybe_read_quit_event()]
+                V
+              Emacs
+              event
+                |
+                \---->------>----- maybe_kbd_translate() ---->---\
+                                                                 |
+                                                                 |
+                                                                 |
+          command event queue                                    |
+                                                    if not from command
+       (contains events that were                   event queue, call
+       read earlier but not processed,              event_stream_next_event()
+       typically when waiting in a                               |
+       sit-for, sleep-for, etc. for                              |
+      a particular event to be received)                         |
+                    |                                            |
+                    |                                            |
+                    V                                            V
+                    ---->------------------------------------<----
+                                                    |
+                                                    | [collected in
+                                                    |  next_event_internal()]
+                                                    |
+      unread-     unread-       event from          |
+      command-    command-       keyboard       else, call
+      events      event           macro      next_event_internal()
+        |           |               |               |
+        |           |               |               |
+        |           |               |               |
+        V           V               V               V
+        --------->----------------------<------------
+                          |
+                          |      [collected in `next-event', which may loop
+                          |       more than once if the event it gets is on
+                          |       a dead frame, device, etc.]
+                          |
+                          |
+                          V
+                 feed into top-level event loop,
+                 which repeatedly calls `next-event'
+                 and then dispatches the event
+                 using `dispatch-event'
+
+   Notice the separation between TTY-specific and generic event
+mechanism.  When using the Xt-based event loop, the TTY-specific stuff
+is replaced but the rest stays the same.
+
+   It's also important to realize that only one different kind of
+system-specific event loop can be operating at a time, and must be able
+to receive all kinds of events simultaneously.  For the two existing
+event loops (implemented in `event-tty.c' and `event-Xt.c',
+respectively), the TTY event loop _only_ handles TTY consoles, while
+the Xt event loop handles _both_ TTY and X consoles.  This situation is
+different from all of the output handlers, where you simply have one
+per console type.
+
+   Here's the Xt Event Loop Diagram (notice that below a certain point,
+it's the same as the above diagram):
+
+     asynch. asynch. asynch. asynch.                 [Collectors in
+      kbd     kbd    process process                    the OS]
+     events  events  output  output
+       |       |       |       |
+       |       |       |       |     asynch. asynch. [Collectors in the
+       |       |       |       |       X        X     OS and X Window System]
+       |       |       |       |     events  events
+       |       |       |       |       |        |
+       |       |       |       |       |        |
+       |       |       |       |       |        |    SIGINT, [signal handlers
+       |       |       |       |       |        |    SIGQUIT,   in XEmacs]
+       |       |       |       |       |        |    SIGWINCH,
+       |       |       |       |       |        |    SIGALRM
+       |       |       |       |       |        |       |
+       |       |       |       |       |        |       |
+       |       |       |       |       |        |       |      timeouts
+       |       |       |       |       |        |       |          |
+       |       |       |       |       |        |       |          |
+       |       |       |       |       |        |       V          |
+       V       V       V       V       V        V      fake        |
+      file    file    file    file    file     file    file        |
+      desc.   desc.   desc.   desc.   desc.    desc.   desc.       |
+      (TTY)   (TTY)   (pipe)  (pipe) (socket) (socket) (pipe)      |
+       |       |       |       |       |        |       |          |
+       |       |       |       |       |        |       |          |
+       |       |       |       |       |        |       |          |
+       V       V       V       V       V        V       V          V
+       --->----------------------------------------<---------<------
+            |              |               |
+            |              |               |[collected using select() in
+            |              |               | _XtWaitForSomething(), called
+            |              |               | from XtAppProcessEvent(), called
+            |              |               | in emacs_Xt_next_event();
+            |              |               | dispatched to various callbacks]
+            |              |               |
+            |              |               |
+       emacs_Xt_        p_s_callback(),    | [popup_selection_callback]
+       event_handler()  x_u_v_s_callback(),| [x_update_vertical_scrollbar_
+            |           x_u_h_s_callback(),|  callback]
+            |           search_callback()  | [x_update_horizontal_scrollbar_
+            |              |               |  callback]
+            |              |               |
+            |              |               |
+       enqueue_Xt_       signal_special_   |
+       dispatch_event()  Xt_user_event()   |
+       [maybe multiple     |               |
+        times, maybe 0     |               |
+        times]             |               |
+            |            enqueue_Xt_       |
+            |            dispatch_event()  |
+            |              |               |
+            |              |               |
+            V              V               |
+            -->----------<--               |
+                   |                       |
+                   |                       |
+                dispatch             Xt_what_callback()
+                event                  sets flags
+                queue                      |
+                   |                       |
+                   |                       |
+                   |                       |
+                   |                       |
+                   ---->-----------<--------
+                        |
+                        |
+                        |     [collected and converted as appropriate in
+                        |            emacs_Xt_next_event()]
+                        |
+                        |
+                        V          (above this line is Xt-specific)
+                      Emacs ------------------------------------------------
+                      event (below this line is the generic event mechanism)
+                        |
+                        |
+     was there      if not, call
+     a SIGINT?   emacs_Xt_next_event()
+         |              |
+         |              |
+         |              |
+         V              V
+         --->-------<----
+                |
+                |        [collected in event_stream_next_event();
+                |         SIGINT is converted using maybe_read_quit_event()]
+                V
+              Emacs
+              event
+                |
+                \---->------>----- maybe_kbd_translate() -->-----\
+                                                                 |
+                                                                 |
+                                                                 |
+          command event queue                                    |
+                                                   if not from command
+       (contains events that were                  event queue, call
+       read earlier but not processed,             event_stream_next_event()
+       typically when waiting in a                               |
+       sit-for, sleep-for, etc. for                              |
+      a particular event to be received)                         |
+                    |                                            |
+                    |                                            |
+                    V                                            V
+                    ---->----------------------------------<------
+                                                    |
+                                                    | [collected in
+                                                    |  next_event_internal()]
+                                                    |
+      unread-     unread-       event from          |
+      command-    command-       keyboard       else, call
+      events      event           macro      next_event_internal()
+        |           |               |               |
+        |           |               |               |
+        |           |               |               |
+        V           V               V               V
+        --------->----------------------<------------
+                          |
+                          |      [collected in `next-event', which may loop
+                          |       more than once if the event it gets is on
+                          |       a dead frame, device, etc.]
+                          |
+                          |
+                          V
+                 feed into top-level event loop,
+                 which repeatedly calls `next-event'
+                 and then dispatches the event
+                 using `dispatch-event'
+
+
+File: internals.info,  Node: Specifics About the Emacs Event,  Next: The Event Stream Callback Routines,  Prev: Specifics of the Event Gathering Mechanism,  Up: Events and the Event Loop
+
+Specifics About the Emacs Event
+===============================
+
+
+File: internals.info,  Node: The Event Stream Callback Routines,  Next: Other Event Loop Functions,  Prev: Specifics About the Emacs Event,  Up: Events and the Event Loop
+
+The Event Stream Callback Routines
+==================================
+
+
+File: internals.info,  Node: Other Event Loop Functions,  Next: Converting Events,  Prev: The Event Stream Callback Routines,  Up: Events and the Event Loop
+
+Other Event Loop Functions
+==========================
+
+   `detect_input_pending()' and `input-pending-p' look for input by
+calling `event_stream->event_pending_p' and looking in
+`[V]unread-command-event' and the `command_event_queue' (they do not
+check for an executing keyboard macro, though).
+
+   `discard-input' cancels any command events pending (and any keyboard
+macros currently executing), and puts the others onto the
+`command_event_queue'.  There is a comment about a "race condition",
+which is not a good sign.
+
+   `next-command-event' and `read-char' are higher-level interfaces to
+`next-event'.  `next-command-event' gets the next "command" event (i.e.
+keypress, mouse event, menu selection, or scrollbar action), calling
+`dispatch-event' on any others.  `read-char' calls `next-command-event'
+and uses `event_to_character()' to return the character equivalent.
+With the right kind of input method support, it is possible for
+(read-char) to return a Kanji character.
+
+
+File: internals.info,  Node: Converting Events,  Next: Dispatching Events; The Command Builder,  Prev: Other Event Loop Functions,  Up: Events and the Event Loop
+
+Converting Events
+=================
+
+   `character_to_event()', `event_to_character()',
+`event-to-character', and `character-to-event' convert between
+characters and keypress events corresponding to the characters.  If the
+event was not a keypress, `event_to_character()' returns -1 and
+`event-to-character' returns `nil'.  These functions convert between
+character representation and the split-up event representation (keysym
+plus mod keys).
+
+
+File: internals.info,  Node: Dispatching Events; The Command Builder,  Prev: Converting Events,  Up: Events and the Event Loop
+
+Dispatching Events; The Command Builder
+=======================================
+
+   Not yet documented.
+
+
+File: internals.info,  Node: Evaluation; Stack Frames; Bindings,  Next: Symbols and Variables,  Prev: Events and the Event Loop,  Up: Top
+
+Evaluation; Stack Frames; Bindings
+**********************************
+
+* Menu:
+
+* Evaluation::
+* Dynamic Binding; The specbinding Stack; Unwind-Protects::
+* Simple Special Forms::
+* Catch and Throw::
+
+
+File: internals.info,  Node: Evaluation,  Next: Dynamic Binding; The specbinding Stack; Unwind-Protects,  Up: Evaluation; Stack Frames; Bindings
+
+Evaluation
+==========
+
+   `Feval()' evaluates the form (a Lisp object) that is passed to it.
+Note that evaluation is only non-trivial for two types of objects:
+symbols and conses.  A symbol is evaluated simply by calling
+`symbol-value' on it and returning the value.
+
+   Evaluating a cons means calling a function.  First, `eval' checks to
+see if garbage-collection is necessary, and calls `garbage_collect_1()'
+if so.  It then increases the evaluation depth by 1 (`lisp_eval_depth',
+which is always less than `max_lisp_eval_depth') and adds an element to
+the linked list of `struct backtrace''s (`backtrace_list').  Each such
+structure contains a pointer to the function being called plus a list
+of the function's arguments.  Originally these values are stored
+unevalled, and as they are evaluated, the backtrace structure is
+updated.  Garbage collection pays attention to the objects pointed to
+in the backtrace structures (garbage collection might happen while a
+function is being called or while an argument is being evaluated, and
+there could easily be no other references to the arguments in the
+argument list; once an argument is evaluated, however, the unevalled
+version is not needed by eval, and so the backtrace structure is
+changed).
+
+   At this point, the function to be called is determined by looking at
+the car of the cons (if this is a symbol, its function definition is
+retrieved and the process repeated).  The function should then consist
+of either a `Lisp_Subr' (built-in function written in C), a
+`Lisp_Compiled_Function' object, or a cons whose car is one of the
+symbols `autoload', `macro' or `lambda'.
+
+   If the function is a `Lisp_Subr', the lisp object points to a
+`struct Lisp_Subr' (created by `DEFUN()'), which contains a pointer to
+the C function, a minimum and maximum number of arguments (or possibly
+the special constants `MANY' or `UNEVALLED'), a pointer to the symbol
+referring to that subr, and a couple of other things.  If the subr
+wants its arguments `UNEVALLED', they are passed raw as a list.
+Otherwise, an array of evaluated arguments is created and put into the
+backtrace structure, and either passed whole (`MANY') or each argument
+is passed as a C argument.
+
+   If the function is a `Lisp_Compiled_Function',
+`funcall_compiled_function()' is called.  If the function is a lambda
+list, `funcall_lambda()' is called.  If the function is a macro, [.....
+fill in] is done.  If the function is an autoload, `do_autoload()' is
+called to load the definition and then eval starts over [explain this
+more].
+
+   When `Feval()' exits, the evaluation depth is reduced by one, the
+debugger is called if appropriate, and the current backtrace structure
+is removed from the list.
+
+   Both `funcall_compiled_function()' and `funcall_lambda()' need to go
+through the list of formal parameters to the function and bind them to
+the actual arguments, checking for `&rest' and `&optional' symbols in
+the formal parameters and making sure the number of actual arguments is
+correct.  `funcall_compiled_function()' can do this a little more
+efficiently, since the formal parameter list can be checked for sanity
+when the compiled function object is created.
+
+   `funcall_lambda()' simply calls `Fprogn' to execute the code in the
+lambda list.
+
+   `funcall_compiled_function()' calls the real byte-code interpreter
+`execute_optimized_program()' on the byte-code instructions, which are
+converted into an internal form for faster execution.
+
+   When a compiled function is executed for the first time by
+`funcall_compiled_function()', or during the dump phase of building
+XEmacs, the byte-code instructions are converted from a `Lisp_String'
+(which is inefficient to access, especially in the presence of MULE)
+into a `Lisp_Opaque' object containing an array of unsigned char, which
+can be directly executed by the byte-code interpreter.  At this time
+the byte code is also analyzed for validity and transformed into a more
+optimized form, so that `execute_optimized_program()' can really fly.
+
+   Here are some of the optimizations performed by the internal
+byte-code transformer:
+  1. References to the `constants' array are checked for out-of-range
+     indices, so that the byte interpreter doesn't have to.
+
+  2. References to the `constants' array that will be used as a Lisp
+     variable are checked for being correct non-constant (i.e. not `t',
+     `nil', or `keywordp') symbols, so that the byte interpreter
+     doesn't have to.
+
+  3. The maximum number of variable bindings in the byte-code is
+     pre-computed, so that space on the `specpdl' stack can be
+     pre-reserved once for the whole function execution.
+
+  4. All byte-code jumps are relative to the current program counter
+     instead of the start of the program, thereby saving a register.
+
+  5. One-byte relative jumps are converted from the byte-code form of
+     unsigned chars offset by 127 to machine-friendly signed chars.
+
+   Of course, this transformation of the `instructions' should not be
+visible to the user, so `Fcompiled_function_instructions()' needs to
+know how to convert the optimized opaque object back into a Lisp string
+that is identical to the original string from the `.elc' file.
+(Actually, the resulting string may (rarely) contain slightly
+different, yet equivalent, byte code.)
+
+   `Ffuncall()' implements Lisp `funcall'.  `(funcall fun x1 x2 x3
+...)' is equivalent to `(eval (list fun (quote x1) (quote x2) (quote
+x3) ...))'.  `Ffuncall()' contains its own code to do the evaluation,
+however, and is very similar to `Feval()'.
+
+   From the performance point of view, it is worth knowing that most of
+the time in Lisp evaluation is spent executing `Lisp_Subr' and
+`Lisp_Compiled_Function' objects via `Ffuncall()' (not `Feval()').
+
+   `Fapply()' implements Lisp `apply', which is very similar to
+`funcall' except that if the last argument is a list, the result is the
+same as if each of the arguments in the list had been passed separately.
+`Fapply()' does some business to expand the last argument if it's a
+list, then calls `Ffuncall()' to do the work.
+
+   `apply1()', `call0()', `call1()', `call2()', and `call3()' call a
+function, passing it the argument(s) given (the arguments are given as
+separate C arguments rather than being passed as an array).  `apply1()'
+uses `Fapply()' while the others use `Ffuncall()' to do the real work.
+
+
+File: internals.info,  Node: Dynamic Binding; The specbinding Stack; Unwind-Protects,  Next: Simple Special Forms,  Prev: Evaluation,  Up: Evaluation; Stack Frames; Bindings
+
+Dynamic Binding; The specbinding Stack; Unwind-Protects
+=======================================================
+
+     struct specbinding
+     {
+       Lisp_Object symbol;
+       Lisp_Object old_value;
+       Lisp_Object (*func) (Lisp_Object); /* for unwind-protect */
+     };
+
+   `struct specbinding' is used for local-variable bindings and
+unwind-protects.  `specpdl' holds an array of `struct specbinding''s,
+`specpdl_ptr' points to the beginning of the free bindings in the
+array, `specpdl_size' specifies the total number of binding slots in
+the array, and `max_specpdl_size' specifies the maximum number of
+bindings the array can be expanded to hold.  `grow_specpdl()' increases
+the size of the `specpdl' array, multiplying its size by 2 but never
+exceeding `max_specpdl_size' (except that if this number is less than
+400, it is first set to 400).
+
+   `specbind()' binds a symbol to a value and is used for local
+variables and `let' forms.  The symbol and its old value (which might
+be `Qunbound', indicating no prior value) are recorded in the specpdl
+array, and `specpdl_size' is increased by 1.
+
+   `record_unwind_protect()' implements an "unwind-protect", which,
+when placed around a section of code, ensures that some specified
+cleanup routine will be executed even if the code exits abnormally
+(e.g. through a `throw' or quit).  `record_unwind_protect()' simply
+adds a new specbinding to the `specpdl' array and stores the
+appropriate information in it.  The cleanup routine can either be a C
+function, which is stored in the `func' field, or a `progn' form, which
+is stored in the `old_value' field.
+
+   `unbind_to()' removes specbindings from the `specpdl' array until
+the specified position is reached.  Each specbinding can be one of
+three types:
+
+  1. an unwind-protect with a C cleanup function (`func' is not 0, and
+     `old_value' holds an argument to be passed to the function);
+
+  2. an unwind-protect with a Lisp form (`func' is 0, `symbol' is
+     `nil', and `old_value' holds the form to be executed with
+     `Fprogn()'); or
+
+  3. a local-variable binding (`func' is 0, `symbol' is not `nil', and
+     `old_value' holds the old value, which is stored as the symbol's
+     value).
+
+
+File: internals.info,  Node: Simple Special Forms,  Next: Catch and Throw,  Prev: Dynamic Binding; The specbinding Stack; Unwind-Protects,  Up: Evaluation; Stack Frames; Bindings
+
+Simple Special Forms
+====================
+
+   `or', `and', `if', `cond', `progn', `prog1', `prog2', `setq',
+`quote', `function', `let*', `let', `while'
+
+   All of these are very simple and work as expected, calling `Feval()'
+or `Fprogn()' as necessary and (in the case of `let' and `let*') using
+`specbind()' to create bindings and `unbind_to()' to undo the bindings
+when finished.
+
+   Note that, with the exception of `Fprogn', these functions are
+typically called in real life only in interpreted code, since the byte
+compiler knows how to convert calls to these functions directly into
+byte code.
+
+
+File: internals.info,  Node: Catch and Throw,  Prev: Simple Special Forms,  Up: Evaluation; Stack Frames; Bindings
+
+Catch and Throw
+===============
+
+     struct catchtag
+     {
+       Lisp_Object tag;
+       Lisp_Object val;
+       struct catchtag *next;
+       struct gcpro *gcpro;
+       jmp_buf jmp;
+       struct backtrace *backlist;
+       int lisp_eval_depth;
+       int pdlcount;
+     };
+
+   `catch' is a Lisp function that places a catch around a body of
+code.  A catch is a means of non-local exit from the code.  When a catch
+is created, a tag is specified, and executing a `throw' to this tag
+will exit from the body of code caught with this tag, and its value will
+be the value given in the call to `throw'.  If there is no such call,
+the code will be executed normally.
+
+   Information pertaining to a catch is held in a `struct catchtag',
+which is placed at the head of a linked list pointed to by `catchlist'.
+`internal_catch()' is passed a C function to call (`Fprogn()' when
+Lisp `catch' is called) and arguments to give it, and places a catch
+around the function.  Each `struct catchtag' is held in the stack frame
+of the `internal_catch()' instance that created the catch.
+
+   `internal_catch()' is fairly straightforward.  It stores into the
+`struct catchtag' the tag name and the current values of
+`backtrace_list', `lisp_eval_depth', `gcprolist', and the offset into
+the `specpdl' array, sets a jump point with `_setjmp()' (storing the
+jump point into the `struct catchtag'), and calls the function.
+Control will return to `internal_catch()' either when the function
+exits normally or through a `_longjmp()' to this jump point.  In the
+latter case, `throw' will store the value to be returned into the
+`struct catchtag' before jumping.  When it's done, `internal_catch()'
+removes the `struct catchtag' from the catchlist and returns the proper
+value.
+
+   `Fthrow()' goes up through the catchlist until it finds one with a
+matching tag.  It then calls `unbind_catch()' to restore everything to
+what it was when the appropriate catch was set, stores the return value
+in the `struct catchtag', and jumps (with `_longjmp()') to its jump
+point.
+
+   `unbind_catch()' removes all catches from the catchlist until it
+finds the correct one.  Some of the catches might have been placed for
+error-trapping, and if so, the appropriate entries on the handlerlist
+must be removed (see "errors").  `unbind_catch()' also restores the
+values of `gcprolist', `backtrace_list', and `lisp_eval', and calls
+`unbind_to()' to undo any specbindings created since the catch.
+
+
+File: internals.info,  Node: Symbols and Variables,  Next: Buffers and Textual Representation,  Prev: Evaluation; Stack Frames; Bindings,  Up: Top
+
+Symbols and Variables
+*********************
+
+* Menu:
+
+* Introduction to Symbols::
+* Obarrays::
+* Symbol Values::
+
+
+File: internals.info,  Node: Introduction to Symbols,  Next: Obarrays,  Up: Symbols and Variables
+
+Introduction to Symbols
+=======================
+
+   A symbol is basically just an object with four fields: a name (a
+string), a value (some Lisp object), a function (some Lisp object), and
+a property list (usually a list of alternating keyword/value pairs).
+What makes symbols special is that there is usually only one symbol with
+a given name, and the symbol is referred to by name.  This makes a
+symbol a convenient way of calling up data by name, i.e. of implementing
+variables. (The variable's value is stored in the "value slot".)
+Similarly, functions are referenced by name, and the definition of the
+function is stored in a symbol's "function slot".  This means that
+there can be a distinct function and variable with the same name.  The
+property list is used as a more general mechanism of associating
+additional values with particular names, and once again the namespace is
+independent of the function and variable namespaces.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-7'
Index: ././info/internals.info-7
--- ././info/internals.info-7	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-7	Thu May 17 23:26:54 2001
@@ -0,0 +1,1118 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Obarrays,  Next: Symbol Values,  Prev: Introduction to Symbols,  Up: Symbols and Variables
+
+Obarrays
+========
+
+   The identity of symbols with their names is accomplished through a
+structure called an obarray, which is just a poorly-implemented hash
+table mapping from strings to symbols whose name is that string. (I say
+"poorly implemented" because an obarray appears in Lisp as a vector
+with some hidden fields rather than as its own opaque type.  This is an
+Emacs Lisp artifact that should be fixed.)
+
+   Obarrays are implemented as a vector of some fixed size (which should
+be a prime for best results), where each "bucket" of the vector
+contains one or more symbols, threaded through a hidden `next' field in
+the symbol.  Lookup of a symbol in an obarray, and adding a symbol to
+an obarray, is accomplished through standard hash-table techniques.
+
+   The standard Lisp function for working with symbols and obarrays is
+`intern'.  This looks up a symbol in an obarray given its name; if it's
+not found, a new symbol is automatically created with the specified
+name, added to the obarray, and returned.  This is what happens when the
+Lisp reader encounters a symbol (or more precisely, encounters the name
+of a symbol) in some text that it is reading.  There is a standard
+obarray called `obarray' that is used for this purpose, although the
+Lisp programmer is free to create his own obarrays and `intern' symbols
+in them.
+
+   Note that, once a symbol is in an obarray, it stays there until
+something is done about it, and the standard obarray `obarray' always
+stays around, so once you use any particular variable name, a
+corresponding symbol will stay around in `obarray' until you exit
+XEmacs.
+
+   Note that `obarray' itself is a variable, and as such there is a
+symbol in `obarray' whose name is `"obarray"' and which contains
+`obarray' as its value.
+
+   Note also that this call to `intern' occurs only when in the Lisp
+reader, not when the code is executed (at which point the symbol is
+already around, stored as such in the definition of the function).
+
+   You can create your own obarray using `make-vector' (this is
+horrible but is an artifact) and intern symbols into that obarray.
+Doing that will result in two or more symbols with the same name.
+However, at most one of these symbols is in the standard `obarray': You
+cannot have two symbols of the same name in any particular obarray.
+Note that you cannot add a symbol to an obarray in any fashion other
+than using `intern': i.e. you can't take an existing symbol and put it
+in an existing obarray.  Nor can you change the name of an existing
+symbol. (Since obarrays are vectors, you can violate the consistency of
+things by storing directly into the vector, but let's ignore that
+possibility.)
+
+   Usually symbols are created by `intern', but if you really want, you
+can explicitly create a symbol using `make-symbol', giving it some
+name.  The resulting symbol is not in any obarray (i.e. it is
+"uninterned"), and you can't add it to any obarray.  Therefore its
+primary purpose is as a symbol to use in macros to avoid namespace
+pollution.  It can also be used as a carrier of information, but cons
+cells could probably be used just as well.
+
+   You can also use `intern-soft' to look up a symbol but not create a
+new one, and `unintern' to remove a symbol from an obarray.  This
+returns the removed symbol. (Remember: You can't put the symbol back
+into any obarray.) Finally, `mapatoms' maps over all of the symbols in
+an obarray.
+
+
+File: internals.info,  Node: Symbol Values,  Prev: Obarrays,  Up: Symbols and Variables
+
+Symbol Values
+=============
+
+   The value field of a symbol normally contains a Lisp object.
+However, a symbol can be "unbound", meaning that it logically has no
+value.  This is internally indicated by storing a special Lisp object,
+called "the unbound marker" and stored in the global variable
+`Qunbound'.  The unbound marker is of a special Lisp object type called
+"symbol-value-magic".  It is impossible for the Lisp programmer to
+directly create or access any object of this type.
+
+   *You must not let any "symbol-value-magic" object escape to the Lisp
+level.*  Printing any of these objects will cause the message `INTERNAL
+EMACS BUG' to appear as part of the print representation.  (You may see
+this normally when you call `debug_print()' from the debugger on a Lisp
+object.) If you let one of these objects escape to the Lisp level, you
+will violate a number of assumptions contained in the C code and make
+the unbound marker not function right.
+
+   When a symbol is created, its value field (and function field) are
+set to `Qunbound'.  The Lisp programmer can restore these conditions
+later using `makunbound' or `fmakunbound', and can query to see whether
+the value of function fields are "bound" (i.e. have a value other than
+`Qunbound') using `boundp' and `fboundp'.  The fields are set to a
+normal Lisp object using `set' (or `setq') and `fset'.
+
+   Other symbol-value-magic objects are used as special markers to
+indicate variables that have non-normal properties.  This includes any
+variables that are tied into C variables (setting the variable magically
+sets some global variable in the C code, and likewise for retrieving the
+variable's value), variables that magically tie into slots in the
+current buffer, variables that are buffer-local, etc.  The
+symbol-value-magic object is stored in the value cell in place of a
+normal object, and the code to retrieve a symbol's value (i.e.
+`symbol-value') knows how to do special things with them.  This means
+that you should not just fetch the value cell directly if you want a
+symbol's value.
+
+   The exact workings of this are rather complex and involved and are
+well-documented in comments in `buffer.c', `symbols.c', and `lisp.h'.
+
+
+File: internals.info,  Node: Buffers and Textual Representation,  Next: MULE Character Sets and Encodings,  Prev: Symbols and Variables,  Up: Top
+
+Buffers and Textual Representation
+**********************************
+
+* Menu:
+
+* Introduction to Buffers::     A buffer holds a block of text such as a file.
+* The Text in a Buffer::        Representation of the text in a buffer.
+* Buffer Lists::                Keeping track of all buffers.
+* Markers and Extents::         Tagging locations within a buffer.
+* Bufbytes and Emchars::        Representation of individual characters.
+* The Buffer Object::           The Lisp object corresponding to a buffer.
+
+
+File: internals.info,  Node: Introduction to Buffers,  Next: The Text in a Buffer,  Up: Buffers and Textual Representation
+
+Introduction to Buffers
+=======================
+
+   A buffer is logically just a Lisp object that holds some text.  In
+this, it is like a string, but a buffer is optimized for frequent
+insertion and deletion, while a string is not.  Furthermore:
+
+  1. Buffers are "permanent" objects, i.e. once you create them, they
+     remain around, and need to be explicitly deleted before they go
+     away.
+
+  2. Each buffer has a unique name, which is a string.  Buffers are
+     normally referred to by name.  In this respect, they are like
+     symbols.
+
+  3. Buffers have a default insertion position, called "point".
+     Inserting text (unless you explicitly give a position) goes at
+     point, and moves point forward past the text.  This is what is
+     going on when you type text into Emacs.
+
+  4. Buffers have lots of extra properties associated with them.
+
+  5. Buffers can be "displayed".  What this means is that there exist a
+     number of "windows", which are objects that correspond to some
+     visible section of your display, and each window has an associated
+     buffer, and the current contents of the buffer are shown in that
+     section of the display.  The redisplay mechanism (which takes care
+     of doing this) knows how to look at the text of a buffer and come
+     up with some reasonable way of displaying this.  Many of the
+     properties of a buffer control how the buffer's text is displayed.
+
+  6. One buffer is distinguished and called the "current buffer".  It is
+     stored in the variable `current_buffer'.  Buffer operations operate
+     on this buffer by default.  When you are typing text into a
+     buffer, the buffer you are typing into is always `current_buffer'.
+     Switching to a different window changes the current buffer.  Note
+     that Lisp code can temporarily change the current buffer using
+     `set-buffer' (often enclosed in a `save-excursion' so that the
+     former current buffer gets restored when the code is finished).
+     However, calling `set-buffer' will NOT cause a permanent change in
+     the current buffer.  The reason for this is that the top-level
+     event loop sets `current_buffer' to the buffer of the selected
+     window, each time it finishes executing a user command.
+
+   Make sure you understand the distinction between "current buffer"
+and "buffer of the selected window", and the distinction between
+"point" of the current buffer and "window-point" of the selected
+window. (This latter distinction is explained in detail in the section
+on windows.)
+
+
+File: internals.info,  Node: The Text in a Buffer,  Next: Buffer Lists,  Prev: Introduction to Buffers,  Up: Buffers and Textual Representation
+
+The Text in a Buffer
+====================
+
+   The text in a buffer consists of a sequence of zero or more
+characters.  A "character" is an integer that logically represents a
+letter, number, space, or other unit of text.  Most of the characters
+that you will typically encounter belong to the ASCII set of characters,
+but there are also characters for various sorts of accented letters,
+special symbols, Chinese and Japanese ideograms (i.e. Kanji, Katakana,
+etc.), Cyrillic and Greek letters, etc.  The actual number of possible
+characters is quite large.
+
+   For now, we can view a character as some non-negative integer that
+has some shape that defines how it typically appears (e.g. as an
+uppercase A). (The exact way in which a character appears depends on the
+font used to display the character.) The internal type of characters in
+the C code is an `Emchar'; this is just an `int', but using a symbolic
+type makes the code clearer.
+
+   Between every character in a buffer is a "buffer position" or
+"character position".  We can speak of the character before or after a
+particular buffer position, and when you insert a character at a
+particular position, all characters after that position end up at new
+positions.  When we speak of the character "at" a position, we really
+mean the character after the position.  (This schizophrenia between a
+buffer position being "between" a character and "on" a character is
+rampant in Emacs.)
+
+   Buffer positions are numbered starting at 1.  This means that
+position 1 is before the first character, and position 0 is not valid.
+If there are N characters in a buffer, then buffer position N+1 is
+after the last one, and position N+2 is not valid.
+
+   The internal makeup of the Emchar integer varies depending on whether
+we have compiled with MULE support.  If not, the Emchar integer is an
+8-bit integer with possible values from 0 - 255.  0 - 127 are the
+standard ASCII characters, while 128 - 255 are the characters from the
+ISO-8859-1 character set.  If we have compiled with MULE support, an
+Emchar is a 19-bit integer, with the various bits having meanings
+according to a complex scheme that will be detailed later.  The
+characters numbered 0 - 255 still have the same meanings as for the
+non-MULE case, though.
+
+   Internally, the text in a buffer is represented in a fairly simple
+fashion: as a contiguous array of bytes, with a "gap" of some size in
+the middle.  Although the gap is of some substantial size in bytes,
+there is no text contained within it: From the perspective of the text
+in the buffer, it does not exist.  The gap logically sits at some buffer
+position, between two characters (or possibly at the beginning or end of
+the buffer).  Insertion of text in a buffer at a particular position is
+always accomplished by first moving the gap to that position (i.e.
+through some block moving of text), then writing the text into the
+beginning of the gap, thereby shrinking the gap.  If the gap shrinks
+down to nothing, a new gap is created. (What actually happens is that a
+new gap is "created" at the end of the buffer's text, which requires
+nothing more than changing a couple of indices; then the gap is "moved"
+to the position where the insertion needs to take place by moving up in
+memory all the text after that position.)  Similarly, deletion occurs
+by moving the gap to the place where the text is to be deleted, and
+then simply expanding the gap to include the deleted text.
+("Expanding" and "shrinking" the gap as just described means just that
+the internal indices that keep track of where the gap is located are
+changed.)
+
+   Note that the total amount of memory allocated for a buffer text
+never decreases while the buffer is live.  Therefore, if you load up a
+20-megabyte file and then delete all but one character, there will be a
+20-megabyte gap, which won't get any smaller (except by inserting
+characters back again).  Once the buffer is killed, the memory allocated
+for the buffer text will be freed, but it will still be sitting on the
+heap, taking up virtual memory, and will not be released back to the
+operating system. (However, if you have compiled XEmacs with rel-alloc,
+the situation is different.  In this case, the space _will_ be released
+back to the operating system.  However, this tends to result in a
+noticeable speed penalty.)
+
+   Astute readers may notice that the text in a buffer is represented as
+an array of _bytes_, while (at least in the MULE case) an Emchar is a
+19-bit integer, which clearly cannot fit in a byte.  This means (of
+course) that the text in a buffer uses a different representation from
+an Emchar: specifically, the 19-bit Emchar becomes a series of one to
+four bytes.  The conversion between these two representations is complex
+and will be described later.
+
+   In the non-MULE case, everything is very simple: An Emchar is an
+8-bit value, which fits neatly into one byte.
+
+   If we are given a buffer position and want to retrieve the character
+at that position, we need to follow these steps:
+
+  1. Pretend there's no gap, and convert the buffer position into a
+     "byte index" that indexes to the appropriate byte in the buffer's
+     stream of textual bytes.  By convention, byte indices begin at 1,
+     just like buffer positions.  In the non-MULE case, byte indices
+     and buffer positions are identical, since one character equals one
+     byte.
+
+  2. Convert the byte index into a "memory index", which takes the gap
+     into account.  The memory index is a direct index into the block of
+     memory that stores the text of a buffer.  This basically just
+     involves checking to see if the byte index is past the gap, and if
+     so, adding the size of the gap to it.  By convention, memory
+     indices begin at 1, just like buffer positions and byte indices,
+     and when referring to the position that is "at" the gap, we always
+     use the memory position at the _beginning_, not at the end, of the
+     gap.
+
+  3. Fetch the appropriate bytes at the determined memory position.
+
+  4. Convert these bytes into an Emchar.
+
+   In the non-Mule case, (3) and (4) boil down to a simple one-byte
+memory access.
+
+   Note that we have defined three types of positions in a buffer:
+
+  1. "buffer positions" or "character positions", typedef `Bufpos'
+
+  2. "byte indices", typedef `Bytind'
+
+  3. "memory indices", typedef `Memind'
+
+   All three typedefs are just `int's, but defining them this way makes
+things a lot clearer.
+
+   Most code works with buffer positions.  In particular, all Lisp code
+that refers to text in a buffer uses buffer positions.  Lisp code does
+not know that byte indices or memory indices exist.
+
+   Finally, we have a typedef for the bytes in a buffer.  This is a
+`Bufbyte', which is an unsigned char.  Referring to them as Bufbytes
+underscores the fact that we are working with a string of bytes in the
+internal Emacs buffer representation rather than in one of a number of
+possible alternative representations (e.g. EUC-encoded text, etc.).
+
+
+File: internals.info,  Node: Buffer Lists,  Next: Markers and Extents,  Prev: The Text in a Buffer,  Up: Buffers and Textual Representation
+
+Buffer Lists
+============
+
+   Recall earlier that buffers are "permanent" objects, i.e.  that they
+remain around until explicitly deleted.  This entails that there is a
+list of all the buffers in existence.  This list is actually an
+assoc-list (mapping from the buffer's name to the buffer) and is stored
+in the global variable `Vbuffer_alist'.
+
+   The order of the buffers in the list is important: the buffers are
+ordered approximately from most-recently-used to least-recently-used.
+Switching to a buffer using `switch-to-buffer', `pop-to-buffer', etc.
+and switching windows using `other-window', etc.  usually brings the
+new current buffer to the front of the list.  `switch-to-buffer',
+`other-buffer', etc. look at the beginning of the list to find an
+alternative buffer to suggest.  You can also explicitly move a buffer
+to the end of the list using `bury-buffer'.
+
+   In addition to the global ordering in `Vbuffer_alist', each frame
+has its own ordering of the list.  These lists always contain the same
+elements as in `Vbuffer_alist' although possibly in a different order.
+`buffer-list' normally returns the list for the selected frame.  This
+allows you to work in separate frames without things interfering with
+each other.
+
+   The standard way to look up a buffer given a name is `get-buffer',
+and the standard way to create a new buffer is `get-buffer-create',
+which looks up a buffer with a given name, creating a new one if
+necessary.  These operations correspond exactly with the symbol
+operations `intern-soft' and `intern', respectively.  You can also
+force a new buffer to be created using `generate-new-buffer', which
+takes a name and (if necessary) makes a unique name from this by
+appending a number, and then creates the buffer.  This is basically
+like the symbol operation `gensym'.
+
+
+File: internals.info,  Node: Markers and Extents,  Next: Bufbytes and Emchars,  Prev: Buffer Lists,  Up: Buffers and Textual Representation
+
+Markers and Extents
+===================
+
+   Among the things associated with a buffer are things that are
+logically attached to certain buffer positions.  This can be used to
+keep track of a buffer position when text is inserted and deleted, so
+that it remains at the same spot relative to the text around it; to
+assign properties to particular sections of text; etc.  There are two
+such objects that are useful in this regard: they are "markers" and
+"extents".
+
+   A "marker" is simply a flag placed at a particular buffer position,
+which is moved around as text is inserted and deleted.  Markers are
+used for all sorts of purposes, such as the `mark' that is the other
+end of textual regions to be cut, copied, etc.
+
+   An "extent" is similar to two markers plus some associated
+properties, and is used to keep track of regions in a buffer as text is
+inserted and deleted, and to add properties (e.g. fonts) to particular
+regions of text.  The external interface of extents is explained
+elsewhere.
+
+   The important thing here is that markers and extents simply contain
+buffer positions in them as integers, and every time text is inserted or
+deleted, these positions must be updated.  In order to minimize the
+amount of shuffling that needs to be done, the positions in markers and
+extents (there's one per marker, two per extent) are stored in Meminds.
+This means that they only need to be moved when the text is physically
+moved in memory; since the gap structure tries to minimize this, it also
+minimizes the number of marker and extent indices that need to be
+adjusted.  Look in `insdel.c' for the details of how this works.
+
+   One other important distinction is that markers are "temporary"
+while extents are "permanent".  This means that markers disappear as
+soon as there are no more pointers to them, and correspondingly, there
+is no way to determine what markers are in a buffer if you are just
+given the buffer.  Extents remain in a buffer until they are detached
+(which could happen as a result of text being deleted) or the buffer is
+deleted, and primitives do exist to enumerate the extents in a buffer.
+
+
+File: internals.info,  Node: Bufbytes and Emchars,  Next: The Buffer Object,  Prev: Markers and Extents,  Up: Buffers and Textual Representation
+
+Bufbytes and Emchars
+====================
+
+   Not yet documented.
+
+
+File: internals.info,  Node: The Buffer Object,  Prev: Bufbytes and Emchars,  Up: Buffers and Textual Representation
+
+The Buffer Object
+=================
+
+   Buffers contain fields not directly accessible by the Lisp
+programmer.  We describe them here, naming them by the names used in
+the C code.  Many are accessible indirectly in Lisp programs via Lisp
+primitives.
+
+`name'
+     The buffer name is a string that names the buffer.  It is
+     guaranteed to be unique.  *Note Buffer Names: (lispref)Buffer
+     Names.
+
+`save_modified'
+     This field contains the time when the buffer was last saved, as an
+     integer.  *Note Buffer Modification: (lispref)Buffer Modification.
+
+`modtime'
+     This field contains the modification time of the visited file.  It
+     is set when the file is written or read.  Every time the buffer is
+     written to the file, this field is compared to the modification
+     time of the file.  *Note Buffer Modification: (lispref)Buffer
+     Modification.
+
+`auto_save_modified'
+     This field contains the time when the buffer was last auto-saved.
+
+`last_window_start'
+     This field contains the `window-start' position in the buffer as of
+     the last time the buffer was displayed in a window.
+
+`undo_list'
+     This field points to the buffer's undo list.  *Note Undo:
+     (lispref)Undo.
+
+`syntax_table_v'
+     This field contains the syntax table for the buffer.  *Note Syntax
+     Tables: (lispref)Syntax Tables.
+
+`downcase_table'
+     This field contains the conversion table for converting text to
+     lower case.  *Note Case Tables: (lispref)Case Tables.
+
+`upcase_table'
+     This field contains the conversion table for converting text to
+     upper case.  *Note Case Tables: (lispref)Case Tables.
+
+`case_canon_table'
+     This field contains the conversion table for canonicalizing text
+     for case-folding search.  *Note Case Tables: (lispref)Case Tables.
+
+`case_eqv_table'
+     This field contains the equivalence table for case-folding search.
+     *Note Case Tables: (lispref)Case Tables.
+
+`display_table'
+     This field contains the buffer's display table, or `nil' if it
+     doesn't have one.  *Note Display Tables: (lispref)Display Tables.
+
+`markers'
+     This field contains the chain of all markers that currently point
+     into the buffer.  Deletion of text in the buffer, and motion of
+     the buffer's gap, must check each of these markers and perhaps
+     update it.  *Note Markers: (lispref)Markers.
+
+`backed_up'
+     This field is a flag that tells whether a backup file has been
+     made for the visited file of this buffer.
+
+`mark'
+     This field contains the mark for the buffer.  The mark is a marker,
+     hence it is also included on the list `markers'.  *Note The Mark:
+     (lispref)The Mark.
+
+`mark_active'
+     This field is non-`nil' if the buffer's mark is active.
+
+`local_var_alist'
+     This field contains the association list describing the variables
+     local in this buffer, and their values, with the exception of
+     local variables that have special slots in the buffer object.
+     (Those slots are omitted from this table.)  *Note Buffer-Local
+     Variables: (lispref)Buffer-Local Variables.
+
+`modeline_format'
+     This field contains a Lisp object which controls how to display
+     the mode line for this buffer.  *Note Modeline Format:
+     (lispref)Modeline Format.
+
+`base_buffer'
+     This field holds the buffer's base buffer (if it is an indirect
+     buffer), or `nil'.
+
+
+File: internals.info,  Node: MULE Character Sets and Encodings,  Next: The Lisp Reader and Compiler,  Prev: Buffers and Textual Representation,  Up: Top
+
+MULE Character Sets and Encodings
+*********************************
+
+   Recall that there are two primary ways that text is represented in
+XEmacs.  The "buffer" representation sees the text as a series of bytes
+(Bufbytes), with a variable number of bytes used per character.  The
+"character" representation sees the text as a series of integers
+(Emchars), one per character.  The character representation is a cleaner
+representation from a theoretical standpoint, and is thus used in many
+cases when lots of manipulations on a string need to be done.  However,
+the buffer representation is the standard representation used in both
+Lisp strings and buffers, and because of this, it is the "default"
+representation that text comes in.  The reason for using this
+representation is that it's compact and is compatible with ASCII.
+
+* Menu:
+
+* Character Sets::
+* Encodings::
+* Internal Mule Encodings::
+* CCL::
+
+
+File: internals.info,  Node: Character Sets,  Next: Encodings,  Up: MULE Character Sets and Encodings
+
+Character Sets
+==============
+
+   A character set (or "charset") is an ordered set of characters.  A
+particular character in a charset is indexed using one or more
+"position codes", which are non-negative integers.  The number of
+position codes needed to identify a particular character in a charset is
+called the "dimension" of the charset.  In XEmacs/Mule, all charsets
+have dimension 1 or 2, and the size of all charsets (except for a few
+special cases) is either 94, 96, 94 by 94, or 96 by 96.  The range of
+position codes used to index characters from any of these types of
+character sets is as follows:
+
+     Charset type            Position code 1         Position code 2
+     ------------------------------------------------------------
+     94                      33 - 126                N/A
+     96                      32 - 127                N/A
+     94x94                   33 - 126                33 - 126
+     96x96                   32 - 127                32 - 127
+
+   Note that in the above cases position codes do not start at an
+expected value such as 0 or 1.  The reason for this will become clear
+later.
+
+   For example, Latin-1 is a 96-character charset, and JISX0208 (the
+Japanese national character set) is a 94x94-character charset.
+
+   [Note that, although the ranges above define the _valid_ position
+codes for a charset, some of the slots in a particular charset may in
+fact be empty.  This is the case for JISX0208, for example, where (e.g.)
+all the slots whose first position code is in the range 118 - 127 are
+empty.]
+
+   There are three charsets that do not follow the above rules.  All of
+them have one dimension, and have ranges of position codes as follows:
+
+     Charset name            Position code 1
+     ------------------------------------
+     ASCII                   0 - 127
+     Control-1               0 - 31
+     Composite               0 - some large number
+
+   (The upper bound of the position code for composite characters has
+not yet been determined, but it will probably be at least 16,383).
+
+   ASCII is the union of two subsidiary character sets: Printing-ASCII
+(the printing ASCII character set, consisting of position codes 33 -
+126, like for a standard 94-character charset) and Control-ASCII (the
+non-printing characters that would appear in a binary file with codes 0
+- 32 and 127).
+
+   Control-1 contains the non-printing characters that would appear in a
+binary file with codes 128 - 159.
+
+   Composite contains characters that are generated by overstriking one
+or more characters from other charsets.
+
+   Note that some characters in ASCII, and all characters in Control-1,
+are "control" (non-printing) characters.  These have no printed
+representation but instead control some other function of the printing
+(e.g. TAB or 8 moves the current character position to the next tab
+stop).  All other characters in all charsets are "graphic" (printing)
+characters.
+
+   When a binary file is read in, the bytes in the file are assigned to
+character sets as follows:
+
+     Bytes           Character set           Range
+     --------------------------------------------------
+     0 - 127         ASCII                   0 - 127
+     128 - 159       Control-1               0 - 31
+     160 - 255       Latin-1                 32 - 127
+
+   This is a bit ad-hoc but gets the job done.
+
+
+File: internals.info,  Node: Encodings,  Next: Internal Mule Encodings,  Prev: Character Sets,  Up: MULE Character Sets and Encodings
+
+Encodings
+=========
+
+   An "encoding" is a way of numerically representing characters from
+one or more character sets.  If an encoding only encompasses one
+character set, then the position codes for the characters in that
+character set could be used directly.  This is not possible, however, if
+more than one character set is to be used in the encoding.
+
+   For example, the conversion detailed above between bytes in a binary
+file and characters is effectively an encoding that encompasses the
+three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit
+bytes.
+
+   Thus, an encoding can be viewed as a way of encoding characters from
+a specified group of character sets using a stream of bytes, each of
+which contains a fixed number of bits (but not necessarily 8, as in the
+common usage of "byte").
+
+   Here are descriptions of a couple of common encodings:
+
+* Menu:
+
+* Japanese EUC (Extended Unix Code)::
+* JIS7::
+
+
+File: internals.info,  Node: Japanese EUC (Extended Unix Code),  Next: JIS7,  Up: Encodings
+
+Japanese EUC (Extended Unix Code)
+---------------------------------
+
+   This encompasses the character sets Printing-ASCII,
+Japanese-JISX0201, and Japanese-JISX0208-Kana (half-width katakana, the
+right half of JISX0201).  It uses 8-bit bytes.
+
+   Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
+charsets, while Japanese-JISX0208 is a 94x94-character charset.
+
+   The encoding is as follows:
+
+     Character set            Representation (PC=position-code)
+     -------------            --------------
+     Printing-ASCII           PC1
+     Japanese-JISX0201-Kana   0x8E       | PC1 + 0x80
+     Japanese-JISX0208        PC1 + 0x80 | PC2 + 0x80
+     Japanese-JISX0212        PC1 + 0x80 | PC2 + 0x80
+
+
+File: internals.info,  Node: JIS7,  Prev: Japanese EUC (Extended Unix Code),  Up: Encodings
+
+JIS7
+----
+
+   This encompasses the character sets Printing-ASCII,
+Japanese-JISX0201-Roman (the left half of JISX0201; this character set
+is very similar to Printing-ASCII and is a 94-character charset),
+Japanese-JISX0208, and Japanese-JISX0201-Kana.  It uses 7-bit bytes.
+
+   Unlike Japanese EUC, this is a "modal" encoding, which means that
+there are multiple states that the encoding can be in, which affect how
+the bytes are to be interpreted.  Special sequences of bytes (called
+"escape sequences") are used to change states.
+
+   The encoding is as follows:
+
+     Character set              Representation (PC=position-code)
+     -------------              --------------
+     Printing-ASCII             PC1
+     Japanese-JISX0201-Roman    PC1
+     Japanese-JISX0201-Kana     PC1
+     Japanese-JISX0208          PC1 PC2
+     
+     
+     Escape sequence   ASCII equivalent   Meaning
+     ---------------   ----------------   -------
+     0x1B 0x28 0x4A    ESC ( J            invoke Japanese-JISX0201-Roman
+     0x1B 0x28 0x49    ESC ( I            invoke Japanese-JISX0201-Kana
+     0x1B 0x24 0x42    ESC $ B            invoke Japanese-JISX0208
+     0x1B 0x28 0x42    ESC ( B            invoke Printing-ASCII
+
+   Initially, Printing-ASCII is invoked.
+
+
+File: internals.info,  Node: Internal Mule Encodings,  Next: CCL,  Prev: Encodings,  Up: MULE Character Sets and Encodings
+
+Internal Mule Encodings
+=======================
+
+   In XEmacs/Mule, each character set is assigned a unique number,
+called a "leading byte".  This is used in the encodings of a character.
+Leading bytes are in the range 0x80 - 0xFF (except for ASCII, which has
+a leading byte of 0), although some leading bytes are reserved.
+
+   Charsets whose leading byte is in the range 0x80 - 0x9F are called
+"official" and are used for built-in charsets.  Other charsets are
+called "private" and have leading bytes in the range 0xA0 - 0xFF; these
+are user-defined charsets.
+
+   More specifically:
+
+     Character set           Leading byte
+     -------------           ------------
+     ASCII                   0
+     Composite               0x80
+     Dimension-1 Official    0x81 - 0x8D
+                               (0x8E is free)
+     Control-1               0x8F
+     Dimension-2 Official    0x90 - 0x99
+                               (0x9A - 0x9D are free;
+                                0x9E and 0x9F are reserved)
+     Dimension-1 Private     0xA0 - 0xEF
+     Dimension-2 Private     0xF0 - 0xFF
+
+   There are two internal encodings for characters in XEmacs/Mule.  One
+is called "string encoding" and is an 8-bit encoding that is used for
+representing characters in a buffer or string.  It uses 1 to 4 bytes per
+character.  The other is called "character encoding" and is a 19-bit
+encoding that is used for representing characters individually in a
+variable.
+
+   (In the following descriptions, we'll ignore composite characters for
+the moment.  We also give a general (structural) overview first,
+followed later by the exact details.)
+
+* Menu:
+
+* Internal String Encoding::
+* Internal Character Encoding::
+
+
+File: internals.info,  Node: Internal String Encoding,  Next: Internal Character Encoding,  Up: Internal Mule Encodings
+
+Internal String Encoding
+------------------------
+
+   ASCII characters are encoded using their position code directly.
+Other characters are encoded using their leading byte followed by their
+position code(s) with the high bit set.  Characters in private character
+sets have their leading byte prefixed with a "leading byte prefix",
+which is either 0x9E or 0x9F. (No character sets are ever assigned these
+leading bytes.) Specifically:
+
+     Character set           Encoding (PC=position-code, LB=leading-byte)
+     -------------           --------
+     ASCII                   PC-1 |
+     Control-1               LB   |  PC1 + 0xA0 |
+     Dimension-1 official    LB   |  PC1 + 0x80 |
+     Dimension-1 private     0x9E |  LB         | PC1 + 0x80 |
+     Dimension-2 official    LB   |  PC1 + 0x80 | PC2 + 0x80 |
+     Dimension-2 private     0x9F |  LB         | PC1 + 0x80 | PC2 + 0x80
+
+   The basic characteristic of this encoding is that the first byte of
+all characters is in the range 0x00 - 0x9F, and the second and
+following bytes of all characters is in the range 0xA0 - 0xFF.  This
+means that it is impossible to get out of sync, or more specifically:
+
+  1. Given any byte position, the beginning of the character it is
+     within can be determined in constant time.
+
+  2. Given any byte position at the beginning of a character, the
+     beginning of the next character can be determined in constant time.
+
+  3. Given any byte position at the beginning of a character, the
+     beginning of the previous character can be determined in constant
+     time.
+
+  4. Textual searches can simply treat encoded strings as if they were
+     encoded in a one-byte-per-character fashion rather than the actual
+     multi-byte encoding.
+
+   None of the standard non-modal encodings meet all of these
+conditions.  For example, EUC satisfies only (2) and (3), while
+Shift-JIS and Big5 (not yet described) satisfy only (2). (All non-modal
+encodings must satisfy (2), in order to be unambiguous.)
+
+
+File: internals.info,  Node: Internal Character Encoding,  Prev: Internal String Encoding,  Up: Internal Mule Encodings
+
+Internal Character Encoding
+---------------------------
+
+   One 19-bit word represents a single character.  The word is
+separated into three fields:
+
+     Bit number:     18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
+                     <------------> <------------------> <------------------>
+     Field:                1                  2                    3
+
+   Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5
+bits.
+
+     Character set           Field 1         Field 2         Field 3
+     -------------           -------         -------         -------
+     ASCII                      0               0              PC1
+        range:                                                   (00 - 7F)
+     Control-1                  0               1              PC1
+        range:                                                   (00 - 1F)
+     Dimension-1 official       0            LB - 0x80         PC1
+        range:                                    (01 - 0D)      (20 - 7F)
+     Dimension-1 private        0            LB - 0x80         PC1
+        range:                                    (20 - 6F)      (20 - 7F)
+     Dimension-2 official    LB - 0x8F         PC1             PC2
+        range:                    (01 - 0A)       (20 - 7F)      (20 - 7F)
+     Dimension-2 private     LB - 0xE1         PC1             PC2
+        range:                    (0F - 1E)       (20 - 7F)      (20 - 7F)
+     Composite                 0x1F             ?               ?
+
+   Note that character codes 0 - 255 are the same as the "binary
+encoding" described above.
+
+
+File: internals.info,  Node: CCL,  Prev: Internal Mule Encodings,  Up: MULE Character Sets and Encodings
+
+CCL
+===
+
+     CCL PROGRAM SYNTAX:
+          CCL_PROGRAM := (CCL_MAIN_BLOCK
+                          [ CCL_EOF_BLOCK ])
+     
+          CCL_MAIN_BLOCK := CCL_BLOCK
+          CCL_EOF_BLOCK := CCL_BLOCK
+     
+          CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
+          STATEMENT :=
+                  SET | IF | BRANCH | LOOP | REPEAT | BREAK
+                  | READ | WRITE
+     
+          SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
+                 | INT-OR-CHAR
+     
+          EXPRESSION := ARG | (EXPRESSION OP ARG)
+     
+          IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK)
+          BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
+          LOOP := (loop STATEMENT [STATEMENT ...])
+          BREAK := (break)
+          REPEAT := (repeat)
+                  | (write-repeat [REG | INT-OR-CHAR | string])
+                  | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?)
+          READ := (read REG) | (read REG REG)
+                  | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK)
+                  | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
+          WRITE := (write REG) | (write REG REG)
+                  | (write INT-OR-CHAR) | (write STRING) | STRING
+                  | (write REG ARRAY)
+          END := (end)
+     
+          REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
+          ARG := REG | INT-OR-CHAR
+          OP :=   + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
+                  | < | > | == | <= | >= | !=
+          SELF_OP :=
+                  += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
+          ARRAY := '[' INT-OR-CHAR ... ']'
+          INT-OR-CHAR := INT | CHAR
+     
+     MACHINE CODE:
+     
+     The machine code consists of a vector of 32-bit words.
+     The first such word specifies the start of the EOF section of the code;
+     this is the code executed to handle any stuff that needs to be done
+     (e.g. designating back to ASCII and left-to-right mode) after all
+     other encoded/decoded data has been written out.  This is not used for
+     charset CCL programs.
+     
+     REGISTER: 0..7  -- referred by RRR or rrr
+     
+     OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
+             TTTTT (5-bit): operator type
+             RRR (3-bit): register number
+             XXXXXXXXXXXXXXXX (15-bit):
+                     CCCCCCCCCCCCCCC: constant or address
+                     000000000000rrr: register number
+     
+     AAAA:   00000 +
+             00001 -
+             00010 *
+             00011 /
+             00100 %
+             00101 &
+             00110 |
+             00111 ~
+     
+             01000 <<
+             01001 >>
+             01010 <8
+             01011 >8
+             01100 //
+             01101 not used
+             01110 not used
+             01111 not used
+     
+             10000 <
+             10001 >
+             10010 ==
+             10011 <=
+             10100 >=
+             10101 !=
+     
+     OPERATORS:      TTTTT RRR XX..
+     
+     SetCS:          00000 RRR C...C      RRR = C...C
+     SetCL:          00001 RRR .....      RRR = c...c
+                     c.............c
+     SetR:           00010 RRR ..rrr      RRR = rrr
+     SetA:           00011 RRR ..rrr      RRR = array[rrr]
+                     C.............C      size of array = C...C
+                     c.............c      contents = c...c
+     
+     Jump:           00100 000 c...c      jump to c...c
+     JumpCond:       00101 RRR c...c      if (!RRR) jump to c...c
+     WriteJump:      00110 RRR c...c      Write1 RRR, jump to c...c
+     WriteReadJump:  00111 RRR c...c      Write1, Read1 RRR, jump to c...c
+     WriteCJump:     01000 000 c...c      Write1 C...C, jump to c...c
+                     C...C
+     WriteCReadJump: 01001 RRR c...c      Write1 C...C, Read1 RRR,
+                     C.............C      and jump to c...c
+     WriteSJump:     01010 000 c...c      WriteS, jump to c...c
+                     C.............C
+                     S.............S
+                     ...
+     WriteSReadJump: 01011 RRR c...c      WriteS, Read1 RRR, jump to c...c
+                     C.............C
+                     S.............S
+                     ...
+     WriteAReadJump: 01100 RRR c...c      WriteA, Read1 RRR, jump to c...c
+                     C.............C      size of array = C...C
+                     c.............c      contents = c...c
+                     ...
+     Branch:         01101 RRR C...C      if (RRR >= 0 && RRR < C..)
+                     c.............c      branch to (RRR+1)th address
+     Read1:          01110 RRR ...        read 1-byte to RRR
+     Read2:          01111 RRR ..rrr      read 2-byte to RRR and rrr
+     ReadBranch:     10000 RRR C...C      Read1 and Branch
+                     c.............c
+                     ...
+     Write1:         10001 RRR .....      write 1-byte RRR
+     Write2:         10010 RRR ..rrr      write 2-byte RRR and rrr
+     WriteC:         10011 000 .....      write 1-char C...CC
+                     C.............C
+     WriteS:         10100 000 .....      write C..-byte of string
+                     C.............C
+                     S.............S
+                     ...
+     WriteA:         10101 RRR .....      write array[RRR]
+                     C.............C      size of array = C...C
+                     c.............c      contents = c...c
+                     ...
+     End:            10110 000 .....      terminate the execution
+     
+     SetSelfCS:      10111 RRR C...C      RRR AAAAA= C...C
+                     ..........AAAAA
+     SetSelfCL:      11000 RRR .....      RRR AAAAA= c...c
+                     c.............c
+                     ..........AAAAA
+     SetSelfR:       11001 RRR ..Rrr      RRR AAAAA= rrr
+                     ..........AAAAA
+     SetExprCL:      11010 RRR ..Rrr      RRR = rrr AAAAA c...c
+                     c.............c
+                     ..........AAAAA
+     SetExprR:       11011 RRR ..rrr      RRR = rrr AAAAA Rrr
+                     ............Rrr
+                     ..........AAAAA
+     JumpCondC:      11100 RRR c...c      if !(RRR AAAAA C..) jump to c...c
+                     C.............C
+                     ..........AAAAA
+     JumpCondR:      11101 RRR c...c      if !(RRR AAAAA rrr) jump to c...c
+                     ............rrr
+                     ..........AAAAA
+     ReadJumpCondC:  11110 RRR c...c      Read1 and JumpCondC
+                     C.............C
+                     ..........AAAAA
+     ReadJumpCondR:  11111 RRR c...c      Read1 and JumpCondR
+                     ............rrr
+                     ..........AAAAA
+
+
+File: internals.info,  Node: The Lisp Reader and Compiler,  Next: Lstreams,  Prev: MULE Character Sets and Encodings,  Up: Top
+
+The Lisp Reader and Compiler
+****************************
+
+   Not yet documented.
+
+
+File: internals.info,  Node: Lstreams,  Next: Consoles; Devices; Frames; Windows,  Prev: The Lisp Reader and Compiler,  Up: Top
+
+Lstreams
+********
+
+   An "lstream" is an internal Lisp object that provides a generic
+buffering stream implementation.  Conceptually, you send data to the
+stream or read data from the stream, not caring what's on the other end
+of the stream.  The other end could be another stream, a file
+descriptor, a stdio stream, a fixed block of memory, a reallocating
+block of memory, etc.  The main purpose of the stream is to provide a
+standard interface and to do buffering.  Macros are defined to read or
+write characters, so the calling functions do not have to worry about
+blocking data together in order to achieve efficiency.
+
+* Menu:
+
+* Creating an Lstream::         Creating an lstream object.
+* Lstream Types::               Different sorts of things that are streamed.
+* Lstream Functions::           Functions for working with lstreams.
+* Lstream Methods::             Creating new lstream types.
+
+
+File: internals.info,  Node: Creating an Lstream,  Next: Lstream Types,  Up: Lstreams
+
+Creating an Lstream
+===================
+
+   Lstreams come in different types, depending on what is being
+interfaced to.  Although the primitive for creating new lstreams is
+`Lstream_new()', generally you do not call this directly.  Instead, you
+call some type-specific creation function, which creates the lstream
+and initializes it as appropriate for the particular type.
+
+   All lstream creation functions take a MODE argument, specifying what
+mode the lstream should be opened as.  This controls whether the
+lstream is for input and output, and optionally whether data should be
+blocked up in units of MULE characters.  Note that some types of
+lstreams can only be opened for input; others only for output; and
+others can be opened either way.  #### Richard Mlynarik thinks that
+there should be a strict separation between input and output streams,
+and he's probably right.
+
+   MODE is a string, one of
+
+`"r"'
+     Open for reading.
+
+`"w"'
+     Open for writing.
+
+`"rc"'
+     Open for reading, but "read" never returns partial MULE characters.
+
+`"wc"'
+     Open for writing, but never writes partial MULE characters.
+
+
+File: internals.info,  Node: Lstream Types,  Next: Lstream Functions,  Prev: Creating an Lstream,  Up: Lstreams
+
+Lstream Types
+=============
+
+stdio
+
+filedesc
+
+lisp-string
+
+fixed-buffer
+
+resizing-buffer
+
+dynarr
+
+lisp-buffer
+
+print
+
+decoding
+
+encoding
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-8'
Index: ././info/internals.info-8
--- ././info/internals.info-8	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-8	Thu May 17 23:26:54 2001
@@ -0,0 +1,1194 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Lstream Functions,  Next: Lstream Methods,  Prev: Lstream Types,  Up: Lstreams
+
+Lstream Functions
+=================
+
+ - Function: Lstream * Lstream_new (Lstream_implementation *IMP, const
+          char *MODE)
+     Allocate and return a new Lstream.  This function is not really
+     meant to be called directly; rather, each stream type should
+     provide its own stream creation function, which creates the stream
+     and does any other necessary creation stuff (e.g. opening a file).
+
+ - Function: void Lstream_set_buffering (Lstream *LSTR,
+          Lstream_buffering BUFFERING, int BUFFERING_SIZE)
+     Change the buffering of a stream.  See `lstream.h'.  By default the
+     buffering is `STREAM_BLOCK_BUFFERED'.
+
+ - Function: int Lstream_flush (Lstream *LSTR)
+     Flush out any pending unwritten data in the stream.  Clear any
+     buffered input data.  Returns 0 on success, -1 on error.
+
+ - Macro: int Lstream_putc (Lstream *STREAM, int C)
+     Write out one byte to the stream.  This is a macro and so it is
+     very efficient.  The C argument is only evaluated once but the
+     STREAM argument is evaluated more than once.  Returns 0 on
+     success, -1 on error.
+
+ - Macro: int Lstream_getc (Lstream *STREAM)
+     Read one byte from the stream.  This is a macro and so it is very
+     efficient.  The STREAM argument is evaluated more than once.
+     Return value is -1 for EOF or error.
+
+ - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
+     Push one byte back onto the input queue.  This will be the next
+     byte read from the stream.  Any number of bytes can be pushed back
+     and will be read in the reverse order they were pushed back--most
+     recent first. (This is necessary for consistency--if there are a
+     number of bytes that have been unread and I read and unread a
+     byte, it needs to be the first to be read again.) This is a macro
+     and so it is very efficient.  The C argument is only evaluated
+     once but the STREAM argument is evaluated more than once.
+
+ - Function: int Lstream_fputc (Lstream *STREAM, int C)
+ - Function: int Lstream_fgetc (Lstream *STREAM)
+ - Function: void Lstream_fungetc (Lstream *STREAM, int C)
+     Function equivalents of the above macros.
+
+ - Function: ssize_t Lstream_read (Lstream *STREAM, void *DATA, size_t
+          SIZE)
+     Read SIZE bytes of DATA from the stream.  Return the number of
+     bytes read.  0 means EOF. -1 means an error occurred and no bytes
+     were read.
+
+ - Function: ssize_t Lstream_write (Lstream *STREAM, void *DATA, size_t
+          SIZE)
+     Write SIZE bytes of DATA to the stream.  Return the number of
+     bytes written.  -1 means an error occurred and no bytes were
+     written.
+
+ - Function: void Lstream_unread (Lstream *STREAM, void *DATA, size_t
+          SIZE)
+     Push back SIZE bytes of DATA onto the input queue.  The next call
+     to `Lstream_read()' with the same size will read the same bytes
+     back.  Note that this will be the case even if there is other
+     pending unread data.
+
+ - Function: int Lstream_close (Lstream *STREAM)
+     Close the stream.  All data will be flushed out.
+
+ - Function: void Lstream_reopen (Lstream *STREAM)
+     Reopen a closed stream.  This enables I/O on it again.  This is not
+     meant to be called except from a wrapper routine that reinitializes
+     variables and such--the close routine may well have freed some
+     necessary storage structures, for example.
+
+ - Function: void Lstream_rewind (Lstream *STREAM)
+     Rewind the stream to the beginning.
+
+
+File: internals.info,  Node: Lstream Methods,  Prev: Lstream Functions,  Up: Lstreams
+
+Lstream Methods
+===============
+
+ - Lstream Method: ssize_t reader (Lstream *STREAM, unsigned char
+          *DATA, size_t SIZE)
+     Read some data from the stream's end and store it into DATA, which
+     can hold SIZE bytes.  Return the number of bytes read.  A return
+     value of 0 means no bytes can be read at this time.  This may be
+     because of an EOF, or because there is a granularity greater than
+     one byte that the stream imposes on the returned data, and SIZE is
+     less than this granularity. (This will happen frequently for
+     streams that need to return whole characters, because
+     `Lstream_read()' calls the reader function repeatedly until it has
+     the number of bytes it wants or until 0 is returned.)  The lstream
+     functions do not treat a 0 return as EOF or do anything special;
+     however, the calling function will interpret any 0 it gets back as
+     EOF.  This will normally not happen unless the caller calls
+     `Lstream_read()' with a very small size.
+
+     This function can be `NULL' if the stream is output-only.
+
+ - Lstream Method: ssize_t writer (Lstream *STREAM, const unsigned char
+          *DATA, size_t SIZE)
+     Send some data to the stream's end.  Data to be sent is in DATA
+     and is SIZE bytes.  Return the number of bytes sent.  This
+     function can send and return fewer bytes than is passed in; in that
+     case, the function will just be called again until there is no
+     data left or 0 is returned.  A return value of 0 means that no
+     more data can be currently stored, but there is no error; the data
+     will be squirreled away until the writer can accept data. (This is
+     useful, e.g., if you're dealing with a non-blocking file
+     descriptor and are getting `EWOULDBLOCK' errors.)  This function
+     can be `NULL' if the stream is input-only.
+
+ - Lstream Method: int rewinder (Lstream *STREAM)
+     Rewind the stream.  If this is `NULL', the stream is not seekable.
+
+ - Lstream Method: int seekable_p (Lstream *STREAM)
+     Indicate whether this stream is seekable--i.e. it can be rewound.
+     This method is ignored if the stream does not have a rewind
+     method.  If this method is not present, the result is determined
+     by whether a rewind method is present.
+
+ - Lstream Method: int flusher (Lstream *STREAM)
+     Perform any additional operations necessary to flush the data in
+     this stream.
+
+ - Lstream Method: int pseudo_closer (Lstream *STREAM)
+
+ - Lstream Method: int closer (Lstream *STREAM)
+     Perform any additional operations necessary to close this stream
+     down.  May be `NULL'.  This function is called when
+     `Lstream_close()' is called or when the stream is
+     garbage-collected.  When this function is called, all pending data
+     in the stream will already have been written out.
+
+ - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
+          (*MARKFUN) (Lisp_Object))
+     Mark this object for garbage collection.  Same semantics as a
+     standard `Lisp_Object' marker.  This function can be `NULL'.
+
+
+File: internals.info,  Node: Consoles; Devices; Frames; Windows,  Next: The Redisplay Mechanism,  Prev: Lstreams,  Up: Top
+
+Consoles; Devices; Frames; Windows
+**********************************
+
+* Menu:
+
+* Introduction to Consoles; Devices; Frames; Windows::
+* Point::
+* Window Hierarchy::
+* The Window Object::
+
+
+File: internals.info,  Node: Introduction to Consoles; Devices; Frames; Windows,  Next: Point,  Up: Consoles; Devices; Frames; Windows
+
+Introduction to Consoles; Devices; Frames; Windows
+==================================================
+
+   A window-system window that you see on the screen is called a
+"frame" in Emacs terminology.  Each frame is subdivided into one or
+more non-overlapping panes, called (confusingly) "windows".  Each
+window displays the text of a buffer in it. (See above on Buffers.) Note
+that buffers and windows are independent entities: Two or more windows
+can be displaying the same buffer (potentially in different locations),
+and a buffer can be displayed in no windows.
+
+   A single display screen that contains one or more frames is called a
+"display".  Under most circumstances, there is only one display.
+However, more than one display can exist, for example if you have a
+"multi-headed" console, i.e. one with a single keyboard but multiple
+displays. (Typically in such a situation, the various displays act like
+one large display, in that the mouse is only in one of them at a time,
+and moving the mouse off of one moves it into another.) In some cases,
+the different displays will have different characteristics, e.g. one
+color and one mono.
+
+   XEmacs can display frames on multiple displays.  It can even deal
+simultaneously with frames on multiple keyboards (called "consoles" in
+XEmacs terminology).  Here is one case where this might be useful: You
+are using XEmacs on your workstation at work, and leave it running.
+Then you go home and dial in on a TTY line, and you can use the
+already-running XEmacs process to display another frame on your local
+TTY.
+
+   Thus, there is a hierarchy console -> display -> frame -> window.
+There is a separate Lisp object type for each of these four concepts.
+Furthermore, there is logically a "selected console", "selected
+display", "selected frame", and "selected window".  Each of these
+objects is distinguished in various ways, such as being the default
+object for various functions that act on objects of that type.  Note
+that every containing object remembers the "selected" object among the
+objects that it contains: e.g. not only is there a selected window, but
+every frame remembers the last window in it that was selected, and
+changing the selected frame causes the remembered window within it to
+become the selected window.  Similar relationships apply for consoles
+to devices and devices to frames.
+
+
+File: internals.info,  Node: Point,  Next: Window Hierarchy,  Prev: Introduction to Consoles; Devices; Frames; Windows,  Up: Consoles; Devices; Frames; Windows
+
+Point
+=====
+
+   Recall that every buffer has a current insertion position, called
+"point".  Now, two or more windows may be displaying the same buffer,
+and the text cursor in the two windows (i.e. `point') can be in two
+different places.  You may ask, how can that be, since each buffer has
+only one value of `point'?  The answer is that each window also has a
+value of `point' that is squirreled away in it.  There is only one
+selected window, and the value of "point" in that buffer corresponds to
+that window.  When the selected window is changed from one window to
+another displaying the same buffer, the old value of `point' is stored
+into the old window's "point" and the value of `point' from the new
+window is retrieved and made the value of `point' in the buffer.  This
+means that `window-point' for the selected window is potentially
+inaccurate, and if you want to retrieve the correct value of `point'
+for a window, you must special-case on the selected window and retrieve
+the buffer's point instead.  This is related to why
+`save-window-excursion' does not save the selected window's value of
+`point'.
+
+
+File: internals.info,  Node: Window Hierarchy,  Next: The Window Object,  Prev: Point,  Up: Consoles; Devices; Frames; Windows
+
+Window Hierarchy
+================
+
+   If a frame contains multiple windows (panes), they are always created
+by splitting an existing window along the horizontal or vertical axis.
+Terminology is a bit confusing here: to "split a window horizontally"
+means to create two side-by-side windows, i.e. to make a _vertical_ cut
+in a window.  Likewise, to "split a window vertically" means to create
+two windows, one above the other, by making a _horizontal_ cut.
+
+   If you split a window and then split again along the same axis, you
+will end up with a number of panes all arranged along the same axis.
+The precise way in which the splits were made should not be important,
+and this is reflected internally.  Internally, all windows are arranged
+in a tree, consisting of two types of windows, "combination" windows
+(which have children, and are covered completely by those children) and
+"leaf" windows, which have no children and are visible.  Every
+combination window has two or more children, all arranged along the same
+axis.  There are (logically) two subtypes of windows, depending on
+whether their children are horizontally or vertically arrayed.  There is
+always one root window, which is either a leaf window (if the frame
+contains only one window) or a combination window (if the frame contains
+more than one window).  In the latter case, the root window will have
+two or more children, either horizontally or vertically arrayed, and
+each of those children will be either a leaf window or another
+combination window.
+
+   Here are some rules:
+
+  1. Horizontal combination windows can never have children that are
+     horizontal combination windows; same for vertical.
+
+  2. Only leaf windows can be split (obviously) and this splitting does
+     one of two things: (a) turns the leaf window into a combination
+     window and creates two new leaf children, or (b) turns the leaf
+     window into one of the two new leaves and creates the other leaf.
+     Rule (1) dictates which of these two outcomes happens.
+
+  3. Every combination window must have at least two children.
+
+  4. Leaf windows can never become combination windows.  They can be
+     deleted, however.  If this results in a violation of (3), the
+     parent combination window also gets deleted.
+
+  5. All functions that accept windows must be prepared to accept
+     combination windows, and do something sane (e.g. signal an error
+     if so).  Combination windows _do_ escape to the Lisp level.
+
+  6. All windows have three fields governing their contents: these are
+     "hchild" (a list of horizontally-arrayed children), "vchild" (a
+     list of vertically-arrayed children), and "buffer" (the buffer
+     contained in a leaf window).  Exactly one of these will be
+     non-`nil'.  Remember that "horizontally-arrayed" means
+     "side-by-side" and "vertically-arrayed" means "one above the
+     other".
+
+  7. Leaf windows also have markers in their `start' (the first buffer
+     position displayed in the window) and `pointm' (the window's
+     stashed value of `point'--see above) fields, while combination
+     windows have `nil' in these fields.
+
+  8. The list of children for a window is threaded through the `next'
+     and `prev' fields of each child window.
+
+  9. *Deleted windows can be undeleted*.  This happens as a result of
+     restoring a window configuration, and is unlike frames, displays,
+     and consoles, which, once deleted, can never be restored.
+     Deleting a window does nothing except set a special `dead' bit to
+     1 and clear out the `next', `prev', `hchild', and `vchild' fields,
+     for GC purposes.
+
+ 10. Most frames actually have two top-level windows--one for the
+     minibuffer and one (the "root") for everything else.  The modeline
+     (if present) separates these two.  The `next' field of the root
+     points to the minibuffer, and the `prev' field of the minibuffer
+     points to the root.  The other `next' and `prev' fields are `nil',
+     and the frame points to both of these windows.  Minibuffer-less
+     frames have no minibuffer window, and the `next' and `prev' of the
+     root window are `nil'.  Minibuffer-only frames have no root
+     window, and the `next' of the minibuffer window is `nil' but the
+     `prev' points to itself. (#### This is an artifact that should be
+     fixed.)
+
+
+File: internals.info,  Node: The Window Object,  Prev: Window Hierarchy,  Up: Consoles; Devices; Frames; Windows
+
+The Window Object
+=================
+
+   Windows have the following accessible fields:
+
+`frame'
+     The frame that this window is on.
+
+`mini_p'
+     Non-`nil' if this window is a minibuffer window.
+
+`buffer'
+     The buffer that the window is displaying.  This may change often
+     during the life of the window.
+
+`dedicated'
+     Non-`nil' if this window is dedicated to its buffer.
+
+`pointm'
+     This is the value of point in the current buffer when this window
+     is selected; when it is not selected, it retains its previous
+     value.
+
+`start'
+     The position in the buffer that is the first character to be
+     displayed in the window.
+
+`force_start'
+     If this flag is non-`nil', it says that the window has been
+     scrolled explicitly by the Lisp program.  This affects what the
+     next redisplay does if point is off the screen: instead of
+     scrolling the window to show the text around point, it moves point
+     to a location that is on the screen.
+
+`last_modified'
+     The `modified' field of the window's buffer, as of the last time a
+     redisplay completed in this window.
+
+`last_point'
+     The buffer's value of point, as of the last time a redisplay
+     completed in this window.
+
+`left'
+     This is the left-hand edge of the window, measured in columns.
+     (The leftmost column on the screen is column 0.)
+
+`top'
+     This is the top edge of the window, measured in lines.  (The top
+     line on the screen is line 0.)
+
+`height'
+     The height of the window, measured in lines.
+
+`width'
+     The width of the window, measured in columns.
+
+`next'
+     This is the window that is the next in the chain of siblings.  It
+     is `nil' in a window that is the rightmost or bottommost of a
+     group of siblings.
+
+`prev'
+     This is the window that is the previous in the chain of siblings.
+     It is `nil' in a window that is the leftmost or topmost of a group
+     of siblings.
+
+`parent'
+     Internally, XEmacs arranges windows in a tree; each group of
+     siblings has a parent window whose area includes all the siblings.
+     This field points to a window's parent.
+
+     Parent windows do not display buffers, and play little role in
+     display except to shape their child windows.  Emacs Lisp programs
+     usually have no access to the parent windows; they operate on the
+     windows at the leaves of the tree, which actually display buffers.
+
+`hscroll'
+     This is the number of columns that the display in the window is
+     scrolled horizontally to the left.  Normally, this is 0.
+
+`use_time'
+     This is the last time that the window was selected.  The function
+     `get-lru-window' uses this field.
+
+`display_table'
+     The window's display table, or `nil' if none is specified for it.
+
+`update_mode_line'
+     Non-`nil' means this window's mode line needs to be updated.
+
+`base_line_number'
+     The line number of a certain position in the buffer, or `nil'.
+     This is used for displaying the line number of point in the mode
+     line.
+
+`base_line_pos'
+     The position in the buffer for which the line number is known, or
+     `nil' meaning none is known.
+
+`region_showing'
+     If the region (or part of it) is highlighted in this window, this
+     field holds the mark position that made one end of that region.
+     Otherwise, this field is `nil'.
+
+
+File: internals.info,  Node: The Redisplay Mechanism,  Next: Extents,  Prev: Consoles; Devices; Frames; Windows,  Up: Top
+
+The Redisplay Mechanism
+***********************
+
+   The redisplay mechanism is one of the most complicated sections of
+XEmacs, especially from a conceptual standpoint.  This is doubly so
+because, unlike for the basic aspects of the Lisp interpreter, the
+computer science theories of how to efficiently handle redisplay are not
+well-developed.
+
+   When working with the redisplay mechanism, remember the Golden Rules
+of Redisplay:
+
+  1. It Is Better To Be Correct Than Fast.
+
+  2. Thou Shalt Not Run Elisp From Within Redisplay.
+
+  3. It Is Better To Be Fast Than Not To Be.
+
+* Menu:
+
+* Critical Redisplay Sections::
+* Line Start Cache::
+* Redisplay Piece by Piece::
+
+
+File: internals.info,  Node: Critical Redisplay Sections,  Next: Line Start Cache,  Up: The Redisplay Mechanism
+
+Critical Redisplay Sections
+===========================
+
+   Within this section, we are defenseless and assume that the
+following cannot happen:
+
+  1. garbage collection
+
+  2. Lisp code evaluation
+
+  3. frame size changes
+
+   We ensure (3) by calling `hold_frame_size_changes()', which will
+cause any pending frame size changes to get put on hold till after the
+end of the critical section.  (1) follows automatically if (2) is met.
+#### Unfortunately, there are some places where Lisp code can be called
+within this section.  We need to remove them.
+
+   If `Fsignal()' is called during this critical section, we will
+`abort()'.
+
+   If garbage collection is called during this critical section, we
+simply return. #### We should abort instead.
+
+   #### If a frame-size change does occur we should probably actually
+be preempting redisplay.
+
+
+File: internals.info,  Node: Line Start Cache,  Next: Redisplay Piece by Piece,  Prev: Critical Redisplay Sections,  Up: The Redisplay Mechanism
+
+Line Start Cache
+================
+
+   The traditional scrolling code in Emacs breaks in a variable height
+world.  It depends on the key assumption that the number of lines that
+can be displayed at any given time is fixed.  This led to a complete
+separation of the scrolling code from the redisplay code.  In order to
+fully support variable height lines, the scrolling code must actually be
+tightly integrated with redisplay.  Only redisplay can determine how
+many lines will be displayed on a screen for any given starting point.
+
+   What is ideally wanted is a complete list of the starting buffer
+position for every possible display line of a buffer along with the
+height of that display line.  Maintaining such a full list would be very
+expensive.  We settle for having it include information for all areas
+which we happen to generate anyhow (i.e. the region currently being
+displayed) and for those areas we need to work with.
+
+   In order to ensure that the cache accurately represents what
+redisplay would actually show, it is necessary to invalidate it in many
+situations.  If the buffer changes, the starting positions may no longer
+be correct.  If a face or an extent has changed then the line heights
+may have altered.  These events happen frequently enough that the cache
+can end up being constantly disabled.  With this potentially constant
+invalidation when is the cache ever useful?
+
+   Even if the cache is invalidated before every single usage, it is
+necessary.  Scrolling often requires knowledge about display lines which
+are actually above or below the visible region.  The cache provides a
+convenient light-weight method of storing this information for multiple
+display regions.  This knowledge is necessary for the scrolling code to
+always obey the First Golden Rule of Redisplay.
+
+   If the cache already contains all of the information that the
+scrolling routines happen to need so that it doesn't have to go
+generate it, then we are able to obey the Third Golden Rule of
+Redisplay.  The first thing we do to help out the cache is to always
+add the displayed region.  This region had to be generated anyway, so
+the cache ends up getting the information basically for free.  In those
+cases where a user is simply scrolling around viewing a buffer there is
+a high probability that this is sufficient to always provide the needed
+information.  The second thing we can do is be smart about invalidating
+the cache.
+
+   TODO--Be smart about invalidating the cache.  Potential places:
+
+   * Insertions at end-of-line which don't cause line-wraps do not
+     alter the starting positions of any display lines.  These types of
+     buffer modifications should not invalidate the cache.  This is
+     actually a large optimization for redisplay speed as well.
+
+   * Buffer modifications frequently only affect the display of lines
+     at and below where they occur.  In these situations we should only
+     invalidate the part of the cache starting at where the
+     modification occurs.
+
+   In case you're wondering, the Second Golden Rule of Redisplay is not
+applicable.
+
+
+File: internals.info,  Node: Redisplay Piece by Piece,  Prev: Line Start Cache,  Up: The Redisplay Mechanism
+
+Redisplay Piece by Piece
+========================
+
+   As you can begin to see redisplay is complex and also not well
+documented. Chuck no longer works on XEmacs so this section is my take
+on the workings of redisplay.
+
+   Redisplay happens in three phases:
+
+  1. Determine desired display in area that needs redisplay.
+     Implemented by `redisplay.c'
+
+  2. Compare desired display with current display Implemented by
+     `redisplay-output.c'
+
+  3. Output changes Implemented by `redisplay-output.c',
+     `redisplay-x.c', `redisplay-msw.c' and `redisplay-tty.c'
+
+   Steps 1 and 2 are device-independent and relatively complex.  Step 3
+is mostly device-dependent.
+
+   Determining the desired display
+
+   Display attributes are stored in `display_line' structures. Each
+`display_line' consists of a set of `display_block''s and each
+`display_block' contains a number of `rune''s. Generally dynarr's of
+`display_line''s are held by each window representing the current
+display and the desired display.
+
+   The `display_line' structures are tightly tied to buffers which
+presents a problem for redisplay as this connection is bogus for the
+modeline. Hence the `display_line' generation routines are duplicated
+for generating the modeline. This means that the modeline display code
+has many bugs that the standard redisplay code does not.
+
+   The guts of `display_line' generation are in `create_text_block',
+which creates a single display line for the desired locale. This
+incrementally parses the characters on the current line and generates
+redisplay structures for each.
+
+   Gutter redisplay is different. Because the data to display is stored
+in a string we cannot use `create_text_block'. Instead we use
+`create_text_string_block' which performs the same function as
+`create_text_block' but for strings. Many of the complexities of
+`create_text_block' to do with cursor handling and selective display
+have been removed.
+
+
+File: internals.info,  Node: Extents,  Next: Faces,  Prev: The Redisplay Mechanism,  Up: Top
+
+Extents
+*******
+
+* Menu:
+
+* Introduction to Extents::     Extents are ranges over text, with properties.
+* Extent Ordering::             How extents are ordered internally.
+* Format of the Extent Info::   The extent information in a buffer or string.
+* Zero-Length Extents::         A weird special case.
+* Mathematics of Extent Ordering::  A rigorous foundation.
+* Extent Fragments::            Cached information useful for redisplay.
+
+
+File: internals.info,  Node: Introduction to Extents,  Next: Extent Ordering,  Up: Extents
+
+Introduction to Extents
+=======================
+
+   Extents are regions over a buffer, with a start and an end position
+denoting the region of the buffer included in the extent.  In addition,
+either end can be closed or open, meaning that the endpoint is or is
+not logically included in the extent.  Insertion of a character at a
+closed endpoint causes the character to go inside the extent; insertion
+at an open endpoint causes the character to go outside.
+
+   Extent endpoints are stored using memory indices (see `insdel.c'),
+to minimize the amount of adjusting that needs to be done when
+characters are inserted or deleted.
+
+   (Formerly, extent endpoints at the gap could be either before or
+after the gap, depending on the open/closedness of the endpoint.  The
+intent of this was to make it so that insertions would automatically go
+inside or out of extents as necessary with no further work needing to
+be done.  It didn't work out that way, however, and just ended up
+complexifying and buggifying all the rest of the code.)
+
+
+File: internals.info,  Node: Extent Ordering,  Next: Format of the Extent Info,  Prev: Introduction to Extents,  Up: Extents
+
+Extent Ordering
+===============
+
+   Extents are compared using memory indices.  There are two orderings
+for extents and both orders are kept current at all times.  The normal
+or "display" order is as follows:
+
+     Extent A is ``less than'' extent B,
+     that is, earlier in the display order,
+       if:    A-start < B-start,
+       or if: A-start = B-start, and A-end > B-end
+
+   So if two extents begin at the same position, the larger of them is
+the earlier one in the display order (`EXTENT_LESS' is true).
+
+   For the e-order, the same thing holds:
+
+     Extent A is ``less than'' extent B in e-order,
+     that is, later in the buffer,
+       if:    A-end < B-end,
+       or if: A-end = B-end, and A-start > B-start
+
+   So if two extents end at the same position, the smaller of them is
+the earlier one in the e-order (`EXTENT_E_LESS' is true).
+
+   The display order and the e-order are complementary orders: any
+theorem about the display order also applies to the e-order if you swap
+all occurrences of "display order" and "e-order", "less than" and
+"greater than", and "extent start" and "extent end".
+
+
+File: internals.info,  Node: Format of the Extent Info,  Next: Zero-Length Extents,  Prev: Extent Ordering,  Up: Extents
+
+Format of the Extent Info
+=========================
+
+   An extent-info structure consists of a list of the buffer or string's
+extents and a "stack of extents" that lists all of the extents over a
+particular position.  The stack-of-extents info is used for
+optimization purposes--it basically caches some info that might be
+expensive to compute.  Certain otherwise hard computations are easy
+given the stack of extents over a particular position, and if the stack
+of extents over a nearby position is known (because it was calculated
+at some prior point in time), it's easy to move the stack of extents to
+the proper position.
+
+   Given that the stack of extents is an optimization, and given that
+it requires memory, a string's stack of extents is wiped out each time
+a garbage collection occurs.  Therefore, any time you retrieve the
+stack of extents, it might not be there.  If you need it to be there,
+use the `_force' version.
+
+   Similarly, a string may or may not have an extent_info structure.
+(Generally it won't if there haven't been any extents added to the
+string.) So use the `_force' version if you need the extent_info
+structure to be there.
+
+   A list of extents is maintained as a double gap array: one gap array
+is ordered by start index (the "display order") and the other is
+ordered by end index (the "e-order").  Note that positions in an extent
+list should logically be conceived of as referring _to_ a particular
+extent (as is the norm in programs) rather than sitting between two
+extents.  Note also that callers of these functions should not be aware
+of the fact that the extent list is implemented as an array, except for
+the fact that positions are integers (this should be generalized to
+handle integers and linked list equally well).
+
+
+File: internals.info,  Node: Zero-Length Extents,  Next: Mathematics of Extent Ordering,  Prev: Format of the Extent Info,  Up: Extents
+
+Zero-Length Extents
+===================
+
+   Extents can be zero-length, and will end up that way if their
+endpoints are explicitly set that way or if their detachable property
+is `nil' and all the text in the extent is deleted. (The exception is
+open-open zero-length extents, which are barred from existing because
+there is no sensible way to define their properties.  Deletion of the
+text in an open-open extent causes it to be converted into a closed-open
+extent.)  Zero-length extents are primarily used to represent
+annotations, and behave as follows:
+
+  1. Insertion at the position of a zero-length extent expands the
+     extent if both endpoints are closed; goes after the extent if it
+     is closed-open; and goes before the extent if it is open-closed.
+
+  2. Deletion of a character on a side of a zero-length extent whose
+     corresponding endpoint is closed causes the extent to be detached
+     if it is detachable; if the extent is not detachable or the
+     corresponding endpoint is open, the extent remains in the buffer,
+     moving as necessary.
+
+   Note that closed-open, non-detachable zero-length extents behave
+exactly like markers and that open-closed, non-detachable zero-length
+extents behave like the "point-type" marker in Mule.
+
+
+File: internals.info,  Node: Mathematics of Extent Ordering,  Next: Extent Fragments,  Prev: Zero-Length Extents,  Up: Extents
+
+Mathematics of Extent Ordering
+==============================
+
+   The extents in a buffer are ordered by "display order" because that
+is that order that the redisplay mechanism needs to process them in.
+The e-order is an auxiliary ordering used to facilitate operations over
+extents.  The operations that can be performed on the ordered list of
+extents in a buffer are
+
+  1. Locate where an extent would go if inserted into the list.
+
+  2. Insert an extent into the list.
+
+  3. Remove an extent from the list.
+
+  4. Map over all the extents that overlap a range.
+
+   (4) requires being able to determine the first and last extents that
+overlap a range.
+
+   NOTE: "overlap" is used as follows:
+
+   * two ranges overlap if they have at least one point in common.
+     Whether the endpoints are open or closed makes a difference here.
+
+   * a point overlaps a range if the point is contained within the
+     range; this is equivalent to treating a point P as the range [P,
+     P].
+
+   * In the case of an _extent_ overlapping a point or range, the extent
+     is normally treated as having closed endpoints.  This applies
+     consistently in the discussion of stacks of extents and such below.
+     Note that this definition of overlap is not necessarily consistent
+     with the extents that `map-extents' maps over, since `map-extents'
+     sometimes pays attention to whether the endpoints of an extents
+     are open or closed.  But for our purposes, it greatly simplifies
+     things to treat all extents as having closed endpoints.
+
+   First, define >, <, <=, etc. as applied to extents to mean
+comparison according to the display order.  Comparison between an
+extent E and an index I means comparison between E and the range [I, I].
+
+   Also define e>, e<, e<=, etc. to mean comparison according to the
+e-order.
+
+   For any range R, define R(0) to be the starting index of the range
+and R(1) to be the ending index of the range.
+
+   For any extent E, define E(next) to be the extent directly following
+E, and E(prev) to be the extent directly preceding E.  Assume E(next)
+and E(prev) can be determined from E in constant time.  (This is
+because we store the extent list as a doubly linked list.)
+
+   Similarly, define E(e-next) and E(e-prev) to be the extents directly
+following and preceding E in the e-order.
+
+   Now:
+
+   Let R be a range.  Let F be the first extent overlapping R.  Let L
+be the last extent overlapping R.
+
+   Theorem 1: R(1) lies between L and L(next), i.e. L <= R(1) < L(next).
+
+   This follows easily from the definition of display order.  The basic
+reason that this theorem applies is that the display order sorts by
+increasing starting index.
+
+   Therefore, we can determine L just by looking at where we would
+insert R(1) into the list, and if we know F and are moving forward over
+extents, we can easily determine when we've hit L by comparing the
+extent we're at to R(1).
+
+     Theorem 2: F(e-prev) e< [1, R(0)] e<= F.
+
+   This is the analog of Theorem 1, and applies because the e-order
+sorts by increasing ending index.
+
+   Therefore, F can be found in the same amount of time as operation
+(1), i.e. the time that it takes to locate where an extent would go if
+inserted into the e-order list.
+
+   If the lists were stored as balanced binary trees, then operation (1)
+would take logarithmic time, which is usually quite fast.  However,
+currently they're stored as simple doubly-linked lists, and instead we
+do some caching to try to speed things up.
+
+   Define a "stack of extents" (or "SOE") as the set of extents
+(ordered in the display order) that overlap an index I, together with
+the SOE's "previous" extent, which is an extent that precedes I in the
+e-order. (Hopefully there will not be very many extents between I and
+the previous extent.)
+
+   Now:
+
+   Let I be an index, let S be the stack of extents on I, let F be the
+first extent in S, and let P be S's previous extent.
+
+   Theorem 3: The first extent in S is the first extent that overlaps
+any range [I, J].
+
+   Proof: Any extent that overlaps [I, J] but does not include I must
+have a start index > I, and thus be greater than any extent in S.
+
+   Therefore, finding the first extent that overlaps a range R is the
+same as finding the first extent that overlaps R(0).
+
+   Theorem 4: Let I2 be an index such that I2 > I, and let F2 be the
+first extent that overlaps I2.  Then, either F2 is in S or F2 is
+greater than any extent in S.
+
+   Proof: If F2 does not include I then its start index is greater than
+I and thus it is greater than any extent in S, including F.  Otherwise,
+F2 includes I and thus is in S, and thus F2 >= F.
+
+
+File: internals.info,  Node: Extent Fragments,  Prev: Mathematics of Extent Ordering,  Up: Extents
+
+Extent Fragments
+================
+
+   Imagine that the buffer is divided up into contiguous,
+non-overlapping "runs" of text such that no extent starts or ends
+within a run (extents that abut the run don't count).
+
+   An extent fragment is a structure that holds data about the run that
+contains a particular buffer position (if the buffer position is at the
+junction of two runs, the run after the position is used)--the
+beginning and end of the run, a list of all of the extents in that run,
+the "merged face" that results from merging all of the faces
+corresponding to those extents, the begin and end glyphs at the
+beginning of the run, etc.  This is the information that redisplay needs
+in order to display this run.
+
+   Extent fragments have to be very quick to update to a new buffer
+position when moving linearly through the buffer.  They rely on the
+stack-of-extents code, which does the heavy-duty algorithmic work of
+determining which extents overly a particular position.
+
+
+File: internals.info,  Node: Faces,  Next: Glyphs,  Prev: Extents,  Up: Top
+
+Faces
+*****
+
+   Not yet documented.
+
+
+File: internals.info,  Node: Glyphs,  Next: Specifiers,  Prev: Faces,  Up: Top
+
+Glyphs
+******
+
+   Glyphs are graphical elements that can be displayed in XEmacs
+buffers or gutters. We use the term graphical element here in the
+broadest possible sense since glyphs can be as mundane as text or as
+arcane as a native tab widget.
+
+   In XEmacs, glyphs represent the uninstantiated state of graphical
+elements, i.e. they hold all the information necessary to produce an
+image on-screen but the image need not exist at this stage, and multiple
+screen images can be instantiated from a single glyph.
+
+   Glyphs are lazily instantiated by calling one of the glyph
+functions. This usually occurs within redisplay when `Fglyph_height' is
+called. Instantiation causes an image-instance to be created and
+cached. This cache is on a per-device basis for all glyphs except
+widget-glyphs, and on a per-window basis for widgets-glyphs.  The
+caching is done by `image_instantiate' and is necessary because it is
+generally possible to display an image-instance in multiple domains.
+For instance if we create a Pixmap, we can actually display this on
+multiple windows - even though we only need a single Pixmap instance to
+do this. If caching wasn't done then it would be necessary to create
+image-instances for every displayable occurrence of a glyph - and every
+usage - and this would be extremely memory and cpu intensive.
+
+   Widget-glyphs (a.k.a native widgets) are not cached in this way.
+This is because widget-glyph image-instances on screen are toolkit
+windows, and thus cannot be reused in multiple XEmacs domains. Thus
+widget-glyphs are cached on an XEmacs window basis.
+
+   Any action on a glyph first consults the cache before actually
+instantiating a widget.
+
+Glyph Instantiation
+===================
+
+   Glyph instantiation is a hairy topic and requires some explanation.
+The guts of glyph instantiation is contained within
+`image_instantiate'. A glyph contains an image which is a specifier.
+When a glyph function - for instance `Fglyph_height' - asks for a
+property of the glyph that can only be determined from its instantiated
+state, then the glyph image is instantiated and an image instance
+created. The instantiation process is governed by the specifier code
+and goes through a series of steps:
+
+   * Validation. Instantiation of image instances happens dynamically -
+     often within the guts of redisplay. Thus it is often not feasible
+     to catch instantiator errors at instantiation time. Instead the
+     instantiator is validated at the time it is added to the image
+     specifier. This function is defined by `image_validate' and at a
+     simple level validates keyword value pairs.
+
+   * Duplication. The specifier code by default takes a copy of the
+     instantiator. This is reasonable for most specifiers but in the
+     case of widget-glyphs can be problematic, since some of the
+     properties in the instantiator - for instance callbacks - could
+     cause infinite recursion in the copying process. Thus the image
+     code defines a function - `image_copy_instantiator' - which will
+     selectively copy values.  This is controlled by the way that a
+     keyword is defined either using `IIFORMAT_VALID_KEYWORD' or
+     `IIFORMAT_VALID_NONCOPY_KEYWORD'. Note that the image caching and
+     redisplay code relies on instantiator copying to ensure that
+     current and new instantiators are actually different rather than
+     referring to the same thing.
+
+   * Normalization. Once the instantiator has been copied it must be
+     converted into a form that is viable at instantiation time. This
+     can involve no changes at all, but typically involves things like
+     converting file names to the actual data. This function is defined
+     by `image_going_to_add' and `normalize_image_instantiator'.
+
+   * Instantiation. When an image instance is actually required for
+     display it is instantiated using `image_instantiate'. This
+     involves calling instantiate methods that are specific to the type
+     of image being instantiated.
+
+   The final instantiation phase also involves a number of steps. In
+order to understand these we need to describe a number of concepts.
+
+   An image is instantiated in a "domain", where a domain can be any
+one of a device, frame, window or image-instance. The domain gives the
+image-instance context and identity and properties that affect the
+appearance of the image-instance may be different for the same glyph
+instantiated in different domains. An example is the face used to
+display the image-instance.
+
+   Although an image is instantiated in a particular domain the
+instantiation domain is not necessarily the domain in which the
+image-instance is cached. For example a pixmap can be instantiated in a
+window be actually be cached on a per-device basis. The domain in which
+the image-instance is actually cached is called the "governing-domain".
+A governing-domain is currently either a device or a window.
+Widget-glyphs and text-glyphs have a window as a governing-domain, all
+other image-instances have a device as the governing-domain. The
+governing domain for an image-instance is determined using the
+governing_domain image-instance method.
+
+Widget-Glyphs
+=============
+
+Widget-Glyphs in the MS-Windows Environment
+===========================================
+
+   To Do
+
+Widget-Glyphs in the X Environment
+==================================
+
+   Widget-glyphs under X make heavy use of lwlib (*note Lucid Widget
+Library::) for manipulating the native toolkit objects. This is
+primarily so that different toolkits can be supported for
+widget-glyphs, just as they are supported for features such as menubars
+etc.
+
+   Lwlib is extremely poorly documented and quite hairy so here is my
+understanding of what goes on.
+
+   Lwlib maintains a set of widget_instances which mirror the
+hierarchical state of Xt widgets. I think this is so that widgets can
+be updated and manipulated generically by the lwlib library. For
+instance update_one_widget_instance can cope with multiple types of
+widget and multiple types of toolkit. Each element in the widget
+hierarchy is updated from its corresponding widget_instance by walking
+the widget_instance tree recursively.
+
+   This has desirable properties such as lw_modify_all_widgets which is
+called from `glyphs-x.c' and updates all the properties of a widget
+without having to know what the widget is or what toolkit it is from.
+Unfortunately this also has hairy properties such as making the lwlib
+code quite complex. And of course lwlib has to know at some level what
+the widget is and how to set its properties.
+
+
+File: internals.info,  Node: Specifiers,  Next: Menus,  Prev: Glyphs,  Up: Top
+
+Specifiers
+**********
+
+   Not yet documented.
+
+
+File: internals.info,  Node: Menus,  Next: Subprocesses,  Prev: Specifiers,  Up: Top
+
+Menus
+*****
+
+   A menu is set by setting the value of the variable `current-menubar'
+(which may be buffer-local) and then calling `set-menubar-dirty-flag'
+to signal a change.  This will cause the menu to be redrawn at the next
+redisplay.  The format of the data in `current-menubar' is described in
+`menubar.c'.
+
+   Internally the data in current-menubar is parsed into a tree of
+`widget_value's' (defined in `lwlib.h'); this is accomplished by the
+recursive function `menu_item_descriptor_to_widget_value()', called by
+`compute_menubar_data()'.  Such a tree is deallocated using
+`free_widget_value()'.
+
+   `update_screen_menubars()' is one of the external entry points.
+This checks to see, for each screen, if that screen's menubar needs to
+be updated.  This is the case if
+
+  1. `set-menubar-dirty-flag' was called since the last redisplay.
+     (This function sets the C variable menubar_has_changed.)
+
+  2. The buffer displayed in the screen has changed.
+
+  3. The screen has no menubar currently displayed.
+
+   `set_screen_menubar()' is called for each such screen.  This
+function calls `compute_menubar_data()' to create the tree of
+widget_value's, then calls `lw_create_widget()',
+`lw_modify_all_widgets()', and/or `lw_destroy_all_widgets()' to create
+the X-Toolkit widget associated with the menu.
+
+   `update_psheets()', the other external entry point, actually changes
+the menus being displayed.  It uses the widgets fixed by
+`update_screen_menubars()' and calls various X functions to ensure that
+the menus are displayed properly.
+
+   The menubar widget is set up so that `pre_activate_callback()' is
+called when the menu is first selected (i.e. mouse button goes down),
+and `menubar_selection_callback()' is called when an item is selected.
+`pre_activate_callback()' calls the function in activate-menubar-hook,
+which can change the menubar (this is described in `menubar.c').  If
+the menubar is changed, `set_screen_menubars()' is called.
+`menubar_selection_callback()' enqueues a menu event, putting in it a
+function to call (either `eval' or `call-interactively') and its
+argument, which is the callback function or form given in the menu's
+description.
+
+
+File: internals.info,  Node: Subprocesses,  Next: Interface to the X Window System,  Prev: Menus,  Up: Top
+
+Subprocesses
+************
+
+   The fields of a process are:
+
+`name'
+     A string, the name of the process.
+
+`command'
+     A list containing the command arguments that were used to start
+     this process.
+
+`filter'
+     A function used to accept output from the process instead of a
+     buffer, or `nil'.
+
+`sentinel'
+     A function called whenever the process receives a signal, or `nil'.
+
+`buffer'
+     The associated buffer of the process.
+
+`pid'
+     An integer, the Unix process ID.
+
+`childp'
+     A flag, non-`nil' if this is really a child process.  It is `nil'
+     for a network connection.
+
+`mark'
+     A marker indicating the position of the end of the last output
+     from this process inserted into the buffer.  This is often but not
+     always the end of the buffer.
+
+`kill_without_query'
+     If this is non-`nil', killing XEmacs while this process is still
+     running does not ask for confirmation about killing the process.
+
+`raw_status_low'
+`raw_status_high'
+     These two fields record 16 bits each of the process status
+     returned by the `wait' system call.
+
+`status'
+     The process status, as `process-status' should return it.
+
+`tick'
+`update_tick'
+     If these two fields are not equal, a change in the status of the
+     process needs to be reported, either by running the sentinel or by
+     inserting a message in the process buffer.
+
+`pty_flag'
+     Non-`nil' if communication with the subprocess uses a PTY; `nil'
+     if it uses a pipe.
+
+`infd'
+     The file descriptor for input from the process.
+
+`outfd'
+     The file descriptor for output to the process.
+
+`subtty'
+     The file descriptor for the terminal that the subprocess is using.
+     (On some systems, there is no need to record this, so the value is
+     `-1'.)
+
+`tty_name'
+     The name of the terminal that the subprocess is using, or `nil' if
+     it is using pipes.
+
+
+File: internals.info,  Node: Interface to the X Window System,  Next: Index,  Prev: Subprocesses,  Up: Top
+
+Interface to the X Window System
+********************************
+
+   Mostly undocumented.
+
+* Menu:
+
+* Lucid Widget Library::        An interface to various widget sets.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/internals.info-9'
Index: ././info/internals.info-9
--- ././info/internals.info-9	Thu Jan  1 09:00:00 1970
+++ ././info/internals.info-9	Thu May 17 23:26:54 2001
@@ -0,0 +1,596 @@
+This is ../info/internals.info, produced by makeinfo version 4.0 from
+internals/internals.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Internals: (internals).       XEmacs Internals Manual.
+END-INFO-DIR-ENTRY
+
+   Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
+Microsystems.  Copyright (C) 1994 - 1998 Free Software Foundation.
+Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: internals.info,  Node: Lucid Widget Library,  Up: Interface to the X Window System
+
+Lucid Widget Library
+====================
+
+   Lwlib is extremely poorly documented and quite hairy.  The author(s)
+blame that on X, Xt, and Motif, with some justice, but also sufficient
+hypocrisy to avoid drawing the obvious conclusion about their own work.
+
+   The Lucid Widget Library is composed of two more or less independent
+pieces.  The first, as the name suggests, is a set of widgets.  These
+widgets are intended to resemble and improve on widgets provided in the
+Motif toolkit but not in the Athena widgets, including menubars and
+scrollbars.  Recent additions by Andy Piper integrate some "modern"
+widgets by Edward Falk, including checkboxes, radio buttons, progress
+gauges, and index tab controls (aka notebooks).
+
+   The second piece of the Lucid widget library is a generic interface
+to several toolkits for X (including Xt, the Athena widget set, and
+Motif, as well as the Lucid widgets themselves) so that core XEmacs
+code need not know which widget set has been used to build the
+graphical user interface.
+
+* Menu:
+
+* Generic Widget Interface::    The lwlib generic widget interface.
+* Scrollbars::
+* Menubars::
+* Checkboxes and Radio Buttons::
+* Progress Bars::
+* Tab Controls::
+
+
+File: internals.info,  Node: Generic Widget Interface,  Next: Scrollbars,  Up: Lucid Widget Library
+
+Generic Widget Interface
+------------------------
+
+   In general in any toolkit a widget may be a composite object.  In Xt,
+all widgets have an X window that they manage, but typically a complex
+widget will have widget children, each of which manages a subwindow of
+the parent widget's X window.  These children may themselves be
+composite widgets.  Thus a widget is actually a tree or hierarchy of
+widgets.
+
+   For each toolkit widget, lwlib maintains a tree of `widget_values'
+which mirror the hierarchical state of Xt widgets (including Motif,
+Athena, 3D Athena, and Falk's widget sets).  Each `widget_value' has
+`contents' member, which points to the head of a linked list of its
+children.  The linked list of siblings is chained through the `next'
+member of `widget_value'.
+
+                +-----------+
+                | composite |
+                +-----------+
+                      |
+                      | contents
+                      V
+                  +-------+ next +-------+ next +-------+
+                  | child |----->| child |----->| child |
+                  +-------+      +-------+      +-------+
+                                     |
+                                     | contents
+                                     V
+                              +-------------+ next +-------------+
+                              | grand child |----->| grand child |
+                              +-------------+      +-------------+
+     
+     The `widget_value' hierarchy of a composite widget with two simple
+     children and one composite child.
+
+   The `widget_instance' structure maintains the inverse view of the
+tree.  As for the `widget_value', siblings are chained through the
+`next' member.  However, rather than naming children, the
+`widget_instance' tree links to parents.
+
+                +-----------+
+                | composite |
+                +-----------+
+                      A
+                      | parent
+                      |
+                  +-------+ next +-------+ next +-------+
+                  | child |----->| child |----->| child |
+                  +-------+      +-------+      +-------+
+                                     A
+                                     | parent
+                                     |
+                              +-------------+ next +-------------+
+                              | grand child |----->| grand child |
+                              +-------------+      +-------------+
+     
+     The `widget_value' hierarchy of a composite widget with two simple
+     children and one composite child.
+
+   This permits widgets derived from different toolkits to be updated
+and manipulated generically by the lwlib library. For instance
+`update_one_widget_instance' can cope with multiple types of widget and
+multiple types of toolkit. Each element in the widget hierarchy is
+updated from its corresponding `widget_value' by walking the
+`widget_value' tree.  This has desirable properties.  For example,
+`lw_modify_all_widgets' is called from `glyphs-x.c' and updates all the
+properties of a widget without having to know what the widget is or
+what toolkit it is from.  Unfortunately this also has its hairy
+properties; the lwlib code quite complex. And of course lwlib has to
+know at some level what the widget is and how to set its properties.
+
+   The `widget_instance' structure also contains a pointer to the root
+of its tree.  Widget instances are further confi
+
+
+File: internals.info,  Node: Scrollbars,  Next: Menubars,  Prev: Generic Widget Interface,  Up: Lucid Widget Library
+
+Scrollbars
+----------
+
+
+File: internals.info,  Node: Menubars,  Next: Checkboxes and Radio Buttons,  Prev: Scrollbars,  Up: Lucid Widget Library
+
+Menubars
+--------
+
+
+File: internals.info,  Node: Checkboxes and Radio Buttons,  Next: Progress Bars,  Prev: Menubars,  Up: Lucid Widget Library
+
+Checkboxes and Radio Buttons
+----------------------------
+
+
+File: internals.info,  Node: Progress Bars,  Next: Tab Controls,  Prev: Checkboxes and Radio Buttons,  Up: Lucid Widget Library
+
+Progress Bars
+-------------
+
+
+File: internals.info,  Node: Tab Controls,  Prev: Progress Bars,  Up: Lucid Widget Library
+
+Tab Controls
+------------
+
+
+File: internals.info,  Node: Index,  Prev: Interface to the X Window System,  Up: Top
+
+Index
+*****
+
+* Menu:
+
+* allocation from frob blocks:           Allocation from Frob Blocks.
+* allocation of objects in XEmacs Lisp:  Allocation of Objects in XEmacs Lisp.
+* allocation, introduction to:           Introduction to Allocation.
+* allocation, low-level:                 Low-level allocation.
+* Amdahl Corporation:                    XEmacs.
+* Andreessen, Marc:                      XEmacs.
+* asynchronous subprocesses:             Modules for Interfacing with the Operating System.
+* bars, progress:                        Progress Bars.
+* Baur, Steve:                           XEmacs.
+* Benson, Eric:                          Lucid Emacs.
+* binding; the specbinding stack; unwind-protects, dynamic: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* bindings, evaluation; stack frames;:   Evaluation; Stack Frames; Bindings.
+* bit vector:                            Bit Vector.
+* bridge, playing:                       XEmacs From the Outside.
+* Buchholz, Martin:                      XEmacs.
+* Bufbyte:                               Character-Related Data Types.
+* Bufbytes and Emchars:                  Bufbytes and Emchars.
+* buffer lists:                          Buffer Lists.
+* buffer object, the:                    The Buffer Object.
+* buffer, the text in a:                 The Text in a Buffer.
+* buffers and textual representation:    Buffers and Textual Representation.
+* buffers, introduction to:              Introduction to Buffers.
+* Bufpos:                                Character-Related Data Types.
+* building, XEmacs from the perspective of: XEmacs From the Perspective of Building.
+* buttons, checkboxes and radio:         Checkboxes and Radio Buttons.
+* byte positions, working with character and: Working With Character and Byte Positions.
+* Bytecount:                             Character-Related Data Types.
+* bytecount_to_charcount:                Working With Character and Byte Positions.
+* Bytind:                                Character-Related Data Types.
+* C code, rules when writing new:        Rules When Writing New C Code.
+* C vs. Lisp:                            The Lisp Language.
+* callback routines, the event stream:   The Event Stream Callback Routines.
+* caller-protects (GCPRO rule):          Writing Lisp Primitives.
+* case table:                            Modules for Other Aspects of the Lisp Interpreter and Object System.
+* catch and throw:                       Catch and Throw.
+* CCL:                                   CCL.
+* character and byte positions, working with: Working With Character and Byte Positions.
+* character encoding, internal:          Internal Character Encoding.
+* character sets:                        Character Sets.
+* character sets and encodings, Mule:    MULE Character Sets and Encodings.
+* character-related data types:          Character-Related Data Types.
+* characters, integers and:              Integers and Characters.
+* Charcount:                             Character-Related Data Types.
+* charcount_to_bytecount:                Working With Character and Byte Positions.
+* charptr_emchar:                        Working With Character and Byte Positions.
+* charptr_n_addr:                        Working With Character and Byte Positions.
+* checkboxes and radio buttons:          Checkboxes and Radio Buttons.
+* closer:                                Lstream Methods.
+* closure:                               The XEmacs Object System (Abstractly Speaking).
+* code, an example of Mule-aware:        An Example of Mule-Aware Code.
+* code, general guidelines for writing Mule-aware: General Guidelines for Writing Mule-Aware Code.
+* code, rules when writing new C:        Rules When Writing New C Code.
+* coding for Mule:                       Coding for Mule.
+* coding rules, general:                 General Coding Rules.
+* command builder, dispatching events; the: Dispatching Events; The Command Builder.
+* comments, writing good:                Writing Good Comments.
+* Common Lisp:                           The Lisp Language.
+* compact_string_chars:                  compact_string_chars.
+* compiled function:                     Compiled Function.
+* compiler, the Lisp reader and:         The Lisp Reader and Compiler.
+* cons:                                  Cons.
+* conservative garbage collection:       GCPROing.
+* consoles; devices; frames; windows:    Consoles; Devices; Frames; Windows.
+* consoles; devices; frames; windows, introduction to: Introduction to Consoles; Devices; Frames; Windows.
+* control flow modules, editor-level:    Editor-Level Control Flow Modules.
+* conversion to and from external data:  Conversion to and from External Data.
+* converting events:                     Converting Events.
+* copy-on-write:                         General Coding Rules.
+* creating Lisp object types:            Techniques for XEmacs Developers.
+* critical redisplay sections:           Critical Redisplay Sections.
+* data dumping:                          Data dumping.
+* data types, character-related:         Character-Related Data Types.
+* DEC_CHARPTR:                           Working With Character and Byte Positions.
+* developers, techniques for XEmacs:     Techniques for XEmacs Developers.
+* devices; frames; windows, consoles;:   Consoles; Devices; Frames; Windows.
+* devices; frames; windows, introduction to consoles;: Introduction to Consoles; Devices; Frames; Windows.
+* Devin, Matthieu:                       Lucid Emacs.
+* dispatching events; the command builder: Dispatching Events; The Command Builder.
+* display order of extents:              Mathematics of Extent Ordering.
+* display-related Lisp objects, modules for other: Modules for other Display-Related Lisp Objects.
+* displayable Lisp objects, modules for the basic: Modules for the Basic Displayable Lisp Objects.
+* dumping:                               Dumping.
+* dumping address allocation:            Address allocation.
+* dumping and its justification, what is: Dumping.
+* dumping data descriptions:             Data descriptions.
+* dumping object inventory:              Object inventory.
+* dumping overview:                      Overview.
+* dumping phase:                         Dumping phase.
+* dumping, data:                         Data dumping.
+* dumping, file loading:                 Reloading phase.
+* dumping, object relocation:            Reloading phase.
+* dumping, pointers:                     Pointers dumping.
+* dumping, putting back the pdump_opaques: Reloading phase.
+* dumping, putting back the pdump_root_objects and pdump_weak_object_chains: Reloading phase.
+* dumping, putting back the pdump_root_struct_ptrs: Reloading phase.
+* dumping, reloading phase:              Reloading phase.
+* dumping, remaining issues:             Remaining issues.
+* dumping, reorganize the hash tables:   Reloading phase.
+* dumping, the header:                   The header.
+* dynamic array:                         Low-Level Modules.
+* dynamic binding; the specbinding stack; unwind-protects: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* dynamic scoping:                       The Lisp Language.
+* dynamic types:                         The Lisp Language.
+* editing operations, modules for standard: Modules for Standard Editing Operations.
+* Emacs 19, GNU:                         GNU Emacs 19.
+* Emacs 20, GNU:                         GNU Emacs 20.
+* Emacs, a history of:                   A History of Emacs.
+* Emchar:                                Character-Related Data Types.
+* Emchars, Bufbytes and:                 Bufbytes and Emchars.
+* encoding, internal character:          Internal Character Encoding.
+* encoding, internal string:             Internal String Encoding.
+* encodings, internal Mule:              Internal Mule Encodings.
+* encodings, Mule:                       Encodings.
+* encodings, Mule character sets and:    MULE Character Sets and Encodings.
+* Energize:                              Lucid Emacs.
+* Epoch <1>:                             XEmacs.
+* Epoch:                                 Lucid Emacs.
+* error checking:                        Techniques for XEmacs Developers.
+* EUC (Extended Unix Code), Japanese:    Japanese EUC (Extended Unix Code).
+* evaluation:                            Evaluation.
+* evaluation; stack frames; bindings:    Evaluation; Stack Frames; Bindings.
+* event gathering mechanism, specifics of the: Specifics of the Event Gathering Mechanism.
+* event loop functions, other:           Other Event Loop Functions.
+* event loop, events and the:            Events and the Event Loop.
+* event stream callback routines, the:   The Event Stream Callback Routines.
+* event, specifics about the Lisp object: Specifics About the Emacs Event.
+* events and the event loop:             Events and the Event Loop.
+* events, converting:                    Converting Events.
+* events, introduction to:               Introduction to Events.
+* events, main loop:                     Main Loop.
+* events; the command builder, dispatching: Dispatching Events; The Command Builder.
+* Extbyte:                               Character-Related Data Types.
+* Extcount:                              Character-Related Data Types.
+* Extended Unix Code, Japanese EUC:      Japanese EUC (Extended Unix Code).
+* extent fragments:                      Extent Fragments.
+* extent info, format of the:            Format of the Extent Info.
+* extent mathematics:                    Mathematics of Extent Ordering.
+* extent ordering <1>:                   Mathematics of Extent Ordering.
+* extent ordering:                       Extent Ordering.
+* extents:                               Extents.
+* extents, display order:                Mathematics of Extent Ordering.
+* extents, introduction to:              Introduction to Extents.
+* extents, markers and:                  Markers and Extents.
+* extents, zero-length:                  Zero-Length Extents.
+* external data, conversion to and from: Conversion to and from External Data.
+* external widget:                       Modules for Interfacing with X Windows.
+* faces:                                 Faces.
+* file system, modules for interfacing with the: Modules for Interfacing with the File System.
+* flusher:                               Lstream Methods.
+* fragments, extent:                     Extent Fragments.
+* frames; windows, consoles; devices;:   Consoles; Devices; Frames; Windows.
+* frames; windows, introduction to consoles; devices;: Introduction to Consoles; Devices; Frames; Windows.
+* Free Software Foundation:              A History of Emacs.
+* frob blocks, allocation from:          Allocation from Frob Blocks.
+* FSF:                                   A History of Emacs.
+* FSF Emacs <1>:                         GNU Emacs 20.
+* FSF Emacs:                             GNU Emacs 19.
+* function, compiled:                    Compiled Function.
+* garbage collection:                    Garbage Collection.
+* garbage collection - step by step:     Garbage Collection - Step by Step.
+* garbage collection protection <1>:     GCPROing.
+* garbage collection protection:         Writing Lisp Primitives.
+* garbage collection, conservative:      GCPROing.
+* garbage collection, invocation:        Invocation.
+* garbage_collect_1:                     garbage_collect_1.
+* gc_sweep:                              gc_sweep.
+* GCPROing:                              GCPROing.
+* global Lisp variables, adding:         Adding Global Lisp Variables.
+* glyph instantiation:                   Glyphs.
+* glyphs:                                Glyphs.
+* GNU Emacs 19:                          GNU Emacs 19.
+* GNU Emacs 20:                          GNU Emacs 20.
+* Gosling, James <1>:                    The Lisp Language.
+* Gosling, James:                        Through Version 18.
+* Great Usenet Renaming:                 Through Version 18.
+* Hackers (Steven Levy):                 A History of Emacs.
+* header files, inline functions:        Techniques for XEmacs Developers.
+* hierarchy of windows:                  Window Hierarchy.
+* history of Emacs, a:                   A History of Emacs.
+* Illinois, University of:               XEmacs.
+* INC_CHARPTR:                           Working With Character and Byte Positions.
+* inline functions:                      Techniques for XEmacs Developers.
+* inline functions, headers:             Techniques for XEmacs Developers.
+* inside, XEmacs from the:               XEmacs From the Inside.
+* instantiation, glyph:                  Glyphs.
+* integers and characters:               Integers and Characters.
+* interactive:                           Modules for Standard Editing Operations.
+* interfacing with the file system, modules for: Modules for Interfacing with the File System.
+* interfacing with the operating system, modules for: Modules for Interfacing with the Operating System.
+* interfacing with X Windows, modules for: Modules for Interfacing with X Windows.
+* internal character encoding:           Internal Character Encoding.
+* internal Mule encodings:               Internal Mule Encodings.
+* internal string encoding:              Internal String Encoding.
+* internationalization, modules for:     Modules for Internationalization.
+* interning:                             The XEmacs Object System (Abstractly Speaking).
+* interpreter and object system, modules for other aspects of the Lisp: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* ITS (Incompatible Timesharing System): A History of Emacs.
+* Japanese EUC (Extended Unix Code):     Japanese EUC (Extended Unix Code).
+* Java:                                  The Lisp Language.
+* Java vs. Lisp:                         The Lisp Language.
+* JIS7:                                  JIS7.
+* Jones, Kyle:                           XEmacs.
+* Kaplan, Simon:                         XEmacs.
+* Levy, Steven:                          A History of Emacs.
+* library, Lucid Widget:                 Lucid Widget Library.
+* line start cache:                      Line Start Cache.
+* Lisp interpreter and object system, modules for other aspects of the: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* Lisp language, the:                    The Lisp Language.
+* Lisp modules, basic:                   Basic Lisp Modules.
+* Lisp object types, creating:           Techniques for XEmacs Developers.
+* Lisp objects are represented in C, how: How Lisp Objects Are Represented in C.
+* Lisp objects, allocation of in XEmacs: Allocation of Objects in XEmacs Lisp.
+* Lisp objects, modules for other display-related: Modules for other Display-Related Lisp Objects.
+* Lisp objects, modules for the basic displayable: Modules for the Basic Displayable Lisp Objects.
+* Lisp primitives, writing:              Writing Lisp Primitives.
+* Lisp reader and compiler, the:         The Lisp Reader and Compiler.
+* Lisp vs. C:                            The Lisp Language.
+* Lisp vs. Java:                         The Lisp Language.
+* low-level allocation:                  Low-level allocation.
+* low-level modules:                     Low-Level Modules.
+* lrecords:                              lrecords.
+* lstream:                               Modules for Interfacing with the File System.
+* lstream functions:                     Lstream Functions.
+* lstream methods:                       Lstream Methods.
+* lstream types:                         Lstream Types.
+* lstream, creating an:                  Creating an Lstream.
+* Lstream_close:                         Lstream Functions.
+* Lstream_fgetc:                         Lstream Functions.
+* Lstream_flush:                         Lstream Functions.
+* Lstream_fputc:                         Lstream Functions.
+* Lstream_fungetc:                       Lstream Functions.
+* Lstream_getc:                          Lstream Functions.
+* Lstream_new:                           Lstream Functions.
+* Lstream_putc:                          Lstream Functions.
+* Lstream_read:                          Lstream Functions.
+* Lstream_reopen:                        Lstream Functions.
+* Lstream_rewind:                        Lstream Functions.
+* Lstream_set_buffering:                 Lstream Functions.
+* Lstream_ungetc:                        Lstream Functions.
+* Lstream_unread:                        Lstream Functions.
+* Lstream_write:                         Lstream Functions.
+* lstreams:                              Lstreams.
+* Lucid Emacs:                           Lucid Emacs.
+* Lucid Inc.:                            Lucid Emacs.
+* Lucid Widget Library:                  Lucid Widget Library.
+* macro hygiene:                         Techniques for XEmacs Developers.
+* main loop:                             Main Loop.
+* mark and sweep:                        Garbage Collection.
+* mark method <1>:                       lrecords.
+* mark method:                           Modules for Other Aspects of the Lisp Interpreter and Object System.
+* mark_object:                           mark_object.
+* marker <1>:                            Lstream Methods.
+* marker:                                Marker.
+* markers and extents:                   Markers and Extents.
+* mathematics of extent ordering:        Mathematics of Extent Ordering.
+* MAX_EMCHAR_LEN:                        Working With Character and Byte Positions.
+* menubars:                              Menubars.
+* menus:                                 Menus.
+* merging attempts:                      XEmacs.
+* MIT:                                   A History of Emacs.
+* Mlynarik, Richard:                     GNU Emacs 19.
+* modules for interfacing with the file system: Modules for Interfacing with the File System.
+* modules for interfacing with the operating system: Modules for Interfacing with the Operating System.
+* modules for interfacing with X Windows: Modules for Interfacing with X Windows.
+* modules for internationalization:      Modules for Internationalization.
+* modules for other aspects of the Lisp interpreter and object system: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* modules for other display-related Lisp objects: Modules for other Display-Related Lisp Objects.
+* modules for standard editing operations: Modules for Standard Editing Operations.
+* modules for the basic displayable Lisp objects: Modules for the Basic Displayable Lisp Objects.
+* modules for the redisplay mechanism:   Modules for the Redisplay Mechanism.
+* modules, a summary of the various XEmacs: A Summary of the Various XEmacs Modules.
+* modules, basic Lisp:                   Basic Lisp Modules.
+* modules, editor-level control flow:    Editor-Level Control Flow Modules.
+* modules, low-level:                    Low-Level Modules.
+* MS-Windows environment, widget-glyphs in the: Glyphs.
+* Mule character sets and encodings:     MULE Character Sets and Encodings.
+* Mule encodings:                        Encodings.
+* Mule encodings, internal:              Internal Mule Encodings.
+* MULE merged XEmacs appears:            XEmacs.
+* Mule, coding for:                      Coding for Mule.
+* Mule-aware code, an example of:        An Example of Mule-Aware Code.
+* Mule-aware code, general guidelines for writing: General Guidelines for Writing Mule-Aware Code.
+* NAS:                                   Modules for Interfacing with the Operating System.
+* native sound:                          Modules for Interfacing with the Operating System.
+* network connections:                   Modules for Interfacing with the Operating System.
+* network sound:                         Modules for Interfacing with the Operating System.
+* Niksic, Hrvoje:                        XEmacs.
+* obarrays:                              Obarrays.
+* object system (abstractly speaking), the XEmacs: The XEmacs Object System (Abstractly Speaking).
+* object system, modules for other aspects of the Lisp interpreter and: Modules for Other Aspects of the Lisp Interpreter and Object System.
+* object types, creating Lisp:           Techniques for XEmacs Developers.
+* object, the buffer:                    The Buffer Object.
+* object, the window:                    The Window Object.
+* objects are represented in C, how Lisp: How Lisp Objects Are Represented in C.
+* objects in XEmacs Lisp, allocation of: Allocation of Objects in XEmacs Lisp.
+* objects, modules for the basic displayable Lisp: Modules for the Basic Displayable Lisp Objects.
+* operating system, modules for interfacing with the: Modules for Interfacing with the Operating System.
+* outside, XEmacs from the:              XEmacs From the Outside.
+* pane:                                  Modules for the Basic Displayable Lisp Objects.
+* permanent objects:                     The XEmacs Object System (Abstractly Speaking).
+* pi, calculating:                       XEmacs From the Outside.
+* point:                                 Point.
+* pointers dumping:                      Pointers dumping.
+* positions, working with character and byte: Working With Character and Byte Positions.
+* primitives, writing Lisp:              Writing Lisp Primitives.
+* progress bars:                         Progress Bars.
+* protection, garbage collection:        GCPROing.
+* pseudo_closer:                         Lstream Methods.
+* Purify:                                Techniques for XEmacs Developers.
+* Quantify:                              Techniques for XEmacs Developers.
+* radio buttons, checkboxes and:         Checkboxes and Radio Buttons.
+* read syntax:                           The XEmacs Object System (Abstractly Speaking).
+* read-eval-print:                       XEmacs From the Outside.
+* reader:                                Lstream Methods.
+* reader and compiler, the Lisp:         The Lisp Reader and Compiler.
+* redisplay mechanism, modules for the:  Modules for the Redisplay Mechanism.
+* redisplay mechanism, the:              The Redisplay Mechanism.
+* redisplay piece by piece:              Redisplay Piece by Piece.
+* redisplay sections, critical:          Critical Redisplay Sections.
+* reloading phase:                       Reloading phase.
+* relocating allocator:                  Low-Level Modules.
+* rename to XEmacs:                      XEmacs.
+* represented in C, how Lisp objects are: How Lisp Objects Are Represented in C.
+* rewinder:                              Lstream Methods.
+* RMS:                                   A History of Emacs.
+* scanner:                               Modules for Other Aspects of the Lisp Interpreter and Object System.
+* scoping, dynamic:                      The Lisp Language.
+* scrollbars:                            Scrollbars.
+* seekable_p:                            Lstream Methods.
+* selections:                            Modules for Interfacing with X Windows.
+* set_charptr_emchar:                    Working With Character and Byte Positions.
+* Sexton, Harlan:                        Lucid Emacs.
+* sound, native:                         Modules for Interfacing with the Operating System.
+* sound, network:                        Modules for Interfacing with the Operating System.
+* SPARCWorks:                            XEmacs.
+* specbinding stack; unwind-protects, dynamic binding; the: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* special forms, simple:                 Simple Special Forms.
+* specifiers:                            Specifiers.
+* stack frames; bindings, evaluation;:   Evaluation; Stack Frames; Bindings.
+* Stallman, Richard:                     A History of Emacs.
+* string:                                String.
+* string encoding, internal:             Internal String Encoding.
+* subprocesses:                          Subprocesses.
+* subprocesses, asynchronous:            Modules for Interfacing with the Operating System.
+* subprocesses, synchronous:             Modules for Interfacing with the Operating System.
+* Sun Microsystems:                      XEmacs.
+* sweep_bit_vectors_1:                   sweep_bit_vectors_1.
+* sweep_lcrecords_1:                     sweep_lcrecords_1.
+* sweep_strings:                         sweep_strings.
+* symbol:                                Symbol.
+* symbol values:                         Symbol Values.
+* symbols and variables:                 Symbols and Variables.
+* symbols, introduction to:              Introduction to Symbols.
+* synchronous subprocesses:              Modules for Interfacing with the Operating System.
+* tab controls:                          Tab Controls.
+* taxes, doing:                          XEmacs From the Outside.
+* techniques for XEmacs developers:      Techniques for XEmacs Developers.
+* TECO:                                  A History of Emacs.
+* temporary objects:                     The XEmacs Object System (Abstractly Speaking).
+* text in a buffer, the:                 The Text in a Buffer.
+* textual representation, buffers and:   Buffers and Textual Representation.
+* Thompson, Chuck:                       XEmacs.
+* throw, catch and:                      Catch and Throw.
+* types, dynamic:                        The Lisp Language.
+* types, lstream:                        Lstream Types.
+* types, proper use of unsigned:         Proper Use of Unsigned Types.
+* University of Illinois:                XEmacs.
+* unsigned types, proper use of:         Proper Use of Unsigned Types.
+* unwind-protects, dynamic binding; the specbinding stack;: Dynamic Binding; The specbinding Stack; Unwind-Protects.
+* values, symbol:                        Symbol Values.
+* variables, adding global Lisp:         Adding Global Lisp Variables.
+* variables, symbols and:                Symbols and Variables.
+* vector:                                Vector.
+* vector, bit:                           Bit Vector.
+* version 18, through:                   Through Version 18.
+* version 19, GNU Emacs:                 GNU Emacs 19.
+* version 20, GNU Emacs:                 GNU Emacs 20.
+* widget interface, generic:             Generic Widget Interface.
+* widget library, Lucid:                 Lucid Widget Library.
+* widget-glyphs:                         Glyphs.
+* widget-glyphs in the MS-Windows environment: Glyphs.
+* widget-glyphs in the X environment:    Glyphs.
+* Win-Emacs:                             XEmacs.
+* window (in Emacs):                     Modules for the Basic Displayable Lisp Objects.
+* window hierarchy:                      Window Hierarchy.
+* window object, the:                    The Window Object.
+* window point internals:                The Window Object.
+* windows, consoles; devices; frames;:   Consoles; Devices; Frames; Windows.
+* windows, introduction to consoles; devices; frames;: Introduction to Consoles; Devices; Frames; Windows.
+* Wing, Ben:                             XEmacs.
+* writer:                                Lstream Methods.
+* writing good comments:                 Writing Good Comments.
+* writing Lisp primitives:               Writing Lisp Primitives.
+* writing Mule-aware code, general guidelines for: General Guidelines for Writing Mule-Aware Code.
+* writing new C code, rules when:        Rules When Writing New C Code.
+* X environment, widget-glyphs in the:   Glyphs.
+* X Window System, interface to the:     Interface to the X Window System.
+* X Windows, modules for interfacing with: Modules for Interfacing with X Windows.
+* XEmacs:                                XEmacs.
+* XEmacs from the inside:                XEmacs From the Inside.
+* XEmacs from the outside:               XEmacs From the Outside.
+* XEmacs from the perspective of building: XEmacs From the Perspective of Building.
+* XEmacs goes it alone:                  XEmacs.
+* XEmacs object system (abstractly speaking), the: The XEmacs Object System (Abstractly Speaking).
+* Zawinski, Jamie:                       Lucid Emacs.
+* zero-length extents:                   Zero-Length Extents.
+
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info'
Index: ././info/lispref.info
--- ././info/lispref.info	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info	Thu May 17 23:26:54 2001
@@ -0,0 +1,919 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+Indirect:
+lispref.info-1: 2366
+lispref.info-2: 49116
+lispref.info-3: 97603
+lispref.info-4: 147443
+lispref.info-5: 197182
+lispref.info-6: 245536
+lispref.info-7: 293943
+lispref.info-8: 342609
+lispref.info-9: 387691
+lispref.info-10: 436623
+lispref.info-11: 485480
+lispref.info-12: 534011
+lispref.info-13: 581563
+lispref.info-14: 629421
+lispref.info-15: 678836
+lispref.info-16: 726831
+lispref.info-17: 772168
+lispref.info-18: 819638
+lispref.info-19: 867196
+lispref.info-20: 914822
+lispref.info-21: 962849
+lispref.info-22: 1011771
+lispref.info-23: 1058034
+lispref.info-24: 1104498
+lispref.info-25: 1154158
+lispref.info-26: 1202849
+lispref.info-27: 1251704
+lispref.info-28: 1300371
+lispref.info-29: 1350322
+lispref.info-30: 1398471
+lispref.info-31: 1444126
+lispref.info-32: 1494115
+lispref.info-33: 1542685
+lispref.info-34: 1589890
+lispref.info-35: 1639716
+lispref.info-36: 1688392
+lispref.info-37: 1734125
+lispref.info-38: 1783264
+lispref.info-39: 1830706
+lispref.info-40: 1879259
+lispref.info-41: 1925812
+lispref.info-42: 1974507
+lispref.info-43: 2018882
+lispref.info-44: 2063267
+lispref.info-45: 2109761
+lispref.info-46: 2150603
+lispref.info-47: 2199821
+lispref.info-48: 2213690
+
+Tag Table:
+(Indirect)
+Node: Top2366
+Node: Copying49116
+Node: Introduction68274
+Node: Caveats69865
+Node: Lisp History71544
+Node: Conventions72800
+Node: Some Terms73615
+Node: nil and t74336
+Node: Evaluation Notation76013
+Node: Printing Notation76926
+Node: Error Messages77800
+Node: Buffer Text Notation78241
+Node: Format of Descriptions79116
+Node: A Sample Function Description79970
+Node: A Sample Variable Description83956
+Node: Acknowledgements84864
+Node: Lisp Data Types86842
+Node: Printed Representation89397
+Node: Comments91439
+Node: Primitive Types92336
+Node: Programming Types93995
+Node: Integer Type95947
+Node: Floating Point Type96984
+Node: Character Type97603
+Node: Symbol Type105507
+Node: Sequence Type108202
+Node: Cons Cell Type109721
+Node: Dotted Pair Notation114205
+Node: Association List Type116326
+Node: Array Type117209
+Node: String Type118675
+Node: Vector Type121356
+Node: Bit Vector Type122128
+Node: Function Type122990
+Node: Macro Type124103
+Node: Primitive Function Type124800
+Node: Compiled-Function Type126326
+Node: Autoload Type126880
+Node: Char Table Type127894
+Node: Hash Table Type128068
+Node: Range Table Type129223
+Node: Weak List Type130076
+Node: Editing Types130226
+Node: Buffer Type131853
+Node: Marker Type133880
+Node: Extent Type134604
+Node: Window Type135872
+Node: Frame Type137283
+Node: Device Type138078
+Node: Console Type138904
+Node: Window Configuration Type140105
+Node: Event Type140803
+Node: Process Type140967
+Node: Stream Type142002
+Node: Keymap Type143125
+Node: Syntax Table Type143663
+Node: Display Table Type144686
+Node: Database Type145125
+Node: Charset Type145291
+Node: Coding System Type145455
+Node: ToolTalk Message Type145639
+Node: ToolTalk Pattern Type145838
+Node: Window-System Types146010
+Node: Face Type147156
+Node: Glyph Type147287
+Node: Specifier Type147443
+Node: Font Instance Type147616
+Node: Color Instance Type147806
+Node: Image Instance Type148003
+Node: Toolbar Button Type148201
+Node: Subwindow Type148394
+Node: X Resource Type148573
+Node: Type Predicates148726
+Node: Equality Predicates157855
+Node: Numbers162666
+Node: Integer Basics164121
+Node: Float Basics166470
+Node: Predicates on Numbers168212
+Node: Comparison of Numbers169845
+Node: Numeric Conversions173666
+Node: Arithmetic Operations175132
+Node: Rounding Operations181271
+Node: Bitwise Operations182384
+Node: Math Functions191430
+Node: Random Numbers193963
+Node: Strings and Characters195729
+Node: String Basics197182
+Node: Predicates for Strings199600
+Node: Creating Strings200363
+Node: Predicates for Characters205704
+Node: Character Codes206775
+Node: Text Comparison208195
+Node: String Conversion211640
+Node: Modifying Strings215310
+Node: String Properties215951
+Node: Formatting Strings216596
+Node: Character Case226214
+Node: Case Tables229768
+Node: Char Tables233739
+Node: Char Table Types235131
+Node: Working With Char Tables236716
+Node: Lists238733
+Node: Cons Cells239856
+Node: Lists as Boxes241192
+Node: List-related Predicates243834
+Node: List Elements245536
+Node: Building Lists250565
+Node: Modifying Lists256557
+Node: Setcar257369
+Node: Setcdr259800
+Node: Rearrangement262321
+Node: Sets And Lists267907
+Node: Association Lists272135
+Ref: Association Lists-Footnote-1281426
+Node: Property Lists281631
+Node: Working With Normal Plists283179
+Node: Working With Lax Plists285516
+Node: Converting Plists To/From Alists287796
+Node: Weak Lists289144
+Node: Sequences Arrays Vectors291307
+Node: Sequence Functions293943
+Node: Arrays297602
+Node: Array Functions300666
+Node: Vectors303199
+Node: Vector Functions304697
+Node: Bit Vectors307268
+Node: Bit Vector Functions308113
+Node: Symbols310412
+Node: Symbol Components311461
+Node: Definitions315644
+Node: Creating Symbols317869
+Node: Symbol Properties324903
+Node: Plists and Alists326430
+Node: Object Plists328179
+Node: Other Plists330939
+Node: Evaluation332738
+Node: Intro Eval333543
+Ref: Intro Eval-Footnote-1336896
+Node: Eval337031
+Node: Forms341450
+Node: Self-Evaluating Forms342609
+Node: Symbol Forms344122
+Node: Classifying Lists345039
+Node: Function Indirection345795
+Node: Function Forms348894
+Node: Macro Forms349891
+Node: Special Forms351491
+Node: Autoloading353800
+Node: Quoting354298
+Node: Control Structures355659
+Node: Sequencing357279
+Node: Conditionals360144
+Node: Combining Conditions363567
+Node: Iteration366837
+Node: Nonlocal Exits368616
+Node: Catch and Throw369318
+Node: Examples of Catch373157
+Node: Errors375176
+Node: Signaling Errors376665
+Node: Processing of Errors385412
+Node: Handling Errors387691
+Node: Error Symbols394932
+Node: Cleanups398888
+Node: Variables402666
+Node: Global Variables404435
+Node: Constant Variables405511
+Node: Local Variables406137
+Node: Void Variables411075
+Node: Defining Variables414591
+Node: Accessing Variables421755
+Node: Setting Variables423180
+Node: Variable Scoping427699
+Node: Scope429298
+Node: Extent430823
+Node: Impl of Scope432302
+Node: Using Scoping434265
+Node: Buffer-Local Variables435787
+Node: Intro to Buffer-Local436623
+Node: Creating Buffer-Local439166
+Node: Default Value445065
+Node: Variable Aliases448208
+Node: Functions450059
+Node: What Is a Function451153
+Node: Lambda Expressions455199
+Node: Lambda Components456109
+Node: Simple Lambda457941
+Node: Argument List459598
+Node: Function Documentation463326
+Node: Function Names465268
+Node: Defining Functions467841
+Node: Calling Functions470881
+Node: Mapping Functions474729
+Node: Anonymous Functions477417
+Node: Function Cells480662
+Node: Inline Functions485480
+Node: Related Topics487290
+Node: Macros488343
+Node: Simple Macro489627
+Node: Expansion490362
+Node: Compiling Macros493366
+Node: Defining Macros495202
+Node: Backquote496519
+Node: Problems with Macros498916
+Node: Argument Evaluation499611
+Node: Surprising Local Vars502526
+Node: Eval During Expansion504594
+Node: Repeated Expansion506287
+Node: Customization508203
+Node: Common Keywords508672
+Node: Group Definitions511517
+Node: Variable Definitions513709
+Node: Customization Types518699
+Node: Simple Types520134
+Node: Composite Types522291
+Node: Splicing into Lists526981
+Node: Type Keywords528816
+Node: Loading532336
+Node: How Programs Do Loading534011
+Node: Autoload543137
+Node: Repeated Loading549207
+Node: Named Features551320
+Node: Unloading557750
+Node: Hooks for Loading559906
+Node: Byte Compilation560623
+Node: Speed of Byte-Code562616
+Node: Compilation Functions563823
+Node: Docs and Compilation570480
+Node: Dynamic Loading573133
+Node: Eval During Compile575497
+Node: Compiled-Function Objects576762
+Node: Disassembly581563
+Node: Different Behavior588844
+Node: Debugging590189
+Node: Debugger591601
+Node: Error Debugging592746
+Node: Infinite Loops595499
+Node: Function Debugging596743
+Node: Explicit Debug599543
+Node: Using Debugger600314
+Node: Debugger Commands602176
+Node: Invoking the Debugger606493
+Node: Internals of Debugger610408
+Node: Syntax Errors615295
+Node: Excess Open616543
+Node: Excess Close618418
+Node: Compilation Errors619839
+Node: Edebug621127
+Node: Using Edebug623235
+Node: Instrumenting625932
+Node: Edebug Execution Modes629421
+Node: Jumping632531
+Node: Edebug Misc634874
+Node: Breakpoints636263
+Node: Global Break Condition639069
+Node: Embedded Breakpoints640024
+Node: Trapping Errors640979
+Node: Edebug Views643055
+Node: Edebug Eval645020
+Node: Eval List646197
+Node: Reading in Edebug649582
+Node: Printing in Edebug650381
+Node: Tracing652096
+Node: Coverage Testing653984
+Node: The Outside Context656025
+Node: Checking Whether to Stop656974
+Node: Edebug Display Update657621
+Node: Edebug Recursive Edit659644
+Node: Instrumenting Macro Calls661299
+Node: Specification List663781
+Node: Backtracking673192
+Node: Debugging Backquote675130
+Node: Specification Examples678836
+Node: Edebug Options680903
+Node: Read and Print686242
+Node: Streams Intro687219
+Node: Input Streams689237
+Node: Input Functions694138
+Node: Output Streams696198
+Node: Output Functions700249
+Node: Output Variables704549
+Node: Minibuffers709350
+Node: Intro to Minibuffers710502
+Node: Text from Minibuffer712690
+Node: Object from Minibuffer717784
+Node: Minibuffer History721877
+Node: Completion724856
+Node: Basic Completion726831
+Node: Minibuffer Completion731714
+Node: Completion Commands735291
+Node: High-Level Completion739948
+Node: Reading File Names744697
+Node: Programmed Completion748389
+Node: Yes-or-No Queries750771
+Node: Multiple Queries756508
+Node: Reading a Password760575
+Node: Minibuffer Misc761918
+Node: Command Loop766798
+Node: Command Overview768142
+Node: Defining Commands771420
+Node: Using Interactive772168
+Node: Interactive Codes776941
+Node: Interactive Examples782733
+Node: Interactive Call784047
+Node: Command Loop Info789462
+Node: Events794441
+Node: Event Types795902
+Node: Event Contents797825
+Node: Event Predicates802301
+Node: Accessing Mouse Event Positions803619
+Node: Frame-Level Event Position Info804318
+Node: Window-Level Event Position Info805358
+Node: Event Text Position Info807122
+Node: Event Glyph Position Info809614
+Node: Event Toolbar Position Info810937
+Node: Other Event Position Info811608
+Node: Accessing Other Event Info812017
+Node: Working With Events813637
+Node: Converting Events819638
+Node: Reading Input823037
+Node: Key Sequence Input824039
+Node: Reading One Event826674
+Node: Dispatching an Event829498
+Node: Quoted Character Input829949
+Node: Peeking and Discarding831297
+Node: Waiting835201
+Node: Quitting837515
+Node: Prefix Command Arguments841923
+Node: Recursive Editing847010
+Node: Disabling Commands851805
+Node: Command History853873
+Node: Keyboard Macros855610
+Node: Keymaps857827
+Node: Keymap Terminology859404
+Node: Format of Keymaps862333
+Node: Creating Keymaps862744
+Node: Inheritance and Keymaps864824
+Node: Key Sequences867196
+Node: Prefix Keys871992
+Node: Active Keymaps875577
+Node: Key Lookup884948
+Node: Functions for Key Lookup890111
+Node: Changing Key Bindings895812
+Node: Key Binding Commands902974
+Node: Scanning Keymaps905039
+Node: Other Keymap Functions913608
+Node: Menus914230
+Node: Menu Format914822
+Node: Menubar Format923468
+Node: Menubar924093
+Node: Modifying Menus927206
+Node: Menu Filters932550
+Node: Pop-Up Menus934446
+Node: Menu Accelerators936774
+Node: Creating Menu Accelerators937530
+Node: Keyboard Menu Traversal938890
+Node: Menu Accelerator Functions939617
+Node: Buffers Menu942693
+Node: Dialog Boxes943987
+Node: Dialog Box Format944154
+Node: Dialog Box Functions945579
+Node: Toolbar945976
+Node: Toolbar Intro946411
+Node: Creating Toolbar948811
+Node: Toolbar Descriptor Format949728
+Node: Specifying the Toolbar954225
+Node: Other Toolbar Variables957832
+Node: Gutter962260
+Node: Gutter Intro962849
+Node: Creating Gutter964852
+Node: Gutter Descriptor Format967739
+Node: Specifying a Gutter972196
+Node: Other Gutter Variables975731
+Node: Common Gutter Widgets980118
+Node: Buffer Tabs981110
+Node: Progress Bars981251
+Node: Scrollbars981396
+Node: Drag and Drop981531
+Node: Supported Protocols982607
+Node: OffiX DND983110
+Node: CDE dt984117
+Node: MSWindows OLE984708
+Node: Loose ends984879
+Node: Drop Interface985271
+Node: Drag Interface986293
+Node: Modes986467
+Node: Major Modes987418
+Node: Major Mode Conventions990333
+Node: Example Major Modes996288
+Node: Auto Major Mode1004321
+Node: Mode Help1011771
+Node: Derived Modes1012872
+Node: Minor Modes1015063
+Node: Minor Mode Conventions1016365
+Node: Keymaps and Minor Modes1019228
+Node: Modeline Format1020063
+Node: Modeline Data1021831
+Node: Modeline Variables1026984
+Node: %-Constructs1031700
+Node: Hooks1034687
+Node: Documentation1041447
+Node: Documentation Basics1042870
+Node: Accessing Documentation1045921
+Node: Keys in Documentation1052202
+Node: Describing Characters1055685
+Node: Help Functions1058034
+Node: Obsoleteness1064484
+Node: Files1067476
+Node: Visiting Files1069401
+Node: Visiting Functions1070906
+Node: Subroutines of Visiting1076064
+Node: Saving Buffers1078137
+Node: Reading from Files1084230
+Node: Writing to Files1086391
+Node: File Locks1089108
+Node: Information about Files1092175
+Node: Testing Accessibility1092936
+Node: Kinds of Files1096676
+Node: Truenames1098357
+Node: File Attributes1099359
+Node: Changing File Attributes1104498
+Node: File Names1109920
+Node: File Name Components1111493
+Node: Directory Names1113938
+Node: Relative File Names1117168
+Node: File Name Expansion1118138
+Node: Unique File Names1121892
+Node: File Name Completion1123507
+Node: User Name Completion1126775
+Node: Contents of Directories1128182
+Node: Create/Delete Dirs1131495
+Node: Magic File Names1132601
+Node: Partial Files1138249
+Node: Intro to Partial Files1138477
+Node: Creating a Partial File1139717
+Node: Detached Partial Files1140653
+Node: Format Conversion1141775
+Node: Files and MS-DOS1147273
+Node: Backups and Auto-Saving1149337
+Node: Backup Files1150012
+Node: Making Backups1151409
+Node: Rename or Copy1154158
+Node: Numbered Backups1156651
+Node: Backup Names1158886
+Node: Auto-Saving1162178
+Node: Reverting1170340
+Node: Buffers1173676
+Node: Buffer Basics1175092
+Node: Current Buffer1177145
+Node: Buffer Names1181849
+Node: Buffer File Name1185056
+Node: Buffer Modification1189175
+Node: Modification Time1191418
+Node: Read Only Buffers1194793
+Node: The Buffer List1198032
+Node: Creating Buffers1202849
+Node: Killing Buffers1204995
+Node: Indirect Buffers1208827
+Node: Windows1211401
+Node: Basic Windows1212879
+Node: Splitting Windows1215977
+Node: Deleting Windows1221303
+Node: Selecting Windows1225221
+Node: Cyclic Window Ordering1229444
+Node: Buffers and Windows1234599
+Node: Displaying Buffers1236377
+Node: Choosing Window1241716
+Node: Window Point1249634
+Node: Window Start1251704
+Node: Vertical Scrolling1256503
+Node: Horizontal Scrolling1262701
+Node: Size of Window1266230
+Node: Position of Window1270948
+Node: Resizing Windows1273201
+Node: Window Configurations1278639
+Node: Frames1282136
+Node: Creating Frames1284477
+Node: Frame Properties1285817
+Node: Property Access1286633
+Node: Initial Properties1287540
+Node: X Frame Properties1290026
+Node: Size and Position1294660
+Node: Frame Name1296658
+Node: Frame Titles1297572
+Node: Deleting Frames1299396
+Node: Finding All Frames1300371
+Node: Frames and Windows1303599
+Node: Minibuffers and Frames1306381
+Node: Input Focus1307299
+Node: Visibility of Frames1310404
+Node: Raising and Lowering1312394
+Node: Frame Configurations1314770
+Node: Frame Hooks1315827
+Node: Consoles and Devices1317632
+Node: Basic Console Functions1320375
+Node: Basic Device Functions1320798
+Node: Console Types and Device Classes1321644
+Node: Connecting to a Console or Device1323911
+Node: The Selected Console and Device1326095
+Node: Console and Device I/O1327121
+Node: Positions1327885
+Node: Point1328854
+Node: Motion1331944
+Node: Character Motion1332711
+Node: Word Motion1334948
+Node: Buffer End Motion1336338
+Node: Text Lines1337875
+Node: Screen Lines1342776
+Node: List Motion1346839
+Node: Skipping Characters1350322
+Node: Excursions1352541
+Node: Narrowing1355581
+Node: Markers1360912
+Node: Overview of Markers1361818
+Node: Predicates on Markers1366510
+Node: Creating Markers1367756
+Node: Information from Markers1371956
+Node: Changing Markers1373054
+Node: The Mark1374582
+Node: The Region1383085
+Node: Text1388771
+Node: Near Point1391470
+Node: Buffer Contents1395657
+Node: Comparing Text1397063
+Node: Insertion1398471
+Node: Commands for Insertion1402381
+Node: Deletion1405275
+Node: User-Level Deletion1408925
+Node: The Kill Ring1413085
+Node: Kill Ring Concepts1415259
+Node: Kill Functions1416313
+Node: Yank Commands1418236
+Node: Low-Level Kill Ring1420107
+Node: Internals of Kill Ring1423193
+Node: Undo1425973
+Node: Maintaining Undo1430310
+Node: Filling1432928
+Node: Margins1438922
+Node: Auto Filling1442945
+Node: Sorting1444126
+Node: Columns1453440
+Node: Indentation1456521
+Node: Primitive Indent1457300
+Node: Mode-Specific Indent1458625
+Node: Region Indent1461157
+Node: Relative Indent1464104
+Node: Indent Tabs1466486
+Node: Motion by Indent1467807
+Node: Case Changes1468586
+Node: Text Properties1471939
+Node: Examining Properties1473752
+Node: Changing Properties1475635
+Node: Property Search1479226
+Node: Special Properties1483945
+Node: Saving Properties1484226
+Node: Substitution1487368
+Node: Registers1490638
+Node: Transposition1493221
+Node: Change Hooks1494115
+Node: Transformations1496155
+Node: Searching and Matching1501259
+Node: String Search1502390
+Node: Regular Expressions1507371
+Node: Syntax of Regexps1508738
+Node: Regexp Example1523341
+Node: Regexp Search1525511
+Node: POSIX Regexps1531848
+Node: Search and Replace1533925
+Node: Match Data1537290
+Node: Simple Match Data1538420
+Node: Replacing Match1542685
+Node: Entire Match Data1545366
+Node: Saving Match Data1547604
+Node: Searching and Case1548992
+Node: Standard Regexps1551026
+Node: Syntax Tables1553224
+Node: Syntax Basics1554338
+Node: Syntax Descriptors1557310
+Node: Syntax Class Table1559160
+Node: Syntax Flags1565198
+Node: Syntax Table Functions1568415
+Node: Motion and Syntax1572703
+Node: Parsing Expressions1574155
+Node: Standard Syntax Tables1580253
+Node: Syntax Table Internals1581097
+Node: Abbrevs1582123
+Node: Abbrev Mode1583927
+Node: Abbrev Tables1584647
+Node: Defining Abbrevs1586186
+Node: Abbrev Files1588107
+Node: Abbrev Expansion1589890
+Node: Standard Abbrev Tables1594521
+Node: Extents1595680
+Node: Intro to Extents1596923
+Node: Creating and Modifying Extents1600915
+Node: Extent Endpoints1602496
+Node: Finding Extents1605759
+Node: Mapping Over Extents1609881
+Node: Extent Properties1616004
+Node: Detached Extents1626165
+Node: Extent Parents1628024
+Node: Duplicable Extents1629718
+Node: Extents and Events1632939
+Node: Atomic Extents1634846
+Node: Specifiers1635293
+Node: Introduction to Specifiers1637406
+Node: Specifiers In-Depth1639716
+Node: Specifier Instancing1644628
+Node: Specifier Types1647890
+Node: Adding Specifications1652964
+Node: Retrieving Specifications1662385
+Node: Specifier Tag Functions1666130
+Node: Specifier Instancing Functions1669364
+Node: Specifier Example1672771
+Node: Creating Specifiers1675927
+Node: Specifier Validation Functions1680244
+Node: Other Specification Functions1682630
+Node: Faces and Window-System Objects1686451
+Node: Faces1686775
+Node: Merging Faces1688392
+Node: Basic Face Functions1690353
+Node: Face Properties1692501
+Node: Face Convenience Functions1702774
+Node: Other Face Display Functions1705994
+Node: Fonts1706806
+Node: Font Specifiers1707507
+Node: Font Instances1708692
+Node: Font Instance Names1709659
+Node: Font Instance Size1710500
+Node: Font Instance Characteristics1711786
+Node: Font Convenience Functions1712964
+Node: Colors1714254
+Node: Color Specifiers1714694
+Node: Color Instances1717054
+Node: Color Instance Properties1717798
+Node: Color Convenience Functions1718424
+Node: Glyphs1719477
+Node: Glyph Functions1721078
+Node: Creating Glyphs1721485
+Node: Glyph Properties1734125
+Node: Glyph Convenience Functions1743292
+Node: Glyph Dimensions1747239
+Node: Images1748319
+Node: Image Specifiers1748768
+Node: Image Instantiator Conversion1764259
+Node: Image Instances1765624
+Node: Image Instance Types1766375
+Node: Image Instance Functions1769140
+Node: Glyph Types1776197
+Node: Mouse Pointer1777969
+Node: Redisplay Glyphs1780972
+Node: Subwindows1782005
+Node: Annotations1782248
+Node: Annotation Basics1783264
+Node: Annotation Primitives1787202
+Node: Annotation Properties1788541
+Node: Locating Annotations1791581
+Node: Margin Primitives1792418
+Node: Annotation Hooks1794312
+Node: Display1794972
+Node: Refresh Screen1795950
+Node: Truncation1798144
+Node: The Echo Area1800669
+Node: Warnings1807112
+Node: Invisible Text1811548
+Node: Selective Display1814127
+Node: Overlay Arrow1818253
+Node: Temporary Displays1819606
+Node: Blinking1823727
+Node: Usual Display1825911
+Node: Display Tables1828460
+Node: Display Table Format1829264
+Node: Active Display Table1830706
+Node: Character Descriptors1834701
+Node: Beeping1835458
+Node: Hash Tables1840224
+Node: Introduction to Hash Tables1840832
+Node: Working With Hash Tables1847391
+Node: Weak Hash Tables1848508
+Node: Range Tables1850525
+Node: Introduction to Range Tables1851214
+Node: Working With Range Tables1851660
+Node: Databases1852619
+Node: Connecting to a Database1852918
+Node: Working With a Database1854025
+Node: Other Database Functions1854899
+Node: Processes1855468
+Node: Subprocess Creation1857692
+Node: Synchronous Processes1861143
+Node: MS-DOS Subprocesses1867865
+Node: Asynchronous Processes1868939
+Node: Deleting Processes1873296
+Node: Process Information1875167
+Node: Input to Processes1879259
+Node: Signals to Processes1881954
+Node: Output from Processes1886769
+Node: Process Buffers1887581
+Node: Filter Functions1890460
+Node: Accepting Output1896051
+Node: Sentinels1897578
+Node: Process Window Size1901068
+Node: Transaction Queues1901417
+Node: Network1903115
+Node: System Interface1905749
+Node: Starting Up1907019
+Node: Start-up Summary1907613
+Node: Init File1911167
+Node: Terminal-Specific1913548
+Node: Command Line Arguments1916707
+Node: Getting Out1920196
+Node: Killing XEmacs1920765
+Node: Suspending XEmacs1922433
+Node: System Environment1925812
+Node: User Identification1931993
+Node: Time of Day1935522
+Node: Time Conversion1938309
+Node: Timers1943551
+Node: Terminal Input1945724
+Node: Input Modes1946227
+Node: Translating Input1948686
+Node: Recording Input1952851
+Node: Terminal Output1954951
+Node: Flow Control1958572
+Node: Batch Mode1962534
+Node: X-Windows1963916
+Node: X Selections1964787
+Node: X Server1967538
+Node: Resources1967989
+Node: Server Data1973300
+Node: Grabs1974507
+Node: X Miscellaneous1976087
+Node: ToolTalk Support1978472
+Node: XEmacs ToolTalk API Summary1978689
+Node: Sending Messages1979989
+Node: Example of Sending Messages1980240
+Node: Elisp Interface for Sending Messages1981302
+Node: Receiving Messages1987898
+Node: Example of Receiving Messages1988121
+Node: Elisp Interface for Receiving Messages1988957
+Node: LDAP Support1992814
+Node: Building XEmacs with LDAP support1993308
+Node: XEmacs LDAP API1994285
+Node: LDAP Variables1995337
+Node: The High-Level LDAP API1997937
+Node: The Low-Level LDAP API2001410
+Node: The LDAP Lisp Object2002241
+Node: Opening and Closing a LDAP Connection2002796
+Node: Low-level Operations on a LDAP Server2004602
+Node: LDAP Internationalization2007326
+Node: LDAP Internationalization Variables2008231
+Node: Encoder/Decoder Functions2009962
+Node: Syntax of Search Filters2010999
+Node: PostgreSQL Support2012297
+Node: Building XEmacs with PostgreSQL support2012692
+Node: XEmacs PostgreSQL libpq API2014039
+Node: libpq Lisp Variables2015918
+Node: libpq Lisp Symbols and DataTypes2018882
+Node: Synchronous Interface Functions2032138
+Node: Asynchronous Interface Functions2036629
+Node: Large Object Support2040134
+Node: Other libpq Functions2040761
+Node: Unimplemented libpq Functions2043796
+Node: XEmacs PostgreSQL libpq Examples2049115
+Node: Internationalization2055206
+Node: I18N Levels 1 and 22055549
+Node: I18N Level 32056255
+Node: Level 3 Basics2056536
+Node: Level 3 Primitives2057369
+Node: Dynamic Messaging2058975
+Node: Domain Specification2059438
+Node: Documentation String Extraction2061108
+Node: I18N Level 42062026
+Node: MULE2062218
+Node: Internationalization Terminology2063267
+Node: Charsets2075466
+Node: Charset Properties2076162
+Node: Basic Charset Functions2080877
+Node: Charset Property Functions2083058
+Node: Predefined Charsets2085128
+Node: MULE Characters2088048
+Node: Composite Characters2088923
+Node: Coding Systems2090190
+Node: Coding System Types2092330
+Node: ISO 20222096314
+Node: EOL Conversion2108589
+Node: Coding System Properties2109761
+Node: Basic Coding System Functions2114084
+Node: Coding System Property Functions2116118
+Node: Encoding and Decoding Text2116676
+Node: Detection of Textual Encoding2117812
+Node: Big5 and Shift-JIS Functions2119348
+Node: Predefined Coding Systems2120500
+Node: CCL2132594
+Node: CCL Syntax2135698
+Node: CCL Statements2137274
+Node: CCL Expressions2141922
+Node: Calling CCL2144461
+Node: CCL Examples2147466
+Node: Category Tables2147603
+Node: Tips2149962
+Node: Style Tips2150603
+Node: Compilation Tips2160122
+Node: Documentation Tips2162036
+Node: Comment Tips2167545
+Node: Library Headers2170548
+Node: Building XEmacs and Object Allocation2174520
+Node: Building XEmacs2175403
+Node: Pure Storage2181981
+Node: Garbage Collection2184769
+Node: Standard Errors2195612
+Node: Standard Buffer-Local Variables2199821
+Node: Standard Keymaps2202456
+Node: Standard Hooks2206190
+Node: Index2213690
+
+End Tag Table
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-1'
Index: ././info/lispref.info-1
--- ././info/lispref.info-1	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-1	Thu May 17 23:26:54 2001
@@ -0,0 +1,1082 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
+
+   This Info file contains the third edition of the XEmacs Lisp
+Reference Manual, corresponding to XEmacs version 21.0.
+
+* Menu:
+
+* Copying::                 Conditions for copying and changing XEmacs.
+* Introduction::            Introduction and conventions used.
+
+* Lisp Data Types::         Data types of objects in XEmacs Lisp.
+* Numbers::                 Numbers and arithmetic functions.
+* Strings and Characters::  Strings, and functions that work on them.
+* Lists::                   Lists, cons cells, and related functions.
+* Sequences Arrays Vectors::  Lists, strings and vectors are called sequences.
+                                Certain functions act on any kind of sequence.
+                                The description of vectors is here as well.
+* Symbols::                 Symbols represent names, uniquely.
+
+* Evaluation::              How Lisp expressions are evaluated.
+* Control Structures::      Conditionals, loops, nonlocal exits.
+* Variables::               Using symbols in programs to stand for values.
+* Functions::               A function is a Lisp program
+                              that can be invoked from other functions.
+* Macros::                  Macros are a way to extend the Lisp language.
+* Customization::           Writing customization declarations.
+
+* Loading::                 Reading files of Lisp code into Lisp.
+* Byte Compilation::        Compilation makes programs run faster.
+* Debugging::               Tools and tips for debugging Lisp programs.
+
+* Read and Print::          Converting Lisp objects to text and back.
+* Minibuffers::             Using the minibuffer to read input.
+* Command Loop::            How the editor command loop works,
+                              and how you can call its subroutines.
+* Keymaps::                 Defining the bindings from keys to commands.
+* Menus::                   Defining pull-down and pop-up menus.
+* Dialog Boxes::	    Creating dialog boxes.
+* Toolbar::		    Controlling the toolbar.
+* Gutter::		    Controlling the gutter.
+* Scrollbars::		    Controlling the scrollbars.
+* Drag and Drop::	    Generic API to inter-application communication
+                              via specific protocols.
+* Modes::                   Defining major and minor modes.
+* Documentation::           Writing and using documentation strings.
+
+* Files::                   Accessing files.
+* Backups and Auto-Saving:: Controlling how backups and auto-save
+                              files are made.
+* Buffers::                 Creating and using buffer objects.
+* Windows::                 Manipulating windows and displaying buffers.
+* Frames::		    Making multiple X windows.
+* Consoles and Devices::    Opening frames on multiple TTY's or X displays.
+* Positions::               Buffer positions and motion functions.
+* Markers::                 Markers represent positions and update
+                              automatically when the text is changed.
+
+* Text::                    Examining and changing text in buffers.
+* Searching and Matching::  Searching buffers for strings or regexps.
+* Syntax Tables::           The syntax table controls word and list parsing.
+* Abbrevs::                 How Abbrev mode works, and its data structures.
+
+* Extents::                 Extents are regions of text with particular
+                              display characteristics.
+* Specifiers::		    How faces and glyphs are specified.
+* Faces and Window-System Objects::
+        		    A face is a set of display characteristics
+                              specifying how text is to be displayed.
+* Glyphs::		    General interface to pixmaps displayed in a
+			      buffer or frame.
+* Annotations::             Higher-level interface to glyphs in a buffer.
+* Display::	            Parameters controlling screen usage.
+                              The bell.  Waiting for input.
+
+* Hash Tables::             Fast data structures for mappings.
+* Range Tables::            Keeping track of ranges of numbers.
+* Databases::               An interface to standard DBM and DB databases.
+
+* Processes::               Running and communicating with subprocesses.
+* System Interface::        Getting the user id, system type, environment
+                              variables, and other such things.
+* X-Windows::		    Functions specific to the X Window System.
+* ToolTalk Support::        Interfacing with the ToolTalk message service.
+* LDAP Support::            Interfacing with the Lightweight Directory
+                              Access Protocol.
+* PostgreSQL Support::      Interfacing to the PostgreSQL libpq library.
+* Internationalization::    How Emacs supports different languages and
+                              cultural conventions.
+* MULE::                    Specifics of the Asian-language support.
+
+Appendices
+
+* Tips::                    Advice for writing Lisp programs.
+* Building XEmacs and Object Allocation::
+                            Behind-the-scenes information about XEmacs.
+* Standard Errors::         List of all error symbols.
+* Standard Buffer-Local Variables::  List of variables local in all buffers.
+* Standard Keymaps::        List of standard keymaps.
+* Standard Hooks::          List of standard hook variables.
+
+* Index::                   Index including concepts, functions, variables,
+                              and other terms.
+
+      --- The Detailed Node Listing ---
+
+Here are other nodes that are inferiors of those already listed,
+mentioned here so you can get to them in one step:
+
+Introduction
+
+* Caveats::                 Flaws and a request for help.
+* Lisp History::            XEmacs Lisp is descended from Maclisp.
+* Conventions::             How the manual is formatted.
+* Acknowledgements::        The authors, editors, and sponsors of this manual.
+
+Conventions
+
+* Some Terms::              Explanation of terms we use in this manual.
+* nil and t::               How the symbols `nil' and `t' are used.
+* Evaluation Notation::     The format we use for examples of evaluation.
+* Printing Notation::       The format we use for examples that print output.
+* Error Messages::          The format we use for examples of errors.
+* Buffer Text Notation::    The format we use for buffer contents in examples.
+* Format of Descriptions::  Notation for describing functions, variables, etc.
+
+Format of Descriptions
+
+* A Sample Function Description::
+* A Sample Variable Description::
+
+Lisp Data Types
+
+* Printed Representation::  How Lisp objects are represented as text.
+* Comments::                Comments and their formatting conventions.
+* Programming Types::       Types found in all Lisp systems.
+* Editing Types::           Types specific to XEmacs.
+* Type Predicates::         Tests related to types.
+* Equality Predicates::     Tests of equality between any two objects.
+
+Programming Types
+
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                        control characters.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, property list, or itself.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Compiled-Function Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                        functions.
+
+Cons Cell Type
+
+* Dotted Pair Notation::    An alternative syntax for lists.
+* Association List Type::   A specially constructed list.
+
+Editing Types
+
+* Buffer Type::             The basic object of editing.
+* Window Type::             What makes buffers visible.
+* Window Configuration Type:: Save what the screen looks like.
+* Marker Type::             A position in a buffer.
+* Process Type::            A process running on the underlying OS.
+* Stream Type::             Receive or send characters.
+* Keymap Type::             What function a keystroke invokes.
+* Syntax Table Type::       What a character means.
+
+Numbers
+
+* Integer Basics::            Representation and range of integers.
+* Float Basics::	      Representation and range of floating point.
+* Predicates on Numbers::     Testing for numbers.
+* Comparison of Numbers::     Equality and inequality predicates.
+* Arithmetic Operations::     How to add, subtract, multiply and divide.
+* Bitwise Operations::        Logical and, or, not, shifting.
+* Numeric Conversions::	      Converting float to integer and vice versa.
+* Math Functions::            Trig, exponential and logarithmic functions.
+* Random Numbers::            Obtaining random integers, predictable or not.
+
+Strings and Characters
+
+* String Basics::             Basic properties of strings and characters.
+* Predicates for Strings::    Testing whether an object is a string or char.
+* Creating Strings::          Functions to allocate new strings.
+* Predicates for Characters:: Testing whether an object is a character.
+* Character Codes::           Each character has an equivalent integer.
+* Text Comparison::           Comparing characters or strings.
+* String Conversion::         Converting characters or strings and vice versa.
+* Modifying Strings::	      Changing characters in a string.
+* String Properties::	      Additional information attached to strings.
+* Formatting Strings::        `format': XEmacs's analog of `printf'.
+* Character Case::            Case conversion functions.
+* Char Tables::               Mapping from characters to Lisp objects.
+* Case Tables::		      Customizing case conversion.
+
+Lists
+
+* Cons Cells::              How lists are made out of cons cells.
+* Lists as Boxes::          Graphical notation to explain lists.
+* List-related Predicates:: Is this object a list?  Comparing two lists.
+* List Elements::           Extracting the pieces of a list.
+* Building Lists::          Creating list structure.
+* Modifying Lists::         Storing new pieces into an existing list.
+* Sets And Lists::          A list can represent a finite mathematical set.
+* Association Lists::       A list can represent a finite relation or mapping.
+* Property Lists::          A different way to represent a finite mapping.
+* Weak Lists::              A list with special garbage-collection behavior.
+
+Modifying Existing List Structure
+
+* Setcar::                  Replacing an element in a list.
+* Setcdr::                  Replacing part of the list backbone.
+                              This can be used to remove or add elements.
+* Rearrangement::           Reordering the elements in a list; combining lists.
+
+Sequences, Arrays, and Vectors
+
+* Sequence Functions::      Functions that accept any kind of sequence.
+* Arrays::                  Characteristics of arrays in XEmacs Lisp.
+* Array Functions::         Functions specifically for arrays.
+* Vectors::                 Functions specifically for vectors.
+
+Symbols
+
+* Symbol Components::       Symbols have names, values, function definitions
+                              and property lists.
+* Definitions::             A definition says how a symbol will be used.
+* Creating Symbols::        How symbols are kept unique.
+* Symbol Properties::       Each symbol has a property list
+                              for recording miscellaneous information.
+
+Evaluation
+
+* Intro Eval::              Evaluation in the scheme of things.
+* Eval::                    How to invoke the Lisp interpreter explicitly.
+* Forms::                   How various sorts of objects are evaluated.
+* Quoting::                 Avoiding evaluation (to put constants in
+                              the program).
+
+Kinds of Forms
+
+* Self-Evaluating Forms::   Forms that evaluate to themselves.
+* Symbol Forms::            Symbols evaluate as variables.
+* Classifying Lists::       How to distinguish various sorts of list forms.
+* Function Forms::          Forms that call functions.
+* Macro Forms::             Forms that call macros.
+* Special Forms::           ``Special forms'' are idiosyncratic primitives,
+                              most of them extremely important.
+* Autoloading::             Functions set up to load files
+                              containing their real definitions.
+
+Control Structures
+
+* Sequencing::              Evaluation in textual order.
+* Conditionals::            `if', `cond'.
+* Combining Conditions::    `and', `or', `not'.
+* Iteration::               `while' loops.
+* Nonlocal Exits::          Jumping out of a sequence.
+
+Nonlocal Exits
+
+* Catch and Throw::         Nonlocal exits for the program's own purposes.
+* Examples of Catch::       Showing how such nonlocal exits can be written.
+* Errors::                  How errors are signaled and handled.
+* Cleanups::                Arranging to run a cleanup form if an
+                              error happens.
+
+Errors
+
+* Signaling Errors::        How to report an error.
+* Processing of Errors::    What XEmacs does when you report an error.
+* Handling Errors::         How you can trap errors and continue execution.
+* Error Symbols::           How errors are classified for trapping them.
+
+Variables
+
+* Global Variables::        Variable values that exist permanently, everywhere.
+* Constant Variables::      Certain "variables" have values that never change.
+* Local Variables::         Variable values that exist only temporarily.
+* Void Variables::          Symbols that lack values.
+* Defining Variables::      A definition says a symbol is used as a variable.
+* Accessing Variables::     Examining values of variables whose names
+                              are known only at run time.
+* Setting Variables::       Storing new values in variables.
+* Variable Scoping::        How Lisp chooses among local and global values.
+* Buffer-Local Variables::  Variable values in effect only in one buffer.
+
+Scoping Rules for Variable Bindings
+
+* Scope::                   Scope means where in the program a value
+                              is visible.  Comparison with other languages.
+* Extent::                  Extent means how long in time a value exists.
+* Impl of Scope::           Two ways to implement dynamic scoping.
+* Using Scoping::           How to use dynamic scoping carefully and
+                              avoid problems.
+
+Buffer-Local Variables
+
+* Intro to Buffer-Local::   Introduction and concepts.
+* Creating Buffer-Local::   Creating and destroying buffer-local bindings.
+* Default Value::           The default value is seen in buffers
+                              that don't have their own local values.
+
+Functions
+
+* What Is a Function::      Lisp functions vs primitives; terminology.
+* Lambda Expressions::      How functions are expressed as Lisp objects.
+* Function Names::          A symbol can serve as the name of a function.
+* Defining Functions::      Lisp expressions for defining functions.
+* Calling Functions::       How to use an existing function.
+* Mapping Functions::       Applying a function to each element of a list, etc.
+* Anonymous Functions::     Lambda-expressions are functions with no names.
+* Function Cells::          Accessing or setting the function definition
+                              of a symbol.
+* Related Topics::          Cross-references to specific Lisp primitives
+                              that have a special bearing on how
+                              functions work.
+
+Lambda Expressions
+
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+
+Macros
+
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+
+Loading
+
+* How Programs Do Loading:: The `load' function and others.
+* Autoload::                Setting up a function to autoload.
+* Named Features::          Loading a library if it isn't already loaded.
+* Repeated Loading::        Precautions about loading a file twice.
+
+Byte Compilation
+
+* Speed of Byte-Code::          An example of speedup from byte compilation.
+* Compilation Functions::       Byte compilation functions.
+* Docs and Compilation::        Dynamic loading of documentation strings.
+* Dynamic Loading::             Dynamic loading of individual functions.
+* Eval During Compile::  	Code to be evaluated when you compile.
+* Compiled-Function Objects::	The data type used for byte-compiled functions.
+* Disassembly::                 Disassembling byte-code; how to read byte-code.
+* Different Behavior::          When compiled code gives different results.
+
+Debugging Lisp Programs
+
+* Debugger::                How the XEmacs Lisp debugger is implemented.
+* Syntax Errors::           How to find syntax errors.
+* Compilation Errors::      How to find errors that show up in
+                              byte compilation.
+* Edebug::                  A source-level XEmacs Lisp debugger.
+
+The Lisp Debugger
+
+* Error Debugging::         Entering the debugger when an error happens.
+* Function Debugging::      Entering it when a certain function is called.
+* Explicit Debug::          Entering it at a certain point in the program.
+* Using Debugger::          What the debugger does; what you see while in it.
+* Debugger Commands::       Commands used while in the debugger.
+* Invoking the Debugger::   How to call the function `debug'.
+* Internals of Debugger::   Subroutines of the debugger, and global variables.
+
+Debugging Invalid Lisp Syntax
+
+* Excess Open::             How to find a spurious open paren or missing close.
+* Excess Close::            How to find a spurious close paren or missing open.
+
+Reading and Printing Lisp Objects
+
+* Streams Intro::           Overview of streams, reading and printing.
+* Input Streams::           Various data types that can be used as
+                              input streams.
+* Input Functions::         Functions to read Lisp objects from text.
+* Output Streams::          Various data types that can be used as
+                              output streams.
+* Output Functions::        Functions to print Lisp objects as text.
+
+Minibuffers
+
+* Intro to Minibuffers::    Basic information about minibuffers.
+* Text from Minibuffer::    How to read a straight text string.
+* Object from Minibuffer::  How to read a Lisp object or expression.
+* Completion::              How to invoke and customize completion.
+* Yes-or-No Queries::       Asking a question with a simple answer.
+* Minibuffer Misc::         Various customization hooks and variables.
+
+Completion
+
+* Basic Completion::        Low-level functions for completing strings.
+                              (These are too low level to use the minibuffer.)
+* Minibuffer Completion::   Invoking the minibuffer with completion.
+* Completion Commands::     Minibuffer commands that do completion.
+* High-Level Completion::   Convenient special cases of completion
+                              (reading buffer name, file name, etc.)
+* Reading File Names::      Using completion to read file names.
+* Programmed Completion::   Finding the completions for a given file name.
+
+Command Loop
+
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Events::		What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How C-g works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+
+Defining Commands
+
+* Using Interactive::       General rules for `interactive'.
+* Interactive Codes::       The standard letter-codes for reading arguments
+                              in various ways.
+* Interactive Examples::    Examples of how to read interactive arguments.
+
+Events
+
+* Event Types::			Events come in different types.
+* Event Contents::		What the contents of each event type are.
+* Event Predicates::		Querying whether an event is of a
+				  particular type.
+* Accessing Mouse Event Positions::
+				Determining where a mouse event occurred,
+				  and over what.
+* Accessing Other Event Info::  Accessing non-positional event info.
+* Working With Events::		Creating, copying, and destroying events.
+* Converting Events::		Converting between events, keys, and
+				  characters.
+
+Accessing Mouse Event Positions
+
+* Frame-Level Event Position Info::
+* Window-Level Event Position Info::
+* Event Text Position Info::
+* Event Glyph Position Info::
+* Event Toolbar Position Info::
+* Other Event Position Info::
+
+Reading Input
+
+* Key Sequence Input::		How to read one key sequence.
+* Reading One Event::		How to read just one event.
+* Dispatching an Event::        What to do with an event once it has been read.
+* Quoted Character Input::	Asking the user to specify a character.
+* Peeking and Discarding::	How to reread or throw away input events.
+
+Keymaps
+
+* Keymap Terminology::        	Definitions of terms pertaining to keymaps.
+* Format of Keymaps::		What a keymap looks like as a Lisp object.
+* Creating Keymaps:: 		Functions to create and copy keymaps.
+* Inheritance and Keymaps::	How one keymap can inherit the bindings
+				  of another keymap.
+* Key Sequences::               How to specify key sequences.
+* Prefix Keys::                 Defining a key with a keymap as its definition.
+* Active Keymaps::	        Each buffer has a local keymap
+                                  to override the standard (global) bindings.
+				Each minor mode can also override them.
+* Key Lookup::                  How extracting elements from keymaps works.
+* Functions for Key Lookup::    How to request key lookup.
+* Changing Key Bindings::       Redefining a key in a keymap.
+* Key Binding Commands::        Interactive interfaces for redefining keys.
+* Scanning Keymaps::            Looking through all keymaps, for printing help.
+* Other Keymap Functions::      Miscellaneous keymap functions.
+
+Menus
+
+* Menu Format::		Format of a menu description.
+* Menubar Format::	How to specify a menubar.
+* Menubar::		Functions for controlling the menubar.
+* Modifying Menus::	Modifying a menu description.
+* Pop-Up Menus::	Functions for specifying pop-up menus.
+* Menu Filters::	Filter functions for the default menubar.
+* Buffers Menu::	The menu that displays the list of buffers.
+
+Dialog Boxes
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+Toolbar
+
+* Toolbar Intro::		An introduction.
+* Toolbar Descriptor Format::	How to create a toolbar.
+* Specifying the Toolbar::	Setting a toolbar.
+* Other Toolbar Variables::	Controlling the size of toolbars.
+
+Gutter
+
+Scrollbars
+
+Major and Minor Modes
+
+* Major Modes::             Defining major modes.
+* Minor Modes::             Defining minor modes.
+* Modeline Format::         Customizing the text that appears in the modeline.
+* Hooks::                   How to use hooks; how to write code that
+                              provides hooks.
+
+Major Modes
+
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How XEmacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+
+Minor Modes
+
+* Minor Mode Conventions::  Tips for writing a minor mode.
+* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
+
+Modeline Format
+
+* Modeline Data::           The data structure that controls the modeline.
+* Modeline Variables::      Variables used in that data structure.
+* %-Constructs::            Putting information into a modeline.
+
+Documentation
+
+* Documentation Basics::    Good style for doc strings.
+                              Where to put them.  How XEmacs stores them.
+* Accessing Documentation:: How Lisp programs can access doc strings.
+* Keys in Documentation::   Substituting current key bindings.
+* Describing Characters::   Making printable descriptions of
+                              non-printing characters and key sequences.
+* Help Functions::          Subroutines used by XEmacs help facilities.
+
+Files
+
+* Visiting Files::          Reading files into Emacs buffers for editing.
+* Saving Buffers::          Writing changed buffers back into files.
+* Reading from Files::      Reading files into other buffers.
+* Writing to Files::        Writing new files from parts of buffers.
+* File Locks::              Locking and unlocking files, to prevent
+                                simultaneous editing by two people.
+* Information about Files::   Testing existence, accessibility, size of files.
+* Contents of Directories::   Getting a list of the files in a directory.
+* Changing File Attributes::  Renaming files, changing protection, etc.
+* File Names::                Decomposing and expanding file names.
+
+Visiting Files
+
+* Visiting Functions::      The usual interface functions for visiting.
+* Subroutines of Visiting:: Lower-level subroutines that they use.
+
+Information about Files
+
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A link?
+* File Attributes::         How large is it?  Any other names?  Etc.
+
+File Names
+
+* File Name Components::    The directory part of a file name, and the rest.
+* Directory Names::         A directory's name as a directory
+                              is different from its name as a file.
+* Relative File Names::     Some file names are relative to a
+                              current directory.
+* File Name Expansion::     Converting relative file names to absolute ones.
+* Unique File Names::       Generating names for temporary files.
+* File Name Completion::    Finding the completions for a given file name.
+
+Backups and Auto-Saving
+
+* Backup Files::            How backup files are made; how their names
+                              are chosen.
+* Auto-Saving::             How auto-save files are made; how their
+                              names are chosen.
+* Reverting::               `revert-buffer', and how to customize
+                              what it does.
+
+Backup Files
+
+* Making Backups::          How XEmacs makes backup files, and when.
+* Rename or Copy::          Two alternatives: renaming the old file
+                              or copying it.
+* Numbered Backups::        Keeping multiple backups for each source file.
+* Backup Names::            How backup file names are computed; customization.
+
+Buffers
+
+* Buffer Basics::           What is a buffer?
+* Buffer Names::            Accessing and changing buffer names.
+* Buffer File Name::        The buffer file name indicates which file
+                              is visited.
+* Buffer Modification::     A buffer is "modified" if it needs to be saved.
+* Modification Time::       Determining whether the visited file was changed
+                              ``behind XEmacs's back''.
+* Read Only Buffers::       Modifying text is not allowed in a
+                              read-only buffer.
+* The Buffer List::         How to look at all the existing buffers.
+* Creating Buffers::        Functions that create buffers.
+* Killing Buffers::         Buffers exist until explicitly killed.
+* Current Buffer::          Designating a buffer as current
+                              so primitives will access its contents.
+
+Windows
+
+* Basic Windows::           Basic information on using windows.
+* Splitting Windows::       Splitting one window into two windows.
+* Deleting Windows::        Deleting a window gives its space to other windows.
+* Selecting Windows::       The selected window is the one that you edit in.
+* Cyclic Window Ordering::  Moving around the existing windows.
+* Buffers and Windows::     Each window displays the contents of a buffer.
+* Displaying Buffers::      Higher-lever functions for displaying a buffer
+                              and choosing a window for it.
+* Window Point::            Each window has its own location of point.
+* Window Start::            The display-start position controls which text
+                              is on-screen in the window.
+* Vertical Scrolling::      Moving text up and down in the window.
+* Horizontal Scrolling::    Moving text sideways on the window.
+* Size of Window::          Accessing the size of a window.
+* Resizing Windows::        Changing the size of a window.
+* Window Configurations::   Saving and restoring the state of the screen.
+
+Frames
+
+* Creating Frames::	    Creating additional frames.
+* Frame Properties::	    Controlling frame size, position, font, etc.
+* Frame Titles::            Automatic updating of frame titles.
+* Deleting Frames::	    Frames last until explicitly deleted.
+* Finding All Frames::	    How to examine all existing frames.
+* Frames and Windows::	    A frame contains windows;
+			      display of text always works through windows.
+* Minibuffers and Frames::  How a frame finds the minibuffer to use.
+* Input Focus::		    Specifying the selected frame.
+* Visibility of Frames::    Frames may be visible or invisible, or icons.
+* Raising and Lowering::    Raising a frame makes it hide other X windows;
+			      lowering it makes the others hide them.
+* Frame Hooks::             Hooks for customizing frame behavior.
+
+Positions
+
+* Point::                   The special position where editing takes place.
+* Motion::                  Changing point.
+* Excursions::              Temporary motion and buffer changes.
+* Narrowing::               Restricting editing to a portion of the buffer.
+
+Motion
+
+* Character Motion::        Moving in terms of characters.
+* Word Motion::             Moving in terms of words.
+* Buffer End Motion::       Moving to the beginning or end of the buffer.
+* Text Lines::              Moving in terms of lines of text.
+* Screen Lines::            Moving in terms of lines as displayed.
+* List Motion::             Moving by parsing lists and sexps.
+* Skipping Characters::     Skipping characters belonging to a certain set.
+
+Markers
+
+* Overview of Markers::     The components of a marker, and how it relocates.
+* Predicates on Markers::   Testing whether an object is a marker.
+* Creating Markers::        Making empty markers or markers at certain places.
+* Information from Markers::  Finding the marker's buffer or character
+                                position.
+* Changing Markers::        Moving the marker to a new buffer or position.
+* The Mark::                How ``the mark'' is implemented with a marker.
+* The Region::              How to access ``the region''.
+
+Text
+
+* Near Point::       Examining text in the vicinity of point.
+* Buffer Contents::  Examining text in a general fashion.
+* Comparing Text::   Comparing substrings of buffers.
+* Insertion::        Adding new text to a buffer.
+* Commands for Insertion::  User-level commands to insert text.
+* Deletion::         Removing text from a buffer.
+* User-Level Deletion::     User-level commands to delete text.
+* The Kill Ring::    Where removed text sometimes is saved for later use.
+* Undo::             Undoing changes to the text of a buffer.
+* Maintaining Undo:: How to enable and disable undo information.
+			How to control how much information is kept.
+* Filling::          Functions for explicit filling.
+* Margins::          How to specify margins for filling commands.
+* Auto Filling::     How auto-fill mode is implemented to break lines.
+* Sorting::          Functions for sorting parts of the buffer.
+* Columns::          Computing horizontal positions, and using them.
+* Indentation::      Functions to insert or adjust indentation.
+* Case Changes::     Case conversion of parts of the buffer.
+* Text Properties::  Assigning Lisp property lists to text characters.
+* Substitution::     Replacing a given character wherever it appears.
+* Registers::        How registers are implemented.  Accessing the text or
+                       position stored in a register.
+* Transposition::    Swapping two portions of a buffer.
+* Change Hooks::     Supplying functions to be run when text is changed.
+
+The Kill Ring
+
+* Kill Ring Concepts::      What text looks like in the kill ring.
+* Kill Functions::          Functions that kill text.
+* Yank Commands::           Commands that access the kill ring.
+* Low-Level Kill Ring::	    Functions and variables for kill ring access.
+* Internals of Kill Ring::  Variables that hold kill-ring data.
+
+Indentation
+
+* Primitive Indent::        Functions used to count and insert indentation.
+* Mode-Specific Indent::    Customize indentation for different modes.
+* Region Indent::           Indent all the lines in a region.
+* Relative Indent::         Indent the current line based on previous lines.
+* Indent Tabs::             Adjustable, typewriter-like tab stops.
+* Motion by Indent::        Move to first non-blank character.
+
+Searching and Matching
+
+* String Search::           Search for an exact match.
+* Regular Expressions::     Describing classes of strings.
+* Regexp Search::           Searching for a match for a regexp.
+* Match Data::              Finding out which part of the text matched
+                              various parts of a regexp, after regexp search.
+* Saving Match Data::       Saving and restoring this information.
+* Standard Regexps::        Useful regexps for finding sentences, pages,...
+* Searching and Case::      Case-independent or case-significant searching.
+
+Regular Expressions
+
+* Syntax of Regexps::       Rules for writing regular expressions.
+* Regexp Example::          Illustrates regular expression syntax.
+
+Syntax Tables
+
+* Syntax Descriptors::      How characters are classified.
+* Syntax Table Functions::  How to create, examine and alter syntax tables.
+* Parsing Expressions::     Parsing balanced expressions
+                              using the syntax table.
+* Standard Syntax Tables::  Syntax tables used by various major modes.
+* Syntax Table Internals::  How syntax table information is stored.
+
+Syntax Descriptors
+
+* Syntax Class Table::      Table of syntax classes.
+* Syntax Flags::            Additional flags each character can have.
+
+Abbrevs And Abbrev Expansion
+
+* Abbrev Mode::             Setting up XEmacs for abbreviation.
+* Tables: Abbrev Tables.    Creating and working with abbrev tables.
+* Defining Abbrevs::        Specifying abbreviations and their expansions.
+* Files: Abbrev Files.      Saving abbrevs in files.
+* Expansion: Abbrev Expansion.  Controlling expansion; expansion subroutines.
+* Standard Abbrev Tables::  Abbrev tables used by various major modes.
+
+Extents
+
+* Intro to Extents::	   Extents are regions over a buffer or string.
+* Creating and Modifying Extents::
+			   Basic extent functions.
+* Extent Endpoints::	   Accessing and setting the bounds of an extent.
+* Finding Extents::	   Determining which extents are in an object.
+* Mapping Over Extents::   More sophisticated functions for extent scanning.
+* Extent Properties::	   Extents have built-in and user-definable properties.
+* Detached Extents::	   Extents that are not in a buffer.
+* Extent Parents::         Inheriting properties from another extent.
+* Duplicable Extents::	   Extents can be marked to be copied into strings.
+* Extents and Events::	   Extents can interact with the keyboard and mouse.
+* Atomic Extents::	   Treating a block of text as a single entity.
+
+Specifiers
+
+* Introduction to Specifiers::	Specifiers provide a clean way for
+				display and other properties to vary
+				(under user control) in a wide variety
+				of contexts.
+* Specifiers In-Depth::		Gory details about specifier innards.
+* Specifier Instancing::	Instancing means obtaining the ``value'' of
+				a specifier in a particular context.
+* Specifier Types::		Specifiers come in different flavors.
+* Adding Specifications::	Specifications control a specifier's ``value''
+				by giving conditions under which a
+				particular value is valid.
+* Retrieving Specifications::	Querying a specifier's specifications.
+* Specifier Instancing Functions::
+				Functions to instance a specifier.
+* Specifier Example::		Making all this stuff clearer.
+* Creating Specifiers::		Creating specifiers for your own use.
+* Specifier Validation Functions::
+				Validating the components of a specifier.
+* Other Specification Functions::
+				Other ways of working with specifications.
+
+Faces and Window-System Objects
+
+* Faces::		Controlling the way text looks.
+* Fonts::		Controlling the typeface of text.
+* Colors::		Controlling the color of text and pixmaps.
+
+Faces
+
+* Merging Faces::		How XEmacs decides which face to use
+				  for a character.
+* Basic Face Functions::	How to define and examine faces.
+* Face Properties::		How to access and modify a face's properties.
+* Face Convenience Functions::	Convenience functions for accessing
+				  particular properties of a face.
+* Other Face Display Functions:: Other functions pertaining to how a
+				  a face appears.
+
+Fonts
+
+* Font Specifiers::		Specifying how a font will appear.
+* Font Instances::		What a font specifier gets instanced as.
+* Font Instance Names::		The name of a font instance.
+* Font Instance Size::		The size of a font instance.
+* Font Instance Characteristics:: Display characteristics of font instances.
+* Font Convenience Functions::	Convenience functions that automatically
+				  instance and retrieve the properties
+				  of a font specifier.
+
+Colors
+
+* Color Specifiers::		Specifying how a color will appear.
+* Color Instances::		What a color specifier gets instanced as.
+* Color Instance Properties::	Properties of color instances.
+* Color Convenience Functions::	Convenience functions that automatically
+				  instance and retrieve the properties
+				  of a color specifier.
+
+Glyphs
+
+* Glyph Functions::	Functions for working with glyphs.
+* Images::		Graphical images displayed in a frame.
+* Glyph Types::         Each glyph has a particular type.
+* Mouse Pointer::	Controlling the mouse pointer.
+* Redisplay Glyphs::    Glyphs controlling various redisplay functions.
+* Subwindows::          Inserting an externally-controlled subwindow
+                          into a buffer.
+
+Glyph Functions
+
+* Creating Glyphs::	Creating new glyphs.
+* Glyph Properties::	Accessing and modifying a glyph's properties.
+* Glyph Convenience Functions::
+			Convenience functions for accessing particular
+			  properties of a glyph.
+* Glyph Dimensions::    Determining the height, width, etc. of a glyph.
+
+Images
+
+* Image Specifiers::		Specifying how an image will appear.
+* Image Instantiator Conversion::
+				Conversion is applied to image instantiators
+				  at the time they are added to an
+				  image specifier or at the time they
+				  are passed to `make-image-instance'.
+* Image Instances::		What an image specifier gets instanced as.
+
+Image Instances
+
+* Image Instance Types::         Each image instances has a particular type.
+* Image Instance Functions::	 Functions for working with image instances.
+
+Annotations
+
+* Annotation Basics::		Introduction to annotations.
+* Annotation Primitives::	Creating and deleting annotations.
+* Annotation Properties::	Retrieving and changing the characteristics
+				  of an annotation.
+* Margin Primitives::		Controlling the size of the margins.
+* Locating Annotations::	Looking for annotations in a buffer.
+* Annotation Hooks::		Hooks called at certain times during an
+				  annotation's lifetime.
+
+Hash Tables
+
+* Introduction to Hash Tables::	Hash tables are fast data structures for
+                                implementing simple tables (i.e. finite
+                                mappings from keys to values).
+* Working With Hash Tables::    Hash table functions.
+* Weak Hash Tables::            Hash tables with special garbage-collection
+                                behavior.
+
+Range Tables
+
+* Introduction to Range Tables:: Range tables efficiently map ranges of
+                                 integers to values.
+* Working With Range Tables::    Range table functions.
+
+
+XEmacs Display
+
+* Refresh Screen::      Clearing the screen and redrawing everything on it.
+* Truncation::          Folding or wrapping long text lines.
+* The Echo Area::       Where messages are displayed.
+* Selective Display::   Hiding part of the buffer text.
+* Overlay Arrow::       Display of an arrow to indicate position.
+* Temporary Displays::  Displays that go away automatically.
+* Blinking::            How XEmacs shows the matching open parenthesis.
+* Usual Display::	The usual conventions for displaying nonprinting chars.
+* Display Tables::	How to specify other conventions.
+* Beeping::             Audible signal to the user.
+
+Processes
+
+* Subprocess Creation::     Functions that start subprocesses.
+* Synchronous Processes::   Details of using synchronous subprocesses.
+* Asynchronous Processes::  Starting up an asynchronous subprocess.
+* Deleting Processes::      Eliminating an asynchronous subprocess.
+* Process Information::     Accessing run-status and other attributes.
+* Input to Processes::      Sending input to an asynchronous subprocess.
+* Signals to Processes::    Stopping, continuing or interrupting
+                              an asynchronous subprocess.
+* Output from Processes::   Collecting output from an asynchronous subprocess.
+* Sentinels::               Sentinels run when process run-status changes.
+* Network::                 Opening network connections.
+
+Receiving Output from Processes
+
+* Process Buffers::         If no filter, output is put in a buffer.
+* Filter Functions::        Filter functions accept output from the process.
+* Accepting Output::        How to wait until process output arrives.
+
+Operating System Interface
+
+* Starting Up::             Customizing XEmacs start-up processing.
+* Getting Out::             How exiting works (permanent or temporary).
+* System Environment::      Distinguish the name and kind of system.
+* Terminal Input::          Recording terminal input for debugging.
+* Terminal Output::         Recording terminal output for debugging.
+* Flow Control::            How to turn output flow control on or off.
+* Batch Mode::              Running XEmacs without terminal interaction.
+
+Starting Up XEmacs
+
+* Start-up Summary::        Sequence of actions XEmacs performs at start-up.
+* Init File::               Details on reading the init file (`.emacs').
+* Terminal-Specific::       How the terminal-specific Lisp file is read.
+* Command Line Arguments::  How command line arguments are processed,
+                              and how you can customize them.
+
+Getting out of XEmacs
+
+* Killing XEmacs::           Exiting XEmacs irreversibly.
+* Suspending XEmacs::        Exiting XEmacs reversibly.
+
+X-Windows
+
+* X Selections::		Transferring text to and from other X clients.
+* X Server::			Information about the X server connected to
+				  a particular device.
+* Resources::			Getting resource values from the server.
+* Server Data::			Getting info about the X server.
+* Grabs::			Restricting access to the server by other apps.
+* X Miscellaneous::             Other X-specific functions and variables.
+
+ToolTalk Support
+
+* XEmacs ToolTalk API Summary::
+* Sending Messages::
+* Receiving Messages::
+
+LDAP Support
+
+* Building XEmacs with LDAP support::  How to add LDAP support to XEmacs
+* XEmacs LDAP API::             Lisp access to LDAP functions
+* Syntax of Search Filters::    A brief summary of RFC 1558
+
+XEmacs LDAP API
+
+* LDAP Variables::              Lisp variables related to LDAP
+* The High-Level LDAP API::     High-level LDAP lisp functions
+* The Low-Level LDAP API::      Low-level LDAP lisp primitives
+* LDAP Internationalization::   I18n variables and functions
+
+The Low-Level LDAP API
+
+* The LDAP Lisp Object::
+* Opening and Closing a LDAP Connection::
+* Low-level Operations on a LDAP Server::
+
+LDAP Internationalization
+
+* LDAP Internationalization Variables::
+* Encoder/Decoder Functions::
+
+Internationalization
+
+* I18N Levels 1 and 2:: Support for different time, date, and currency formats.
+* I18N Level 3::        Support for localized messages.
+* I18N Level 4::        Support for Asian languages.
+
+MULE
+
+* Internationalization Terminology::
+                        Definition of various internationalization terms.
+* Charsets::            Sets of related characters.
+* MULE Characters::     Working with characters in XEmacs/MULE.
+* Composite Characters:: Making new characters by overstriking other ones.
+* ISO 2022::            An international standard for charsets and encodings.
+* Coding Systems::      Ways of representing a string of chars using integers.
+* CCL::                 A special language for writing fast converters.
+* Category Tables::     Subdividing charsets into groups.
+
+Tips
+
+* Style Tips::                Writing clean and robust programs.
+* Compilation Tips::          Making compiled code run fast.
+* Documentation Tips::        Writing readable documentation strings.
+* Comment Tips::	      Conventions for writing comments.
+* Library Headers::           Standard headers for library packages.
+
+Building XEmacs and Object Allocation
+
+* Building XEmacs::         How to preload Lisp libraries into XEmacs.
+* Pure Storage::            A kludge to make preloaded Lisp functions sharable.
+* Garbage Collection::      Reclaiming space for Lisp objects no longer used.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-10'
Index: ././info/lispref.info-10
--- ././info/lispref.info-10	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-10	Thu May 17 23:26:54 2001
@@ -0,0 +1,1218 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Intro to Buffer-Local,  Next: Creating Buffer-Local,  Up: Buffer-Local Variables
+
+Introduction to Buffer-Local Variables
+--------------------------------------
+
+   A buffer-local variable has a buffer-local binding associated with a
+particular buffer.  The binding is in effect when that buffer is
+current; otherwise, it is not in effect.  If you set the variable while
+a buffer-local binding is in effect, the new value goes in that binding,
+so the global binding is unchanged; this means that the change is
+visible in that buffer alone.
+
+   A variable may have buffer-local bindings in some buffers but not in
+others.  The global binding is shared by all the buffers that don't have
+their own bindings.  Thus, if you set the variable in a buffer that does
+not have a buffer-local binding for it, the new value is visible in all
+buffers except those with buffer-local bindings.  (Here we are assuming
+that there are no `let'-style local bindings to complicate the issue.)
+
+   The most common use of buffer-local bindings is for major modes to
+change variables that control the behavior of commands.  For example, C
+mode and Lisp mode both set the variable `paragraph-start' to specify
+that only blank lines separate paragraphs.  They do this by making the
+variable buffer-local in the buffer that is being put into C mode or
+Lisp mode, and then setting it to the new value for that mode.
+
+   The usual way to make a buffer-local binding is with
+`make-local-variable', which is what major mode commands use.  This
+affects just the current buffer; all other buffers (including those yet
+to be created) continue to share the global value.
+
+   A more powerful operation is to mark the variable as "automatically
+buffer-local" by calling `make-variable-buffer-local'.  You can think
+of this as making the variable local in all buffers, even those yet to
+be created.  More precisely, the effect is that setting the variable
+automatically makes the variable local to the current buffer if it is
+not already so.  All buffers start out by sharing the global value of
+the variable as usual, but any `setq' creates a buffer-local binding
+for the current buffer.  The new value is stored in the buffer-local
+binding, leaving the (default) global binding untouched.  The global
+value can no longer be changed with `setq'; you need to use
+`setq-default' to do that.
+
+   Local variables in a file you edit are also represented by
+buffer-local bindings for the buffer that holds the file within XEmacs.
+*Note Auto Major Mode::.
+
+
+File: lispref.info,  Node: Creating Buffer-Local,  Next: Default Value,  Prev: Intro to Buffer-Local,  Up: Buffer-Local Variables
+
+Creating and Deleting Buffer-Local Bindings
+-------------------------------------------
+
+ - Command: make-local-variable variable
+     This function creates a buffer-local binding in the current buffer
+     for VARIABLE (a symbol).  Other buffers are not affected.  The
+     value returned is VARIABLE.
+
+     The buffer-local value of VARIABLE starts out as the same value
+     VARIABLE previously had.  If VARIABLE was void, it remains void.
+
+          ;; In buffer `b1':
+          (setq foo 5)                ; Affects all buffers.
+               => 5
+          (make-local-variable 'foo)  ; Now it is local in `b1'.
+               => foo
+          foo                         ; That did not change
+               => 5                   ;   the value.
+          (setq foo 6)                ; Change the value
+               => 6                   ;   in `b1'.
+          foo
+               => 6
+          
+          ;; In buffer `b2', the value hasn't changed.
+          (save-excursion
+            (set-buffer "b2")
+            foo)
+               => 5
+
+     Making a variable buffer-local within a `let'-binding for that
+     variable does not work.  This is because `let' does not distinguish
+     between different kinds of bindings; it knows only which variable
+     the binding was made for.
+
+     *Please note:* do not use `make-local-variable' for a hook
+     variable.  Instead, use `make-local-hook'.  *Note Hooks::.
+
+ - Command: make-variable-buffer-local variable
+     This function marks VARIABLE (a symbol) automatically
+     buffer-local, so that any subsequent attempt to set it will make it
+     local to the current buffer at the time.
+
+     The value returned is VARIABLE.
+
+ - Function: local-variable-p variable buffer &optional after-set
+     This returns `t' if VARIABLE is buffer-local in buffer BUFFER;
+     else `nil'.
+
+     If optional third arg AFTER-SET is non-`nil', return `t' if SYMBOL
+     would be buffer-local after it is set, regardless of whether it is
+     so presently.
+
+     A `nil' value for BUFFER is _not_ the same as `(current-buffer)',
+     but means "no buffer".  Specifically:
+
+     If BUFFER is `nil' and AFTER-SET is `nil', a return value of `t'
+     indicates that the variable is one of the special built-in
+     variables that is always buffer-local. (This includes
+     `buffer-file-name', `buffer-read-only', `buffer-undo-list', and
+     others.)
+
+     If BUFFER is `nil' and AFTER-SET is `t', a return value of `t'
+     indicates that the variable has had `make-variable-buffer-local'
+     applied to it.
+
+ - Function: buffer-local-variables &optional buffer
+     This function returns a list describing the buffer-local variables
+     in buffer BUFFER.  It returns an association list (*note
+     Association Lists::) in which each association contains one
+     buffer-local variable and its value.  When a buffer-local variable
+     is void in BUFFER, then it appears directly in the resulting list.
+     If BUFFER is omitted, the current buffer is used.
+
+          (make-local-variable 'foobar)
+          (makunbound 'foobar)
+          (make-local-variable 'bind-me)
+          (setq bind-me 69)
+          (setq lcl (buffer-local-variables))
+              ;; First, built-in variables local in all buffers:
+          => ((mark-active . nil)
+              (buffer-undo-list nil)
+              (mode-name . "Fundamental")
+              ...
+              ;; Next, non-built-in local variables.
+              ;; This one is local and void:
+              foobar
+              ;; This one is local and nonvoid:
+              (bind-me . 69))
+
+     Note that storing new values into the CDRs of cons cells in this
+     list does _not_ change the local values of the variables.
+
+ - Command: kill-local-variable variable
+     This function deletes the buffer-local binding (if any) for
+     VARIABLE (a symbol) in the current buffer.  As a result, the
+     global (default) binding of VARIABLE becomes visible in this
+     buffer.  Usually this results in a change in the value of
+     VARIABLE, since the global value is usually different from the
+     buffer-local value just eliminated.
+
+     If you kill the local binding of a variable that automatically
+     becomes local when set, this makes the global value visible in the
+     current buffer.  However, if you set the variable again, that will
+     once again create a local binding for it.
+
+     `kill-local-variable' returns VARIABLE.
+
+     This function is a command because it is sometimes useful to kill
+     one buffer-local variable interactively, just as it is useful to
+     create buffer-local variables interactively.
+
+ - Function: kill-all-local-variables
+     This function eliminates all the buffer-local variable bindings of
+     the current buffer except for variables marked as "permanent".  As
+     a result, the buffer will see the default values of most variables.
+
+     This function also resets certain other information pertaining to
+     the buffer: it sets the local keymap to `nil', the syntax table to
+     the value of `standard-syntax-table', and the abbrev table to the
+     value of `fundamental-mode-abbrev-table'.
+
+     Every major mode command begins by calling this function, which
+     has the effect of switching to Fundamental mode and erasing most
+     of the effects of the previous major mode.  To ensure that this
+     does its job, the variables that major modes set should not be
+     marked permanent.
+
+     `kill-all-local-variables' returns `nil'.
+
+   A local variable is "permanent" if the variable name (a symbol) has a
+`permanent-local' property that is non-`nil'.  Permanent locals are
+appropriate for data pertaining to where the file came from or how to
+save it, rather than with how to edit the contents.
+
+
+File: lispref.info,  Node: Default Value,  Prev: Creating Buffer-Local,  Up: Buffer-Local Variables
+
+The Default Value of a Buffer-Local Variable
+--------------------------------------------
+
+   The global value of a variable with buffer-local bindings is also
+called the "default" value, because it is the value that is in effect
+except when specifically overridden.
+
+   The functions `default-value' and `setq-default' access and change a
+variable's default value regardless of whether the current buffer has a
+buffer-local binding.  For example, you could use `setq-default' to
+change the default setting of `paragraph-start' for most buffers; and
+this would work even when you are in a C or Lisp mode buffer that has a
+buffer-local value for this variable.
+
+   The special forms `defvar' and `defconst' also set the default value
+(if they set the variable at all), rather than any local value.
+
+ - Function: default-value symbol
+     This function returns SYMBOL's default value.  This is the value
+     that is seen in buffers that do not have their own values for this
+     variable.  If SYMBOL is not buffer-local, this is equivalent to
+     `symbol-value' (*note Accessing Variables::).
+
+ - Function: default-boundp symbol
+     The function `default-boundp' tells you whether SYMBOL's default
+     value is nonvoid.  If `(default-boundp 'foo)' returns `nil', then
+     `(default-value 'foo)' would get an error.
+
+     `default-boundp' is to `default-value' as `boundp' is to
+     `symbol-value'.
+
+ - Special Form: setq-default symbol value
+     This sets the default value of SYMBOL to VALUE.  It does not
+     evaluate SYMBOL, but does evaluate VALUE.  The value of the
+     `setq-default' form is VALUE.
+
+     If a SYMBOL is not buffer-local for the current buffer, and is not
+     marked automatically buffer-local, `setq-default' has the same
+     effect as `setq'.  If SYMBOL is buffer-local for the current
+     buffer, then this changes the value that other buffers will see
+     (as long as they don't have a buffer-local value), but not the
+     value that the current buffer sees.
+
+          ;; In buffer `foo':
+          (make-local-variable 'local)
+               => local
+          (setq local 'value-in-foo)
+               => value-in-foo
+          (setq-default local 'new-default)
+               => new-default
+          local
+               => value-in-foo
+          (default-value 'local)
+               => new-default
+          
+          ;; In (the new) buffer `bar':
+          local
+               => new-default
+          (default-value 'local)
+               => new-default
+          (setq local 'another-default)
+               => another-default
+          (default-value 'local)
+               => another-default
+          
+          ;; Back in buffer `foo':
+          local
+               => value-in-foo
+          (default-value 'local)
+               => another-default
+
+ - Function: set-default symbol value
+     This function is like `setq-default', except that SYMBOL is
+     evaluated.
+
+          (set-default (car '(a b c)) 23)
+               => 23
+          (default-value 'a)
+               => 23
+
+
+File: lispref.info,  Node: Variable Aliases,  Prev: Buffer-Local Variables,  Up: Variables
+
+Variable Aliases
+================
+
+   You can define a variable as an "alias" for another.  Any time you
+reference the former variable, the current value of the latter is
+returned.  Any time you change the value of the former variable, the
+value of the latter is actually changed.  This is useful in cases where
+you want to rename a variable but still make old code work (*note
+Obsoleteness::).
+
+ - Function: defvaralias variable alias
+     This function defines VARIABLE as an alias for ALIAS.
+     Thenceforth, any operations performed on VARIABLE will actually be
+     performed on ALIAS.  Both VARIABLE and ALIAS should be symbols.
+     If ALIAS is `nil', remove any aliases for VARIABLE.  ALIAS can
+     itself be aliased, and the chain of variable aliases will be
+     followed appropriately.  If VARIABLE already has a value, this
+     value will be shadowed until the alias is removed, at which point
+     it will be restored.  Currently VARIABLE cannot be a built-in
+     variable, a variable that has a buffer-local value in any buffer,
+     or the symbols `nil' or `t'.
+
+ - Function: variable-alias variable &optional follow-past-lisp-magic
+     If VARIABLE is aliased to another variable, this function returns
+     that variable.  VARIABLE should be a symbol.  If VARIABLE is not
+     aliased, this function returns `nil'.
+
+ - Function: indirect-variable object &optional follow-past-lisp-magic
+     This function returns the variable at the end of OBJECT's
+     variable-alias chain.  If OBJECT is a symbol, follow all variable
+     aliases and return the final (non-aliased) symbol.  If OBJECT is
+     not a symbol, just return it.  Signal a
+     `cyclic-variable-indirection' error if there is a loop in the
+     variable chain of symbols.
+
+
+File: lispref.info,  Node: Functions,  Next: Macros,  Prev: Variables,  Up: Top
+
+Functions
+*********
+
+   A Lisp program is composed mainly of Lisp functions.  This chapter
+explains what functions are, how they accept arguments, and how to
+define them.
+
+* Menu:
+
+* What Is a Function::    Lisp functions vs. primitives; terminology.
+* Lambda Expressions::    How functions are expressed as Lisp objects.
+* Function Names::        A symbol can serve as the name of a function.
+* Defining Functions::    Lisp expressions for defining functions.
+* Calling Functions::     How to use an existing function.
+* Mapping Functions::     Applying a function to each element of a list, etc.
+* Anonymous Functions::   Lambda expressions are functions with no names.
+* Function Cells::        Accessing or setting the function definition
+                            of a symbol.
+* Inline Functions::	  Defining functions that the compiler will open code.
+* Related Topics::        Cross-references to specific Lisp primitives
+                            that have a special bearing on how functions work.
+
+
+File: lispref.info,  Node: What Is a Function,  Next: Lambda Expressions,  Up: Functions
+
+What Is a Function?
+===================
+
+   In a general sense, a function is a rule for carrying on a
+computation given several values called "arguments".  The result of the
+computation is called the value of the function.  The computation can
+also have side effects: lasting changes in the values of variables or
+the contents of data structures.
+
+   Here are important terms for functions in XEmacs Lisp and for other
+function-like objects.
+
+"function"
+     In XEmacs Lisp, a "function" is anything that can be applied to
+     arguments in a Lisp program.  In some cases, we use it more
+     specifically to mean a function written in Lisp.  Special forms and
+     macros are not functions.
+
+"primitive"
+     A "primitive" is a function callable from Lisp that is written in
+     C, such as `car' or `append'.  These functions are also called
+     "built-in" functions or "subrs".  (Special forms are also
+     considered primitives.)
+
+     Usually the reason that a function is a primitives is because it is
+     fundamental, because it provides a low-level interface to operating
+     system services, or because it needs to run fast.  Primitives can
+     be modified or added only by changing the C sources and
+     recompiling the editor.  See *Note Writing Lisp Primitives:
+     (internals)Writing Lisp Primitives.
+
+"lambda expression"
+     A "lambda expression" is a function written in Lisp.  These are
+     described in the following section.  *Note Lambda Expressions::.
+
+"special form"
+     A "special form" is a primitive that is like a function but does
+     not evaluate all of its arguments in the usual way.  It may
+     evaluate only some of the arguments, or may evaluate them in an
+     unusual order, or several times.  Many special forms are described
+     in *Note Control Structures::.
+
+"macro"
+     A "macro" is a construct defined in Lisp by the programmer.  It
+     differs from a function in that it translates a Lisp expression
+     that you write into an equivalent expression to be evaluated
+     instead of the original expression.  Macros enable Lisp
+     programmers to do the sorts of things that special forms can do.
+     *Note Macros::, for how to define and use macros.
+
+"command"
+     A "command" is an object that `command-execute' can invoke; it is
+     a possible definition for a key sequence.  Some functions are
+     commands; a function written in Lisp is a command if it contains an
+     interactive declaration (*note Defining Commands::).  Such a
+     function can be called from Lisp expressions like other functions;
+     in this case, the fact that the function is a command makes no
+     difference.
+
+     Keyboard macros (strings and vectors) are commands also, even
+     though they are not functions.  A symbol is a command if its
+     function definition is a command; such symbols can be invoked with
+     `M-x'.  The symbol is a function as well if the definition is a
+     function.  *Note Command Overview::.
+
+"keystroke command"
+     A "keystroke command" is a command that is bound to a key sequence
+     (typically one to three keystrokes).  The distinction is made here
+     merely to avoid confusion with the meaning of "command" in
+     non-Emacs editors; for Lisp programs, the distinction is normally
+     unimportant.
+
+"compiled function"
+     A "compiled function" is a function that has been compiled by the
+     byte compiler.  *Note Compiled-Function Type::.
+
+ - Function: subrp object
+     This function returns `t' if OBJECT is a built-in function (i.e.,
+     a Lisp primitive).
+
+          (subrp 'message)            ; `message' is a symbol,
+               => nil                 ;   not a subr object.
+          (subrp (symbol-function 'message))
+               => t
+
+ - Function: compiled-function-p object
+     This function returns `t' if OBJECT is a compiled function.  For
+     example:
+
+          (compiled-function-p (symbol-function 'next-line))
+               => t
+
+
+File: lispref.info,  Node: Lambda Expressions,  Next: Function Names,  Prev: What Is a Function,  Up: Functions
+
+Lambda Expressions
+==================
+
+   A function written in Lisp is a list that looks like this:
+
+     (lambda (ARG-VARIABLES...)
+       [DOCUMENTATION-STRING]
+       [INTERACTIVE-DECLARATION]
+       BODY-FORMS...)
+
+Such a list is called a "lambda expression".  In XEmacs Lisp, it
+actually is valid as an expression--it evaluates to itself.  In some
+other Lisp dialects, a lambda expression is not a valid expression at
+all.  In either case, its main use is not to be evaluated as an
+expression, but to be called as a function.
+
+* Menu:
+
+* Lambda Components::       The parts of a lambda expression.
+* Simple Lambda::           A simple example.
+* Argument List::           Details and special features of argument lists.
+* Function Documentation::  How to put documentation in a function.
+
+
+File: lispref.info,  Node: Lambda Components,  Next: Simple Lambda,  Up: Lambda Expressions
+
+Components of a Lambda Expression
+---------------------------------
+
+   A function written in Lisp (a "lambda expression") is a list that
+looks like this:
+
+     (lambda (ARG-VARIABLES...)
+       [DOCUMENTATION-STRING]
+       [INTERACTIVE-DECLARATION]
+       BODY-FORMS...)
+
+   The first element of a lambda expression is always the symbol
+`lambda'.  This indicates that the list represents a function.  The
+reason functions are defined to start with `lambda' is so that other
+lists, intended for other uses, will not accidentally be valid as
+functions.
+
+   The second element is a list of symbols-the argument variable names.
+This is called the "lambda list".  When a Lisp function is called, the
+argument values are matched up against the variables in the lambda
+list, which are given local bindings with the values provided.  *Note
+Local Variables::.
+
+   The documentation string is a Lisp string object placed within the
+function definition to describe the function for the XEmacs help
+facilities.  *Note Function Documentation::.
+
+   The interactive declaration is a list of the form `(interactive
+CODE-STRING)'.  This declares how to provide arguments if the function
+is used interactively.  Functions with this declaration are called
+"commands"; they can be called using `M-x' or bound to a key.
+Functions not intended to be called in this way should not have
+interactive declarations.  *Note Defining Commands::, for how to write
+an interactive declaration.
+
+   The rest of the elements are the "body" of the function: the Lisp
+code to do the work of the function (or, as a Lisp programmer would say,
+"a list of Lisp forms to evaluate").  The value returned by the
+function is the value returned by the last element of the body.
+
+
+File: lispref.info,  Node: Simple Lambda,  Next: Argument List,  Prev: Lambda Components,  Up: Lambda Expressions
+
+A Simple Lambda-Expression Example
+----------------------------------
+
+   Consider for example the following function:
+
+     (lambda (a b c) (+ a b c))
+
+We can call this function by writing it as the CAR of an expression,
+like this:
+
+     ((lambda (a b c) (+ a b c))
+      1 2 3)
+
+This call evaluates the body of the lambda expression  with the variable
+`a' bound to 1, `b' bound to 2, and `c' bound to 3.  Evaluation of the
+body adds these three numbers, producing the result 6; therefore, this
+call to the function returns the value 6.
+
+   Note that the arguments can be the results of other function calls,
+as in this example:
+
+     ((lambda (a b c) (+ a b c))
+      1 (* 2 3) (- 5 4))
+
+This evaluates the arguments `1', `(* 2 3)', and `(- 5 4)' from left to
+right.  Then it applies the lambda expression to the argument values 1,
+6 and 1 to produce the value 8.
+
+   It is not often useful to write a lambda expression as the CAR of a
+form in this way.  You can get the same result, of making local
+variables and giving them values, using the special form `let' (*note
+Local Variables::).  And `let' is clearer and easier to use.  In
+practice, lambda expressions are either stored as the function
+definitions of symbols, to produce named functions, or passed as
+arguments to other functions (*note Anonymous Functions::).
+
+   However, calls to explicit lambda expressions were very useful in the
+old days of Lisp, before the special form `let' was invented.  At that
+time, they were the only way to bind and initialize local variables.
+
+
+File: lispref.info,  Node: Argument List,  Next: Function Documentation,  Prev: Simple Lambda,  Up: Lambda Expressions
+
+Advanced Features of Argument Lists
+-----------------------------------
+
+   Our simple sample function, `(lambda (a b c) (+ a b c))', specifies
+three argument variables, so it must be called with three arguments: if
+you try to call it with only two arguments or four arguments, you get a
+`wrong-number-of-arguments' error.
+
+   It is often convenient to write a function that allows certain
+arguments to be omitted.  For example, the function `substring' accepts
+three arguments--a string, the start index and the end index--but the
+third argument defaults to the LENGTH of the string if you omit it.  It
+is also convenient for certain functions to accept an indefinite number
+of arguments, as the functions `list' and `+' do.
+
+   To specify optional arguments that may be omitted when a function is
+called, simply include the keyword `&optional' before the optional
+arguments.  To specify a list of zero or more extra arguments, include
+the keyword `&rest' before one final argument.
+
+   Thus, the complete syntax for an argument list is as follows:
+
+     (REQUIRED-VARS...
+      [&optional OPTIONAL-VARS...]
+      [&rest REST-VAR])
+
+The square brackets indicate that the `&optional' and `&rest' clauses,
+and the variables that follow them, are optional.
+
+   A call to the function requires one actual argument for each of the
+REQUIRED-VARS.  There may be actual arguments for zero or more of the
+OPTIONAL-VARS, and there cannot be any actual arguments beyond that
+unless the lambda list uses `&rest'.  In that case, there may be any
+number of extra actual arguments.
+
+   If actual arguments for the optional and rest variables are omitted,
+then they always default to `nil'.  There is no way for the function to
+distinguish between an explicit argument of `nil' and an omitted
+argument.  However, the body of the function is free to consider `nil'
+an abbreviation for some other meaningful value.  This is what
+`substring' does; `nil' as the third argument to `substring' means to
+use the length of the string supplied.
+
+     Common Lisp note: Common Lisp allows the function to specify what
+     default value to use when an optional argument is omitted; XEmacs
+     Lisp always uses `nil'.
+
+   For example, an argument list that looks like this:
+
+     (a b &optional c d &rest e)
+
+binds `a' and `b' to the first two actual arguments, which are
+required.  If one or two more arguments are provided, `c' and `d' are
+bound to them respectively; any arguments after the first four are
+collected into a list and `e' is bound to that list.  If there are only
+two arguments, `c' is `nil'; if two or three arguments, `d' is `nil';
+if four arguments or fewer, `e' is `nil'.
+
+   There is no way to have required arguments following optional
+ones--it would not make sense.  To see why this must be so, suppose
+that `c' in the example were optional and `d' were required.  Suppose
+three actual arguments are given; which variable would the third
+argument be for?  Similarly, it makes no sense to have any more
+arguments (either required or optional) after a `&rest' argument.
+
+   Here are some examples of argument lists and proper calls:
+
+     ((lambda (n) (1+ n))                ; One required:
+      1)                                 ; requires exactly one argument.
+          => 2
+     ((lambda (n &optional n1)           ; One required and one optional:
+              (if n1 (+ n n1) (1+ n)))   ; 1 or 2 arguments.
+      1 2)
+          => 3
+     ((lambda (n &rest ns)               ; One required and one rest:
+              (+ n (apply '+ ns)))       ; 1 or more arguments.
+      1 2 3 4 5)
+          => 15
+
+
+File: lispref.info,  Node: Function Documentation,  Prev: Argument List,  Up: Lambda Expressions
+
+Documentation Strings of Functions
+----------------------------------
+
+   A lambda expression may optionally have a "documentation string" just
+after the lambda list.  This string does not affect execution of the
+function; it is a kind of comment, but a systematized comment which
+actually appears inside the Lisp world and can be used by the XEmacs
+help facilities.  *Note Documentation::, for how the
+DOCUMENTATION-STRING is accessed.
+
+   It is a good idea to provide documentation strings for all the
+functions in your program, even those that are only called from within
+your program.  Documentation strings are like comments, except that they
+are easier to access.
+
+   The first line of the documentation string should stand on its own,
+because `apropos' displays just this first line.  It should consist of
+one or two complete sentences that summarize the function's purpose.
+
+   The start of the documentation string is usually indented in the
+source file, but since these spaces come before the starting
+double-quote, they are not part of the string.  Some people make a
+practice of indenting any additional lines of the string so that the
+text lines up in the program source.  _This is a mistake._  The
+indentation of the following lines is inside the string; what looks
+nice in the source code will look ugly when displayed by the help
+commands.
+
+   You may wonder how the documentation string could be optional, since
+there are required components of the function that follow it (the body).
+Since evaluation of a string returns that string, without any side
+effects, it has no effect if it is not the last form in the body.
+Thus, in practice, there is no confusion between the first form of the
+body and the documentation string; if the only body form is a string
+then it serves both as the return value and as the documentation.
+
+
+File: lispref.info,  Node: Function Names,  Next: Defining Functions,  Prev: Lambda Expressions,  Up: Functions
+
+Naming a Function
+=================
+
+   In most computer languages, every function has a name; the idea of a
+function without a name is nonsensical.  In Lisp, a function in the
+strictest sense has no name.  It is simply a list whose first element is
+`lambda', or a primitive subr-object.
+
+   However, a symbol can serve as the name of a function.  This happens
+when you put the function in the symbol's "function cell" (*note Symbol
+Components::).  Then the symbol itself becomes a valid, callable
+function, equivalent to the list or subr-object that its function cell
+refers to.  The contents of the function cell are also called the
+symbol's "function definition".  The procedure of using a symbol's
+function definition in place of the symbol is called "symbol function
+indirection"; see *Note Function Indirection::.
+
+   In practice, nearly all functions are given names in this way and
+referred to through their names.  For example, the symbol `car' works
+as a function and does what it does because the primitive subr-object
+`#<subr car>' is stored in its function cell.
+
+   We give functions names because it is convenient to refer to them by
+their names in Lisp expressions.  For primitive subr-objects such as
+`#<subr car>', names are the only way you can refer to them: there is
+no read syntax for such objects.  For functions written in Lisp, the
+name is more convenient to use in a call than an explicit lambda
+expression.  Also, a function with a name can refer to itself--it can
+be recursive.  Writing the function's name in its own definition is much
+more convenient than making the function definition point to itself
+(something that is not impossible but that has various disadvantages in
+practice).
+
+   We often identify functions with the symbols used to name them.  For
+example, we often speak of "the function `car'", not distinguishing
+between the symbol `car' and the primitive subr-object that is its
+function definition.  For most purposes, there is no need to
+distinguish.
+
+   Even so, keep in mind that a function need not have a unique name.
+While a given function object _usually_ appears in the function cell of
+only one symbol, this is just a matter of convenience.  It is easy to
+store it in several symbols using `fset'; then each of the symbols is
+equally well a name for the same function.
+
+   A symbol used as a function name may also be used as a variable;
+these two uses of a symbol are independent and do not conflict.
+
+
+File: lispref.info,  Node: Defining Functions,  Next: Calling Functions,  Prev: Function Names,  Up: Functions
+
+Defining Functions
+==================
+
+   We usually give a name to a function when it is first created.  This
+is called "defining a function", and it is done with the `defun'
+special form.
+
+ - Special Form: defun name argument-list body-forms
+     `defun' is the usual way to define new Lisp functions.  It defines
+     the symbol NAME as a function that looks like this:
+
+          (lambda ARGUMENT-LIST . BODY-FORMS)
+
+     `defun' stores this lambda expression in the function cell of
+     NAME.  It returns the value NAME, but usually we ignore this value.
+
+     As described previously (*note Lambda Expressions::),
+     ARGUMENT-LIST is a list of argument names and may include the
+     keywords `&optional' and `&rest'.  Also, the first two forms in
+     BODY-FORMS may be a documentation string and an interactive
+     declaration.
+
+     There is no conflict if the same symbol NAME is also used as a
+     variable, since the symbol's value cell is independent of the
+     function cell.  *Note Symbol Components::.
+
+     Here are some examples:
+
+          (defun foo () 5)
+               => foo
+          (foo)
+               => 5
+          
+          (defun bar (a &optional b &rest c)
+              (list a b c))
+               => bar
+          (bar 1 2 3 4 5)
+               => (1 2 (3 4 5))
+          (bar 1)
+               => (1 nil nil)
+          (bar)
+          error--> Wrong number of arguments.
+          
+          (defun capitalize-backwards ()
+            "Upcase the last letter of a word."
+            (interactive)
+            (backward-word 1)
+            (forward-word 1)
+            (backward-char 1)
+            (capitalize-word 1))
+               => capitalize-backwards
+
+     Be careful not to redefine existing functions unintentionally.
+     `defun' redefines even primitive functions such as `car' without
+     any hesitation or notification.  Redefining a function already
+     defined is often done deliberately, and there is no way to
+     distinguish deliberate redefinition from unintentional
+     redefinition.
+
+ - Function: define-function name definition
+ - Function: defalias name definition
+     These equivalent special forms define the symbol NAME as a
+     function, with definition DEFINITION (which can be any valid Lisp
+     function).
+
+     The proper place to use `define-function' or `defalias' is where a
+     specific function name is being defined--especially where that
+     name appears explicitly in the source file being loaded.  This is
+     because `define-function' and `defalias' record which file defined
+     the function, just like `defun'.  (*note Unloading::).
+
+     By contrast, in programs that manipulate function definitions for
+     other purposes, it is better to use `fset', which does not keep
+     such records.
+
+   See also `defsubst', which defines a function like `defun' and tells
+the Lisp compiler to open-code it.  *Note Inline Functions::.
+
+
+File: lispref.info,  Node: Calling Functions,  Next: Mapping Functions,  Prev: Defining Functions,  Up: Functions
+
+Calling Functions
+=================
+
+   Defining functions is only half the battle.  Functions don't do
+anything until you "call" them, i.e., tell them to run.  Calling a
+function is also known as "invocation".
+
+   The most common way of invoking a function is by evaluating a list.
+For example, evaluating the list `(concat "a" "b")' calls the function
+`concat' with arguments `"a"' and `"b"'.  *Note Evaluation::, for a
+description of evaluation.
+
+   When you write a list as an expression in your program, the function
+name is part of the program.  This means that you choose which function
+to call, and how many arguments to give it, when you write the program.
+Usually that's just what you want.  Occasionally you need to decide at
+run time which function to call.  To do that, use the functions
+`funcall' and `apply'.
+
+ - Function: funcall function &rest arguments
+     `funcall' calls FUNCTION with ARGUMENTS, and returns whatever
+     FUNCTION returns.
+
+     Since `funcall' is a function, all of its arguments, including
+     FUNCTION, are evaluated before `funcall' is called.  This means
+     that you can use any expression to obtain the function to be
+     called.  It also means that `funcall' does not see the expressions
+     you write for the ARGUMENTS, only their values.  These values are
+     _not_ evaluated a second time in the act of calling FUNCTION;
+     `funcall' enters the normal procedure for calling a function at the
+     place where the arguments have already been evaluated.
+
+     The argument FUNCTION must be either a Lisp function or a
+     primitive function.  Special forms and macros are not allowed,
+     because they make sense only when given the "unevaluated" argument
+     expressions.  `funcall' cannot provide these because, as we saw
+     above, it never knows them in the first place.
+
+          (setq f 'list)
+               => list
+          (funcall f 'x 'y 'z)
+               => (x y z)
+          (funcall f 'x 'y '(z))
+               => (x y (z))
+          (funcall 'and t nil)
+          error--> Invalid function: #<subr and>
+
+     Compare these example with the examples of `apply'.
+
+ - Function: apply function &rest arguments
+     `apply' calls FUNCTION with ARGUMENTS, just like `funcall' but
+     with one difference: the last of ARGUMENTS is a list of arguments
+     to give to FUNCTION, rather than a single argument.  We also say
+     that `apply' "spreads" this list so that each individual element
+     becomes an argument.
+
+     `apply' returns the result of calling FUNCTION.  As with
+     `funcall', FUNCTION must either be a Lisp function or a primitive
+     function; special forms and macros do not make sense in `apply'.
+
+          (setq f 'list)
+               => list
+          (apply f 'x 'y 'z)
+          error--> Wrong type argument: listp, z
+          (apply '+ 1 2 '(3 4))
+               => 10
+          (apply '+ '(1 2 3 4))
+               => 10
+          
+          (apply 'append '((a b c) nil (x y z) nil))
+               => (a b c x y z)
+
+     For an interesting example of using `apply', see the description of
+     `mapcar', in *Note Mapping Functions::.
+
+   It is common for Lisp functions to accept functions as arguments or
+find them in data structures (especially in hook variables and property
+lists) and call them using `funcall' or `apply'.  Functions that accept
+function arguments are often called "functionals".
+
+   Sometimes, when you call a functional, it is useful to supply a no-op
+function as the argument.  Here are two different kinds of no-op
+function:
+
+ - Function: identity arg
+     This function returns ARG and has no side effects.
+
+ - Command: ignore &rest args
+     This function ignores any arguments and returns `nil'.
+
+
+File: lispref.info,  Node: Mapping Functions,  Next: Anonymous Functions,  Prev: Calling Functions,  Up: Functions
+
+Mapping Functions
+=================
+
+   A "mapping function" applies a given function to each element of a
+list or other collection.  XEmacs Lisp has several such functions;
+`mapcar' and `mapconcat', which scan a list, are described here.
+*Note Creating Symbols::, for the function `mapatoms' which maps over
+the symbols in an obarray.
+
+   Mapping functions should never modify the sequence being mapped over.
+The results are unpredictable.
+
+ - Function: mapcar function sequence
+     `mapcar' applies FUNCTION to each element of SEQUENCE in turn, and
+     returns a list of the results.
+
+     The argument SEQUENCE can be any kind of sequence; that is, a
+     list, a vector, a bit vector, or a string.  The result is always a
+     list.  The length of the result is the same as the length of
+     SEQUENCE.
+
+     For example:
+
+          (mapcar 'car '((a b) (c d) (e f)))
+               => (a c e)
+          (mapcar '1+ [1 2 3])
+               => (2 3 4)
+          (mapcar 'char-to-string "abc")
+               => ("a" "b" "c")
+          
+          ;; Call each function in `my-hooks'.
+          (mapcar 'funcall my-hooks)
+          
+          (defun mapcar* (f &rest args)
+            "Apply FUNCTION to successive cars of all ARGS.
+          Return the list of results."
+            ;; If no list is exhausted,
+            (if (not (memq 'nil args))
+                ;; apply function to CARs.
+                (cons (apply f (mapcar 'car args))
+                      (apply 'mapcar* f
+                             ;; Recurse for rest of elements.
+                             (mapcar 'cdr args)))))
+          
+          (mapcar* 'cons '(a b c) '(1 2 3 4))
+               => ((a . 1) (b . 2) (c . 3))
+
+ - Function: mapconcat function sequence separator
+     `mapconcat' applies FUNCTION to each element of SEQUENCE: the
+     results, which must be strings, are concatenated.  Between each
+     pair of result strings, `mapconcat' inserts the string SEPARATOR.
+     Usually SEPARATOR contains a space or comma or other suitable
+     punctuation.
+
+     The argument FUNCTION must be a function that can take one
+     argument and return a string.  The argument SEQUENCE can be any
+     kind of sequence; that is, a list, a vector, a bit vector, or a
+     string.
+
+          (mapconcat 'symbol-name
+                     '(The cat in the hat)
+                     " ")
+               => "The cat in the hat"
+          
+          (mapconcat (function (lambda (x) (format "%c" (1+ x))))
+                     "HAL-8000"
+                     "")
+               => "IBM.9111"
+
+
+File: lispref.info,  Node: Anonymous Functions,  Next: Function Cells,  Prev: Mapping Functions,  Up: Functions
+
+Anonymous Functions
+===================
+
+   In Lisp, a function is a list that starts with `lambda', a byte-code
+function compiled from such a list, or alternatively a primitive
+subr-object; names are "extra".  Although usually functions are defined
+with `defun' and given names at the same time, it is occasionally more
+concise to use an explicit lambda expression--an anonymous function.
+Such a list is valid wherever a function name is.
+
+   Any method of creating such a list makes a valid function.  Even
+this:
+
+     (setq silly (append '(lambda (x)) (list (list '+ (* 3 4) 'x))))
+     => (lambda (x) (+ 12 x))
+
+This computes a list that looks like `(lambda (x) (+ 12 x))' and makes
+it the value (_not_ the function definition!) of `silly'.
+
+   Here is how we might call this function:
+
+     (funcall silly 1)
+     => 13
+
+(It does _not_ work to write `(silly 1)', because this function is not
+the _function definition_ of `silly'.  We have not given `silly' any
+function definition, just a value as a variable.)
+
+   Most of the time, anonymous functions are constants that appear in
+your program.  For example, you might want to pass one as an argument
+to the function `mapcar', which applies any given function to each
+element of a list.  Here we pass an anonymous function that multiplies
+a number by two:
+
+     (defun double-each (list)
+       (mapcar '(lambda (x) (* 2 x)) list))
+     => double-each
+     (double-each '(2 11))
+     => (4 22)
+
+In such cases, we usually use the special form `function' instead of
+simple quotation to quote the anonymous function.
+
+ - Special Form: function function-object
+     This special form returns FUNCTION-OBJECT without evaluating it.
+     In this, it is equivalent to `quote'.  However, it serves as a
+     note to the XEmacs Lisp compiler that FUNCTION-OBJECT is intended
+     to be used only as a function, and therefore can safely be
+     compiled.  Contrast this with `quote', in *Note Quoting::.
+
+   Using `function' instead of `quote' makes a difference inside a
+function or macro that you are going to compile.  For example:
+
+     (defun double-each (list)
+       (mapcar (function (lambda (x) (* 2 x))) list))
+     => double-each
+     (double-each '(2 11))
+     => (4 22)
+
+If this definition of `double-each' is compiled, the anonymous function
+is compiled as well.  By contrast, in the previous definition where
+ordinary `quote' is used, the argument passed to `mapcar' is the
+precise list shown:
+
+     (lambda (x) (* x 2))
+
+The Lisp compiler cannot assume this list is a function, even though it
+looks like one, since it does not know what `mapcar' does with the
+list.  Perhaps `mapcar' will check that the CAR of the third element is
+the symbol `*'!  The advantage of `function' is that it tells the
+compiler to go ahead and compile the constant function.
+
+   We sometimes write `function' instead of `quote' when quoting the
+name of a function, but this usage is just a sort of comment.
+
+     (function SYMBOL) == (quote SYMBOL) == 'SYMBOL
+
+   See `documentation' in *Note Accessing Documentation::, for a
+realistic example using `function' and an anonymous function.
+
+
+File: lispref.info,  Node: Function Cells,  Next: Inline Functions,  Prev: Anonymous Functions,  Up: Functions
+
+Accessing Function Cell Contents
+================================
+
+   The "function definition" of a symbol is the object stored in the
+function cell of the symbol.  The functions described here access, test,
+and set the function cell of symbols.
+
+   See also the function `indirect-function' in *Note Function
+Indirection::.
+
+ - Function: symbol-function symbol
+     This returns the object in the function cell of SYMBOL.  If the
+     symbol's function cell is void, a `void-function' error is
+     signaled.
+
+     This function does not check that the returned object is a
+     legitimate function.
+
+          (defun bar (n) (+ n 2))
+               => bar
+          (symbol-function 'bar)
+               => (lambda (n) (+ n 2))
+          (fset 'baz 'bar)
+               => bar
+          (symbol-function 'baz)
+               => bar
+
+   If you have never given a symbol any function definition, we say that
+that symbol's function cell is "void".  In other words, the function
+cell does not have any Lisp object in it.  If you try to call such a
+symbol as a function, it signals a `void-function' error.
+
+   Note that void is not the same as `nil' or the symbol `void'.  The
+symbols `nil' and `void' are Lisp objects, and can be stored into a
+function cell just as any other object can be (and they can be valid
+functions if you define them in turn with `defun').  A void function
+cell contains no object whatsoever.
+
+   You can test the voidness of a symbol's function definition with
+`fboundp'.  After you have given a symbol a function definition, you
+can make it void once more using `fmakunbound'.
+
+ - Function: fboundp symbol
+     This function returns `t' if SYMBOL has an object in its function
+     cell, `nil' otherwise.  It does not check that the object is a
+     legitimate function.
+
+ - Function: fmakunbound symbol
+     This function makes SYMBOL's function cell void, so that a
+     subsequent attempt to access this cell will cause a `void-function'
+     error.  (See also `makunbound', in *Note Local Variables::.)
+
+          (defun foo (x) x)
+               => x
+          (foo 1)
+               =>1
+          (fmakunbound 'foo)
+               => x
+          (foo 1)
+          error--> Symbol's function definition is void: foo
+
+ - Function: fset symbol object
+     This function stores OBJECT in the function cell of SYMBOL.  The
+     result is OBJECT.  Normally OBJECT should be a function or the
+     name of a function, but this is not checked.
+
+     There are three normal uses of this function:
+
+        * Copying one symbol's function definition to another.  (In
+          other words, making an alternate name for a function.)
+
+        * Giving a symbol a function definition that is not a list and
+          therefore cannot be made with `defun'.  For example, you can
+          use `fset' to give a symbol SYMBOL1 a function definition
+          which is another symbol SYMBOL2; then SYMBOL1 serves as an
+          alias for whatever definition SYMBOL2 presently has.
+
+        * In constructs for defining or altering functions.  If `defun'
+          were not a primitive, it could be written in Lisp (as a
+          macro) using `fset'.
+
+     Here are examples of the first two uses:
+
+          ;; Give `first' the same definition `car' has.
+          (fset 'first (symbol-function 'car))
+               => #<subr car>
+          (first '(1 2 3))
+               => 1
+          
+          ;; Make the symbol `car' the function definition of `xfirst'.
+          (fset 'xfirst 'car)
+               => car
+          (xfirst '(1 2 3))
+               => 1
+          (symbol-function 'xfirst)
+               => car
+          (symbol-function (symbol-function 'xfirst))
+               => #<subr car>
+          
+          ;; Define a named keyboard macro.
+          (fset 'kill-two-lines "\^u2\^k")
+               => "\^u2\^k"
+
+     See also the related functions `define-function' and `defalias',
+     in *Note Defining Functions::.
+
+   When writing a function that extends a previously defined function,
+the following idiom is sometimes used:
+
+     (fset 'old-foo (symbol-function 'foo))
+     (defun foo ()
+       "Just like old-foo, except more so."
+       (old-foo)
+       (more-so))
+
+This does not work properly if `foo' has been defined to autoload.  In
+such a case, when `foo' calls `old-foo', Lisp attempts to define
+`old-foo' by loading a file.  Since this presumably defines `foo'
+rather than `old-foo', it does not produce the proper results.  The
+only way to avoid this problem is to make sure the file is loaded
+before moving aside the old definition of `foo'.
+
+   But it is unmodular and unclean, in any case, for a Lisp file to
+redefine a function defined elsewhere.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-11'
Index: ././info/lispref.info-11
--- ././info/lispref.info-11	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-11	Thu May 17 23:26:54 2001
@@ -0,0 +1,1291 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Inline Functions,  Next: Related Topics,  Prev: Function Cells,  Up: Functions
+
+Inline Functions
+================
+
+   You can define an "inline function" by using `defsubst' instead of
+`defun'.  An inline function works just like an ordinary function
+except for one thing: when you compile a call to the function, the
+function's definition is open-coded into the caller.
+
+   Making a function inline makes explicit calls run faster.  But it
+also has disadvantages.  For one thing, it reduces flexibility; if you
+change the definition of the function, calls already inlined still use
+the old definition until you recompile them.  Since the flexibility of
+redefining functions is an important feature of XEmacs, you should not
+make a function inline unless its speed is really crucial.
+
+   Another disadvantage is that making a large function inline can
+increase the size of compiled code both in files and in memory.  Since
+the speed advantage of inline functions is greatest for small
+functions, you generally should not make large functions inline.
+
+   It's possible to define a macro to expand into the same code that an
+inline function would execute.  But the macro would have a limitation:
+you can use it only explicitly--a macro cannot be called with `apply',
+`mapcar' and so on.  Also, it takes some work to convert an ordinary
+function into a macro.  (*Note Macros::.)  To convert it into an inline
+function is very easy; simply replace `defun' with `defsubst'.  Since
+each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do for macros.  (*Note Argument Evaluation::.)
+
+   Inline functions can be used and open-coded later on in the same
+file, following the definition, just like macros.
+
+
+File: lispref.info,  Node: Related Topics,  Prev: Inline Functions,  Up: Functions
+
+Other Topics Related to Functions
+=================================
+
+   Here is a table of several functions that do things related to
+function calling and function definitions.  They are documented
+elsewhere, but we provide cross references here.
+
+`apply'
+     See *Note Calling Functions::.
+
+`autoload'
+     See *Note Autoload::.
+
+`call-interactively'
+     See *Note Interactive Call::.
+
+`commandp'
+     See *Note Interactive Call::.
+
+`documentation'
+     See *Note Accessing Documentation::.
+
+`eval'
+     See *Note Eval::.
+
+`funcall'
+     See *Note Calling Functions::.
+
+`ignore'
+     See *Note Calling Functions::.
+
+`indirect-function'
+     See *Note Function Indirection::.
+
+`interactive'
+     See *Note Using Interactive::.
+
+`interactive-p'
+     See *Note Interactive Call::.
+
+`mapatoms'
+     See *Note Creating Symbols::.
+
+`mapcar'
+     See *Note Mapping Functions::.
+
+`mapconcat'
+     See *Note Mapping Functions::.
+
+`undefined'
+     See *Note Key Lookup::.
+
+
+File: lispref.info,  Node: Macros,  Next: Loading,  Prev: Functions,  Up: Top
+
+Macros
+******
+
+   "Macros" enable you to define new control constructs and other
+language features.  A macro is defined much like a function, but instead
+of telling how to compute a value, it tells how to compute another Lisp
+expression which will in turn compute the value.  We call this
+expression the "expansion" of the macro.
+
+   Macros can do this because they operate on the unevaluated
+expressions for the arguments, not on the argument values as functions
+do.  They can therefore construct an expansion containing these
+argument expressions or parts of them.
+
+   If you are using a macro to do something an ordinary function could
+do, just for the sake of speed, consider using an inline function
+instead.  *Note Inline Functions::.
+
+* Menu:
+
+* Simple Macro::            A basic example.
+* Expansion::               How, when and why macros are expanded.
+* Compiling Macros::        How macros are expanded by the compiler.
+* Defining Macros::         How to write a macro definition.
+* Backquote::               Easier construction of list structure.
+* Problems with Macros::    Don't evaluate the macro arguments too many times.
+                              Don't hide the user's variables.
+
+
+File: lispref.info,  Node: Simple Macro,  Next: Expansion,  Up: Macros
+
+A Simple Example of a Macro
+===========================
+
+   Suppose we would like to define a Lisp construct to increment a
+variable value, much like the `++' operator in C.  We would like to
+write `(inc x)' and have the effect of `(setq x (1+ x))'.  Here's a
+macro definition that does the job:
+
+     (defmacro inc (var)
+        (list 'setq var (list '1+ var)))
+
+   When this is called with `(inc x)', the argument `var' has the value
+`x'--_not_ the _value_ of `x'.  The body of the macro uses this to
+construct the expansion, which is `(setq x (1+ x))'.  Once the macro
+definition returns this expansion, Lisp proceeds to evaluate it, thus
+incrementing `x'.
+
+
+File: lispref.info,  Node: Expansion,  Next: Compiling Macros,  Prev: Simple Macro,  Up: Macros
+
+Expansion of a Macro Call
+=========================
+
+   A macro call looks just like a function call in that it is a list
+which starts with the name of the macro.  The rest of the elements of
+the list are the arguments of the macro.
+
+   Evaluation of the macro call begins like evaluation of a function
+call except for one crucial difference: the macro arguments are the
+actual expressions appearing in the macro call.  They are not evaluated
+before they are given to the macro definition.  By contrast, the
+arguments of a function are results of evaluating the elements of the
+function call list.
+
+   Having obtained the arguments, Lisp invokes the macro definition just
+as a function is invoked.  The argument variables of the macro are bound
+to the argument values from the macro call, or to a list of them in the
+case of a `&rest' argument.  And the macro body executes and returns
+its value just as a function body does.
+
+   The second crucial difference between macros and functions is that
+the value returned by the macro body is not the value of the macro call.
+Instead, it is an alternate expression for computing that value, also
+known as the "expansion" of the macro.  The Lisp interpreter proceeds
+to evaluate the expansion as soon as it comes back from the macro.
+
+   Since the expansion is evaluated in the normal manner, it may contain
+calls to other macros.  It may even be a call to the same macro, though
+this is unusual.
+
+   You can see the expansion of a given macro call by calling
+`macroexpand'.
+
+ - Function: macroexpand form &optional environment
+     This function expands FORM, if it is a macro call.  If the result
+     is another macro call, it is expanded in turn, until something
+     which is not a macro call results.  That is the value returned by
+     `macroexpand'.  If FORM is not a macro call to begin with, it is
+     returned as given.
+
+     Note that `macroexpand' does not look at the subexpressions of
+     FORM (although some macro definitions may do so).  Even if they
+     are macro calls themselves, `macroexpand' does not expand them.
+
+     The function `macroexpand' does not expand calls to inline
+     functions.  Normally there is no need for that, since a call to an
+     inline function is no harder to understand than a call to an
+     ordinary function.
+
+     If ENVIRONMENT is provided, it specifies an alist of macro
+     definitions that shadow the currently defined macros.  Byte
+     compilation uses this feature.
+
+          (defmacro inc (var)
+              (list 'setq var (list '1+ var)))
+               => inc
+          
+          (macroexpand '(inc r))
+               => (setq r (1+ r))
+          
+          (defmacro inc2 (var1 var2)
+              (list 'progn (list 'inc var1) (list 'inc var2)))
+               => inc2
+          
+          (macroexpand '(inc2 r s))
+               => (progn (inc r) (inc s))  ; `inc' not expanded here.
+
+
+File: lispref.info,  Node: Compiling Macros,  Next: Defining Macros,  Prev: Expansion,  Up: Macros
+
+Macros and Byte Compilation
+===========================
+
+   You might ask why we take the trouble to compute an expansion for a
+macro and then evaluate the expansion.  Why not have the macro body
+produce the desired results directly?  The reason has to do with
+compilation.
+
+   When a macro call appears in a Lisp program being compiled, the Lisp
+compiler calls the macro definition just as the interpreter would, and
+receives an expansion.  But instead of evaluating this expansion, it
+compiles the expansion as if it had appeared directly in the program.
+As a result, the compiled code produces the value and side effects
+intended for the macro, but executes at full compiled speed.  This would
+not work if the macro body computed the value and side effects
+itself--they would be computed at compile time, which is not useful.
+
+   In order for compilation of macro calls to work, the macros must be
+defined in Lisp when the calls to them are compiled.  The compiler has a
+special feature to help you do this: if a file being compiled contains a
+`defmacro' form, the macro is defined temporarily for the rest of the
+compilation of that file.  To use this feature, you must define the
+macro in the same file where it is used and before its first use.
+
+   Byte-compiling a file executes any `require' calls at top-level in
+the file.  This is in case the file needs the required packages for
+proper compilation.  One way to ensure that necessary macro definitions
+are available during compilation is to require the files that define
+them (*note Named Features::).  To avoid loading the macro definition
+files when someone _runs_ the compiled program, write
+`eval-when-compile' around the `require' calls (*note Eval During
+Compile::).
+
+
+File: lispref.info,  Node: Defining Macros,  Next: Backquote,  Prev: Compiling Macros,  Up: Macros
+
+Defining Macros
+===============
+
+   A Lisp macro is a list whose CAR is `macro'.  Its CDR should be a
+function; expansion of the macro works by applying the function (with
+`apply') to the list of unevaluated argument-expressions from the macro
+call.
+
+   It is possible to use an anonymous Lisp macro just like an anonymous
+function, but this is never done, because it does not make sense to pass
+an anonymous macro to functionals such as `mapcar'.  In practice, all
+Lisp macros have names, and they are usually defined with the special
+form `defmacro'.
+
+ - Special Form: defmacro name argument-list body-forms...
+     `defmacro' defines the symbol NAME as a macro that looks like this:
+
+          (macro lambda ARGUMENT-LIST . BODY-FORMS)
+
+     This macro object is stored in the function cell of NAME.  The
+     value returned by evaluating the `defmacro' form is NAME, but
+     usually we ignore this value.
+
+     The shape and meaning of ARGUMENT-LIST is the same as in a
+     function, and the keywords `&rest' and `&optional' may be used
+     (*note Argument List::).  Macros may have a documentation string,
+     but any `interactive' declaration is ignored since macros cannot be
+     called interactively.
+
+
+File: lispref.info,  Node: Backquote,  Next: Problems with Macros,  Prev: Defining Macros,  Up: Macros
+
+Backquote
+=========
+
+   Macros often need to construct large list structures from a mixture
+of constants and nonconstant parts.  To make this easier, use the macro
+``' (often called "backquote").
+
+   Backquote allows you to quote a list, but selectively evaluate
+elements of that list.  In the simplest case, it is identical to the
+special form `quote' (*note Quoting::).  For example, these two forms
+yield identical results:
+
+     `(a list of (+ 2 3) elements)
+          => (a list of (+ 2 3) elements)
+     '(a list of (+ 2 3) elements)
+          => (a list of (+ 2 3) elements)
+
+   The special marker `,' inside of the argument to backquote indicates
+a value that isn't constant.  Backquote evaluates the argument of `,'
+and puts the value in the list structure:
+
+     (list 'a 'list 'of (+ 2 3) 'elements)
+          => (a list of 5 elements)
+     `(a list of ,(+ 2 3) elements)
+          => (a list of 5 elements)
+
+   You can also "splice" an evaluated value into the resulting list,
+using the special marker `,@'.  The elements of the spliced list become
+elements at the same level as the other elements of the resulting list.
+The equivalent code without using ``' is often unreadable.  Here are
+some examples:
+
+     (setq some-list '(2 3))
+          => (2 3)
+     (cons 1 (append some-list '(4) some-list))
+          => (1 2 3 4 2 3)
+     `(1 ,@some-list 4 ,@some-list)
+          => (1 2 3 4 2 3)
+     
+     (setq list '(hack foo bar))
+          => (hack foo bar)
+     (cons 'use
+       (cons 'the
+         (cons 'words (append (cdr list) '(as elements)))))
+          => (use the words foo bar as elements)
+     `(use the words ,@(cdr list) as elements)
+          => (use the words foo bar as elements)
+
+     In older versions of Emacs (before XEmacs 19.12 or FSF Emacs
+     version 19.29), ``' used a different syntax which required an
+     extra level of parentheses around the entire backquote construct.
+     Likewise, each `,' or `,@' substitution required an extra level of
+     parentheses surrounding both the `,' or `,@' and the following
+     expression.  The old syntax required whitespace between the ``',
+     `,' or `,@' and the following expression.
+
+     This syntax is still accepted, but no longer recommended except for
+     compatibility with old Emacs versions.
+
+
+File: lispref.info,  Node: Problems with Macros,  Prev: Backquote,  Up: Macros
+
+Common Problems Using Macros
+============================
+
+   The basic facts of macro expansion have counterintuitive
+consequences.  This section describes some important consequences that
+can lead to trouble, and rules to follow to avoid trouble.
+
+* Menu:
+
+* Argument Evaluation::    The expansion should evaluate each macro arg once.
+* Surprising Local Vars::  Local variable bindings in the expansion
+                              require special care.
+* Eval During Expansion::  Don't evaluate them; put them in the expansion.
+* Repeated Expansion::     Avoid depending on how many times expansion is done.
+
+
+File: lispref.info,  Node: Argument Evaluation,  Next: Surprising Local Vars,  Up: Problems with Macros
+
+Evaluating Macro Arguments Repeatedly
+-------------------------------------
+
+   When defining a macro you must pay attention to the number of times
+the arguments will be evaluated when the expansion is executed.  The
+following macro (used to facilitate iteration) illustrates the problem.
+This macro allows us to write a simple "for" loop such as one might
+find in Pascal.
+
+     (defmacro for (var from init to final do &rest body)
+       "Execute a simple \"for\" loop.
+     For example, (for i from 1 to 10 do (print i))."
+       (list 'let (list (list var init))
+             (cons 'while (cons (list '<= var final)
+                                (append body (list (list 'inc var)))))))
+     => for
+     
+     (for i from 1 to 3 do
+        (setq square (* i i))
+        (princ (format "\n%d %d" i square)))
+     ==>
+     (let ((i 1))
+       (while (<= i 3)
+         (setq square (* i i))
+         (princ (format "%d      %d" i square))
+         (inc i)))
+     
+          -|1       1
+          -|2       4
+          -|3       9
+     => nil
+
+(The arguments `from', `to', and `do' in this macro are "syntactic
+sugar"; they are entirely ignored.  The idea is that you will write
+noise words (such as `from', `to', and `do') in those positions in the
+macro call.)
+
+   Here's an equivalent definition simplified through use of backquote:
+
+     (defmacro for (var from init to final do &rest body)
+       "Execute a simple \"for\" loop.
+     For example, (for i from 1 to 10 do (print i))."
+       `(let ((,var ,init))
+          (while (<= ,var ,final)
+            ,@body
+            (inc ,var))))
+
+   Both forms of this definition (with backquote and without) suffer
+from the defect that FINAL is evaluated on every iteration.  If FINAL
+is a constant, this is not a problem.  If it is a more complex form,
+say `(long-complex-calculation x)', this can slow down the execution
+significantly.  If FINAL has side effects, executing it more than once
+is probably incorrect.
+
+   A well-designed macro definition takes steps to avoid this problem by
+producing an expansion that evaluates the argument expressions exactly
+once unless repeated evaluation is part of the intended purpose of the
+macro.  Here is a correct expansion for the `for' macro:
+
+     (let ((i 1)
+           (max 3))
+       (while (<= i max)
+         (setq square (* i i))
+         (princ (format "%d      %d" i square))
+         (inc i)))
+
+   Here is a macro definition that creates this expansion:
+
+     (defmacro for (var from init to final do &rest body)
+       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+       `(let ((,var ,init)
+              (max ,final))
+          (while (<= ,var max)
+            ,@body
+            (inc ,var))))
+
+   Unfortunately, this introduces another problem.  Proceed to the
+following node.
+
+
+File: lispref.info,  Node: Surprising Local Vars,  Next: Eval During Expansion,  Prev: Argument Evaluation,  Up: Problems with Macros
+
+Local Variables in Macro Expansions
+-----------------------------------
+
+   In the previous section, the definition of `for' was fixed as
+follows to make the expansion evaluate the macro arguments the proper
+number of times:
+
+     (defmacro for (var from init to final do &rest body)
+       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+       `(let ((,var ,init)
+              (max ,final))
+          (while (<= ,var max)
+            ,@body
+            (inc ,var))))
+
+   The new definition of `for' has a new problem: it introduces a local
+variable named `max' which the user does not expect.  This causes
+trouble in examples such as the following:
+
+     (let ((max 0))
+       (for x from 0 to 10 do
+         (let ((this (frob x)))
+           (if (< max this)
+               (setq max this)))))
+
+The references to `max' inside the body of the `for', which are
+supposed to refer to the user's binding of `max', really access the
+binding made by `for'.
+
+   The way to correct this is to use an uninterned symbol instead of
+`max' (*note Creating Symbols::).  The uninterned symbol can be bound
+and referred to just like any other symbol, but since it is created by
+`for', we know that it cannot already appear in the user's program.
+Since it is not interned, there is no way the user can put it into the
+program later.  It will never appear anywhere except where put by
+`for'.  Here is a definition of `for' that works this way:
+
+     (defmacro for (var from init to final do &rest body)
+       "Execute a simple for loop: (for i from 1 to 10 do (print i))."
+       (let ((tempvar (make-symbol "max")))
+         `(let ((,var ,init)
+                (,tempvar ,final))
+            (while (<= ,var ,tempvar)
+              ,@body
+              (inc ,var)))))
+
+This creates an uninterned symbol named `max' and puts it in the
+expansion instead of the usual interned symbol `max' that appears in
+expressions ordinarily.
+
+
+File: lispref.info,  Node: Eval During Expansion,  Next: Repeated Expansion,  Prev: Surprising Local Vars,  Up: Problems with Macros
+
+Evaluating Macro Arguments in Expansion
+---------------------------------------
+
+   Another problem can happen if you evaluate any of the macro argument
+expressions during the computation of the expansion, such as by calling
+`eval' (*note Eval::).  If the argument is supposed to refer to the
+user's variables, you may have trouble if the user happens to use a
+variable with the same name as one of the macro arguments.  Inside the
+macro body, the macro argument binding is the most local binding of this
+variable, so any references inside the form being evaluated do refer to
+it.  Here is an example:
+
+     (defmacro foo (a)
+       (list 'setq (eval a) t))
+          => foo
+     (setq x 'b)
+     (foo x) ==> (setq b t)
+          => t                  ; and `b' has been set.
+     ;; but
+     (setq a 'c)
+     (foo a) ==> (setq a t)
+          => t                  ; but this set `a', not `c'.
+
+   It makes a difference whether the user's variable is named `a' or
+`x', because `a' conflicts with the macro argument variable `a'.
+
+   Another reason not to call `eval' in a macro definition is that it
+probably won't do what you intend in a compiled program.  The
+byte-compiler runs macro definitions while compiling the program, when
+the program's own computations (which you might have wished to access
+with `eval') don't occur and its local variable bindings don't exist.
+
+   The safe way to work with the run-time value of an expression is to
+put the expression into the macro expansion, so that its value is
+computed as part of executing the expansion.
+
+
+File: lispref.info,  Node: Repeated Expansion,  Prev: Eval During Expansion,  Up: Problems with Macros
+
+How Many Times is the Macro Expanded?
+-------------------------------------
+
+   Occasionally problems result from the fact that a macro call is
+expanded each time it is evaluated in an interpreted function, but is
+expanded only once (during compilation) for a compiled function.  If the
+macro definition has side effects, they will work differently depending
+on how many times the macro is expanded.
+
+   In particular, constructing objects is a kind of side effect.  If the
+macro is called once, then the objects are constructed only once.  In
+other words, the same structure of objects is used each time the macro
+call is executed.  In interpreted operation, the macro is reexpanded
+each time, producing a fresh collection of objects each time.  Usually
+this does not matter--the objects have the same contents whether they
+are shared or not.  But if the surrounding program does side effects on
+the objects, it makes a difference whether they are shared.  Here is an
+example:
+
+     (defmacro empty-object ()
+       (list 'quote (cons nil nil)))
+     
+     (defun initialize (condition)
+       (let ((object (empty-object)))
+         (if condition
+             (setcar object condition))
+         object))
+
+If `initialize' is interpreted, a new list `(nil)' is constructed each
+time `initialize' is called.  Thus, no side effect survives between
+calls.  If `initialize' is compiled, then the macro `empty-object' is
+expanded during compilation, producing a single "constant" `(nil)' that
+is reused and altered each time `initialize' is called.
+
+   One way to avoid pathological cases like this is to think of
+`empty-object' as a funny kind of constant, not as a memory allocation
+construct.  You wouldn't use `setcar' on a constant such as `'(nil)',
+so naturally you won't use it on `(empty-object)' either.
+
+
+File: lispref.info,  Node: Customization,  Up: Top
+
+Writing Customization Definitions
+*********************************
+
+   This chapter describes how to declare user options for customization,
+and also customization groups for classifying them.  We use the term
+"customization item" to include both kinds of customization
+definitions--as well as face definitions.
+
+* Menu:
+
+* Common Keywords::
+* Group Definitions::
+* Variable Definitions::
+* Customization Types::
+
+
+File: lispref.info,  Node: Common Keywords,  Next: Group Definitions,  Up: Customization
+
+Common Keywords for All Kinds of Items
+======================================
+
+   All kinds of customization declarations (for variables and groups,
+and for faces) accept keyword arguments for specifying various
+information.  This section describes some keywords that apply to all
+kinds.
+
+   All of these keywords, except `:tag', can be used more than once in
+a given item.  Each use of the keyword has an independent effect.  The
+keyword `:tag' is an exception because any given item can only display
+one name.
+
+`:tag NAME'
+     Use NAME, a string, instead of the item's name, to label the item
+     in customization menus and buffers.
+
+`:group GROUP'
+     Put this customization item in group GROUP.  When you use `:group'
+     in a `defgroup', it makes the new group a subgroup of GROUP.
+
+     If you use this keyword more than once, you can put a single item
+     into more than one group.  Displaying any of those groups will
+     show this item.  Be careful not to overdo this!
+
+`:link LINK-DATA'
+     Include an external link after the documentation string for this
+     item.  This is a sentence containing an active field which
+     references some other documentation.
+
+     There are three alternatives you can use for LINK-DATA:
+
+    `(custom-manual INFO-NODE)'
+          Link to an Info node; INFO-NODE is a string which specifies
+          the node name, as in `"(emacs)Top"'.  The link appears as
+          `[manual]' in the customization buffer.
+
+    `(info-link INFO-NODE)'
+          Like `custom-manual' except that the link appears in the
+          customization buffer with the Info node name.
+
+    `(url-link URL)'
+          Link to a web page; URL is a string which specifies the URL.
+          The link appears in the customization buffer as URL.
+
+     You can specify the text to use in the customization buffer by
+     adding `:tag NAME' after the first element of the LINK-DATA; for
+     example, `(info-link :tag "foo" "(emacs)Top")' makes a link to the
+     Emacs manual which appears in the buffer as `foo'.
+
+     An item can have more than one external link; however, most items
+     have none at all.
+
+`:load FILE'
+     Load file FILE (a string) before displaying this customization
+     item.  Loading is done with `load-library', and only if the file is
+     not already loaded.
+
+`:require FEATURE'
+     Require feature FEATURE (a symbol) when installing a value for
+     this item (an option or a face) that was saved using the
+     customization feature.  This is done by calling `require'.
+
+     The most common reason to use `:require' is when a variable enables
+     a feature such as a minor mode, and just setting the variable
+     won't have any effect unless the code which implements the mode is
+     loaded.
+
+
+File: lispref.info,  Node: Group Definitions,  Next: Variable Definitions,  Prev: Common Keywords,  Up: Customization
+
+Defining Custom Groups
+======================
+
+   Each Emacs Lisp package should have one main customization group
+which contains all the options, faces and other groups in the package.
+If the package has a small number of options and faces, use just one
+group and put everything in it.  When there are more than twelve or so
+options and faces, then you should structure them into subgroups, and
+put the subgroups under the package's main customization group.  It is
+OK to put some of the options and faces in the package's main group
+alongside the subgroups.
+
+   The package's main or only group should be a member of one or more of
+the standard customization groups.  (To display the full list of them,
+use `M-x customize'.)  Choose one or more of them (but not too many),
+and add your group to each of them using the `:group' keyword.
+
+   The way to declare new customization groups is with `defgroup'.
+
+ - Macro: defgroup group members doc [keyword value]...
+     Declare GROUP as a customization group containing MEMBERS.  Do not
+     quote the symbol GROUP.  The argument DOC specifies the
+     documentation string for the group.
+
+     The argument MEMBERS is a list specifying an initial set of
+     customization items to be members of the group.  However, most
+     often MEMBERS is `nil', and you specify the group's members by
+     using the `:group' keyword when defining those members.
+
+     If you want to specify group members through MEMBERS, each element
+     should have the form `(NAME WIDGET)'.  Here NAME is a symbol, and
+     WIDGET is a widget type for editing that symbol.  Useful widgets
+     are `custom-variable' for a variable, `custom-face' for a face,
+     and `custom-group' for a group.
+
+     In addition to the common keywords (*note Common Keywords::), you
+     can use this keyword in `defgroup':
+
+    `:prefix PREFIX'
+          If the name of an item in the group starts with PREFIX, then
+          the tag for that item is constructed (by default) by omitting
+          PREFIX.
+
+          One group can have any number of prefixes.
+
+
+File: lispref.info,  Node: Variable Definitions,  Next: Customization Types,  Prev: Group Definitions,  Up: Customization
+
+Defining Customization Variables
+================================
+
+   Use `defcustom' to declare user-editable variables.
+
+ - Macro: defcustom option default doc [keyword value]...
+     Declare OPTION as a customizable user option variable.  Do not
+     quote OPTION.  The argument DOC specifies the documentation string
+     for the variable.
+
+     If OPTION is void, `defcustom' initializes it to DEFAULT.  DEFAULT
+     should be an expression to compute the value; be careful in
+     writing it, because it can be evaluated on more than one occasion.
+
+     The following additional keywords are defined:
+
+    `:type TYPE'
+          Use TYPE as the data type for this option.  It specifies which
+          values are legitimate, and how to display the value.  *Note
+          Customization Types::, for more information.
+
+    `:options LIST'
+          Specify LIST as the list of reasonable values for use in this
+          option.
+
+          Currently this is meaningful only when the type is `hook'.
+          In that case, the elements of LIST should be functions that
+          are useful as elements of the hook value.  The user is not
+          restricted to using only these functions, but they are
+          offered as convenient alternatives.
+
+    `:version VERSION'
+          This option specifies that the variable was first introduced,
+          or its default value was changed, in Emacs version VERSION.
+          The value VERSION must be a string.  For example,
+
+               (defcustom foo-max 34
+                 "*Maximum number of foo's allowed."
+                 :type 'integer
+                 :group 'foo
+                 :version "20.3")
+
+    `:set SETFUNCTION'
+          Specify SETFUNCTION as the way to change the value of this
+          option.  The function SETFUNCTION should take two arguments,
+          a symbol and the new value, and should do whatever is
+          necessary to update the value properly for this option (which
+          may not mean simply setting the option as a Lisp variable).
+          The default for SETFUNCTION is `set-default'.
+
+    `:get GETFUNCTION'
+          Specify GETFUNCTION as the way to extract the value of this
+          option.  The function GETFUNCTION should take one argument, a
+          symbol, and should return the "current value" for that symbol
+          (which need not be the symbol's Lisp value).  The default is
+          `default-value'.
+
+    `:initialize FUNCTION'
+          FUNCTION should be a function used to initialize the variable
+          when the `defcustom' is evaluated.  It should take two
+          arguments, the symbol and value.  Here are some predefined
+          functions meant for use in this way:
+
+         `custom-initialize-set'
+               Use the variable's `:set' function to initialize the
+               variable, but do not reinitialize it if it is already
+               non-void.  This is the default `:initialize' function.
+
+         `custom-initialize-default'
+               Like `custom-initialize-set', but use the function
+               `set-default' to set the variable, instead of the
+               variable's `:set' function.  This is the usual choice
+               for a variable whose `:set' function enables or disables
+               a minor mode; with this choice, defining the variable
+               will not call the minor mode function, but customizing
+               the variable will do so.
+
+         `custom-initialize-reset'
+               Always use the `:set' function to initialize the
+               variable.  If the variable is already non-void, reset it
+               by calling the `:set' function using the current value
+               (returned by the `:get' method).
+
+         `custom-initialize-changed'
+               Use the `:set' function to initialize the variable, if
+               it is already set or has been customized; otherwise,
+               just use `set-default'.
+
+   The `:require' option is useful for an option that turns on the
+operation of a certain feature.  Assuming that the package is coded to
+check the value of the option, you still need to arrange for the package
+to be loaded.  You can do that with `:require'.  *Note Common
+Keywords::.  Here is an example, from the library `paren.el':
+
+     (defcustom show-paren-mode nil
+       "Toggle Show Paren mode...."
+       :set (lambda (symbol value)
+              (show-paren-mode (or value 0)))
+       :initialize 'custom-initialize-default
+       :type 'boolean
+       :group 'paren-showing
+       :require 'paren)
+
+   Internally, `defcustom' uses the symbol property `standard-value' to
+record the expression for the default value, and `saved-value' to
+record the value saved by the user with the customization buffer.  The
+`saved-value' property is actually a list whose car is an expression
+which evaluates to the value.
+
+
+File: lispref.info,  Node: Customization Types,  Prev: Variable Definitions,  Up: Customization
+
+Customization Types
+===================
+
+   When you define a user option with `defcustom', you must specify its
+"customization type".  That is a Lisp object which describes (1) which
+values are legitimate and (2) how to display the value in the
+customization buffer for editing.
+
+   You specify the customization type in `defcustom' with the `:type'
+keyword.  The argument of `:type' is evaluated; since types that vary
+at run time are rarely useful, normally you use a quoted constant.  For
+example:
+
+     (defcustom diff-command "diff"
+       "*The command to use to run diff."
+       :type '(string)
+       :group 'diff)
+
+   In general, a customization type is a list whose first element is a
+symbol, one of the customization type names defined in the following
+sections.  After this symbol come a number of arguments, depending on
+the symbol.  Between the type symbol and its arguments, you can
+optionally write keyword-value pairs (*note Type Keywords::).
+
+   Some of the type symbols do not use any arguments; those are called
+"simple types".  For a simple type, if you do not use any keyword-value
+pairs, you can omit the parentheses around the type symbol.  For
+example just `string' as a customization type is equivalent to
+`(string)'.
+
+* Menu:
+
+* Simple Types::
+* Composite Types::
+* Splicing into Lists::
+* Type Keywords::
+
+
+File: lispref.info,  Node: Simple Types,  Next: Composite Types,  Up: Customization Types
+
+Simple Types
+------------
+
+   This section describes all the simple customization types.
+
+`sexp'
+     The value may be any Lisp object that can be printed and read
+     back.  You can use `sexp' as a fall-back for any option, if you
+     don't want to take the time to work out a more specific type to
+     use.
+
+`integer'
+     The value must be an integer, and is represented textually in the
+     customization buffer.
+
+`number'
+     The value must be a number, and is represented textually in the
+     customization buffer.
+
+`string'
+     The value must be a string, and the customization buffer shows
+     just the contents, with no delimiting `"' characters and no
+     quoting with `\'.
+
+`regexp'
+     Like `string' except that the string must be a valid regular
+     expression.
+
+`character'
+     The value must be a character code.  A character code is actually
+     an integer, but this type shows the value by inserting the
+     character in the buffer, rather than by showing the number.
+
+`file'
+     The value must be a file name, and you can do completion with
+     `M-<TAB>'.
+
+`(file :must-match t)'
+     The value must be a file name for an existing file, and you can do
+     completion with `M-<TAB>'.
+
+`directory'
+     The value must be a directory name, and you can do completion with
+     `M-<TAB>'.
+
+`symbol'
+     The value must be a symbol.  It appears in the customization
+     buffer as the name of the symbol.
+
+`function'
+     The value must be either a lambda expression or a function name.
+     When it is a function name, you can do completion with `M-<TAB>'.
+
+`variable'
+     The value must be a variable name, and you can do completion with
+     `M-<TAB>'.
+
+`face'
+     The value must be a symbol which is a face name.
+
+`boolean'
+     The value is boolean--either `nil' or `t'.  Note that by using
+     `choice' and `const' together (see the next section), you can
+     specify that the value must be `nil' or `t', but also specify the
+     text to describe each value in a way that fits the specific
+     meaning of the alternative.
+
+
+File: lispref.info,  Node: Composite Types,  Next: Splicing into Lists,  Prev: Simple Types,  Up: Customization Types
+
+Composite Types
+---------------
+
+   When none of the simple types is appropriate, you can use composite
+types, which build new types from other types.  Here are several ways of
+doing that:
+
+`(restricted-sexp :match-alternatives CRITERIA)'
+     The value may be any Lisp object that satisfies one of CRITERIA.
+     CRITERIA should be a list, and each elements should be one of
+     these possibilities:
+
+        * A predicate--that is, a function of one argument that returns
+          non-`nil' if the argument fits a certain type.  This means
+          that objects of that type are acceptable.
+
+        * A quoted constant--that is, `'OBJECT'.  This means that
+          OBJECT itself is an acceptable value.
+
+     For example,
+
+          (restricted-sexp :match-alternatives (integerp 't 'nil))
+
+     allows integers, `t' and `nil' as legitimate values.
+
+     The customization buffer shows all legitimate values using their
+     read syntax, and the user edits them textually.
+
+`(cons CAR-TYPE CDR-TYPE)'
+     The value must be a cons cell, its CAR must fit CAR-TYPE, and its
+     CDR must fit CDR-TYPE.  For example, `(cons string symbol)' is a
+     customization type which matches values such as `("foo" . foo)'.
+
+     In the customization buffer, the CAR and the CDR are displayed and
+     edited separately, each according to the type that you specify for
+     it.
+
+`(list ELEMENT-TYPES...)'
+     The value must be a list with exactly as many elements as the
+     ELEMENT-TYPES you have specified; and each element must fit the
+     corresponding ELEMENT-TYPE.
+
+     For example, `(list integer string function)' describes a list of
+     three elements; the first element must be an integer, the second a
+     string, and the third a function.
+
+     In the customization buffer, the each element is displayed and
+     edited separately, according to the type specified for it.
+
+`(vector ELEMENT-TYPES...)'
+     Like `list' except that the value must be a vector instead of a
+     list.  The elements work the same as in `list'.
+
+`(choice ALTERNATIVE-TYPES...)'
+     The value must fit at least one of ALTERNATIVE-TYPES.  For
+     example, `(choice integer string)' allows either an integer or a
+     string.
+
+     In the customization buffer, the user selects one of the
+     alternatives using a menu, and can then edit the value in the
+     usual way for that alternative.
+
+     Normally the strings in this menu are determined automatically
+     from the choices; however, you can specify different strings for
+     the menu by including the `:tag' keyword in the alternatives.  For
+     example, if an integer stands for a number of spaces, while a
+     string is text to use verbatim, you might write the customization
+     type this way,
+
+          (choice (integer :tag "Number of spaces")
+                  (string :tag "Literal text"))
+
+     so that the menu offers `Number of spaces' and `Literal Text'.
+
+     In any alternative for which `nil' is not a valid value, other than
+     a `const', you should specify a valid default for that alternative
+     using the `:value' keyword.  *Note Type Keywords::.
+
+`(const VALUE)'
+     The value must be VALUE--nothing else is allowed.
+
+     The main use of `const' is inside of `choice'.  For example,
+     `(choice integer (const nil))' allows either an integer or `nil'.
+
+     `:tag' is often used with `const', inside of `choice'.  For
+     example,
+
+          (choice (const :tag "Yes" t)
+                  (const :tag "No" nil)
+                  (const :tag "Ask" foo))
+
+`(function-item FUNCTION)'
+     Like `const', but used for values which are functions.  This
+     displays the documentation string as well as the function name.
+     The documentation string is either the one you specify with
+     `:doc', or FUNCTION's own documentation string.
+
+`(variable-item VARIABLE)'
+     Like `const', but used for values which are variable names.  This
+     displays the documentation string as well as the variable name.
+     The documentation string is either the one you specify with
+     `:doc', or VARIABLE's own documentation string.
+
+`(set ELEMENTS...)'
+     The value must be a list and each element of the list must be one
+     of the ELEMENTS specified.  This appears in the customization
+     buffer as a checklist.
+
+`(repeat ELEMENT-TYPE)'
+     The value must be a list and each element of the list must fit the
+     type ELEMENT-TYPE.  This appears in the customization buffer as a
+     list of elements, with `[INS]' and `[DEL]' buttons for adding more
+     elements or removing elements.
+
+
+File: lispref.info,  Node: Splicing into Lists,  Next: Type Keywords,  Prev: Composite Types,  Up: Customization Types
+
+Splicing into Lists
+-------------------
+
+   The `:inline' feature lets you splice a variable number of elements
+into the middle of a list or vector.  You use it in a `set', `choice'
+or `repeat' type which appears among the element-types of a `list' or
+`vector'.
+
+   Normally, each of the element-types in a `list' or `vector'
+describes one and only one element of the list or vector.  Thus, if an
+element-type is a `repeat', that specifies a list of unspecified length
+which appears as one element.
+
+   But when the element-type uses `:inline', the value it matches is
+merged directly into the containing sequence.  For example, if it
+matches a list with three elements, those become three elements of the
+overall sequence.  This is analogous to using `,@' in the backquote
+construct.
+
+   For example, to specify a list whose first element must be `t' and
+whose remaining arguments should be zero or more of `foo' and `bar',
+use this customization type:
+
+     (list (const t) (set :inline t foo bar))
+
+This matches values such as `(t)', `(t foo)', `(t bar)' and `(t foo
+bar)'.
+
+   When the element-type is a `choice', you use `:inline' not in the
+`choice' itself, but in (some of) the alternatives of the `choice'.
+For example, to match a list which must start with a file name,
+followed either by the symbol `t' or two strings, use this
+customization type:
+
+     (list file
+           (choice (const t)
+                   (list :inline t string string)))
+
+If the user chooses the first alternative in the choice, then the
+overall list has two elements and the second element is `t'.  If the
+user chooses the second alternative, then the overall list has three
+elements and the second and third must be strings.
+
+
+File: lispref.info,  Node: Type Keywords,  Prev: Splicing into Lists,  Up: Customization Types
+
+Type Keywords
+-------------
+
+   You can specify keyword-argument pairs in a customization type after
+the type name symbol.  Here are the keywords you can use, and their
+meanings:
+
+`:value DEFAULT'
+     This is used for a type that appears as an alternative inside of
+     `choice'; it specifies the default value to use, at first, if and
+     when the user selects this alternative with the menu in the
+     customization buffer.
+
+     Of course, if the actual value of the option fits this
+     alternative, it will appear showing the actual value, not DEFAULT.
+
+     If `nil' is not a valid value for the alternative, then it is
+     essential to specify a valid default with `:value'.
+
+`:format FORMAT-STRING'
+     This string will be inserted in the buffer to represent the value
+     corresponding to the type.  The following `%' escapes are available
+     for use in FORMAT-STRING:
+
+    `%[BUTTON%]'
+          Display the text BUTTON marked as a button.  The `:action'
+          attribute specifies what the button will do if the user
+          invokes it; its value is a function which takes two
+          arguments--the widget which the button appears in, and the
+          event.
+
+          There is no way to specify two different buttons with
+          different actions.
+
+    `%{SAMPLE%}'
+          Show SAMPLE in a special face specified by `:sample-face'.
+
+    `%v'
+          Substitute the item's value.  How the value is represented
+          depends on the kind of item, and (for variables) on the
+          customization type.
+
+    `%d'
+          Substitute the item's documentation string.
+
+    `%h'
+          Like `%d', but if the documentation string is more than one
+          line, add an active field to control whether to show all of
+          it or just the first line.
+
+    `%t'
+          Substitute the tag here.  You specify the tag with the `:tag'
+          keyword.
+
+    `%%'
+          Display a literal `%'.
+
+`:action ACTION'
+     Perform ACTION if the user clicks on a button.
+
+`:button-face FACE'
+     Use the face FACE (a face name or a list of face names) for button
+     text displayed with `%[...%]'.
+
+`:button-prefix PREFIX'
+`:button-suffix SUFFIX'
+     These specify the text to display before and after a button.  Each
+     can be:
+
+    `nil'
+          No text is inserted.
+
+    a string
+          The string is inserted literally.
+
+    a symbol
+          The symbol's value is used.
+
+`:tag TAG'
+     Use TAG (a string) as the tag for the value (or part of the value)
+     that corresponds to this type.
+
+`:doc DOC'
+     Use DOC as the documentation string for this value (or part of the
+     value) that corresponds to this type.  In order for this to work,
+     you must specify a value for `:format', and use `%d' or `%h' in
+     that value.
+
+     The usual reason to specify a documentation string for a type is to
+     provide more information about the meanings of alternatives inside
+     a `:choice' type or the parts of some other composite type.
+
+`:help-echo MOTION-DOC'
+     When you move to this item with `widget-forward' or
+     `widget-backward', it will display the string MOTION-DOC in the
+     echo area.
+
+`:match FUNCTION'
+     Specify how to decide whether a value matches the type.  The
+     corresponding value, FUNCTION, should be a function that accepts
+     two arguments, a widget and a value; it should return non-`nil' if
+     the value is acceptable.
+
+
+File: lispref.info,  Node: Loading,  Next: Byte Compilation,  Prev: Macros,  Up: Top
+
+Loading
+*******
+
+   Loading a file of Lisp code means bringing its contents into the Lisp
+environment in the form of Lisp objects.  XEmacs finds and opens the
+file, reads the text, evaluates each form, and then closes the file.
+
+   The load functions evaluate all the expressions in a file just as
+the `eval-current-buffer' function evaluates all the expressions in a
+buffer.  The difference is that the load functions read and evaluate
+the text in the file as found on disk, not the text in an Emacs buffer.
+
+   The loaded file must contain Lisp expressions, either as source code
+or as byte-compiled code.  Each form in the file is called a "top-level
+form".  There is no special format for the forms in a loadable file;
+any form in a file may equally well be typed directly into a buffer and
+evaluated there.  (Indeed, most code is tested this way.)  Most often,
+the forms are function definitions and variable definitions.
+
+   A file containing Lisp code is often called a "library".  Thus, the
+"Rmail library" is a file containing code for Rmail mode.  Similarly, a
+"Lisp library directory" is a directory of files containing Lisp code.
+
+* Menu:
+
+* How Programs Do Loading::     The `load' function and others.
+* Autoload::                    Setting up a function to autoload.
+* Repeated Loading::            Precautions about loading a file twice.
+* Named Features::              Loading a library if it isn't already loaded.
+* Unloading::			How to ``unload'' a library that was loaded.
+* Hooks for Loading::		Providing code to be run when
+				  particular libraries are loaded.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-12'
Index: ././info/lispref.info-12
--- ././info/lispref.info-12	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-12	Thu May 17 23:26:54 2001
@@ -0,0 +1,1139 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: How Programs Do Loading,  Next: Autoload,  Up: Loading
+
+How Programs Do Loading
+=======================
+
+   XEmacs Lisp has several interfaces for loading.  For example,
+`autoload' creates a placeholder object for a function in a file;
+trying to call the autoloading function loads the file to get the
+function's real definition (*note Autoload::).  `require' loads a file
+if it isn't already loaded (*note Named Features::).  Ultimately, all
+these facilities call the `load' function to do the work.
+
+ - Function: load filename &optional missing-ok nomessage nosuffix
+     This function finds and opens a file of Lisp code, evaluates all
+     the forms in it, and closes the file.
+
+     To find the file, `load' first looks for a file named
+     `FILENAME.elc', that is, for a file whose name is FILENAME with
+     `.elc' appended.  If such a file exists, it is loaded.  If there
+     is no file by that name, then `load' looks for a file named
+     `FILENAME.el'.  If that file exists, it is loaded.  Finally, if
+     neither of those names is found, `load' looks for a file named
+     FILENAME with nothing appended, and loads it if it exists.  (The
+     `load' function is not clever about looking at FILENAME.  In the
+     perverse case of a file named `foo.el.el', evaluation of `(load
+     "foo.el")' will indeed find it.)
+
+     If the optional argument NOSUFFIX is non-`nil', then the suffixes
+     `.elc' and `.el' are not tried.  In this case, you must specify
+     the precise file name you want.
+
+     If FILENAME is a relative file name, such as `foo' or
+     `baz/foo.bar', `load' searches for the file using the variable
+     `load-path'.  It appends FILENAME to each of the directories
+     listed in `load-path', and loads the first file it finds whose name
+     matches.  The current default directory is tried only if it is
+     specified in `load-path', where `nil' stands for the default
+     directory.  `load' tries all three possible suffixes in the first
+     directory in `load-path', then all three suffixes in the second
+     directory, and so on.
+
+     If you get a warning that `foo.elc' is older than `foo.el', it
+     means you should consider recompiling `foo.el'.  *Note Byte
+     Compilation::.
+
+     Messages like `Loading foo...' and `Loading foo...done' appear in
+     the echo area during loading unless NOMESSAGE is non-`nil'.
+
+     Any unhandled errors while loading a file terminate loading.  If
+     the load was done for the sake of `autoload', any function
+     definitions made during the loading are undone.
+
+     If `load' can't find the file to load, then normally it signals the
+     error `file-error' (with `Cannot open load file FILENAME').  But
+     if MISSING-OK is non-`nil', then `load' just returns `nil'.
+
+     You can use the variable `load-read-function' to specify a function
+     for `load' to use instead of `read' for reading expressions.  See
+     below.
+
+     `load' returns `t' if the file loads successfully.
+
+ - User Option: load-path
+     The value of this variable is a list of directories to search when
+     loading files with `load'.  Each element is a string (which must be
+     a directory name) or `nil' (which stands for the current working
+     directory).  The value of `load-path' is initialized from the
+     environment variable `EMACSLOADPATH', if that exists; otherwise its
+     default value is specified in `emacs/src/paths.h' when XEmacs is
+     built.
+
+     The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
+     (or `;', according to the operating system) separates directory
+     names, and `.' is used for the current default directory.  Here is
+     an example of how to set your `EMACSLOADPATH' variable from a
+     `csh' `.login' file:
+
+          setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
+
+     Here is how to set it using `sh':
+
+          export EMACSLOADPATH
+          EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
+
+     Here is an example of code you can place in a `.emacs' file to add
+     several directories to the front of your default `load-path':
+
+          (setq load-path
+                (append (list nil "/user/bil/emacs"
+                              "/usr/local/lisplib"
+                              "~/emacs")
+                        load-path))
+
+     In this example, the path searches the current working directory
+     first, followed then by the `/user/bil/emacs' directory, the
+     `/usr/local/lisplib' directory, and the `~/emacs' directory, which
+     are then followed by the standard directories for Lisp code.
+
+     The command line options `-l' or `-load' specify a Lisp library to
+     load as part of Emacs startup.  Since this file might be in the
+     current directory, Emacs 18 temporarily adds the current directory
+     to the front of `load-path' so the file can be found there.  Newer
+     Emacs versions also find such files in the current directory, but
+     without altering `load-path'.
+
+     Dumping Emacs uses a special value of `load-path'.  If the value of
+     `load-path' at the end of dumping is unchanged (that is, still the
+     same special value), the dumped Emacs switches to the ordinary
+     `load-path' value when it starts up, as described above.  But if
+     `load-path' has any other value at the end of dumping, that value
+     is used for execution of the dumped Emacs also.
+
+     Therefore, if you want to change `load-path' temporarily for
+     loading a few libraries in `site-init.el' or `site-load.el', you
+     should bind `load-path' locally with `let' around the calls to
+     `load'.
+
+ - Function: locate-file filename path-list &optional suffixes mode
+     This function searches for a file in the same way that `load' does,
+     and returns the file found (if any). (In fact, `load' uses this
+     function to search through `load-path'.) It searches for FILENAME
+     through PATH-LIST, expanded by one of the optional SUFFIXES
+     (string of suffixes separated by `:'s), checking for access MODE
+     (0|1|2|4 = exists|executable|writable|readable), default readable.
+
+     `locate-file' keeps hash tables of the directories it searches
+     through, in order to speed things up.  It tries valiantly to not
+     get confused in the face of a changing and unpredictable
+     environment, but can occasionally get tripped up.  In this case,
+     you will have to call `locate-file-clear-hashing' to get it back
+     on track.  See that function for details.
+
+ - Function: locate-file-clear-hashing path
+     This function clears the hash records for the specified list of
+     directories.  `locate-file' uses a hashing scheme to speed lookup,
+     and will correctly track the following environmental changes:
+
+        * changes of any sort to the list of directories to be searched.
+
+        * addition and deletion of non-shadowing files (see below) from
+          the directories in the list.
+
+        * byte-compilation of a .el file into a .elc file.
+
+     `locate-file' will primarily get confused if you add a file that
+     shadows (i.e. has the same name as) another file further down in
+     the directory list.  In this case, you must call
+     `locate-file-clear-hashing'.
+
+ - Variable: load-in-progress
+     This variable is non-`nil' if Emacs is in the process of loading a
+     file, and it is `nil' otherwise.
+
+ - Variable: load-read-function
+     This variable specifies an alternate expression-reading function
+     for `load' and `eval-region' to use instead of `read'.  The
+     function should accept one argument, just as `read' does.
+
+     Normally, the variable's value is `nil', which means those
+     functions should use `read'.
+
+ - User Option: load-warn-when-source-newer
+     This variable specifies whether `load' should check whether the
+     source is newer than the binary.  If this variable is true, then
+     when a `.elc' file is being loaded and the corresponding `.el' is
+     newer, a warning message will be printed.  The default is `nil',
+     but it is bound to `t' during the initial loadup.
+
+ - User Option: load-warn-when-source-only
+     This variable specifies whether `load' should warn when loading a
+     `.el' file instead of an `.elc'.  If this variable is true, then
+     when `load' is called with a filename without an extension, and
+     the `.elc' version doesn't exist but the `.el' version does, then
+     a message will be printed.  If an explicit extension is passed to
+     `load', no warning will be printed.  The default is `nil', but it
+     is bound to `t' during the initial loadup.
+
+ - User Option: load-ignore-elc-files
+     This variable specifies whether `load' should ignore `.elc' files
+     when a suffix is not given.  This is normally used only to
+     bootstrap the `.elc' files when building XEmacs, when you use the
+     command `make all-elc'. (This forces the `.el' versions to be
+     loaded in the process of compiling those same files, so that
+     existing out-of-date `.elc' files do not make it mess things up.)
+
+   To learn how `load' is used to build XEmacs, see *Note Building
+XEmacs::.
+
+
+File: lispref.info,  Node: Autoload,  Next: Repeated Loading,  Prev: How Programs Do Loading,  Up: Loading
+
+Autoload
+========
+
+   The "autoload" facility allows you to make a function or macro known
+in Lisp, but put off loading the file that defines it.  The first call
+to the function automatically reads the proper file to install the real
+definition and other associated code, then runs the real definition as
+if it had been loaded all along.
+
+   There are two ways to set up an autoloaded function: by calling
+`autoload', and by writing a special "magic" comment in the source
+before the real definition.  `autoload' is the low-level primitive for
+autoloading; any Lisp program can call `autoload' at any time.  Magic
+comments do nothing on their own; they serve as a guide for the command
+`update-file-autoloads', which constructs calls to `autoload' and
+arranges to execute them when Emacs is built.  Magic comments are the
+most convenient way to make a function autoload, but only for packages
+installed along with Emacs.
+
+ - Function: autoload function filename &optional docstring interactive
+          type
+     This function defines the function (or macro) named FUNCTION so as
+     to load automatically from FILENAME.  The string FILENAME
+     specifies the file to load to get the real definition of FUNCTION.
+
+     The argument DOCSTRING is the documentation string for the
+     function.  Normally, this is identical to the documentation string
+     in the function definition itself.  Specifying the documentation
+     string in the call to `autoload' makes it possible to look at the
+     documentation without loading the function's real definition.
+
+     If INTERACTIVE is non-`nil', then the function can be called
+     interactively.  This lets completion in `M-x' work without loading
+     the function's real definition.  The complete interactive
+     specification need not be given here; it's not needed unless the
+     user actually calls FUNCTION, and when that happens, it's time to
+     load the real definition.
+
+     You can autoload macros and keymaps as well as ordinary functions.
+     Specify TYPE as `macro' if FUNCTION is really a macro.  Specify
+     TYPE as `keymap' if FUNCTION is really a keymap.  Various parts of
+     Emacs need to know this information without loading the real
+     definition.
+
+     An autoloaded keymap loads automatically during key lookup when a
+     prefix key's binding is the symbol FUNCTION.  Autoloading does not
+     occur for other kinds of access to the keymap.  In particular, it
+     does not happen when a Lisp program gets the keymap from the value
+     of a variable and calls `define-key'; not even if the variable
+     name is the same symbol FUNCTION.
+
+     If FUNCTION already has a non-void function definition that is not
+     an autoload object, `autoload' does nothing and returns `nil'.  If
+     the function cell of FUNCTION is void, or is already an autoload
+     object, then it is defined as an autoload object like this:
+
+          (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
+
+     For example,
+
+          (symbol-function 'run-prolog)
+               => (autoload "prolog" 169681 t nil)
+
+     In this case, `"prolog"' is the name of the file to load, 169681
+     refers to the documentation string in the `DOC' file (*note
+     Documentation Basics::), `t' means the function is interactive,
+     and `nil' that it is not a macro or a keymap.
+
+   The autoloaded file usually contains other definitions and may
+require or provide one or more features.  If the file is not completely
+loaded (due to an error in the evaluation of its contents), any function
+definitions or `provide' calls that occurred during the load are
+undone.  This is to ensure that the next attempt to call any function
+autoloading from this file will try again to load the file.  If not for
+this, then some of the functions in the file might appear defined, but
+they might fail to work properly for the lack of certain subroutines
+defined later in the file and not loaded successfully.
+
+   XEmacs as distributed comes with many autoloaded functions.  The
+calls to `autoload' are in the file `loaddefs.el'.  There is a
+convenient way of updating them automatically.
+
+   If the autoloaded file fails to define the desired Lisp function or
+macro, then an error is signaled with data `"Autoloading failed to
+define function FUNCTION-NAME"'.
+
+   A magic autoload comment looks like `;;;###autoload', on a line by
+itself, just before the real definition of the function in its
+autoloadable source file.  The command `M-x update-file-autoloads'
+writes a corresponding `autoload' call into `loaddefs.el'.  Building
+Emacs loads `loaddefs.el' and thus calls `autoload'.  `M-x
+update-directory-autoloads' is even more powerful; it updates autoloads
+for all files in the current directory.
+
+   The same magic comment can copy any kind of form into `loaddefs.el'.
+If the form following the magic comment is not a function definition,
+it is copied verbatim.  You can also use a magic comment to execute a
+form at build time _without_ executing it when the file itself is
+loaded.  To do this, write the form "on the same line" as the magic
+comment.  Since it is in a comment, it does nothing when you load the
+source file; but `update-file-autoloads' copies it to `loaddefs.el',
+where it is executed while building Emacs.
+
+   The following example shows how `doctor' is prepared for autoloading
+with a magic comment:
+
+     ;;;###autoload
+     (defun doctor ()
+       "Switch to *doctor* buffer and start giving psychotherapy."
+       (interactive)
+       (switch-to-buffer "*doctor*")
+       (doctor-mode))
+
+Here's what that produces in `loaddefs.el':
+
+     (autoload 'doctor "doctor"
+       "\
+     Switch to *doctor* buffer and start giving psychotherapy."
+       t)
+
+The backslash and newline immediately following the double-quote are a
+convention used only in the preloaded Lisp files such as `loaddefs.el';
+they tell `make-docfile' to put the documentation string in the `DOC'
+file.  *Note Building XEmacs::.
+
+
+File: lispref.info,  Node: Repeated Loading,  Next: Named Features,  Prev: Autoload,  Up: Loading
+
+Repeated Loading
+================
+
+   You may load one file more than once in an Emacs session.  For
+example, after you have rewritten and reinstalled a function definition
+by editing it in a buffer, you may wish to return to the original
+version; you can do this by reloading the file it came from.
+
+   When you load or reload files, bear in mind that the `load' and
+`load-library' functions automatically load a byte-compiled file rather
+than a non-compiled file of similar name.  If you rewrite a file that
+you intend to save and reinstall, remember to byte-compile it if
+necessary; otherwise you may find yourself inadvertently reloading the
+older, byte-compiled file instead of your newer, non-compiled file!
+
+   When writing the forms in a Lisp library file, keep in mind that the
+file might be loaded more than once.  For example, the choice of
+`defvar' vs. `defconst' for defining a variable depends on whether it
+is desirable to reinitialize the variable if the library is reloaded:
+`defconst' does so, and `defvar' does not.  (*Note Defining
+Variables::.)
+
+   The simplest way to add an element to an alist is like this:
+
+     (setq minor-mode-alist
+           (cons '(leif-mode " Leif") minor-mode-alist))
+
+But this would add multiple elements if the library is reloaded.  To
+avoid the problem, write this:
+
+     (or (assq 'leif-mode minor-mode-alist)
+         (setq minor-mode-alist
+               (cons '(leif-mode " Leif") minor-mode-alist)))
+
+   To add an element to a list just once, use `add-to-list' (*note
+Setting Variables::).
+
+   Occasionally you will want to test explicitly whether a library has
+already been loaded.  Here's one way to test, in a library, whether it
+has been loaded before:
+
+     (defvar foo-was-loaded)
+     
+     (if (not (boundp 'foo-was-loaded))
+         EXECUTE-FIRST-TIME-ONLY)
+     
+     (setq foo-was-loaded t)
+
+If the library uses `provide' to provide a named feature, you can use
+`featurep' to test whether the library has been loaded.  *Note Named
+Features::.
+
+
+File: lispref.info,  Node: Named Features,  Next: Unloading,  Prev: Repeated Loading,  Up: Loading
+
+Features
+========
+
+   `provide' and `require' are an alternative to `autoload' for loading
+files automatically.  They work in terms of named "features".
+Autoloading is triggered by calling a specific function, but a feature
+is loaded the first time another program asks for it by name.
+
+   A feature name is a symbol that stands for a collection of functions,
+variables, etc.  The file that defines them should "provide" the
+feature.  Another program that uses them may ensure they are defined by
+"requiring" the feature.  This loads the file of definitions if it
+hasn't been loaded already.
+
+   To require the presence of a feature, call `require' with the
+feature name as argument.  `require' looks in the global variable
+`features' to see whether the desired feature has been provided
+already.  If not, it loads the feature from the appropriate file.  This
+file should call `provide' at the top level to add the feature to
+`features'; if it fails to do so, `require' signals an error.
+
+   Features are normally named after the files that provide them, so
+that `require' need not be given the file name.
+
+   For example, in `emacs/lisp/prolog.el', the definition for
+`run-prolog' includes the following code:
+
+     (defun run-prolog ()
+       "Run an inferior Prolog process, input and output via buffer *prolog*."
+       (interactive)
+       (require 'comint)
+       (switch-to-buffer (make-comint "prolog" prolog-program-name))
+       (inferior-prolog-mode))
+
+The expression `(require 'comint)' loads the file `comint.el' if it has
+not yet been loaded.  This ensures that `make-comint' is defined.
+
+   The `comint.el' file contains the following top-level expression:
+
+     (provide 'comint)
+
+This adds `comint' to the global `features' list, so that `(require
+'comint)' will henceforth know that nothing needs to be done.
+
+   When `require' is used at top level in a file, it takes effect when
+you byte-compile that file (*note Byte Compilation::) as well as when
+you load it.  This is in case the required package contains macros that
+the byte compiler must know about.
+
+   Although top-level calls to `require' are evaluated during byte
+compilation, `provide' calls are not.  Therefore, you can ensure that a
+file of definitions is loaded before it is byte-compiled by including a
+`provide' followed by a `require' for the same feature, as in the
+following example.
+
+     (provide 'my-feature)  ; Ignored by byte compiler,
+                            ;   evaluated by `load'.
+     (require 'my-feature)  ; Evaluated by byte compiler.
+
+The compiler ignores the `provide', then processes the `require' by
+loading the file in question.  Loading the file does execute the
+`provide' call, so the subsequent `require' call does nothing while
+loading.
+
+ - Function: provide feature
+     This function announces that FEATURE is now loaded, or being
+     loaded, into the current XEmacs session.  This means that the
+     facilities associated with FEATURE are or will be available for
+     other Lisp programs.
+
+     The direct effect of calling `provide' is to add FEATURE to the
+     front of the list `features' if it is not already in the list.
+     The argument FEATURE must be a symbol.  `provide' returns FEATURE.
+
+          features
+               => (bar bish)
+          
+          (provide 'foo)
+               => foo
+          features
+               => (foo bar bish)
+
+     When a file is loaded to satisfy an autoload, and it stops due to
+     an error in the evaluating its contents, any function definitions
+     or `provide' calls that occurred during the load are undone.
+     *Note Autoload::.
+
+ - Function: require feature &optional filename
+     This function checks whether FEATURE is present in the current
+     XEmacs session (using `(featurep FEATURE)'; see below).  If it is
+     not, then `require' loads FILENAME with `load'.  If FILENAME is
+     not supplied, then the name of the symbol FEATURE is used as the
+     file name to load.
+
+     If loading the file fails to provide FEATURE, `require' signals an
+     error, `Required feature FEATURE was not provided'.
+
+ - Function: featurep fexp
+     This function returns `t' if feature FEXP is present in this
+     Emacs.  Use this to conditionalize execution of lisp code based on
+     the presence or absence of emacs or environment extensions.
+
+     FEXP can be a symbol, a number, or a list.
+
+     If FEXP is a symbol, it is looked up in the `features' variable,
+     and `t' is returned if it is found, `nil' otherwise.
+
+     If FEXP is a number, the function returns `t' if this Emacs has an
+     equal or greater number than FEXP, `nil' otherwise.  Note that
+     minor Emacs version is expected to be 2 decimal places wide, so
+     `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write
+     `(featurep 20.04)', unless you wish to match for XEmacs 20.40.
+
+     If FEXP is a list whose car is the symbol `and', the function
+     returns `t' if all the features in its cdr are present, `nil'
+     otherwise.
+
+     If FEXP is a list whose car is the symbol `or', the function
+     returns `t' if any the features in its cdr are present, `nil'
+     otherwise.
+
+     If FEXP is a list whose car is the symbol `not', the function
+     returns `t' if the feature is not present, `nil' otherwise.
+
+     Examples:
+
+          (featurep 'xemacs)
+               => ; t on XEmacs.
+          
+          (featurep '(and xemacs gnus))
+               => ; t on XEmacs with Gnus loaded.
+          
+          (featurep '(or tty-frames (and emacs 19.30)))
+               => ; t if this Emacs supports TTY frames.
+          
+          (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
+               => ; t on XEmacs 19.15 and later, or on
+                         ; FSF Emacs 19.34 and later.
+
+     *Please note:* The advanced arguments of this function (anything
+     other than a symbol) are not yet supported by FSF Emacs.  If you
+     feel they are useful for supporting multiple Emacs variants, lobby
+     Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
+
+ - Variable: features
+     The value of this variable is a list of symbols that are the
+     features loaded in the current XEmacs session.  Each symbol was
+     put in this list with a call to `provide'.  The order of the
+     elements in the `features' list is not significant.
+
+
+File: lispref.info,  Node: Unloading,  Next: Hooks for Loading,  Prev: Named Features,  Up: Loading
+
+Unloading
+=========
+
+   You can discard the functions and variables loaded by a library to
+reclaim memory for other Lisp objects.  To do this, use the function
+`unload-feature':
+
+ - Command: unload-feature feature &optional force
+     This command unloads the library that provided feature FEATURE.
+     It undefines all functions, macros, and variables defined in that
+     library with `defconst', `defvar', `defun', `defmacro',
+     `defsubst', `define-function' and `defalias'.  It then restores
+     any autoloads formerly associated with those symbols.  (Loading
+     saves these in the `autoload' property of the symbol.)
+
+     Ordinarily, `unload-feature' refuses to unload a library on which
+     other loaded libraries depend.  (A library A depends on library B
+     if A contains a `require' for B.)  If the optional argument FORCE
+     is non-`nil', dependencies are ignored and you can unload any
+     library.
+
+   The `unload-feature' function is written in Lisp; its actions are
+based on the variable `load-history'.
+
+ - Variable: load-history
+     This variable's value is an alist connecting library names with the
+     names of functions and variables they define, the features they
+     provide, and the features they require.
+
+     Each element is a list and describes one library.  The CAR of the
+     list is the name of the library, as a string.  The rest of the
+     list is composed of these kinds of objects:
+
+        * Symbols that were defined by this library.
+
+        * Lists of the form `(require . FEATURE)' indicating features
+          that were required.
+
+        * Lists of the form `(provide . FEATURE)' indicating features
+          that were provided.
+
+     The value of `load-history' may have one element whose CAR is
+     `nil'.  This element describes definitions made with `eval-buffer'
+     on a buffer that is not visiting a file.
+
+   The command `eval-region' updates `load-history', but does so by
+adding the symbols defined to the element for the file being visited,
+rather than replacing that element.
+
+
+File: lispref.info,  Node: Hooks for Loading,  Prev: Unloading,  Up: Loading
+
+Hooks for Loading
+=================
+
+ - Variable: after-load-alist
+     An alist of expressions to evaluate if and when particular
+     libraries are loaded.  Each element looks like this:
+
+          (FILENAME FORMS...)
+
+     When `load' is run and the file-name argument is FILENAME, the
+     FORMS in the corresponding element are executed at the end of
+     loading.
+
+     FILENAME must match exactly!  Normally FILENAME is the name of a
+     library, with no directory specified, since that is how `load' is
+     normally called.  An error in FORMS does not undo the load, but
+     does prevent execution of the rest of the FORMS.
+
+
+
+File: lispref.info,  Node: Byte Compilation,  Next: Debugging,  Prev: Loading,  Up: Top
+
+Byte Compilation
+****************
+
+   XEmacs Lisp has a "compiler" that translates functions written in
+Lisp into a special representation called "byte-code" that can be
+executed more efficiently.  The compiler replaces Lisp function
+definitions with byte-code.  When a byte-coded function is called, its
+definition is evaluated by the "byte-code interpreter".
+
+   Because the byte-compiled code is evaluated by the byte-code
+interpreter, instead of being executed directly by the machine's
+hardware (as true compiled code is), byte-code is completely
+transportable from machine to machine without recompilation.  It is not,
+however, as fast as true compiled code.
+
+   In general, any version of Emacs can run byte-compiled code produced
+by recent earlier versions of Emacs, but the reverse is not true.  In
+particular, if you compile a program with XEmacs 20, the compiled code
+may not run in earlier versions.
+
+   The first time a compiled-function object is executed, the byte-code
+instructions are validated and the byte-code is further optimized.  An
+`invalid-byte-code' error is signaled if the byte-code is invalid, for
+example if it contains invalid opcodes.  This usually means a bug in
+the byte compiler.
+
+   *Note Compilation Errors::, for how to investigate errors occurring
+in byte compilation.
+
+* Menu:
+
+* Speed of Byte-Code::          An example of speedup from byte compilation.
+* Compilation Functions::       Byte compilation functions.
+* Docs and Compilation::        Dynamic loading of documentation strings.
+* Dynamic Loading::             Dynamic loading of individual functions.
+* Eval During Compile::  	Code to be evaluated when you compile.
+* Compiled-Function Objects::	The data type used for byte-compiled functions.
+* Disassembly::                 Disassembling byte-code; how to read byte-code.
+* Different Behavior::          When compiled code gives different results.
+
+
+File: lispref.info,  Node: Speed of Byte-Code,  Next: Compilation Functions,  Up: Byte Compilation
+
+Performance of Byte-Compiled Code
+=================================
+
+   A byte-compiled function is not as efficient as a primitive function
+written in C, but runs much faster than the version written in Lisp.
+Here is an example:
+
+     (defun silly-loop (n)
+       "Return time before and after N iterations of a loop."
+       (let ((t1 (current-time-string)))
+         (while (> (setq n (1- n))
+                   0))
+         (list t1 (current-time-string))))
+     => silly-loop
+     
+     (silly-loop 5000000)
+     => ("Mon Sep 14 15:51:49 1998"
+         "Mon Sep 14 15:52:07 1998")  ; 18 seconds
+     
+     (byte-compile 'silly-loop)
+     => #<compiled-function
+     (n)
+     "...(23)"
+     [current-time-string t1 n 0]
+     2
+     "Return time before and after N iterations of a loop.">
+     
+     (silly-loop 5000000)
+     => ("Mon Sep 14 15:53:43 1998"
+         "Mon Sep 14 15:53:49 1998")  ; 6 seconds
+
+   In this example, the interpreted code required 18 seconds to run,
+whereas the byte-compiled code required 6 seconds.  These results are
+representative, but actual results will vary greatly.
+
+
+File: lispref.info,  Node: Compilation Functions,  Next: Docs and Compilation,  Prev: Speed of Byte-Code,  Up: Byte Compilation
+
+The Compilation Functions
+=========================
+
+   You can byte-compile an individual function or macro definition with
+the `byte-compile' function.  You can compile a whole file with
+`byte-compile-file', or several files with `byte-recompile-directory'
+or `batch-byte-compile'.
+
+   When you run the byte compiler, you may get warnings in a buffer
+called `*Compile-Log*'.  These report things in your program that
+suggest a problem but are not necessarily erroneous.
+
+   Be careful when byte-compiling code that uses macros.  Macro calls
+are expanded when they are compiled, so the macros must already be
+defined for proper compilation.  For more details, see *Note Compiling
+Macros::.
+
+   Normally, compiling a file does not evaluate the file's contents or
+load the file.  But it does execute any `require' calls at top level in
+the file.  One way to ensure that necessary macro definitions are
+available during compilation is to `require' the file that defines them
+(*note Named Features::).  To avoid loading the macro definition files
+when someone _runs_ the compiled program, write `eval-when-compile'
+around the `require' calls (*note Eval During Compile::).
+
+ - Function: byte-compile symbol
+     This function byte-compiles the function definition of SYMBOL,
+     replacing the previous definition with the compiled one.  The
+     function definition of SYMBOL must be the actual code for the
+     function; i.e., the compiler does not follow indirection to
+     another symbol.  `byte-compile' returns the new, compiled
+     definition of SYMBOL.
+
+     If SYMBOL's definition is a compiled-function object,
+     `byte-compile' does nothing and returns `nil'.  Lisp records only
+     one function definition for any symbol, and if that is already
+     compiled, non-compiled code is not available anywhere.  So there
+     is no way to "compile the same definition again."
+
+          (defun factorial (integer)
+            "Compute factorial of INTEGER."
+            (if (= 1 integer) 1
+              (* integer (factorial (1- integer)))))
+          => factorial
+          
+          (byte-compile 'factorial)
+          => #<compiled-function
+          (integer)
+          "...(21)"
+          [integer 1 factorial]
+          3
+          "Compute factorial of INTEGER.">
+
+     The result is a compiled-function object.  The string it contains
+     is the actual byte-code; each character in it is an instruction or
+     an operand of an instruction.  The vector contains all the
+     constants, variable names and function names used by the function,
+     except for certain primitives that are coded as special
+     instructions.
+
+ - Command: compile-defun &optional arg
+     This command reads the defun containing point, compiles it, and
+     evaluates the result.  If you use this on a defun that is actually
+     a function definition, the effect is to install a compiled version
+     of that function.
+
+     If ARG is non-`nil', the result is inserted in the current buffer
+     after the form; otherwise, it is printed in the minibuffer.
+
+ - Command: byte-compile-file filename &optional load
+     This function compiles a file of Lisp code named FILENAME into a
+     file of byte-code.  The output file's name is made by appending
+     `c' to the end of FILENAME.
+
+     If `load' is non-`nil', the file is loaded after having been
+     compiled.
+
+     Compilation works by reading the input file one form at a time.
+     If it is a definition of a function or macro, the compiled
+     function or macro definition is written out.  Other forms are
+     batched together, then each batch is compiled, and written so that
+     its compiled code will be executed when the file is read.  All
+     comments are discarded when the input file is read.
+
+     This command returns `t'.  When called interactively, it prompts
+     for the file name.
+
+          % ls -l push*
+          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+          
+          (byte-compile-file "~/emacs/push.el")
+               => t
+          
+          % ls -l push*
+          -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+          -rw-r--r--  1 lewis     638 Oct  8 20:25 push.elc
+
+ - Command: byte-recompile-directory directory &optional flag
+          norecursion force
+     This function recompiles every `.el' file in DIRECTORY that needs
+     recompilation.  A file needs recompilation if a `.elc' file exists
+     but is older than the `.el' file.
+
+     Files in subdirectories of DIRECTORY are also processed unless
+     optional argument NORECURSION is non-`nil'.
+
+     When a `.el' file has no corresponding `.elc' file, then FLAG says
+     what to do.  If it is `nil', these files are ignored.  If it is
+     non-`nil', the user is asked whether to compile each such file.
+
+     If the fourth optional argument FORCE is non-`nil', recompile
+     every `.el' file that already has a `.elc' file.
+
+     The return value of this command is unpredictable.
+
+ - Function: batch-byte-compile
+     This function runs `byte-compile-file' on files specified on the
+     command line.  This function must be used only in a batch
+     execution of Emacs, as it kills Emacs on completion.  An error in
+     one file does not prevent processing of subsequent files.  (The
+     file that gets the error will not, of course, produce any compiled
+     code.)
+
+          % xemacs -batch -f batch-byte-compile *.el
+
+ - Function: batch-byte-recompile-directory
+     This function is similar to `batch-byte-compile' but runs the
+     command `byte-recompile-directory' on the files remaining on the
+     command line.
+
+ - Variable: byte-recompile-directory-ignore-errors-p
+     If non-`nil', this specifies that `byte-recompile-directory' will
+     continue compiling even when an error occurs in a file.  This is
+     normally `nil', but is bound to `t' by
+     `batch-byte-recompile-directory'.
+
+ - Function: byte-code instructions constants stack-depth
+     This function actually interprets byte-code.  Don't call this
+     function yourself.  Only the byte compiler knows how to generate
+     valid calls to this function.
+
+     In newer Emacs versions (19 and up), byte code is usually executed
+     as part of a compiled-function object, and only rarely due to an
+     explicit call to `byte-code'.  A byte-compiled function was once
+     actually defined with a body that calls `byte-code', but in recent
+     versions of Emacs `byte-code' is only used to run isolated
+     fragments of lisp code without an associated argument list.
+
+
+File: lispref.info,  Node: Docs and Compilation,  Next: Dynamic Loading,  Prev: Compilation Functions,  Up: Byte Compilation
+
+Documentation Strings and Compilation
+=====================================
+
+   Functions and variables loaded from a byte-compiled file access their
+documentation strings dynamically from the file whenever needed.  This
+saves space within Emacs, and makes loading faster because the
+documentation strings themselves need not be processed while loading the
+file.  Actual access to the documentation strings becomes slower as a
+result, but normally not enough to bother users.
+
+   Dynamic access to documentation strings does have drawbacks:
+
+   * If you delete or move the compiled file after loading it, Emacs
+     can no longer access the documentation strings for the functions
+     and variables in the file.
+
+   * If you alter the compiled file (such as by compiling a new
+     version), then further access to documentation strings in this
+     file will give nonsense results.
+
+   If your site installs Emacs following the usual procedures, these
+problems will never normally occur.  Installing a new version uses a new
+directory with a different name; as long as the old version remains
+installed, its files will remain unmodified in the places where they are
+expected to be.
+
+   However, if you have built Emacs yourself and use it from the
+directory where you built it, you will experience this problem
+occasionally if you edit and recompile Lisp files.  When it happens, you
+can cure the problem by reloading the file after recompiling it.
+
+   Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs
+19.28 do not support the dynamic docstrings feature, and so will not be
+able to load bytecode created by more recent Emacs versions.  You can
+turn off the dynamic docstring feature by setting
+`byte-compile-dynamic-docstrings' to `nil'.  Once this is done, you can
+compile files that will load into older Emacs versions.  You can do
+this globally, or for one source file by specifying a file-local
+binding for the variable.  Here's one way to do that:
+
+     -*-byte-compile-dynamic-docstrings: nil;-*-
+
+ - Variable: byte-compile-dynamic-docstrings
+     If this is non-`nil', the byte compiler generates compiled files
+     that are set up for dynamic loading of documentation strings.
+
+   The dynamic documentation string feature writes compiled files that
+use a special Lisp reader construct, `#@COUNT'.  This construct skips
+the next COUNT characters.  It also uses the `#$' construct, which
+stands for "the name of this file, as a string."  It is best not to use
+these constructs in Lisp source files.
+
+
+File: lispref.info,  Node: Dynamic Loading,  Next: Eval During Compile,  Prev: Docs and Compilation,  Up: Byte Compilation
+
+Dynamic Loading of Individual Functions
+=======================================
+
+   When you compile a file, you can optionally enable the "dynamic
+function loading" feature (also known as "lazy loading").  With dynamic
+function loading, loading the file doesn't fully read the function
+definitions in the file.  Instead, each function definition contains a
+place-holder which refers to the file.  The first time each function is
+called, it reads the full definition from the file, to replace the
+place-holder.
+
+   The advantage of dynamic function loading is that loading the file
+becomes much faster.  This is a good thing for a file which contains
+many separate commands, provided that using one of them does not imply
+you will soon (or ever) use the rest.  A specialized mode which provides
+many keyboard commands often has that usage pattern: a user may invoke
+the mode, but use only a few of the commands it provides.
+
+   The dynamic loading feature has certain disadvantages:
+
+   * If you delete or move the compiled file after loading it, Emacs
+     can no longer load the remaining function definitions not already
+     loaded.
+
+   * If you alter the compiled file (such as by compiling a new
+     version), then trying to load any function not already loaded will
+     get nonsense results.
+
+   If you compile a new version of the file, the best thing to do is
+immediately load the new compiled file.  That will prevent any future
+problems.
+
+   The byte compiler uses the dynamic function loading feature if the
+variable `byte-compile-dynamic' is non-`nil' at compilation time.  Do
+not set this variable globally, since dynamic loading is desirable only
+for certain files.  Instead, enable the feature for specific source
+files with file-local variable bindings, like this:
+
+     -*-byte-compile-dynamic: t;-*-
+
+ - Variable: byte-compile-dynamic
+     If this is non-`nil', the byte compiler generates compiled files
+     that are set up for dynamic function loading.
+
+ - Function: fetch-bytecode function
+     This immediately finishes loading the definition of FUNCTION from
+     its byte-compiled file, if it is not fully loaded already.  The
+     argument FUNCTION may be a compiled-function object or a function
+     name.
+
+
+File: lispref.info,  Node: Eval During Compile,  Next: Compiled-Function Objects,  Prev: Dynamic Loading,  Up: Byte Compilation
+
+Evaluation During Compilation
+=============================
+
+   These features permit you to write code to be evaluated during
+compilation of a program.
+
+ - Special Form: eval-and-compile body
+     This form marks BODY to be evaluated both when you compile the
+     containing code and when you run it (whether compiled or not).
+
+     You can get a similar result by putting BODY in a separate file
+     and referring to that file with `require'.  Using `require' is
+     preferable if there is a substantial amount of code to be executed
+     in this way.
+
+ - Special Form: eval-when-compile body
+     This form marks BODY to be evaluated at compile time and not when
+     the compiled program is loaded.  The result of evaluation by the
+     compiler becomes a constant which appears in the compiled program.
+     When the program is interpreted, not compiled at all, BODY is
+     evaluated normally.
+
+     At top level, this is analogous to the Common Lisp idiom
+     `(eval-when (compile eval) ...)'.  Elsewhere, the Common Lisp `#.'
+     reader macro (but not when interpreting) is closer to what
+     `eval-when-compile' does.
+
+
+File: lispref.info,  Node: Compiled-Function Objects,  Next: Disassembly,  Prev: Eval During Compile,  Up: Byte Compilation
+
+Compiled-Function Objects
+=========================
+
+   Byte-compiled functions have a special data type: they are
+"compiled-function objects". The evaluator handles this data type
+specially when it appears as a function to be called.
+
+   The printed representation for a compiled-function object normally
+begins with `#<compiled-function' and ends with `>'.  However, if the
+variable `print-readably' is non-`nil', the object is printed beginning
+with `#[' and ending with `]'.  This representation can be read
+directly by the Lisp reader, and is used in byte-compiled files (those
+ending in `.elc').
+
+   In Emacs version 18, there was no compiled-function object data type;
+compiled functions used the function `byte-code' to run the byte code.
+
+   A compiled-function object has a number of different attributes.
+They are:
+
+ARGLIST
+     The list of argument symbols.
+
+INSTRUCTIONS
+     The string containing the byte-code instructions.
+
+CONSTANTS
+     The vector of Lisp objects referenced by the byte code.  These
+     include symbols used as function names and variable names.
+
+STACK-DEPTH
+     The maximum stack size this function needs.
+
+DOC-STRING
+     The documentation string (if any); otherwise, `nil'.  The value may
+     be a number or a list, in case the documentation string is stored
+     in a file.  Use the function `documentation' to get the real
+     documentation string (*note Accessing Documentation::).
+
+INTERACTIVE
+     The interactive spec (if any).  This can be a string or a Lisp
+     expression.  It is `nil' for a function that isn't interactive.
+
+DOMAIN
+     The domain (if any).  This is only meaningful if I18N3
+     (message-translation) support was compiled into XEmacs.  This is a
+     string defining which domain to find the translation for the
+     documentation string and interactive prompt.  *Note Domain
+     Specification::.
+
+   Here's an example of a compiled-function object, in printed
+representation.  It is the definition of the command `backward-sexp'.
+
+     (symbol-function 'backward-sexp)
+     => #<compiled-function
+     (&optional arg)
+     "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
+
+   The primitive way to create a compiled-function object is with
+`make-byte-code':
+
+ - Function: make-byte-code arglist instructions constants stack-depth
+          &optional doc-string interactive
+     This function constructs and returns a compiled-function object
+     with the specified attributes.
+
+     _Please note:_ Unlike all other Emacs-lisp functions, calling this
+     with five arguments is _not_ the same as calling it with six
+     arguments, the last of which is `nil'.  If the INTERACTIVE arg is
+     specified as `nil', then that means that this function was defined
+     with `(interactive)'.  If the arg is not specified, then that means
+     the function is not interactive.  This is terrible behavior which
+     is retained for compatibility with old `.elc' files which expected
+     these semantics.
+
+   You should not try to come up with the elements for a
+compiled-function object yourself, because if they are inconsistent,
+XEmacs may crash when you call the function.  Always leave it to the
+byte compiler to create these objects; it makes the elements consistent
+(we hope).
+
+   The following primitives are provided for accessing the elements of
+a compiled-function object.
+
+ - Function: compiled-function-arglist function
+     This function returns the argument list of compiled-function object
+     FUNCTION.
+
+ - Function: compiled-function-instructions function
+     This function returns a string describing the byte-code
+     instructions of compiled-function object FUNCTION.
+
+ - Function: compiled-function-constants function
+     This function returns the vector of Lisp objects referenced by
+     compiled-function object FUNCTION.
+
+ - Function: compiled-function-stack-depth function
+     This function returns the maximum stack size needed by
+     compiled-function object FUNCTION.
+
+ - Function: compiled-function-doc-string function
+     This function returns the doc string of compiled-function object
+     FUNCTION, if available.
+
+ - Function: compiled-function-interactive function
+     This function returns the interactive spec of compiled-function
+     object FUNCTION, if any.  The return value is `nil' or a
+     two-element list, the first element of which is the symbol
+     `interactive' and the second element is the interactive spec (a
+     string or Lisp form).
+
+ - Function: compiled-function-domain function
+     This function returns the domain of compiled-function object
+     FUNCTION, if any.  The result will be a string or `nil'.  *Note
+     Domain Specification::.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-13'
Index: ././info/lispref.info-13
--- ././info/lispref.info-13	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-13	Thu May 17 23:26:54 2001
@@ -0,0 +1,1149 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Disassembly,  Next: Different Behavior,  Prev: Compiled-Function Objects,  Up: Byte Compilation
+
+Disassembled Byte-Code
+======================
+
+   People do not write byte-code; that job is left to the byte compiler.
+But we provide a disassembler to satisfy a cat-like curiosity.  The
+disassembler converts the byte-compiled code into humanly readable form.
+
+   The byte-code interpreter is implemented as a simple stack machine.
+It pushes values onto a stack of its own, then pops them off to use them
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
+
+   In addition to the stack, byte-code functions can use, bind, and set
+ordinary Lisp variables, by transferring values between variables and
+the stack.
+
+ - Command: disassemble object &optional stream
+     This function prints the disassembled code for OBJECT.  If STREAM
+     is supplied, then output goes there.  Otherwise, the disassembled
+     code is printed to the stream `standard-output'.  The argument
+     OBJECT can be a function name or a lambda expression.
+
+     As a special exception, if this function is used interactively, it
+     outputs to a buffer named `*Disassemble*'.
+
+   Here are two examples of using the `disassemble' function.  We have
+added explanatory comments to help you relate the byte-code to the Lisp
+source; these do not appear in the output of `disassemble'.
+
+     (defun factorial (integer)
+       "Compute factorial of an integer."
+       (if (= 1 integer) 1
+         (* integer (factorial (1- integer)))))
+          => factorial
+     
+     (factorial 4)
+          => 24
+     
+     (disassemble 'factorial)
+          -| byte-code for factorial:
+      doc: Compute factorial of an integer.
+      args: (integer)
+     
+     0   varref   integer        ; Get value of `integer'
+                                 ;   from the environment
+                                 ;   and push the value
+                                 ;   onto the stack.
+     
+     1   constant 1              ; Push 1 onto stack.
+     
+     2   eqlsign                 ; Pop top two values off stack,
+                                 ;   compare them,
+                                 ;   and push result onto stack.
+     
+     3   goto-if-nil 1           ; Pop and test top of stack;
+                                 ;   if `nil',
+                                 ;   go to label 1 (which is also byte 7),
+                                 ;   else continue.
+     
+     5   constant 1              ; Push 1 onto top of stack.
+     
+     6   return                  ; Return the top element
+                                 ;   of the stack.
+     
+     7:1 varref   integer        ; Push value of `integer' onto stack.
+     
+     8   constant factorial      ; Push `factorial' onto stack.
+     
+     9   varref   integer        ; Push value of `integer' onto stack.
+     
+     10  sub1                    ; Pop `integer', decrement value,
+                                 ;   push new value onto stack.
+     
+                                 ; Stack now contains:
+                                 ;   - decremented value of `integer'
+                                 ;   - `factorial'
+                                 ;   - value of `integer'
+     
+     15  call     1              ; Call function `factorial' using
+                                 ;   the first (i.e., the top) element
+                                 ;   of the stack as the argument;
+                                 ;   push returned value onto stack.
+     
+                                 ; Stack now contains:
+                                 ;   - result of recursive
+                                 ;        call to `factorial'
+                                 ;   - value of `integer'
+     
+     12  mult                    ; Pop top two values off the stack,
+                                 ;   multiply them,
+                                 ;   pushing the result onto the stack.
+     
+     13  return                  ; Return the top element
+                                 ;   of the stack.
+          => nil
+
+   The `silly-loop' function is somewhat more complex:
+
+     (defun silly-loop (n)
+       "Return time before and after N iterations of a loop."
+       (let ((t1 (current-time-string)))
+         (while (> (setq n (1- n))
+                   0))
+         (list t1 (current-time-string))))
+          => silly-loop
+     
+     (disassemble 'silly-loop)
+          -| byte-code for silly-loop:
+      doc: Return time before and after N iterations of a loop.
+      args: (n)
+     
+     0   constant current-time-string  ; Push
+                                       ;   `current-time-string'
+                                       ;   onto top of stack.
+     
+     1   call     0              ; Call `current-time-string'
+                                 ;    with no argument,
+                                 ;    pushing result onto stack.
+     
+     2   varbind  t1             ; Pop stack and bind `t1'
+                                 ;   to popped value.
+     
+     3:1 varref   n              ; Get value of `n' from
+                                 ;   the environment and push
+                                 ;   the value onto the stack.
+     
+     4   sub1                    ; Subtract 1 from top of stack.
+     
+     5   dup                     ; Duplicate the top of the stack;
+                                 ;   i.e., copy the top of
+                                 ;   the stack and push the
+                                 ;   copy onto the stack.
+     
+     6   varset   n              ; Pop the top of the stack,
+                                 ;   and set `n' to the value.
+     
+                                 ; In effect, the sequence `dup varset'
+                                 ;   copies the top of the stack
+                                 ;   into the value of `n'
+                                 ;   without popping it.
+     
+     7   constant 0              ; Push 0 onto stack.
+     
+     8   gtr                     ; Pop top two values off stack,
+                                 ;   test if N is greater than 0
+                                 ;   and push result onto stack.
+     
+     9   goto-if-not-nil 1       ; Goto label 1 (byte 3) if `n' <= 0
+                                 ;   (this exits the while loop).
+                                 ;   else pop top of stack
+                                 ;   and continue
+     
+     11  varref   t1             ; Push value of `t1' onto stack.
+     
+     12  constant current-time-string  ; Push
+                                       ;   `current-time-string'
+                                       ;   onto top of stack.
+     
+     13  call     0              ; Call `current-time-string' again.
+     
+     14  unbind   1              ; Unbind `t1' in local environment.
+     
+     15  list2                   ; Pop top two elements off stack,
+                                 ;   create a list of them,
+                                 ;   and push list onto stack.
+     
+     16  return                  ; Return the top element of the stack.
+     
+          => nil
+
+
+File: lispref.info,  Node: Different Behavior,  Prev: Disassembly,  Up: Byte Compilation
+
+Different Behavior
+==================
+
+   The intent is that compiled byte-code and the corresponding code
+executed by the Lisp interpreter produce identical results.  However,
+there are some circumstances where the results will differ.
+
+   * Arithmetic operations may be rearranged for efficiency or
+     compile-time evaluation.  When floating point numbers are
+     involved, this may produce different values or an overflow.
+
+   * Some arithmetic operations may be optimized away.  For example, the
+     expression `(+ x)' may be optimized to simply `x'.  If the value
+     of `x' is a marker, then the value will be a marker instead of an
+     integer.  If the value of `x' is a cons cell, then the interpreter
+     will issue an error, while the bytecode will not.
+
+     If you're trying to use `(+ OBJECT 0)' to convert OBJECT to
+     integer, consider using an explicit conversion function, which is
+     clearer and guaranteed to work.  Instead of `(+ MARKER 0)', use
+     `(marker-position MARKER)'.  Instead of `(+ CHAR 0)', use
+     `(char-int CHAR)'.
+
+   For maximal equivalence between interpreted and compiled code, the
+variables `byte-compile-delete-errors' and `byte-compile-optimize' can
+be set to `nil', but this is not recommended.
+
+
+File: lispref.info,  Node: Debugging,  Next: Read and Print,  Prev: Byte Compilation,  Up: Top
+
+Debugging Lisp Programs
+***********************
+
+   There are three ways to investigate a problem in an XEmacs Lisp
+program, depending on what you are doing with the program when the
+problem appears.
+
+   * If the problem occurs when you run the program, you can use a Lisp
+     debugger (either the default debugger or Edebug) to investigate
+     what is happening during execution.
+
+   * If the problem is syntactic, so that Lisp cannot even read the
+     program, you can use the XEmacs facilities for editing Lisp to
+     localize it.
+
+   * If the problem occurs when trying to compile the program with the
+     byte compiler, you need to know how to examine the compiler's
+     input buffer.
+
+* Menu:
+
+* Debugger::            How the XEmacs Lisp debugger is implemented.
+* Syntax Errors::       How to find syntax errors.
+* Compilation Errors::  How to find errors that show up in byte compilation.
+* Edebug::		A source-level XEmacs Lisp debugger.
+
+   Another useful debugging tool is the dribble file.  When a dribble
+file is open, XEmacs copies all keyboard input characters to that file.
+Afterward, you can examine the file to find out what input was used.
+*Note Terminal Input::.
+
+   For debugging problems in terminal descriptions, the
+`open-termscript' function can be useful.  *Note Terminal Output::.
+
+
+File: lispref.info,  Node: Debugger,  Next: Syntax Errors,  Up: Debugging
+
+The Lisp Debugger
+=================
+
+   The "Lisp debugger" provides the ability to suspend evaluation of a
+form.  While evaluation is suspended (a state that is commonly known as
+a "break"), you may examine the run time stack, examine the values of
+local or global variables, or change those values.  Since a break is a
+recursive edit, all the usual editing facilities of XEmacs are
+available; you can even run programs that will enter the debugger
+recursively.  *Note Recursive Editing::.
+
+* Menu:
+
+* Error Debugging::       Entering the debugger when an error happens.
+* Infinite Loops::	  Stopping and debugging a program that doesn't exit.
+* Function Debugging::    Entering it when a certain function is called.
+* Explicit Debug::        Entering it at a certain point in the program.
+* Using Debugger::        What the debugger does; what you see while in it.
+* Debugger Commands::     Commands used while in the debugger.
+* Invoking the Debugger:: How to call the function `debug'.
+* Internals of Debugger:: Subroutines of the debugger, and global variables.
+
+
+File: lispref.info,  Node: Error Debugging,  Next: Infinite Loops,  Up: Debugger
+
+Entering the Debugger on an Error
+---------------------------------
+
+   The most important time to enter the debugger is when a Lisp error
+happens.  This allows you to investigate the immediate causes of the
+error.
+
+   However, entry to the debugger is not a normal consequence of an
+error.  Many commands frequently get Lisp errors when invoked in
+inappropriate contexts (such as `C-f' at the end of the buffer) and
+during ordinary editing it would be very unpleasant to enter the
+debugger each time this happens.  If you want errors to enter the
+debugger, set the variable `debug-on-error' to non-`nil'.
+
+ - User Option: debug-on-error
+     This variable determines whether the debugger is called when an
+     error is signaled and not handled.  If `debug-on-error' is `t', all
+     errors call the debugger.  If it is `nil', none call the debugger.
+
+     The value can also be a list of error conditions that should call
+     the debugger.  For example, if you set it to the list
+     `(void-variable)', then only errors about a variable that has no
+     value invoke the debugger.
+
+     When this variable is non-`nil', Emacs does not catch errors that
+     happen in process filter functions and sentinels.  Therefore, these
+     errors also can invoke the debugger.  *Note Processes::.
+
+ - User Option: debug-on-signal
+     This variable is similar to `debug-on-error' but breaks whenever
+     an error is signalled, regardless of whether it would be handled.
+
+ - User Option: debug-ignored-errors
+     This variable specifies certain kinds of errors that should not
+     enter the debugger.  Its value is a list of error condition
+     symbols and/or regular expressions.  If the error has any of those
+     condition symbols, or if the error message matches any of the
+     regular expressions, then that error does not enter the debugger,
+     regardless of the value of `debug-on-error'.
+
+     The normal value of this variable lists several errors that happen
+     often during editing but rarely result from bugs in Lisp programs.
+
+   To debug an error that happens during loading of the `.emacs' file,
+use the option `-debug-init', which binds `debug-on-error' to `t' while
+`.emacs' is loaded and inhibits use of `condition-case' to catch init
+file errors.
+
+   If your `.emacs' file sets `debug-on-error', the effect may not last
+past the end of loading `.emacs'.  (This is an undesirable byproduct of
+the code that implements the `-debug-init' command line option.)  The
+best way to make `.emacs' set `debug-on-error' permanently is with
+`after-init-hook', like this:
+
+     (add-hook 'after-init-hook
+               '(lambda () (setq debug-on-error t)))
+
+
+File: lispref.info,  Node: Infinite Loops,  Next: Function Debugging,  Prev: Error Debugging,  Up: Debugger
+
+Debugging Infinite Loops
+------------------------
+
+   When a program loops infinitely and fails to return, your first
+problem is to stop the loop.  On most operating systems, you can do this
+with `C-g', which causes quit.
+
+   Ordinary quitting gives no information about why the program was
+looping.  To get more information, you can set the variable
+`debug-on-quit' to non-`nil'.  Quitting with `C-g' is not considered an
+error, and `debug-on-error' has no effect on the handling of `C-g'.
+Likewise, `debug-on-quit' has no effect on errors.
+
+   Once you have the debugger running in the middle of the infinite
+loop, you can proceed from the debugger using the stepping commands.
+If you step through the entire loop, you will probably get enough
+information to solve the problem.
+
+ - User Option: debug-on-quit
+     This variable determines whether the debugger is called when `quit'
+     is signaled and not handled.  If `debug-on-quit' is non-`nil',
+     then the debugger is called whenever you quit (that is, type
+     `C-g').  If `debug-on-quit' is `nil', then the debugger is not
+     called when you quit.  *Note Quitting::.
+
+
+File: lispref.info,  Node: Function Debugging,  Next: Explicit Debug,  Prev: Infinite Loops,  Up: Debugger
+
+Entering the Debugger on a Function Call
+----------------------------------------
+
+   To investigate a problem that happens in the middle of a program, one
+useful technique is to enter the debugger whenever a certain function is
+called.  You can do this to the function in which the problem occurs,
+and then step through the function, or you can do this to a function
+called shortly before the problem, step quickly over the call to that
+function, and then step through its caller.
+
+ - Command: debug-on-entry function-name
+     This function requests FUNCTION-NAME to invoke the debugger each
+     time it is called.  It works by inserting the form `(debug
+     'debug)' into the function definition as the first form.
+
+     Any function defined as Lisp code may be set to break on entry,
+     regardless of whether it is interpreted code or compiled code.  If
+     the function is a command, it will enter the debugger when called
+     from Lisp and when called interactively (after the reading of the
+     arguments).  You can't debug primitive functions (i.e., those
+     written in C) this way.
+
+     When `debug-on-entry' is called interactively, it prompts for
+     FUNCTION-NAME in the minibuffer.
+
+     If the function is already set up to invoke the debugger on entry,
+     `debug-on-entry' does nothing.
+
+     *Please note:* if you redefine a function after using
+     `debug-on-entry' on it, the code to enter the debugger is lost.
+
+     `debug-on-entry' returns FUNCTION-NAME.
+
+          (defun fact (n)
+            (if (zerop n) 1
+                (* n (fact (1- n)))))
+               => fact
+          (debug-on-entry 'fact)
+               => fact
+          (fact 3)
+          
+          ------ Buffer: *Backtrace* ------
+          Entering:
+          * fact(3)
+            eval-region(4870 4878 t)
+            byte-code("...")
+            eval-last-sexp(nil)
+            (let ...)
+            eval-insert-last-sexp(nil)
+          * call-interactively(eval-insert-last-sexp)
+          ------ Buffer: *Backtrace* ------
+          
+          (symbol-function 'fact)
+               => (lambda (n)
+                    (debug (quote debug))
+                    (if (zerop n) 1 (* n (fact (1- n)))))
+
+ - Command: cancel-debug-on-entry &optional function-name
+     This function undoes the effect of `debug-on-entry' on
+     FUNCTION-NAME.  When called interactively, it prompts for
+     FUNCTION-NAME in the minibuffer.  If FUNCTION-NAME is `nil' or the
+     empty string, it cancels debugging for all functions.
+
+     If `cancel-debug-on-entry' is called more than once on the same
+     function, the second call does nothing.  `cancel-debug-on-entry'
+     returns FUNCTION-NAME.
+
+
+File: lispref.info,  Node: Explicit Debug,  Next: Using Debugger,  Prev: Function Debugging,  Up: Debugger
+
+Explicit Entry to the Debugger
+------------------------------
+
+   You can cause the debugger to be called at a certain point in your
+program by writing the expression `(debug)' at that point.  To do this,
+visit the source file, insert the text `(debug)' at the proper place,
+and type `C-M-x'.  Be sure to undo this insertion before you save the
+file!
+
+   The place where you insert `(debug)' must be a place where an
+additional form can be evaluated and its value ignored.  (If the value
+of `(debug)' isn't ignored, it will alter the execution of the
+program!)  The most common suitable places are inside a `progn' or an
+implicit `progn' (*note Sequencing::).
+
+
+File: lispref.info,  Node: Using Debugger,  Next: Debugger Commands,  Prev: Explicit Debug,  Up: Debugger
+
+Using the Debugger
+------------------
+
+   When the debugger is entered, it displays the previously selected
+buffer in one window and a buffer named `*Backtrace*' in another
+window.  The backtrace buffer contains one line for each level of Lisp
+function execution currently going on.  At the beginning of this buffer
+is a message describing the reason that the debugger was invoked (such
+as the error message and associated data, if it was invoked due to an
+error).
+
+   The backtrace buffer is read-only and uses a special major mode,
+Debugger mode, in which letters are defined as debugger commands.  The
+usual XEmacs editing commands are available; thus, you can switch
+windows to examine the buffer that was being edited at the time of the
+error, switch buffers, visit files, or do any other sort of editing.
+However, the debugger is a recursive editing level (*note Recursive
+Editing::) and it is wise to go back to the backtrace buffer and exit
+the debugger (with the `q' command) when you are finished with it.
+Exiting the debugger gets out of the recursive edit and kills the
+backtrace buffer.
+
+   The backtrace buffer shows you the functions that are executing and
+their argument values.  It also allows you to specify a stack frame by
+moving point to the line describing that frame.  (A stack frame is the
+place where the Lisp interpreter records information about a particular
+invocation of a function.)  The frame whose line point is on is
+considered the "current frame".  Some of the debugger commands operate
+on the current frame.
+
+   The debugger itself must be run byte-compiled, since it makes
+assumptions about how many stack frames are used for the debugger
+itself.  These assumptions are false if the debugger is running
+interpreted.
+
+
+File: lispref.info,  Node: Debugger Commands,  Next: Invoking the Debugger,  Prev: Using Debugger,  Up: Debugger
+
+Debugger Commands
+-----------------
+
+   Inside the debugger (in Debugger mode), these special commands are
+available in addition to the usual cursor motion commands.  (Keep in
+mind that all the usual facilities of XEmacs, such as switching windows
+or buffers, are still available.)
+
+   The most important use of debugger commands is for stepping through
+code, so that you can see how control flows.  The debugger can step
+through the control structures of an interpreted function, but cannot do
+so in a byte-compiled function.  If you would like to step through a
+byte-compiled function, replace it with an interpreted definition of the
+same function.  (To do this, visit the source file for the function and
+type `C-M-x' on its definition.)
+
+   Here is a list of Debugger mode commands:
+
+`c'
+     Exit the debugger and continue execution.  This resumes execution
+     of the program as if the debugger had never been entered (aside
+     from the effect of any variables or data structures you may have
+     changed while inside the debugger).
+
+     Continuing when an error or quit was signalled will cause the
+     normal action of the signalling to take place.  If you do not want
+     this to happen, but instead want the program execution to continue
+     as if the call to `signal' did not occur, use the `r' command.
+
+`d'
+     Continue execution, but enter the debugger the next time any Lisp
+     function is called.  This allows you to step through the
+     subexpressions of an expression, seeing what values the
+     subexpressions compute, and what else they do.
+
+     The stack frame made for the function call which enters the
+     debugger in this way will be flagged automatically so that the
+     debugger will be called again when the frame is exited.  You can
+     use the `u' command to cancel this flag.
+
+`b'
+     Flag the current frame so that the debugger will be entered when
+     the frame is exited.  Frames flagged in this way are marked with
+     stars in the backtrace buffer.
+
+`u'
+     Don't enter the debugger when the current frame is exited.  This
+     cancels a `b' command on that frame.
+
+`e'
+     Read a Lisp expression in the minibuffer, evaluate it, and print
+     the value in the echo area.  The debugger alters certain important
+     variables, and the current buffer, as part of its operation; `e'
+     temporarily restores their outside-the-debugger values so you can
+     examine them.  This makes the debugger more transparent.  By
+     contrast, `M-:' does nothing special in the debugger; it shows you
+     the variable values within the debugger.
+
+`q'
+     Terminate the program being debugged; return to top-level XEmacs
+     command execution.
+
+     If the debugger was entered due to a `C-g' but you really want to
+     quit, and not debug, use the `q' command.
+
+`r'
+     Return a value from the debugger.  The value is computed by
+     reading an expression with the minibuffer and evaluating it.
+
+     The `r' command is useful when the debugger was invoked due to exit
+     from a Lisp call frame (as requested with `b'); then the value
+     specified in the `r' command is used as the value of that frame.
+     It is also useful if you call `debug' and use its return value.
+
+     If the debugger was entered at the beginning of a function call,
+     `r' has the same effect as `c', and the specified return value
+     does not matter.
+
+     If the debugger was entered through a call to `signal' (i.e. as a
+     result of an error or quit), then returning a value will cause the
+     call to `signal' itself to return, rather than throwing to
+     top-level or invoking a handler, as is normal.  This allows you to
+     correct an error (e.g. the type of an argument was wrong) or
+     continue from a `debug-on-quit' as if it never happened.
+
+     Note that some errors (e.g. any error signalled using the `error'
+     function, and many errors signalled from a primitive function) are
+     not continuable.  If you return a value from them and continue
+     execution, then the error will immediately be signalled again.
+     Other errors (e.g. wrong-type-argument errors) will be continually
+     resignalled until the problem is corrected.
+
+
+File: lispref.info,  Node: Invoking the Debugger,  Next: Internals of Debugger,  Prev: Debugger Commands,  Up: Debugger
+
+Invoking the Debugger
+---------------------
+
+   Here we describe fully the function used to invoke the debugger.
+
+ - Function: debug &rest debugger-args
+     This function enters the debugger.  It switches buffers to a buffer
+     named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
+     recursive entry to the debugger, etc.), and fills it with
+     information about the stack of Lisp function calls.  It then
+     enters a recursive edit, showing the backtrace buffer in Debugger
+     mode.
+
+     The Debugger mode `c' and `r' commands exit the recursive edit;
+     then `debug' switches back to the previous buffer and returns to
+     whatever called `debug'.  This is the only way the function
+     `debug' can return to its caller.
+
+     If the first of the DEBUGGER-ARGS passed to `debug' is `nil' (or
+     if it is not one of the special values in the table below), then
+     `debug' displays the rest of its arguments at the top of the
+     `*Backtrace*' buffer.  This mechanism is used to display a message
+     to the user.
+
+     However, if the first argument passed to `debug' is one of the
+     following special values, then it has special significance.
+     Normally, these values are passed to `debug' only by the internals
+     of XEmacs and the debugger, and not by programmers calling `debug'.
+
+     The special values are:
+
+    `lambda'
+          A first argument of `lambda' means `debug' was called because
+          of entry to a function when `debug-on-next-call' was
+          non-`nil'.  The debugger displays `Entering:' as a line of
+          text at the top of the buffer.
+
+    `debug'
+          `debug' as first argument indicates a call to `debug' because
+          of entry to a function that was set to debug on entry.  The
+          debugger displays `Entering:', just as in the `lambda' case.
+          It also marks the stack frame for that function so that it
+          will invoke the debugger when exited.
+
+    `t'
+          When the first argument is `t', this indicates a call to
+          `debug' due to evaluation of a list form when
+          `debug-on-next-call' is non-`nil'.  The debugger displays the
+          following as the top line in the buffer:
+
+               Beginning evaluation of function call form:
+
+    `exit'
+          When the first argument is `exit', it indicates the exit of a
+          stack frame previously marked to invoke the debugger on exit.
+          The second argument given to `debug' in this case is the
+          value being returned from the frame.  The debugger displays
+          `Return value:' on the top line of the buffer, followed by
+          the value being returned.
+
+    `error'
+          When the first argument is `error', the debugger indicates
+          that it is being entered because an error or `quit' was
+          signaled and not handled, by displaying `Signaling:' followed
+          by the error signaled and any arguments to `signal'.  For
+          example,
+
+               (let ((debug-on-error t))
+                 (/ 1 0))
+               
+               ------ Buffer: *Backtrace* ------
+               Signaling: (arith-error)
+                 /(1 0)
+               ...
+               ------ Buffer: *Backtrace* ------
+
+          If an error was signaled, presumably the variable
+          `debug-on-error' is non-`nil'.  If `quit' was signaled, then
+          presumably the variable `debug-on-quit' is non-`nil'.
+
+    `nil'
+          Use `nil' as the first of the DEBUGGER-ARGS when you want to
+          enter the debugger explicitly.  The rest of the DEBUGGER-ARGS
+          are printed on the top line of the buffer.  You can use this
+          feature to display messages--for example, to remind yourself
+          of the conditions under which `debug' is called.
+
+
+File: lispref.info,  Node: Internals of Debugger,  Prev: Invoking the Debugger,  Up: Debugger
+
+Internals of the Debugger
+-------------------------
+
+   This section describes functions and variables used internally by the
+debugger.
+
+ - Variable: debugger
+     The value of this variable is the function to call to invoke the
+     debugger.  Its value must be a function of any number of arguments
+     (or, more typically, the name of a function).  Presumably this
+     function will enter some kind of debugger.  The default value of
+     the variable is `debug'.
+
+     The first argument that Lisp hands to the function indicates why it
+     was called.  The convention for arguments is detailed in the
+     description of `debug'.
+
+ - Command: backtrace &optional stream detailed
+     This function prints a trace of Lisp function calls currently
+     active.  This is the function used by `debug' to fill up the
+     `*Backtrace*' buffer.  It is written in C, since it must have
+     access to the stack to determine which function calls are active.
+     The return value is always `nil'.
+
+     The backtrace is normally printed to `standard-output', but this
+     can be changed by specifying a value for STREAM.  If DETAILED is
+     non-`nil', the backtrace also shows places where currently active
+     variable bindings, catches, condition-cases, and unwind-protects
+     were made as well as function calls.
+
+     In the following example, a Lisp expression calls `backtrace'
+     explicitly.  This prints the backtrace to the stream
+     `standard-output': in this case, to the buffer `backtrace-output'.
+     Each line of the backtrace represents one function call.  The
+     line shows the values of the function's arguments if they are all
+     known.  If they are still being computed, the line says so.  The
+     arguments of special forms are elided.
+
+          (with-output-to-temp-buffer "backtrace-output"
+            (let ((var 1))
+              (save-excursion
+                (setq var (eval '(progn
+                                   (1+ var)
+                                   (list 'testing (backtrace))))))))
+          
+               => nil
+          
+          ----------- Buffer: backtrace-output ------------
+            backtrace()
+            (list ...computing arguments...)
+            (progn ...)
+            eval((progn (1+ var) (list (quote testing) (backtrace))))
+            (setq ...)
+            (save-excursion ...)
+            (let ...)
+            (with-output-to-temp-buffer ...)
+            eval-region(1973 2142 #<buffer *scratch*>)
+            byte-code("...  for eval-print-last-sexp ...")
+            eval-print-last-sexp(nil)
+          * call-interactively(eval-print-last-sexp)
+          ----------- Buffer: backtrace-output ------------
+
+     The character `*' indicates a frame whose debug-on-exit flag is
+     set.
+
+ - Variable: debug-on-next-call
+     If this variable is non-`nil', it says to call the debugger before
+     the next `eval', `apply' or `funcall'.  Entering the debugger sets
+     `debug-on-next-call' to `nil'.
+
+     The `d' command in the debugger works by setting this variable.
+
+ - Function: backtrace-debug level flag
+     This function sets the debug-on-exit flag of the stack frame LEVEL
+     levels down the stack, giving it the value FLAG.  If FLAG is
+     non-`nil', this will cause the debugger to be entered when that
+     frame later exits.  Even a nonlocal exit through that frame will
+     enter the debugger.
+
+     This function is used only by the debugger.
+
+ - Variable: command-debug-status
+     This variable records the debugging status of the current
+     interactive command.  Each time a command is called interactively,
+     this variable is bound to `nil'.  The debugger can set this
+     variable to leave information for future debugger invocations
+     during the same command.
+
+     The advantage, for the debugger, of using this variable rather than
+     another global variable is that the data will never carry over to a
+     subsequent command invocation.
+
+ - Function: backtrace-frame frame-number
+     The function `backtrace-frame' is intended for use in Lisp
+     debuggers.  It returns information about what computation is
+     happening in the stack frame FRAME-NUMBER levels down.
+
+     If that frame has not evaluated the arguments yet (or is a special
+     form), the value is `(nil FUNCTION ARG-FORMS...)'.
+
+     If that frame has evaluated its arguments and called its function
+     already, the value is `(t FUNCTION ARG-VALUES...)'.
+
+     In the return value, FUNCTION is whatever was supplied as the CAR
+     of the evaluated list, or a `lambda' expression in the case of a
+     macro call.  If the function has a `&rest' argument, that is
+     represented as the tail of the list ARG-VALUES.
+
+     If FRAME-NUMBER is out of range, `backtrace-frame' returns `nil'.
+
+
+File: lispref.info,  Node: Syntax Errors,  Next: Compilation Errors,  Prev: Debugger,  Up: Debugging
+
+Debugging Invalid Lisp Syntax
+=============================
+
+   The Lisp reader reports invalid syntax, but cannot say where the real
+problem is.  For example, the error "End of file during parsing" in
+evaluating an expression indicates an excess of open parentheses (or
+square brackets).  The reader detects this imbalance at the end of the
+file, but it cannot figure out where the close parenthesis should have
+been.  Likewise, "Invalid read syntax: ")"" indicates an excess close
+parenthesis or missing open parenthesis, but does not say where the
+missing parenthesis belongs.  How, then, to find what to change?
+
+   If the problem is not simply an imbalance of parentheses, a useful
+technique is to try `C-M-e' at the beginning of each defun, and see if
+it goes to the place where that defun appears to end.  If it does not,
+there is a problem in that defun.
+
+   However, unmatched parentheses are the most common syntax errors in
+Lisp, and we can give further advice for those cases.
+
+* Menu:
+
+* Excess Open::     How to find a spurious open paren or missing close.
+* Excess Close::    How to find a spurious close paren or missing open.
+
+
+File: lispref.info,  Node: Excess Open,  Next: Excess Close,  Up: Syntax Errors
+
+Excess Open Parentheses
+-----------------------
+
+   The first step is to find the defun that is unbalanced.  If there is
+an excess open parenthesis, the way to do this is to insert a close
+parenthesis at the end of the file and type `C-M-b' (`backward-sexp').
+This will move you to the beginning of the defun that is unbalanced.
+(Then type `C-<SPC> C-_ C-u C-<SPC>' to set the mark there, undo the
+insertion of the close parenthesis, and finally return to the mark.)
+
+   The next step is to determine precisely what is wrong.  There is no
+way to be sure of this except to study the program, but often the
+existing indentation is a clue to where the parentheses should have
+been.  The easiest way to use this clue is to reindent with `C-M-q' and
+see what moves.
+
+   Before you do this, make sure the defun has enough close parentheses.
+Otherwise, `C-M-q' will get an error, or will reindent all the rest of
+the file until the end.  So move to the end of the defun and insert a
+close parenthesis there.  Don't use `C-M-e' to move there, since that
+too will fail to work until the defun is balanced.
+
+   Now you can go to the beginning of the defun and type `C-M-q'.
+Usually all the lines from a certain point to the end of the function
+will shift to the right.  There is probably a missing close parenthesis,
+or a superfluous open parenthesis, near that point.  (However, don't
+assume this is true; study the code to make sure.)  Once you have found
+the discrepancy, undo the `C-M-q' with `C-_', since the old indentation
+is probably appropriate to the intended parentheses.
+
+   After you think you have fixed the problem, use `C-M-q' again.  If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, `C-M-q' should not change
+anything.
+
+
+File: lispref.info,  Node: Excess Close,  Prev: Excess Open,  Up: Syntax Errors
+
+Excess Close Parentheses
+------------------------
+
+   To deal with an excess close parenthesis, first insert an open
+parenthesis at the beginning of the file, back up over it, and type
+`C-M-f' to find the end of the unbalanced defun.  (Then type `C-<SPC>
+C-_ C-u C-<SPC>' to set the mark there, undo the insertion of the open
+parenthesis, and finally return to the mark.)
+
+   Then find the actual matching close parenthesis by typing `C-M-f' at
+the beginning of the defun.  This will leave you somewhere short of the
+place where the defun ought to end.  It is possible that you will find
+a spurious close parenthesis in that vicinity.
+
+   If you don't see a problem at that point, the next thing to do is to
+type `C-M-q' at the beginning of the defun.  A range of lines will
+probably shift left; if so, the missing open parenthesis or spurious
+close parenthesis is probably near the first of those lines.  (However,
+don't assume this is true; study the code to make sure.)  Once you have
+found the discrepancy, undo the `C-M-q' with `C-_', since the old
+indentation is probably appropriate to the intended parentheses.
+
+   After you think you have fixed the problem, use `C-M-q' again.  If
+the old indentation actually fit the intended nesting of parentheses,
+and you have put back those parentheses, `C-M-q' should not change
+anything.
+
+
+File: lispref.info,  Node: Compilation Errors,  Next: Edebug,  Prev: Syntax Errors,  Up: Debugging
+
+Debugging Problems in Compilation
+=================================
+
+   When an error happens during byte compilation, it is normally due to
+invalid syntax in the program you are compiling.  The compiler prints a
+suitable error message in the `*Compile-Log*' buffer, and then stops.
+The message may state a function name in which the error was found, or
+it may not.  Either way, here is how to find out where in the file the
+error occurred.
+
+   What you should do is switch to the buffer ` *Compiler Input*'.
+(Note that the buffer name starts with a space, so it does not show up
+in `M-x list-buffers'.)  This buffer contains the program being
+compiled, and point shows how far the byte compiler was able to read.
+
+   If the error was due to invalid Lisp syntax, point shows exactly
+where the invalid syntax was _detected_.  The cause of the error is not
+necessarily near by!  Use the techniques in the previous section to find
+the error.
+
+   If the error was detected while compiling a form that had been read
+successfully, then point is located at the end of the form.  In this
+case, this technique can't localize the error precisely, but can still
+show you which function to check.
+
+
+File: lispref.info,  Node: Edebug,  Prev: Compilation Errors,  Up: Top
+
+Edebug
+======
+
+   Edebug is a source-level debugger for XEmacs Lisp programs that
+provides the following features:
+
+   * Step through evaluation, stopping before and after each expression.
+
+   * Set conditional or unconditional breakpoints, install embedded
+     breakpoints, or a global break event.
+
+   * Trace slow or fast stopping briefly at each stop point, or each
+     breakpoint.
+
+   * Display expression results and evaluate expressions as if outside
+     of Edebug.  Interface with the custom printing package for
+     printing circular structures.
+
+   * Automatically reevaluate a list of expressions and display their
+     results each time Edebug updates the display.
+
+   * Output trace info on function enter and exit.
+
+   * Errors stop before the source causing the error.
+
+   * Display backtrace without Edebug calls.
+
+   * Allow specification of argument evaluation for macros and defining
+     forms.
+
+   * Provide rudimentary coverage testing and display of frequency
+     counts.
+
+
+   The first three sections should tell you enough about Edebug to
+enable you to use it.
+
+* Menu:
+
+* Using Edebug::		Introduction to use of Edebug.
+* Instrumenting::		You must first instrument code.
+* Edebug Execution Modes::	Execution modes, stopping more or less often.
+* Jumping::			Commands to jump to a specified place.
+* Edebug Misc::			Miscellaneous commands.
+* Breakpoints::			Setting breakpoints to make the program stop.
+* Trapping Errors::		trapping errors with Edebug.
+* Edebug Views::		Views inside and outside of Edebug.
+* Edebug Eval::			Evaluating expressions within Edebug.
+* Eval List::			Automatic expression evaluation.
+* Reading in Edebug::		Customization of reading.
+* Printing in Edebug::		Customization of printing.
+* Tracing::			How to produce tracing output.
+* Coverage Testing::		How to test evaluation coverage.
+* The Outside Context::		Data that Edebug saves and restores.
+* Instrumenting Macro Calls::	Specifying how to handle macro calls.
+* Edebug Options::		Option variables for customizing Edebug.
+
+
+File: lispref.info,  Node: Using Edebug,  Next: Instrumenting,  Up: Edebug
+
+Using Edebug
+------------
+
+   To debug an XEmacs Lisp program with Edebug, you must first
+"instrument" the Lisp code that you want to debug.  If you want to just
+try it now, load `edebug.el', move point into a definition and do `C-u
+C-M-x' (`eval-defun' with a prefix argument).  See *Note
+Instrumenting:: for alternative ways to instrument code.
+
+   Once a function is instrumented, any call to the function activates
+Edebug.  Activating Edebug may stop execution and let you step through
+the function, or it may update the display and continue execution while
+checking for debugging commands, depending on the selected Edebug
+execution mode.  The initial execution mode is `step', by default,
+which does stop execution.  *Note Edebug Execution Modes::.
+
+   Within Edebug, you normally view an XEmacs buffer showing the source
+of the Lisp function you are debugging.  This is referred to as the
+"source code buffer"--but note that it is not always the same buffer
+depending on which function is currently being executed.
+
+   An arrow at the left margin indicates the line where the function is
+executing.  Point initially shows where within the line the function is
+executing, but you can move point yourself.
+
+   If you instrument the definition of `fac' (shown below) and then
+execute `(fac 3)', here is what you normally see.  Point is at the
+open-parenthesis before `if'.
+
+     (defun fac (n)
+     =>-!-(if (< 0 n)
+           (* n (fac (1- n)))
+         1))
+
+   The places within a function where Edebug can stop execution are
+called "stop points".  These occur both before and after each
+subexpression that is a list, and also after each variable reference.
+Here we show with periods the stop points found in the function `fac':
+
+     (defun fac (n)
+       .(if .(< 0 n.).
+           .(* n. .(fac (1- n.).).).
+         1).)
+
+   While the source code buffer is selected, the special commands of
+Edebug are available in it, in addition to the commands of XEmacs Lisp
+mode.  (The buffer is temporarily made read-only, however.)  For
+example, you can type the Edebug command <SPC> to execute until the
+next stop point.  If you type <SPC> once after entry to `fac', here is
+the display you will see:
+
+     (defun fac (n)
+     =>(if -!-(< 0 n)
+           (* n (fac (1- n)))
+         1))
+
+   When Edebug stops execution after an expression, it displays the
+expression's value in the echo area.
+
+   Other frequently used commands are `b' to set a breakpoint at a stop
+point, `g' to execute until a breakpoint is reached, and `q' to exit to
+the top-level command loop.  Type `?' to display a list of all Edebug
+commands.
+
+
+File: lispref.info,  Node: Instrumenting,  Next: Edebug Execution Modes,  Prev: Using Edebug,  Up: Edebug
+
+Instrumenting for Edebug
+------------------------
+
+   In order to use Edebug to debug Lisp code, you must first
+"instrument" the code.  Instrumenting a form inserts additional code
+into it which invokes Edebug at the proper places.  Furthermore, if
+Edebug detects a syntax error while instrumenting, point is left at the
+erroneous code and an `invalid-read-syntax' error is signaled.
+
+   Once you have loaded Edebug, the command `C-M-x' (`eval-defun') is
+redefined so that when invoked with a prefix argument on a definition,
+it instruments the definition before evaluating it.  (The source code
+itself is not modified.)  If the variable `edebug-all-defs' is
+non-`nil', that inverts the meaning of the prefix argument: then
+`C-M-x' instruments the definition _unless_ it has a prefix argument.
+The default value of `edebug-all-defs' is `nil'.  The command `M-x
+edebug-all-defs' toggles the value of the variable `edebug-all-defs'.
+
+   If `edebug-all-defs' is non-`nil', then the commands `eval-region',
+`eval-current-buffer', and `eval-buffer' also instrument any
+definitions they evaluate.  Similarly, `edebug-all-forms' controls
+whether `eval-region' should instrument _any_ form, even non-defining
+forms.  This doesn't apply to loading or evaluations in the minibuffer.
+The command `M-x edebug-all-forms' toggles this option.
+
+   Another command, `M-x edebug-eval-top-level-form', is available to
+instrument any top-level form regardless of the value of
+`edebug-all-defs' or `edebug-all-forms'.
+
+   Just before Edebug instruments any code, it calls any functions in
+the variable `edebug-setup-hook' and resets its value to `nil'.  You
+could use this to load up Edebug specifications associated with a
+package you are using but only when you also use Edebug.  For example,
+`my-specs.el' may be loaded automatically when you use `my-package'
+with Edebug by including the following code in `my-package.el'.
+
+     (add-hook 'edebug-setup-hook
+       (function (lambda () (require 'my-specs))))
+
+   While Edebug is active, the command `I' (`edebug-instrument-callee')
+instruments the definition of the function or macro called by the list
+form after point, if is not already instrumented.  If the location of
+the definition is not known to Edebug, this command cannot be used.
+After loading Edebug, `eval-region' records the position of every
+definition it evaluates, even if not instrumenting it.  Also see the
+command `i' (*Note Jumping::) which steps into the callee.
+
+   Edebug knows how to instrument all the standard special forms, an
+interactive form with an expression argument, anonymous lambda
+expressions, and other defining forms.  (Specifications for macros
+defined by `cl.el' (version 2.03) are provided in `cl-specs.el'.)
+Edebug cannot know what a user-defined macro will do with the arguments
+of a macro call so you must tell it.  See *Note Instrumenting Macro
+Calls:: for the details.
+
+   Note that a couple ways remain to evaluate expressions without
+instrumenting them.  Loading a file via the `load' subroutine does not
+instrument expressions for Edebug.  Evaluations in the minibuffer via
+`eval-expression' (`M-ESC') are not instrumented.
+
+   To remove instrumentation from a definition, simply reevaluate it
+with one of the non-instrumenting commands, or reload the file.
+
+   See *Note Edebug Eval:: for other evaluation functions available
+inside of Edebug.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-14'
Index: ././info/lispref.info-14
--- ././info/lispref.info-14	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-14	Thu May 17 23:26:54 2001
@@ -0,0 +1,1234 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Edebug Execution Modes,  Next: Jumping,  Prev: Instrumenting,  Up: Edebug
+
+Edebug Execution Modes
+----------------------
+
+   Edebug supports several execution modes for running the program you
+are debugging.  We call these alternatives "Edebug execution modes"; do
+not confuse them with major or minor modes.  The current Edebug
+execution mode determines how Edebug displays the progress of the
+evaluation, whether it stops at each stop point, or continues to the
+next breakpoint, for example.
+
+   Normally, you specify the Edebug execution mode by typing a command
+to continue the program in a certain mode.  Here is a table of these
+commands.  All except for `S' resume execution of the program, at least
+for a certain distance.
+
+`S'
+     Stop: don't execute any more of the program for now, just wait for
+     more Edebug commands (`edebug-stop').
+
+`<SPC>'
+     Step: stop at the next stop point encountered (`edebug-step-mode').
+
+`n'
+     Next: stop at the next stop point encountered after an expression
+     (`edebug-next-mode').  Also see `edebug-forward-sexp' in *Note
+     Edebug Misc::.
+
+`t'
+     Trace: pause one second at each Edebug stop point
+     (`edebug-trace-mode').
+
+`T'
+     Rapid trace: update at each stop point, but don't actually pause
+     (`edebug-Trace-fast-mode').
+
+`g'
+     Go: run until the next breakpoint (`edebug-go-mode').  *Note
+     Breakpoints::.
+
+`c'
+     Continue: pause for one second at each breakpoint, but don't stop
+     (`edebug-continue-mode').
+
+`C'
+     Rapid continue: update at each breakpoint, but don't actually pause
+     (`edebug-Continue-fast-mode').
+
+`G'
+     Go non-stop: ignore breakpoints (`edebug-Go-nonstop-mode').  You
+     can still stop the program by hitting any key.
+
+   In general, the execution modes earlier in the above list run the
+program more slowly or stop sooner.
+
+   When you enter a new Edebug level, the initial execution mode comes
+from the value of the variable `edebug-initial-mode'.  By default, this
+specifies `step' mode.  Note that you may reenter the same Edebug level
+several times if, for example, an instrumented function is called
+several times from one command.
+
+   While executing or tracing, you can interrupt the execution by typing
+any Edebug command.  Edebug stops the program at the next stop point and
+then executes the command that you typed.  For example, typing `t'
+during execution switches to trace mode at the next stop point.  You can
+use `S' to stop execution without doing anything else.
+
+   If your function happens to read input, a character you hit
+intending to interrupt execution may be read by the function instead.
+You can avoid such unintended results by paying attention to when your
+program wants input.
+
+   Keyboard macros containing Edebug commands do not work; when you exit
+from Edebug, to resume the program, whether you are defining or
+executing a keyboard macro is forgotten.  Also, defining or executing a
+keyboard macro outside of Edebug does not affect the command loop inside
+Edebug.  This is usually an advantage.  But see
+`edebug-continue-kbd-macro'.
+
+
+File: lispref.info,  Node: Jumping,  Next: Edebug Misc,  Prev: Edebug Execution Modes,  Up: Edebug
+
+Jumping
+-------
+
+   Commands described here let you jump to a specified location.  All,
+except `i', use temporary breakpoints to establish the stop point and
+then switch to `go' mode.  Any other breakpoint reached before the
+intended stop point will also stop execution.  See *Note Breakpoints::
+for the details on breakpoints.
+
+`f'
+     Run the program forward over one expression
+     (`edebug-forward-sexp').  More precisely, set a temporary
+     breakpoint at the position that `C-M-f' would reach, then execute
+     in `go' mode so that the program will stop at breakpoints.
+
+     With a prefix argument N, the temporary breakpoint is placed N
+     sexps beyond point.  If the containing list ends before N more
+     elements, then the place to stop is after the containing
+     expression.
+
+     Be careful that the position `C-M-f' finds is a place that the
+     program will really get to; this may not be true in a `cond', for
+     example.
+
+     This command does `forward-sexp' starting at point rather than the
+     stop point.  If you want to execute one expression from the
+     current stop point, type `w' first, to move point there.
+
+`o'
+     Continue "out of" an expression (`edebug-step-out').  It places a
+     temporary breakpoint at the end of the sexp containing point.
+
+     If the containing sexp is a function definition itself, it
+     continues until just before the last sexp in the definition.  If
+     that is where you are now, it returns from the function and then
+     stops.  In other words, this command does not exit the currently
+     executing function unless you are positioned after the last sexp.
+
+`I'
+     Step into the function or macro after point after first ensuring
+     that it is instrumented.  It does this by calling
+     `edebug-on-entry' and then switching to `go' mode.
+
+     Although the automatic instrumentation is convenient, it is not
+     later automatically uninstrumented.
+
+`h'
+     Proceed to the stop point near where point is using a temporary
+     breakpoint (`edebug-goto-here').
+
+   All the commands in this section may fail to work as expected in case
+of nonlocal exit, because a nonlocal exit can bypass the temporary
+breakpoint where you expected the program to stop.
+
+
+File: lispref.info,  Node: Edebug Misc,  Next: Breakpoints,  Prev: Jumping,  Up: Edebug
+
+Miscellaneous
+-------------
+
+   Some miscellaneous commands are described here.
+
+`?'
+     Display the help message for Edebug (`edebug-help').
+
+`C-]'
+     Abort one level back to the previous command level
+     (`abort-recursive-edit').
+
+`q'
+     Return to the top level editor command loop (`top-level').  This
+     exits all recursive editing levels, including all levels of Edebug
+     activity.  However, instrumented code protected with
+     `unwind-protect' or `condition-case' forms may resume debugging.
+
+`Q'
+     Like `q' but don't stop even for protected code
+     (`top-level-nonstop').
+
+`r'
+     Redisplay the most recently known expression result in the echo
+     area (`edebug-previous-result').
+
+`d'
+     Display a backtrace, excluding Edebug's own functions for clarity
+     (`edebug-backtrace').
+
+     You cannot use debugger commands in the backtrace buffer in Edebug
+     as you would in the standard debugger.
+
+     The backtrace buffer is killed automatically when you continue
+     execution.
+
+   From the Edebug recursive edit, you may invoke commands that activate
+Edebug again recursively.  Any time Edebug is active, you can quit to
+the top level with `q' or abort one recursive edit level with `C-]'.
+You can display a backtrace of all the pending evaluations with `d'.
+
+
+File: lispref.info,  Node: Breakpoints,  Next: Trapping Errors,  Prev: Edebug Misc,  Up: Edebug
+
+Breakpoints
+-----------
+
+   There are three more ways to stop execution once it has started:
+breakpoints, the global break condition, and embedded breakpoints.
+
+   While using Edebug, you can specify "breakpoints" in the program you
+are testing: points where execution should stop.  You can set a
+breakpoint at any stop point, as defined in *Note Using Edebug::.  For
+setting and unsetting breakpoints, the stop point that is affected is
+the first one at or after point in the source code buffer.  Here are the
+Edebug commands for breakpoints:
+
+`b'
+     Set a breakpoint at the stop point at or after point
+     (`edebug-set-breakpoint').  If you use a prefix argument, the
+     breakpoint is temporary (it turns off the first time it stops the
+     program).
+
+`u'
+     Unset the breakpoint (if any) at the stop point at or after the
+     current point (`edebug-unset-breakpoint').
+
+`x CONDITION <RET>'
+     Set a conditional breakpoint which stops the program only if
+     CONDITION evaluates to a non-`nil' value
+     (`edebug-set-conditional-breakpoint').  If you use a prefix
+     argument, the breakpoint is temporary (it turns off the first time
+     it stops the program).
+
+`B'
+     Move point to the next breakpoint in the definition
+     (`edebug-next-breakpoint').
+
+   While in Edebug, you can set a breakpoint with `b' and unset one
+with `u'.  First you must move point to a position at or before the
+desired Edebug stop point, then hit the key to change the breakpoint.
+Unsetting a breakpoint that has not been set does nothing.
+
+   Reevaluating or reinstrumenting a definition clears all its
+breakpoints.
+
+   A "conditional breakpoint" tests a condition each time the program
+gets there.  To set a conditional breakpoint, use `x', and specify the
+condition expression in the minibuffer.  Setting a conditional
+breakpoint at a stop point that already has a conditional breakpoint
+puts the current condition expression in the minibuffer so you can edit
+it.
+
+   You can make both conditional and unconditional breakpoints
+"temporary" by using a prefix arg to the command to set the breakpoint.
+After breaking at a temporary breakpoint, it is automatically cleared.
+
+   Edebug always stops or pauses at a breakpoint except when the Edebug
+mode is `Go-nonstop'.  In that mode, it ignores breakpoints entirely.
+
+   To find out where your breakpoints are, use `B', which moves point
+to the next breakpoint in the definition following point, or to the
+first breakpoint if there are no following breakpoints.  This command
+does not continue execution--it just moves point in the buffer.
+
+* Menu:
+
+* Global Break Condition::	Breaking on an event.
+* Embedded Breakpoints::	Embedding breakpoints in code.
+
+
+File: lispref.info,  Node: Global Break Condition,  Next: Embedded Breakpoints,  Up: Breakpoints
+
+Global Break Condition
+......................
+
+   In contrast to breaking when execution reaches specified locations,
+you can also cause a break when a certain event occurs.  The "global
+break condition" is a condition that is repeatedly evaluated at every
+stop point.  If it evaluates to a non-`nil' value, then execution is
+stopped or paused depending on the execution mode, just like a
+breakpoint.  Any errors that might occur as a result of evaluating the
+condition are ignored, as if the result were `nil'.
+
+   You can set or edit the condition expression, stored in
+`edebug-global-break-condition', using `X'
+(`edebug-set-global-break-condition').
+
+   Using the global break condition is perhaps the fastest way to find
+where in your code some event occurs, but since it is rather expensive
+you should reset the condition to `nil' when not in use.
+
+
+File: lispref.info,  Node: Embedded Breakpoints,  Prev: Global Break Condition,  Up: Breakpoints
+
+Embedded Breakpoints
+....................
+
+   Since all breakpoints in a definition are cleared each time you
+reinstrument it, you might rather create an "embedded breakpoint" which
+is simply a call to the function `edebug'.  You can, of course, make
+such a call conditional.  For example, in the `fac' function, insert
+the first line as shown below to stop when the argument reaches zero:
+
+     (defun fac (n)
+       (if (= n 0) (edebug))
+       (if (< 0 n)
+           (* n (fac (1- n)))
+         1))
+
+   When the `fac' definition is instrumented and the function is
+called, Edebug will stop before the call to `edebug'.  Depending on the
+execution mode, Edebug will stop or pause.
+
+   However, if no instrumented code is being executed, calling `edebug'
+will instead invoke `debug'.  Calling `debug' will always invoke the
+standard backtrace debugger.
+
+
+File: lispref.info,  Node: Trapping Errors,  Next: Edebug Views,  Prev: Breakpoints,  Up: Edebug
+
+Trapping Errors
+---------------
+
+   An error may be signaled by subroutines or XEmacs Lisp code.  If a
+signal is not handled by a `condition-case', this indicates an
+unrecognized situation has occurred.  If Edebug is not active when an
+unhandled error is signaled, `debug' is run normally (if
+`debug-on-error' is non-`nil').  But while Edebug is active,
+`debug-on-error' and `debug-on-quit' are bound to `edebug-on-error' and
+`edebug-on-quit', which are both `t' by default.  Actually, if
+`debug-on-error' already has a non-`nil' value, that value is still
+used.
+
+   It is best to change the values of `edebug-on-error' or
+`edebug-on-quit' when Edebug is not active since their values won't be
+used until the next time Edebug is invoked at a deeper command level.
+If you only change `debug-on-error' or `debug-on-quit' while Edebug is
+active, these changes will be forgotten when Edebug becomes inactive.
+Furthermore, during Edebug's recursive edit, these variables are bound
+to the values they had outside of Edebug.
+
+   Edebug shows you the last stop point that it knew about before the
+error was signaled.  This may be the location of a call to a function
+which was not instrumented, within which the error actually occurred.
+For an unbound variable error, the last known stop point might be quite
+distant from the offending variable.  If the cause of the error is not
+obvious at first, note that you can also get a full backtrace inside of
+Edebug (see *Note Edebug Misc::).
+
+   Edebug can also trap signals even if they are handled.  If
+`debug-on-error' is a list of signal names, Edebug will stop when any
+of these errors are signaled.  Edebug shows you the last known stop
+point just as for unhandled errors.  After you continue execution, the
+error is signaled again (but without being caught by Edebug).  Edebug
+can only trap errors that are handled if they are signaled in Lisp code
+(not subroutines) since it does so by temporarily replacing the
+`signal' function.
+
+
+File: lispref.info,  Node: Edebug Views,  Next: Edebug Eval,  Prev: Trapping Errors,  Up: Edebug
+
+Edebug Views
+------------
+
+   The following Edebug commands let you view aspects of the buffer and
+window status that obtained before entry to Edebug.
+
+`v'
+     View the outside window configuration (`edebug-view-outside').
+
+`p'
+     Temporarily display the outside current buffer with point at its
+     outside position (`edebug-bounce-point'). If prefix arg is
+     supplied, sit for that many seconds instead.
+
+`w'
+     Move point back to the current stop point (`edebug-where') in the
+     source code buffer.  Also, if you use this command in another
+     window displaying the same buffer, this window will be used
+     instead to display the buffer in the future.
+
+`W'
+     Toggle the `edebug-save-windows' variable which indicates whether
+     the outside window configuration is saved and restored
+     (`edebug-toggle-save-windows').  Also, each time it is toggled on,
+     make the outside window configuration the same as the current
+     window configuration.
+
+     With a prefix argument, `edebug-toggle-save-windows' only toggles
+     saving and restoring of the selected window.  To specify a window
+     that is not displaying the source code buffer, you must use
+     `C-xXW' from the global keymap.
+
+   You can view the outside window configuration with `v' or just
+bounce to the current point in the current buffer with `p', even if it
+is not normally displayed.  After moving point, you may wish to pop
+back to the stop point with `w' from a source code buffer.
+
+   By using `W' twice, Edebug again saves and restores the outside
+window configuration, but to the current configuration.  This is a
+convenient way to, for example, add another buffer to be displayed
+whenever Edebug is active.  However, the automatic redisplay of
+`*edebug*' and `*edebug-trace*' may conflict with the buffers you wish
+to see unless you have enough windows open.
+
+
+File: lispref.info,  Node: Edebug Eval,  Next: Eval List,  Prev: Edebug Views,  Up: Edebug
+
+Evaluation
+----------
+
+   While within Edebug, you can evaluate expressions "as if" Edebug were
+not running.  Edebug tries to be invisible to the expression's
+evaluation and printing.  Evaluation of expressions that cause side
+effects will work as expected except for things that Edebug explicitly
+saves and restores.  See *Note The Outside Context:: for details on this
+process.  Also see *Note Reading in Edebug:: and *Note Printing in
+Edebug:: for topics related to evaluation.
+
+`e EXP <RET>'
+     Evaluate expression EXP in the context outside of Edebug
+     (`edebug-eval-expression').  In other words, Edebug tries to avoid
+     altering the effect of EXP.
+
+`M-<ESC> EXP <RET>'
+     Evaluate expression EXP in the context of Edebug itself.
+
+`C-x C-e'
+     Evaluate the expression before point, in the context outside of
+     Edebug (`edebug-eval-last-sexp').
+
+   Edebug supports evaluation of expressions containing references to
+lexically bound symbols created by the following constructs in `cl.el'
+(version 2.03 or later): `lexical-let', `macrolet', and
+`symbol-macrolet'.
+
+
+File: lispref.info,  Node: Eval List,  Next: Reading in Edebug,  Prev: Edebug Eval,  Up: Edebug
+
+Evaluation List Buffer
+----------------------
+
+   You can use the "evaluation list buffer", called `*edebug*', to
+evaluate expressions interactively.  You can also set up the
+"evaluation list" of expressions to be evaluated automatically each
+time Edebug updates the display.
+
+`E'
+     Switch to the evaluation list buffer `*edebug*'
+     (`edebug-visit-eval-list').
+
+   In the `*edebug*' buffer you can use the commands of Lisp
+Interaction as well as these special commands:
+
+`LFD'
+     Evaluate the expression before point, in the outside context, and
+     insert the value in the buffer (`edebug-eval-print-last-sexp').
+
+`C-x C-e'
+     Evaluate the expression before point, in the context outside of
+     Edebug (`edebug-eval-last-sexp').
+
+`C-c C-u'
+     Build a new evaluation list from the first expression of each
+     group, reevaluate and redisplay (`edebug-update-eval-list').
+     Groups are separated by comment lines.
+
+`C-c C-d'
+     Delete the evaluation list group that point is in
+     (`edebug-delete-eval-item').
+
+`C-c C-w'
+     Switch back to the source code buffer at the current stop point
+     (`edebug-where').
+
+   You can evaluate expressions in the evaluation list window with
+`LFD' or `C-x C-e', just as you would in `*scratch*'; but they are
+evaluated in the context outside of Edebug.
+
+   The expressions you enter interactively (and their results) are lost
+when you continue execution unless you add them to the evaluation list
+with `C-c C-u'.  This command builds a new list from the first
+expression of each "evaluation list group".  Groups are separated by
+comment lines.  Be careful not to add expressions that execute
+instrumented code otherwise an infinite loop will result.
+
+   When the evaluation list is redisplayed, each expression is displayed
+followed by the result of evaluating it, and a comment line.  If an
+error occurs during an evaluation, the error message is displayed in a
+string as if it were the result.  Therefore expressions that, for
+example, use variables not currently valid do not interrupt your
+debugging.
+
+   Here is an example of what the evaluation list window looks like
+after several expressions have been added to it:
+
+     (current-buffer)
+     #<buffer *scratch*>
+     ;---------------------------------------------------------------
+     (selected-window)
+     #<window 16 on *scratch*>
+     ;---------------------------------------------------------------
+     (point)
+     196
+     ;---------------------------------------------------------------
+     bad-var
+     "Symbol's value as variable is void: bad-var"
+     ;---------------------------------------------------------------
+     (recursion-depth)
+     0
+     ;---------------------------------------------------------------
+     this-command
+     eval-last-sexp
+     ;---------------------------------------------------------------
+
+   To delete a group, move point into it and type `C-c C-d', or simply
+delete the text for the group and update the evaluation list with `C-c
+C-u'.  When you add a new group, be sure it is separated from its
+neighbors by a comment line.
+
+   After selecting `*edebug*', you can return to the source code buffer
+with `C-c C-w'.  The `*edebug*' buffer is killed when you continue
+execution, and recreated next time it is needed.
+
+
+File: lispref.info,  Node: Reading in Edebug,  Next: Printing in Edebug,  Prev: Eval List,  Up: Edebug
+
+Reading in Edebug
+-----------------
+
+   To instrument a form, Edebug first reads the whole form.  Edebug
+replaces the standard Lisp Reader with its own reader that remembers the
+positions of expressions.  This reader is used by the Edebug
+replacements for `eval-region', `eval-defun', `eval-buffer', and
+`eval-current-buffer'.
+
+   Another package, `cl-read.el', replaces the standard reader with one
+that understands Common Lisp reader macros.  If you use that package,
+Edebug will automatically load `edebug-cl-read.el' to provide
+corresponding reader macros that remember positions of expressions.  If
+you define new reader macros, you will have to define similar reader
+macros for Edebug.
+
+
+File: lispref.info,  Node: Printing in Edebug,  Next: Tracing,  Prev: Reading in Edebug,  Up: Edebug
+
+Printing in Edebug
+------------------
+
+   If the result of an expression in your program contains a circular
+reference, you may get an error when Edebug attempts to print it.  You
+can set `print-length' to a non-zero value to limit the print length of
+lists (the number of cdrs), and in Emacs 19, set `print-level' to a
+non-zero value to limit the print depth of lists.  But you can print
+such circular structures and structures that share elements more
+informatively by using the `cust-print' package.
+
+   To load `cust-print' and activate custom printing only for Edebug,
+simply use the command `M-x edebug-install-custom-print'.  To restore
+the standard print functions, use `M-x edebug-uninstall-custom-print'.
+You can also activate custom printing for printing in any Lisp code;
+see the package for details.
+
+   Here is an example of code that creates a circular structure:
+
+     (progn
+       (edebug-install-custom-print)
+       (setq a '(x y))
+       (setcar a a))
+
+   Edebug will print the result of the `setcar' as `Result: #1=(#1#
+y)'.  The `#1=' notation names the structure that follows it, and the
+`#1#' notation references the previously named structure.  This
+notation is used for any shared elements of lists or vectors.
+
+   Independent of whether `cust-print' is active, while printing
+results Edebug binds `print-length', `print-level', and `print-circle'
+to `edebug-print-length' (`50'), `edebug-print-level' (`50'), and
+`edebug-print-circle' (`t') respectively, if these values are
+non-`nil'.  Also, `print-readably' is bound to `nil' since some objects
+simply cannot be printed readably.
+
+
+File: lispref.info,  Node: Tracing,  Next: Coverage Testing,  Prev: Printing in Edebug,  Up: Edebug
+
+Tracing
+-------
+
+   In addition to automatic stepping through source code, which is also
+called _tracing_ (see *Note Edebug Execution Modes::), Edebug can
+produce a traditional trace listing of execution in a separate buffer,
+`*edebug-trace*'.
+
+   If the variable `edebug-trace' is non-`nil', each function entry and
+exit adds lines to the trace buffer.  On function entry, Edebug prints
+`::::{' followed by the function name and argument values.  On function
+exit, Edebug prints `::::}' followed by the function name and result of
+the function.  The number of `:'s is computed from the recursion depth.
+The balanced braces in the trace buffer can be used to find the
+matching beginning or end of function calls. These displays may be
+customized by replacing the functions `edebug-print-trace-before' and
+`edebug-print-trace-after', which take an arbitrary message string to
+print.
+
+   The macro `edebug-tracing' provides tracing similar to function
+enter and exit tracing, but for arbitrary expressions.  This macro
+should be explicitly inserted by you around expressions you wish to
+trace the execution of.  The first argument is a message string
+(evaluated), and the rest are expressions to evaluate.  The result of
+the last expression is returned.
+
+   Finally, you can insert arbitrary strings into the trace buffer with
+explicit calls to `edebug-trace'.  The arguments of this function are
+the same as for `message', but a newline is always inserted after each
+string printed in this way.
+
+   `edebug-tracing' and `edebug-trace' insert lines in the trace buffer
+even if Edebug is not active.  Every time the trace buffer is added to,
+the window is scrolled to show the last lines inserted.  (There may be
+some display problems if you use tracing along with the evaluation
+list.)
+
+
+File: lispref.info,  Node: Coverage Testing,  Next: The Outside Context,  Prev: Tracing,  Up: Edebug
+
+Coverage Testing
+----------------
+
+   Edebug provides a rudimentary coverage tester and display of
+execution frequency.  Frequency counts are always accumulated, both
+before and after evaluation of each instrumented expression, even if
+the execution mode is `Go-nonstop'.  Coverage testing is only done if
+the option `edebug-test-coverage' is non-`nil' because this is
+relatively expensive.  Both data sets are displayed by `M-x
+edebug-display-freq-count'.
+
+ - Command: edebug-display-freq-count
+     Display the frequency count data for each line of the current
+     definition.  The frequency counts are inserted as comment lines
+     after each line, and you can undo all insertions with one `undo'
+     command.  The counts are inserted starting under the `(' before an
+     expression or the `)' after an expression, or on the last char of
+     a symbol.  The counts are only displayed when they differ from
+     previous counts on the same line.
+
+     If coverage is being tested, whenever all known results of an
+     expression are `eq', the char `=' will be appended after the count
+     for that expression.  Note that this is always the case for an
+     expression only evaluated once.
+
+     To clear the frequency count and coverage data for a definition,
+     reinstrument it.
+
+
+   For example, after evaluating `(fac 5)' with an embedded breakpoint,
+and setting `edebug-test-coverage' to `t', when the breakpoint is
+reached, the frequency data is looks like this:
+
+     (defun fac (n)
+       (if (= n 0) (edebug))
+     ;#6           1      0 =5
+       (if (< 0 n)
+     ;#5         =
+           (* n (fac (1- n)))
+     ;#    5               0
+         1))
+     ;#   0
+
+   The comment lines show that `fac' has been called 6 times.  The
+first `if' statement has returned 5 times with the same result each
+time, and the same is true for the condition on the second `if'.  The
+recursive call of `fac' has not returned at all.
+
+
+File: lispref.info,  Node: The Outside Context,  Next: Instrumenting Macro Calls,  Prev: Coverage Testing,  Up: Edebug
+
+The Outside Context
+-------------------
+
+   Edebug tries to be transparent to the program you are debugging.  In
+addition, most evaluations you do within Edebug (see *Note Edebug
+Eval::) occur in the same outside context which is temporarily restored
+for the evaluation.  But Edebug is not completely successful and this
+section explains precisely how it fails.  Edebug operation unavoidably
+alters some data in XEmacs, and this can interfere with debugging
+certain programs.  Also notice that Edebug's protection against change
+of outside data means that any side effects _intended_ by the user in
+the course of debugging will be defeated.
+
+* Menu:
+
+* Checking Whether to Stop::	When Edebug decides what to do.
+* Edebug Display Update::	When Edebug updates the display.
+* Edebug Recursive Edit::	When Edebug stops execution.
+
+
+File: lispref.info,  Node: Checking Whether to Stop,  Next: Edebug Display Update,  Up: The Outside Context
+
+Checking Whether to Stop
+........................
+
+   Whenever Edebug is entered just to think about whether to take some
+action, it needs to save and restore certain data.
+
+   * `max-lisp-eval-depth' and `max-specpdl-size' are both incremented
+     one time to reduce Edebug's impact on the stack.  You could,
+     however, still run out of stack space when using Edebug.
+
+   * The state of keyboard macro execution is saved and restored.  While
+     Edebug is active, `executing-macro' is bound to
+     `edebug-continue-kbd-macro'.
+
+
+
+File: lispref.info,  Node: Edebug Display Update,  Next: Edebug Recursive Edit,  Prev: Checking Whether to Stop,  Up: The Outside Context
+
+Edebug Display Update
+.....................
+
+   When Edebug needs to display something (e.g., in trace mode), it
+saves the current window configuration from "outside" Edebug.  When you
+exit Edebug (by continuing the program), it restores the previous window
+configuration.
+
+   XEmacs redisplays only when it pauses.  Usually, when you continue
+execution, the program comes back into Edebug at a breakpoint or after
+stepping without pausing or reading input in between.  In such cases,
+XEmacs never gets a chance to redisplay the "outside" configuration.
+What you see is the same window configuration as the last time Edebug
+was active, with no interruption.
+
+   Entry to Edebug for displaying something also saves and restores the
+following data, but some of these are deliberately not restored if an
+error or quit signal occurs.
+
+   * Which buffer is current, and where point and mark are in the
+     current buffer are saved and restored.
+
+   * The Edebug Display Update, is saved and restored if
+     `edebug-save-windows' is non-`nil'.  It is not restored on error
+     or quit, but the outside selected window _is_ reselected even on
+     error or quit in case a `save-excursion' is active.  If the value
+     of `edebug-save-windows' is a list, only the listed windows are
+     saved and restored.
+
+     The window start and horizontal scrolling of the source code
+     buffer are not restored, however, so that the display remains
+     coherent.
+
+   * The value of point in each displayed buffer is saved and restored
+     if `edebug-save-displayed-buffer-points' is non-`nil'.
+
+   * The variables `overlay-arrow-position' and `overlay-arrow-string'
+     are saved and restored.  So you can safely invoke Edebug from the
+     recursive edit elsewhere in the same buffer.
+
+   * `cursor-in-echo-area' is locally bound to `nil' so that the cursor
+     shows up in the window.
+
+
+
+File: lispref.info,  Node: Edebug Recursive Edit,  Prev: Edebug Display Update,  Up: The Outside Context
+
+Edebug Recursive Edit
+.....................
+
+   When Edebug is entered and actually reads commands from the user, it
+saves (and later restores) these additional data:
+
+   * The current match data, for whichever buffer was current.
+
+   * `last-command', `this-command', `last-command-char',
+     `last-input-char', `last-input-event', `last-command-event',
+     `last-event-frame', `last-nonmenu-event', and `track-mouse' .
+     Commands used within Edebug do not affect these variables outside
+     of Edebug.
+
+     The key sequence returned by `this-command-keys' is changed by
+     executing commands within Edebug and there is no way to reset the
+     key sequence from Lisp.
+
+     For Emacs 18, Edebug cannot save and restore the value of
+     `unread-command-char'.  Entering Edebug while this variable has a
+     nontrivial value can interfere with execution of the program you
+     are debugging.
+
+   * Complex commands executed while in Edebug are added to the variable
+     `command-history'.  In rare cases this can alter execution.
+
+   * Within Edebug, the recursion depth appears one deeper than the
+     recursion depth outside Edebug.  This is not true of the
+     automatically updated evaluation list window.
+
+   * `standard-output' and `standard-input' are bound to `nil' by the
+     `recursive-edit', but Edebug temporarily restores them during
+     evaluations.
+
+   * The state of keyboard macro definition is saved and restored.
+     While Edebug is active, `defining-kbd-macro' is bound to
+     `edebug-continue-kbd-macro'.
+
+
+
+File: lispref.info,  Node: Instrumenting Macro Calls,  Next: Edebug Options,  Prev: The Outside Context,  Up: Edebug
+
+Instrumenting Macro Calls
+-------------------------
+
+   When Edebug instruments an expression that calls a Lisp macro, it
+needs additional advice to do the job properly.  This is because there
+is no way to tell which subexpressions of the macro call may be
+evaluated.  (Evaluation may occur explicitly in the macro body, or when
+the resulting expansion is evaluated, or any time later.)  You must
+explain the format of macro call arguments by using `def-edebug-spec' to
+define an "Edebug specification" for each macro.
+
+ - Macro: def-edebug-spec macro specification
+     Specify which expressions of a call to macro MACRO are forms to be
+     evaluated.  For simple macros, the SPECIFICATION often looks very
+     similar to the formal argument list of the macro definition, but
+     specifications are much more general than macro arguments.
+
+     The MACRO argument may actually be any symbol, not just a macro
+     name.
+
+     Unless you are using Emacs 19 or XEmacs, this macro is only defined
+     in Edebug, so you may want to use the following which is
+     equivalent: `(put 'MACRO 'edebug-form-spec 'SPECIFICATION)'
+
+   Here is a simple example that defines the specification for the
+`for' macro described in the XEmacs Lisp Reference Manual, followed by
+an alternative, equivalent specification.
+
+     (def-edebug-spec for
+       (symbolp "from" form "to" form "do" &rest form))
+     
+     (def-edebug-spec for
+       (symbolp ['from form] ['to form] ['do body]))
+
+   Here is a table of the possibilities for SPECIFICATION and how each
+directs processing of arguments.
+
+*`t'
+     All arguments are instrumented for evaluation.
+
+*`0'
+     None of the arguments is instrumented.
+
+*a symbol
+     The symbol must have an Edebug specification which is used instead.
+     This indirection is repeated until another kind of specification is
+     found.  This allows you to inherit the specification for another
+     macro.
+
+*a list
+     The elements of the list describe the types of the arguments of a
+     calling form.  The possible elements of a specification list are
+     described in the following sections.
+
+* Menu:
+
+* Specification List::		How to specify complex patterns of evaluation.
+* Backtracking::		What Edebug does when matching fails.
+* Debugging Backquote::	Debugging Backquote
+* Specification Examples::	To help understand specifications.
+
+
+File: lispref.info,  Node: Specification List,  Next: Backtracking,  Up: Instrumenting Macro Calls
+
+Specification List
+..................
+
+   A "specification list" is required for an Edebug specification if
+some arguments of a macro call are evaluated while others are not.  Some
+elements in a specification list match one or more arguments, but others
+modify the processing of all following elements.  The latter, called
+"keyword specifications", are symbols beginning with ``&'' (e.g.
+`&optional').
+
+   A specification list may contain sublists which match arguments that
+are themselves lists, or it may contain vectors used for grouping.
+Sublists and groups thus subdivide the specification list into a
+hierarchy of levels.  Keyword specifications only apply to the
+remainder of the sublist or group they are contained in and there is an
+implicit grouping around a keyword specification and all following
+elements in the sublist or group.
+
+   If a specification list fails at some level, then backtracking may
+be invoked to find some alternative at a higher level, or if no
+alternatives remain, an error will be signaled.  See *Note
+Backtracking:: for more details.
+
+   Edebug specifications provide at least the power of regular
+expression matching.  Some context-free constructs are also supported:
+the matching of sublists with balanced parentheses, recursive
+processing of forms, and recursion via indirect specifications.
+
+   Each element of a specification list may be one of the following,
+with the corresponding type of argument:
+
+`sexp'
+     A single unevaluated expression.
+
+`form'
+     A single evaluated expression, which is instrumented.
+
+`place'
+     A place as in the Common Lisp `setf' place argument.  It will be
+     instrumented just like a form, but the macro is expected to strip
+     the instrumentation.  Two functions, `edebug-unwrap' and
+     `edebug-unwrap*', are provided to strip the instrumentation one
+     level or recursively at all levels.
+
+`body'
+     Short for `&rest form'.  See `&rest' below.
+
+`function-form'
+     A function form: either a quoted function symbol, a quoted lambda
+     expression, or a form (that should evaluate to a function symbol
+     or lambda expression).  This is useful when function arguments
+     might be quoted with `quote' rather than `function' since the body
+     of a lambda expression will be instrumented either way.
+
+`lambda-expr'
+     An unquoted anonymous lambda expression.
+
+`&optional'
+     All following elements in the specification list are optional; as
+     soon as one does not match, Edebug stops matching at this level.
+
+     To make just a few elements optional followed by non-optional
+     elements, use `[&optional SPECS...]'.  To specify that several
+     elements should all succeed together, use `&optional [SPECS...]'.
+     See the `defun' example below.
+
+`&rest'
+     All following elements in the specification list are repeated zero
+     or more times.  All the elements need not match in the last
+     repetition, however.
+
+     To repeat only a few elements, use `[&rest SPECS...]'.  To specify
+     all elements must match on every repetition, use `&rest
+     [SPECS...]'.
+
+`&or'
+     Each of the following elements in the specification list is an
+     alternative, processed left to right until one matches.  One of the
+     alternatives must match otherwise the `&or' specification fails.
+
+     Each list element following `&or' is a single alternative even if
+     it is a keyword specification. (This breaks the implicit grouping
+     rule.)  To group two or more list elements as a single
+     alternative, enclose them in `[...]'.
+
+`&not'
+     Each of the following elements is matched as alternatives as if by
+     using `&or', but if any of them match, the specification fails.
+     If none of them match, nothing is matched, but the `&not'
+     specification succeeds.
+
+`&define'
+     Indicates that the specification is for a defining form.  The
+     defining form itself is not instrumented (i.e. Edebug does not
+     stop before and after the defining form), but forms inside it
+     typically will be instrumented.  The `&define' keyword should be
+     the first element in a list specification.
+
+     Additional specifications that may only appear after `&define' are
+     described here.  See the `defun' example below.
+
+    `name'
+          The argument, a symbol, is the name of the defining form.
+          But a defining form need not be named at all, in which case a
+          unique name will be created for it.
+
+          The `name' specification may be used more than once in the
+          specification and each subsequent use will append the
+          corresponding symbol argument to the previous name with ``@''
+          between them.  This is useful for generating unique but
+          meaningful names for definitions such as `defadvice' and
+          `defmethod'.
+
+    `:name'
+          The element following `:name' should be a symbol; it is used
+          as an additional name component for the definition.  This is
+          useful to add a unique, static component to the name of the
+          definition.  It may be used more than once.  No argument is
+          matched.
+
+    `arg'
+          The argument, a symbol, is the name of an argument of the
+          defining form.  However, lambda list keywords (symbols
+          starting with ``&'') are not allowed.  See `lambda-list' and
+          the example below.
+
+    `lambda-list'
+          This matches the whole argument list of an XEmacs Lisp lambda
+          expression, which is a list of symbols and the keywords
+          `&optional' and `&rest'
+
+    `def-body'
+          The argument is the body of code in a definition.  This is
+          like `body', described above, but a definition body must be
+          instrumented with a different Edebug call that looks up
+          information associated with the definition.  Use `def-body'
+          for the highest level list of forms within the definition.
+
+    `def-form'
+          The argument is a single, highest-level form in a definition.
+          This is like `def-body', except use this to match a single
+          form rather than a list of forms.  As a special case,
+          `def-form' also means that tracing information is not output
+          when the form is executed.  See the `interactive' example
+          below.
+
+`nil'
+     This is successful when there are no more arguments to match at the
+     current argument list level; otherwise it fails.  See sublist
+     specifications and the backquote example below.
+
+`gate'
+     No argument is matched but backtracking through the gate is
+     disabled while matching the remainder of the specifications at
+     this level.  This is primarily used to generate more specific
+     syntax error messages.  See *Note Backtracking:: for more details.
+     Also see the `let' example below.
+
+`OTHER-SYMBOL'
+     Any other symbol in a specification list may be a predicate or an
+     indirect specification.
+
+     If the symbol has an Edebug specification, this "indirect
+     specification" should be either a list specification that is used
+     in place of the symbol, or a function that is called to process the
+     arguments.  The specification may be defined with `def-edebug-spec'
+     just as for macros. See the `defun' example below.
+
+     Otherwise, the symbol should be a predicate.  The predicate is
+     called with the argument and the specification fails if the
+     predicate fails.  The argument is not instrumented.
+
+     Predicates that may be used include: `symbolp', `integerp',
+     `stringp', `vectorp', `atom' (which matches a number, string,
+     symbol, or vector), `keywordp', and `lambda-list-keywordp'.  The
+     last two, defined in `edebug.el', test whether the argument is a
+     symbol starting with ``:'' and ``&'' respectively.
+
+`[ELEMENTS...]'
+     Rather than matching a vector argument, a vector treats the
+     ELEMENTS as a single "group specification".
+
+`"STRING"'
+     The argument should be a symbol named STRING.  This specification
+     is equivalent to the quoted symbol, `'SYMBOL', where the name of
+     SYMBOL is the STRING, but the string form is preferred.
+
+`'SYMBOL or (quote SYMBOL)'
+     The argument should be the symbol SYMBOL.  But use a string
+     specification instead.
+
+`(vector ELEMENTS...)'
+     The argument should be a vector whose elements must match the
+     ELEMENTS in the specification.  See the backquote example below.
+
+`(ELEMENTS...)'
+     Any other list is a "sublist specification" and the argument must
+     be a list whose elements match the specification ELEMENTS.
+
+     A sublist specification may be a dotted list and the corresponding
+     list argument may then be a dotted list.  Alternatively, the last
+     cdr of a dotted list specification may be another sublist
+     specification (via a grouping or an indirect specification, e.g.
+     `(spec .  [(more specs...)])') whose elements match the non-dotted
+     list arguments.  This is useful in recursive specifications such
+     as in the backquote example below.  Also see the description of a
+     `nil' specification above for terminating such recursion.
+
+     Note that a sublist specification of the form `(specs .  nil)'
+     means the same as `(specs)', and `(specs .
+     (sublist-elements...))' means the same as `(specs
+     sublist-elements...)'.
+
+
+File: lispref.info,  Node: Backtracking,  Next: Debugging Backquote,  Prev: Specification List,  Up: Instrumenting Macro Calls
+
+Backtracking
+............
+
+   If a specification fails to match at some point, this does not
+necessarily mean a syntax error will be signaled; instead,
+"backtracking" will take place until all alternatives have been
+exhausted.  Eventually every element of the argument list must be
+matched by some element in the specification, and every required element
+in the specification must match some argument.
+
+   Backtracking is disabled for the remainder of a sublist or group when
+certain conditions occur, described below.  Backtracking is reenabled
+when a new alternative is established by `&optional', `&rest', or
+`&or'.  It is also reenabled initially when processing a sublist or
+group specification or an indirect specification.
+
+   You might want to disable backtracking to commit to some alternative
+so that Edebug can provide a more specific syntax error message.
+Normally, if no alternative matches, Edebug reports that none matched,
+but if one alternative is committed to, Edebug can report how it failed
+to match.
+
+   First, backtracking is disabled while matching any of the form
+specifications (i.e. `form', `body', `def-form', and `def-body').
+These specifications will match any form so any error must be in the
+form itself rather than at a higher level.
+
+   Second, backtracking is disabled after successfully matching a quoted
+symbol or string specification, since this usually indicates a
+recognized construct.  If you have a set of alternative constructs that
+all begin with the same symbol, you can usually work around this
+constraint by factoring the symbol out of the alternatives, e.g.,
+`["foo" &or [first case] [second case] ...]'.
+
+   Third, backtracking may be explicitly disabled by using the `gate'
+specification.  This is useful when you know that no higher
+alternatives may apply.
+
+
+File: lispref.info,  Node: Debugging Backquote,  Next: Specification Examples,  Prev: Backtracking,  Up: Instrumenting Macro Calls
+
+Debugging Backquote
+...................
+
+   Backquote (``') is a macro that results in an expression that may or
+may not be evaluated.  It is often used to simplify the definition of a
+macro to return an expression that is evaluated, but Edebug does not
+know when this is the case.  However, the forms inside unquotes (`,' and
+`,@') are evaluated and Edebug instruments them.
+
+   Nested backquotes are supported by Edebug, but there is a limit on
+the support of quotes inside of backquotes.  Quoted forms (with `'')
+are not normally evaluated, but if the quoted form appears immediately
+within `,' and `,@' forms, Edebug treats this as a backquoted form at
+the next higher level (even if there is not a next higher level - this
+is difficult to fix).
+
+   If the backquoted forms happen to be code intended to be evaluated,
+you can have Edebug instrument them by using `edebug-`' instead of the
+regular ``'.  Unquoted forms can always appear inside `edebug-`'
+anywhere a form is normally allowed.  But `(, FORM)' may be used in two
+other places specially recognized by Edebug: wherever a predicate
+specification would match, and at the head of a list form in place of a
+function name or lambda expression.  The FORM inside a spliced unquote,
+`(,@ FORM)', will be wrapped, but the unquote form itself will not be
+wrapped since this would interfere with the splicing.
+
+   There is one other complication with using `edebug-`'.  If the
+`edebug-`' call is in a macro and the macro may be called from code
+that is also instrumented, and if unquoted forms contain any macro
+arguments bound to instrumented forms, then you should modify the
+specification for the macro as follows: the specifications for those
+arguments must use `def-form' instead of `form'.  (This is to
+reestablish the Edebugging context for those external forms.)
+
+   For example, the `for' macro (*note Problems with Macros: ()Problems
+with Macros.) is shown here but with `edebug-`' substituted for regular
+``'.
+
+     (defmacro inc (var)
+       (list 'setq var (list '1+ var)))
+     
+     (defmacro for (var from init to final do &rest body)
+       (let ((tempvar (make-symbol "max")))
+         (edebug-` (let (((, var) (, init))
+                         ((, tempvar) (, final)))
+                     (while (<= (, var) (, tempvar))
+                       (, body)
+                       (inc (, var)))))))
+
+   Here is the corresponding modified Edebug specification and some code
+that calls the macro:
+
+     (def-edebug-spec for
+       (symbolp "from" def-form "to" def-form "do" &rest def-form))
+     
+     (let ((n 5))
+       (for i from n to (* n (+ n 1)) do
+         (message "%s" i)))
+
+   After instrumenting the `for' macro and the macro call, Edebug first
+steps to the beginning of the macro call, then into the macro body,
+then through each of the unquoted expressions in the backquote showing
+the expressions that will be embedded in the backquote form.  Then when
+the macro expansion is evaluated, Edebug will step through the `let'
+form and each time it gets to an unquoted form, it will jump back to an
+argument of the macro call to step through that expression.  Finally
+stepping will continue after the macro call.  Even more convoluted
+execution paths may result when using anonymous functions.
+
+   When the result of an expression is an instrumented expression, it is
+difficult to see the expression inside the instrumentation.  So you may
+want to set the option `edebug-unwrap-results' to a non-`nil' value
+while debugging such expressions, but it would slow Edebug down to
+always do this.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-15'
Index: ././info/lispref.info-15
--- ././info/lispref.info-15	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-15	Thu May 17 23:26:54 2001
@@ -0,0 +1,1240 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Specification Examples,  Prev: Debugging Backquote,  Up: Instrumenting Macro Calls
+
+Specification Examples
+......................
+
+   Here we provide several examples of Edebug specifications to show
+many of its capabilities.
+
+   A `let' special form has a sequence of bindings and a body.  Each of
+the bindings is either a symbol or a sublist with a symbol and optional
+value.  In the specification below, notice the `gate' inside of the
+sublist to prevent backtracking.
+
+     (def-edebug-spec let
+       ((&rest
+         &or symbolp (gate symbolp &optional form))
+        body))
+
+   Edebug uses the following specifications for `defun' and `defmacro'
+and the associated argument list and `interactive' specifications.  It
+is necessary to handle the expression argument of an interactive form
+specially since it is actually evaluated outside of the function body.
+
+     (def-edebug-spec defmacro defun)      ; Indirect ref to `defun' spec
+     (def-edebug-spec defun
+       (&define name lambda-list
+                [&optional stringp]        ; Match the doc string, if present.
+                [&optional ("interactive" interactive)]
+                def-body))
+     
+     (def-edebug-spec lambda-list
+       (([&rest arg]
+         [&optional ["&optional" arg &rest arg]]
+         &optional ["&rest" arg]
+         )))
+     
+     (def-edebug-spec interactive
+       (&optional &or stringp def-form))    ; Notice: `def-form'
+
+   The specification for backquote below illustrates how to match
+dotted lists and use `nil' to terminate recursion.  It also illustrates
+how components of a vector may be matched.  (The actual specification
+provided by Edebug does not support dotted lists because doing so
+causes very deep recursion that could fail.)
+
+     (def-edebug-spec ` (backquote-form))  ;; alias just for clarity
+     
+     (def-edebug-spec backquote-form
+       (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
+            (backquote-form . [&or nil backquote-form])
+            (vector &rest backquote-form)
+            sexp))
+
+
+File: lispref.info,  Node: Edebug Options,  Prev: Instrumenting Macro Calls,  Up: Edebug
+
+Edebug Options
+--------------
+
+   These options affect the behavior of Edebug:
+
+ - User Option: edebug-setup-hook
+     Functions to call before Edebug is used.  Each time it is set to a
+     new value, Edebug will call those functions once and then
+     `edebug-setup-hook' is reset to `nil'.  You could use this to load
+     up Edebug specifications associated with a package you are using
+     but only when you also use Edebug.  See *Note Instrumenting::.
+
+ - User Option: edebug-all-defs
+     If non-`nil', normal evaluation of any defining forms (e.g.
+     `defun' and `defmacro') will instrument them for Edebug.  This
+     applies to `eval-defun', `eval-region', and `eval-current-buffer'.
+
+     Use the command `M-x edebug-all-defs' to toggle the value of this
+     variable. You may want to make this variable local to each buffer
+     by calling `(make-local-variable 'edebug-all-defs)' in your
+     `emacs-lisp-mode-hook'.  See *Note Instrumenting::.
+
+ - User Option: edebug-all-forms
+     If non-`nil', normal evaluation of any forms by `eval-defun',
+     `eval-region', and `eval-current-buffer' will instrument them for
+     Edebug.
+
+     Use the command `M-x edebug-all-forms' to toggle the value of this
+     option.  See *Note Instrumenting::.
+
+ - User Option: edebug-save-windows
+     If non-`nil', save and restore window configuration on Edebug
+     calls.  It takes some time to do this, so if your program does not
+     care what happens to data about windows, you may want to set this
+     variable to `nil'.
+
+     If the value is a list, only the listed windows are saved and
+     restored.
+
+     `M-x edebug-toggle-save-windows' may be used to change this
+     variable.  This command is bound to `W' in source code buffers.
+     See *Note Edebug Display Update::.
+
+ - User Option: edebug-save-displayed-buffer-points
+     If non-`nil', save and restore point in all displayed buffers.
+     This is necessary if you are debugging code that changes the point
+     of a buffer which is displayed in a non-selected window.  If
+     Edebug or the user then selects the window, the buffer's point
+     will be changed to the window's point.
+
+     This is an expensive operation since it visits each window and
+     therefore each displayed buffer twice for each Edebug activation,
+     so it is best to avoid it if you can.  See *Note Edebug Display
+     Update::.
+
+ - User Option: edebug-initial-mode
+     If this variable is non-`nil', it specifies the initial execution
+     mode for Edebug when it is first activated.  Possible values are
+     `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
+     `continue', and `Continue-fast'.
+
+     The default value is `step'.  See *Note Edebug Execution Modes::.
+
+ - User Option: edebug-trace
+     Non-`nil' means display a trace of function entry and exit.
+     Tracing output is displayed in a buffer named `*edebug-trace*', one
+     function entry or exit per line, indented by the recursion level.
+
+     The default value is `nil'.
+
+     Also see `edebug-tracing'.  See *Note Tracing::.
+
+ - User Option: edebug-test-coverage
+     If non-`nil', Edebug tests coverage of all expressions debugged.
+     This is done by comparing the result of each expression with the
+     previous result. Coverage is considered OK if two different
+     results are found.  So to sufficiently test the coverage of your
+     code, try to execute it under conditions that evaluate all
+     expressions more than once, and produce different results for each
+     expression.
+
+     Use `M-x edebug-display-freq-count' to display the frequency count
+     and coverage information for a definition.  See *Note Coverage
+     Testing::.
+
+ - User Option: edebug-continue-kbd-macro
+     If non-`nil', continue defining or executing any keyboard macro
+     that is executing outside of Edebug.   Use this with caution since
+     it is not debugged.  See *Note Edebug Execution Modes::.
+
+ - User Option: edebug-print-length
+     If non-`nil', bind `print-length' to this while printing results
+     in Edebug.  The default value is `50'.  See *Note Printing in
+     Edebug::.
+
+ - User Option: edebug-print-level
+     If non-`nil', bind `print-level' to this while printing results in
+     Edebug.  The default value is `50'.
+
+ - User Option: edebug-print-circle
+     If non-`nil', bind `print-circle' to this while printing results
+     in Edebug.  The default value is `nil'.
+
+ - User Option: edebug-on-error
+     `debug-on-error' is bound to this while Edebug is active.  See
+     *Note Trapping Errors::.
+
+ - User Option: edebug-on-quit
+     `debug-on-quit' is bound to this while Edebug is active.  See
+     *Note Trapping Errors::.
+
+ - User Option: edebug-unwrap-results
+     Non-`nil' if Edebug should unwrap results of expressions.  This is
+     useful when debugging macros where the results of expressions are
+     instrumented expressions.  But don't do this when results might be
+     circular or an infinite loop will result.  See *Note Debugging
+     Backquote::.
+
+ - User Option: edebug-global-break-condition
+     If non-`nil', an expression to test for at every stop point.  If
+     the result is non-`nil', then break.  Errors are ignored.  See
+     *Note Global Break Condition::.
+
+
+File: lispref.info,  Node: Read and Print,  Next: Minibuffers,  Prev: Debugging,  Up: Top
+
+Reading and Printing Lisp Objects
+*********************************
+
+   "Printing" and "reading" are the operations of converting Lisp
+objects to textual form and vice versa.  They use the printed
+representations and read syntax described in *Note Lisp Data Types::.
+
+   This chapter describes the Lisp functions for reading and printing.
+It also describes "streams", which specify where to get the text (if
+reading) or where to put it (if printing).
+
+* Menu:
+
+* Streams Intro::     Overview of streams, reading and printing.
+* Input Streams::     Various data types that can be used as input streams.
+* Input Functions::   Functions to read Lisp objects from text.
+* Output Streams::    Various data types that can be used as output streams.
+* Output Functions::  Functions to print Lisp objects as text.
+* Output Variables::  Variables that control what the printing functions do.
+
+
+File: lispref.info,  Node: Streams Intro,  Next: Input Streams,  Up: Read and Print
+
+Introduction to Reading and Printing
+====================================
+
+   "Reading" a Lisp object means parsing a Lisp expression in textual
+form and producing a corresponding Lisp object.  This is how Lisp
+programs get into Lisp from files of Lisp code.  We call the text the
+"read syntax" of the object.  For example, the text `(a . 5)' is the
+read syntax for a cons cell whose CAR is `a' and whose CDR is the
+number 5.
+
+   "Printing" a Lisp object means producing text that represents that
+object--converting the object to its printed representation.  Printing
+the cons cell described above produces the text `(a . 5)'.
+
+   Reading and printing are more or less inverse operations: printing
+the object that results from reading a given piece of text often
+produces the same text, and reading the text that results from printing
+an object usually produces a similar-looking object.  For example,
+printing the symbol `foo' produces the text `foo', and reading that text
+returns the symbol `foo'.  Printing a list whose elements are `a' and
+`b' produces the text `(a b)', and reading that text produces a list
+(but not the same list) with elements `a' and `b'.
+
+   However, these two operations are not precisely inverses.  There are
+three kinds of exceptions:
+
+   * Printing can produce text that cannot be read.  For example,
+     buffers, windows, frames, subprocesses and markers print into text
+     that starts with `#'; if you try to read this text, you get an
+     error.  There is no way to read those data types.
+
+   * One object can have multiple textual representations.  For example,
+     `1' and `01' represent the same integer, and `(a b)' and `(a .
+     (b))' represent the same list.  Reading will accept any of the
+     alternatives, but printing must choose one of them.
+
+   * Comments can appear at certain points in the middle of an object's
+     read sequence without affecting the result of reading it.
+
+
+File: lispref.info,  Node: Input Streams,  Next: Input Functions,  Prev: Streams Intro,  Up: Read and Print
+
+Input Streams
+=============
+
+   Most of the Lisp functions for reading text take an "input stream"
+as an argument.  The input stream specifies where or how to get the
+characters of the text to be read.  Here are the possible types of input
+stream:
+
+BUFFER
+     The input characters are read from BUFFER, starting with the
+     character directly after point.  Point advances as characters are
+     read.
+
+MARKER
+     The input characters are read from the buffer that MARKER is in,
+     starting with the character directly after the marker.  The marker
+     position advances as characters are read.  The value of point in
+     the buffer has no effect when the stream is a marker.
+
+STRING
+     The input characters are taken from STRING, starting at the first
+     character in the string and using as many characters as required.
+
+FUNCTION
+     The input characters are generated by FUNCTION, one character per
+     call.  Normally FUNCTION is called with no arguments, and should
+     return a character.
+
+     Occasionally FUNCTION is called with one argument (always a
+     character).  When that happens, FUNCTION should save the argument
+     and arrange to return it on the next call.  This is called
+     "unreading" the character; it happens when the Lisp reader reads
+     one character too many and wants to "put it back where it came
+     from".
+
+`t'
+     `t' used as a stream means that the input is read from the
+     minibuffer.  In fact, the minibuffer is invoked once and the text
+     given by the user is made into a string that is then used as the
+     input stream.
+
+`nil'
+     `nil' supplied as an input stream means to use the value of
+     `standard-input' instead; that value is the "default input
+     stream", and must be a non-`nil' input stream.
+
+SYMBOL
+     A symbol as input stream is equivalent to the symbol's function
+     definition (if any).
+
+   Here is an example of reading from a stream that is a buffer, showing
+where point is located before and after:
+
+     ---------- Buffer: foo ----------
+     This-!- is the contents of foo.
+     ---------- Buffer: foo ----------
+     
+     (read (get-buffer "foo"))
+          => is
+     (read (get-buffer "foo"))
+          => the
+     
+     ---------- Buffer: foo ----------
+     This is the-!- contents of foo.
+     ---------- Buffer: foo ----------
+
+Note that the first read skips a space.  Reading skips any amount of
+whitespace preceding the significant text.
+
+   In Emacs 18, reading a symbol discarded the delimiter terminating the
+symbol.  Thus, point would end up at the beginning of `contents' rather
+than after `the'.  The Emacs 19 behavior is superior because it
+correctly handles input such as `bar(foo)', where the open-parenthesis
+that ends one object is needed as the beginning of another object.
+
+   Here is an example of reading from a stream that is a marker,
+initially positioned at the beginning of the buffer shown.  The value
+read is the symbol `This'.
+
+
+     ---------- Buffer: foo ----------
+     This is the contents of foo.
+     ---------- Buffer: foo ----------
+     
+     (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
+          => #<marker at 1 in foo>
+     (read m)
+          => This
+     m
+          => #<marker at 5 in foo>   ;; Before the first space.
+
+   Here we read from the contents of a string:
+
+     (read "(When in) the course")
+          => (When in)
+
+   The following example reads from the minibuffer.  The prompt is:
+`Lisp expression: '.  (That is always the prompt used when you read
+from the stream `t'.)  The user's input is shown following the prompt.
+
+     (read t)
+          => 23
+     ---------- Buffer: Minibuffer ----------
+     Lisp expression: 23 <RET>
+     ---------- Buffer: Minibuffer ----------
+
+   Finally, here is an example of a stream that is a function, named
+`useless-stream'.  Before we use the stream, we initialize the variable
+`useless-list' to a list of characters.  Then each call to the function
+`useless-stream' obtains the next character in the list or unreads a
+character by adding it to the front of the list.
+
+     (setq useless-list (append "XY()" nil))
+          => (88 89 40 41)
+     
+     (defun useless-stream (&optional unread)
+       (if unread
+           (setq useless-list (cons unread useless-list))
+         (prog1 (car useless-list)
+                (setq useless-list (cdr useless-list)))))
+          => useless-stream
+
+Now we read using the stream thus constructed:
+
+     (read 'useless-stream)
+          => XY
+     
+     useless-list
+          => (40 41)
+
+Note that the open and close parentheses remains in the list.  The Lisp
+reader encountered the open parenthesis, decided that it ended the
+input, and unread it.  Another attempt to read from the stream at this
+point would read `()' and return `nil'.
+
+
+File: lispref.info,  Node: Input Functions,  Next: Output Streams,  Prev: Input Streams,  Up: Read and Print
+
+Input Functions
+===============
+
+   This section describes the Lisp functions and variables that pertain
+to reading.
+
+   In the functions below, STREAM stands for an input stream (see the
+previous section).  If STREAM is `nil' or omitted, it defaults to the
+value of `standard-input'.
+
+   An `end-of-file' error is signaled if reading encounters an
+unterminated list, vector, or string.
+
+ - Function: read &optional stream
+     This function reads one textual Lisp expression from STREAM,
+     returning it as a Lisp object.  This is the basic Lisp input
+     function.
+
+ - Function: read-from-string string &optional start end
+     This function reads the first textual Lisp expression from the
+     text in STRING.  It returns a cons cell whose CAR is that
+     expression, and whose CDR is an integer giving the position of the
+     next remaining character in the string (i.e., the first one not
+     read).
+
+     If START is supplied, then reading begins at index START in the
+     string (where the first character is at index 0).  If END is also
+     supplied, then reading stops just before that index, as if the rest
+     of the string were not there.
+
+     For example:
+
+          (read-from-string "(setq x 55) (setq y 5)")
+               => ((setq x 55) . 11)
+          (read-from-string "\"A short string\"")
+               => ("A short string" . 16)
+          
+          ;; Read starting at the first character.
+          (read-from-string "(list 112)" 0)
+               => ((list 112) . 10)
+          ;; Read starting at the second character.
+          (read-from-string "(list 112)" 1)
+               => (list . 5)
+          ;; Read starting at the seventh character,
+          ;;   and stopping at the ninth.
+          (read-from-string "(list 112)" 6 8)
+               => (11 . 8)
+
+ - Variable: standard-input
+     This variable holds the default input stream--the stream that
+     `read' uses when the STREAM argument is `nil'.
+
+
+File: lispref.info,  Node: Output Streams,  Next: Output Functions,  Prev: Input Functions,  Up: Read and Print
+
+Output Streams
+==============
+
+   An output stream specifies what to do with the characters produced
+by printing.  Most print functions accept an output stream as an
+optional argument.  Here are the possible types of output stream:
+
+BUFFER
+     The output characters are inserted into BUFFER at point.  Point
+     advances as characters are inserted.
+
+MARKER
+     The output characters are inserted into the buffer that MARKER
+     points into, at the marker position.  The marker position advances
+     as characters are inserted.  The value of point in the buffer has
+     no effect on printing when the stream is a marker.
+
+FUNCTION
+     The output characters are passed to FUNCTION, which is responsible
+     for storing them away.  It is called with a single character as
+     argument, as many times as there are characters to be output, and
+     is free to do anything at all with the characters it receives.
+
+`t'
+     The output characters are displayed in the echo area.
+
+`nil'
+     `nil' specified as an output stream means to the value of
+     `standard-output' instead; that value is the "default output
+     stream", and must be a non-`nil' output stream.
+
+SYMBOL
+     A symbol as output stream is equivalent to the symbol's function
+     definition (if any).
+
+   Many of the valid output streams are also valid as input streams.
+The difference between input and output streams is therefore mostly one
+of how you use a Lisp object, not a distinction of types of object.
+
+   Here is an example of a buffer used as an output stream.  Point is
+initially located as shown immediately before the `h' in `the'.  At the
+end, point is located directly before that same `h'.
+
+     ---------- Buffer: foo ----------
+     This is t-!-he contents of foo.
+     ---------- Buffer: foo ----------
+     
+     (print "This is the output" (get-buffer "foo"))
+          => "This is the output"
+     
+     ---------- Buffer: foo ----------
+     This is t
+     "This is the output"
+     -!-he contents of foo.
+     ---------- Buffer: foo ----------
+
+   Now we show a use of a marker as an output stream.  Initially, the
+marker is in buffer `foo', between the `t' and the `h' in the word
+`the'.  At the end, the marker has advanced over the inserted text so
+that it remains positioned before the same `h'.  Note that the location
+of point, shown in the usual fashion, has no effect.
+
+     ---------- Buffer: foo ----------
+     "This is the -!-output"
+     ---------- Buffer: foo ----------
+     
+     m
+          => #<marker at 11 in foo>
+     
+     (print "More output for foo." m)
+          => "More output for foo."
+     
+     ---------- Buffer: foo ----------
+     "This is t
+     "More output for foo."
+     he -!-output"
+     ---------- Buffer: foo ----------
+     
+     m
+          => #<marker at 35 in foo>
+
+   The following example shows output to the echo area:
+
+     (print "Echo Area output" t)
+          => "Echo Area output"
+     ---------- Echo Area ----------
+     "Echo Area output"
+     ---------- Echo Area ----------
+
+   Finally, we show the use of a function as an output stream.  The
+function `eat-output' takes each character that it is given and conses
+it onto the front of the list `last-output' (*note Building Lists::).
+At the end, the list contains all the characters output, but in reverse
+order.
+
+     (setq last-output nil)
+          => nil
+     
+     (defun eat-output (c)
+       (setq last-output (cons c last-output)))
+          => eat-output
+     
+     (print "This is the output" 'eat-output)
+          => "This is the output"
+     
+     last-output
+          => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\  ?e ?h ?t
+                     ?\  ?s ?i ?\  ?s ?i ?h ?T ?\" ?\n)
+
+Now we can put the output in the proper order by reversing the list:
+
+     (concat (nreverse last-output))
+          => "
+     \"This is the output\"
+     "
+
+Calling `concat' converts the list to a string so you can see its
+contents more clearly.
+
+
+File: lispref.info,  Node: Output Functions,  Next: Output Variables,  Prev: Output Streams,  Up: Read and Print
+
+Output Functions
+================
+
+   This section describes the Lisp functions for printing Lisp objects.
+
+   Some of the XEmacs printing functions add quoting characters to the
+output when necessary so that it can be read properly.  The quoting
+characters used are `"' and `\'; they distinguish strings from symbols,
+and prevent punctuation characters in strings and symbols from being
+taken as delimiters when reading.  *Note Printed Representation::, for
+full details.  You specify quoting or no quoting by the choice of
+printing function.
+
+   If the text is to be read back into Lisp, then it is best to print
+with quoting characters to avoid ambiguity.  Likewise, if the purpose is
+to describe a Lisp object clearly for a Lisp programmer.  However, if
+the purpose of the output is to look nice for humans, then it is better
+to print without quoting.
+
+   Printing a self-referent Lisp object requires an infinite amount of
+text.  In certain cases, trying to produce this text leads to a stack
+overflow.  XEmacs detects such recursion and prints `#LEVEL' instead of
+recursively printing an object already being printed.  For example,
+here `#0' indicates a recursive reference to the object at level 0 of
+the current print operation:
+
+     (setq foo (list nil))
+          => (nil)
+     (setcar foo foo)
+          => (#0)
+
+   In the functions below, STREAM stands for an output stream.  (See
+the previous section for a description of output streams.)  If STREAM
+is `nil' or omitted, it defaults to the value of `standard-output'.
+
+ - Function: print object &optional stream
+     The `print' function is a convenient way of printing.  It outputs
+     the printed representation of OBJECT to STREAM, printing in
+     addition one newline before OBJECT and another after it.  Quoting
+     characters are used.  `print' returns OBJECT.  For example:
+
+          (progn (print 'The\ cat\ in)
+                 (print "the hat")
+                 (print " came back"))
+               -|
+               -| The\ cat\ in
+               -|
+               -| "the hat"
+               -|
+               -| " came back"
+               -|
+               => " came back"
+
+ - Function: prin1 object &optional stream
+     This function outputs the printed representation of OBJECT to
+     STREAM.  It does not print newlines to separate output as `print'
+     does, but it does use quoting characters just like `print'.  It
+     returns OBJECT.
+
+          (progn (prin1 'The\ cat\ in)
+                 (prin1 "the hat")
+                 (prin1 " came back"))
+               -| The\ cat\ in"the hat"" came back"
+               => " came back"
+
+ - Function: princ object &optional stream
+     This function outputs the printed representation of OBJECT to
+     STREAM.  It returns OBJECT.
+
+     This function is intended to produce output that is readable by
+     people, not by `read', so it doesn't insert quoting characters and
+     doesn't put double-quotes around the contents of strings.  It does
+     not add any spacing between calls.
+
+          (progn
+            (princ 'The\ cat)
+            (princ " in the \"hat\""))
+               -| The cat in the "hat"
+               => " in the \"hat\""
+
+ - Function: terpri &optional stream
+     This function outputs a newline to STREAM.  The name stands for
+     "terminate print".
+
+ - Function: write-char character &optional stream
+     This function outputs CHARACTER to STREAM.  It returns CHARACTER.
+
+ - Function: prin1-to-string object &optional noescape
+     This function returns a string containing the text that `prin1'
+     would have printed for the same argument.
+
+          (prin1-to-string 'foo)
+               => "foo"
+          (prin1-to-string (mark-marker))
+               => "#<marker at 2773 in strings.texi>"
+
+     If NOESCAPE is non-`nil', that inhibits use of quoting characters
+     in the output.  (This argument is supported in Emacs versions 19
+     and later.)
+
+          (prin1-to-string "foo")
+               => "\"foo\""
+          (prin1-to-string "foo" t)
+               => "foo"
+
+     See `format', in *Note String Conversion::, for other ways to
+     obtain the printed representation of a Lisp object as a string.
+
+
+File: lispref.info,  Node: Output Variables,  Prev: Output Functions,  Up: Read and Print
+
+Variables Affecting Output
+==========================
+
+ - Variable: standard-output
+     The value of this variable is the default output stream--the stream
+     that print functions use when the STREAM argument is `nil'.
+
+ - Variable: print-escape-newlines
+     If this variable is non-`nil', then newline characters in strings
+     are printed as `\n' and formfeeds are printed as `\f'.  Normally
+     these characters are printed as actual newlines and formfeeds.
+
+     This variable affects the print functions `prin1' and `print', as
+     well as everything that uses them.  It does not affect `princ'.
+     Here is an example using `prin1':
+
+          (prin1 "a\nb")
+               -| "a
+               -| b"
+               => "a
+          b"
+          
+          (let ((print-escape-newlines t))
+            (prin1 "a\nb"))
+               -| "a\nb"
+               => "a
+          b"
+
+     In the second expression, the local binding of
+     `print-escape-newlines' is in effect during the call to `prin1',
+     but not during the printing of the result.
+
+ - Variable: print-readably
+     If non-`nil', then all objects will be printed in a readable form.
+     If an object has no readable representation, then an error is
+     signalled.  When `print-readably' is true, compiled-function
+     objects will be written in `#[...]' form instead of in
+     `#<compiled-function [...]>' form, and two-element lists of the
+     form `(quote object)' will be written as the equivalent `'object'.
+     Do not _set_ this variable; bind it instead.
+
+ - Variable: print-length
+     The value of this variable is the maximum number of elements of a
+     list that will be printed.  If a list being printed has more than
+     this many elements, it is abbreviated with an ellipsis.
+
+     If the value is `nil' (the default), then there is no limit.
+
+          (setq print-length 2)
+               => 2
+          (print '(1 2 3 4 5))
+               -| (1 2 ...)
+               => (1 2 ...)
+
+ - Variable: print-level
+     The value of this variable is the maximum depth of nesting of
+     parentheses and brackets when printed.  Any list or vector at a
+     depth exceeding this limit is abbreviated with an ellipsis.  A
+     value of `nil' (which is the default) means no limit.
+
+     This variable exists in version 19 and later versions.
+
+ - Variable: print-string-length
+     The value of this variable is the maximum number of characters of
+     a string that will be printed.  If a string being printed has more
+     than this many characters, it is abbreviated with an ellipsis.
+
+ - Variable: print-gensym
+     If non-`nil', then uninterned symbols will be printed specially.
+     Uninterned symbols are those which are not present in `obarray',
+     that is, those which were made with `make-symbol' or by calling
+     `intern' with a second argument.
+
+     When `print-gensym' is true, such symbols will be preceded by
+     `#:', which causes the reader to create a new symbol instead of
+     interning and returning an existing one.  Beware: The `#:' syntax
+     creates a new symbol each time it is seen, so if you print an
+     object which contains two pointers to the same uninterned symbol,
+     `read' will not duplicate that structure.
+
+     Also, since XEmacs has no real notion of packages, there is no way
+     for the printer to distinguish between symbols interned in no
+     obarray, and symbols interned in an alternate obarray.
+
+ - Variable: float-output-format
+     This variable holds the format descriptor string that Lisp uses to
+     print floats.  This is a `%'-spec like those accepted by `printf'
+     in C, but with some restrictions.  It must start with the two
+     characters `%.'.  After that comes an integer precision
+     specification, and then a letter which controls the format.  The
+     letters allowed are `e', `f' and `g'.
+
+        * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
+
+        * Use `f' for decimal point notation `DIGITS.DIGITS'.
+
+        * Use `g' to choose the shorter of those two formats for the
+          number at hand.
+
+     The precision in any of these cases is the number of digits
+     following the decimal point.  With `f', a precision of 0 means to
+     omit the decimal point.  0 is not allowed with `f' or `g'.
+
+     A value of `nil' means to use `%.16g'.
+
+     Regardless of the value of `float-output-format', a floating point
+     number will never be printed in such a way that it is ambiguous
+     with an integer; that is, a floating-point number will always be
+     printed with a decimal point and/or an exponent, even if the
+     digits following the decimal point are all zero.  This is to
+     preserve read-equivalence.
+
+
+File: lispref.info,  Node: Minibuffers,  Next: Command Loop,  Prev: Read and Print,  Up: Top
+
+Minibuffers
+***********
+
+   A "minibuffer" is a special buffer that XEmacs commands use to read
+arguments more complicated than the single numeric prefix argument.
+These arguments include file names, buffer names, and command names (as
+in `M-x').  The minibuffer is displayed on the bottom line of the
+frame, in the same place as the echo area, but only while it is in use
+for reading an argument.
+
+* Menu:
+
+* Intro to Minibuffers::      Basic information about minibuffers.
+* Text from Minibuffer::      How to read a straight text string.
+* Object from Minibuffer::    How to read a Lisp object or expression.
+* Minibuffer History::	      Recording previous minibuffer inputs
+				so the user can reuse them.
+* Completion::                How to invoke and customize completion.
+* Yes-or-No Queries::         Asking a question with a simple answer.
+* Multiple Queries::	      Asking a series of similar questions.
+* Reading a Password::	      Reading a password from the terminal.
+* Minibuffer Misc::           Various customization hooks and variables.
+
+
+File: lispref.info,  Node: Intro to Minibuffers,  Next: Text from Minibuffer,  Up: Minibuffers
+
+Introduction to Minibuffers
+===========================
+
+   In most ways, a minibuffer is a normal XEmacs buffer.  Most
+operations _within_ a buffer, such as editing commands, work normally
+in a minibuffer.  However, many operations for managing buffers do not
+apply to minibuffers.  The name of a minibuffer always has the form
+` *Minibuf-NUMBER', and it cannot be changed.  Minibuffers are
+displayed only in special windows used only for minibuffers; these
+windows always appear at the bottom of a frame.  (Sometimes frames have
+no minibuffer window, and sometimes a special kind of frame contains
+nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
+
+   The minibuffer's window is normally a single line.  You can resize it
+temporarily with the window sizing commands; it reverts to its normal
+size when the minibuffer is exited.  You can resize it permanently by
+using the window sizing commands in the frame's other window, when the
+minibuffer is not active.  If the frame contains just a minibuffer, you
+can change the minibuffer's size by changing the frame's size.
+
+   If a command uses a minibuffer while there is an active minibuffer,
+this is called a "recursive minibuffer".  The first minibuffer is named
+` *Minibuf-0*'.  Recursive minibuffers are named by incrementing the
+number at the end of the name.  (The names begin with a space so that
+they won't show up in normal buffer lists.)  Of several recursive
+minibuffers, the innermost (or most recently entered) is the active
+minibuffer.  We usually call this "the" minibuffer.  You can permit or
+forbid recursive minibuffers by setting the variable
+`enable-recursive-minibuffers'.
+
+   Like other buffers, a minibuffer may use any of several local keymaps
+(*note Keymaps::); these contain various exit commands and in some cases
+completion commands (*note Completion::).
+
+   * `minibuffer-local-map' is for ordinary input (no completion).
+
+   * `minibuffer-local-completion-map' is for permissive completion.
+
+   * `minibuffer-local-must-match-map' is for strict completion and for
+     cautious completion.
+
+
+File: lispref.info,  Node: Text from Minibuffer,  Next: Object from Minibuffer,  Prev: Intro to Minibuffers,  Up: Minibuffers
+
+Reading Text Strings with the Minibuffer
+========================================
+
+   Most often, the minibuffer is used to read text as a string.  It can
+also be used to read a Lisp object in textual form.  The most basic
+primitive for minibuffer input is `read-from-minibuffer'; it can do
+either one.
+
+   In most cases, you should not call minibuffer input functions in the
+middle of a Lisp function.  Instead, do all minibuffer input as part of
+reading the arguments for a command, in the `interactive' spec.  *Note
+Defining Commands::.
+
+ - Function: read-from-minibuffer prompt-string &optional
+          initial-contents keymap read hist abbrev-table default
+     This function is the most general way to get input through the
+     minibuffer.  By default, it accepts arbitrary text and returns it
+     as a string; however, if READ is non-`nil', then it uses `read' to
+     convert the text into a Lisp object (*note Input Functions::).
+
+     The first thing this function does is to activate a minibuffer and
+     display it with PROMPT-STRING as the prompt.  This value must be a
+     string.
+
+     Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
+     inserts it into the minibuffer, leaving point at the end.  The
+     minibuffer appears with this text as its contents.
+
+     The value of INITIAL-CONTENTS may also be a cons cell of the form
+     `(STRING . POSITION)'.  This means to insert STRING in the
+     minibuffer but put point POSITION characters from the beginning,
+     rather than at the end.
+
+     When the user types a command to exit the minibuffer,
+     `read-from-minibuffer' constructs the return value from the text in
+     the minibuffer.  Normally it returns a string containing that text.
+     However, if READ is non-`nil', `read-from-minibuffer' reads the
+     text and returns the resulting Lisp object, unevaluated.  (*Note
+     Input Functions::, for information about reading.)
+
+     The argument DEFAULT specifies a default value to make available
+     through the history commands.  It should be a string, or `nil'.
+
+     If KEYMAP is non-`nil', that keymap is the local keymap to use in
+     the minibuffer.  If KEYMAP is omitted or `nil', the value of
+     `minibuffer-local-map' is used as the keymap.  Specifying a keymap
+     is the most important way to customize the minibuffer for various
+     applications such as completion.
+
+     The argument ABBREV-TABLE specifies `local-abbrev-table' in the
+     minibuffer (*note Standard Abbrev Tables::).
+
+     The argument HIST specifies which history list variable to use for
+     saving the input and for history commands used in the minibuffer.
+     It defaults to `minibuffer-history'.  *Note Minibuffer History::.
+
+     When the user types a command to exit the minibuffer,
+     `read-from-minibuffer' uses the text in the minibuffer to produce
+     its return value.  Normally it simply makes a string containing
+     that text.  However, if READ is non-`nil', `read-from-minibuffer'
+     reads the text and returns the resulting Lisp object, unevaluated.
+     (*Note Input Functions::, for information about reading.)
+
+     *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
+     argument are two alternative features for more or less the same
+     job.  It does not make sense to use both features in a single call
+     to `read-from-minibuffer'.  In general, we recommend using
+     DEFAULT, since this permits the user to insert the default value
+     when it is wanted, but does not burden the user with deleting it
+     from the minibuffer on other occasions.  However, if user is
+     supposed to edit default value, INITIAL-CONTENTS may be preferred.
+
+ - Function: read-string prompt &optional initial history default-value
+     This function reads a string from the minibuffer and returns it.
+     The arguments PROMPT and INITIAL are used as in
+     `read-from-minibuffer'.  The keymap used is `minibuffer-local-map'.
+
+     The optional argument HISTORY, if non-`nil', specifies a history
+     list and optionally the initial position in the list.  The optional
+     argument DEFAULT-VALUE specifies a default value to return if the
+     user enters null input; it should be a string.
+
+     This function is a simplified interface to the
+     `read-from-minibuffer' function:
+
+          (read-string PROMPT INITIAL HISTORY DEFAULT)
+          ==
+          (read-from-minibuffer PROMPT INITIAL nil nil
+                                HISTORY nil DEFAULT)))
+
+ - Variable: minibuffer-local-map
+     This is the default local keymap for reading from the minibuffer.
+     By default, it makes the following bindings:
+
+    `C-j'
+          `exit-minibuffer'
+
+    <RET>
+          `exit-minibuffer'
+
+    `C-g'
+          `abort-recursive-edit'
+
+    `M-n'
+          `next-history-element'
+
+    `M-p'
+          `previous-history-element'
+
+    `M-r'
+          `next-matching-history-element'
+
+    `M-s'
+          `previous-matching-history-element'
+
+
+File: lispref.info,  Node: Object from Minibuffer,  Next: Minibuffer History,  Prev: Text from Minibuffer,  Up: Minibuffers
+
+Reading Lisp Objects with the Minibuffer
+========================================
+
+   This section describes functions for reading Lisp objects with the
+minibuffer.
+
+ - Function: read-expression prompt &optional initial history
+          default-value
+     This function reads a Lisp object using the minibuffer, and
+     returns it without evaluating it.  The arguments PROMPT and
+     INITIAL are used as in `read-from-minibuffer'.
+
+     The optional argument HISTORY, if non-`nil', specifies a history
+     list and optionally the initial position in the list.  The optional
+     argument DEFAULT-VALUE specifies a default value to return if the
+     user enters null input; it should be a string.
+
+     This is a simplified interface to the `read-from-minibuffer'
+     function:
+
+          (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
+          ==
+          (read-from-minibuffer PROMPT INITIAL nil t
+                                HISTORY nil DEFAULT-VALUE)
+
+     Here is an example in which we supply the string `"(testing)"' as
+     initial input:
+
+          (read-expression
+           "Enter an expression: " (format "%s" '(testing)))
+          
+          ;; Here is how the minibuffer is displayed:
+          
+          ---------- Buffer: Minibuffer ----------
+          Enter an expression: (testing)-!-
+          ---------- Buffer: Minibuffer ----------
+
+     The user can type <RET> immediately to use the initial input as a
+     default, or can edit the input.
+
+ - Function: read-minibuffer prompt &optional initial history
+          default-value
+     This is a FSF Emacs compatible function.  Use `read-expression'
+     instead.
+
+ - Function: eval-minibuffer prompt &optional initial history
+          default-value
+     This function reads a Lisp expression using the minibuffer,
+     evaluates it, then returns the result.  The arguments PROMPT and
+     INITIAL are used as in `read-from-minibuffer'.
+
+     The optional argument HISTORY, if non-`nil', specifies a history
+     list and optionally the initial position in the list.  The optional
+     argument DEFAULT-VALUE specifies a default value to return if the
+     user enters null input; it should be a string.
+
+     This function simply evaluates the result of a call to
+     `read-expression':
+
+          (eval-minibuffer PROMPT INITIAL)
+          ==
+          (eval (read-expression PROMPT INITIAL))
+
+ - Function: edit-and-eval-command prompt form &optional history
+     This function reads a Lisp expression in the minibuffer, and then
+     evaluates it.  The difference between this command and
+     `eval-minibuffer' is that here the initial FORM is not optional
+     and it is treated as a Lisp object to be converted to printed
+     representation rather than as a string of text.  It is printed with
+     `prin1', so if it is a string, double-quote characters (`"')
+     appear in the initial text.  *Note Output Functions::.
+
+     The first thing `edit-and-eval-command' does is to activate the
+     minibuffer with PROMPT as the prompt.  Then it inserts the printed
+     representation of FORM in the minibuffer, and lets the user edit
+     it.  When the user exits the minibuffer, the edited text is read
+     with `read' and then evaluated.  The resulting value becomes the
+     value of `edit-and-eval-command'.
+
+     In the following example, we offer the user an expression with
+     initial text which is a valid form already:
+
+          (edit-and-eval-command "Please edit: " '(forward-word 1))
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following appears in the minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          Please edit: (forward-word 1)-!-
+          ---------- Buffer: Minibuffer ----------
+
+     Typing <RET> right away would exit the minibuffer and evaluate the
+     expression, thus moving point forward one word.
+     `edit-and-eval-command' returns `t' in this example.
+
+
+File: lispref.info,  Node: Minibuffer History,  Next: Completion,  Prev: Object from Minibuffer,  Up: Minibuffers
+
+Minibuffer History
+==================
+
+   A "minibuffer history list" records previous minibuffer inputs so
+the user can reuse them conveniently.  A history list is actually a
+symbol, not a list; it is a variable whose value is a list of strings
+(previous inputs), most recent first.
+
+   There are many separate history lists, used for different kinds of
+inputs.  It's the Lisp programmer's job to specify the right history
+list for each use of the minibuffer.
+
+   The basic minibuffer input functions `read-from-minibuffer' and
+`completing-read' both accept an optional argument named HIST which is
+how you specify the history list.  Here are the possible values:
+
+VARIABLE
+     Use VARIABLE (a symbol) as the history list.
+
+(VARIABLE . STARTPOS)
+     Use VARIABLE (a symbol) as the history list, and assume that the
+     initial history position is STARTPOS (an integer, counting from
+     zero which specifies the most recent element of the history).
+
+     If you specify STARTPOS, then you should also specify that element
+     of the history as the initial minibuffer contents, for consistency.
+
+   If you don't specify HIST, then the default history list
+`minibuffer-history' is used.  For other standard history lists, see
+below.  You can also create your own history list variable; just
+initialize it to `nil' before the first use.
+
+   Both `read-from-minibuffer' and `completing-read' add new elements
+to the history list automatically, and provide commands to allow the
+user to reuse items on the list.  The only thing your program needs to
+do to use a history list is to initialize it and to pass its name to
+the input functions when you wish.  But it is safe to modify the list
+by hand when the minibuffer input functions are not using it.
+
+   Here are some of the standard minibuffer history list variables:
+
+ - Variable: minibuffer-history
+     The default history list for minibuffer history input.
+
+ - Variable: query-replace-history
+     A history list for arguments to `query-replace' (and similar
+     arguments to other commands).
+
+ - Variable: file-name-history
+     A history list for file name arguments.
+
+ - Variable: regexp-history
+     A history list for regular expression arguments.
+
+ - Variable: extended-command-history
+     A history list for arguments that are names of extended commands.
+
+ - Variable: shell-command-history
+     A history list for arguments that are shell commands.
+
+ - Variable: read-expression-history
+     A history list for arguments that are Lisp expressions to evaluate.
+
+ - Variable: Info-minibuffer-history
+     A history list for Info mode's minibuffer.
+
+ - Variable: Manual-page-minibuffer-history
+     A history list for `manual-entry'.
+
+   There are many other minibuffer history lists, defined by various
+libraries.  An `M-x apropos' search for `history' should prove fruitful
+in discovering them.
+
+
+File: lispref.info,  Node: Completion,  Next: Yes-or-No Queries,  Prev: Minibuffer History,  Up: Minibuffers
+
+Completion
+==========
+
+   "Completion" is a feature that fills in the rest of a name starting
+from an abbreviation for it.  Completion works by comparing the user's
+input against a list of valid names and determining how much of the
+name is determined uniquely by what the user has typed.  For example,
+when you type `C-x b' (`switch-to-buffer') and then type the first few
+letters of the name of the buffer to which you wish to switch, and then
+type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
+can.
+
+   Standard XEmacs commands offer completion for names of symbols,
+files, buffers, and processes; with the functions in this section, you
+can implement completion for other kinds of names.
+
+   The `try-completion' function is the basic primitive for completion:
+it returns the longest determined completion of a given initial string,
+with a given set of strings to match against.
+
+   The function `completing-read' provides a higher-level interface for
+completion.  A call to `completing-read' specifies how to determine the
+list of valid names.  The function then activates the minibuffer with a
+local keymap that binds a few keys to commands useful for completion.
+Other functions provide convenient simple interfaces for reading
+certain kinds of names with completion.
+
+* Menu:
+
+* Basic Completion::       Low-level functions for completing strings.
+                             (These are too low level to use the minibuffer.)
+* Minibuffer Completion::  Invoking the minibuffer with completion.
+* Completion Commands::    Minibuffer commands that do completion.
+* High-Level Completion::  Convenient special cases of completion
+                             (reading buffer name, file name, etc.)
+* Reading File Names::     Using completion to read file names.
+* Programmed Completion::  Finding the completions for a given file name.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-16'
Index: ././info/lispref.info-16
--- ././info/lispref.info-16	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-16	Thu May 17 23:26:54 2001
@@ -0,0 +1,1093 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Basic Completion,  Next: Minibuffer Completion,  Up: Completion
+
+Basic Completion Functions
+--------------------------
+
+   The two functions `try-completion' and `all-completions' have
+nothing in themselves to do with minibuffers.  We describe them in this
+chapter so as to keep them near the higher-level completion features
+that do use the minibuffer.
+
+ - Function: try-completion string collection &optional predicate
+     This function returns the longest common prefix of all possible
+     completions of STRING in COLLECTION.  The value of COLLECTION must
+     be an alist, an obarray, or a function that implements a virtual
+     set of strings (see below).
+
+     Completion compares STRING against each of the permissible
+     completions specified by COLLECTION; if the beginning of the
+     permissible completion equals STRING, it matches.  If no
+     permissible completions match, `try-completion' returns `nil'.  If
+     only one permissible completion matches, and the match is exact,
+     then `try-completion' returns `t'.  Otherwise, the value is the
+     longest initial sequence common to all the permissible completions
+     that match.
+
+     If COLLECTION is an alist (*note Association Lists::), the CARs of
+     the alist elements form the set of permissible completions.
+
+     If COLLECTION is an obarray (*note Creating Symbols::), the names
+     of all symbols in the obarray form the set of permissible
+     completions.  The global variable `obarray' holds an obarray
+     containing the names of all interned Lisp symbols.
+
+     Note that the only valid way to make a new obarray is to create it
+     empty and then add symbols to it one by one using `intern'.  Also,
+     you cannot intern a given symbol in more than one obarray.
+
+     If the argument PREDICATE is non-`nil', then it must be a function
+     of one argument.  It is used to test each possible match, and the
+     match is accepted only if PREDICATE returns non-`nil'.  The
+     argument given to PREDICATE is either a cons cell from the alist
+     (the CAR of which is a string) or else it is a symbol (_not_ a
+     symbol name) from the obarray.
+
+     You can also use a symbol that is a function as COLLECTION.  Then
+     the function is solely responsible for performing completion;
+     `try-completion' returns whatever this function returns.  The
+     function is called with three arguments: STRING, PREDICATE and
+     `nil'.  (The reason for the third argument is so that the same
+     function can be used in `all-completions' and do the appropriate
+     thing in either case.)  *Note Programmed Completion::.
+
+     In the first of the following examples, the string `foo' is
+     matched by three of the alist CARs.  All of the matches begin with
+     the characters `fooba', so that is the result.  In the second
+     example, there is only one possible match, and it is exact, so the
+     value is `t'.
+
+          (try-completion
+           "foo"
+           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
+               => "fooba"
+          
+          (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
+               => t
+
+     In the following example, numerous symbols begin with the
+     characters `forw', and all of them begin with the word `forward'.
+     In most of the symbols, this is followed with a `-', but not in
+     all, so no more than `forward' can be completed.
+
+          (try-completion "forw" obarray)
+               => "forward"
+
+     Finally, in the following example, only two of the three possible
+     matches pass the predicate `test' (the string `foobaz' is too
+     short).  Both of those begin with the string `foobar'.
+
+          (defun test (s)
+            (> (length (car s)) 6))
+               => test
+          (try-completion
+           "foo"
+           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+           'test)
+               => "foobar"
+
+ - Function: all-completions string collection &optional predicate
+     This function returns a list of all possible completions of STRING.
+     The arguments to this function are the same as those of
+     `try-completion'.
+
+     If COLLECTION is a function, it is called with three arguments:
+     STRING, PREDICATE and `t'; then `all-completions' returns whatever
+     the function returns.  *Note Programmed Completion::.
+
+     Here is an example, using the function `test' shown in the example
+     for `try-completion':
+
+          (defun test (s)
+            (> (length (car s)) 6))
+               => test
+          
+          (all-completions
+           "foo"
+           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+           'test)
+               => ("foobar1" "foobar2")
+
+ - Variable: completion-ignore-case
+     If the value of this variable is non-`nil', XEmacs does not
+     consider case significant in completion.
+
+
+File: lispref.info,  Node: Minibuffer Completion,  Next: Completion Commands,  Prev: Basic Completion,  Up: Completion
+
+Completion and the Minibuffer
+-----------------------------
+
+   This section describes the basic interface for reading from the
+minibuffer with completion.
+
+ - Function: completing-read prompt collection &optional predicate
+          require-match initial hist default
+     This function reads a string in the minibuffer, assisting the user
+     by providing completion.  It activates the minibuffer with prompt
+     PROMPT, which must be a string.  If INITIAL is non-`nil',
+     `completing-read' inserts it into the minibuffer as part of the
+     input.  Then it allows the user to edit the input, providing
+     several commands to attempt completion.
+
+     The actual completion is done by passing COLLECTION and PREDICATE
+     to the function `try-completion'.  This happens in certain
+     commands bound in the local keymaps used for completion.
+
+     If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
+     exit unless the input completes to an element of COLLECTION.  If
+     REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
+     won't exit unless the input typed is itself an element of
+     COLLECTION.  If REQUIRE-MATCH is `nil', the exit commands work
+     regardless of the input in the minibuffer.
+
+     However, empty input is always permitted, regardless of the value
+     of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT.
+     The value of DEFAULT (if non-`nil') is also available to the user
+     through the history commands.
+
+     The user can exit with null input by typing <RET> with an empty
+     minibuffer.  Then `completing-read' returns `""'.  This is how the
+     user requests whatever default the command uses for the value being
+     read.  The user can return using <RET> in this way regardless of
+     the value of REQUIRE-MATCH, and regardless of whether the empty
+     string is included in COLLECTION.
+
+     The function `completing-read' works by calling `read-expression'.
+     It uses `minibuffer-local-completion-map' as the keymap if
+     REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
+     if REQUIRE-MATCH is non-`nil'.  *Note Completion Commands::.
+
+     The argument HIST specifies which history list variable to use for
+     saving the input and for minibuffer history commands.  It defaults
+     to `minibuffer-history'.  *Note Minibuffer History::.
+
+     Completion ignores case when comparing the input against the
+     possible matches, if the built-in variable
+     `completion-ignore-case' is non-`nil'.  *Note Basic Completion::.
+
+     Here's an example of using `completing-read':
+
+          (completing-read
+           "Complete a foo: "
+           '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+           nil t "fo")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following appears in the minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          Complete a foo: fo-!-
+          ---------- Buffer: Minibuffer ----------
+
+     If the user then types `<DEL> <DEL> b <RET>', `completing-read'
+     returns `barfoo'.
+
+     The `completing-read' function binds three variables to pass
+     information to the commands that actually do completion.  These
+     variables are `minibuffer-completion-table',
+     `minibuffer-completion-predicate' and
+     `minibuffer-completion-confirm'.  For more information about them,
+     see *Note Completion Commands::.
+
+
+File: lispref.info,  Node: Completion Commands,  Next: High-Level Completion,  Prev: Minibuffer Completion,  Up: Completion
+
+Minibuffer Commands That Do Completion
+--------------------------------------
+
+   This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+ - Variable: minibuffer-local-completion-map
+     `completing-read' uses this value as the local keymap when an
+     exact match of one of the completions is not required.  By
+     default, this keymap makes the following bindings:
+
+    `?'
+          `minibuffer-completion-help'
+
+    <SPC>
+          `minibuffer-complete-word'
+
+    <TAB>
+          `minibuffer-complete'
+
+     with other characters bound as in `minibuffer-local-map' (*note
+     Text from Minibuffer::).
+
+ - Variable: minibuffer-local-must-match-map
+     `completing-read' uses this value as the local keymap when an
+     exact match of one of the completions is required.  Therefore, no
+     keys are bound to `exit-minibuffer', the command that exits the
+     minibuffer unconditionally.  By default, this keymap makes the
+     following bindings:
+
+    `?'
+          `minibuffer-completion-help'
+
+    <SPC>
+          `minibuffer-complete-word'
+
+    <TAB>
+          `minibuffer-complete'
+
+    `C-j'
+          `minibuffer-complete-and-exit'
+
+    <RET>
+          `minibuffer-complete-and-exit'
+
+     with other characters bound as in `minibuffer-local-map'.
+
+ - Variable: minibuffer-completion-table
+     The value of this variable is the alist or obarray used for
+     completion in the minibuffer.  This is the global variable that
+     contains what `completing-read' passes to `try-completion'.  It is
+     used by minibuffer completion commands such as
+     `minibuffer-complete-word'.
+
+ - Variable: minibuffer-completion-predicate
+     This variable's value is the predicate that `completing-read'
+     passes to `try-completion'.  The variable is also used by the other
+     minibuffer completion functions.
+
+ - Command: minibuffer-complete-word
+     This function completes the minibuffer contents by at most a single
+     word.  Even if the minibuffer contents have only one completion,
+     `minibuffer-complete-word' does not add any characters beyond the
+     first character that is not a word constituent.  *Note Syntax
+     Tables::.
+
+ - Command: minibuffer-complete
+     This function completes the minibuffer contents as far as possible.
+
+ - Command: minibuffer-complete-and-exit
+     This function completes the minibuffer contents, and exits if
+     confirmation is not required, i.e., if
+     `minibuffer-completion-confirm' is `nil'.  If confirmation _is_
+     required, it is given by repeating this command immediately--the
+     command is programmed to work without confirmation when run twice
+     in succession.
+
+ - Variable: minibuffer-completion-confirm
+     When the value of this variable is non-`nil', XEmacs asks for
+     confirmation of a completion before exiting the minibuffer.  The
+     function `minibuffer-complete-and-exit' checks the value of this
+     variable before it exits.
+
+ - Command: minibuffer-completion-help
+     This function creates a list of the possible completions of the
+     current minibuffer contents.  It works by calling `all-completions'
+     using the value of the variable `minibuffer-completion-table' as
+     the COLLECTION argument, and the value of
+     `minibuffer-completion-predicate' as the PREDICATE argument.  The
+     list of completions is displayed as text in a buffer named
+     `*Completions*'.
+
+ - Function: display-completion-list completions &rest cl-keys
+     This function displays COMPLETIONS to the stream in
+     `standard-output', usually a buffer.  (*Note Read and Print::, for
+     more information about streams.)  The argument COMPLETIONS is
+     normally a list of completions just returned by `all-completions',
+     but it does not have to be.  Each element may be a symbol or a
+     string, either of which is simply printed, or a list of two
+     strings, which is printed as if the strings were concatenated.
+
+     This function is called by `minibuffer-completion-help'.  The most
+     common way to use it is together with
+     `with-output-to-temp-buffer', like this:
+
+          (with-output-to-temp-buffer "*Completions*"
+            (display-completion-list
+              (all-completions (buffer-string) my-alist)))
+
+ - User Option: completion-auto-help
+     If this variable is non-`nil', the completion commands
+     automatically display a list of possible completions whenever
+     nothing can be completed because the next character is not
+     uniquely determined.
+
+
+File: lispref.info,  Node: High-Level Completion,  Next: Reading File Names,  Prev: Completion Commands,  Up: Completion
+
+High-Level Completion  Functions
+--------------------------------
+
+   This section describes the higher-level convenient functions for
+reading certain sorts of names with completion.
+
+   In most cases, you should not call these functions in the middle of a
+Lisp function.  When possible, do all minibuffer input as part of
+reading the arguments for a command, in the `interactive' spec.  *Note
+Defining Commands::.
+
+ - Function: read-buffer prompt &optional default existing
+     This function reads the name of a buffer and returns it as a
+     string.  The argument DEFAULT is the default name to use, the
+     value to return if the user exits with an empty minibuffer.  If
+     non-`nil', it should be a string or a buffer.  It is mentioned in
+     the prompt, but is not inserted in the minibuffer as initial input.
+
+     If EXISTING is non-`nil', then the name specified must be that of
+     an existing buffer.  The usual commands to exit the minibuffer do
+     not exit if the text is not valid, and <RET> does completion to
+     attempt to find a valid name.  (However, DEFAULT is not checked
+     for validity; it is returned, whatever it is, if the user exits
+     with the minibuffer empty.)
+
+     In the following example, the user enters `minibuffer.t', and then
+     types <RET>.  The argument EXISTING is `t', and the only buffer
+     name starting with the given input is `minibuffer.texi', so that
+     name is the value.
+
+          (read-buffer "Buffer name? " "foo" t)
+          ;; After evaluation of the preceding expression,
+          ;;   the following prompt appears,
+          ;;   with an empty minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          Buffer name? (default foo) -!-
+          ---------- Buffer: Minibuffer ----------
+          
+          ;; The user types `minibuffer.t <RET>'.
+               => "minibuffer.texi"
+
+ - Function: read-command prompt &optional default-value
+     This function reads the name of a command and returns it as a Lisp
+     symbol.  The argument PROMPT is used as in `read-from-minibuffer'.
+     Recall that a command is anything for which `commandp' returns
+     `t', and a command name is a symbol for which `commandp' returns
+     `t'.  *Note Interactive Call::.
+
+     The argument DEFAULT-VALUE specifies what to return if the user
+     enters null input.  It can be a symbol or a string; if it is a
+     string, `read-command' interns it before returning it.  If DEFAULT
+     is `nil', that means no default has been specified; then if the
+     user enters null input, the return value is `nil'.
+
+          (read-command "Command name? ")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following prompt appears with an empty minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          Command name?
+          ---------- Buffer: Minibuffer ----------
+
+     If the user types `forward-c <RET>', then this function returns
+     `forward-char'.
+
+     The `read-command' function is a simplified interface to the
+     function `completing-read'.  It uses the variable `obarray' so as
+     to complete in the set of extant Lisp symbols, and it uses the
+     `commandp' predicate so as to accept only command names:
+
+          (read-command PROMPT)
+          ==
+          (intern (completing-read PROMPT obarray
+                                   'commandp t nil))
+
+ - Function: read-variable prompt &optional default-value
+     This function reads the name of a user variable and returns it as a
+     symbol.
+
+     The argument DEFAULT-VALUE specifies what to return if the user
+     enters null input.  It can be a symbol or a string; if it is a
+     string, `read-variable' interns it before returning it.  If
+     DEFAULT-VALUE is `nil', that means no default has been specified;
+     then if the user enters null input, the return value is `nil'.
+
+          (read-variable "Variable name? ")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following prompt appears,
+          ;;   with an empty minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          Variable name? -!-
+          ---------- Buffer: Minibuffer ----------
+
+     If the user then types `fill-p <RET>', `read-variable' returns
+     `fill-prefix'.
+
+     This function is similar to `read-command', but uses the predicate
+     `user-variable-p' instead of `commandp':
+
+          (read-variable PROMPT)
+          ==
+          (intern
+           (completing-read PROMPT obarray
+                            'user-variable-p t nil))
+
+
+File: lispref.info,  Node: Reading File Names,  Next: Programmed Completion,  Prev: High-Level Completion,  Up: Completion
+
+Reading File Names
+------------------
+
+   Here is another high-level completion function, designed for reading
+a file name.  It provides special features including automatic insertion
+of the default directory.
+
+ - Function: read-file-name prompt &optional directory default existing
+          initial history
+     This function reads a file name in the minibuffer, prompting with
+     PROMPT and providing completion.  If DEFAULT is non-`nil', then
+     the function returns DEFAULT if the user just types <RET>.
+     DEFAULT is not checked for validity; it is returned, whatever it
+     is, if the user exits with the minibuffer empty.
+
+     If EXISTING is non-`nil', then the user must specify the name of
+     an existing file; <RET> performs completion to make the name valid
+     if possible, and then refuses to exit if it is not valid.  If the
+     value of EXISTING is neither `nil' nor `t', then <RET> also
+     requires confirmation after completion.  If EXISTING is `nil',
+     then the name of a nonexistent file is acceptable.
+
+     The argument DIRECTORY specifies the directory to use for
+     completion of relative file names.  If `insert-default-directory'
+     is non-`nil', DIRECTORY is also inserted in the minibuffer as
+     initial input.  It defaults to the current buffer's value of
+     `default-directory'.
+
+     If you specify INITIAL, that is an initial file name to insert in
+     the buffer (after DIRECTORY, if that is inserted).  In this case,
+     point goes at the beginning of INITIAL.  The default for INITIAL
+     is `nil'--don't insert any file name.  To see what INITIAL does,
+     try the command `C-x C-v'.
+
+     Here is an example:
+
+          (read-file-name "The file is ")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following appears in the minibuffer:
+          
+          ---------- Buffer: Minibuffer ----------
+          The file is /gp/gnu/elisp/-!-
+          ---------- Buffer: Minibuffer ----------
+
+     Typing `manual <TAB>' results in the following:
+
+          ---------- Buffer: Minibuffer ----------
+          The file is /gp/gnu/elisp/manual.texi-!-
+          ---------- Buffer: Minibuffer ----------
+
+     If the user types <RET>, `read-file-name' returns the file name as
+     the string `"/gp/gnu/elisp/manual.texi"'.
+
+ - User Option: insert-default-directory
+     This variable is used by `read-file-name'.  Its value controls
+     whether `read-file-name' starts by placing the name of the default
+     directory in the minibuffer, plus the initial file name if any.
+     If the value of this variable is `nil', then `read-file-name' does
+     not place any initial input in the minibuffer (unless you specify
+     initial input with the INITIAL argument).  In that case, the
+     default directory is still used for completion of relative file
+     names, but is not displayed.
+
+     For example:
+
+          ;; Here the minibuffer starts out with the default directory.
+          (let ((insert-default-directory t))
+            (read-file-name "The file is "))
+          
+          ---------- Buffer: Minibuffer ----------
+          The file is ~lewis/manual/-!-
+          ---------- Buffer: Minibuffer ----------
+          
+          ;; Here the minibuffer is empty and only the prompt
+          ;;   appears on its line.
+          (let ((insert-default-directory nil))
+            (read-file-name "The file is "))
+          
+          ---------- Buffer: Minibuffer ----------
+          The file is -!-
+          ---------- Buffer: Minibuffer ----------
+
+
+File: lispref.info,  Node: Programmed Completion,  Prev: Reading File Names,  Up: Completion
+
+Programmed Completion
+---------------------
+
+   Sometimes it is not possible to create an alist or an obarray
+containing all the intended possible completions.  In such a case, you
+can supply your own function to compute the completion of a given
+string.  This is called "programmed completion".
+
+   To use this feature, pass a symbol with a function definition as the
+COLLECTION argument to `completing-read'.  The function
+`completing-read' arranges to pass your completion function along to
+`try-completion' and `all-completions', which will then let your
+function do all the work.
+
+   The completion function should accept three arguments:
+
+   * The string to be completed.
+
+   * The predicate function to filter possible matches, or `nil' if
+     none.  Your function should call the predicate for each possible
+     match, and ignore the possible match if the predicate returns
+     `nil'.
+
+   * A flag specifying the type of operation.
+
+   There are three flag values for three operations:
+
+   * `nil' specifies `try-completion'.  The completion function should
+     return the completion of the specified string, or `t' if the
+     string is a unique and exact match already, or `nil' if the string
+     matches no possibility.
+
+     If the string is an exact match for one possibility, but also
+     matches other longer possibilities, the function should return the
+     string, not `t'.
+
+   * `t' specifies `all-completions'.  The completion function should
+     return a list of all possible completions of the specified string.
+
+   * `lambda' specifies a test for an exact match.  The completion
+     function should return `t' if the specified string is an exact
+     match for some possibility; `nil' otherwise.
+
+   It would be consistent and clean for completion functions to allow
+lambda expressions (lists that are functions) as well as function
+symbols as COLLECTION, but this is impossible.  Lists as completion
+tables are already assigned another meaning--as alists.  It would be
+unreliable to fail to handle an alist normally because it is also a
+possible function.  So you must arrange for any function you wish to
+use for completion to be encapsulated in a symbol.
+
+   Emacs uses programmed completion when completing file names.  *Note
+File Name Completion::.
+
+
+File: lispref.info,  Node: Yes-or-No Queries,  Next: Multiple Queries,  Prev: Completion,  Up: Minibuffers
+
+Yes-or-No Queries
+=================
+
+   This section describes functions used to ask the user a yes-or-no
+question.  The function `y-or-n-p' can be answered with a single
+character; it is useful for questions where an inadvertent wrong answer
+will not have serious consequences.  `yes-or-no-p' is suitable for more
+momentous questions, since it requires three or four characters to
+answer.  Variations of these functions can be used to ask a yes-or-no
+question using a dialog box, or optionally using one.
+
+   If either of these functions is called in a command that was invoked
+using the mouse, then it uses a dialog box or pop-up menu to ask the
+question.  Otherwise, it uses keyboard input.
+
+   Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
+does not; but it seems best to describe them together.
+
+ - Function: y-or-n-p prompt
+     This function asks the user a question, expecting input in the echo
+     area.  It returns `t' if the user types `y', `nil' if the user
+     types `n'.  This function also accepts <SPC> to mean yes and <DEL>
+     to mean no.  It accepts `C-]' to mean "quit", like `C-g', because
+     the question might look like a minibuffer and for that reason the
+     user might try to use `C-]' to get out.  The answer is a single
+     character, with no <RET> needed to terminate it.  Upper and lower
+     case are equivalent.
+
+     "Asking the question" means printing PROMPT in the echo area,
+     followed by the string `(y or n) '.  If the input is not one of
+     the expected answers (`y', `n', `<SPC>', `<DEL>', or something
+     that quits), the function responds `Please answer y or n.', and
+     repeats the request.
+
+     This function does not actually use the minibuffer, since it does
+     not allow editing of the answer.  It actually uses the echo area
+     (*note The Echo Area::), which uses the same screen space as the
+     minibuffer.  The cursor moves to the echo area while the question
+     is being asked.
+
+     The answers and their meanings, even `y' and `n', are not
+     hardwired.  The keymap `query-replace-map' specifies them.  *Note
+     Search and Replace::.
+
+     In the following example, the user first types `q', which is
+     invalid.  At the next prompt the user types `y'.
+
+          (y-or-n-p "Do you need a lift? ")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following prompt appears in the echo area:
+          
+          ---------- Echo area ----------
+          Do you need a lift? (y or n)
+          ---------- Echo area ----------
+          
+          ;; If the user then types `q', the following appears:
+          
+          ---------- Echo area ----------
+          Please answer y or n.  Do you need a lift? (y or n)
+          ---------- Echo area ----------
+          
+          ;; When the user types a valid answer,
+          ;;   it is displayed after the question:
+          
+          ---------- Echo area ----------
+          Do you need a lift? (y or n) y
+          ---------- Echo area ----------
+
+     We show successive lines of echo area messages, but only one
+     actually appears on the screen at a time.
+
+ - Function: yes-or-no-p prompt
+     This function asks the user a question, expecting input in the
+     minibuffer.  It returns `t' if the user enters `yes', `nil' if the
+     user types `no'.  The user must type <RET> to finalize the
+     response.  Upper and lower case are equivalent.
+
+     `yes-or-no-p' starts by displaying PROMPT in the echo area,
+     followed by `(yes or no) '.  The user must type one of the
+     expected responses; otherwise, the function responds `Please answer
+     yes or no.', waits about two seconds and repeats the request.
+
+     `yes-or-no-p' requires more work from the user than `y-or-n-p' and
+     is appropriate for more crucial decisions.
+
+     Here is an example:
+
+          (yes-or-no-p "Do you really want to remove everything? ")
+          
+          ;; After evaluation of the preceding expression,
+          ;;   the following prompt appears,
+          ;;   with an empty minibuffer:
+          
+          ---------- Buffer: minibuffer ----------
+          Do you really want to remove everything? (yes or no)
+          ---------- Buffer: minibuffer ----------
+
+     If the user first types `y <RET>', which is invalid because this
+     function demands the entire word `yes', it responds by displaying
+     these prompts, with a brief pause between them:
+
+          ---------- Buffer: minibuffer ----------
+          Please answer yes or no.
+          Do you really want to remove everything? (yes or no)
+          ---------- Buffer: minibuffer ----------
+
+ - Function: yes-or-no-p-dialog-box prompt
+     This function asks the user a "y or n" question with a popup dialog
+     box.  It returns `t' if the answer is "yes".  PROMPT is the string
+     to display to ask the question.
+
+   The following functions ask a question either in the minibuffer or a
+dialog box, depending on whether the last user event (which presumably
+invoked this command) was a keyboard or mouse event.  When XEmacs is
+running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
+are replaced with the following functions, so that menu items bring up
+dialog boxes instead of minibuffer questions.
+
+ - Function: y-or-n-p-maybe-dialog-box prompt
+     This function asks user a "y or n" question, using either a dialog
+     box or the minibuffer, as appropriate.
+
+ - Function: yes-or-no-p-maybe-dialog-box prompt
+     This function asks user a "yes or no" question, using either a
+     dialog box or the minibuffer, as appropriate.
+
+
+File: lispref.info,  Node: Multiple Queries,  Next: Reading a Password,  Prev: Yes-or-No Queries,  Up: Minibuffers
+
+Asking Multiple Y-or-N Questions
+================================
+
+   When you have a series of similar questions to ask, such as "Do you
+want to save this buffer" for each buffer in turn, you should use
+`map-y-or-n-p' to ask the collection of questions, rather than asking
+each question individually.  This gives the user certain convenient
+facilities such as the ability to answer the whole series at once.
+
+ - Function: map-y-or-n-p prompter actor list &optional help
+          action-alist
+     This function, new in Emacs 19, asks the user a series of
+     questions, reading a single-character answer in the echo area for
+     each one.
+
+     The value of LIST specifies the objects to ask questions about.
+     It should be either a list of objects or a generator function.  If
+     it is a function, it should expect no arguments, and should return
+     either the next object to ask about, or `nil' meaning stop asking
+     questions.
+
+     The argument PROMPTER specifies how to ask each question.  If
+     PROMPTER is a string, the question text is computed like this:
+
+          (format PROMPTER OBJECT)
+
+     where OBJECT is the next object to ask about (as obtained from
+     LIST).
+
+     If not a string, PROMPTER should be a function of one argument
+     (the next object to ask about) and should return the question
+     text.  If the value is a string, that is the question to ask the
+     user.  The function can also return `t' meaning do act on this
+     object (and don't ask the user), or `nil' meaning ignore this
+     object (and don't ask the user).
+
+     The argument ACTOR says how to act on the answers that the user
+     gives.  It should be a function of one argument, and it is called
+     with each object that the user says yes for.  Its argument is
+     always an object obtained from LIST.
+
+     If the argument HELP is given, it should be a list of this form:
+
+          (SINGULAR PLURAL ACTION)
+
+     where SINGULAR is a string containing a singular noun that
+     describes the objects conceptually being acted on, PLURAL is the
+     corresponding plural noun, and ACTION is a transitive verb
+     describing what ACTOR does.
+
+     If you don't specify HELP, the default is `("object" "objects"
+     "act on")'.
+
+     Each time a question is asked, the user may enter `y', `Y', or
+     <SPC> to act on that object; `n', `N', or <DEL> to skip that
+     object; `!' to act on all following objects; <ESC> or `q' to exit
+     (skip all following objects); `.' (period) to act on the current
+     object and then exit; or `C-h' to get help.  These are the same
+     answers that `query-replace' accepts.  The keymap
+     `query-replace-map' defines their meaning for `map-y-or-n-p' as
+     well as for `query-replace'; see *Note Search and Replace::.
+
+     You can use ACTION-ALIST to specify additional possible answers
+     and what they mean.  It is an alist of elements of the form `(CHAR
+     FUNCTION HELP)', each of which defines one additional answer.  In
+     this element, CHAR is a character (the answer); FUNCTION is a
+     function of one argument (an object from LIST); HELP is a string.
+
+     When the user responds with CHAR, `map-y-or-n-p' calls FUNCTION.
+     If it returns non-`nil', the object is considered "acted upon",
+     and `map-y-or-n-p' advances to the next object in LIST.  If it
+     returns `nil', the prompt is repeated for the same object.
+
+     If `map-y-or-n-p' is called in a command that was invoked using the
+     mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
+     Info::) is either `nil' or a list--then it uses a dialog box or
+     pop-up menu to ask the question.  In this case, it does not use
+     keyboard input or the echo area.  You can force use of the mouse
+     or use of keyboard input by binding `last-nonmenu-event' to a
+     suitable value around the call.
+
+     The return value of `map-y-or-n-p' is the number of objects acted
+     on.
+
+
+File: lispref.info,  Node: Reading a Password,  Next: Minibuffer Misc,  Prev: Multiple Queries,  Up: Minibuffers
+
+Reading a Password
+==================
+
+   To read a password to pass to another program, you can use the
+function `read-passwd'.
+
+ - Function: read-passwd prompt &optional confirm default
+     This function reads a password, prompting with PROMPT.  It does
+     not echo the password as the user types it; instead, it echoes `.'
+     for each character in the password.
+
+     The optional argument CONFIRM, if non-`nil', says to read the
+     password twice and insist it must be the same both times.  If it
+     isn't the same, the user has to type it over and over until the
+     last two times match.
+
+     The optional argument DEFAULT specifies the default password to
+     return if the user enters empty input.  It is translated to `.'
+     and inserted in the minibuffer. If DEFAULT is `nil', then
+     `read-passwd' returns the null string in that case.
+
+ - User Option: passwd-invert-frame-when-keyboard-grabbed
+     If non-`nil', swap the foreground and background colors of all
+     faces while reading a password.  Default values is `t', unless
+     feature `infodock' is provided.
+
+ - User Option: passwd-echo
+     This specifies the character echoed when typing a password.  When
+     `nil', nothing is echoed.
+
+
+File: lispref.info,  Node: Minibuffer Misc,  Prev: Reading a Password,  Up: Minibuffers
+
+Minibuffer Miscellany
+=====================
+
+   This section describes some basic functions and variables related to
+minibuffers.
+
+ - Command: exit-minibuffer
+     This command exits the active minibuffer.  It is normally bound to
+     keys in minibuffer local keymaps.
+
+ - Command: self-insert-and-exit
+     This command exits the active minibuffer after inserting the last
+     character typed on the keyboard (found in `last-command-char';
+     *note Command Loop Info::).
+
+ - Command: previous-history-element n
+     This command replaces the minibuffer contents with the value of the
+     Nth previous (older) history element.
+
+ - Command: next-history-element n
+     This command replaces the minibuffer contents with the value of the
+     Nth more recent history element.
+
+ - Command: previous-matching-history-element pattern
+     This command replaces the minibuffer contents with the value of the
+     previous (older) history element that matches PATTERN (a regular
+     expression).
+
+ - Command: next-matching-history-element pattern
+     This command replaces the minibuffer contents with the value of
+     the next (newer) history element that matches PATTERN (a regular
+     expression).
+
+ - Function: minibuffer-prompt
+     This function returns the prompt string of the currently active
+     minibuffer.  If no minibuffer is active, it returns `nil'.
+
+ - Function: minibuffer-prompt-width
+     This function returns the display width of the prompt string of the
+     currently active minibuffer.  If no minibuffer is active, it
+     returns 0.
+
+ - Variable: minibuffer-setup-hook
+     This is a normal hook that is run whenever the minibuffer is
+     entered.  *Note Hooks::.
+
+ - Variable: minibuffer-exit-hook
+     This is a normal hook that is run whenever the minibuffer is
+     exited.  *Note Hooks::.
+
+ - Variable: minibuffer-help-form
+     The current value of this variable is used to rebind `help-form'
+     locally inside the minibuffer (*note Help Functions::).
+
+ - Function: active-minibuffer-window
+     This function returns the currently active minibuffer window, or
+     `nil' if none is currently active.
+
+ - Function: minibuffer-window &optional frame
+     This function returns the minibuffer window used for frame FRAME.
+     If FRAME is `nil', that stands for the current frame.  Note that
+     the minibuffer window used by a frame need not be part of that
+     frame--a frame that has no minibuffer of its own necessarily uses
+     some other frame's minibuffer window.
+
+ - Function: window-minibuffer-p &optional window
+     This function returns non-`nil' if WINDOW is a minibuffer window.
+
+   It is not correct to determine whether a given window is a
+minibuffer by comparing it with the result of `(minibuffer-window)',
+because there can be more than one minibuffer window if there is more
+than one frame.
+
+ - Function: minibuffer-window-active-p window
+     This function returns non-`nil' if WINDOW, assumed to be a
+     minibuffer window, is currently active.
+
+ - Variable: minibuffer-scroll-window
+     If the value of this variable is non-`nil', it should be a window
+     object.  When the function `scroll-other-window' is called in the
+     minibuffer, it scrolls this window.
+
+   Finally, some functions and variables deal with recursive minibuffers
+(*note Recursive Editing::):
+
+ - Function: minibuffer-depth
+     This function returns the current depth of activations of the
+     minibuffer, a nonnegative integer.  If no minibuffers are active,
+     it returns zero.
+
+ - User Option: enable-recursive-minibuffers
+     If this variable is non-`nil', you can invoke commands (such as
+     `find-file') that use minibuffers even while the minibuffer window
+     is active.  Such invocation produces a recursive editing level for
+     a new minibuffer.  The outer-level minibuffer is invisible while
+     you are editing the inner one.
+
+     This variable only affects invoking the minibuffer while the
+     minibuffer window is selected.   If you switch windows while in the
+     minibuffer, you can always invoke minibuffer commands while some
+     other window is selected.
+
+   In FSF Emacs 19, if a command name has a property
+`enable-recursive-minibuffers' that is non-`nil', then the command can
+use the minibuffer to read arguments even if it is invoked from the
+minibuffer.  The minibuffer command `next-matching-history-element'
+(normally `M-s' in the minibuffer) uses this feature.
+
+   This is not implemented in XEmacs because it is a kludge.  If you
+want to explicitly set the value of `enable-recursive-minibuffers' in
+this fashion, just use an evaluated interactive spec and bind
+`enable-recursive-minibuffers' while reading from the minibuffer.  See
+the definition of `next-matching-history-element' in `lisp/minibuf.el'.
+
+
+File: lispref.info,  Node: Command Loop,  Next: Keymaps,  Prev: Minibuffers,  Up: Top
+
+Command Loop
+************
+
+   When you run XEmacs, it enters the "editor command loop" almost
+immediately.  This loop reads events, executes their definitions, and
+displays the results.  In this chapter, we describe how these things
+are done, and the subroutines that allow Lisp programs to do them.
+
+* Menu:
+
+* Command Overview::    How the command loop reads commands.
+* Defining Commands::   Specifying how a function should read arguments.
+* Interactive Call::    Calling a command, so that it will read arguments.
+* Command Loop Info::   Variables set by the command loop for you to examine.
+* Events::		What input looks like when you read it.
+* Reading Input::       How to read input events from the keyboard or mouse.
+* Waiting::             Waiting for user input or elapsed time.
+* Quitting::            How C-g works.  How to catch or defer quitting.
+* Prefix Command Arguments::    How the commands to set prefix args work.
+* Recursive Editing::   Entering a recursive edit,
+                          and why you usually shouldn't.
+* Disabling Commands::  How the command loop handles disabled commands.
+* Command History::     How the command history is set up, and how accessed.
+* Keyboard Macros::     How keyboard macros are implemented.
+
+
+File: lispref.info,  Node: Command Overview,  Next: Defining Commands,  Up: Command Loop
+
+Command Loop Overview
+=====================
+
+   The command loop in XEmacs is a standard event loop, reading events
+one at a time with `next-event' and handling them with
+`dispatch-event'.  An event is typically a single user action, such as
+a keypress, mouse movement, or menu selection; but they can also be
+notifications from the window system, informing XEmacs that (for
+example) part of its window was just uncovered and needs to be redrawn.
+*Note Events::.  Pending events are held in a first-in, first-out list
+called the "event queue": events are read from the head of the list,
+and newly arriving events are added to the tail.  In this way, events
+are always processed in the order in which they arrive.
+
+   `dispatch-event' does most of the work of handling user actions.
+The first thing it must do is put the events together into a key
+sequence, which is a sequence of events that translates into a command.
+It does this by consulting the active keymaps, which specify what the
+valid key sequences are and how to translate them into commands.  *Note
+Key Lookup::, for information on how this is done.  The result of the
+translation should be a keyboard macro or an interactively callable
+function.  If the key is `M-x', then it reads the name of another
+command, which it then calls.  This is done by the command
+`execute-extended-command' (*note Interactive Call::).
+
+   To execute a command requires first reading the arguments for it.
+This is done by calling `command-execute' (*note Interactive Call::).
+For commands written in Lisp, the `interactive' specification says how
+to read the arguments.  This may use the prefix argument (*note Prefix
+Command Arguments::) or may read with prompting in the minibuffer
+(*note Minibuffers::).  For example, the command `find-file' has an
+`interactive' specification which says to read a file name using the
+minibuffer.  The command's function body does not use the minibuffer;
+if you call this command from Lisp code as a function, you must supply
+the file name string as an ordinary Lisp function argument.
+
+   If the command is a string or vector (i.e., a keyboard macro) then
+`execute-kbd-macro' is used to execute it.  You can call this function
+yourself (*note Keyboard Macros::).
+
+   To terminate the execution of a running command, type `C-g'.  This
+character causes "quitting" (*note Quitting::).
+
+ - Variable: pre-command-hook
+     The editor command loop runs this normal hook before each command.
+     At that time, `this-command' contains the command that is about to
+     run, and `last-command' describes the previous command.  *Note
+     Hooks::.
+
+ - Variable: post-command-hook
+     The editor command loop runs this normal hook after each command.
+     (In FSF Emacs, it is also run when the command loop is entered, or
+     reentered after an error or quit.)  At that time, `this-command'
+     describes the command that just ran, and `last-command' describes
+     the command before that.  *Note Hooks::.
+
+   Quitting is suppressed while running `pre-command-hook' and
+`post-command-hook'.  If an error happens while executing one of these
+hooks, it terminates execution of the hook, but that is all it does.
+
+
+File: lispref.info,  Node: Defining Commands,  Next: Interactive Call,  Prev: Command Overview,  Up: Command Loop
+
+Defining Commands
+=================
+
+   A Lisp function becomes a command when its body contains, at top
+level, a form that calls the special form `interactive'.  This form
+does nothing when actually executed, but its presence serves as a flag
+to indicate that interactive calling is permitted.  Its argument
+controls the reading of arguments for an interactive call.
+
+* Menu:
+
+* Using Interactive::     General rules for `interactive'.
+* Interactive Codes::     The standard letter-codes for reading arguments
+                             in various ways.
+* Interactive Examples::  Examples of how to read interactive arguments.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-17'
Index: ././info/lispref.info-17
--- ././info/lispref.info-17	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-17	Thu May 17 23:26:54 2001
@@ -0,0 +1,1287 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Using Interactive,  Next: Interactive Codes,  Up: Defining Commands
+
+Using `interactive'
+-------------------
+
+   This section describes how to write the `interactive' form that
+makes a Lisp function an interactively-callable command.
+
+ - Special Form: interactive arg-descriptor
+     This special form declares that the function in which it appears
+     is a command, and that it may therefore be called interactively
+     (via `M-x' or by entering a key sequence bound to it).  The
+     argument ARG-DESCRIPTOR declares how to compute the arguments to
+     the command when the command is called interactively.
+
+     A command may be called from Lisp programs like any other
+     function, but then the caller supplies the arguments and
+     ARG-DESCRIPTOR has no effect.
+
+     The `interactive' form has its effect because the command loop
+     (actually, its subroutine `call-interactively') scans through the
+     function definition looking for it, before calling the function.
+     Once the function is called, all its body forms including the
+     `interactive' form are executed, but at this time `interactive'
+     simply returns `nil' without even evaluating its argument.
+
+   There are three possibilities for the argument ARG-DESCRIPTOR:
+
+   * It may be omitted or `nil'; then the command is called with no
+     arguments.  This leads quickly to an error if the command requires
+     one or more arguments.
+
+   * It may be a Lisp expression that is not a string; then it should
+     be a form that is evaluated to get a list of arguments to pass to
+     the command.
+
+     If this expression reads keyboard input (this includes using the
+     minibuffer), keep in mind that the integer value of point or the
+     mark before reading input may be incorrect after reading input.
+     This is because the current buffer may be receiving subprocess
+     output; if subprocess output arrives while the command is waiting
+     for input, it could relocate point and the mark.
+
+     Here's an example of what _not_ to do:
+
+          (interactive
+           (list (region-beginning) (region-end)
+                 (read-string "Foo: " nil 'my-history)))
+
+     Here's how to avoid the problem, by examining point and the mark
+     only after reading the keyboard input:
+
+          (interactive
+           (let ((string (read-string "Foo: " nil 'my-history)))
+             (list (region-beginning) (region-end) string)))
+
+   * It may be a string; then its contents should consist of a code
+     character followed by a prompt (which some code characters use and
+     some ignore).  The prompt ends either with the end of the string
+     or with a newline.  Here is a simple example:
+
+          (interactive "bFrobnicate buffer: ")
+
+     The code letter `b' says to read the name of an existing buffer,
+     with completion.  The buffer name is the sole argument passed to
+     the command.  The rest of the string is a prompt.
+
+     If there is a newline character in the string, it terminates the
+     prompt.  If the string does not end there, then the rest of the
+     string should contain another code character and prompt,
+     specifying another argument.  You can specify any number of
+     arguments in this way.
+
+     The prompt string can use `%' to include previous argument values
+     (starting with the first argument) in the prompt.  This is done
+     using `format' (*note Formatting Strings::).  For example, here is
+     how you could read the name of an existing buffer followed by a
+     new name to give to that buffer:
+
+          (interactive "bBuffer to rename: \nsRename buffer %s to: ")
+
+     If the first character in the string is `*', then an error is
+     signaled if the buffer is read-only.
+
+     If the first character in the string is `@', and if the key
+     sequence used to invoke the command includes any mouse events, then
+     the window associated with the first of those events is selected
+     before the command is run.
+
+     If the first character in the string is `_', then this command will
+     not cause the region to be deactivated when it completes; that is,
+     `zmacs-region-stays' will be set to `t' when the command exits
+     successfully.
+
+     You can use `*', `@', and `_' together; the order does not matter.
+     Actual reading of arguments is controlled by the rest of the
+     prompt string (starting with the first character that is not `*',
+     `@', or `_').
+
+ - Function: function-interactive function
+     This function retrieves the interactive specification of FUNCTION,
+     which may be any funcallable object.  The specification will be
+     returned as the list of the symbol `interactive' and the specs.  If
+     FUNCTION is not interactive, `nil' will be returned.
+
+
+File: lispref.info,  Node: Interactive Codes,  Next: Interactive Examples,  Prev: Using Interactive,  Up: Defining Commands
+
+Code Characters for `interactive'
+---------------------------------
+
+   The code character descriptions below contain a number of key words,
+defined here as follows:
+
+Completion
+     Provide completion.  <TAB>, <SPC>, and <RET> perform name
+     completion because the argument is read using `completing-read'
+     (*note Completion::).  `?' displays a list of possible completions.
+
+Existing
+     Require the name of an existing object.  An invalid name is not
+     accepted; the commands to exit the minibuffer do not exit if the
+     current input is not valid.
+
+Default
+     A default value of some sort is used if the user enters no text in
+     the minibuffer.  The default depends on the code character.
+
+No I/O
+     This code letter computes an argument without reading any input.
+     Therefore, it does not use a prompt string, and any prompt string
+     you supply is ignored.
+
+     Even though the code letter doesn't use a prompt string, you must
+     follow it with a newline if it is not the last code character in
+     the string.
+
+Prompt
+     A prompt immediately follows the code character.  The prompt ends
+     either with the end of the string or with a newline.
+
+Special
+     This code character is meaningful only at the beginning of the
+     interactive string, and it does not look for a prompt or a newline.
+     It is a single, isolated character.
+
+   Here are the code character descriptions for use with `interactive':
+
+`*'
+     Signal an error if the current buffer is read-only.  Special.
+
+`@'
+     Select the window mentioned in the first mouse event in the key
+     sequence that invoked this command.  Special.
+
+`_'
+     Do not cause the region to be deactivated when this command
+     completes.  Special.
+
+`a'
+     A function name (i.e., a symbol satisfying `fboundp').  Existing,
+     Completion, Prompt.
+
+`b'
+     The name of an existing buffer.  By default, uses the name of the
+     current buffer (*note Buffers::).  Existing, Completion, Default,
+     Prompt.
+
+`B'
+     A buffer name.  The buffer need not exist.  By default, uses the
+     name of a recently used buffer other than the current buffer.
+     Completion, Default, Prompt.
+
+`c'
+     A character.  The cursor does not move into the echo area.  Prompt.
+
+`C'
+     A command name (i.e., a symbol satisfying `commandp').  Existing,
+     Completion, Prompt.
+
+`d'
+     The position of point, as an integer (*note Point::).  No I/O.
+
+`D'
+     A directory name.  The default is the current default directory of
+     the current buffer, `default-directory' (*note System
+     Environment::).  Existing, Completion, Default, Prompt.
+
+`e'
+     The last mouse-button or misc-user event in the key sequence that
+     invoked the command.  No I/O.
+
+     You can use `e' more than once in a single command's interactive
+     specification.  If the key sequence that invoked the command has N
+     mouse-button or misc-user events, the Nth `e' provides the Nth
+     such event.
+
+`f'
+     A file name of an existing file (*note File Names::).  The default
+     directory is `default-directory'.  Existing, Completion, Default,
+     Prompt.
+
+`F'
+     A file name.  The file need not exist.  Completion, Default,
+     Prompt.
+
+`k'
+     A key sequence (*note Keymap Terminology::).  This keeps reading
+     events until a command (or undefined command) is found in the
+     current key maps.  The key sequence argument is represented as a
+     vector of events.  The cursor does not move into the echo area.
+     Prompt.
+
+     This kind of input is used by commands such as `describe-key' and
+     `global-set-key'.
+
+`K'
+     A key sequence, whose definition you intend to change.  This works
+     like `k', except that it suppresses, for the last input event in
+     the key sequence, the conversions that are normally used (when
+     necessary) to convert an undefined key into a defined one.
+
+`m'
+     The position of the mark, as an integer.  No I/O.
+
+`n'
+     A number read with the minibuffer.  If the input is not a number,
+     the user is asked to try again.  The prefix argument, if any, is
+     not used.  Prompt.
+
+`N'
+     The raw prefix argument.  If the prefix argument is `nil', then
+     read a number as with `n'.  Requires a number.  *Note Prefix
+     Command Arguments::.  Prompt.
+
+`p'
+     The numeric prefix argument.  (Note that this `p' is lower case.)
+     No I/O.
+
+`P'
+     The raw prefix argument.  (Note that this `P' is upper case.)  No
+     I/O.
+
+`r'
+     Point and the mark, as two numeric arguments, smallest first.
+     This is the only code letter that specifies two successive
+     arguments rather than one.  No I/O.
+
+`s'
+     Arbitrary text, read in the minibuffer and returned as a string
+     (*note Text from Minibuffer::).  Terminate the input with either
+     <LFD> or <RET>.  (`C-q' may be used to include either of these
+     characters in the input.)  Prompt.
+
+`S'
+     An interned symbol whose name is read in the minibuffer.  Any
+     whitespace character terminates the input.  (Use `C-q' to include
+     whitespace in the string.)  Other characters that normally
+     terminate a symbol (e.g., parentheses and brackets) do not do so
+     here.  Prompt.
+
+`v'
+     A variable declared to be a user option (i.e., satisfying the
+     predicate `user-variable-p').  *Note High-Level Completion::.
+     Existing, Completion, Prompt.
+
+`x'
+     A Lisp object, specified with its read syntax, terminated with a
+     <LFD> or <RET>.  The object is not evaluated.  *Note Object from
+     Minibuffer::.  Prompt.
+
+`X'
+     A Lisp form is read as with `x', but then evaluated so that its
+     value becomes the argument for the command.  Prompt.
+
+
+File: lispref.info,  Node: Interactive Examples,  Prev: Interactive Codes,  Up: Defining Commands
+
+Examples of Using `interactive'
+-------------------------------
+
+   Here are some examples of `interactive':
+
+     (defun foo1 ()              ; `foo1' takes no arguments,
+         (interactive)           ;   just moves forward two words.
+         (forward-word 2))
+          => foo1
+     
+     (defun foo2 (n)             ; `foo2' takes one argument,
+         (interactive "p")       ;   which is the numeric prefix.
+         (forward-word (* 2 n)))
+          => foo2
+     
+     (defun foo3 (n)             ; `foo3' takes one argument,
+         (interactive "nCount:") ;   which is read with the Minibuffer.
+         (forward-word (* 2 n)))
+          => foo3
+     
+     (defun three-b (b1 b2 b3)
+       "Select three existing buffers.
+     Put them into three windows, selecting the last one."
+         (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
+         (delete-other-windows)
+         (split-window (selected-window) 8)
+         (switch-to-buffer b1)
+         (other-window 1)
+         (split-window (selected-window) 8)
+         (switch-to-buffer b2)
+         (other-window 1)
+         (switch-to-buffer b3))
+          => three-b
+     (three-b "*scratch*" "declarations.texi" "*mail*")
+          => nil
+
+
+File: lispref.info,  Node: Interactive Call,  Next: Command Loop Info,  Prev: Defining Commands,  Up: Command Loop
+
+Interactive Call
+================
+
+   After the command loop has translated a key sequence into a
+definition, it invokes that definition using the function
+`command-execute'.  If the definition is a function that is a command,
+`command-execute' calls `call-interactively', which reads the arguments
+and calls the command.  You can also call these functions yourself.
+
+ - Function: commandp function
+     Returns `t' if FUNCTION is suitable for calling interactively;
+     that is, if FUNCTION is a command.  Otherwise, returns `nil'.
+
+     The interactively callable objects include strings and vectors
+     (treated as keyboard macros), lambda expressions that contain a
+     top-level call to `interactive', compiled-function objects made
+     from such lambda expressions, autoload objects that are declared
+     as interactive (non-`nil' fourth argument to `autoload'), and some
+     of the primitive functions.
+
+     A symbol is `commandp' if its function definition is `commandp'.
+
+     Keys and keymaps are not commands.  Rather, they are used to look
+     up commands (*note Keymaps::).
+
+     See `documentation' in *Note Accessing Documentation::, for a
+     realistic example of using `commandp'.
+
+ - Function: call-interactively command &optional record-flag keys
+     This function calls the interactively callable function COMMAND,
+     reading arguments according to its interactive calling
+     specifications.  An error is signaled if COMMAND is not a function
+     or if it cannot be called interactively (i.e., is not a command).
+     Note that keyboard macros (strings and vectors) are not accepted,
+     even though they are considered commands, because they are not
+     functions.
+
+     If RECORD-FLAG is the symbol `lambda', the interactive calling
+     arguments for COMMAND are read and returned as a list, but the
+     function is not called on them.
+
+     If RECORD-FLAG is `t', then this command and its arguments are
+     unconditionally added to the list `command-history'.  Otherwise,
+     the command is added only if it uses the minibuffer to read an
+     argument.  *Note Command History::.
+
+ - Function: command-execute command &optional record-flag keys
+     This function executes COMMAND as an editing command.  The
+     argument COMMAND must satisfy the `commandp' predicate; i.e., it
+     must be an interactively callable function or a keyboard macro.
+
+     A string or vector as COMMAND is executed with
+     `execute-kbd-macro'.  A function is passed to
+     `call-interactively', along with the optional RECORD-FLAG.
+
+     A symbol is handled by using its function definition in its place.
+     A symbol with an `autoload' definition counts as a command if it
+     was declared to stand for an interactively callable function.
+     Such a definition is handled by loading the specified library and
+     then rechecking the definition of the symbol.
+
+ - Command: execute-extended-command prefix-argument
+     This function reads a command name from the minibuffer using
+     `completing-read' (*note Completion::).  Then it uses
+     `command-execute' to call the specified command.  Whatever that
+     command returns becomes the value of `execute-extended-command'.
+
+     If the command asks for a prefix argument, it receives the value
+     PREFIX-ARGUMENT.  If `execute-extended-command' is called
+     interactively, the current raw prefix argument is used for
+     PREFIX-ARGUMENT, and thus passed on to whatever command is run.
+
+     `execute-extended-command' is the normal definition of `M-x', so
+     it uses the string `M-x ' as a prompt.  (It would be better to
+     take the prompt from the events used to invoke
+     `execute-extended-command', but that is painful to implement.)  A
+     description of the value of the prefix argument, if any, also
+     becomes part of the prompt.
+
+          (execute-extended-command 1)
+          ---------- Buffer: Minibuffer ----------
+          1 M-x forward-word RET
+          ---------- Buffer: Minibuffer ----------
+               => t
+
+ - Function: interactive-p
+     This function returns `t' if the containing function (the one that
+     called `interactive-p') was called interactively, with the function
+     `call-interactively'.  (It makes no difference whether
+     `call-interactively' was called from Lisp or directly from the
+     editor command loop.)  If the containing function was called by
+     Lisp evaluation (or with `apply' or `funcall'), then it was not
+     called interactively.
+
+     The most common use of `interactive-p' is for deciding whether to
+     print an informative message.  As a special exception,
+     `interactive-p' returns `nil' whenever a keyboard macro is being
+     run.  This is to suppress the informative messages and speed
+     execution of the macro.
+
+     For example:
+
+          (defun foo ()
+            (interactive)
+            (and (interactive-p)
+                 (message "foo")))
+               => foo
+          
+          (defun bar ()
+            (interactive)
+            (setq foobar (list (foo) (interactive-p))))
+               => bar
+          
+          ;; Type `M-x foo'.
+               -| foo
+          
+          ;; Type `M-x bar'.
+          ;; This does not print anything.
+          
+          foobar
+               => (nil t)
+
+
+File: lispref.info,  Node: Command Loop Info,  Next: Events,  Prev: Interactive Call,  Up: Command Loop
+
+Information from the Command Loop
+=================================
+
+   The editor command loop sets several Lisp variables to keep status
+records for itself and for commands that are run.
+
+ - Variable: last-command
+     This variable records the name of the previous command executed by
+     the command loop (the one before the current command).  Normally
+     the value is a symbol with a function definition, but this is not
+     guaranteed.
+
+     The value is copied from `this-command' when a command returns to
+     the command loop, except when the command specifies a prefix
+     argument for the following command.
+
+ - Variable: this-command
+     This variable records the name of the command now being executed by
+     the editor command loop.  Like `last-command', it is normally a
+     symbol with a function definition.
+
+     The command loop sets this variable just before running a command,
+     and copies its value into `last-command' when the command finishes
+     (unless the command specifies a prefix argument for the following
+     command).
+
+     Some commands set this variable during their execution, as a flag
+     for whatever command runs next.  In particular, the functions for
+     killing text set `this-command' to `kill-region' so that any kill
+     commands immediately following will know to append the killed text
+     to the previous kill.
+
+   If you do not want a particular command to be recognized as the
+previous command in the case where it got an error, you must code that
+command to prevent this.  One way is to set `this-command' to `t' at the
+beginning of the command, and set `this-command' back to its proper
+value at the end, like this:
+
+     (defun foo (args...)
+       (interactive ...)
+       (let ((old-this-command this-command))
+         (setq this-command t)
+         ...do the work...
+         (setq this-command old-this-command)))
+
+ - Function: this-command-keys
+     This function returns a vector containing the key and mouse events
+     that invoked the present command, plus any previous commands that
+     generated the prefix argument for this command. (Note: this is not
+     the same as in FSF Emacs, which can return a string.)  *Note
+     Events::.
+
+     This function copies the vector and the events; it is safe to keep
+     and modify them.
+
+          (this-command-keys)
+          ;; Now use `C-u C-x C-e' to evaluate that.
+               => [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
+
+ - Variable: last-command-event
+     This variable is set to the last input event that was read by the
+     command loop as part of a command.  The principal use of this
+     variable is in `self-insert-command', which uses it to decide which
+     character to insert.
+
+     This variable is off limits: you may not set its value or modify
+     the event that is its value, as it is destructively modified by
+     `read-key-sequence'.  If you want to keep a pointer to this value,
+     you must use `copy-event'.
+
+     Note that this variable is an alias for `last-command-char' in FSF
+     Emacs.
+
+          last-command-event
+          ;; Now type `C-u C-x C-e'.
+               => #<keypress-event control-E>
+
+ - Variable: last-command-char
+     If the value of `last-command-event' is a keyboard event, then this
+     is the nearest character equivalent to it (or `nil' if there is no
+     character equivalent).  `last-command-char' is the character that
+     `self-insert-command' will insert in the buffer.  Remember that
+     there is _not_ a one-to-one mapping between keyboard events and
+     XEmacs characters: many keyboard events have no corresponding
+     character, and when the Mule feature is available, most characters
+     can not be input on standard keyboards, except possibly with help
+     from an input method.  So writing code that examines this variable
+     to determine what key has been typed is bad practice, unless you
+     are certain that it will be one of a small set of characters.
+
+     This variable exists for compatibility with Emacs version 18.
+
+          last-command-char
+          ;; Now use `C-u C-x C-e' to evaluate that.
+               => ?\^E
+
+
+ - Variable: current-mouse-event
+     This variable holds the mouse-button event which invoked this
+     command, or `nil'.  This is what `(interactive "e")' returns.
+
+ - Variable: echo-keystrokes
+     This variable determines how much time should elapse before command
+     characters echo.  Its value must be an integer, which specifies the
+     number of seconds to wait before echoing.  If the user types a
+     prefix key (say `C-x') and then delays this many seconds before
+     continuing, the key `C-x' is echoed in the echo area.  Any
+     subsequent characters in the same command will be echoed as well.
+
+     If the value is zero, then command input is not echoed.
+
+
+File: lispref.info,  Node: Events,  Next: Reading Input,  Prev: Command Loop Info,  Up: Command Loop
+
+Events
+======
+
+   The XEmacs command loop reads a sequence of "events" that represent
+keyboard or mouse activity.  Unlike in Emacs 18 and in FSF Emacs,
+events are a primitive Lisp type that must be manipulated using their
+own accessor and settor primitives.  This section describes the
+representation and meaning of input events in detail.
+
+   A key sequence that starts with a mouse event is read using the
+keymaps of the buffer in the window that the mouse was in, not the
+current buffer.  This does not imply that clicking in a window selects
+that window or its buffer--that is entirely under the control of the
+command binding of the key sequence.
+
+   For information about how exactly the XEmacs command loop works,
+*Note Reading Input::.
+
+ - Function: eventp object
+     This function returns non-`nil' if OBJECT is an input event.
+
+* Menu:
+
+* Event Types::			Events come in different types.
+* Event Contents::		What the contents of each event type are.
+* Event Predicates::		Querying whether an event is of a
+				  particular type.
+* Accessing Mouse Event Positions::
+				Determining where a mouse event occurred,
+				  and over what.
+* Accessing Other Event Info::  Accessing non-positional event info.
+* Working With Events::		Creating, copying, and destroying events.
+* Converting Events::		Converting between events, keys, and
+				  characters.
+
+
+File: lispref.info,  Node: Event Types,  Next: Event Contents,  Up: Events
+
+Event Types
+-----------
+
+   Events represent keyboard or mouse activity or status changes of
+various sorts, such as process input being available or a timeout being
+triggered.  The different event types are as follows:
+
+key-press event
+     A key was pressed.  Note that modifier keys such as "control",
+     "shift", and "alt" do not generate events; instead, they are
+     tracked internally by XEmacs, and non-modifier key presses
+     generate events that specify both the key pressed and the
+     modifiers that were held down at the time.
+
+button-press event
+button-release event
+     A button was pressed or released.  Along with the button that was
+     pressed or released, button events specify the modifier keys that
+     were held down at the time and the position of the pointer at the
+     time.
+
+motion event
+     The pointer was moved.  Along with the position of the pointer,
+     these events also specify the modifier keys that were held down at
+     the time.
+
+misc-user event
+     A menu item was selected, the scrollbar was used, or a drag or a
+     drop occurred.
+
+process event
+     Input is available on a process.
+
+timeout event
+     A timeout has triggered.
+
+magic event
+     Some window-system-specific action (such as a frame being resized
+     or a portion of a frame needing to be redrawn) has occurred.  The
+     contents of this event are not accessible at the E-Lisp level, but
+     `dispatch-event' knows what to do with an event of this type.
+
+eval event
+     This is a special kind of event specifying that a particular
+     function needs to be called when this event is dispatched.  An
+     event of this type is sometimes placed in the event queue when a
+     magic event is processed.  This kind of event should generally
+     just be passed off to `dispatch-event'.  *Note Dispatching an
+     Event::.
+
+
+File: lispref.info,  Node: Event Contents,  Next: Event Predicates,  Prev: Event Types,  Up: Events
+
+Contents of the Different Types of Events
+-----------------------------------------
+
+   Every event, no matter what type it is, contains a timestamp (which
+is typically an offset in milliseconds from when the X server was
+started) indicating when the event occurred.  In addition, many events
+contain a "channel", which specifies which frame the event occurred on,
+and/or a value indicating which modifier keys (shift, control, etc.)
+were held down at the time of the event.
+
+   The contents of each event are as follows:
+
+key-press event
+
+    channel
+
+    timestamp
+
+    key
+          Which key was pressed.  This is an integer (in the printing
+          ASCII range: >32 and <127) or a symbol such as `left' or
+          `right'.  Note that many physical keys are actually treated
+          as two separate keys, depending on whether the shift key is
+          pressed; for example, the "a" key is treated as either "a" or
+          "A" depending on the state of the shift key, and the "1" key
+          is similarly treated as either "1" or "!" on most keyboards.
+          In such cases, the shift key does not show up in the modifier
+          list.  For other keys, such as `backspace', the shift key
+          shows up as a regular modifier.
+
+    modifiers
+          Which modifier keys were pressed.  As mentioned above, the
+          shift key is not treated as a modifier for many keys and will
+          not show up in this list in such cases.
+
+button-press event
+button-release event
+
+    channel
+
+    timestamp
+
+    button
+          What button went down or up.  Buttons are numbered starting
+          at 1.
+
+    modifiers
+          Which modifier keys were pressed.  The special business
+          mentioned above for the shift key does _not_ apply to mouse
+          events.
+
+    x
+    y
+          The position of the pointer (in pixels) at the time of the
+          event.
+
+pointer-motion event
+
+    channel
+
+    timestamp
+
+    x
+    y
+          The position of the pointer (in pixels) after it moved.
+
+    modifiers
+          Which modifier keys were pressed.  The special business
+          mentioned above for the shift key does _not_ apply to mouse
+          events.
+
+misc-user event
+
+    timestamp
+
+    function
+          The E-Lisp function to call for this event.  This is normally
+          either `eval' or `call-interactively'.
+
+    object
+          The object to pass to the function.  This is normally the
+          callback that was specified in the menu description.
+
+    button
+          What button went down or up.  Buttons are numbered starting
+          at 1.
+
+    modifiers
+          Which modifier keys were pressed.  The special business
+          mentioned above for the shift key does _not_ apply to mouse
+          events.
+
+    x
+    y
+          The position of the pointer (in pixels) at the time of the
+          event.
+
+process_event
+
+    timestamp
+
+    process
+          The Emacs "process" object in question.
+
+timeout event
+
+    timestamp
+
+    function
+          The E-Lisp function to call for this timeout.  It is called
+          with one argument, the event.
+
+    object
+          Some Lisp object associated with this timeout, to make it
+          easier to tell them apart.  The function and object for this
+          event were specified when the timeout was set.
+
+magic event
+
+    timestamp
+     (The rest of the information in this event is not user-accessible.)
+
+eval event
+
+    timestamp
+
+    function
+          An E-Lisp function to call when this event is dispatched.
+
+    object
+          The object to pass to the function.  The function and object
+          are set when the event is created.
+
+ - Function: event-type event
+     Return the type of EVENT.
+
+     This will be a symbol; one of
+
+    `key-press'
+          A key was pressed.
+
+    `button-press'
+          A mouse button was pressed.
+
+    `button-release'
+          A mouse button was released.
+
+    `motion'
+          The mouse moved.
+
+    `misc-user'
+          Some other user action happened; typically, this is a menu
+          selection, scrollbar action, or drag and drop action.
+
+    `process'
+          Input is available from a subprocess.
+
+    `timeout'
+          A timeout has expired.
+
+    `eval'
+          This causes a specified action to occur when dispatched.
+
+    `magic'
+          Some window-system-specific event has occurred.
+
+
+File: lispref.info,  Node: Event Predicates,  Next: Accessing Mouse Event Positions,  Prev: Event Contents,  Up: Events
+
+Event Predicates
+----------------
+
+   The following predicates return whether an object is an event of a
+particular type.
+
+ - Function: key-press-event-p object
+     This is true if OBJECT is a key-press event.
+
+ - Function: button-event-p object
+     This is true if OBJECT is a mouse button-press or button-release
+     event.
+
+ - Function: button-press-event-p object
+     This is true if OBJECT is a mouse button-press event.
+
+ - Function: button-release-event-p object
+     This is true if OBJECT is a mouse button-release event.
+
+ - Function: motion-event-p object
+     This is true if OBJECT is a mouse motion event.
+
+ - Function: mouse-event-p object
+     This is true if OBJECT is a mouse button-press, button-release or
+     motion event.
+
+ - Function: eval-event-p object
+     This is true if OBJECT is an eval event.
+
+ - Function: misc-user-event-p object
+     This is true if OBJECT is a misc-user event.
+
+ - Function: process-event-p object
+     This is true if OBJECT is a process event.
+
+ - Function: timeout-event-p object
+     This is true if OBJECT is a timeout event.
+
+ - Function: event-live-p object
+     This is true if OBJECT is any event that has not been deallocated.
+
+
+File: lispref.info,  Node: Accessing Mouse Event Positions,  Next: Accessing Other Event Info,  Prev: Event Predicates,  Up: Events
+
+Accessing the Position of a Mouse Event
+---------------------------------------
+
+   Unlike other events, mouse events (i.e. motion, button-press,
+button-release, and drag or drop type misc-user events) occur in a
+particular location on the screen. Many primitives are provided for
+determining exactly where the event occurred and what is under that
+location.
+
+* Menu:
+
+* Frame-Level Event Position Info::
+* Window-Level Event Position Info::
+* Event Text Position Info::
+* Event Glyph Position Info::
+* Event Toolbar Position Info::
+* Other Event Position Info::
+
+
+File: lispref.info,  Node: Frame-Level Event Position Info,  Next: Window-Level Event Position Info,  Up: Accessing Mouse Event Positions
+
+Frame-Level Event Position Info
+...............................
+
+   The following functions return frame-level information about where a
+mouse event occurred.
+
+ - Function: event-frame event
+     This function returns the "channel" or frame that the given mouse
+     motion, button press, button release, or misc-user event occurred
+     in.  This will be `nil' for non-mouse events.
+
+ - Function: event-x-pixel event
+     This function returns the X position in pixels of the given mouse
+     event.  The value returned is relative to the frame the event
+     occurred in.  This will signal an error if the event is not a
+     mouse event.
+
+ - Function: event-y-pixel event
+     This function returns the Y position in pixels of the given mouse
+     event.  The value returned is relative to the frame the event
+     occurred in.  This will signal an error if the event is not a
+     mouse event.
+
+
+File: lispref.info,  Node: Window-Level Event Position Info,  Next: Event Text Position Info,  Prev: Frame-Level Event Position Info,  Up: Accessing Mouse Event Positions
+
+Window-Level Event Position Info
+................................
+
+   The following functions return window-level information about where
+a mouse event occurred.
+
+ - Function: event-window event
+     Given a mouse motion, button press, button release, or misc-user
+     event, compute and return the window on which that event occurred.
+     This may be `nil' if the event occurred in the border or over a
+     toolbar.  The modeline is considered to be within the window it
+     describes.
+
+ - Function: event-buffer event
+     Given a mouse motion, button press, button release, or misc-user
+     event, compute and return the buffer of the window on which that
+     event occurred.  This may be `nil' if the event occurred in the
+     border or over a toolbar.  The modeline is considered to be within
+     the window it describes.  This is equivalent to calling
+     `event-window' and then calling `window-buffer' on the result if
+     it is a window.
+
+ - Function: event-window-x-pixel event
+     This function returns the X position in pixels of the given mouse
+     event.  The value returned is relative to the window the event
+     occurred in.  This will signal an error if the event is not a
+     mouse-motion, button-press, button-release, or misc-user event.
+
+ - Function: event-window-y-pixel event
+     This function returns the Y position in pixels of the given mouse
+     event.  The value returned is relative to the window the event
+     occurred in.  This will signal an error if the event is not a
+     mouse-motion, button-press, button-release, or misc-user event.
+
+
+File: lispref.info,  Node: Event Text Position Info,  Next: Event Glyph Position Info,  Prev: Window-Level Event Position Info,  Up: Accessing Mouse Event Positions
+
+Event Text Position Info
+........................
+
+   The following functions return information about the text (including
+the modeline) that a mouse event occurred over or near.
+
+ - Function: event-over-text-area-p event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event, this function returns `t' if the event is over the text
+     area of a window.  Otherwise, `nil' is returned.  The modeline is
+     not considered to be part of the text area.
+
+ - Function: event-over-modeline-p event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event, this function returns `t' if the event is over the modeline
+     of a window.  Otherwise, `nil' is returned.
+
+ - Function: event-x event
+     This function returns the X position of the given mouse-motion,
+     button-press, button-release, or misc-user event in characters.
+     This is relative to the window the event occurred over.
+
+ - Function: event-y event
+     This function returns the Y position of the given mouse-motion,
+     button-press, button-release, or misc-user event in characters.
+     This is relative to the window the event occurred over.
+
+ - Function: event-point event
+     This function returns the character position of the given
+     mouse-motion, button-press, button-release, or misc-user event.
+     If the event did not occur over a window, or did not occur over
+     text, then this returns `nil'.  Otherwise, it returns an index
+     into the buffer visible in the event's window.
+
+ - Function: event-closest-point event
+     This function returns the character position of the given
+     mouse-motion, button-press, button-release, or misc-user event.
+     If the event did not occur over a window or over text, it returns
+     the closest point to the location of the event.  If the Y pixel
+     position overlaps a window and the X pixel position is to the left
+     of that window, the closest point is the beginning of the line
+     containing the Y position.  If the Y pixel position overlaps a
+     window and the X pixel position is to the right of that window,
+     the closest point is the end of the line containing the Y
+     position.  If the Y pixel position is above a window, 0 is
+     returned.  If it is below a window, the value of `(window-end)' is
+     returned.
+
+
+File: lispref.info,  Node: Event Glyph Position Info,  Next: Event Toolbar Position Info,  Prev: Event Text Position Info,  Up: Accessing Mouse Event Positions
+
+Event Glyph Position Info
+.........................
+
+   The following functions return information about the glyph (if any)
+that a mouse event occurred over.
+
+ - Function: event-over-glyph-p event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event, this function returns `t' if the event is over a glyph.
+     Otherwise, `nil' is returned.
+
+ - Function: event-glyph-extent event
+     If the given mouse-motion, button-press, button-release, or
+     misc-user event happened on top of a glyph, this returns its
+     extent; else `nil' is returned.
+
+ - Function: event-glyph-x-pixel event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event over a glyph, this function returns the X position of the
+     pointer relative to the upper left of the glyph.  If the event is
+     not over a glyph, it returns `nil'.
+
+ - Function: event-glyph-y-pixel event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event over a glyph, this function returns the Y position of the
+     pointer relative to the upper left of the glyph.  If the event is
+     not over a glyph, it returns `nil'.
+
+
+File: lispref.info,  Node: Event Toolbar Position Info,  Next: Other Event Position Info,  Prev: Event Glyph Position Info,  Up: Accessing Mouse Event Positions
+
+Event Toolbar Position Info
+...........................
+
+ - Function: event-over-toolbar-p event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event, this function returns `t' if the event is over a toolbar.
+     Otherwise, `nil' is returned.
+
+ - Function: event-toolbar-button event
+     If the given mouse-motion, button-press, button-release, or
+     misc-user event happened on top of a toolbar button, this function
+     returns the button.  Otherwise, `nil' is returned.
+
+
+File: lispref.info,  Node: Other Event Position Info,  Prev: Event Toolbar Position Info,  Up: Accessing Mouse Event Positions
+
+Other Event Position Info
+.........................
+
+ - Function: event-over-border-p event
+     Given a mouse-motion, button-press, button-release, or misc-user
+     event, this function returns `t' if the event is over an internal
+     toolbar.  Otherwise, `nil' is returned.
+
+
+File: lispref.info,  Node: Accessing Other Event Info,  Next: Working With Events,  Prev: Accessing Mouse Event Positions,  Up: Events
+
+Accessing the Other Contents of Events
+--------------------------------------
+
+   The following functions allow access to the contents of events other
+than the position info described in the previous section.
+
+ - Function: event-timestamp event
+     This function returns the timestamp of the given event object.
+
+ - Function: event-device event
+     This function returns the device that the given event occurred on.
+
+ - Function: event-key event
+     This function returns the Keysym of the given key-press event.
+     This will be the ASCII code of a printing character, or a symbol.
+
+ - Function: event-button event
+     This function returns the button-number of the given button-press
+     or button-release event.
+
+ - Function: event-modifiers event
+     This function returns a list of symbols, the names of the modifier
+     keys which were down when the given mouse or keyboard event was
+     produced.
+
+ - Function: event-modifier-bits event
+     This function returns a number representing the modifier keys
+     which were down when the given mouse or keyboard event was
+     produced.
+
+ - Function: event-function event
+     This function returns the callback function of the given timeout,
+     misc-user, or eval event.
+
+ - Function: event-object event
+     This function returns the callback function argument of the given
+     timeout, misc-user, or eval event.
+
+ - Function: event-process event
+     This function returns the process of the given process event.
+
+
+File: lispref.info,  Node: Working With Events,  Next: Converting Events,  Prev: Accessing Other Event Info,  Up: Events
+
+Working With Events
+-------------------
+
+   XEmacs provides primitives for creating, copying, and destroying
+event objects.  Many functions that return events take an event object
+as an argument and fill in the fields of this event; or they make accept
+either an event object or `nil', creating the event object first in the
+latter case.
+
+ - Function: make-event &optional type plist
+     This function creates a new event structure.  If no arguments are
+     specified, the created event will be empty.  To specify the event
+     type, use the TYPE argument.  The allowed types are `empty',
+     `key-press', `button-press', `button-release', `motion', or
+     `misc-user'.
+
+     PLIST is a property list, the properties being compatible to those
+     returned by `event-properties'.  For events other than `empty', it
+     is mandatory to specify certain properties.  For `empty' events,
+     PLIST must be `nil'.  The list is "canonicalized", which means
+     that if a property keyword is present more than once, only the
+     first instance is taken into account.  Specifying an unknown or
+     illegal property signals an error.
+
+     The following properties are allowed:
+
+    `channel'
+          The event channel.  This is a frame or a console.  For mouse
+          events (of type `button-press', `button-release' and
+          `motion'), this must be a frame.  For key-press events, it
+          must be a console.  If channel is unspecified by PLIST, it
+          will be set to the selected frame or selected console, as
+          appropriate.
+
+    `key'
+          The event key.  This is either a symbol or a character.  It
+          is allowed (and required) only for key-press events.
+
+    `button'
+          The event button.  This an integer, either 1, 2 or 3.  It is
+          allowed only for button-press and button-release events.
+
+    `modifiers'
+          The event modifiers.  This is a list of modifier symbols.  It
+          is allowed for key-press, button-press, button-release and
+          motion events.
+
+    `x'
+          The event X coordinate.  This is an integer.  It is relative
+          to the channel's root window, and is allowed for
+          button-press, button-release and motion events.
+
+    `y'
+          The event Y coordinate.  This is an integer.  It is relative
+          to the channel's root window, and is allowed for
+          button-press, button-release and motion events.  This means
+          that, for instance, to access the toolbar, the `y' property
+          will have to be negative.
+
+    `timestamp'
+          The event timestamp, a non-negative integer.  Allowed for all
+          types of events.
+
+     _WARNING_: the event object returned by this function may be a
+     reused one; see the function `deallocate-event'.
+
+     The events created by `make-event' can be used as non-interactive
+     arguments to the functions with an `(interactive "e")'
+     specification.
+
+     Here are some basic examples of usage:
+
+          ;; Create an empty event.
+          (make-event)
+               => #<empty-event>
+          
+          ;; Try creating a key-press event.
+          (make-event 'key-press)
+               error--> Undefined key for keypress event
+          
+          ;; Creating a key-press event, try 2
+          (make-event 'key-press '(key home))
+               => #<keypress-event home>
+          
+          ;; Create a key-press event of dubious fame.
+          (make-event 'key-press '(key escape modifiers (meta alt control shift)))
+               => #<keypress-event control-meta-alt-shift-escape>
+          
+          ;; Create a M-button1 event at coordinates defined by variables
+          ;; X and Y.
+          (make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
+               => #<buttondown-event meta-button1>
+          
+          ;; Create a similar button-release event.
+          (make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
+               => #<buttonup-event meta-button1up>
+          
+          ;; Create a mouse-motion event.
+          (make-event 'motion '(x 20 y 30))
+               => #<motion-event 20, 30>
+          
+          (event-properties (make-event 'motion '(x 20 y 30)))
+               => (channel #<x-frame "emacs" 0x8e2> x 20 y 30
+                   modifiers nil timestamp 0)
+
+     In conjunction with `event-properties', you can use `make-event'
+     to create modified copies of existing events.  For instance, the
+     following code will return an `equal' copy of EVENT:
+
+          (make-event (event-type EVENT)
+                      (event-properties EVENT))
+
+     Note, however, that you cannot use `make-event' as the generic
+     replacement for `copy-event', because it does not allow creating
+     all of the event types.
+
+     To create a modified copy of an event, you can use the
+     canonicalization feature of PLIST.  The following example creates
+     a copy of EVENT, but with `modifiers' reset to `nil'.
+
+          (make-event (event-type EVENT)
+                      (append '(modifiers nil)
+                              (event-properties EVENT)))
+
+ - Function: copy-event event1 &optional event2
+     This function makes a copy of the event object EVENT1.  If a
+     second event argument EVENT2 is given, EVENT1 is copied into
+     EVENT2 and EVENT2 is returned.  If EVENT2 is not supplied (or is
+     `nil') then a new event will be made, as with `make-event'.
+
+ - Function: deallocate-event event
+     This function allows the given event structure to be reused.  You
+     *MUST NOT* use this event object after calling this function with
+     it.  You will lose.  It is not necessary to call this function, as
+     event objects are garbage-collected like all other objects;
+     however, it may be more efficient to explicitly deallocate events
+     when you are sure that it is safe to do so.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-18'
Index: ././info/lispref.info-18
--- ././info/lispref.info-18	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-18	Thu May 17 23:26:54 2001
@@ -0,0 +1,1125 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Converting Events,  Prev: Working With Events,  Up: Events
+
+Converting Events
+-----------------
+
+   XEmacs provides some auxiliary functions for converting between
+events and other ways of representing keys.  These are useful when
+working with ASCII strings and with keymaps.
+
+ - Function: character-to-event key-description &optional event console
+          use-console-meta-flag
+     This function converts a keystroke description to an event
+     structure.  KEY-DESCRIPTION is the specification of a key stroke,
+     and EVENT is the event object to fill in.  This function contains
+     knowledge about what the codes "mean"--for example, the number 9 is
+     converted to the character <Tab>, not the distinct character
+     <Control-I>.
+
+     Note that KEY-DESCRIPTION can be an integer, a character, a symbol
+     such as `clear' or a list such as `(control backspace)'.
+
+     If optional arg EVENT is non-`nil', it is modified; otherwise, a
+     new event object is created.  In both cases, the event is returned.
+
+     Optional third arg CONSOLE is the console to store in the event,
+     and defaults to the selected console.
+
+     If KEY-DESCRIPTION is an integer or character, the high bit may be
+     interpreted as the meta key. (This is done for backward
+     compatibility in lots of places.)  If USE-CONSOLE-META-FLAG is
+     `nil', this will always be the case.  If USE-CONSOLE-META-FLAG is
+     non-`nil', the `meta' flag for CONSOLE affects whether the high
+     bit is interpreted as a meta key. (See `set-input-mode'.)  If you
+     don't want this silly meta interpretation done, you should pass in
+     a list containing the character.
+
+     Beware that `character-to-event' and `event-to-character' are not
+     strictly inverse functions, since events contain much more
+     information than the ASCII character set can encode.
+
+ - Function: event-to-character event &optional allow-extra-modifiers
+          allow-meta allow-non-ascii
+     This function returns the closest ASCII approximation to EVENT.
+     If the event isn't a keypress, this returns `nil'.
+
+     If ALLOW-EXTRA-MODIFIERS is non-`nil', then this is lenient in its
+     translation; it will ignore modifier keys other than <control> and
+     <meta>, and will ignore the <shift> modifier on those characters
+     which have no shifted ASCII equivalent (<Control-Shift-A> for
+     example, will be mapped to the same ASCII code as <Control-A>).
+
+     If ALLOW-META is non-`nil', then the <Meta> modifier will be
+     represented by turning on the high bit of the byte returned;
+     otherwise, `nil' will be returned for events containing the <Meta>
+     modifier.
+
+     If ALLOW-NON-ASCII is non-`nil', then characters which are present
+     in the prevailing character set (*note variable
+     `character-set-property': Keymaps.) will be returned as their code
+     in that character set, instead of the return value being
+     restricted to ASCII.
+
+     Note that specifying both ALLOW-META and ALLOW-NON-ASCII is
+     ambiguous, as both use the high bit; <M-x> and <oslash> will be
+     indistinguishable.
+
+ - Function: events-to-keys events &optional no-mice
+     Given a vector of event objects, this function returns a vector of
+     key descriptors, or a string (if they all fit in the ASCII range).
+     Optional arg NO-MICE means that button events are not allowed.
+
+
+File: lispref.info,  Node: Reading Input,  Next: Waiting,  Prev: Events,  Up: Command Loop
+
+Reading Input
+=============
+
+   The editor command loop reads keyboard input using the function
+`next-event' and constructs key sequences out of the events using
+`dispatch-event'.  Lisp programs can also use the function
+`read-key-sequence', which reads input a key sequence at a time.  See
+also `momentary-string-display' in *Note Temporary Displays::, and
+`sit-for' in *Note Waiting::.  *Note Terminal Input::, for functions
+and variables for controlling terminal input modes and debugging
+terminal input.
+
+   For higher-level input facilities, see *Note Minibuffers::.
+
+* Menu:
+
+* Key Sequence Input::		How to read one key sequence.
+* Reading One Event::		How to read just one event.
+* Dispatching an Event::        What to do with an event once it has been read.
+* Quoted Character Input::	Asking the user to specify a character.
+* Peeking and Discarding::    	How to reread or throw away input events.
+
+
+File: lispref.info,  Node: Key Sequence Input,  Next: Reading One Event,  Up: Reading Input
+
+Key Sequence Input
+------------------
+
+   Lisp programs can read input a key sequence at a time by calling
+`read-key-sequence'; for example, `describe-key' uses it to read the
+key to describe.
+
+ - Function: read-key-sequence prompt &optional continue-echo
+          dont-downcase-last
+     This function reads a sequence of keystrokes or mouse clicks and
+     returns it as a vector of event objects read.  It keeps reading
+     events until it has accumulated a full key sequence; that is,
+     enough to specify a non-prefix command using the currently active
+     keymaps.
+
+     The vector and the event objects it contains are freshly created
+     (and so will not be side-effected by subsequent calls to this
+     function).
+
+     The function `read-key-sequence' suppresses quitting: `C-g' typed
+     while reading with this function works like any other character,
+     and does not set `quit-flag'.  *Note Quitting::.
+
+     The argument PROMPT is either a string to be displayed in the echo
+     area as a prompt, or `nil', meaning not to display a prompt.
+
+     Second optional arg CONTINUE-ECHO non-`nil' means this key echoes
+     as a continuation of the previous key.
+
+     Third optional arg DONT-DOWNCASE-LAST non-`nil' means do not
+     convert the last event to lower case.  (Normally any upper case
+     event is converted to lower case if the original event is
+     undefined and the lower case equivalent is defined.) This argument
+     is provided mostly for FSF compatibility; the equivalent effect
+     can be achieved more generally by binding
+     `retry-undefined-key-binding-unshifted' to `nil' around the call
+     to `read-key-sequence'.
+
+     If the user selects a menu item while we are prompting for a key
+     sequence, the returned value will be a vector of a single
+     menu-selection event (a misc-user event).  An error will be
+     signalled if you pass this value to `lookup-key' or a related
+     function.
+
+     In the example below, the prompt `?' is displayed in the echo area,
+     and the user types `C-x C-f'.
+
+          (read-key-sequence "?")
+          
+          ---------- Echo Area ----------
+          ?C-x C-f
+          ---------- Echo Area ----------
+          
+               => [#<keypress-event control-X> #<keypress-event control-F>]
+
+   If an input character is an upper-case letter and has no key binding,
+but its lower-case equivalent has one, then `read-key-sequence'
+converts the character to lower case.  Note that `lookup-key' does not
+perform case conversion in this way.
+
+
+File: lispref.info,  Node: Reading One Event,  Next: Dispatching an Event,  Prev: Key Sequence Input,  Up: Reading Input
+
+Reading One Event
+-----------------
+
+   The lowest level functions for command input are those which read a
+single event.  These functions often make a distinction between
+"command events", which are user actions (keystrokes and mouse
+actions), and other events, which serve as communication between XEmacs
+and the window system.
+
+ - Function: next-event &optional event prompt
+     This function reads and returns the next available event from the
+     window system or terminal driver, waiting if necessary until an
+     event is available.  Pass this object to `dispatch-event' to
+     handle it. If an event object is supplied, it is filled in and
+     returned; otherwise a new event object will be created.
+
+     Events can come directly from the user, from a keyboard macro, or
+     from `unread-command-events'.
+
+     In most cases, the function `next-command-event' is more
+     appropriate.
+
+ - Function: next-command-event &optional event prompt
+     This function returns the next available "user" event from the
+     window system or terminal driver.  Pass this object to
+     `dispatch-event' to handle it.  If an event object is supplied, it
+     is filled in and returned, otherwise a new event object will be
+     created.
+
+     The event returned will be a keyboard, mouse press, or mouse
+     release event.  If there are non-command events available (mouse
+     motion, sub-process output, etc) then these will be executed (with
+     `dispatch-event') and discarded.  This function is provided as a
+     convenience; it is equivalent to the Lisp code
+
+                  (while (progn
+                           (next-event event)
+                           (not (or (key-press-event-p event)
+                                    (button-press-event-p event)
+                                    (button-release-event-p event)
+                                    (menu-event-p event))))
+                     (dispatch-event event))
+
+     Here is what happens if you call `next-command-event' and then
+     press the right-arrow function key:
+
+          (next-command-event)
+               => #<keypress-event right>
+
+ - Function: read-char
+     This function reads and returns a character of command input.  If a
+     mouse click is detected, an error is signalled.  The character
+     typed is returned as an ASCII value.  This function is retained for
+     compatibility with Emacs 18, and is most likely the wrong thing
+     for you to be using: consider using `next-command-event' instead.
+
+ - Function: enqueue-eval-event function object
+     This function adds an eval event to the back of the queue.  The
+     eval event will be the next event read after all pending events.
+
+
+File: lispref.info,  Node: Dispatching an Event,  Next: Quoted Character Input,  Prev: Reading One Event,  Up: Reading Input
+
+Dispatching an Event
+--------------------
+
+ - Function: dispatch-event event
+     Given an event object returned by `next-event', this function
+     executes it.  This is the basic function that makes XEmacs respond
+     to user input; it also deals with notifications from the window
+     system (such as Expose events).
+
+
+File: lispref.info,  Node: Quoted Character Input,  Next: Peeking and Discarding,  Prev: Dispatching an Event,  Up: Reading Input
+
+Quoted Character Input
+----------------------
+
+   You can use the function `read-quoted-char' to ask the user to
+specify a character, and allow the user to specify a control or meta
+character conveniently, either literally or as an octal character code.
+The command `quoted-insert' uses this function.
+
+ - Function: read-quoted-char &optional prompt
+     This function is like `read-char', except that if the first
+     character read is an octal digit (0-7), it reads up to two more
+     octal digits (but stopping if a non-octal digit is found) and
+     returns the character represented by those digits in octal.
+
+     Quitting is suppressed when the first character is read, so that
+     the user can enter a `C-g'.  *Note Quitting::.
+
+     If PROMPT is supplied, it specifies a string for prompting the
+     user.  The prompt string is always displayed in the echo area,
+     followed by a single `-'.
+
+     In the following example, the user types in the octal number 177
+     (which is 127 in decimal).
+
+          (read-quoted-char "What character")
+          
+          ---------- Echo Area ----------
+          What character-177
+          ---------- Echo Area ----------
+          
+               => 127
+
+
+File: lispref.info,  Node: Peeking and Discarding,  Prev: Quoted Character Input,  Up: Reading Input
+
+Miscellaneous Event Input Features
+----------------------------------
+
+   This section describes how to "peek ahead" at events without using
+them up, how to check for pending input, and how to discard pending
+input.
+
+   See also the variables `last-command-event' and `last-command-char'
+(*Note Command Loop Info::).
+
+ - Variable: unread-command-events
+     This variable holds a list of events waiting to be read as command
+     input.  The events are used in the order they appear in the list,
+     and removed one by one as they are used.
+
+     The variable is needed because in some cases a function reads a
+     event and then decides not to use it.  Storing the event in this
+     variable causes it to be processed normally, by the command loop
+     or by the functions to read command input.
+
+     For example, the function that implements numeric prefix arguments
+     reads any number of digits.  When it finds a non-digit event, it
+     must unread the event so that it can be read normally by the
+     command loop.  Likewise, incremental search uses this feature to
+     unread events with no special meaning in a search, because these
+     events should exit the search and then execute normally.
+
+
+ - Variable: unread-command-event
+     This variable holds a single event to be read as command input.
+
+     This variable is mostly obsolete now that you can use
+     `unread-command-events' instead; it exists only to support programs
+     written for versions of XEmacs prior to 19.12.
+
+ - Function: input-pending-p
+     This function determines whether any command input is currently
+     available to be read.  It returns immediately, with value `t' if
+     there is available input, `nil' otherwise.  On rare occasions it
+     may return `t' when no input is available.
+
+ - Variable: last-input-event
+     This variable is set to the last keyboard or mouse button event
+     received.
+
+     This variable is off limits: you may not set its value or modify
+     the event that is its value, as it is destructively modified by
+     `read-key-sequence'.  If you want to keep a pointer to this value,
+     you must use `copy-event'.
+
+     Note that this variable is an alias for `last-input-char' in FSF
+     Emacs.
+
+     In the example below, a character is read (the character `1').  It
+     becomes the value of `last-input-event', while `C-e' (from the
+     `C-x C-e' command used to evaluate this expression) remains the
+     value of `last-command-event'.
+
+          (progn (print (next-command-event))
+                 (print last-command-event)
+                 last-input-event)
+               -| #<keypress-event 1>
+               -| #<keypress-event control-E>
+               => #<keypress-event 1>
+
+ - Variable: last-input-char
+     If the value of `last-input-event' is a keyboard event, then this
+     is the nearest ASCII equivalent to it.  Remember that there is
+     _not_ a 1:1 mapping between keyboard events and ASCII characters:
+     the set of keyboard events is much larger, so writing code that
+     examines this variable to determine what key has been typed is bad
+     practice, unless you are certain that it will be one of a small
+     set of characters.
+
+     This function exists for compatibility with Emacs version 18.
+
+ - Function: discard-input
+     This function discards the contents of the terminal input buffer
+     and cancels any keyboard macro that might be in the process of
+     definition.  It returns `nil'.
+
+     In the following example, the user may type a number of characters
+     right after starting the evaluation of the form.  After the
+     `sleep-for' finishes sleeping, `discard-input' discards any
+     characters typed during the sleep.
+
+          (progn (sleep-for 2)
+                 (discard-input))
+               => nil
+
+
+File: lispref.info,  Node: Waiting,  Next: Quitting,  Prev: Reading Input,  Up: Command Loop
+
+Waiting for Elapsed Time or Input
+=================================
+
+   The wait functions are designed to wait for a certain amount of time
+to pass or until there is input.  For example, you may wish to pause in
+the middle of a computation to allow the user time to view the display.
+`sit-for' pauses and updates the screen, and returns immediately if
+input comes in, while `sleep-for' pauses without updating the screen.
+
+   Note that in FSF Emacs, the commands `sit-for' and `sleep-for' take
+two arguments to specify the time (one integer and one float value),
+instead of a single argument that can be either an integer or a float.
+
+ - Function: sit-for seconds &optional nodisplay
+     This function performs redisplay (provided there is no pending
+     input from the user), then waits SECONDS seconds, or until input is
+     available.  The result is `t' if `sit-for' waited the full time
+     with no input arriving (see `input-pending-p' in *Note Peeking and
+     Discarding::).  Otherwise, the value is `nil'.
+
+     The argument SECONDS need not be an integer.  If it is a floating
+     point number, `sit-for' waits for a fractional number of seconds.
+
+     Redisplay is normally preempted if input arrives, and does not
+     happen at all if input is available before it starts. (You can
+     force screen updating in such a case by using `force-redisplay'.
+     *Note Refresh Screen::.) If there is no input pending, you can
+     force an update with no delay by using `(sit-for 0)'.
+
+     If NODISPLAY is non-`nil', then `sit-for' does not redisplay, but
+     it still returns as soon as input is available (or when the
+     timeout elapses).
+
+     The usual purpose of `sit-for' is to give the user time to read
+     text that you display.
+
+ - Function: sleep-for seconds
+     This function simply pauses for SECONDS seconds without updating
+     the display.  This function pays no attention to available input.
+     It returns `nil'.
+
+     The argument SECONDS need not be an integer.  If it is a floating
+     point number, `sleep-for' waits for a fractional number of seconds.
+
+     Use `sleep-for' when you wish to guarantee a delay.
+
+   *Note Time of Day::, for functions to get the current time.
+
+
+File: lispref.info,  Node: Quitting,  Next: Prefix Command Arguments,  Prev: Waiting,  Up: Command Loop
+
+Quitting
+========
+
+   Typing `C-g' while a Lisp function is running causes XEmacs to
+"quit" whatever it is doing.  This means that control returns to the
+innermost active command loop.
+
+   Typing `C-g' while the command loop is waiting for keyboard input
+does not cause a quit; it acts as an ordinary input character.  In the
+simplest case, you cannot tell the difference, because `C-g' normally
+runs the command `keyboard-quit', whose effect is to quit.  However,
+when `C-g' follows a prefix key, the result is an undefined key.  The
+effect is to cancel the prefix key as well as any prefix argument.
+
+   In the minibuffer, `C-g' has a different definition: it aborts out
+of the minibuffer.  This means, in effect, that it exits the minibuffer
+and then quits.  (Simply quitting would return to the command loop
+_within_ the minibuffer.)  The reason why `C-g' does not quit directly
+when the command reader is reading input is so that its meaning can be
+redefined in the minibuffer in this way.  `C-g' following a prefix key
+is not redefined in the minibuffer, and it has its normal effect of
+canceling the prefix key and prefix argument.  This too would not be
+possible if `C-g' always quit directly.
+
+   When `C-g' does directly quit, it does so by setting the variable
+`quit-flag' to `t'.  XEmacs checks this variable at appropriate times
+and quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
+thus causes a quit.
+
+   At the level of C code, quitting cannot happen just anywhere; only
+at the special places that check `quit-flag'.  The reason for this is
+that quitting at other places might leave an inconsistency in XEmacs's
+internal state.  Because quitting is delayed until a safe place,
+quitting cannot make XEmacs crash.
+
+   Certain functions such as `read-key-sequence' or `read-quoted-char'
+prevent quitting entirely even though they wait for input.  Instead of
+quitting, `C-g' serves as the requested input.  In the case of
+`read-key-sequence', this serves to bring about the special behavior of
+`C-g' in the command loop.  In the case of `read-quoted-char', this is
+so that `C-q' can be used to quote a `C-g'.
+
+   You can prevent quitting for a portion of a Lisp function by binding
+the variable `inhibit-quit' to a non-`nil' value.  Then, although `C-g'
+still sets `quit-flag' to `t' as usual, the usual result of this--a
+quit--is prevented.  Eventually, `inhibit-quit' will become `nil'
+again, such as when its binding is unwound at the end of a `let' form.
+At that time, if `quit-flag' is still non-`nil', the requested quit
+happens immediately.  This behavior is ideal when you wish to make sure
+that quitting does not happen within a "critical section" of the
+program.
+
+   In some functions (such as `read-quoted-char'), `C-g' is handled in
+a special way that does not involve quitting.  This is done by reading
+the input with `inhibit-quit' bound to `t', and setting `quit-flag' to
+`nil' before `inhibit-quit' becomes `nil' again.  This excerpt from the
+definition of `read-quoted-char' shows how this is done; it also shows
+that normal quitting is permitted after the first character of input.
+
+     (defun read-quoted-char (&optional prompt)
+       "...DOCUMENTATION..."
+       (let ((count 0) (code 0) char)
+         (while (< count 3)
+           (let ((inhibit-quit (zerop count))
+                 (help-form nil))
+             (and prompt (message "%s-" prompt))
+             (setq char (read-char))
+             (if inhibit-quit (setq quit-flag nil)))
+           ...)
+         (logand 255 code)))
+
+ - Variable: quit-flag
+     If this variable is non-`nil', then XEmacs quits immediately,
+     unless `inhibit-quit' is non-`nil'.  Typing `C-g' ordinarily sets
+     `quit-flag' non-`nil', regardless of `inhibit-quit'.
+
+ - Variable: inhibit-quit
+     This variable determines whether XEmacs should quit when
+     `quit-flag' is set to a value other than `nil'.  If `inhibit-quit'
+     is non-`nil', then `quit-flag' has no special effect.
+
+ - Command: keyboard-quit
+     This function signals the `quit' condition with `(signal 'quit
+     nil)'.  This is the same thing that quitting does.  (See `signal'
+     in *Note Errors::.)
+
+   You can specify a character other than `C-g' to use for quitting.
+See the function `set-input-mode' in *Note Terminal Input::.
+
+
+File: lispref.info,  Node: Prefix Command Arguments,  Next: Recursive Editing,  Prev: Quitting,  Up: Command Loop
+
+Prefix Command Arguments
+========================
+
+   Most XEmacs commands can use a "prefix argument", a number specified
+before the command itself.  (Don't confuse prefix arguments with prefix
+keys.)  The prefix argument is at all times represented by a value,
+which may be `nil', meaning there is currently no prefix argument.
+Each command may use the prefix argument or ignore it.
+
+   There are two representations of the prefix argument: "raw" and
+"numeric".  The editor command loop uses the raw representation
+internally, and so do the Lisp variables that store the information, but
+commands can request either representation.
+
+   Here are the possible values of a raw prefix argument:
+
+   * `nil', meaning there is no prefix argument.  Its numeric value is
+     1, but numerous commands make a distinction between `nil' and the
+     integer 1.
+
+   * An integer, which stands for itself.
+
+   * A list of one element, which is an integer.  This form of prefix
+     argument results from one or a succession of `C-u''s with no
+     digits.  The numeric value is the integer in the list, but some
+     commands make a distinction between such a list and an integer
+     alone.
+
+   * The symbol `-'.  This indicates that `M--' or `C-u -' was typed,
+     without following digits.  The equivalent numeric value is -1, but
+     some commands make a distinction between the integer -1 and the
+     symbol `-'.
+
+   We illustrate these possibilities by calling the following function
+with various prefixes:
+
+     (defun display-prefix (arg)
+       "Display the value of the raw prefix arg."
+       (interactive "P")
+       (message "%s" arg))
+
+Here are the results of calling `display-prefix' with various raw
+prefix arguments:
+
+             M-x display-prefix  -| nil
+     
+     C-u     M-x display-prefix  -| (4)
+     
+     C-u C-u M-x display-prefix  -| (16)
+     
+     C-u 3   M-x display-prefix  -| 3
+     
+     M-3     M-x display-prefix  -| 3      ; (Same as `C-u 3'.)
+     
+     C-3     M-x display-prefix  -| 3      ; (Same as `C-u 3'.)
+     
+     C-u -   M-x display-prefix  -| -
+     
+     M--     M-x display-prefix  -| -      ; (Same as `C-u -'.)
+     
+     C--     M-x display-prefix  -| -      ; (Same as `C-u -'.)
+     
+     C-u - 7 M-x display-prefix  -| -7
+     
+     M-- 7   M-x display-prefix  -| -7     ; (Same as `C-u -7'.)
+     
+     C-- 7   M-x display-prefix  -| -7     ; (Same as `C-u -7'.)
+
+   XEmacs uses two variables to store the prefix argument: `prefix-arg'
+and `current-prefix-arg'.  Commands such as `universal-argument' that
+set up prefix arguments for other commands store them in `prefix-arg'.
+In contrast, `current-prefix-arg' conveys the prefix argument to the
+current command, so setting it has no effect on the prefix arguments
+for future commands.
+
+   Normally, commands specify which representation to use for the prefix
+argument, either numeric or raw, in the `interactive' declaration.
+(*Note Using Interactive::.)  Alternatively, functions may look at the
+value of the prefix argument directly in the variable
+`current-prefix-arg', but this is less clean.
+
+ - Function: prefix-numeric-value raw
+     This function returns the numeric meaning of a valid raw prefix
+     argument value, RAW.  The argument may be a symbol, a number, or a
+     list.  If it is `nil', the value 1 is returned; if it is `-', the
+     value -1 is returned; if it is a number, that number is returned;
+     if it is a list, the CAR of that list (which should be a number) is
+     returned.
+
+ - Variable: current-prefix-arg
+     This variable holds the raw prefix argument for the _current_
+     command.  Commands may examine it directly, but the usual way to
+     access it is with `(interactive "P")'.
+
+ - Variable: prefix-arg
+     The value of this variable is the raw prefix argument for the
+     _next_ editing command.  Commands that specify prefix arguments for
+     the following command work by setting this variable.
+
+   Do not call the functions `universal-argument', `digit-argument', or
+`negative-argument' unless you intend to let the user enter the prefix
+argument for the _next_ command.
+
+ - Command: universal-argument
+     This command reads input and specifies a prefix argument for the
+     following command.  Don't call this command yourself unless you
+     know what you are doing.
+
+ - Command: digit-argument arg
+     This command adds to the prefix argument for the following
+     command.  The argument ARG is the raw prefix argument as it was
+     before this command; it is used to compute the updated prefix
+     argument.  Don't call this command yourself unless you know what
+     you are doing.
+
+ - Command: negative-argument arg
+     This command adds to the numeric argument for the next command.
+     The argument ARG is the raw prefix argument as it was before this
+     command; its value is negated to form the new prefix argument.
+     Don't call this command yourself unless you know what you are
+     doing.
+
+
+File: lispref.info,  Node: Recursive Editing,  Next: Disabling Commands,  Prev: Prefix Command Arguments,  Up: Command Loop
+
+Recursive Editing
+=================
+
+   The XEmacs command loop is entered automatically when XEmacs starts
+up.  This top-level invocation of the command loop never exits; it keeps
+running as long as XEmacs does.  Lisp programs can also invoke the
+command loop.  Since this makes more than one activation of the command
+loop, we call it "recursive editing".  A recursive editing level has
+the effect of suspending whatever command invoked it and permitting the
+user to do arbitrary editing before resuming that command.
+
+   The commands available during recursive editing are the same ones
+available in the top-level editing loop and defined in the keymaps.
+Only a few special commands exit the recursive editing level; the others
+return to the recursive editing level when they finish.  (The special
+commands for exiting are always available, but they do nothing when
+recursive editing is not in progress.)
+
+   All command loops, including recursive ones, set up all-purpose error
+handlers so that an error in a command run from the command loop will
+not exit the loop.
+
+   Minibuffer input is a special kind of recursive editing.  It has a
+few special wrinkles, such as enabling display of the minibuffer and the
+minibuffer window, but fewer than you might suppose.  Certain keys
+behave differently in the minibuffer, but that is only because of the
+minibuffer's local map; if you switch windows, you get the usual XEmacs
+commands.
+
+   To invoke a recursive editing level, call the function
+`recursive-edit'.  This function contains the command loop; it also
+contains a call to `catch' with tag `exit', which makes it possible to
+exit the recursive editing level by throwing to `exit' (*note Catch and
+Throw::).  If you throw a value other than `t', then `recursive-edit'
+returns normally to the function that called it.  The command `C-M-c'
+(`exit-recursive-edit') does this.  Throwing a `t' value causes
+`recursive-edit' to quit, so that control returns to the command loop
+one level up.  This is called "aborting", and is done by `C-]'
+(`abort-recursive-edit').
+
+   Most applications should not use recursive editing, except as part of
+using the minibuffer.  Usually it is more convenient for the user if you
+change the major mode of the current buffer temporarily to a special
+major mode, which should have a command to go back to the previous mode.
+(The `e' command in Rmail uses this technique.)  Or, if you wish to
+give the user different text to edit "recursively", create and select a
+new buffer in a special mode.  In this mode, define a command to
+complete the processing and go back to the previous buffer.  (The `m'
+command in Rmail does this.)
+
+   Recursive edits are useful in debugging.  You can insert a call to
+`debug' into a function definition as a sort of breakpoint, so that you
+can look around when the function gets there.  `debug' invokes a
+recursive edit but also provides the other features of the debugger.
+
+   Recursive editing levels are also used when you type `C-r' in
+`query-replace' or use `C-x q' (`kbd-macro-query').
+
+ - Command: recursive-edit
+     This function invokes the editor command loop.  It is called
+     automatically by the initialization of XEmacs, to let the user
+     begin editing.  When called from a Lisp program, it enters a
+     recursive editing level.
+
+     In the following example, the function `simple-rec' first advances
+     point one word, then enters a recursive edit, printing out a
+     message in the echo area.  The user can then do any editing
+     desired, and then type `C-M-c' to exit and continue executing
+     `simple-rec'.
+
+          (defun simple-rec ()
+            (forward-word 1)
+            (message "Recursive edit in progress")
+            (recursive-edit)
+            (forward-word 1))
+               => simple-rec
+          (simple-rec)
+               => nil
+
+ - Command: exit-recursive-edit
+     This function exits from the innermost recursive edit (including
+     minibuffer input).  Its definition is effectively `(throw 'exit
+     nil)'.
+
+ - Command: abort-recursive-edit
+     This function aborts the command that requested the innermost
+     recursive edit (including minibuffer input), by signaling `quit'
+     after exiting the recursive edit.  Its definition is effectively
+     `(throw 'exit t)'.  *Note Quitting::.
+
+ - Command: top-level
+     This function exits all recursive editing levels; it does not
+     return a value, as it jumps completely out of any computation
+     directly back to the main command loop.
+
+ - Function: recursion-depth
+     This function returns the current depth of recursive edits.  When
+     no recursive edit is active, it returns 0.
+
+
+File: lispref.info,  Node: Disabling Commands,  Next: Command History,  Prev: Recursive Editing,  Up: Command Loop
+
+Disabling Commands
+==================
+
+   "Disabling a command" marks the command as requiring user
+confirmation before it can be executed.  Disabling is used for commands
+which might be confusing to beginning users, to prevent them from using
+the commands by accident.
+
+   The low-level mechanism for disabling a command is to put a
+non-`nil' `disabled' property on the Lisp symbol for the command.
+These properties are normally set up by the user's `.emacs' file with
+Lisp expressions such as this:
+
+     (put 'upcase-region 'disabled t)
+
+For a few commands, these properties are present by default and may be
+removed by the `.emacs' file.
+
+   If the value of the `disabled' property is a string, the message
+saying the command is disabled includes that string.  For example:
+
+     (put 'delete-region 'disabled
+          "Text deleted this way cannot be yanked back!\n")
+
+   *Note Disabling: (xemacs)Disabling, for the details on what happens
+when a disabled command is invoked interactively.  Disabling a command
+has no effect on calling it as a function from Lisp programs.
+
+ - Command: enable-command command
+     Allow COMMAND to be executed without special confirmation from now
+     on, and (if the user confirms) alter the user's `.emacs' file so
+     that this will apply to future sessions.
+
+ - Command: disable-command command
+     Require special confirmation to execute COMMAND from now on, and
+     (if the user confirms) alter the user's `.emacs' file so that this
+     will apply to future sessions.
+
+ - Variable: disabled-command-hook
+     This normal hook is run instead of a disabled command, when the
+     user invokes the disabled command interactively.  The hook
+     functions can use `this-command-keys' to determine what the user
+     typed to run the command, and thus find the command itself.  *Note
+     Hooks::.
+
+     By default, `disabled-command-hook' contains a function that asks
+     the user whether to proceed.
+
+
+File: lispref.info,  Node: Command History,  Next: Keyboard Macros,  Prev: Disabling Commands,  Up: Command Loop
+
+Command History
+===============
+
+   The command loop keeps a history of the complex commands that have
+been executed, to make it convenient to repeat these commands.  A
+"complex command" is one for which the interactive argument reading
+uses the minibuffer.  This includes any `M-x' command, any `M-:'
+command, and any command whose `interactive' specification reads an
+argument from the minibuffer.  Explicit use of the minibuffer during
+the execution of the command itself does not cause the command to be
+considered complex.
+
+ - Variable: command-history
+     This variable's value is a list of recent complex commands, each
+     represented as a form to evaluate.  It continues to accumulate all
+     complex commands for the duration of the editing session, but all
+     but the first (most recent) thirty elements are deleted when a
+     garbage collection takes place (*note Garbage Collection::).
+
+          command-history
+          => ((switch-to-buffer "chistory.texi")
+              (describe-key "^X^[")
+              (visit-tags-table "~/emacs/src/")
+              (find-tag "repeat-complex-command"))
+
+   This history list is actually a special case of minibuffer history
+(*note Minibuffer History::), with one special twist: the elements are
+expressions rather than strings.
+
+   There are a number of commands devoted to the editing and recall of
+previous commands.  The commands `repeat-complex-command', and
+`list-command-history' are described in the user manual (*note
+Repetition: (xemacs)Repetition.).  Within the minibuffer, the history
+commands used are the same ones available in any minibuffer.
+
+
+File: lispref.info,  Node: Keyboard Macros,  Prev: Command History,  Up: Command Loop
+
+Keyboard Macros
+===============
+
+   A "keyboard macro" is a canned sequence of input events that can be
+considered a command and made the definition of a key.  The Lisp
+representation of a keyboard macro is a string or vector containing the
+events.  Don't confuse keyboard macros with Lisp macros (*note
+Macros::).
+
+ - Function: execute-kbd-macro macro &optional count
+     This function executes MACRO as a sequence of events.  If MACRO is
+     a string or vector, then the events in it are executed exactly as
+     if they had been input by the user.  The sequence is _not_
+     expected to be a single key sequence; normally a keyboard macro
+     definition consists of several key sequences concatenated.
+
+     If MACRO is a symbol, then its function definition is used in
+     place of MACRO.  If that is another symbol, this process repeats.
+     Eventually the result should be a string or vector.  If the result
+     is not a symbol, string, or vector, an error is signaled.
+
+     The argument COUNT is a repeat count; MACRO is executed that many
+     times.  If COUNT is omitted or `nil', MACRO is executed once.  If
+     it is 0, MACRO is executed over and over until it encounters an
+     error or a failing search.
+
+ - Variable: executing-macro
+     This variable contains the string or vector that defines the
+     keyboard macro that is currently executing.  It is `nil' if no
+     macro is currently executing.  A command can test this variable to
+     behave differently when run from an executing macro.  Do not set
+     this variable yourself.
+
+ - Variable: defining-kbd-macro
+     This variable indicates whether a keyboard macro is being defined.
+     A command can test this variable to behave differently while a
+     macro is being defined.  The commands `start-kbd-macro' and
+     `end-kbd-macro' set this variable--do not set it yourself.
+
+ - Variable: last-kbd-macro
+     This variable is the definition of the most recently defined
+     keyboard macro.  Its value is a string or vector, or `nil'.
+
+   The commands are described in the user's manual (*note Keyboard
+Macros: (xemacs)Keyboard Macros.).
+
+
+File: lispref.info,  Node: Keymaps,  Next: Menus,  Prev: Command Loop,  Up: Top
+
+Keymaps
+*******
+
+   The bindings between input events and commands are recorded in data
+structures called "keymaps".  Each binding in a keymap associates (or
+"binds") an individual event type either with another keymap or with a
+command.  When an event is bound to a keymap, that keymap is used to
+look up the next input event; this continues until a command is found.
+The whole process is called "key lookup".
+
+* Menu:
+
+* Keymap Terminology::       Definitions of terms pertaining to keymaps.
+* Format of Keymaps::        What a keymap looks like as a Lisp object.
+* Creating Keymaps::         Functions to create and copy keymaps.
+* Inheritance and Keymaps::  How one keymap can inherit the bindings
+                                of another keymap.
+* Key Sequences::            How to specify key sequences.
+* Prefix Keys::              Defining a key with a keymap as its definition.
+* Active Keymaps::           Each buffer has a local keymap
+                                to override the standard (global) bindings.
+                                A minor mode can also override them.
+* Key Lookup::               How extracting elements from keymaps works.
+* Functions for Key Lookup:: How to request key lookup.
+* Changing Key Bindings::    Redefining a key in a keymap.
+* Key Binding Commands::     Interactive interfaces for redefining keys.
+* Scanning Keymaps::         Looking through all keymaps, for printing help.
+* Other Keymap Functions::   Miscellaneous keymap functions.
+
+
+File: lispref.info,  Node: Keymap Terminology,  Next: Format of Keymaps,  Up: Keymaps
+
+Keymap Terminology
+==================
+
+   A "keymap" is a table mapping event types to definitions (which can
+be any Lisp objects, though only certain types are meaningful for
+execution by the command loop).  Given an event (or an event type) and a
+keymap, XEmacs can get the event's definition.  Events mapped in keymaps
+include keypresses, button presses, and button releases (*note
+Events::).
+
+   A sequence of input events that form a unit is called a "key
+sequence", or "key" for short.  A sequence of one event is always a key
+sequence, and so are some multi-event sequences.
+
+   A keymap determines a binding or definition for any key sequence.  If
+the key sequence is a single event, its binding is the definition of the
+event in the keymap.  The binding of a key sequence of more than one
+event is found by an iterative process: the binding of the first event
+is found, and must be a keymap; then the second event's binding is found
+in that keymap, and so on until all the events in the key sequence are
+used up.
+
+   If the binding of a key sequence is a keymap, we call the key
+sequence a "prefix key".  Otherwise, we call it a "complete key"
+(because no more events can be added to it).  If the binding is `nil',
+we call the key "undefined".  Examples of prefix keys are `C-c', `C-x',
+and `C-x 4'.  Examples of defined complete keys are `X', <RET>, and
+`C-x 4 C-f'.  Examples of undefined complete keys are `C-x C-g', and
+`C-c 3'.  *Note Prefix Keys::, for more details.
+
+   The rule for finding the binding of a key sequence assumes that the
+intermediate bindings (found for the events before the last) are all
+keymaps; if this is not so, the sequence of events does not form a
+unit--it is not really a key sequence.  In other words, removing one or
+more events from the end of any valid key must always yield a prefix
+key.  For example, `C-f C-n' is not a key; `C-f' is not a prefix key,
+so a longer sequence starting with `C-f' cannot be a key.
+
+   Note that the set of possible multi-event key sequences depends on
+the bindings for prefix keys; therefore, it can be different for
+different keymaps, and can change when bindings are changed.  However,
+a one-event sequence is always a key sequence, because it does not
+depend on any prefix keys for its well-formedness.
+
+   At any time, several primary keymaps are "active"--that is, in use
+for finding key bindings.  These are the "global map", which is shared
+by all buffers; the "local keymap", which is usually associated with a
+specific major mode; and zero or more "minor mode keymaps", which
+belong to currently enabled minor modes.  (Not all minor modes have
+keymaps.)  The local keymap bindings shadow (i.e., take precedence
+over) the corresponding global bindings.  The minor mode keymaps shadow
+both local and global keymaps.  *Note Active Keymaps::, for details.
+
+
+File: lispref.info,  Node: Format of Keymaps,  Next: Creating Keymaps,  Prev: Keymap Terminology,  Up: Keymaps
+
+Format of Keymaps
+=================
+
+   A keymap is a primitive type that associates events with their
+bindings.  Note that this is different from Emacs 18 and FSF Emacs,
+where keymaps are lists.
+
+ - Function: keymapp object
+     This function returns `t' if OBJECT is a keymap, `nil' otherwise.
+
+
+File: lispref.info,  Node: Creating Keymaps,  Next: Inheritance and Keymaps,  Prev: Format of Keymaps,  Up: Keymaps
+
+Creating Keymaps
+================
+
+   Here we describe the functions for creating keymaps.
+
+ - Function: make-keymap &optional name
+     This function constructs and returns a new keymap object.  All
+     entries in it are `nil', meaning "command undefined".
+
+     Optional argument NAME specifies a name to assign to the keymap,
+     as in `set-keymap-name'.  This name is only a debugging
+     convenience; it is not used except when printing the keymap.
+
+ - Function: make-sparse-keymap &optional name
+     This function constructs and returns a new keymap object.  All
+     entries in it are `nil', meaning "command undefined".  The only
+     difference between this function and `make-keymap' is that this
+     function returns a "smaller" keymap (one that is expected to
+     contain fewer entries).  As keymaps dynamically resize, this
+     distinction is not great.
+
+     Optional argument NAME specifies a name to assign to the keymap,
+     as in `set-keymap-name'.  This name is only a debugging
+     convenience; it is not used except when printing the keymap.
+
+ - Function: set-keymap-name keymap new-name
+     This function assigns a "name" to a keymap.  The name is only a
+     debugging convenience; it is not used except when printing the
+     keymap.
+
+ - Function: keymap-name keymap
+     This function returns the "name" of a keymap, as assigned using
+     `set-keymap-name'.
+
+ - Function: copy-keymap keymap
+     This function returns a copy of KEYMAP.  Any keymaps that appear
+     directly as bindings in KEYMAP are also copied recursively, and so
+     on to any number of levels.  However, recursive copying does not
+     take place when the definition of a character is a symbol whose
+     function definition is a keymap; the same symbol appears in the
+     new copy.
+
+          (setq map (copy-keymap (current-local-map)))
+          => #<keymap 3 entries 0x21f80>
+          
+          (eq map (current-local-map))
+              => nil
+
+
+File: lispref.info,  Node: Inheritance and Keymaps,  Next: Key Sequences,  Prev: Creating Keymaps,  Up: Keymaps
+
+Inheritance and Keymaps
+=======================
+
+   A keymap can inherit the bindings of other keymaps.  The other
+keymaps are called the keymap's "parents", and are set with
+`set-keymap-parents'.  When searching for a binding for a key sequence
+in a particular keymap, that keymap itself will first be searched;
+then, if no binding was found in the map and it has parents, the first
+parent keymap will be searched; then that keymap's parent will be
+searched, and so on, until either a binding for the key sequence is
+found, or a keymap without a parent is encountered.  At this point, the
+search will continue with the next parent of the most recently
+encountered keymap that has another parent, etc.  Essentially, a
+depth-first search of all the ancestors of the keymap is conducted.
+
+   `(current-global-map)' is the default parent of all keymaps.
+
+ - Function: set-keymap-parents keymap parents
+     This function sets the parent keymaps of KEYMAP to the list
+     PARENTS.
+
+     If you change the bindings in one of the keymaps in PARENTS using
+     `define-key' or other key-binding functions, these changes are
+     visible in KEYMAP unless shadowed by bindings in that map or in
+     earlier-searched ancestors.  The converse is not true: if you use
+     `define-key' to change KEYMAP, that affects the bindings in that
+     map, but has no effect on any of the keymaps in PARENTS.
+
+ - Function: keymap-parents keymap
+     This function returns the list of parent keymaps of KEYMAP, or
+     `nil' if KEYMAP has no parents.
+
+   As an alternative to specifying a parent, you can also specify a
+"default binding" that is used whenever a key is not otherwise bound in
+the keymap.  This is useful for terminal emulators, for example, which
+may want to trap all keystrokes and pass them on in some modified
+format.  Note that if you specify a default binding for a keymap,
+neither the keymap's parents nor the current global map are searched for
+key bindings.
+
+ - Function: set-keymap-default-binding keymap command
+     This function sets the default binding of KEYMAP to COMMAND, or
+     `nil' if no default is desired.
+
+ - Function: keymap-default-binding keymap
+     This function returns the default binding of KEYMAP, or `nil' if
+     it has none.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-19'
Index: ././info/lispref.info-19
--- ././info/lispref.info-19	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-19	Thu May 17 23:26:54 2001
@@ -0,0 +1,1157 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Key Sequences,  Next: Prefix Keys,  Prev: Inheritance and Keymaps,  Up: Keymaps
+
+Key Sequences
+=============
+
+   Contrary to popular belief, the world is not ASCII.  When running
+under a window manager, XEmacs can tell the difference between, for
+example, the keystrokes `control-h', `control-shift-h', and
+`backspace'.  You can, in fact, bind different commands to each of
+these.
+
+   A "key sequence" is a set of keystrokes.  A "keystroke" is a keysym
+and some set of modifiers (such as <CONTROL> and <META>).  A "keysym"
+is what is printed on the keys on your keyboard.
+
+   A keysym may be represented by a symbol, or (if and only if it is
+equivalent to an ASCII character in the range 32 - 255) by a character
+or its equivalent ASCII code.  The `A' key may be represented by the
+symbol `A', the character `?A', or by the number 65.  The `break' key
+may be represented only by the symbol `break'.
+
+   A keystroke may be represented by a list: the last element of the
+list is the key (a symbol, character, or number, as above) and the
+preceding elements are the symbolic names of modifier keys (<CONTROL>,
+<META>, <SUPER>, <HYPER>, <ALT>, and <SHIFT>).  Thus, the sequence
+`control-b' is represented by the forms `(control b)', `(control ?b)',
+and `(control 98)'.  A keystroke may also be represented by an event
+object, as returned by the `next-command-event' and `read-key-sequence'
+functions.
+
+   Note that in this context, the keystroke `control-b' is _not_
+represented by the number 2 (the ASCII code for `^B') or the character
+`?\^B'.  See below.
+
+   The <SHIFT> modifier is somewhat of a special case.  You should not
+(and cannot) use `(meta shift a)' to mean `(meta A)', since for
+characters that have ASCII equivalents, the state of the shift key is
+implicit in the keysym (`a' vs. `A').  You also cannot say `(shift =)'
+to mean `+', as that sort of thing varies from keyboard to keyboard.
+The <SHIFT> modifier is for use only with characters that do not have a
+second keysym on the same key, such as `backspace' and `tab'.
+
+   A key sequence is a vector of keystrokes.  As a degenerate case,
+elements of this vector may also be keysyms if they have no modifiers.
+That is, the `A' keystroke is represented by all of these forms:
+
+             A       ?A      65      (A)     (?A)    (65)
+             [A]     [?A]    [65]    [(A)]   [(?A)]  [(65)]
+
+   the `control-a' keystroke is represented by these forms:
+
+             (control A)     (control ?A)    (control 65)
+             [(control A)]   [(control ?A)]  [(control 65)]
+
+   the key sequence `control-c control-a' is represented by these forms:
+
+             [(control c) (control a)]       [(control ?c) (control ?a)]
+             [(control 99) (control 65)]     etc.
+
+   Mouse button clicks work just like keypresses: `(control button1)'
+means pressing the left mouse button while holding down the control
+key.  `[(control c) (shift button3)]' means `control-c', hold <SHIFT>,
+click right.
+
+   Commands may be bound to the mouse-button up-stroke rather than the
+down-stroke as well.  `button1' means the down-stroke, and `button1up'
+means the up-stroke.  Different commands may be bound to the up and
+down strokes, though that is probably not what you want, so be careful.
+
+   For backward compatibility, a key sequence may also be represented by
+a string.  In this case, it represents the key sequence(s) that would
+produce that sequence of ASCII characters in a purely ASCII world.  For
+example, a string containing the ASCII backspace character, `"\^H"',
+would represent two key sequences: `(control h)' and `backspace'.
+Binding a command to this will actually bind both of those key
+sequences.  Likewise for the following pairs:
+
+                     control h       backspace
+                     control i       tab
+                     control m       return
+                     control j       linefeed
+                     control [       escape
+                     control @      control space
+
+   After binding a command to two key sequences with a form like
+
+             (define-key global-map "\^X\^I" 'command-1)
+
+it is possible to redefine only one of those sequences like so:
+
+             (define-key global-map [(control x) (control i)] 'command-2)
+             (define-key global-map [(control x) tab] 'command-3)
+
+   Of course, all of this applies only when running under a window
+system.  If you're talking to XEmacs through a TTY connection, you
+don't get any of these features.
+
+ - Function: event-matches-key-specifier-p event key-specifier
+     This function returns non-`nil' if EVENT matches KEY-SPECIFIER,
+     which can be any valid form representing a key sequence.  This can
+     be useful, e.g., to determine if the user pressed `help-char' or
+     `quit-char'.
+
+
+File: lispref.info,  Node: Prefix Keys,  Next: Active Keymaps,  Prev: Key Sequences,  Up: Keymaps
+
+Prefix Keys
+===========
+
+   A "prefix key" has an associated keymap that defines what to do with
+key sequences that start with the prefix key.  For example, `C-x' is a
+prefix key, and it uses a keymap that is also stored in the variable
+`ctl-x-map'.  Here is a list of the standard prefix keys of XEmacs and
+their keymaps:
+
+   * `help-map' is used for events that follow `C-h'.
+
+   * `mode-specific-map' is for events that follow `C-c'.  This map is
+     not actually mode specific; its name was chosen to be informative
+     for the user in `C-h b' (`display-bindings'), where it describes
+     the main use of the `C-c' prefix key.
+
+   * `ctl-x-map' is the map used for events that follow `C-x'.  This
+     map is also the function definition of `Control-X-prefix'.
+
+   * `ctl-x-4-map' is used for events that follow `C-x 4'.
+
+   * `ctl-x-5-map' is used for events that follow `C-x 5'.
+
+   * The prefix keys `C-x n', `C-x r' and `C-x a' use keymaps that have
+     no special name.
+
+   * `esc-map' is an evil hack that is present for compatibility
+     purposes with Emacs 18.  Defining a key in `esc-map' is equivalent
+     to defining the same key in `global-map' but with the <META>
+     prefix added.  You should _not_ use this in your code. (This map is
+     also the function definition of `ESC-prefix'.)
+
+   The binding of a prefix key is the keymap to use for looking up the
+events that follow the prefix key.  (It may instead be a symbol whose
+function definition is a keymap.  The effect is the same, but the symbol
+serves as a name for the prefix key.)  Thus, the binding of `C-x' is
+the symbol `Control-X-prefix', whose function definition is the keymap
+for `C-x' commands.  (The same keymap is also the value of `ctl-x-map'.)
+
+   Prefix key definitions can appear in any active keymap.  The
+definitions of `C-c', `C-x', `C-h' and <ESC> as prefix keys appear in
+the global map, so these prefix keys are always available.  Major and
+minor modes can redefine a key as a prefix by putting a prefix key
+definition for it in the local map or the minor mode's map.  *Note
+Active Keymaps::.
+
+   If a key is defined as a prefix in more than one active map, then its
+various definitions are in effect merged: the commands defined in the
+minor mode keymaps come first, followed by those in the local map's
+prefix definition, and then by those from the global map.
+
+   In the following example, we make `C-p' a prefix key in the local
+keymap, in such a way that `C-p' is identical to `C-x'.  Then the
+binding for `C-p C-f' is the function `find-file', just like `C-x C-f'.
+The key sequence `C-p 6' is not found in any active keymap.
+
+     (use-local-map (make-sparse-keymap))
+         => nil
+     (local-set-key "\C-p" ctl-x-map)
+         => nil
+     (key-binding "\C-p\C-f")
+         => find-file
+     
+     (key-binding "\C-p6")
+         => nil
+
+ - Function: define-prefix-command symbol &optional mapvar
+     This function defines SYMBOL as a prefix command: it creates a
+     keymap and stores it as SYMBOL's function definition.  Storing the
+     symbol as the binding of a key makes the key a prefix key that has
+     a name.  If optional argument MAPVAR is not specified, it also
+     sets SYMBOL as a variable, to have the keymap as its value. (If
+     MAPVAR is given and is not `t', its value is stored as the value
+     of SYMBOL.) The function returns SYMBOL.
+
+     In Emacs version 18, only the function definition of SYMBOL was
+     set, not the value as a variable.
+
+
+File: lispref.info,  Node: Active Keymaps,  Next: Key Lookup,  Prev: Prefix Keys,  Up: Keymaps
+
+Active Keymaps
+==============
+
+   XEmacs normally contains many keymaps; at any given time, just a few
+of them are "active" in that they participate in the interpretation of
+user input.  These are the global keymap, the current buffer's local
+keymap, and the keymaps of any enabled minor modes.
+
+   The "global keymap" holds the bindings of keys that are defined
+regardless of the current buffer, such as `C-f'.  The variable
+`global-map' holds this keymap, which is always active.
+
+   Each buffer may have another keymap, its "local keymap", which may
+contain new or overriding definitions for keys.  The current buffer's
+local keymap is always active except when `overriding-local-map' or
+`overriding-terminal-local-map' overrides it.  Extents and text
+properties can specify an alternative local map for certain parts of the
+buffer; see *Note Extents and Events::.
+
+   Each minor mode may have a keymap; if it does, the keymap is active
+when the minor mode is enabled.
+
+   The variable `overriding-local-map' and
+`overriding-terminal-local-map', if non-`nil', specify other local
+keymaps that override the buffer's local map and all the minor mode
+keymaps.
+
+   All the active keymaps are used together to determine what command to
+execute when a key is entered.  XEmacs searches these maps one by one,
+in order of decreasing precedence, until it finds a binding in one of
+the maps.
+
+   More specifically:
+
+   For key-presses, the order of keymaps searched is:
+
+   * the `keymap' property of any extent(s) or text properties at point;
+
+   * any applicable minor-mode maps;
+
+   * the current local map of the current buffer;
+
+   * the current global map.
+
+   For mouse-clicks, the order of keymaps searched is:
+
+   * the current local map of the `mouse-grabbed-buffer' if any;
+
+   * the `keymap' property of any extent(s) at the position of the click
+     (this includes modeline extents);
+
+   * the `modeline-map' of the buffer corresponding to the modeline
+     under the mouse (if the click happened over a modeline);
+
+   * the value of `toolbar-map' in the current buffer (if the click
+     happened over a toolbar);
+
+   * the current local map of the buffer under the mouse (does not
+     apply to toolbar clicks);
+
+   * any applicable minor-mode maps;
+
+   * the current global map.
+
+   Note that if `overriding-local-map' or
+`overriding-terminal-local-map' is non-`nil', _only_ those two maps and
+the current global map are searched.
+
+   The procedure for searching a single keymap is called "key lookup";
+see *Note Key Lookup::.
+
+   Since every buffer that uses the same major mode normally uses the
+same local keymap, you can think of the keymap as local to the mode.  A
+change to the local keymap of a buffer (using `local-set-key', for
+example) is seen also in the other buffers that share that keymap.
+
+   The local keymaps that are used for Lisp mode, C mode, and several
+other major modes exist even if they have not yet been used.  These
+local maps are the values of the variables `lisp-mode-map',
+`c-mode-map', and so on.  For most other modes, which are less
+frequently used, the local keymap is constructed only when the mode is
+used for the first time in a session.
+
+   The minibuffer has local keymaps, too; they contain various
+completion and exit commands.  *Note Intro to Minibuffers::.
+
+   *Note Standard Keymaps::, for a list of standard keymaps.
+
+ - Function: current-keymaps &optional event-or-keys
+     This function returns a list of the current keymaps that will be
+     searched for bindings.  This lists keymaps such as the current
+     local map and the minor-mode maps, but does not list the parents
+     of those keymaps.  EVENT-OR-KEYS controls which keymaps will be
+     listed.  If EVENT-OR-KEYS is a mouse event (or a vector whose last
+     element is a mouse event), the keymaps for that mouse event will
+     be listed.  Otherwise, the keymaps for key presses will be listed.
+
+ - Variable: global-map
+     This variable contains the default global keymap that maps XEmacs
+     keyboard input to commands.  The global keymap is normally this
+     keymap.  The default global keymap is a full keymap that binds
+     `self-insert-command' to all of the printing characters.
+
+     It is normal practice to change the bindings in the global map,
+     but you should not assign this variable any value other than the
+     keymap it starts out with.
+
+ - Function: current-global-map
+     This function returns the current global keymap.  This is the same
+     as the value of `global-map' unless you change one or the other.
+
+          (current-global-map)
+          => #<keymap global-map 639 entries 0x221>
+
+ - Function: current-local-map &optional buffer
+     This function returns BUFFER's local keymap, or `nil' if it has
+     none.  BUFFER defaults to the current buffer.
+
+     In the following example, the keymap for the `*scratch*' buffer
+     (using Lisp Interaction mode) has a number of entries, including
+     one prefix key, `C-x'.
+
+          (current-local-map)
+          => #<keymap lisp-interaction-mode-map 5 entries 0x558>
+          (describe-bindings-internal (current-local-map))
+          =>  ; Inserted into the buffer:
+          backspace       backward-delete-char-untabify
+          linefeed        eval-print-last-sexp
+          delete          delete-char
+          C-j             eval-print-last-sexp
+          C-x             << Prefix Command >>
+          M-tab           lisp-complete-symbol
+          M-;             lisp-indent-for-comment
+          M-C-i           lisp-complete-symbol
+          M-C-q           indent-sexp
+          M-C-x           eval-defun
+          Alt-backspace   backward-kill-sexp
+          Alt-delete      kill-sexp
+          
+          C-x x           edebug-defun
+
+ - Function: current-minor-mode-maps
+     This function returns a list of the keymaps of currently enabled
+     minor modes.
+
+ - Function: use-global-map keymap
+     This function makes KEYMAP the new current global keymap.  It
+     returns `nil'.
+
+     It is very unusual to change the global keymap.
+
+ - Function: use-local-map keymap &optional buffer
+     This function makes KEYMAP the new local keymap of BUFFER.  BUFFER
+     defaults to the current buffer.  If KEYMAP is `nil', then the
+     buffer has no local keymap.  `use-local-map' returns `nil'.  Most
+     major mode commands use this function.
+
+ - Variable: minor-mode-map-alist
+     This variable is an alist describing keymaps that may or may not be
+     active according to the values of certain variables.  Its elements
+     look like this:
+
+          (VARIABLE . KEYMAP)
+
+     The keymap KEYMAP is active whenever VARIABLE has a non-`nil'
+     value.  Typically VARIABLE is the variable that enables or
+     disables a minor mode.  *Note Keymaps and Minor Modes::.
+
+     Note that elements of `minor-mode-map-alist' do not have the same
+     structure as elements of `minor-mode-alist'.  The map must be the
+     CDR of the element; a list with the map as the second element will
+     not do.
+
+     What's more, the keymap itself must appear in the CDR.  It does not
+     work to store a variable in the CDR and make the map the value of
+     that variable.
+
+     When more than one minor mode keymap is active, their order of
+     priority is the order of `minor-mode-map-alist'.  But you should
+     design minor modes so that they don't interfere with each other.
+     If you do this properly, the order will not matter.
+
+     See also `minor-mode-key-binding', above.  See *Note Keymaps and
+     Minor Modes::, for more information about minor modes.
+
+ - Variable: modeline-map
+     This variable holds the keymap consulted for mouse-clicks on the
+     modeline of a window.  This variable may be buffer-local; its
+     value will be looked up in the buffer of the window whose modeline
+     was clicked upon.
+
+ - Variable: toolbar-map
+     This variable holds the keymap consulted for mouse-clicks over a
+     toolbar.
+
+ - Variable: mouse-grabbed-buffer
+     If non-`nil', a buffer which should be consulted first for all
+     mouse activity.  When a mouse-click is processed, it will first be
+     looked up in the local-map of this buffer, and then through the
+     normal mechanism if there is no binding for that click.  This
+     buffer's value of `mode-motion-hook' will be consulted instead of
+     the `mode-motion-hook' of the buffer of the window under the mouse.
+     You should _bind_ this, not set it.
+
+ - Variable: overriding-local-map
+     If non-`nil', this variable holds a keymap to use instead of the
+     buffer's local keymap and instead of all the minor mode keymaps.
+     This keymap, if any, overrides all other maps that would have been
+     active, except for the current global map.
+
+ - Variable: overriding-terminal-local-map
+     If non-`nil', this variable holds a keymap to use instead of the
+     buffer's local keymap and instead of all the minor mode keymaps,
+     but for the selected console only. (In other words, this variable
+     is always console-local; putting a keymap here only applies to
+     keystrokes coming from the selected console.  *Note Consoles and
+     Devices::.) This keymap, if any, overrides all other maps that
+     would have been active, except for the current global map.
+
+
+File: lispref.info,  Node: Key Lookup,  Next: Functions for Key Lookup,  Prev: Active Keymaps,  Up: Keymaps
+
+Key Lookup
+==========
+
+   "Key lookup" is the process of finding the binding of a key sequence
+from a given keymap.  Actual execution of the binding is not part of
+key lookup.
+
+   Key lookup uses just the event type of each event in the key
+sequence; the rest of the event is ignored.  In fact, a key sequence
+used for key lookup may designate mouse events with just their types
+(symbols) instead of with entire mouse events (lists).  *Note Events::.
+Such a pseudo-key-sequence is insufficient for `command-execute', but
+it is sufficient for looking up or rebinding a key.
+
+   When the key sequence consists of multiple events, key lookup
+processes the events sequentially: the binding of the first event is
+found, and must be a keymap; then the second event's binding is found in
+that keymap, and so on until all the events in the key sequence are used
+up.  (The binding thus found for the last event may or may not be a
+keymap.)  Thus, the process of key lookup is defined in terms of a
+simpler process for looking up a single event in a keymap.  How that is
+done depends on the type of object associated with the event in that
+keymap.
+
+   Let's use the term "keymap entry" to describe the value found by
+looking up an event type in a keymap.  (This doesn't include the item
+string and other extra elements in menu key bindings because
+`lookup-key' and other key lookup functions don't include them in the
+returned value.)  While any Lisp object may be stored in a keymap as a
+keymap entry, not all make sense for key lookup.  Here is a list of the
+meaningful kinds of keymap entries:
+
+`nil'
+     `nil' means that the events used so far in the lookup form an
+     undefined key.  When a keymap fails to mention an event type at
+     all, and has no default binding, that is equivalent to a binding
+     of `nil' for that event type.
+
+KEYMAP
+     The events used so far in the lookup form a prefix key.  The next
+     event of the key sequence is looked up in KEYMAP.
+
+COMMAND
+     The events used so far in the lookup form a complete key, and
+     COMMAND is its binding.  *Note What Is a Function::.
+
+ARRAY
+     The array (either a string or a vector) is a keyboard macro.  The
+     events used so far in the lookup form a complete key, and the
+     array is its binding.  See *Note Keyboard Macros::, for more
+     information. (Note that you cannot use a shortened form of a key
+     sequence here, such as `(control y)'; you must use the full form
+     `[(control y)]'.  *Note Key Sequences::.)
+
+LIST
+     The meaning of a list depends on the types of the elements of the
+     list.
+
+        * If the CAR of LIST is `lambda', then the list is a lambda
+          expression.  This is presumed to be a command, and is treated
+          as such (see above).
+
+        * If the CAR of LIST is a keymap and the CDR is an event type,
+          then this is an "indirect entry":
+
+               (OTHERMAP . OTHERTYPE)
+
+          When key lookup encounters an indirect entry, it looks up
+          instead the binding of OTHERTYPE in OTHERMAP and uses that.
+
+          This feature permits you to define one key as an alias for
+          another key.  For example, an entry whose CAR is the keymap
+          called `esc-map' and whose CDR is 32 (the code for <SPC>)
+          means, "Use the global binding of `Meta-<SPC>', whatever that
+          may be."
+
+SYMBOL
+     The function definition of SYMBOL is used in place of SYMBOL.  If
+     that too is a symbol, then this process is repeated, any number of
+     times.  Ultimately this should lead to an object that is a keymap,
+     a command or a keyboard macro.  A list is allowed if it is a
+     keymap or a command, but indirect entries are not understood when
+     found via symbols.
+
+     Note that keymaps and keyboard macros (strings and vectors) are not
+     valid functions, so a symbol with a keymap, string, or vector as
+     its function definition is invalid as a function.  It is, however,
+     valid as a key binding.  If the definition is a keyboard macro,
+     then the symbol is also valid as an argument to `command-execute'
+     (*note Interactive Call::).
+
+     The symbol `undefined' is worth special mention: it means to treat
+     the key as undefined.  Strictly speaking, the key is defined, and
+     its binding is the command `undefined'; but that command does the
+     same thing that is done automatically for an undefined key: it
+     rings the bell (by calling `ding') but does not signal an error.
+
+     `undefined' is used in local keymaps to override a global key
+     binding and make the key "undefined" locally.  A local binding of
+     `nil' would fail to do this because it would not override the
+     global binding.
+
+ANYTHING ELSE
+     If any other type of object is found, the events used so far in the
+     lookup form a complete key, and the object is its binding, but the
+     binding is not executable as a command.
+
+   In short, a keymap entry may be a keymap, a command, a keyboard
+macro, a symbol that leads to one of them, or an indirection or `nil'.
+
+
+File: lispref.info,  Node: Functions for Key Lookup,  Next: Changing Key Bindings,  Prev: Key Lookup,  Up: Keymaps
+
+Functions for Key Lookup
+========================
+
+   Here are the functions and variables pertaining to key lookup.
+
+ - Function: lookup-key keymap key &optional accept-defaults
+     This function returns the definition of KEY in KEYMAP.  If the
+     string or vector KEY is not a valid key sequence according to the
+     prefix keys specified in KEYMAP (which means it is "too long" and
+     has extra events at the end), then the value is a number, the
+     number of events at the front of KEY that compose a complete key.
+
+     If ACCEPT-DEFAULTS is non-`nil', then `lookup-key' considers
+     default bindings as well as bindings for the specific events in
+     KEY.  Otherwise, `lookup-key' reports only bindings for the
+     specific sequence KEY, ignoring default bindings except when you
+     explicitly ask about them.
+
+     All the other functions described in this chapter that look up
+     keys use `lookup-key'.
+
+          (lookup-key (current-global-map) "\C-x\C-f")
+              => find-file
+          (lookup-key (current-global-map) "\C-x\C-f12345")
+              => 2
+
+     If KEY begins with the character whose value is contained in
+     `meta-prefix-char', that character is implicitly removed and the
+     <META> modifier added to the key.  Thus, the first example below is
+     handled by conversion into the second example.
+
+          (lookup-key (current-global-map) "\ef")
+              => forward-word
+          (lookup-key (current-global-map) "\M-f")
+              => forward-word
+
+     Unlike `read-key-sequence', this function does not modify the
+     specified events in ways that discard information (*note Key
+     Sequence Input::).  In particular, it does not convert letters to
+     lower case.
+
+ - Command: undefined
+     Used in keymaps to undefine keys.  If a key sequence is defined to
+     this, invoking this key sequence causes a "key undefined" error,
+     just as if the key sequence had no binding.
+
+ - Function: key-binding key &optional accept-defaults
+     This function returns the binding for KEY in the current keymaps,
+     trying all the active keymaps.  The result is `nil' if KEY is
+     undefined in the keymaps.
+
+     The argument ACCEPT-DEFAULTS controls checking for default
+     bindings, as in `lookup-key' (above).
+
+          (key-binding "\C-x\C-f")
+              => find-file
+          (key-binding '(control home))
+              => beginning-of-buffer
+          (key-binding [escape escape escape])
+              => keyboard-escape-quit
+
+ - Function: local-key-binding keys &optional accept-defaults
+     This function returns the binding for KEYS in the current local
+     keymap, or `nil' if it is undefined there.
+
+     The argument ACCEPT-DEFAULTS controls checking for default
+     bindings, as in `lookup-key' (above).
+
+ - Function: global-key-binding keys &optional accept-defaults
+     This function returns the binding for command KEYS in the current
+     global keymap, or `nil' if it is undefined there.
+
+     The argument ACCEPT-DEFAULTS controls checking for default
+     bindings, as in `lookup-key' (above).
+
+ - Function: minor-mode-key-binding key &optional accept-defaults
+     This function returns a list of all the active minor mode bindings
+     of KEY.  More precisely, it returns an alist of pairs `(MODENAME .
+     BINDING)', where MODENAME is the variable that enables the minor
+     mode, and BINDING is KEY's binding in that mode.  If KEY has no
+     minor-mode bindings, the value is `nil'.
+
+     If the first binding is not a prefix command, all subsequent
+     bindings from other minor modes are omitted, since they would be
+     completely shadowed.  Similarly, the list omits non-prefix
+     bindings that follow prefix bindings.
+
+     The argument ACCEPT-DEFAULTS controls checking for default
+     bindings, as in `lookup-key' (above).
+
+ - Variable: meta-prefix-char
+     This variable is the meta-prefix character code.  It is used when
+     translating a two-character sequence to a meta character so it can
+     be looked up in a keymap.  For useful results, the value should be
+     a prefix event (*note Prefix Keys::).  The default value is `?\^['
+     (integer 27), which is the ASCII character usually produced by the
+     <ESC> key.
+
+     As long as the value of `meta-prefix-char' remains `?\^[', key
+     lookup translates `<ESC> b' into `M-b', which is normally defined
+     as the `backward-word' command.  However, if you set
+     `meta-prefix-char' to `?\^X' (i.e. the keystroke `C-x') or its
+     equivalent ASCII code `24', then XEmacs will translate `C-x b'
+     (whose standard binding is the `switch-to-buffer' command) into
+     `M-b'.
+
+          meta-prefix-char                    ; The default value.
+               => ?\^[   ; Under XEmacs 20.
+               => 27     ; Under XEmacs 19.
+          (key-binding "\eb")
+               => backward-word
+          ?\C-x                               ; The print representation
+                                                     ;   of a character.
+               => ?\^X   ; Under XEmacs 20.
+               => 24     ; Under XEmacs 19.
+          (setq meta-prefix-char 24)
+               => 24
+          (key-binding "\C-xb")
+               => backward-word            ; Now, typing `C-x b' is
+                                              ;   like typing `M-b'.
+          
+          (setq meta-prefix-char ?\e)          ; Avoid confusion!
+                                               ; Restore the default value!
+               => ?\^[   ; Under XEmacs 20.
+               => 27     ; Under XEmacs 19.
+
+
+File: lispref.info,  Node: Changing Key Bindings,  Next: Key Binding Commands,  Prev: Functions for Key Lookup,  Up: Keymaps
+
+Changing Key Bindings
+=====================
+
+   The way to rebind a key is to change its entry in a keymap.  If you
+change a binding in the global keymap, the change is effective in all
+buffers (though it has no direct effect in buffers that shadow the
+global binding with a local one).  If you change the current buffer's
+local map, that usually affects all buffers using the same major mode.
+The `global-set-key' and `local-set-key' functions are convenient
+interfaces for these operations (*note Key Binding Commands::).  You
+can also use `define-key', a more general function; then you must
+specify explicitly the map to change.
+
+   The way to specify the key sequence that you want to rebind is
+described above (*note Key Sequences::).
+
+   For the functions below, an error is signaled if KEYMAP is not a
+keymap or if KEY is not a string or vector representing a key sequence.
+You can use event types (symbols) as shorthand for events that are
+lists.
+
+ - Function: define-key keymap key binding
+     This function sets the binding for KEY in KEYMAP.  (If KEY is more
+     than one event long, the change is actually made in another keymap
+     reached from KEYMAP.)  The argument BINDING can be any Lisp
+     object, but only certain types are meaningful.  (For a list of
+     meaningful types, see *Note Key Lookup::.)  The value returned by
+     `define-key' is BINDING.
+
+     Every prefix of KEY must be a prefix key (i.e., bound to a keymap)
+     or undefined; otherwise an error is signaled.
+
+     If some prefix of KEY is undefined, then `define-key' defines it
+     as a prefix key so that the rest of KEY may be defined as
+     specified.
+
+   Here is an example that creates a sparse keymap and makes a number of
+bindings in it:
+
+     (setq map (make-sparse-keymap))
+         => #<keymap 0 entries 0xbee>
+     (define-key map "\C-f" 'forward-char)
+         => forward-char
+     map
+         => #<keymap 1 entry 0xbee>
+     (describe-bindings-internal map)
+     =>   ; (Inserted in buffer)
+     C-f             forward-char
+     
+     ;; Build sparse submap for `C-x' and bind `f' in that.
+     (define-key map "\C-xf" 'forward-word)
+         => forward-word
+     map
+         => #<keymap 2 entries 0xbee>
+     (describe-bindings-internal map)
+     =>   ; (Inserted in buffer)
+     C-f             forward-char
+     C-x             << Prefix Command >>
+     
+     C-x f           forward-word
+     
+     ;; Bind `C-p' to the `ctl-x-map'.
+     (define-key map "\C-p" ctl-x-map)
+     ;; `ctl-x-map'
+     => #<keymap Control-X-prefix 77 entries 0x3bf>
+     
+     ;; Bind `C-f' to `foo' in the `ctl-x-map'.
+     (define-key map "\C-p\C-f" 'foo)
+     => foo
+     map
+         => #<keymap 3 entries 0xbee>
+     (describe-bindings-internal map)
+     =>   ; (Inserted in buffer)
+     C-f             forward-char
+     C-p             << Prefix command Control-X-prefix >>
+     C-x             << Prefix Command >>
+     
+     C-p tab         indent-rigidly
+     C-p $           set-selective-display
+     C-p '           expand-abbrev
+     C-p (           start-kbd-macro
+     C-p )           end-kbd-macro
+        ...
+     C-p C-x         exchange-point-and-mark
+     C-p C-z         suspend-or-iconify-emacs
+     C-p M-escape    repeat-complex-command
+     C-p M-C-[       repeat-complex-command
+     
+     C-x f           forward-word
+     
+     C-p 4 .         find-tag-other-window
+        ...
+     C-p 4 C-o       display-buffer
+     
+     C-p 5 0         delete-frame
+        ...
+     C-p 5 C-f       find-file-other-frame
+     
+        ...
+     
+     C-p a i g       inverse-add-global-abbrev
+     C-p a i l       inverse-add-mode-abbrev
+
+Note that storing a new binding for `C-p C-f' actually works by
+changing an entry in `ctl-x-map', and this has the effect of changing
+the bindings of both `C-p C-f' and `C-x C-f' in the default global map.
+
+ - Function: substitute-key-definition olddef newdef keymap &optional
+          oldmap prefix
+     This function replaces OLDDEF with NEWDEF for any keys in KEYMAP
+     that were bound to OLDDEF.  In other words, OLDDEF is replaced
+     with NEWDEF wherever it appears.  Prefix keymaps are checked
+     recursively.
+
+     The function returns `nil'.
+
+     For example, this redefines `C-x C-f', if you do it in an XEmacs
+     with standard bindings:
+
+          (substitute-key-definition
+           'find-file 'find-file-read-only (current-global-map))
+
+     If OLDMAP is non-`nil', then its bindings determine which keys to
+     rebind.  The rebindings still happen in KEYMAP, not in OLDMAP.
+     Thus, you can change one map under the control of the bindings in
+     another.  For example,
+
+          (substitute-key-definition
+            'delete-backward-char 'my-funny-delete
+            my-map global-map)
+
+     puts the special deletion command in `my-map' for whichever keys
+     are globally bound to the standard deletion command.
+
+     If argument PREFIX is non-`nil', then only those occurrences of
+     OLDDEF found in keymaps accessible through the keymap bound to
+     PREFIX in KEYMAP are redefined.  See also `accessible-keymaps'.
+
+
+ - Function: suppress-keymap keymap &optional nodigits
+     This function changes the contents of the full keymap KEYMAP by
+     making all the printing characters undefined.  More precisely, it
+     binds them to the command `undefined'.  This makes ordinary
+     insertion of text impossible.  `suppress-keymap' returns `nil'.
+
+     If NODIGITS is `nil', then `suppress-keymap' defines digits to run
+     `digit-argument', and `-' to run `negative-argument'.  Otherwise
+     it makes them undefined like the rest of the printing characters.
+
+     The `suppress-keymap' function does not make it impossible to
+     modify a buffer, as it does not suppress commands such as `yank'
+     and `quoted-insert'.  To prevent any modification of a buffer, make
+     it read-only (*note Read Only Buffers::).
+
+     Since this function modifies KEYMAP, you would normally use it on
+     a newly created keymap.  Operating on an existing keymap that is
+     used for some other purpose is likely to cause trouble; for
+     example, suppressing `global-map' would make it impossible to use
+     most of XEmacs.
+
+     Most often, `suppress-keymap' is used to initialize local keymaps
+     of modes such as Rmail and Dired where insertion of text is not
+     desirable and the buffer is read-only.  Here is an example taken
+     from the file `emacs/lisp/dired.el', showing how the local keymap
+     for Dired mode is set up:
+
+            ...
+            (setq dired-mode-map (make-keymap))
+            (suppress-keymap dired-mode-map)
+            (define-key dired-mode-map "r" 'dired-rename-file)
+            (define-key dired-mode-map "\C-d" 'dired-flag-file-deleted)
+            (define-key dired-mode-map "d" 'dired-flag-file-deleted)
+            (define-key dired-mode-map "v" 'dired-view-file)
+            (define-key dired-mode-map "e" 'dired-find-file)
+            (define-key dired-mode-map "f" 'dired-find-file)
+            ...
+
+
+File: lispref.info,  Node: Key Binding Commands,  Next: Scanning Keymaps,  Prev: Changing Key Bindings,  Up: Keymaps
+
+Commands for Binding Keys
+=========================
+
+   This section describes some convenient interactive interfaces for
+changing key bindings.  They work by calling `define-key'.
+
+   People often use `global-set-key' in their `.emacs' file for simple
+customization.  For example,
+
+     (global-set-key "\C-x\C-\\" 'next-line)
+
+or
+
+     (global-set-key [(control ?x) (control ?\\)] 'next-line)
+
+or
+
+     (global-set-key [?\C-x ?\C-\\] 'next-line)
+
+redefines `C-x C-\' to move down a line.
+
+     (global-set-key [(meta button1)] 'mouse-set-point)
+
+redefines the first (leftmost) mouse button, typed with the Meta key, to
+set point where you click.
+
+ - Command: global-set-key key definition
+     This function sets the binding of KEY in the current global map to
+     DEFINITION.
+
+          (global-set-key KEY DEFINITION)
+          ==
+          (define-key (current-global-map) KEY DEFINITION)
+
+ - Command: global-unset-key key
+     This function removes the binding of KEY from the current global
+     map.
+
+     One use of this function is in preparation for defining a longer
+     key that uses KEY as a prefix--which would not be allowed if KEY
+     has a non-prefix binding.  For example:
+
+          (global-unset-key "\C-l")
+              => nil
+          (global-set-key "\C-l\C-l" 'redraw-display)
+              => nil
+
+     This function is implemented simply using `define-key':
+
+          (global-unset-key KEY)
+          ==
+          (define-key (current-global-map) KEY nil)
+
+ - Command: local-set-key key definition
+     This function sets the binding of KEY in the current local keymap
+     to DEFINITION.
+
+          (local-set-key KEY DEFINITION)
+          ==
+          (define-key (current-local-map) KEY DEFINITION)
+
+ - Command: local-unset-key key
+     This function removes the binding of KEY from the current local
+     map.
+
+          (local-unset-key KEY)
+          ==
+          (define-key (current-local-map) KEY nil)
+
+
+File: lispref.info,  Node: Scanning Keymaps,  Next: Other Keymap Functions,  Prev: Key Binding Commands,  Up: Keymaps
+
+Scanning Keymaps
+================
+
+   This section describes functions used to scan all the current
+keymaps, or all keys within a keymap, for the sake of printing help
+information.
+
+ - Function: accessible-keymaps keymap &optional prefix
+     This function returns a list of all the keymaps that can be
+     accessed (via prefix keys) from KEYMAP.  The value is an
+     association list with elements of the form `(KEY . MAP)', where
+     KEY is a prefix key whose definition in KEYMAP is MAP.
+
+     The elements of the alist are ordered so that the KEY increases in
+     length.  The first element is always `([] . KEYMAP)', because the
+     specified keymap is accessible from itself with a prefix of no
+     events.
+
+     If PREFIX is given, it should be a prefix key sequence; then
+     `accessible-keymaps' includes only the submaps whose prefixes start
+     with PREFIX.  These elements look just as they do in the value of
+     `(accessible-keymaps)'; the only difference is that some elements
+     are omitted.
+
+     In the example below, the returned alist indicates that the key
+     `C-x', which is displayed as `[(control x)]', is a prefix key
+     whose definition is the keymap `#<keymap ((control x) #<keymap
+     emacs-lisp-mode-map 8 entries 0x546>) 1 entry 0x8a2>'. (The strange
+     notation for the keymap's name indicates that this is an internal
+     submap of `emacs-lisp-mode-map'.  This is because
+     `lisp-interaction-mode-map' has set up `emacs-lisp-mode-map' as
+     its parent, and `lisp-interaction-mode-map' defines no key
+     sequences beginning with `C-x'.)
+
+          (current-local-map)
+          => #<keymap lisp-interaction-mode-map 5 entries 0x558>
+          (accessible-keymaps (current-local-map))
+          =>(([] . #<keymap lisp-interaction-mode-map 5 entries 0x558>)
+              ([(control x)] .
+               #<keymap ((control x) #<keymap emacs-lisp-mode-map 8 entries 0x546>)
+                        1 entry 0x8a2>))
+
+     The following example shows the results of calling
+     `accessible-keymaps' on a large, complex keymap.  Notice how some
+     keymaps were given explicit names using `set-keymap-name'; those
+     submaps without explicit names are given descriptive names
+     indicating their relationship to their enclosing keymap.
+
+          (accessible-keymaps (current-global-map))
+          => (([] . #<keymap global-map 639 entries 0x221>)
+             ([(control c)] . #<keymap mode-specific-command-prefix 1 entry 0x3cb>)
+             ([(control h)] . #<keymap help-map 33 entries 0x4ec>)
+             ([(control x)] . #<keymap Control-X-prefix 77 entries 0x3bf>)
+             ([(meta escape)] .
+                #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+                         3 entries 0x3e0>)
+             ([(meta control \[)] .
+                #<keymap ((meta escape) #<keymap global-map 639 entries 0x221>)
+                         3 entries 0x3e0>)
+             ([f1] . #<keymap help-map 33 entries 0x4ec>)
+             ([(control x) \4] . #<keymap ctl-x-4-prefix 9 entries 0x3c5>)
+             ([(control x) \5] . #<keymap ctl-x-5-prefix 8 entries 0x3c8>)
+             ([(control x) \6] . #<keymap 13 entries 0x4d2>)
+             ([(control x) a] .
+                #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+                         8 entries 0x3ef>)
+             ([(control x) n] . #<keymap narrowing-prefix 3 entries 0x3dd>)
+             ([(control x) r] . #<keymap rectangle-prefix 18 entries 0x3e9>)
+             ([(control x) v] . #<keymap vc-prefix-map 13 entries 0x60e>)
+             ([(control x) a i] .
+               #<keymap (i #<keymap (a #<keymap Control-X-prefix 77 entries 0x3bf>)
+                                    8 entries 0x3ef>)
+                        2 entries 0x3f5>))
+
+ - Function: map-keymap function keymap &optional sort-first
+     This function applies FUNCTION to each element of KEYMAP.
+     FUNCTION will be called with two arguments: a key-description
+     list, and the binding.  The order in which the elements of the
+     keymap are passed to the function is unspecified.  If the function
+     inserts new elements into the keymap, it may or may not be called
+     with them later.  No element of the keymap will ever be passed to
+     the function more than once.
+
+     The function will not be called on elements of this keymap's
+     parents (*note Inheritance and Keymaps::) or upon keymaps which
+     are contained within this keymap (multi-character definitions).
+     It will be called on <META> characters since they are not really
+     two-character sequences.
+
+     If the optional third argument SORT-FIRST is non-`nil', then the
+     elements of the keymap will be passed to the mapper function in a
+     canonical order.  Otherwise, they will be passed in hash (that is,
+     random) order, which is faster.
+
+ - Function: keymap-fullness keymap
+     This function returns the number of bindings in the keymap.
+
+ - Function: where-is-internal definition &optional keymaps firstonly
+          noindirect event-or-keys
+     This function returns a list of key sequences (of any length) that
+     are bound to DEFINITION in a set of keymaps.
+
+     The argument DEFINITION can be any object; it is compared with all
+     keymap entries using `eq'.
+
+     KEYMAPS can be either a keymap (meaning search in that keymap and
+     the current global keymap) or a list of keymaps (meaning search in
+     exactly those keymaps and no others).  If KEYMAPS is nil, search
+     in the currently applicable maps for EVENT-OR-KEYS.
+
+     If KEYMAPS is a keymap, then the maps searched are KEYMAPS and the
+     global keymap.  If KEYMAPS is a list of keymaps, then the maps
+     searched are exactly those keymaps, and no others.  If KEYMAPS is
+     `nil', then the maps used are the current active keymaps for
+     EVENT-OR-KEYS (this is equivalent to specifying `(current-keymaps
+     EVENT-OR-KEYS)' as the argument to KEYMAPS).
+
+     If FIRSTONLY is non-`nil', then the value is a single vector
+     representing the first key sequence found, rather than a list of
+     all possible key sequences.
+
+     If NOINDIRECT is non-`nil', `where-is-internal' doesn't follow
+     indirect keymap bindings.  This makes it possible to search for an
+     indirect definition itself.
+
+     This function is used by `where-is' (*note Help: (xemacs)Help.).
+
+          (where-is-internal 'describe-function)
+              => ([(control h) d] [(control h) f] [f1 d] [f1 f])
+
+ - Function: describe-bindings-internal map &optional all shadow prefix
+          mouse-only-p
+     This function inserts (into the current buffer) a list of all
+     defined keys and their definitions in MAP.  Optional second
+     argument ALL says whether to include even "uninteresting"
+     definitions, i.e.  symbols with a non-`nil' `suppress-keymap'
+     property.  Third argument SHADOW is a list of keymaps whose
+     bindings shadow those of map; if a binding is present in any
+     shadowing map, it is not printed.  Fourth argument PREFIX, if
+     non-`nil', should be a key sequence; only bindings which start
+     with that key sequence will be printed.  Fifth argument
+     MOUSE-ONLY-P says to only print bindings for mouse clicks.
+
+   `describe-bindings-internal' is used to implement the help command
+`describe-bindings'.
+
+ - Command: describe-bindings &optional prefix mouse-only-p
+     This function creates a listing of all defined keys and their
+     definitions.  It writes the listing in a buffer named `*Help*' and
+     displays it in a window.
+
+     If optional argument PREFIX is non-`nil', it should be a prefix
+     key; then the listing includes only keys that start with PREFIX.
+
+     When several characters with consecutive ASCII codes have the same
+     definition, they are shown together, as `FIRSTCHAR..LASTCHAR'.  In
+     this instance, you need to know the ASCII codes to understand
+     which characters this means.  For example, in the default global
+     map, the characters `<SPC> .. ~' are described by a single line.
+     <SPC> is ASCII 32, `~' is ASCII 126, and the characters between
+     them include all the normal printing characters, (e.g., letters,
+     digits, punctuation, etc.); all these characters are bound to
+     `self-insert-command'.
+
+     If the second optional argument MOUSE-ONLY-P (prefix arg,
+     interactively) is non-`nil' then only the mouse bindings are
+     displayed.
+
+
+File: lispref.info,  Node: Other Keymap Functions,  Prev: Scanning Keymaps,  Up: Keymaps
+
+Other Keymap Functions
+======================
+
+ - Function: set-keymap-prompt keymap new-prompt
+     This function sets the "prompt" of KEYMAP to string NEW-PROMPT, or
+     `nil' if no prompt is desired.  The prompt is shown in the
+     echo-area when reading a key-sequence to be looked-up in this
+     keymap.
+
+ - Function: keymap-prompt keymap &optional use-inherited
+     This function returns the "prompt" of the given keymap.  If
+     USE-INHERITED is non-`nil', any parent keymaps will also be
+     searched for a prompt.
+
+
+File: lispref.info,  Node: Menus,  Next: Dialog Boxes,  Prev: Keymaps,  Up: Top
+
+Menus
+*****
+
+* Menu:
+
+* Menu Format::         Format of a menu description.
+* Menubar Format::      How to specify a menubar.
+* Menubar::             Functions for controlling the menubar.
+* Modifying Menus::     Modifying a menu description.
+* Pop-Up Menus::        Functions for specifying pop-up menus.
+* Menu Filters::        Filter functions for the default menubar.
+* Menu Accelerators::   Using and controlling menu accelerator keys
+* Buffers Menu::        The menu that displays the list of buffers.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-2'
Index: ././info/lispref.info-2
--- ././info/lispref.info-2	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-2	Thu May 17 23:26:54 2001
@@ -0,0 +1,1171 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: Top
+
+GNU GENERAL PUBLIC LICENSE
+**************************
+
+                         Version 2, June 1991
+
+     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
+     675 Mass Ave, Cambridge, MA 02139, USA
+     
+     Everyone is permitted to copy and distribute verbatim copies
+     of this license document, but changing it is not allowed.
+
+Preamble
+========
+
+   The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Library General Public License instead.)  You can apply it to
+your programs, too.
+
+   When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it in
+new free programs; and that you know you can do these things.
+
+   To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+   For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+   We protect your rights with two steps: (1) copyright the software,
+and (2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+   Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+   Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+   The precise terms and conditions for copying, distribution and
+modification follow.
+
+    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains a
+     notice placed by the copyright holder saying it may be distributed
+     under the terms of this General Public License.  The "Program",
+     below, refers to any such program or work, and a "work based on
+     the Program" means either the Program or any derivative work under
+     copyright law: that is to say, a work containing the Program or a
+     portion of it, either verbatim or with modifications and/or
+     translated into another language.  (Hereinafter, translation is
+     included without limitation in the term "modification".)  Each
+     licensee is addressed as "you".
+
+     Activities other than copying, distribution and modification are
+     not covered by this License; they are outside its scope.  The act
+     of running the Program is not restricted, and the output from the
+     Program is covered only if its contents constitute a work based on
+     the Program (independent of having been made by running the
+     Program).  Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+     source code as you receive it, in any medium, provided that you
+     conspicuously and appropriately publish on each copy an appropriate
+     copyright notice and disclaimer of warranty; keep intact all the
+     notices that refer to this License and to the absence of any
+     warranty; and give any other recipients of the Program a copy of
+     this License along with the Program.
+
+     You may charge a fee for the physical act of transferring a copy,
+     and you may at your option offer warranty protection in exchange
+     for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+     of it, thus forming a work based on the Program, and copy and
+     distribute such modifications or work under the terms of Section 1
+     above, provided that you also meet all of these conditions:
+
+       a. You must cause the modified files to carry prominent notices
+          stating that you changed the files and the date of any change.
+
+       b. You must cause any work that you distribute or publish, that
+          in whole or in part contains or is derived from the Program
+          or any part thereof, to be licensed as a whole at no charge
+          to all third parties under the terms of this License.
+
+       c. If the modified program normally reads commands interactively
+          when run, you must cause it, when started running for such
+          interactive use in the most ordinary way, to print or display
+          an announcement including an appropriate copyright notice and
+          a notice that there is no warranty (or else, saying that you
+          provide a warranty) and that users may redistribute the
+          program under these conditions, and telling the user how to
+          view a copy of this License.  (Exception: if the Program
+          itself is interactive but does not normally print such an
+          announcement, your work based on the Program is not required
+          to print an announcement.)
+
+     These requirements apply to the modified work as a whole.  If
+     identifiable sections of that work are not derived from the
+     Program, and can be reasonably considered independent and separate
+     works in themselves, then this License, and its terms, do not
+     apply to those sections when you distribute them as separate
+     works.  But when you distribute the same sections as part of a
+     whole which is a work based on the Program, the distribution of
+     the whole must be on the terms of this License, whose permissions
+     for other licensees extend to the entire whole, and thus to each
+     and every part regardless of who wrote it.
+
+     Thus, it is not the intent of this section to claim rights or
+     contest your rights to work written entirely by you; rather, the
+     intent is to exercise the right to control the distribution of
+     derivative or collective works based on the Program.
+
+     In addition, mere aggregation of another work not based on the
+     Program with the Program (or with a work based on the Program) on
+     a volume of a storage or distribution medium does not bring the
+     other work under the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+     under Section 2) in object code or executable form under the terms
+     of Sections 1 and 2 above provided that you also do one of the
+     following:
+
+       a. Accompany it with the complete corresponding machine-readable
+          source code, which must be distributed under the terms of
+          Sections 1 and 2 above on a medium customarily used for
+          software interchange; or,
+
+       b. Accompany it with a written offer, valid for at least three
+          years, to give any third party, for a charge no more than your
+          cost of physically performing source distribution, a complete
+          machine-readable copy of the corresponding source code, to be
+          distributed under the terms of Sections 1 and 2 above on a
+          medium customarily used for software interchange; or,
+
+       c. Accompany it with the information you received as to the offer
+          to distribute corresponding source code.  (This alternative is
+          allowed only for noncommercial distribution and only if you
+          received the program in object code or executable form with
+          such an offer, in accord with Subsection b above.)
+
+     The source code for a work means the preferred form of the work for
+     making modifications to it.  For an executable work, complete
+     source code means all the source code for all modules it contains,
+     plus any associated interface definition files, plus the scripts
+     used to control compilation and installation of the executable.
+     However, as a special exception, the source code distributed need
+     not include anything that is normally distributed (in either
+     source or binary form) with the major components (compiler,
+     kernel, and so on) of the operating system on which the executable
+     runs, unless that component itself accompanies the executable.
+
+     If distribution of executable or object code is made by offering
+     access to copy from a designated place, then offering equivalent
+     access to copy the source code from the same place counts as
+     distribution of the source code, even though third parties are not
+     compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+     except as expressly provided under this License.  Any attempt
+     otherwise to copy, modify, sublicense or distribute the Program is
+     void, and will automatically terminate your rights under this
+     License.  However, parties who have received copies, or rights,
+     from you under this License will not have their licenses
+     terminated so long as such parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+     signed it.  However, nothing else grants you permission to modify
+     or distribute the Program or its derivative works.  These actions
+     are prohibited by law if you do not accept this License.
+     Therefore, by modifying or distributing the Program (or any work
+     based on the Program), you indicate your acceptance of this
+     License to do so, and all its terms and conditions for copying,
+     distributing or modifying the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+     Program), the recipient automatically receives a license from the
+     original licensor to copy, distribute or modify the Program
+     subject to these terms and conditions.  You may not impose any
+     further restrictions on the recipients' exercise of the rights
+     granted herein.  You are not responsible for enforcing compliance
+     by third parties to this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+     infringement or for any other reason (not limited to patent
+     issues), conditions are imposed on you (whether by court order,
+     agreement or otherwise) that contradict the conditions of this
+     License, they do not excuse you from the conditions of this
+     License.  If you cannot distribute so as to satisfy simultaneously
+     your obligations under this License and any other pertinent
+     obligations, then as a consequence you may not distribute the
+     Program at all.  For example, if a patent license would not permit
+     royalty-free redistribution of the Program by all those who
+     receive copies directly or indirectly through you, then the only
+     way you could satisfy both it and this License would be to refrain
+     entirely from distribution of the Program.
+
+     If any portion of this section is held invalid or unenforceable
+     under any particular circumstance, the balance of the section is
+     intended to apply and the section as a whole is intended to apply
+     in other circumstances.
+
+     It is not the purpose of this section to induce you to infringe any
+     patents or other property right claims or to contest validity of
+     any such claims; this section has the sole purpose of protecting
+     the integrity of the free software distribution system, which is
+     implemented by public license practices.  Many people have made
+     generous contributions to the wide range of software distributed
+     through that system in reliance on consistent application of that
+     system; it is up to the author/donor to decide if he or she is
+     willing to distribute software through any other system and a
+     licensee cannot impose that choice.
+
+     This section is intended to make thoroughly clear what is believed
+     to be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+     certain countries either by patents or by copyrighted interfaces,
+     the original copyright holder who places the Program under this
+     License may add an explicit geographical distribution limitation
+     excluding those countries, so that distribution is permitted only
+     in or among countries not thus excluded.  In such case, this
+     License incorporates the limitation as if written in the body of
+     this License.
+
+  9. The Free Software Foundation may publish revised and/or new
+     versions of the General Public License from time to time.  Such
+     new versions will be similar in spirit to the present version, but
+     may differ in detail to address new problems or concerns.
+
+     Each version is given a distinguishing version number.  If the
+     Program specifies a version number of this License which applies
+     to it and "any later version", you have the option of following
+     the terms and conditions either of that version or of any later
+     version published by the Free Software Foundation.  If the Program
+     does not specify a version number of this License, you may choose
+     any version ever published by the Free Software Foundation.
+
+ 10. If you wish to incorporate parts of the Program into other free
+     programs whose distribution conditions are different, write to the
+     author to ask for permission.  For software which is copyrighted
+     by the Free Software Foundation, write to the Free Software
+     Foundation; we sometimes make exceptions for this.  Our decision
+     will be guided by the two goals of preserving the free status of
+     all derivatives of our free software and of promoting the sharing
+     and reuse of software generally.
+
+                                NO WARRANTY
+
+ 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
+     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
+     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
+     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
+     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
+     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
+     SERVICING, REPAIR OR CORRECTION.
+
+ 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
+     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
+     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
+     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
+     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
+     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
+     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+                      END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+=============================================
+
+   If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+   To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
+     Copyright (C) 19YY  NAME OF AUTHOR
+     
+     This program is free software; you can redistribute it and/or
+     modify it under the terms of the GNU General Public License
+     as published by the Free Software Foundation; either version 2
+     of the License, or (at your option) any later version.
+     
+     This program is distributed in the hope that it will be useful,
+     but WITHOUT ANY WARRANTY; without even the implied warranty of
+     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+     GNU General Public License for more details.
+     
+     You should have received a copy of the GNU General Public License
+     along with this program; if not, write to the Free Software
+     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+
+   Also add information on how to contact you by electronic and paper
+mail.
+
+   If the program is interactive, make it output a short notice like
+this when it starts in an interactive mode:
+
+     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
+     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
+     type `show w'.  This is free software, and you are welcome
+     to redistribute it under certain conditions; type `show c'
+     for details.
+
+   The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License.  Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+   You should also get your employer (if you work as a programmer) or
+your school, if any, to sign a "copyright disclaimer" for the program,
+if necessary.  Here is a sample; alter the names:
+
+     Yoyodyne, Inc., hereby disclaims all copyright
+     interest in the program `Gnomovision'
+     (which makes passes at compilers) written
+     by James Hacker.
+     
+     SIGNATURE OF TY COON, 1 April 1989
+     Ty Coon, President of Vice
+
+   This General Public License does not permit incorporating your
+program into proprietary programs.  If your program is a subroutine
+library, you may consider it more useful to permit linking proprietary
+applications with the library.  If this is what you want to do, use the
+GNU Library General Public License instead of this License.
+
+
+File: lispref.info,  Node: Introduction,  Next: Lisp Data Types,  Prev: Copying,  Up: Top
+
+Introduction
+************
+
+   Most of the XEmacs text editor is written in the programming
+language called XEmacs Lisp.  You can write new code in XEmacs Lisp and
+install it as an extension to the editor.  However, XEmacs Lisp is more
+than a mere "extension language"; it is a full computer programming
+language in its own right.  You can use it as you would any other
+programming language.
+
+   Because XEmacs Lisp is designed for use in an editor, it has special
+features for scanning and parsing text as well as features for handling
+files, buffers, displays, subprocesses, and so on.  XEmacs Lisp is
+closely integrated with the editing facilities; thus, editing commands
+are functions that can also conveniently be called from Lisp programs,
+and parameters for customization are ordinary Lisp variables.
+
+   This manual describes XEmacs Lisp, presuming considerable familiarity
+with the use of XEmacs for editing.  (See `The XEmacs Reference
+Manual', for this basic information.)  Generally speaking, the earlier
+chapters describe features of XEmacs Lisp that have counterparts in many
+programming languages, and later chapters describe features that are
+peculiar to XEmacs Lisp or relate specifically to editing.
+
+   This is edition 3.3.
+
+* Menu:
+
+* Caveats::             Flaws and a request for help.
+* Lisp History::        XEmacs Lisp is descended from Maclisp.
+* Conventions::         How the manual is formatted.
+* Acknowledgements::    The authors, editors, and sponsors of this manual.
+
+
+File: lispref.info,  Node: Caveats,  Next: Lisp History,  Up: Introduction
+
+Caveats
+=======
+
+   This manual has gone through numerous drafts.  It is nearly complete
+but not flawless.  There are a few topics that are not covered, either
+because we consider them secondary (such as most of the individual
+modes) or because they are yet to be written.  Because we are not able
+to deal with them completely, we have left out several parts
+intentionally.
+
+   The manual should be fully correct in what it does cover, and it is
+therefore open to criticism on anything it says--from specific examples
+and descriptive text, to the ordering of chapters and sections.  If
+something is confusing, or you find that you have to look at the sources
+or experiment to learn something not covered in the manual, then perhaps
+the manual should be fixed.  Please let us know.
+
+   As you use this manual, we ask that you send corrections as soon as
+you find them.  If you think of a simple, real life example for a
+function or group of functions, please make an effort to write it up
+and send it in.  Please reference any comments to the node name and
+function or variable name, as appropriate.  Also state the number of
+the edition which you are criticizing.
+
+   This manual was originally written for FSF Emacs 19 and was updated
+by Ben Wing (ben@xemacs.org) for Lucid Emacs 19.10 and later for XEmacs
+19.12, 19.13, 19.14, and 20.0.  It was further updated by the XEmacs
+Development Team for 19.15 and 20.1.  Please send comments and
+corrections relating to XEmacs-specific portions of this manual to
+     xemacs@xemacs.org
+
+   or post to the newsgroup
+     comp.emacs.xemacs
+
+      --Ben Wing
+
+
+File: lispref.info,  Node: Lisp History,  Next: Conventions,  Prev: Caveats,  Up: Introduction
+
+Lisp History
+============
+
+   Lisp (LISt Processing language) was first developed in the late
+1950's at the Massachusetts Institute of Technology for research in
+artificial intelligence.  The great power of the Lisp language makes it
+superior for other purposes as well, such as writing editing commands.
+
+   Dozens of Lisp implementations have been built over the years, each
+with its own idiosyncrasies.  Many of them were inspired by Maclisp,
+which was written in the 1960's at MIT's Project MAC.  Eventually the
+implementors of the descendants of Maclisp came together and developed a
+standard for Lisp systems, called Common Lisp.
+
+   XEmacs Lisp is largely inspired by Maclisp, and a little by Common
+Lisp.  If you know Common Lisp, you will notice many similarities.
+However, many of the features of Common Lisp have been omitted or
+simplified in order to reduce the memory requirements of XEmacs.
+Sometimes the simplifications are so drastic that a Common Lisp user
+might be very confused.  We will occasionally point out how XEmacs Lisp
+differs from Common Lisp.  If you don't know Common Lisp, don't worry
+about it; this manual is self-contained.
+
+
+File: lispref.info,  Node: Conventions,  Next: Acknowledgements,  Prev: Lisp History,  Up: Introduction
+
+Conventions
+===========
+
+   This section explains the notational conventions that are used in
+this manual.  You may want to skip this section and refer back to it
+later.
+
+* Menu:
+
+* Some Terms::               Explanation of terms we use in this manual.
+* nil and t::                How the symbols `nil' and `t' are used.
+* Evaluation Notation::      The format we use for examples of evaluation.
+* Printing Notation::        The format we use for examples that print output.
+* Error Messages::           The format we use for examples of errors.
+* Buffer Text Notation::     The format we use for buffer contents in examples.
+* Format of Descriptions::   Notation for describing functions, variables, etc.
+
+
+File: lispref.info,  Node: Some Terms,  Next: nil and t,  Up: Conventions
+
+Some Terms
+----------
+
+   Throughout this manual, the phrases "the Lisp reader" and "the Lisp
+printer" are used to refer to those routines in Lisp that convert
+textual representations of Lisp objects into actual Lisp objects, and
+vice versa.  *Note Printed Representation::, for more details.  You, the
+person reading this manual, are thought of as "the programmer" and are
+addressed as "you".  "The user" is the person who uses Lisp programs,
+including those you write.
+
+   Examples of Lisp code appear in this font or form: `(list 1 2 3)'.
+Names that represent arguments or metasyntactic variables appear in
+this font or form: FIRST-NUMBER.
+
+
+File: lispref.info,  Node: nil and t,  Next: Evaluation Notation,  Prev: Some Terms,  Up: Conventions
+
+`nil' and `t'
+-------------
+
+   In Lisp, the symbol `nil' has three separate meanings: it is a
+symbol with the name `nil'; it is the logical truth value FALSE; and it
+is the empty list--the list of zero elements.  When used as a variable,
+`nil' always has the value `nil'.
+
+   As far as the Lisp reader is concerned, `()' and `nil' are
+identical: they stand for the same object, the symbol `nil'.  The
+different ways of writing the symbol are intended entirely for human
+readers.  After the Lisp reader has read either `()' or `nil', there is
+no way to determine which representation was actually written by the
+programmer.
+
+   In this manual, we use `()' when we wish to emphasize that it means
+the empty list, and we use `nil' when we wish to emphasize that it
+means the truth value FALSE.  That is a good convention to use in Lisp
+programs also.
+
+     (cons 'foo ())                ; Emphasize the empty list
+     (not nil)                     ; Emphasize the truth value FALSE
+
+   In contexts where a truth value is expected, any non-`nil' value is
+considered to be TRUE.  However, `t' is the preferred way to represent
+the truth value TRUE.  When you need to choose a value which represents
+TRUE, and there is no other basis for choosing, use `t'.  The symbol
+`t' always has value `t'.
+
+   In XEmacs Lisp, `nil' and `t' are special symbols that always
+evaluate to themselves.  This is so that you do not need to quote them
+to use them as constants in a program.  An attempt to change their
+values results in a `setting-constant' error.  *Note Accessing
+Variables::.
+
+
+File: lispref.info,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: nil and t,  Up: Conventions
+
+Evaluation Notation
+-------------------
+
+   A Lisp expression that you can evaluate is called a "form".
+Evaluating a form always produces a result, which is a Lisp object.  In
+the examples in this manual, this is indicated with `=>':
+
+     (car '(1 2))
+          => 1
+
+You can read this as "`(car '(1 2))' evaluates to 1".
+
+   When a form is a macro call, it expands into a new form for Lisp to
+evaluate.  We show the result of the expansion with `==>'.  We may or
+may not show the actual result of the evaluation of the expanded form.
+
+     (news-cadr '(a b c))
+          ==> (car (cdr '(a b c)))
+          => b
+
+   Sometimes to help describe one form we show another form that
+produces identical results.  The exact equivalence of two forms is
+indicated with `=='.
+
+     (cons 'a nil) == (list 'a)
+
+
+File: lispref.info,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions
+
+Printing Notation
+-----------------
+
+   Many of the examples in this manual print text when they are
+evaluated.  If you execute example code in a Lisp Interaction buffer
+(such as the buffer `*scratch*'), the printed text is inserted into the
+buffer.  If you execute the example by other means (such as by
+evaluating the function `eval-region'), the printed text is displayed
+in the echo area.  You should be aware that text displayed in the echo
+area is truncated to a single line.
+
+   Examples in this manual indicate printed text with `-|',
+irrespective of where that text goes.  The value returned by evaluating
+the form (here `bar') follows on a separate line.
+
+     (progn (print 'foo) (print 'bar))
+          -| foo
+          -| bar
+          => bar
+
+
+File: lispref.info,  Node: Error Messages,  Next: Buffer Text Notation,  Prev: Printing Notation,  Up: Conventions
+
+Error Messages
+--------------
+
+   Some examples signal errors.  This normally displays an error message
+in the echo area.  We show the error message on a line starting with
+`error-->'.  Note that `error-->' itself does not appear in the echo
+area.
+
+     (+ 23 'x)
+     error--> Wrong type argument: integer-or-marker-p, x
+
+
+File: lispref.info,  Node: Buffer Text Notation,  Next: Format of Descriptions,  Prev: Error Messages,  Up: Conventions
+
+Buffer Text Notation
+--------------------
+
+   Some examples show modifications to text in a buffer, with "before"
+and "after" versions of the text.  These examples show the contents of
+the buffer in question between two lines of dashes containing the buffer
+name.  In addition, `-!-' indicates the location of point.  (The symbol
+for point, of course, is not part of the text in the buffer; it
+indicates the place _between_ two characters where point is located.)
+
+     ---------- Buffer: foo ----------
+     This is the -!-contents of foo.
+     ---------- Buffer: foo ----------
+     
+     (insert "changed ")
+          => nil
+     ---------- Buffer: foo ----------
+     This is the changed -!-contents of foo.
+     ---------- Buffer: foo ----------
+
+
+File: lispref.info,  Node: Format of Descriptions,  Prev: Buffer Text Notation,  Up: Conventions
+
+Format of Descriptions
+----------------------
+
+   Functions, variables, macros, commands, user options, and special
+forms are described in this manual in a uniform format.  The first line
+of a description contains the name of the item followed by its
+arguments, if any.  The category--function, variable, or
+whatever--appears at the beginning of the line.  The description
+follows on succeeding lines, sometimes with examples.
+
+* Menu:
+
+* A Sample Function Description::       A description of an imaginary
+                                          function, `foo'.
+* A Sample Variable Description::       A description of an imaginary
+                                          variable,
+                                          `electric-future-map'.
+
+
+File: lispref.info,  Node: A Sample Function Description,  Next: A Sample Variable Description,  Up: Format of Descriptions
+
+A Sample Function Description
+.............................
+
+   In a function description, the name of the function being described
+appears first.  It is followed on the same line by a list of parameters.
+The names used for the parameters are also used in the body of the
+description.
+
+   The appearance of the keyword `&optional' in the parameter list
+indicates that the arguments for subsequent parameters may be omitted
+(omitted parameters default to `nil').  Do not write `&optional' when
+you call the function.
+
+   The keyword `&rest' (which will always be followed by a single
+parameter) indicates that any number of arguments can follow.  The value
+of the single following parameter will be a list of all these arguments.
+Do not write `&rest' when you call the function.
+
+   Here is a description of an imaginary function `foo':
+
+ - Function: foo integer1 &optional integer2 &rest integers
+     The function `foo' subtracts INTEGER1 from INTEGER2, then adds all
+     the rest of the arguments to the result.  If INTEGER2 is not
+     supplied, then the number 19 is used by default.
+
+          (foo 1 5 3 9)
+               => 16
+          (foo 5)
+               => 14
+
+     More generally,
+
+          (foo W X Y...)
+          ==
+          (+ (- X W) Y...)
+
+   Any parameter whose name contains the name of a type (e.g., INTEGER,
+INTEGER1 or BUFFER) is expected to be of that type.  A plural of a type
+(such as BUFFERS) often means a list of objects of that type.
+Parameters named OBJECT may be of any type.  (*Note Lisp Data Types::,
+for a list of XEmacs object types.)  Parameters with other sorts of
+names (e.g., NEW-FILE) are discussed specifically in the description of
+the function.  In some sections, features common to parameters of
+several functions are described at the beginning.
+
+   *Note Lambda Expressions::, for a more complete description of
+optional and rest arguments.
+
+   Command, macro, and special form descriptions have the same format,
+but the word `Function' is replaced by `Command', `Macro', or `Special
+Form', respectively.  Commands are simply functions that may be called
+interactively; macros process their arguments differently from functions
+(the arguments are not evaluated), but are presented the same way.
+
+   Special form descriptions use a more complex notation to specify
+optional and repeated parameters because they can break the argument
+list down into separate arguments in more complicated ways.
+``[OPTIONAL-ARG]'' means that OPTIONAL-ARG is optional and
+`REPEATED-ARGS...' stands for zero or more arguments.  Parentheses are
+used when several arguments are grouped into additional levels of list
+structure.  Here is an example:
+
+ - Special Form: count-loop (VAR [FROM TO [INC]]) BODY...
+     This imaginary special form implements a loop that executes the
+     BODY forms and then increments the variable VAR on each iteration.
+     On the first iteration, the variable has the value FROM; on
+     subsequent iterations, it is incremented by 1 (or by INC if that
+     is given).  The loop exits before executing BODY if VAR equals TO.
+     Here is an example:
+
+          (count-loop (i 0 10)
+            (prin1 i) (princ " ")
+            (prin1 (aref vector i)) (terpri))
+
+     If FROM and TO are omitted, then VAR is bound to `nil' before the
+     loop begins, and the loop exits if VAR is non-`nil' at the
+     beginning of an iteration.  Here is an example:
+
+          (count-loop (done)
+            (if (pending)
+                (fixit)
+              (setq done t)))
+
+     In this special form, the arguments FROM and TO are optional, but
+     must both be present or both absent.  If they are present, INC may
+     optionally be specified as well.  These arguments are grouped with
+     the argument VAR into a list, to distinguish them from BODY, which
+     includes all remaining elements of the form.
+
+
+File: lispref.info,  Node: A Sample Variable Description,  Prev: A Sample Function Description,  Up: Format of Descriptions
+
+A Sample Variable Description
+.............................
+
+   A "variable" is a name that can hold a value.  Although any variable
+can be set by the user, certain variables that exist specifically so
+that users can change them are called "user options".  Ordinary
+variables and user options are described using a format like that for
+functions except that there are no arguments.
+
+   Here is a description of the imaginary `electric-future-map'
+variable.
+
+ - Variable: electric-future-map
+     The value of this variable is a full keymap used by Electric
+     Command Future mode.  The functions in this map allow you to edit
+     commands you have not yet thought about executing.
+
+   User option descriptions have the same format, but `Variable' is
+replaced by `User Option'.
+
+
+File: lispref.info,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction
+
+Acknowledgements
+================
+
+   This manual was based on the GNU Emacs Lisp Reference Manual, version
+2.4, written by Robert Krawitz, Bil Lewis, Dan LaLiberte, Richard M.
+Stallman and Chris Welty, the volunteers of the GNU manual group, in an
+effort extending over several years.  Robert J. Chassell helped to
+review and edit the manual, with the support of the Defense Advanced
+Research Projects Agency, ARPA Order 6082, arranged by Warren A. Hunt,
+Jr. of Computational Logic, Inc.
+
+   Ben Wing adapted this manual for XEmacs 19.14 and 20.0, and earlier
+for Lucid Emacs 19.10, XEmacs 19.12, and XEmacs 19.13.  He is the sole
+author of many of the manual sections, in particular the XEmacs-specific
+sections: events, faces, extents, glyphs, specifiers, toolbar, menubars,
+scrollbars, dialog boxes, devices, consoles, hash tables, range tables,
+char tables, databases, and others.  The section on annotations was
+originally written by Chuck Thompson.  Corrections to v3.1 and later
+were done by Martin Buchholz, Steve Baur, and Hrvoje Niksic.
+
+   Corrections to the original GNU Emacs Lisp Reference Manual were
+supplied by Karl Berry, Jim Blandy, Bard Bloom, Stephane Boucher, David
+Boyes, Alan Carroll, Richard Davis, Lawrence R. Dodd, Peter Doornbosch,
+David A. Duff, Chris Eich, Beverly Erlebacher, David Eckelkamp, Ralf
+Fassel, Eirik Fuller, Stephen Gildea, Bob Glickstein, Eric Hanchrow,
+George Hartzell, Nathan Hess, Masayuki Ida, Dan Jacobson, Jak Kirman,
+Bob Knighten, Frederick M. Korz, Joe Lammens, Glenn M. Lewis, K. Richard
+Magill, Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner
+Myers, Thomas A. Peterson, Francesco Potorti, Friedrich Pukelsheim,
+Arnold D. Robbins, Raul Rockwell, Per Starback, Shinichirou Sugou, Kimmo
+Suominen, Edward Tharp, Bill Trost, Rickard Westman, Jean White, Matthew
+Wilding, Carl Witty, Dale Worley, Rusty Wright, and David D. Zuhn.
+
+
+File: lispref.info,  Node: Lisp Data Types,  Next: Numbers,  Prev: Introduction,  Up: Top
+
+Lisp Data Types
+***************
+
+   A Lisp "object" is a piece of data used and manipulated by Lisp
+programs.  For our purposes, a "type" or "data type" is a set of
+possible objects.
+
+   Every object belongs to at least one type.  Objects of the same type
+have similar structures and may usually be used in the same contexts.
+Types can overlap, and objects can belong to two or more types.
+Consequently, we can ask whether an object belongs to a particular type,
+but not for "the" type of an object.
+
+   A few fundamental object types are built into XEmacs.  These, from
+which all other types are constructed, are called "primitive types".
+Each object belongs to one and only one primitive type.  These types
+include "integer", "character" (starting with XEmacs 20.0), "float",
+"cons", "symbol", "string", "vector", "bit-vector", "subr",
+"compiled-function", "hash-table", "range-table", "char-table",
+"weak-list", and several special types, such as "buffer", that are
+related to editing.  (*Note Editing Types::.)
+
+   Each primitive type has a corresponding Lisp function that checks
+whether an object is a member of that type.
+
+   Note that Lisp is unlike many other languages in that Lisp objects
+are "self-typing": the primitive type of the object is implicit in the
+object itself.  For example, if an object is a vector, nothing can treat
+it as a number; Lisp knows it is a vector, not a number.
+
+   In most languages, the programmer must declare the data type of each
+variable, and the type is known by the compiler but not represented in
+the data.  Such type declarations do not exist in XEmacs Lisp.  A Lisp
+variable can have any type of value, and it remembers whatever value
+you store in it, type and all.
+
+   This chapter describes the purpose, printed representation, and read
+syntax of each of the standard types in Emacs Lisp.  Details on how to
+use these types can be found in later chapters.
+
+* Menu:
+
+* Printed Representation::      How Lisp objects are represented as text.
+* Comments::                    Comments and their formatting conventions.
+* Primitive Types::             List of all primitive types in XEmacs.
+* Programming Types::           Types found in all Lisp systems.
+* Editing Types::               Types specific to XEmacs.
+* Window-System Types::         Types specific to windowing systems.
+* Type Predicates::             Tests related to types.
+* Equality Predicates::         Tests of equality between any two objects.
+
+
+File: lispref.info,  Node: Printed Representation,  Next: Comments,  Up: Lisp Data Types
+
+Printed Representation and Read Syntax
+======================================
+
+   The "printed representation" of an object is the format of the
+output generated by the Lisp printer (the function `prin1') for that
+object.  The "read syntax" of an object is the format of the input
+accepted by the Lisp reader (the function `read') for that object.
+Most objects have more than one possible read syntax.  Some types of
+object have no read syntax; except for these cases, the printed
+representation of an object is also a read syntax for it.
+
+   In other languages, an expression is text; it has no other form.  In
+Lisp, an expression is primarily a Lisp object and only secondarily the
+text that is the object's read syntax.  Often there is no need to
+emphasize this distinction, but you must keep it in the back of your
+mind, or you will occasionally be very confused.
+
+   Every type has a printed representation.  Some types have no read
+syntax, since it may not make sense to enter objects of these types
+directly in a Lisp program.  For example, the buffer type does not have
+a read syntax.  Objects of these types are printed in "hash notation":
+the characters `#<' followed by a descriptive string (typically the
+type name followed by the name of the object), and closed with a
+matching `>'.  Hash notation cannot be read at all, so the Lisp reader
+signals the error `invalid-read-syntax' whenever it encounters `#<'.
+
+     (current-buffer)
+          => #<buffer "objects.texi">
+
+   When you evaluate an expression interactively, the Lisp interpreter
+first reads the textual representation of it, producing a Lisp object,
+and then evaluates that object (*note Evaluation::).  However,
+evaluation and reading are separate activities.  Reading returns the
+Lisp object represented by the text that is read; the object may or may
+not be evaluated later.  *Note Input Functions::, for a description of
+`read', the basic function for reading objects.
+
+
+File: lispref.info,  Node: Comments,  Next: Primitive Types,  Prev: Printed Representation,  Up: Lisp Data Types
+
+Comments
+========
+
+   A "comment" is text that is written in a program only for the sake
+of humans that read the program, and that has no effect on the meaning
+of the program.  In Lisp, a semicolon (`;') starts a comment if it is
+not within a string or character constant.  The comment continues to
+the end of line.  The Lisp reader discards comments; they do not become
+part of the Lisp objects which represent the program within the Lisp
+system.
+
+   The `#@COUNT' construct, which skips the next COUNT characters, is
+useful for program-generated comments containing binary data.  The
+XEmacs Lisp byte compiler uses this in its output files (*note Byte
+Compilation::).  It isn't meant for source files, however.
+
+   *Note Comment Tips::, for conventions for formatting comments.
+
+
+File: lispref.info,  Node: Primitive Types,  Next: Programming Types,  Prev: Comments,  Up: Lisp Data Types
+
+Primitive Types
+===============
+
+   For reference, here is a list of all the primitive types that may
+exist in XEmacs.  Note that some of these types may not exist in some
+XEmacs executables; that depends on the options that XEmacs was
+configured with.
+
+   * bit-vector
+
+   * buffer
+
+   * char-table
+
+   * character
+
+   * charset
+
+   * coding-system
+
+   * cons
+
+   * color-instance
+
+   * compiled-function
+
+   * console
+
+   * database
+
+   * device
+
+   * event
+
+   * extent
+
+   * face
+
+   * float
+
+   * font-instance
+
+   * frame
+
+   * glyph
+
+   * hash-table
+
+   * image-instance
+
+   * integer
+
+   * keymap
+
+   * marker
+
+   * process
+
+   * range-table
+
+   * specifier
+
+   * string
+
+   * subr
+
+   * subwindow
+
+   * symbol
+
+   * toolbar-button
+
+   * tooltalk-message
+
+   * tooltalk-pattern
+
+   * vector
+
+   * weak-list
+
+   * window
+
+   * window-configuration
+
+   * x-resource
+
+   In addition, the following special types are created internally but
+will never be seen by Lisp code.  You may encounter them, however, if
+you are debugging XEmacs.  The printed representation of these objects
+begins `#<INTERNAL EMACS BUG', which indicates to the Lisp programmer
+that he has found an internal bug in XEmacs if he ever encounters any
+of these objects.
+
+   * char-table-entry
+
+   * command-builder
+
+   * extent-auxiliary
+
+   * extent-info
+
+   * lcrecord-list
+
+   * lstream
+
+   * opaque
+
+   * opaque-list
+
+   * popup-data
+
+   * symbol-value-buffer-local
+
+   * symbol-value-forward
+
+   * symbol-value-lisp-magic
+
+   * symbol-value-varalias
+
+   * toolbar-data
+
+
+File: lispref.info,  Node: Programming Types,  Next: Editing Types,  Prev: Primitive Types,  Up: Lisp Data Types
+
+Programming Types
+=================
+
+   There are two general categories of types in XEmacs Lisp: those
+having to do with Lisp programming, and those having to do with
+editing.  The former exist in many Lisp implementations, in one form or
+another.  The latter are unique to XEmacs Lisp.
+
+* Menu:
+
+* Integer Type::        Numbers without fractional parts.
+* Floating Point Type:: Numbers with fractional parts and with a large range.
+* Character Type::      The representation of letters, numbers and
+                        control characters.
+* Symbol Type::         A multi-use object that refers to a function,
+                        variable, or property list, and has a unique identity.
+* Sequence Type::       Both lists and arrays are classified as sequences.
+* Cons Cell Type::      Cons cells, and lists (which are made from cons cells).
+* Array Type::          Arrays include strings and vectors.
+* String Type::         An (efficient) array of characters.
+* Vector Type::         One-dimensional arrays.
+* Bit Vector Type::     An (efficient) array of bits.
+* Function Type::       A piece of executable code you can call from elsewhere.
+* Macro Type::          A method of expanding an expression into another
+                          expression, more fundamental but less pretty.
+* Primitive Function Type::     A function written in C, callable from Lisp.
+* Compiled-Function Type::      A function written in Lisp, then compiled.
+* Autoload Type::       A type used for automatically loading seldom-used
+                        functions.
+* Char Table Type::     A mapping from characters to Lisp objects.
+* Hash Table Type::     A fast mapping between Lisp objects.
+* Range Table Type::    A mapping from ranges of integers to Lisp objects.
+* Weak List Type::      A list with special garbage-collection properties.
+
+
+File: lispref.info,  Node: Integer Type,  Next: Floating Point Type,  Up: Programming Types
+
+Integer Type
+------------
+
+   The range of values for integers in XEmacs Lisp is -134217728 to
+134217727 (28 bits; i.e., -2**27 to 2**27 - 1) on most machines.  (Some
+machines, in particular 64-bit machines such as the DEC Alpha, may
+provide a wider range.)  It is important to note that the XEmacs Lisp
+arithmetic functions do not check for overflow.  Thus `(1+ 134217727)'
+is -134217728 on most machines. (However, you _will_ get an error if
+you attempt to read an out-of-range number using the Lisp reader.)
+
+   The read syntax for integers is a sequence of (base ten) digits with
+an optional sign at the beginning. (The printed representation produced
+by the Lisp interpreter never has a leading `+'.)
+
+     -1               ; The integer -1.
+     1                ; The integer 1.
+     +1               ; Also the integer 1.
+     268435457        ; Causes an error on a 28-bit implementation.
+
+   *Note Numbers::, for more information.
+
+
+File: lispref.info,  Node: Floating Point Type,  Next: Character Type,  Prev: Integer Type,  Up: Programming Types
+
+Floating Point Type
+-------------------
+
+   XEmacs supports floating point numbers.  The precise range of
+floating point numbers is machine-specific.
+
+   The printed representation for floating point numbers requires either
+a decimal point (with at least one digit following), an exponent, or
+both.  For example, `1500.0', `15e2', `15.0e2', `1.5e3', and `.15e4'
+are five ways of writing a floating point number whose value is 1500.
+They are all equivalent.
+
+   *Note Numbers::, for more information.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-20'
Index: ././info/lispref.info-20
--- ././info/lispref.info-20	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-20	Thu May 17 23:26:54 2001
@@ -0,0 +1,1224 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Menu Format,  Next: Menubar Format,  Up: Menus
+
+Format of Menus
+===============
+
+   A menu is described using a "menu description", which is a list of
+menu items, keyword-value pairs, strings, and submenus.  The menu
+description specifies which items are present in the menu, what function
+each item invokes, and whether the item is selectable or not.  Pop-up
+menus are directly described with a menu description, while menubars are
+described slightly differently (see below).
+
+   The first element of a menu must be a string, which is the name of
+the menu.  This is the string that will be displayed in the parent menu
+or menubar, if any.  This string is not displayed in the menu itself,
+except in the case of the top level pop-up menu, where there is no
+parent.  In this case, the string will be displayed at the top of the
+menu if `popup-menu-titles' is non-`nil'.
+
+   Immediately following the first element there may optionally be up
+to four keyword-value pairs, as follows:
+
+`:included FORM'
+     This can be used to control the visibility of a menu.  The form is
+     evaluated and the menu will be omitted if the result is `nil'.
+
+`:config SYMBOL'
+     This is an efficient shorthand for `:included (memq SYMBOL
+     menubar-configuration)'.  See the variable `menubar-configuration'.
+
+`:filter FUNCTION'
+     A menu filter is used to sensitize or incrementally create a
+     submenu only when it is selected by the user and not every time
+     the menubar is activated.  The filter function is passed the list
+     of menu items in the submenu and must return a list of menu items
+     to be used for the menu.  It is called only when the menu is about
+     to be displayed, so other menus may already be displayed.  Vile
+     and terrible things will happen if a menu filter function changes
+     the current buffer, window, or frame.  It also should not raise,
+     lower, or iconify any frames.  Basically, the filter function
+     should have no side-effects.
+
+`:accelerator KEY'
+     A menu accelerator is a keystroke which can be pressed while the
+     menu is visible which will immediately activate the item.  KEY
+     must be a char or the symbol name of a key.  *Note Menu
+     Accelerators::.
+
+   The rest of the menu consists of elements as follows:
+
+   * A "menu item", which is a vector in the following form:
+
+          `[ NAME CALLBACK :KEYWORD VALUE :KEYWORD VALUE ... ]'
+
+     NAME is a string, the name of the menu item; it is the string to
+     display on the menu.  It is filtered through the resource
+     database, so it is possible for resources to override what string
+     is actually displayed.
+
+     CALLBACK is a form that will be invoked when the menu item is
+     selected.  If the callback of a menu item is a symbol, then it
+     must name a command.  It will be invoked with
+     `call-interactively'.  If it is a list, then it is evaluated with
+     `eval'.
+
+     The valid keywords and their meanings are described below.
+
+     Note that for compatibility purposes, the form
+
+          `[ NAME CALLBACK ACTIVE-P ]'
+
+     is also accepted and is equivalent to
+
+          `[ NAME CALLBACK :active ACTIVE-P ]'
+
+     and the form
+
+          `[ NAME CALLBACK ACTIVE-P SUFFIX]'
+
+     is accepted and is equivalent to
+
+          `[ NAME CALLBACK :active ACTIVE-P :suffix SUFFIX]'
+
+     However, these older forms are deprecated and should generally not
+     be used.
+
+   * If an element of a menu is a string, then that string will be
+     presented in the menu as unselectable text.
+
+   * If an element of a menu is a string consisting solely of hyphens,
+     then that item will be presented as a solid horizontal line.
+
+   * If an element of a menu is a string beginning with `--:', then a
+     particular sort of horizontal line will be displayed, as follows:
+
+    `"--:singleLine"'
+          A solid horizontal line.  This is equivalent to a string
+          consisting solely of hyphens.
+
+    `"--:doubleLine"'
+          A solid double horizontal line.
+
+    `"--:singleDashedLine"'
+          A dashed horizontal line.
+
+    `"--:doubleDashedLine"'
+          A dashed double horizontal line.
+
+    `"--:noLine"'
+          No line (but a small space is left).
+
+    `"--:shadowEtchedIn"'
+          A solid horizontal line with a 3-d recessed appearance.
+
+    `"--:shadowEtchedOut"'
+          A solid horizontal line with a 3-d pushed-out appearance.
+
+    `"--:shadowDoubleEtchedIn"'
+          A solid double horizontal line with a 3-d recessed appearance.
+
+    `"--:shadowDoubleEtchedOut"'
+          A solid double horizontal line with a 3-d pushed-out
+          appearance.
+
+    `"--:shadowEtchedInDash"'
+          A dashed horizontal line with a 3-d recessed appearance.
+
+    `"--:shadowEtchedOutDash"'
+          A dashed horizontal line with a 3-d pushed-out appearance.
+
+    `"--:shadowDoubleEtchedInDash"'
+          A dashed double horizontal line with a 3-d recessed
+          appearance.
+
+    `"--:shadowDoubleEtchedOutDash"'
+          A dashed double horizontal line with a 3-d pushed-out
+          appearance.
+
+   * If an element of a menu is a list, it is treated as a submenu.
+     The name of that submenu (the first element in the list) will be
+     used as the name of the item representing this menu on the parent.
+
+   The possible keywords are as follows:
+
+:active FORM
+     FORM will be evaluated when the menu that this item is a part of
+     is about to be displayed, and the item will be selectable only if
+     the result is non-`nil'.  If the item is unselectable, it will
+     usually be displayed grayed-out to indicate this.
+
+:suffix FORM
+     FORM will be evaluated when the menu that this item is a part of
+     is about to be displayed, and the resulting string is appended to
+     the displayed name.  This provides a convenient way of adding the
+     name of a command's "argument" to the menu, like `Kill Buffer
+     NAME'.
+
+:keys STRING
+     Normally, the keyboard equivalents of commands in menus are
+     displayed when the "callback" is a symbol.  This can be used to
+     specify keys for more complex menu items.  It is passed through
+     `substitute-command-keys' first.
+
+:style STYLE
+     Specifies what kind of object this menu item is.  STYLE be one of
+     the symbols
+
+    `nil'
+          A normal menu item.
+
+    `toggle'
+          A toggle button.
+
+    `radio'
+          A radio button.
+
+    `button'
+          A menubar button.
+
+     The only difference between toggle and radio buttons is how they
+     are displayed.  But for consistency, a toggle button should be
+     used when there is one option whose value can be turned on or off,
+     and radio buttons should be used when there is a set of mutually
+     exclusive options.  When using a group of radio buttons, you
+     should arrange for no more than one to be marked as selected at a
+     time.
+
+:selected FORM
+     Meaningful only when STYLE is `toggle', `radio' or `button'.  This
+     specifies whether the button will be in the selected or unselected
+     state.  FORM is evaluated, as for `:active'.
+
+:included FORM
+     This can be used to control the visibility of a menu item.  The
+     form is evaluated and the menu item is only displayed if the
+     result is non-`nil'.  Note that this is different from `:active':
+     If `:active' evaluates to `nil', the item will be displayed grayed
+     out, while if `:included' evaluates to `nil', the item will be
+     omitted entirely.
+
+:config SYMBOL
+     This is an efficient shorthand for `:included (memq SYMBOL
+     menubar-configuration)'.  See the variable `menubar-configuration'.
+
+:accelerator KEY
+     A menu accelerator is a keystroke which can be pressed while the
+     menu is visible which will immediately activate the item.  KEY
+     must be a char or the symbol name of a key.  *Note Menu
+     Accelerators::.
+
+ - Variable: menubar-configuration
+     This variable holds a list of symbols, against which the value of
+     the `:config' tag for each menubar item will be compared.  If a
+     menubar item has a `:config' tag, then it is omitted from the
+     menubar if that tag is not a member of the `menubar-configuration'
+     list.
+
+   For example:
+
+      ("File"
+       :filter file-menu-filter      ; file-menu-filter is a function that takes
+                                     ; one argument (a list of menu items) and
+                                     ; returns a list of menu items
+       [ "Save As..."    write-file]
+       [ "Revert Buffer" revert-buffer :active (buffer-modified-p) ]
+       [ "Read Only"     toggle-read-only :style toggle :selected buffer-read-only ]
+       )
+
+
+File: lispref.info,  Node: Menubar Format,  Next: Menubar,  Prev: Menu Format,  Up: Menus
+
+Format of the Menubar
+=====================
+
+   A menubar is a list of menus, menu items, and strings.  The format is
+similar to that of a menu, except:
+
+   * The first item need not be a string, and is not treated specially.
+
+   * A string consisting solely of hyphens is not treated specially.
+
+   * If an element of a menubar is `nil', then it is used to represent
+     the division between the set of menubar items which are flush-left
+     and those which are flush-right.  (Note: this isn't completely
+     implemented yet.)
+
+
+File: lispref.info,  Node: Menubar,  Next: Modifying Menus,  Prev: Menubar Format,  Up: Menus
+
+Menubar
+=======
+
+ - Variable: current-menubar
+     This variable holds the description of the current menubar.  This
+     may be buffer-local.  When the menubar is changed, the function
+     `set-menubar-dirty-flag' has to be called in order for the menubar
+     to be updated on the screen.
+
+ - Constant: default-menubar
+     This variable holds the menubar description of the menubar that is
+     visible at startup.  This is the value that `current-menubar' has
+     at startup.
+
+ - Function: set-menubar-dirty-flag
+     This function tells XEmacs that the menubar widget has to be
+     updated.  Changes to the menubar will generally not be visible
+     until this function is called.
+
+   The following convenience functions are provided for setting the
+menubar.  They are equivalent to doing the appropriate action to change
+`current-menubar', and then calling `set-menubar-dirty-flag'.  Note
+that these functions copy their argument using `copy-sequence'.
+
+ - Function: set-menubar menubar
+     This function sets the default menubar to be MENUBAR (*note Menu
+     Format::).  This is the menubar that will be visible in buffers
+     that have not defined their own, buffer-local menubar.
+
+ - Function: set-buffer-menubar menubar
+     This function sets the buffer-local menubar to be MENUBAR.  This
+     does not change the menubar in any buffers other than the current
+     one.
+
+   Miscellaneous:
+
+ - Variable: menubar-show-keybindings
+     If true, the menubar will display keyboard equivalents.  If false,
+     only the command names will be displayed.
+
+ - Variable: activate-menubar-hook
+     Function or functions called before a menubar menu is pulled down.
+     These functions are called with no arguments, and should
+     interrogate and modify the value of `current-menubar' as desired.
+
+     The functions on this hook are invoked after the mouse goes down,
+     but before the menu is mapped, and may be used to activate,
+     deactivate, add, or delete items from the menus.  However, using a
+     filter (with the `:filter' keyword in a menu description) is
+     generally a more efficient way of accomplishing the same thing,
+     because the filter is invoked only when the actual menu goes down.
+     With a complex menu, there can be a quite noticeable and
+     sometimes aggravating delay if all menu modification is
+     implemented using the `activate-menubar-hook'.  See above.
+
+     These functions may return the symbol `t' to assert that they have
+     made no changes to the menubar.  If any other value is returned,
+     the menubar is recomputed.  If `t' is returned but the menubar has
+     been changed, then the changes may not show up right away.
+     Returning `nil' when the menubar has not changed is not so bad;
+     more computation will be done, but redisplay of the menubar will
+     still be performed optimally.
+
+ - Variable: menu-no-selection-hook
+     Function or functions to call when a menu or dialog box is
+     dismissed without a selection having been made.
+
+
+File: lispref.info,  Node: Modifying Menus,  Next: Pop-Up Menus,  Prev: Menubar,  Up: Menus
+
+Modifying Menus
+===============
+
+   The following functions are provided to modify the menubar of one of
+its submenus.  Note that these functions modify the menu in-place,
+rather than copying it and making a new menu.
+
+   Some of these functions take a "menu path", which is a list of
+strings identifying the menu to be modified.  For example, `("File")'
+names the top-level "File" menu.  `("File" "Foo")' names a hypothetical
+submenu of "File".
+
+   Others take a "menu item path", which is similar to a menu path but
+also specifies a particular item to be modified.  For example, `("File"
+"Save")' means the menu item called "Save" under the top-level "File"
+menu.  `("Menu" "Foo" "Item")' means the menu item called "Item" under
+the "Foo" submenu of "Menu".
+
+ - Function: add-submenu menu-path submenu &optional before in-menu
+     This function adds a menu to the menubar or one of its submenus.
+     If the named menu exists already, it is changed.
+
+     MENU-PATH identifies the menu under which the new menu should be
+     inserted.  If MENU-PATH is `nil', then the menu will be added to
+     the menubar itself.
+
+     SUBMENU is the new menu to add (*note Menu Format::).
+
+     BEFORE, if provided, is the name of a menu before which this menu
+     should be added, if this menu is not on its parent already.  If
+     the menu is already present, it will not be moved.
+
+     If IN-MENU is present use that instead of `current-menubar' as the
+     menu to change.
+
+ - Function: add-menu-button menu-path menu-leaf &optional before
+          in-menu
+     This function adds a menu item to some menu, creating the menu
+     first if necessary.  If the named item exists already, it is
+     changed.
+
+     MENU-PATH identifies the menu under which the new menu item should
+     be inserted.
+
+     MENU-LEAF is a menubar leaf node (*note Menu Format::).
+
+     BEFORE, if provided, is the name of a menu before which this item
+     should be added, if this item is not on the menu already.  If the
+     item is already present, it will not be moved.
+
+     If IN-MENU is present use that instead of `current-menubar' as the
+     menu to change.
+
+ - Function: delete-menu-item menu-item-path &optional from-menu
+     This function removes the menu item specified by MENU-ITEM-PATH
+     from the menu hierarchy.
+
+     If FROM-MENU is present use that instead of `current-menubar' as
+     the menu to change.
+
+ - Function: enable-menu-item menu-item-path
+     This function makes the menu item specified by MENU-ITEM-PATH be
+     selectable.
+
+ - Function: disable-menu-item menu-item-path
+     This function makes the menu item specified by MENU-ITEM-PATH be
+     unselectable.
+
+ - Function: relabel-menu-item menu-item-path new-name
+     This function changes the string of the menu item specified by
+     MENU-ITEM-PATH.  NEW-NAME is the string that the menu item will be
+     printed as from now on.
+
+   The following function can be used to search for a particular item in
+a menubar specification, given a path to the item.
+
+ - Function: find-menu-item menubar menu-item-path &optional parent
+     This function searches MENUBAR for the item given by
+     MENU-ITEM-PATH starting from PARENT (`nil' means start at the top
+     of MENUBAR).  This function returns `(ITEM . PARENT)', where
+     PARENT is the immediate parent of the item found (a menu
+     description), and ITEM is either a vector, list, or string,
+     depending on the nature of the menu item.
+
+     This function signals an error if the item is not found.
+
+   The following deprecated functions are also documented, so that
+existing code can be understood.  You should not use these functions in
+new code.
+
+ - Function: add-menu menu-path menu-name menu-items &optional before
+     This function adds a menu to the menubar or one of its submenus.
+     If the named menu exists already, it is changed.  This is
+     obsolete; use `add-submenu' instead.
+
+     MENU-PATH identifies the menu under which the new menu should be
+     inserted.  If MENU-PATH is `nil', then the menu will be added to
+     the menubar itself.
+
+     MENU-NAME is the string naming the menu to be added; MENU-ITEMS is
+     a list of menu items, strings, and submenus.  These two arguments
+     are the same as the first and following elements of a menu
+     description (*note Menu Format::).
+
+     BEFORE, if provided, is the name of a menu before which this menu
+     should be added, if this menu is not on its parent already.  If the
+     menu is already present, it will not be moved.
+
+ - Function: add-menu-item menu-path item-name function enabled-p
+          &optional before
+     This function adds a menu item to some menu, creating the menu
+     first if necessary.  If the named item exists already, it is
+     changed.  This is obsolete; use `add-menu-button' instead.
+
+     MENU-PATH identifies the menu under which the new menu item should
+     be inserted. ITEM-NAME, FUNCTION, and ENABLED-P are the first,
+     second, and third elements of a menu item vector (*note Menu
+     Format::).
+
+     BEFORE, if provided, is the name of a menu item before which this
+     item should be added, if this item is not on the menu already.  If
+     the item is already present, it will not be moved.
+
+
+File: lispref.info,  Node: Menu Filters,  Next: Menu Accelerators,  Prev: Pop-Up Menus,  Up: Menus
+
+Menu Filters
+============
+
+   The following filter functions are provided for use in
+`default-menubar'.  You may want to use them in your own menubar
+description.
+
+ - Function: file-menu-filter menu-items
+     This function changes the arguments and sensitivity of these File
+     menu items:
+
+    `Delete Buffer'
+          Has the name of the current buffer appended to it.
+
+    `Print Buffer'
+          Has the name of the current buffer appended to it.
+
+    `Pretty-Print Buffer'
+          Has the name of the current buffer appended to it.
+
+    `Save Buffer'
+          Has the name of the current buffer appended to it, and is
+          sensitive only when the current buffer is modified.
+
+    `Revert Buffer'
+          Has the name of the current buffer appended to it, and is
+          sensitive only when the current buffer has a file.
+
+    `Delete Frame'
+          Sensitive only when there is more than one visible frame.
+
+ - Function: edit-menu-filter menu-items
+     This function changes the arguments and sensitivity of these Edit
+     menu items:
+
+    `Cut'
+          Sensitive only when XEmacs owns the primary X Selection (if
+          `zmacs-regions' is `t', this is equivalent to saying that
+          there is a region selected).
+
+    `Copy'
+          Sensitive only when XEmacs owns the primary X Selection.
+
+    `Clear'
+          Sensitive only when XEmacs owns the primary X Selection.
+
+    `Paste'
+          Sensitive only when there is an owner for the X Clipboard
+          Selection.
+
+    `Undo'
+          Sensitive only when there is undo information.  While in the
+          midst of an undo, this is changed to `Undo More'.
+
+ - Function: buffers-menu-filter menu-items
+     This function sets up the Buffers menu.  *Note Buffers Menu::, for
+     more information.
+
+
+File: lispref.info,  Node: Pop-Up Menus,  Next: Menu Filters,  Prev: Modifying Menus,  Up: Menus
+
+Pop-Up Menus
+============
+
+ - Function: popup-menu menu-description &optional event
+     This function pops up a menu specified by MENU-DESCRIPTION, which
+     is a menu description (*note Menu Format::).  The menu is
+     displayed at the current mouse position.
+
+ - Function: popup-menu-up-p
+     This function returns `t' if a pop-up menu is up, `nil' otherwise.
+
+ - Variable: popup-menu-titles
+     If true (the default), pop-up menus will have title bars at the
+     top.
+
+   Some machinery is provided that attempts to provide a higher-level
+mechanism onto pop-up menus.  This only works if you do not redefine
+the binding for button3.
+
+ - Command: popup-mode-menu
+     This function pops up a menu of global and mode-specific commands.
+     The menu is computed by combining `global-popup-menu' and
+     `mode-popup-menu'.  This is the default binding for button3.  You
+     should generally not change this binding.
+
+ - Variable: global-popup-menu
+     This holds the global popup menu.  This is present in all modes.
+     (This is `nil' by default.)
+
+ - Variable: mode-popup-menu
+     The mode-specific popup menu.  Automatically buffer local.  This
+     is appended to the default items in `global-popup-menu'.
+
+ - Constant: default-popup-menu
+     This holds the default value of `mode-popup-menu'.
+
+ - Variable: activate-popup-menu-hook
+     Function or functions run before a mode-specific popup menu is made
+     visible.  These functions are called with no arguments, and should
+     interrogate and modify the value of `global-popup-menu' or
+     `mode-popup-menu' as desired.  Note: this hook is only run if you
+     use `popup-mode-menu' for activating the global and mode-specific
+     commands; if you have your own binding for button3, this hook
+     won't be run.
+
+   The following convenience functions are provided for displaying
+pop-up menus.
+
+ - Command: popup-buffer-menu event
+     This function pops up a copy of the `Buffers' menu (from the
+     menubar) where the mouse is clicked.  It should be bound to a
+     mouse button event.
+
+ - Command: popup-menubar-menu event
+     This function pops up a copy of menu that also appears in the
+     menubar.  It should be bound to a mouse button event.
+
+
+File: lispref.info,  Node: Menu Accelerators,  Next: Buffers Menu,  Prev: Menu Filters,  Up: Menus
+
+Menu Accelerators
+=================
+
+   Menu accelerators are keyboard shortcuts for accessing the menubar.
+Accelerator keys can be specified for menus as well as for menu items.
+An accelerator key for a menu is used to activate that menu when it
+appears as a submenu of another menu.  An accelerator key for a menu
+item is used to activate that item.
+
+* Menu:
+
+* Creating Menu Accelerators::  How to add accelerator keys to a menu.
+* Keyboard Menu Traversal::     How to use and modify the keys which are used
+                                to traverse the menu structure.
+* Menu Accelerator Functions::  Functions for working with menu accelerators.
+
+
+File: lispref.info,  Node: Creating Menu Accelerators,  Next: Keyboard Menu Traversal,  Up: Menu Accelerators
+
+Creating Menu Accelerators
+--------------------------
+
+   Menu accelerators are specified as part of the menubar format using
+the :accelerator tag to specify a key or by placing "%_" in the menu or
+menu item name prior to the letter which is to be used as the
+accelerator key.  The advantage of the second method is that the menu
+rendering code then knows to draw an underline under that character,
+which is the canonical way of indicating an accelerator key to a user.
+
+   For example, the command
+
+     (add-submenu nil '("%_Test"
+                        ["One" (insert "1") :accelerator ?1 :active t]
+                        ["%_Two" (insert "2")]
+                        ["%_3" (insert "3")]))
+
+   will add a new menu to the top level menubar.  The new menu can be
+reached by pressing "t" while the top level menubar is active.  When
+the menu is active, pressing "1" will activate the first item and
+insert the character "1" into the buffer.  Pressing "2" will activate
+the second item and insert the character "2" into the buffer.  Pressing
+"3" will activate the third item and insert the character "3" into the
+buffer.
+
+   It is possible to activate the top level menubar itself using
+accelerator keys.  *Note Menu Accelerator Functions::.
+
+
+File: lispref.info,  Node: Keyboard Menu Traversal,  Next: Menu Accelerator Functions,  Prev: Creating Menu Accelerators,  Up: Menu Accelerators
+
+Keyboard Menu Traversal
+-----------------------
+
+   In addition to immediately activating a menu or menu item, the
+keyboard can be used to traverse the menus without activating items.
+The keyboard arrow keys, the return key and the escape key are defined
+to traverse the menus in a way that should be familiar to users of any
+of a certain family of popular PC operating systems.
+
+   This behavior can be changed by modifying the bindings in
+menu-accelerator-map.  At this point, the online help is your best bet
+for more information about how to modify the menu traversal keys.
+
+
+File: lispref.info,  Node: Menu Accelerator Functions,  Prev: Keyboard Menu Traversal,  Up: Menu Accelerators
+
+Menu Accelerator Functions
+--------------------------
+
+ - Command: accelerate-menu
+     Make the menubar immediately active and place the cursor on the
+     left most entry in the top level menu.  Menu items can be selected
+     as usual.
+
+ - Variable: menu-accelerator-enabled
+     Whether menu accelerator keys can cause the menubar to become
+     active.
+
+     If `menu-force' or `menu-fallback', then menu accelerator keys can
+     be used to activate the top level menu.  Once the menubar becomes
+     active, the accelerator keys can be used regardless of the value
+     of this variable.
+
+     `menu-force' is used to indicate that the menu accelerator key
+     takes precedence over bindings in the current keymap(s).
+     `menu-fallback' means that bindings in the current keymap take
+     precedence over menu accelerator keys.  Thus a top level menu with
+     an accelerator of "T" would be activated on a keypress of Meta-t
+     if MENU-ACCELERATOR-ENABLED is `menu-force'.  However, if
+     MENU-ACCELERATOR-ENABLED is `menu-fallback', then Meta-t will not
+     activate the menubar and will instead run the function
+     transpose-words, to which it is normally bound.
+
+     The default value is `nil'.
+
+     See also MENU-ACCELERATOR-MODIFIERS and MENU-ACCELERATOR-PREFIX.
+
+ - Variable: menu-accelerator-map
+     Keymap consulted to determine the commands to run in response to
+     keypresses occurring while the menubar is active.  *Note Keyboard
+     Menu Traversal::.
+
+ - Variable: menu-accelerator-modifiers
+     A list of modifier keys which must be pressed in addition to a
+     valid menu accelerator in order for the top level menu to be
+     activated in response to a keystroke.  The default value of
+     `(meta)' mirrors the usage of the alt key as a menu accelerator in
+     popular PC operating systems.
+
+     The modifier keys in MENU-ACCELERATOR-MODIFIERS must match exactly
+     the modifiers present in the keypress.  The only exception is that
+     the shift modifier is accepted in conjunction with alphabetic keys
+     even if it is not a menu accelerator modifier.
+
+     See also MENU-ACCELERATOR-ENABLED and MENU-ACCELERATOR-PREFIX.
+
+ - Variable: menu-accelerator-prefix
+     Prefix key(s) that must be typed before menu accelerators will be
+     activated.  Must be a valid key descriptor.
+
+     The default value is `nil'.
+
+     (setq menu-accelerator-prefix ?\C-x)
+     (setq menu-accelerator-modifiers '(meta control))
+     (setq menu-accelerator-enabled 'menu-force)
+     (add-submenu nil '("%_Test"
+                        ["One" (insert "1") :accelerator ?1 :active t]
+                        ["%_Two" (insert "2")]
+                        ["%_3" (insert "3")]))
+
+   will add the menu "Test" to the top level menubar.  Pressing C-x
+followed by C-M-T will activate the menubar and display the "Test"
+menu.  Pressing C-M-T by itself will not activate the menubar.  Neither
+will pressing C-x followed by anything else.
+
+
+File: lispref.info,  Node: Buffers Menu,  Prev: Menu Accelerators,  Up: Menus
+
+Buffers Menu
+============
+
+   The following options control how the `Buffers' menu is displayed.
+This is a list of all (or a subset of) the buffers currently in
+existence, and is updated dynamically.
+
+ - User Option: buffers-menu-max-size
+     This user option holds the maximum number of entries which may
+     appear on the `Buffers' menu.  If this is 10, then only the ten
+     most-recently-selected buffers will be shown.  If this is `nil',
+     then all buffers will be shown.  Setting this to a large number or
+     `nil' will slow down menu responsiveness.
+
+ - Function: format-buffers-menu-line buffer
+     This function returns a string to represent BUFFER in the
+     `Buffers' menu.  `nil' means the buffer shouldn't be listed.  You
+     can redefine this.
+
+ - User Option: complex-buffers-menu-p
+     If true, the `Buffers' menu will contain several commands, as
+     submenus of each buffer line.  If this is false, then there will
+     be only one command: select that buffer.
+
+ - User Option: buffers-menu-switch-to-buffer-function
+     This user option holds the function to call to select a buffer
+     from the `Buffers' menu.  `switch-to-buffer' is a good choice, as
+     is `pop-to-buffer'.
+
+
+File: lispref.info,  Node: Dialog Boxes,  Next: Toolbar,  Prev: Menus,  Up: Top
+
+Dialog Boxes
+************
+
+* Menu:
+
+* Dialog Box Format::
+* Dialog Box Functions::
+
+
+File: lispref.info,  Node: Dialog Box Format,  Next: Dialog Box Functions,  Up: Dialog Boxes
+
+Dialog Box Format
+=================
+
+   A dialog box description is a list.
+
+   * The first element of the list is a string to display in the dialog
+     box.
+
+   * The rest of the elements are descriptions of the dialog box's
+     buttons.  Each one is a vector of three elements:
+        - The first element is the text of the button.
+
+        - The second element is the "callback".
+
+        - The third element is `t' or `nil', whether this button is
+          selectable.
+
+   If the callback of a button is a symbol, then it must name a command.
+It will be invoked with `call-interactively'.  If it is a list, then it
+is evaluated with `eval'.
+
+   One (and only one) of the buttons may be `nil'.  This marker means
+that all following buttons should be flushright instead of flushleft.
+
+   The syntax, more precisely:
+
+        form         :=  <something to pass to `eval'>
+        command      :=  <a symbol or string, to pass to `call-interactively'>
+        callback     :=  command | form
+        active-p     :=  <t, nil, or a form to evaluate to decide whether this
+                         button should be selectable>
+        name         :=  <string>
+        partition    :=  'nil'
+        button       :=  '['  name callback active-p ']'
+        dialog       :=  '(' name [ button ]+ [ partition [ button ]+ ] ')'
+
+
+File: lispref.info,  Node: Dialog Box Functions,  Prev: Dialog Box Format,  Up: Dialog Boxes
+
+Dialog Box Functions
+====================
+
+ - Function: popup-dialog-box dbox-desc
+     This function pops up a dialog box.  DBOX-DESC describes how the
+     dialog box will appear (*note Dialog Box Format::).
+
+   *Note Yes-or-No Queries::, for functions to ask a yes/no question
+using a dialog box.
+
+
+File: lispref.info,  Node: Toolbar,  Next: Gutter,  Prev: Dialog Boxes,  Up: Top
+
+Toolbar
+*******
+
+* Menu:
+
+* Toolbar Intro::		An introduction.
+* Creating Toolbar::            How to create a toolbar.
+* Toolbar Descriptor Format::	Accessing and modifying a toolbar's
+                                  properties.
+* Specifying the Toolbar::	Setting a toolbar's contents.
+* Other Toolbar Variables::	Controlling the size of toolbars.
+
+
+File: lispref.info,  Node: Toolbar Intro,  Next: Creating Toolbar,  Up: Toolbar
+
+Toolbar Intro
+=============
+
+   A "toolbar" is a bar of icons displayed along one edge of a frame.
+You can view a toolbar as a series of menu shortcuts--the most common
+menu options can be accessed with a single click rather than a series
+of clicks and/or drags to select the option from a menu.  Consistent
+with this, a help string (called the "help-echo") describing what an
+icon in the toolbar (called a "toolbar button") does, is displayed in
+the minibuffer when the mouse is over the button.
+
+   In XEmacs, a toolbar can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying toolbars
+simultaneously.  The contents, thickness, and visibility of the
+toolbars can be controlled separately, and the values can be
+per-buffer, per-frame, etc., using specifiers (*note Specifiers::).
+
+   Normally, there is one toolbar displayed in a frame.  Usually, this
+is the standard toolbar, but certain modes will override this and
+substitute their own toolbar.  In some cases (e.g. the VM package), a
+package will supply its own toolbar along a different edge from the
+standard toolbar, so that both can be visible at once.  This standard
+toolbar is usually positioned along the top of the frame, but this can
+be changed using `set-default-toolbar-position'.
+
+   Note that, for each of the toolbar properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+toolbar positions (top, bottom, left, and right), and an additional
+specifier for the "default" toolbar, i.e. the toolbar whose position is
+controlled by `set-default-toolbar-position'.  The way this works is
+that `set-default-toolbar-position' arranges things so that the
+appropriate position-specific specifiers for the default position
+inherit from the corresponding default specifiers.  That way, if the
+position-specific specifier does not give a value (which it usually
+doesn't), then the value from the default specifier applies.  If you
+want to control the default toolbar, you just change the default
+specifiers, and everything works.  A package such as VM that wants to
+put its own toolbar in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+toolbar to the same position, it will just not be visible.
+
+
+File: lispref.info,  Node: Creating Toolbar,  Next: Toolbar Descriptor Format,  Prev: Toolbar Intro,  Up: Toolbar
+
+Creating Toolbar
+================
+
+ - Function: make-toolbar-specifier spec-list
+     Return a new `toolbar' specifier object with the given
+     specification list.  SPEC-LIST can be a list of specifications
+     (each of which is a cons of a locale and a list of instantiators),
+     a single instantiator, or a list of instantiators.  *Note
+     Specifiers::, for more information about specifiers.
+
+     Toolbar specifiers are used to specify the format of a toolbar.
+     The values of the variables `default-toolbar', `top-toolbar',
+     `left-toolbar', `right-toolbar', and `bottom-toolbar' are always
+     toolbar specifiers.
+
+     Valid toolbar instantiators are called "toolbar descriptors" and
+     are lists of vectors.  See `default-toolbar' for a description of
+     the exact format.
+
+
+File: lispref.info,  Node: Toolbar Descriptor Format,  Next: Specifying the Toolbar,  Prev: Creating Toolbar,  Up: Toolbar
+
+Toolbar Descriptor Format
+=========================
+
+   The contents of a toolbar are specified using a "toolbar descriptor".
+The format of a toolbar descriptor is a list of "toolbar button
+descriptors".  Each toolbar button descriptor is a vector in one of the
+following formats:
+
+   * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
+
+   * `[:style 2D-OR-3D]'
+
+   * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
+
+   * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
+
+   Optionally, one of the toolbar button descriptors may be `nil'
+instead of a vector; this signifies the division between the toolbar
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+   The first vector format above specifies a normal toolbar button; the
+others specify blank areas in the toolbar.
+
+   For the first vector format:
+
+   * GLYPH-LIST should be a list of one to six glyphs (as created by
+     `make-glyph') or a symbol whose value is such a list.  The first
+     glyph, which must be provided, is the glyph used to display the
+     toolbar button when it is in the "up" (not pressed) state.  The
+     optional second glyph is for displaying the button when it is in
+     the "down" (pressed) state.  The optional third glyph is for when
+     the button is disabled.  The last three glyphs are for displaying
+     the button in the "up", "down", and "disabled" states,
+     respectively, but are used when the user has called for captioned
+     toolbar buttons (using `toolbar-buttons-captioned-p').  The
+     function `toolbar-make-button-list' is useful in creating these
+     glyph lists.
+
+   * Even if you do not provide separate down-state and disabled-state
+     glyphs, the user will still get visual feedback to indicate which
+     state the button is in.  Buttons in the up-state are displayed
+     with a shadowed border that gives a raised appearance to the
+     button.  Buttons in the down-state are displayed with shadows that
+     give a recessed appearance.  Buttons in the disabled state are
+     displayed with no shadows, giving a 2-d effect.
+
+   * If some of the toolbar glyphs are not provided, they inherit as
+     follows:
+
+               UP:                up
+               DOWN:              down -> up
+               DISABLED:          disabled -> up
+               CAP-UP:            cap-up -> up
+               CAP-DOWN:          cap-down -> cap-up -> down -> up
+               CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
+
+   * The second element FUNCTION is a function to be called when the
+     toolbar button is activated (i.e. when the mouse is released over
+     the toolbar button, if the press occurred in the toolbar).  It can
+     be any form accepted by `call-interactively', since this is how it
+     is invoked.
+
+   * The third element ENABLED-P specifies whether the toolbar button
+     is enabled (disabled buttons do nothing when they are activated,
+     and are displayed differently; see above).  It should be either a
+     boolean or a form that evaluates to a boolean.
+
+   * The fourth element HELP, if non-`nil', should be a string.  This
+     string is displayed in the echo area when the mouse passes over the
+     toolbar button.
+
+   For the other vector formats (specifying blank areas of the toolbar):
+
+   * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
+     whether the area is displayed with shadows (giving it a raised,
+     3-d appearance) or without shadows (giving it a flat appearance).
+
+   * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
+     area.  If omitted, it defaults to a device-specific value (8
+     pixels for X devices).
+
+ - Function: toolbar-make-button-list up &optional down disabled cap-up
+          cap-down cap-disabled
+     This function calls `make-glyph' on each arg and returns a list of
+     the results.  This is useful for setting the first argument of a
+     toolbar button descriptor (typically, the result of this function
+     is assigned to a symbol, which is specified as the first argument
+     of the toolbar button descriptor).
+
+ - Function: check-toolbar-button-syntax button &optional noerror
+     Verify the syntax of entry BUTTON in a toolbar description list.
+     If you want to verify the syntax of a toolbar description list as a
+     whole, use `check-valid-instantiator' with a specifier type of
+     `toolbar'.
+
+
+File: lispref.info,  Node: Specifying the Toolbar,  Next: Other Toolbar Variables,  Prev: Toolbar Descriptor Format,  Up: Toolbar
+
+Specifying the Toolbar
+======================
+
+   In order to specify the contents of a toolbar, set one of the
+specifier variables `default-toolbar', `top-toolbar', `bottom-toolbar',
+`left-toolbar', or `right-toolbar'.  These are specifiers, which means
+you set them with `set-specifier' and query them with `specifier-specs'
+or `specifier-instance'.  You will get an error if you try to set them
+using `setq'.  The valid instantiators for these specifiers are toolbar
+descriptors, as described above.  *Note Specifiers::, for more
+information.
+
+   Most of the time, you will set `default-toolbar', which allows the
+user to choose where the toolbar should go.
+
+ - Specifier: default-toolbar
+     The position of this toolbar is specified in the function
+     `default-toolbar-position'.  If the corresponding
+     position-specific toolbar (e.g. `top-toolbar' if
+     `default-toolbar-position' is `top') does not specify a toolbar in
+     a particular domain, then the value of `default-toolbar' in that
+     domain, of any, will be used instead.
+
+   Note that the toolbar at any particular position will not be
+displayed unless its thickness (width or height, depending on
+orientation) is non-zero and its visibility status is true.  The
+thickness is controlled by the specifiers `top-toolbar-height',
+`bottom-toolbar-height', `left-toolbar-width', and
+`right-toolbar-width', and the visibility status is controlled by the
+specifiers `top-toolbar-visible-p', `bottom-toolbar-visible-p',
+`left-toolbar-visible-p', and `right-toolbar-visible-p' (*note Other
+Toolbar Variables::).
+
+ - Function: set-default-toolbar-position position
+     This function sets the position that the `default-toolbar' will be
+     displayed at.  Valid positions are the symbols `top', `bottom',
+     `left' and `right'.  What this actually does is set the fallback
+     specifier for the position-specific specifier corresponding to the
+     given position to `default-toolbar', and set the fallbacks for the
+     other position-specific specifiers to `nil'.  It also does the
+     same thing for the position-specific thickness and visibility
+     specifiers, which inherit from one of `default-toolbar-height' or
+     `default-toolbar-width', and from `default-toolbar-visible-p',
+     respectively (*note Other Toolbar Variables::).
+
+ - Function: default-toolbar-position
+     This function returns the position that the `default-toolbar' will
+     be displayed at.
+
+   You can also explicitly set a toolbar at a particular position.  When
+redisplay determines what to display at a particular position in a
+particular domain (i.e. window), it first consults the position-specific
+toolbar.  If that does not yield a toolbar descriptor, the
+`default-toolbar' is consulted if `default-toolbar-position' indicates
+this position.
+
+ - Specifier: top-toolbar
+     Specifier for the toolbar at the top of the frame.
+
+ - Specifier: bottom-toolbar
+     Specifier for the toolbar at the bottom of the frame.
+
+ - Specifier: left-toolbar
+     Specifier for the toolbar at the left edge of the frame.
+
+ - Specifier: right-toolbar
+     Specifier for the toolbar at the right edge of the frame.
+
+ - Function: toolbar-specifier-p object
+     This function returns non-`nil' if OBJECT is a toolbar specifier.
+     Toolbar specifiers are the actual objects contained in the toolbar
+     variables described above, and their valid instantiators are
+     toolbar descriptors (*note Toolbar Descriptor Format::).
+
+
+File: lispref.info,  Node: Other Toolbar Variables,  Prev: Specifying the Toolbar,  Up: Toolbar
+
+Other Toolbar Variables
+=======================
+
+   The variables to control the toolbar thickness, visibility status,
+and captioned status are all specifiers.  *Note Specifiers::.
+
+ - Specifier: default-toolbar-height
+     This specifies the height of the default toolbar, if it's oriented
+     horizontally.  The position of the default toolbar is specified by
+     the function `set-default-toolbar-position'.  If the corresponding
+     position-specific toolbar thickness specifier (e.g.
+     `top-toolbar-height' if `default-toolbar-position' is `top') does
+     not specify a thickness in a particular domain (a window or a
+     frame), then the value of `default-toolbar-height' or
+     `default-toolbar-width' (depending on the toolbar orientation) in
+     that domain, if any, will be used instead.
+
+ - Specifier: default-toolbar-width
+     This specifies the width of the default toolbar, if it's oriented
+     vertically.  This behaves like `default-toolbar-height'.
+
+   Note that `default-toolbar-height' is only used when
+`default-toolbar-position' is `top' or `bottom', and
+`default-toolbar-width' is only used when `default-toolbar-position' is
+`left' or `right'.
+
+ - Specifier: top-toolbar-height
+     This specifies the height of the top toolbar.
+
+ - Specifier: bottom-toolbar-height
+     This specifies the height of the bottom toolbar.
+
+ - Specifier: left-toolbar-width
+     This specifies the width of the left toolbar.
+
+ - Specifier: right-toolbar-width
+     This specifies the width of the right toolbar.
+
+   Note that all of the position-specific toolbar thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default toolbar.  Therefore, you will have to set a non-zero thickness
+value if you want a position-specific toolbar to be displayed.
+
+ - Specifier: default-toolbar-visible-p
+     This specifies whether the default toolbar is visible.  The
+     position of the default toolbar is specified by the function
+     `set-default-toolbar-position'.  If the corresponding
+     position-specific toolbar visibility specifier (e.g.
+     `top-toolbar-visible-p' if `default-toolbar-position' is `top')
+     does not specify a visible-p value in a particular domain (a
+     window or a frame), then the value of `default-toolbar-visible-p'
+     in that domain, if any, will be used instead.
+
+ - Specifier: top-toolbar-visible-p
+     This specifies whether the top toolbar is visible.
+
+ - Specifier: bottom-toolbar-visible-p
+     This specifies whether the bottom toolbar is visible.
+
+ - Specifier: left-toolbar-visible-p
+     This specifies whether the left toolbar is visible.
+
+ - Specifier: right-toolbar-visible-p
+     This specifies whether the right toolbar is visible.
+
+   `default-toolbar-visible-p' and all of the position-specific toolbar
+visibility specifiers have a fallback value of true.
+
+   Internally, toolbar thickness and visibility specifiers are
+instantiated in both window and frame domains, for different purposes.
+The value in the domain of a frame's selected window specifies the
+actual toolbar thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the toolbar
+thickness or visibility that is used in frame geometry calculations.
+
+   Thus, for example, if you set the frame width to 80 characters and
+the left toolbar width for that frame to 68 pixels, then the frame will
+be sized to fit 80 characters plus a 68-pixel left toolbar.  If you then
+set the left toolbar width to 0 for a particular buffer (or if that
+buffer does not specify a left toolbar or has a `nil' value specified
+for `left-toolbar-visible-p'), you will find that, when that buffer is
+displayed in the selected window, the window will have a width of 86 or
+87 characters--the frame is sized for a 68-pixel left toolbar but the
+selected window specifies that the left toolbar is not visible, so it is
+expanded to take up the slack.
+
+ - Specifier: toolbar-buttons-captioned-p
+     Whether toolbar buttons are captioned.  This affects which glyphs
+     from a toolbar button descriptor are chosen.  *Note Toolbar
+     Descriptor Format::.
+
+   You can also reset the toolbar to what it was when XEmacs started up.
+
+ - Constant: initial-toolbar-spec
+     The toolbar descriptor used to initialize `default-toolbar' at
+     startup.
+
+
+File: lispref.info,  Node: Gutter,  Next: Scrollbars,  Prev: Toolbar,  Up: Top
+
+Gutter
+******
+
+   A gutter is a rectangle displayed along one edge of a frame.  It can
+contain arbitrary text or graphics.
+
+* Menu:
+
+* Gutter Intro::		An introduction.
+* Creating Gutter::             How to create a gutter.
+* Gutter Descriptor Format::	Accessing and modifying a gutter's
+                                  properties.
+* Specifying a Gutter::		Setting a gutter's contents.
+* Other Gutter Variables::	Controlling the size of gutters.
+* Common Gutter Widgets::       Things to put in gutters.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-21'
Index: ././info/lispref.info-21
--- ././info/lispref.info-21	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-21	Thu May 17 23:26:54 2001
@@ -0,0 +1,1153 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Gutter Intro,  Next: Creating Gutter,  Prev: Gutter,  Up: Gutter
+
+Gutter Intro
+============
+
+   A "gutter" is a rectangle displayed along one edge of a frame.  It
+can contain arbitrary text or graphics.  It could be considered a
+generalization of a toolbar, although toolbars are not currently
+implemented using gutters.
+
+   In XEmacs, a gutter can be displayed along any of the four edges of
+the frame, and two or more different edges can be displaying gutters
+simultaneously.  The contents, thickness, and visibility of the gutters
+can be controlled separately, and the values can be per-buffer,
+per-frame, etc., using specifiers (*note Specifiers::).
+
+   Normally, there is one gutter displayed in a frame.  Usually, this is
+the default gutter, containing buffer tabs, but modes cab override this
+and substitute their own gutter.  This default gutter is usually
+positioned along the top of the frame, but this can be changed using
+`set-default-gutter-position'.
+
+   Note that, for each of the gutter properties (contents, thickness,
+and visibility), there is a separate specifier for each of the four
+gutter positions (top, bottom, left, and right), and an additional
+specifier for the "default" gutter, i.e. the gutter whose position is
+controlled by `set-default-gutter-position'.  The way this works is
+that `set-default-gutter-position' arranges things so that the
+appropriate position-specific specifiers for the default position
+inherit from the corresponding default specifiers.  That way, if the
+position-specific specifier does not give a value (which it usually
+doesn't), then the value from the default specifier applies.  If you
+want to control the default gutter, you just change the default
+specifiers, and everything works.  A package such as VM that wants to
+put its own gutter in a different location from the default just sets
+the position-specific specifiers, and if the user sets the default
+gutter to the same position, it will just not be visible.
+
+
+File: lispref.info,  Node: Creating Gutter,  Next: Gutter Descriptor Format,  Prev: Gutter Intro,  Up: Gutter
+
+Creating Gutter
+===============
+
+ - Function: make-gutter-specifier spec-list
+     Return a new `gutter' specifier object with the given specification
+     list.  SPEC-LIST can be a list of specifications (each of which is
+     a cons of a locale and a list of instantiators), a single
+     instantiator, or a list of instantiators.  *Note Specifiers::, for
+     more information about specifiers.
+
+     Gutter specifiers are used to specify the format of a gutter.  The
+     values of the variables `default-gutter', `top-gutter',
+     `left-gutter', `right-gutter', and `bottom-gutter' are always
+     gutter specifiers.
+
+     Valid gutter instantiators are called "gutter descriptors" and are
+     either strings or property-lists of strings.  See `default-gutter'
+     for a description of the exact format.
+
+ - Function: make-gutter-size-specifier spec-list
+     Return a new `gutter-size' specifier object with the given spec
+     list.  SPEC-LIST can be a list of specifications (each of which is
+     a cons of a locale and a list of instantiators), a single
+     instantiator, or a list of instantiators.  *Note Specifiers::, for
+     more information about specifiers.
+
+     Gutter-size specifiers are used to specify the size of a gutter.
+     The values of the variables `default-gutter-size',
+     `top-gutter-size', `left-gutter-size', `right-gutter-size', and
+     `bottom-gutter-size' are always gutter-size specifiers.
+
+     Valid gutter-size instantiators are either integers or the special
+     symbol `autodetect'. If a gutter-size is set to `autodetect' them
+     the size of the gutter will be adjusted to just accommodate the
+     gutters contents. `autodetect' only works for top and bottom
+     gutters.
+
+ - Function: make-gutter-visible-specifier spec-list
+     Return a new `gutter-visible' specifier object with the given spec
+     list.  SPEC-LIST can be a list of specifications (each of which is
+     a cons of a locale and a list of instantiators), a single
+     instantiator, or a list of instantiators.  *Note Specifiers::, for
+     more information about specifiers.
+
+     Gutter-visible specifiers are used to specify the visibility of a
+     gutter.  The values of the variables `default-gutter-visible-p',
+     `top-gutter-visible-p', `left-gutter-visible-p',
+     `right-gutter-visible-p', and `bottom-gutter-visible-p' are always
+     gutter-visible specifiers.
+
+     Valid gutter-visible instantiators are `t', `nil' or a list of
+     symbols.  If a gutter-visible instantiator is set to a list of
+     symbols, and the corresponding gutter specification is a
+     property-list strings, then elements of the gutter specification
+     will only be visible if the corresponding symbol occurs in the
+     gutter-visible instantiator.
+
+
+File: lispref.info,  Node: Gutter Descriptor Format,  Next: Specifying a Gutter,  Prev: Creating Gutter,  Up: Gutter
+
+Gutter Descriptor Format
+========================
+
+   The contents of a gutter are specified using a "gutter descriptor".
+The format of a gutter descriptor is a list of "gutter button
+descriptors".  Each gutter button descriptor is a vector in one of the
+following formats:
+
+   * `[GLYPH-LIST FUNCTION ENABLED-P HELP]'
+
+   * `[:style 2D-OR-3D]'
+
+   * `[:style 2D-OR-3D :size WIDTH-OR-HEIGHT]'
+
+   * `[:size WIDTH-OR-HEIGHT :style 2D-OR-3D]'
+
+   Optionally, one of the gutter button descriptors may be `nil'
+instead of a vector; this signifies the division between the gutter
+buttons that are to be displayed flush-left, and the buttons to be
+displayed flush-right.
+
+   The first vector format above specifies a normal gutter button; the
+others specify blank areas in the gutter.
+
+   For the first vector format:
+
+   * GLYPH-LIST should be a list of one to six glyphs (as created by
+     `make-glyph') or a symbol whose value is such a list.  The first
+     glyph, which must be provided, is the glyph used to display the
+     gutter button when it is in the "up" (not pressed) state.  The
+     optional second glyph is for displaying the button when it is in
+     the "down" (pressed) state.  The optional third glyph is for when
+     the button is disabled.  The last three glyphs are for displaying
+     the button in the "up", "down", and "disabled" states,
+     respectively, but are used when the user has called for captioned
+     gutter buttons (using `gutter-buttons-captioned-p').  The function
+     `gutter-make-button-list' is useful in creating these glyph lists.
+
+   * Even if you do not provide separate down-state and disabled-state
+     glyphs, the user will still get visual feedback to indicate which
+     state the button is in.  Buttons in the up-state are displayed
+     with a shadowed border that gives a raised appearance to the
+     button.  Buttons in the down-state are displayed with shadows that
+     give a recessed appearance.  Buttons in the disabled state are
+     displayed with no shadows, giving a 2-d effect.
+
+   * If some of the gutter glyphs are not provided, they inherit as
+     follows:
+
+               UP:                up
+               DOWN:              down -> up
+               DISABLED:          disabled -> up
+               CAP-UP:            cap-up -> up
+               CAP-DOWN:          cap-down -> cap-up -> down -> up
+               CAP-DISABLED:      cap-disabled -> cap-up -> disabled -> up
+
+   * The second element FUNCTION is a function to be called when the
+     gutter button is activated (i.e. when the mouse is released over
+     the gutter button, if the press occurred in the gutter).  It can
+     be any form accepted by `call-interactively', since this is how it
+     is invoked.
+
+   * The third element ENABLED-P specifies whether the gutter button is
+     enabled (disabled buttons do nothing when they are activated, and
+     are displayed differently; see above).  It should be either a
+     boolean or a form that evaluates to a boolean.
+
+   * The fourth element HELP, if non-`nil', should be a string.  This
+     string is displayed in the echo area when the mouse passes over the
+     gutter button.
+
+   For the other vector formats (specifying blank areas of the gutter):
+
+   * 2D-OR-3D should be one of the symbols `2d' or `3d', indicating
+     whether the area is displayed with shadows (giving it a raised,
+     3-d appearance) or without shadows (giving it a flat appearance).
+
+   * WIDTH-OR-HEIGHT specifies the length, in pixels, of the blank
+     area.  If omitted, it defaults to a device-specific value (8
+     pixels for X devices).
+
+ - Function: gutter-make-button-list up &optional down disabled cap-up
+          cap-down cap-disabled
+     This function calls `make-glyph' on each arg and returns a list of
+     the results.  This is useful for setting the first argument of a
+     gutter button descriptor (typically, the result of this function
+     is assigned to a symbol, which is specified as the first argument
+     of the gutter button descriptor).
+
+ - Function: check-gutter-button-syntax button &optional noerror
+     Verify the syntax of entry BUTTON in a gutter description list.
+     If you want to verify the syntax of a gutter description list as a
+     whole, use `check-valid-instantiator' with a specifier type of
+     `gutter'.
+
+
+File: lispref.info,  Node: Specifying a Gutter,  Next: Other Gutter Variables,  Prev: Gutter Descriptor Format,  Up: Gutter
+
+Specifying a Gutter
+===================
+
+   In order to specify the contents of a gutter, set one of the
+specifier variables `default-gutter', `top-gutter', `bottom-gutter',
+`left-gutter', or `right-gutter'.  These are specifiers, which means
+you set them with `set-specifier' and query them with `specifier-specs'
+or `specifier-instance'.  You will get an error if you try to set them
+using `setq'.  The valid instantiators for these specifiers are gutter
+descriptors, as described above.  *Note Specifiers::, for more
+information.
+
+   Most of the time, you will set `default-gutter', which allows the
+user to choose where the gutter should go.
+
+ - Specifier: default-gutter
+     The position of this gutter is specified in the function
+     `default-gutter-position'.  If the corresponding position-specific
+     gutter (e.g. `top-gutter' if `default-gutter-position' is `top')
+     does not specify a gutter in a particular domain, then the value
+     of `default-gutter' in that domain, of any, will be used instead.
+
+   Note that the gutter at any particular position will not be displayed
+unless its thickness (width or height, depending on orientation) is
+non-zero and its visibility status is true.  The thickness is controlled
+by the specifiers `top-gutter-height', `bottom-gutter-height',
+`left-gutter-width', and `right-gutter-width', and the visibility
+status is controlled by the specifiers `top-gutter-visible-p',
+`bottom-gutter-visible-p', `left-gutter-visible-p', and
+`right-gutter-visible-p' (*note Other Gutter Variables::).
+
+ - Function: set-default-gutter-position position
+     This function sets the position that the `default-gutter' will be
+     displayed at.  Valid positions are the symbols `top', `bottom',
+     `left' and `right'.  What this actually does is set the fallback
+     specifier for the position-specific specifier corresponding to the
+     given position to `default-gutter', and set the fallbacks for the
+     other position-specific specifiers to `nil'.  It also does the
+     same thing for the position-specific thickness and visibility
+     specifiers, which inherit from one of `default-gutter-height' or
+     `default-gutter-width', and from `default-gutter-visible-p',
+     respectively (*note Other Gutter Variables::).
+
+ - Function: default-gutter-position
+     This function returns the position that the `default-gutter' will
+     be displayed at.
+
+   You can also explicitly set a gutter at a particular position.  When
+redisplay determines what to display at a particular position in a
+particular domain (i.e. window), it first consults the position-specific
+gutter.  If that does not yield a gutter descriptor, the
+`default-gutter' is consulted if `default-gutter-position' indicates
+this position.
+
+ - Specifier: top-gutter
+     Specifier for the gutter at the top of the frame.
+
+ - Specifier: bottom-gutter
+     Specifier for the gutter at the bottom of the frame.
+
+ - Specifier: left-gutter
+     Specifier for the gutter at the left edge of the frame.
+
+ - Specifier: right-gutter
+     Specifier for the gutter at the right edge of the frame.
+
+ - Function: gutter-specifier-p object
+     This function returns non-`nil' if OBJECT is a gutter specifier.
+     Gutter specifiers are the actual objects contained in the gutter
+     variables described above, and their valid instantiators are
+     gutter descriptors (*note Gutter Descriptor Format::).
+
+
+File: lispref.info,  Node: Other Gutter Variables,  Next: Common Gutter Widgets,  Prev: Specifying a Gutter,  Up: Gutter
+
+Other Gutter Variables
+======================
+
+   The variables to control the gutter thickness, visibility status, and
+captioned status are all specifiers.  *Note Specifiers::.
+
+ - Specifier: default-gutter-height
+     This specifies the height of the default gutter, if it's oriented
+     horizontally.  The position of the default gutter is specified by
+     the function `set-default-gutter-position'.  If the corresponding
+     position-specific gutter thickness specifier (e.g.
+     `top-gutter-height' if `default-gutter-position' is `top') does
+     not specify a thickness in a particular domain (a window or a
+     frame), then the value of `default-gutter-height' or
+     `default-gutter-width' (depending on the gutter orientation) in
+     that domain, if any, will be used instead.
+
+ - Specifier: default-gutter-width
+     This specifies the width of the default gutter, if it's oriented
+     vertically.  This behaves like `default-gutter-height'.
+
+   Note that `default-gutter-height' is only used when
+`default-gutter-position' is `top' or `bottom', and
+`default-gutter-width' is only used when `default-gutter-position' is
+`left' or `right'.
+
+ - Specifier: top-gutter-height
+     This specifies the height of the top gutter.
+
+ - Specifier: bottom-gutter-height
+     This specifies the height of the bottom gutter.
+
+ - Specifier: left-gutter-width
+     This specifies the width of the left gutter.
+
+ - Specifier: right-gutter-width
+     This specifies the width of the right gutter.
+
+   Note that all of the position-specific gutter thickness specifiers
+have a fallback value of zero when they do not correspond to the
+default gutter.  Therefore, you will have to set a non-zero thickness
+value if you want a position-specific gutter to be displayed.
+
+ - Specifier: default-gutter-visible-p
+     This specifies whether the default gutter is visible.  The
+     position of the default gutter is specified by the function
+     `set-default-gutter-position'.  If the corresponding
+     position-specific gutter visibility specifier (e.g.
+     `top-gutter-visible-p' if `default-gutter-position' is `top') does
+     not specify a visible-p value in a particular domain (a window or
+     a frame), then the value of `default-gutter-visible-p' in that
+     domain, if any, will be used instead.
+
+ - Specifier: top-gutter-visible-p
+     This specifies whether the top gutter is visible.
+
+ - Specifier: bottom-gutter-visible-p
+     This specifies whether the bottom gutter is visible.
+
+ - Specifier: left-gutter-visible-p
+     This specifies whether the left gutter is visible.
+
+ - Specifier: right-gutter-visible-p
+     This specifies whether the right gutter is visible.
+
+   `default-gutter-visible-p' and all of the position-specific gutter
+visibility specifiers have a fallback value of true.
+
+   Internally, gutter thickness and visibility specifiers are
+instantiated in both window and frame domains, for different purposes.
+The value in the domain of a frame's selected window specifies the
+actual gutter thickness or visibility that you will see in that frame.
+The value in the domain of a frame itself specifies the gutter
+thickness or visibility that is used in frame geometry calculations.
+
+   Thus, for example, if you set the frame width to 80 characters and
+the left gutter width for that frame to 68 pixels, then the frame will
+be sized to fit 80 characters plus a 68-pixel left gutter.  If you then
+set the left gutter width to 0 for a particular buffer (or if that
+buffer does not specify a left gutter or has a `nil' value specified for
+`left-gutter-visible-p'), you will find that, when that buffer is
+displayed in the selected window, the window will have a width of 86 or
+87 characters - the frame is sized for a 68-pixel left gutter but the
+selected window specifies that the left gutter is not visible, so it is
+expanded to take up the slack.
+
+ - Specifier: gutter-buttons-captioned-p
+     Whether gutter buttons are captioned.  This affects which glyphs
+     from a gutter button descriptor are chosen.  *Note Gutter
+     Descriptor Format::.
+
+   You can also reset the gutter to what it was when XEmacs started up.
+
+ - Constant: initial-gutter-spec
+     The gutter descriptor used to initialize `default-gutter' at
+     startup.
+
+
+File: lispref.info,  Node: Common Gutter Widgets,  Prev: Other Gutter Variables,  Up: Gutter
+
+Common Gutter Widgets
+=====================
+
+   A gutter can contain arbitrary text.  So, for example, in an Info
+buffer you could put the title of the current node in the top gutter,
+and it would not scroll out of view in a long node.  (This is an
+artificial example, since usually the node name is sufficiently
+descriptive, and Info puts that in the mode line.)
+
+   A more common use for the gutter is to hold some kind of active
+widget.  The buffer-tab facility, available in all XEmacs frames,
+creates an array of file-folder-like tabs, which the user can click with
+the mouse to switch buffers.  W3 uses a progress-bar widget in the
+bottom gutter to give a visual indication of the progress of
+time-consuming operations like downloading.
+
+* Menu:
+
+* Buffer Tabs::         Tabbed divider index metaphor for switching buffers.
+* Progress Bars::       Visual indication of operation progress.
+
+
+File: lispref.info,  Node: Buffer Tabs,  Next: Progress Bars,  Up: Common Gutter Widgets
+
+Buffer Tabs
+-----------
+
+   Not documented yet.
+
+
+File: lispref.info,  Node: Progress Bars,  Prev: Buffer Tabs,  Up: Common Gutter Widgets
+
+Progress Bars
+-------------
+
+   Not documented yet.
+
+
+File: lispref.info,  Node: Scrollbars,  Next: Drag and Drop,  Prev: Gutter,  Up: Top
+
+Scrollbars
+**********
+
+   Not yet documented.
+
+
+File: lispref.info,  Node: Drag and Drop,  Next: Modes,  Prev: Scrollbars,  Up: Top
+
+Drag and Drop
+*************
+
+   _WARNING_: the Drag'n'Drop API is still under development and the
+interface may change! The current implementation is considered
+experimental.
+
+   Drag'n'drop is a way to transfer information between multiple
+applications.  To do this several GUIs define their own protocols.
+Examples are OffiX, CDE, Motif, KDE, MSWindows, GNOME, and many more.
+To catch all these protocols, XEmacs provides a generic API.
+
+   One prime idea behind the API is to use a data interface that is
+transparent for all systems. The author thinks that this is best
+archived by using URL and MIME data, cause any internet enabled system
+must support these for email already. XEmacs also already provides
+powerful interfaces to support these types of data (tm and w3).
+
+* Menu:
+
+* Supported Protocols:: Which low-level protocols are supported.
+* Drop Interface::      How XEmacs handles a drop from another application.
+* Drag Interface::      Calls to initiate a drag from XEmacs.
+
+
+File: lispref.info,  Node: Supported Protocols,  Next: Drop Interface,  Up: Drag and Drop
+
+Supported Protocols
+===================
+
+   The current release of XEmacs only support a small set of Drag'n'drop
+protocols. Some of these only support limited options available in the
+API.
+
+* Menu:
+
+* OffiX DND::           A generic X based protocol.
+* CDE dt::              Common Desktop Environment used on suns.
+* MSWindows OLE::       Mr. Gates way of live.
+* Loose ends::          The other protocols.
+
+
+File: lispref.info,  Node: OffiX DND,  Next: CDE dt,  Up: Supported Protocols
+
+OffiX DND
+---------
+
+   _WARNING_: If you compile in OffiX, you may not be able to use
+multiple X displays successfully.  If the two servers are from
+different vendors, the results may be unpredictable.
+
+   The OffiX Drag'n'Drop protocol is part of a X API/Widget library
+created by Cesar Crusius. It is based on X-Atoms and ClientMessage
+events, and works with any X platform supporting them.
+
+   OffiX is supported if 'offix is member of the variable
+dragdrop-protocols, or the feature 'offix is defined.
+
+   Unfortunately it uses it's own data types. Examples are: File, Files,
+Exe, Link, URL, MIME. The API tries to choose the right type for the
+data that is dragged from XEmacs (well, not yet...).
+
+   XEmacs supports both MIME and URL drags and drops using this API. No
+application interaction is possible while dragging is in progress.
+
+   For information about the OffiX project have a look at
+http://leb.net/~offix/
+
+
+File: lispref.info,  Node: CDE dt,  Next: MSWindows OLE,  Prev: OffiX DND,  Up: Supported Protocols
+
+CDE dt
+------
+
+   CDE stands for Common Desktop Environment. It is based on the Motif
+widget library. It's drag'n'drop protocol is also an abstraction of the
+Motif protocol (so it might be possible, that XEmacs will also support
+the Motif protocol soon).
+
+   CDE has three different types: file, buffer, and text. XEmacs only
+uses file and buffer drags. The API will disallow full URL drags, only
+file method URLs are passed through.
+
+   Buffer drags are always converted to plain text.
+
+
+File: lispref.info,  Node: MSWindows OLE,  Next: Loose ends,  Prev: CDE dt,  Up: Supported Protocols
+
+MSWindows OLE
+-------------
+
+   Only allows file drags and drops.
+
+
+File: lispref.info,  Node: Loose ends,  Prev: MSWindows OLE,  Up: Supported Protocols
+
+Loose ends
+----------
+
+   The following protocols will be supported soon: Xdnd, Motif, Xde (if
+I get some specs), KDE OffiX (if KDE can find XEmacs windows).
+
+   In particular Xdnd will be one of the protocols that can benefit from
+the XEmacs API, cause it also uses MIME types to encode dragged data.
+
+
+File: lispref.info,  Node: Drop Interface,  Next: Drag Interface,  Prev: Supported Protocols,  Up: Drag and Drop
+
+Drop Interface
+==============
+
+   For each activated low-level protocol, a internal routine will catch
+incoming drops and convert them to a dragdrop-drop type misc-user-event.
+
+   This misc-user-event has its function argument set to
+`dragdrop-drop-dispatch' and the object contains the data of the drop
+(converted to URL/MIME specific data). This function will search the
+variable `experimental-dragdrop-drop-functions' for a function that can
+handle the dropped data.
+
+   To modify the drop behavior, the user can modify the variable
+`experimental-dragdrop-drop-functions'. Each element of this list
+specifies a possible handler for dropped data. The first one that can
+handle the data will return `t' and exit. Another possibility is to set
+a extent-property with the same name. Extents are checked prior to the
+variable.
+
+   The customization group `drag-n-drop' shows all variables of user
+interest.
+
+
+File: lispref.info,  Node: Drag Interface,  Prev: Drop Interface,  Up: Drag and Drop
+
+Drag Interface
+==============
+
+   This describes the drag API (not implemented yet).
+
+
+File: lispref.info,  Node: Modes,  Next: Documentation,  Prev: Drag and Drop,  Up: Top
+
+Major and Minor Modes
+*********************
+
+   A "mode" is a set of definitions that customize XEmacs and can be
+turned on and off while you edit.  There are two varieties of modes:
+"major modes", which are mutually exclusive and used for editing
+particular kinds of text, and "minor modes", which provide features
+that users can enable individually.
+
+   This chapter describes how to write both major and minor modes, how
+to indicate them in the modeline, and how they run hooks supplied by the
+user.  For related topics such as keymaps and syntax tables, see *Note
+Keymaps::, and *Note Syntax Tables::.
+
+* Menu:
+
+* Major Modes::        Defining major modes.
+* Minor Modes::        Defining minor modes.
+* Modeline Format::    Customizing the text that appears in the modeline.
+* Hooks::              How to use hooks; how to write code that provides hooks.
+
+
+File: lispref.info,  Node: Major Modes,  Next: Minor Modes,  Up: Modes
+
+Major Modes
+===========
+
+   Major modes specialize XEmacs for editing particular kinds of text.
+Each buffer has only one major mode at a time.
+
+   The least specialized major mode is called "Fundamental mode".  This
+mode has no mode-specific definitions or variable settings, so each
+XEmacs command behaves in its default manner, and each option is in its
+default state.  All other major modes redefine various keys and options.
+For example, Lisp Interaction mode provides special key bindings for
+<LFD> (`eval-print-last-sexp'), <TAB> (`lisp-indent-line'), and other
+keys.
+
+   When you need to write several editing commands to help you perform a
+specialized editing task, creating a new major mode is usually a good
+idea.  In practice, writing a major mode is easy (in contrast to
+writing a minor mode, which is often difficult).
+
+   If the new mode is similar to an old one, it is often unwise to
+modify the old one to serve two purposes, since it may become harder to
+use and maintain.  Instead, copy and rename an existing major mode
+definition and alter the copy--or define a "derived mode" (*note
+Derived Modes::).  For example, Rmail Edit mode, which is in
+`emacs/lisp/rmailedit.el', is a major mode that is very similar to Text
+mode except that it provides three additional commands.  Its definition
+is distinct from that of Text mode, but was derived from it.
+
+   Rmail Edit mode is an example of a case where one piece of text is
+put temporarily into a different major mode so it can be edited in a
+different way (with ordinary XEmacs commands rather than Rmail).  In
+such cases, the temporary major mode usually has a command to switch
+back to the buffer's usual mode (Rmail mode, in this case).  You might
+be tempted to present the temporary redefinitions inside a recursive
+edit and restore the usual ones when the user exits; but this is a bad
+idea because it constrains the user's options when it is done in more
+than one buffer: recursive edits must be exited most-recently-entered
+first.  Using alternative major modes avoids this limitation.  *Note
+Recursive Editing::.
+
+   The standard XEmacs Lisp library directory contains the code for
+several major modes, in files including `text-mode.el', `texinfo.el',
+`lisp-mode.el', `c-mode.el', and `rmail.el'.  You can look at these
+libraries to see how modes are written.  Text mode is perhaps the
+simplest major mode aside from Fundamental mode.  Rmail mode is a
+complicated and specialized mode.
+
+* Menu:
+
+* Major Mode Conventions::  Coding conventions for keymaps, etc.
+* Example Major Modes::     Text mode and Lisp modes.
+* Auto Major Mode::         How XEmacs chooses the major mode automatically.
+* Mode Help::               Finding out how to use a mode.
+* Derived Modes::           Defining a new major mode based on another major
+                              mode.
+
+
+File: lispref.info,  Node: Major Mode Conventions,  Next: Example Major Modes,  Up: Major Modes
+
+Major Mode Conventions
+----------------------
+
+   The code for existing major modes follows various coding conventions,
+including conventions for local keymap and syntax table initialization,
+global names, and hooks.  Please follow these conventions when you
+define a new major mode:
+
+   * Define a command whose name ends in `-mode', with no arguments,
+     that switches to the new mode in the current buffer.  This command
+     should set up the keymap, syntax table, and local variables in an
+     existing buffer without changing the buffer's text.
+
+   * Write a documentation string for this command that describes the
+     special commands available in this mode.  `C-h m'
+     (`describe-mode') in your mode will display this string.
+
+     The documentation string may include the special documentation
+     substrings, `\[COMMAND]', `\{KEYMAP}', and `\<KEYMAP>', that
+     enable the documentation to adapt automatically to the user's own
+     key bindings.  *Note Keys in Documentation::.
+
+   * The major mode command should start by calling
+     `kill-all-local-variables'.  This is what gets rid of the local
+     variables of the major mode previously in effect.
+
+   * The major mode command should set the variable `major-mode' to the
+     major mode command symbol.  This is how `describe-mode' discovers
+     which documentation to print.
+
+   * The major mode command should set the variable `mode-name' to the
+     "pretty" name of the mode, as a string.  This appears in the mode
+     line.
+
+   * Since all global names are in the same name space, all the global
+     variables, constants, and functions that are part of the mode
+     should have names that start with the major mode name (or with an
+     abbreviation of it if the name is long).  *Note Style Tips::.
+
+   * The major mode should usually have its own keymap, which is used
+     as the local keymap in all buffers in that mode.  The major mode
+     function should call `use-local-map' to install this local map.
+     *Note Active Keymaps::, for more information.
+
+     This keymap should be kept in a global variable named
+     `MODENAME-mode-map'.  Normally the library that defines the mode
+     sets this variable.
+
+   * The mode may have its own syntax table or may share one with other
+     related modes.  If it has its own syntax table, it should store
+     this in a variable named `MODENAME-mode-syntax-table'.  *Note
+     Syntax Tables::.
+
+   * The mode may have its own abbrev table or may share one with other
+     related modes.  If it has its own abbrev table, it should store
+     this in a variable named `MODENAME-mode-abbrev-table'.  *Note
+     Abbrev Tables::.
+
+   * Use `defvar' to set mode-related variables, so that they are not
+     reinitialized if they already have a value.  (Such reinitialization
+     could discard customizations made by the user.)
+
+   * To make a buffer-local binding for an Emacs customization
+     variable, use `make-local-variable' in the major mode command, not
+     `make-variable-buffer-local'.  The latter function would make the
+     variable local to every buffer in which it is subsequently set,
+     which would affect buffers that do not use this mode.  It is
+     undesirable for a mode to have such global effects.  *Note
+     Buffer-Local Variables::.
+
+     It's ok to use `make-variable-buffer-local', if you wish, for a
+     variable used only within a single Lisp package.
+
+   * Each major mode should have a "mode hook" named
+     `MODENAME-mode-hook'.  The major mode command should run that
+     hook, with `run-hooks', as the very last thing it does. *Note
+     Hooks::.
+
+   * The major mode command may also run the hooks of some more basic
+     modes.  For example, `indented-text-mode' runs `text-mode-hook' as
+     well as `indented-text-mode-hook'.  It may run these other hooks
+     immediately before the mode's own hook (that is, after everything
+     else), or it may run them earlier.
+
+   * If something special should be done if the user switches a buffer
+     from this mode to any other major mode, the mode can set a local
+     value for `change-major-mode-hook'.
+
+   * If this mode is appropriate only for specially-prepared text, then
+     the major mode command symbol should have a property named
+     `mode-class' with value `special', put on as follows:
+
+          (put 'funny-mode 'mode-class 'special)
+
+     This tells XEmacs that new buffers created while the current
+     buffer has Funny mode should not inherit Funny mode.  Modes such
+     as Dired, Rmail, and Buffer List use this feature.
+
+   * If you want to make the new mode the default for files with certain
+     recognizable names, add an element to `auto-mode-alist' to select
+     the mode for those file names.  If you define the mode command to
+     autoload, you should add this element in the same file that calls
+     `autoload'.  Otherwise, it is sufficient to add the element in the
+     file that contains the mode definition.  *Note Auto Major Mode::.
+
+   * In the documentation, you should provide a sample `autoload' form
+     and an example of how to add to `auto-mode-alist', that users can
+     include in their `.emacs' files.
+
+   * The top-level forms in the file defining the mode should be
+     written so that they may be evaluated more than once without
+     adverse consequences.  Even if you never load the file more than
+     once, someone else will.
+
+ - Variable: change-major-mode-hook
+     This normal hook is run by `kill-all-local-variables' before it
+     does anything else.  This gives major modes a way to arrange for
+     something special to be done if the user switches to a different
+     major mode.  For best results, make this variable buffer-local, so
+     that it will disappear after doing its job and will not interfere
+     with the subsequent major mode.  *Note Hooks::.
+
+
+File: lispref.info,  Node: Example Major Modes,  Next: Auto Major Mode,  Prev: Major Mode Conventions,  Up: Major Modes
+
+Major Mode Examples
+-------------------
+
+   Text mode is perhaps the simplest mode besides Fundamental mode.
+Here are excerpts from  `text-mode.el' that illustrate many of the
+conventions listed above:
+
+     ;; Create mode-specific tables.
+     (defvar text-mode-syntax-table nil
+       "Syntax table used while in text mode.")
+     
+     (if text-mode-syntax-table
+         ()              ; Do not change the table if it is already set up.
+       (setq text-mode-syntax-table (make-syntax-table))
+       (modify-syntax-entry ?\" ".   " text-mode-syntax-table)
+       (modify-syntax-entry ?\\ ".   " text-mode-syntax-table)
+       (modify-syntax-entry ?' "w   " text-mode-syntax-table))
+     
+     (defvar text-mode-abbrev-table nil
+       "Abbrev table used while in text mode.")
+     (define-abbrev-table 'text-mode-abbrev-table ())
+     
+     (defvar text-mode-map nil)   ; Create a mode-specific keymap.
+     
+     (if text-mode-map
+         ()              ; Do not change the keymap if it is already set up.
+       (setq text-mode-map (make-sparse-keymap))
+       (define-key text-mode-map "\t" 'tab-to-tab-stop)
+       (define-key text-mode-map "\es" 'center-line)
+       (define-key text-mode-map "\eS" 'center-paragraph))
+
+   Here is the complete major mode function definition for Text mode:
+
+     (defun text-mode ()
+       "Major mode for editing text intended for humans to read.
+      Special commands: \\{text-mode-map}
+     Turning on text-mode runs the hook `text-mode-hook'."
+       (interactive)
+       (kill-all-local-variables)
+       (use-local-map text-mode-map)     ; This provides the local keymap.
+       (setq mode-name "Text")           ; This name goes into the modeline.
+       (setq major-mode 'text-mode)      ; This is how `describe-mode'
+                                         ;   finds the doc string to print.
+       (setq local-abbrev-table text-mode-abbrev-table)
+       (set-syntax-table text-mode-syntax-table)
+       (run-hooks 'text-mode-hook))      ; Finally, this permits the user to
+                                         ;   customize the mode with a hook.
+
+   The three Lisp modes (Lisp mode, Emacs Lisp mode, and Lisp
+Interaction mode) have more features than Text mode and the code is
+correspondingly more complicated.  Here are excerpts from
+`lisp-mode.el' that illustrate how these modes are written.
+
+     ;; Create mode-specific table variables.
+     (defvar lisp-mode-syntax-table nil "")
+     (defvar emacs-lisp-mode-syntax-table nil "")
+     (defvar lisp-mode-abbrev-table nil "")
+     
+     (if (not emacs-lisp-mode-syntax-table) ; Do not change the table
+                                            ;   if it is already set.
+         (let ((i 0))
+           (setq emacs-lisp-mode-syntax-table (make-syntax-table))
+     
+           ;; Set syntax of chars up to 0 to class of chars that are
+           ;;   part of symbol names but not words.
+           ;;   (The number 0 is `48' in the ASCII character set.)
+           (while (< i ?0)
+             (modify-syntax-entry i "_   " emacs-lisp-mode-syntax-table)
+             (setq i (1+ i)))
+           ...
+           ;; Set the syntax for other characters.
+           (modify-syntax-entry ?  "    " emacs-lisp-mode-syntax-table)
+           (modify-syntax-entry ?\t "    " emacs-lisp-mode-syntax-table)
+           ...
+           (modify-syntax-entry ?\( "()  " emacs-lisp-mode-syntax-table)
+           (modify-syntax-entry ?\) ")(  " emacs-lisp-mode-syntax-table)
+           ...))
+     ;; Create an abbrev table for lisp-mode.
+     (define-abbrev-table 'lisp-mode-abbrev-table ())
+
+   Much code is shared among the three Lisp modes.  The following
+function sets various variables; it is called by each of the major Lisp
+mode functions:
+
+     (defun lisp-mode-variables (lisp-syntax)
+       ;; The `lisp-syntax' argument is `nil' in Emacs Lisp mode,
+       ;;   and `t' in the other two Lisp modes.
+       (cond (lisp-syntax
+              (if (not lisp-mode-syntax-table)
+                  ;; The Emacs Lisp mode syntax table always exists, but
+                  ;;   the Lisp Mode syntax table is created the first time a
+                  ;;   mode that needs it is called.  This is to save space.
+                  (progn (setq lisp-mode-syntax-table
+                            (copy-syntax-table emacs-lisp-mode-syntax-table))
+                         ;; Change some entries for Lisp mode.
+                         (modify-syntax-entry ?\| "\"   "
+                                              lisp-mode-syntax-table)
+                         (modify-syntax-entry ?\[ "_   "
+                                              lisp-mode-syntax-table)
+                         (modify-syntax-entry ?\] "_   "
+                                              lisp-mode-syntax-table)))
+               (set-syntax-table lisp-mode-syntax-table)))
+       (setq local-abbrev-table lisp-mode-abbrev-table)
+       ...)
+
+   Functions such as `forward-paragraph' use the value of the
+`paragraph-start' variable.  Since Lisp code is different from ordinary
+text, the `paragraph-start' variable needs to be set specially to
+handle Lisp.  Also, comments are indented in a special fashion in Lisp
+and the Lisp modes need their own mode-specific
+`comment-indent-function'.  The code to set these variables is the rest
+of `lisp-mode-variables'.
+
+       (make-local-variable 'paragraph-start)
+       ;; Having `^' is not clean, but `page-delimiter'
+       ;; has them too, and removing those is a pain.
+       (setq paragraph-start (concat "^$\\|" page-delimiter))
+       ...
+       (make-local-variable 'comment-indent-function)
+       (setq comment-indent-function 'lisp-comment-indent))
+
+   Each of the different Lisp modes has a slightly different keymap.
+For example, Lisp mode binds `C-c C-l' to `run-lisp', but the other
+Lisp modes do not.  However, all Lisp modes have some commands in
+common.  The following function adds these common commands to a given
+keymap.
+
+     (defun lisp-mode-commands (map)
+       (define-key map "\e\C-q" 'indent-sexp)
+       (define-key map "\177" 'backward-delete-char-untabify)
+       (define-key map "\t" 'lisp-indent-line))
+
+   Here is an example of using `lisp-mode-commands' to initialize a
+keymap, as part of the code for Emacs Lisp mode.  First we declare a
+variable with `defvar' to hold the mode-specific keymap.  When this
+`defvar' executes, it sets the variable to `nil' if it was void.  Then
+we set up the keymap if the variable is `nil'.
+
+   This code avoids changing the keymap or the variable if it is already
+set up.  This lets the user customize the keymap.
+
+     (defvar emacs-lisp-mode-map () "")
+     (if emacs-lisp-mode-map
+         ()
+       (setq emacs-lisp-mode-map (make-sparse-keymap))
+       (define-key emacs-lisp-mode-map "\e\C-x" 'eval-defun)
+       (lisp-mode-commands emacs-lisp-mode-map))
+
+   Finally, here is the complete major mode function definition for
+Emacs Lisp mode.
+
+     (defun emacs-lisp-mode ()
+       "Major mode for editing Lisp code to run in XEmacs.
+     Commands:
+     Delete converts tabs to spaces as it moves back.
+     Blank lines separate paragraphs.  Semicolons start comments.
+     \\{emacs-lisp-mode-map}
+     Entry to this mode runs the hook `emacs-lisp-mode-hook'."
+       (interactive)
+       (kill-all-local-variables)
+       (use-local-map emacs-lisp-mode-map)    ; This provides the local keymap.
+       (set-syntax-table emacs-lisp-mode-syntax-table)
+       (setq major-mode 'emacs-lisp-mode)     ; This is how `describe-mode'
+                                              ;   finds out what to describe.
+       (setq mode-name "Emacs-Lisp")          ; This goes into the modeline.
+       (lisp-mode-variables nil)              ; This defines various variables.
+       (run-hooks 'emacs-lisp-mode-hook))     ; This permits the user to use a
+                                              ;   hook to customize the mode.
+
+
+File: lispref.info,  Node: Auto Major Mode,  Next: Mode Help,  Prev: Example Major Modes,  Up: Major Modes
+
+How XEmacs Chooses a Major Mode
+-------------------------------
+
+   Based on information in the file name or in the file itself, XEmacs
+automatically selects a major mode for the new buffer when a file is
+visited.
+
+ - Command: fundamental-mode
+     Fundamental mode is a major mode that is not specialized for
+     anything in particular.  Other major modes are defined in effect
+     by comparison with this one--their definitions say what to change,
+     starting from Fundamental mode.  The `fundamental-mode' function
+     does _not_ run any hooks; you're not supposed to customize it.
+     (If you want Emacs to behave differently in Fundamental mode,
+     change the _global_ state of Emacs.)
+
+ - Command: normal-mode &optional find-file
+     This function establishes the proper major mode and local variable
+     bindings for the current buffer.  First it calls `set-auto-mode',
+     then it runs `hack-local-variables' to parse, and bind or evaluate
+     as appropriate, any local variables.
+
+     If the FIND-FILE argument to `normal-mode' is non-`nil',
+     `normal-mode' assumes that the `find-file' function is calling it.
+     In this case, it may process a local variables list at the end of
+     the file and in the `-*-' line.  The variable
+     `enable-local-variables' controls whether to do so.
+
+     If you run `normal-mode' interactively, the argument FIND-FILE is
+     normally `nil'.  In this case, `normal-mode' unconditionally
+     processes any local variables list.  *Note Local Variables in
+     Files: (xemacs)File variables, for the syntax of the local
+     variables section of a file.
+
+     `normal-mode' uses `condition-case' around the call to the major
+     mode function, so errors are caught and reported as a `File mode
+     specification error',  followed by the original error message.
+
+ - User Option: enable-local-variables
+     This variable controls processing of local variables lists in files
+     being visited.  A value of `t' means process the local variables
+     lists unconditionally; `nil' means ignore them; anything else means
+     ask the user what to do for each file.  The default value is `t'.
+
+ - Variable: ignored-local-variables
+     This variable holds a list of variables that should not be set by
+     a local variables list.  Any value specified for one of these
+     variables is ignored.
+
+   In addition to this list, any variable whose name has a non-`nil'
+`risky-local-variable' property is also ignored.
+
+ - User Option: enable-local-eval
+     This variable controls processing of `Eval:' in local variables
+     lists in files being visited.  A value of `t' means process them
+     unconditionally; `nil' means ignore them; anything else means ask
+     the user what to do for each file.  The default value is `maybe'.
+
+ - Function: set-auto-mode
+     This function selects the major mode that is appropriate for the
+     current buffer.  It may base its decision on the value of the `-*-'
+     line, on the visited file name (using `auto-mode-alist'), or on the
+     value of a local variable.  However, this function does not look
+     for the `mode:' local variable near the end of a file; the
+     `hack-local-variables' function does that.  *Note How Major Modes
+     are Chosen: (xemacs)Choosing Modes.
+
+ - User Option: default-major-mode
+     This variable holds the default major mode for new buffers.  The
+     standard value is `fundamental-mode'.
+
+     If the value of `default-major-mode' is `nil', XEmacs uses the
+     (previously) current buffer's major mode for the major mode of a
+     new buffer.  However, if the major mode symbol has a `mode-class'
+     property with value `special', then it is not used for new buffers;
+     Fundamental mode is used instead.  The modes that have this
+     property are those such as Dired and Rmail that are useful only
+     with text that has been specially prepared.
+
+ - Function: set-buffer-major-mode buffer
+     This function sets the major mode of BUFFER to the value of
+     `default-major-mode'.  If that variable is `nil', it uses the
+     current buffer's major mode (if that is suitable).
+
+     The low-level primitives for creating buffers do not use this
+     function, but medium-level commands such as `switch-to-buffer' and
+     `find-file-noselect' use it whenever they create buffers.
+
+ - Variable: initial-major-mode
+     The value of this variable determines the major mode of the initial
+     `*scratch*' buffer.  The value should be a symbol that is a major
+     mode command name.  The default value is `lisp-interaction-mode'.
+
+ - Variable: auto-mode-alist
+     This variable contains an association list of file name patterns
+     (regular expressions; *note Regular Expressions::) and
+     corresponding major mode functions.  Usually, the file name
+     patterns test for suffixes, such as `.el' and `.c', but this need
+     not be the case.  An ordinary element of the alist looks like
+     `(REGEXP .  MODE-FUNCTION)'.
+
+     For example,
+
+          (("^/tmp/fol/" . text-mode)
+           ("\\.texinfo\\'" . texinfo-mode)
+           ("\\.texi\\'" . texinfo-mode)
+           ("\\.el\\'" . emacs-lisp-mode)
+           ("\\.c\\'" . c-mode)
+           ("\\.h\\'" . c-mode)
+           ...)
+
+     When you visit a file whose expanded file name (*note File Name
+     Expansion::) matches a REGEXP, `set-auto-mode' calls the
+     corresponding MODE-FUNCTION.  This feature enables XEmacs to select
+     the proper major mode for most files.
+
+     If an element of `auto-mode-alist' has the form `(REGEXP FUNCTION
+     t)', then after calling FUNCTION, XEmacs searches
+     `auto-mode-alist' again for a match against the portion of the file
+     name that did not match before.
+
+     This match-again feature is useful for uncompression packages: an
+     entry of the form `("\\.gz\\'" . FUNCTION)' can uncompress the file
+     and then put the uncompressed file in the proper mode according to
+     the name sans `.gz'.
+
+     Here is an example of how to prepend several pattern pairs to
+     `auto-mode-alist'.  (You might use this sort of expression in your
+     `.emacs' file.)
+
+          (setq auto-mode-alist
+            (append
+             ;; File name starts with a dot.
+             '(("/\\.[^/]*\\'" . fundamental-mode)
+               ;; File name has no dot.
+               ("[^\\./]*\\'" . fundamental-mode)
+               ;; File name ends in `.C'.
+               ("\\.C\\'" . c++-mode))
+             auto-mode-alist))
+
+ - Variable: interpreter-mode-alist
+     This variable specifies major modes to use for scripts that
+     specify a command interpreter in an `#!' line.  Its value is a
+     list of elements of the form `(INTERPRETER . MODE)'; for example,
+     `("perl" . perl-mode)' is one element present by default.  The
+     element says to use mode MODE if the file specifies INTERPRETER.
+
+     This variable is applicable only when the `auto-mode-alist' does
+     not indicate which major mode to use.
+
+ - Function: hack-local-variables &optional force
+     This function parses, and binds or evaluates as appropriate, any
+     local variables for the current buffer.
+
+     The handling of `enable-local-variables' documented for
+     `normal-mode' actually takes place here.  The argument FORCE
+     usually comes from the argument FIND-FILE given to `normal-mode'.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-22'
Index: ././info/lispref.info-22
--- ././info/lispref.info-22	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-22	Thu May 17 23:26:54 2001
@@ -0,0 +1,1147 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Mode Help,  Next: Derived Modes,  Prev: Auto Major Mode,  Up: Major Modes
+
+Getting Help about a Major Mode
+-------------------------------
+
+   The `describe-mode' function is used to provide information about
+major modes.  It is normally called with `C-h m'.  The `describe-mode'
+function uses the value of `major-mode', which is why every major mode
+function needs to set the `major-mode' variable.
+
+ - Command: describe-mode
+     This function displays the documentation of the current major mode.
+
+     The `describe-mode' function calls the `documentation' function
+     using the value of `major-mode' as an argument.  Thus, it displays
+     the documentation string of the major mode function.  (*Note
+     Accessing Documentation::.)
+
+ - Variable: major-mode
+     This variable holds the symbol for the current buffer's major mode.
+     This symbol should have a function definition that is the command
+     to switch to that major mode.  The `describe-mode' function uses
+     the documentation string of the function as the documentation of
+     the major mode.
+
+
+File: lispref.info,  Node: Derived Modes,  Prev: Mode Help,  Up: Major Modes
+
+Defining Derived Modes
+----------------------
+
+   It's often useful to define a new major mode in terms of an existing
+one.  An easy way to do this is to use `define-derived-mode'.
+
+ - Macro: define-derived-mode variant parent name docstring body...
+     This construct defines VARIANT as a major mode command, using NAME
+     as the string form of the mode name.
+
+     The new command VARIANT is defined to call the function PARENT,
+     then override certain aspects of that parent mode:
+
+        * The new mode has its own keymap, named `VARIANT-map'.
+          `define-derived-mode' initializes this map to inherit from
+          `PARENT-map', if it is not already set.
+
+        * The new mode has its own syntax table, kept in the variable
+          `VARIANT-syntax-table'.  `define-derived-mode' initializes
+          this variable by copying `PARENT-syntax-table', if it is not
+          already set.
+
+        * The new mode has its own abbrev table, kept in the variable
+          `VARIANT-abbrev-table'.  `define-derived-mode' initializes
+          this variable by copying `PARENT-abbrev-table', if it is not
+          already set.
+
+        * The new mode has its own mode hook, `VARIANT-hook', which it
+          runs in standard fashion as the very last thing that it does.
+          (The new mode also runs the mode hook of PARENT as part of
+          calling PARENT.)
+
+     In addition, you can specify how to override other aspects of
+     PARENT with BODY.  The command VARIANT evaluates the forms in BODY
+     after setting up all its usual overrides, just before running
+     `VARIANT-hook'.
+
+     The argument DOCSTRING specifies the documentation string for the
+     new mode.  If you omit DOCSTRING, `define-derived-mode' generates
+     a documentation string.
+
+     Here is a hypothetical example:
+
+          (define-derived-mode hypertext-mode
+            text-mode "Hypertext"
+            "Major mode for hypertext.
+          \\{hypertext-mode-map}"
+            (setq case-fold-search nil))
+          
+          (define-key hypertext-mode-map
+            [down-mouse-3] 'do-hyper-link)
+
+
+File: lispref.info,  Node: Minor Modes,  Next: Modeline Format,  Prev: Major Modes,  Up: Modes
+
+Minor Modes
+===========
+
+   A "minor mode" provides features that users may enable or disable
+independently of the choice of major mode.  Minor modes can be enabled
+individually or in combination.  Minor modes would be better named
+"Generally available, optional feature modes" except that such a name is
+unwieldy.
+
+   A minor mode is not usually a modification of single major mode.  For
+example, Auto Fill mode may be used in any major mode that permits text
+insertion.  To be general, a minor mode must be effectively independent
+of the things major modes do.
+
+   A minor mode is often much more difficult to implement than a major
+mode.  One reason is that you should be able to activate and deactivate
+minor modes in any order.  A minor mode should be able to have its
+desired effect regardless of the major mode and regardless of the other
+minor modes in effect.
+
+   Often the biggest problem in implementing a minor mode is finding a
+way to insert the necessary hook into the rest of XEmacs.  Minor mode
+keymaps make this easier than it used to be.
+
+* Menu:
+
+* Minor Mode Conventions::      Tips for writing a minor mode.
+* Keymaps and Minor Modes::     How a minor mode can have its own keymap.
+
+
+File: lispref.info,  Node: Minor Mode Conventions,  Next: Keymaps and Minor Modes,  Up: Minor Modes
+
+Conventions for Writing Minor Modes
+-----------------------------------
+
+   There are conventions for writing minor modes just as there are for
+major modes.  Several of the major mode conventions apply to minor
+modes as well: those regarding the name of the mode initialization
+function, the names of global symbols, and the use of keymaps and other
+tables.
+
+   In addition, there are several conventions that are specific to
+minor modes.
+
+   * Make a variable whose name ends in `-mode' to represent the minor
+     mode.  Its value should enable or disable the mode (`nil' to
+     disable; anything else to enable.)  We call this the "mode
+     variable".
+
+     This variable is used in conjunction with the `minor-mode-alist' to
+     display the minor mode name in the modeline.  It can also enable
+     or disable a minor mode keymap.  Individual commands or hooks can
+     also check the variable's value.
+
+     If you want the minor mode to be enabled separately in each buffer,
+     make the variable buffer-local.
+
+   * Define a command whose name is the same as the mode variable.  Its
+     job is to enable and disable the mode by setting the variable.
+
+     The command should accept one optional argument.  If the argument
+     is `nil', it should toggle the mode (turn it on if it is off, and
+     off if it is on).  Otherwise, it should turn the mode on if the
+     argument is a positive integer, a symbol other than `nil' or `-',
+     or a list whose CAR is such an integer or symbol; it should turn
+     the mode off otherwise.
+
+     Here is an example taken from the definition of
+     `transient-mark-mode'.  It shows the use of `transient-mark-mode'
+     as a variable that enables or disables the mode's behavior, and
+     also shows the proper way to toggle, enable or disable the minor
+     mode based on the raw prefix argument value.
+
+          (setq transient-mark-mode
+                (if (null arg) (not transient-mark-mode)
+                  (> (prefix-numeric-value arg) 0)))
+
+   * Add an element to `minor-mode-alist' for each minor mode (*note
+     Modeline Variables::).  This element should be a list of the
+     following form:
+
+          (MODE-VARIABLE STRING)
+
+     Here MODE-VARIABLE is the variable that controls enabling of the
+     minor mode, and STRING is a short string, starting with a space,
+     to represent the mode in the modeline.  These strings must be
+     short so that there is room for several of them at once.
+
+     When you add an element to `minor-mode-alist', use `assq' to check
+     for an existing element, to avoid duplication.  For example:
+
+          (or (assq 'leif-mode minor-mode-alist)
+              (setq minor-mode-alist
+                    (cons '(leif-mode " Leif") minor-mode-alist)))
+
+
+File: lispref.info,  Node: Keymaps and Minor Modes,  Prev: Minor Mode Conventions,  Up: Minor Modes
+
+Keymaps and Minor Modes
+-----------------------
+
+   Each minor mode can have its own keymap, which is active when the
+mode is enabled.  To set up a keymap for a minor mode, add an element
+to the alist `minor-mode-map-alist'.  *Note Active Keymaps::.
+
+   One use of minor mode keymaps is to modify the behavior of certain
+self-inserting characters so that they do something else as well as
+self-insert.  In general, this is the only way to do that, since the
+facilities for customizing `self-insert-command' are limited to special
+cases (designed for abbrevs and Auto Fill mode).  (Do not try
+substituting your own definition of `self-insert-command' for the
+standard one.  The editor command loop handles this function specially.)
+
+
+File: lispref.info,  Node: Modeline Format,  Next: Hooks,  Prev: Minor Modes,  Up: Modes
+
+Modeline Format
+===============
+
+   Each Emacs window (aside from minibuffer windows) includes a
+modeline, which displays status information about the buffer displayed
+in the window.  The modeline contains information about the buffer,
+such as its name, associated file, depth of recursive editing, and the
+major and minor modes.
+
+   This section describes how the contents of the modeline are
+controlled.  It is in the chapter on modes because much of the
+information displayed in the modeline relates to the enabled major and
+minor modes.
+
+   `modeline-format' is a buffer-local variable that holds a template
+used to display the modeline of the current buffer.  All windows for
+the same buffer use the same `modeline-format' and their modelines
+appear the same (except for scrolling percentages and line numbers).
+
+   The modeline of a window is normally updated whenever a different
+buffer is shown in the window, or when the buffer's modified-status
+changes from `nil' to `t' or vice-versa.  If you modify any of the
+variables referenced by `modeline-format' (*note Modeline Variables::),
+you may want to force an update of the modeline so as to display the
+new information.
+
+ - Function: redraw-modeline &optional all
+     Force redisplay of the current buffer's modeline.  If ALL is
+     non-`nil', then force redisplay of all modelines.
+
+   The modeline is usually displayed in inverse video.  This is
+controlled using the `modeline' face.  *Note Faces::.
+
+* Menu:
+
+* Modeline Data::         The data structure that controls the modeline.
+* Modeline Variables::    Variables used in that data structure.
+* %-Constructs::          Putting information into a modeline.
+
+
+File: lispref.info,  Node: Modeline Data,  Next: Modeline Variables,  Up: Modeline Format
+
+The Data Structure of the Modeline
+----------------------------------
+
+   The modeline contents are controlled by a data structure of lists,
+strings, symbols, and numbers kept in the buffer-local variable
+`modeline-format'.  The data structure is called a "modeline
+construct", and it is built in recursive fashion out of simpler modeline
+constructs.  The same data structure is used for constructing frame
+titles (*note Frame Titles::).
+
+ - Variable: modeline-format
+     The value of this variable is a modeline construct with overall
+     responsibility for the modeline format.  The value of this variable
+     controls which other variables are used to form the modeline text,
+     and where they appear.
+
+   A modeline construct may be as simple as a fixed string of text, but
+it usually specifies how to use other variables to construct the text.
+Many of these variables are themselves defined to have modeline
+constructs as their values.
+
+   The default value of `modeline-format' incorporates the values of
+variables such as `mode-name' and `minor-mode-alist'.  Because of this,
+very few modes need to alter `modeline-format'.  For most purposes, it
+is sufficient to alter the variables referenced by `modeline-format'.
+
+   A modeline construct may be a string, symbol, glyph, generic
+specifier, list or cons cell.
+
+`STRING'
+     A string as a modeline construct is displayed verbatim in the mode
+     line except for "`%'-constructs".  Decimal digits after the `%'
+     specify the field width for space filling on the right (i.e., the
+     data is left justified).  *Note %-Constructs::.
+
+`SYMBOL'
+     A symbol as a modeline construct stands for its value.  The value
+     of SYMBOL is processed as a modeline construct, in place of
+     SYMBOL.  However, the symbols `t' and `nil' are ignored; so is any
+     symbol whose value is void.
+
+     There is one exception: if the value of SYMBOL is a string, it is
+     displayed verbatim: the `%'-constructs are not recognized.
+
+`GLYPH'
+     A glyph is displayed as is.
+
+`GENERIC-SPECIFIER'
+     A GENERIC-SPECIFIER (i.e. a specifier of type `generic') stands
+     for its instance.  The instance of GENERIC-SPECIFIER is computed
+     in the current window using the equivalent of `specifier-instance'
+     and the value is processed.
+
+`(STRING REST...) or (LIST REST...)'
+     A list whose first element is a string or list means to process
+     all the elements recursively and concatenate the results.  This is
+     the most common form of mode line construct.
+
+`(SYMBOL THEN ELSE)'
+     A list whose first element is a symbol is a conditional.  Its
+     meaning depends on the value of SYMBOL.  If the value is non-`nil',
+     the second element, THEN, is processed recursively as a modeline
+     element.  But if the value of SYMBOL is `nil', the third element,
+     ELSE, is processed recursively.  You may omit ELSE; then the mode
+     line element displays nothing if the value of SYMBOL is `nil'.
+
+`(WIDTH REST...)'
+     A list whose first element is an integer specifies truncation or
+     padding of the results of REST.  The remaining elements REST are
+     processed recursively as modeline constructs and concatenated
+     together.  Then the result is space filled (if WIDTH is positive)
+     or truncated (to -WIDTH columns, if WIDTH is negative) on the
+     right.
+
+     For example, the usual way to show what percentage of a buffer is
+     above the top of the window is to use a list like this: `(-3
+     "%p")'.
+
+`(EXTENT REST...)'
+     A list whose car is an extent means the cdr of the list is
+     processed normally but the results are displayed using the face of
+     the extent, and mouse clicks over this section are processed using
+     the keymap of the extent. (In addition, if the extent has a
+     help-echo property, that string will be echoed when the mouse
+     moves over this section.) If extents are nested, all keymaps are
+     properly consulted when processing mouse clicks, but multiple
+     faces are not correctly merged (only the first face is used), and
+     lists of faces are not correctly handled.
+
+   If you do alter `modeline-format' itself, the new value should use
+the same variables that appear in the default value (*note Modeline
+Variables::), rather than duplicating their contents or displaying the
+information in another fashion.  This way, customizations made by the
+user or by Lisp programs (such as `display-time' and major modes) via
+changes to those variables remain effective.
+
+   Here is an example of a `modeline-format' that might be useful for
+`shell-mode', since it contains the hostname and default directory.
+
+     (setq modeline-format
+       (list ""
+        'modeline-modified
+        "%b--"
+        (getenv "HOST")      ; One element is not constant.
+        ":"
+        'default-directory
+        "   "
+        'global-mode-string
+        "   %[("
+        'mode-name
+        'modeline-process
+        'minor-mode-alist
+        "%n"
+        ")%]----"
+        '(line-number-mode "L%l--")
+        '(-3 . "%p")
+        "-%-"))
+
+
+File: lispref.info,  Node: Modeline Variables,  Next: %-Constructs,  Prev: Modeline Data,  Up: Modeline Format
+
+Variables Used in the Modeline
+------------------------------
+
+   This section describes variables incorporated by the standard value
+of `modeline-format' into the text of the mode line.  There is nothing
+inherently special about these variables; any other variables could
+have the same effects on the modeline if `modeline-format' were changed
+to use them.
+
+ - Variable: modeline-modified
+     This variable holds the value of the modeline construct that
+     displays whether the current buffer is modified.
+
+     The default value of `modeline-modified' is `("--%1*%1+-")'.  This
+     means that the modeline displays `--**-' if the buffer is
+     modified, `-----' if the buffer is not modified, `--%%-' if the
+     buffer is read only, and `--%*--' if the buffer is read only and
+     modified.
+
+     Changing this variable does not force an update of the modeline.
+
+ - Variable: modeline-buffer-identification
+     This variable identifies the buffer being displayed in the window.
+     Its default value is `("%F: %17b")', which means that it usually
+     displays `Emacs:' followed by seventeen characters of the buffer
+     name.  (In a terminal frame, it displays the frame name instead of
+     `Emacs'; this has the effect of showing the frame number.)  You may
+     want to change this in modes such as Rmail that do not behave like
+     a "normal" XEmacs.
+
+ - Variable: global-mode-string
+     This variable holds a modeline spec that appears in the mode line
+     by default, just after the buffer name.  The command `display-time'
+     sets `global-mode-string' to refer to the variable
+     `display-time-string', which holds a string containing the time and
+     load information.
+
+     The `%M' construct substitutes the value of `global-mode-string',
+     but this is obsolete, since the variable is included directly in
+     the modeline.
+
+ - Variable: mode-name
+     This buffer-local variable holds the "pretty" name of the current
+     buffer's major mode.  Each major mode should set this variable so
+     that the mode name will appear in the modeline.
+
+ - Variable: minor-mode-alist
+     This variable holds an association list whose elements specify how
+     the modeline should indicate that a minor mode is active.  Each
+     element of the `minor-mode-alist' should be a two-element list:
+
+          (MINOR-MODE-VARIABLE MODELINE-STRING)
+
+     More generally, MODELINE-STRING can be any mode line spec.  It
+     appears in the mode line when the value of MINOR-MODE-VARIABLE is
+     non-`nil', and not otherwise.  These strings should begin with
+     spaces so that they don't run together.  Conventionally, the
+     MINOR-MODE-VARIABLE for a specific mode is set to a non-`nil'
+     value when that minor mode is activated.
+
+     The default value of `minor-mode-alist' is:
+
+          minor-mode-alist
+          => ((vc-mode vc-mode)
+              (abbrev-mode " Abbrev")
+              (overwrite-mode overwrite-mode)
+              (auto-fill-function " Fill")
+              (defining-kbd-macro " Def")
+              (isearch-mode isearch-mode))
+
+     `minor-mode-alist' is not buffer-local.  The variables mentioned
+     in the alist should be buffer-local if the minor mode can be
+     enabled separately in each buffer.
+
+ - Variable: modeline-process
+     This buffer-local variable contains the modeline information on
+     process status in modes used for communicating with subprocesses.
+     It is displayed immediately following the major mode name, with no
+     intervening space.  For example, its value in the `*shell*' buffer
+     is `(": %s")', which allows the shell to display its status along
+     with the major mode as: `(Shell: run)'.  Normally this variable is
+     `nil'.
+
+ - Variable: default-modeline-format
+     This variable holds the default `modeline-format' for buffers that
+     do not override it.  This is the same as `(default-value
+     'modeline-format)'.
+
+     The default value of `default-modeline-format' is:
+
+          (""
+           modeline-modified
+           modeline-buffer-identification
+           "   "
+           global-mode-string
+           "   %[("
+           mode-name
+           modeline-process
+           minor-mode-alist
+           "%n"
+           ")%]----"
+           (line-number-mode "L%l--")
+           (-3 . "%p")
+           "-%-")
+
+ - Variable: vc-mode
+     The variable `vc-mode', local in each buffer, records whether the
+     buffer's visited file is maintained with version control, and, if
+     so, which kind.  Its value is `nil' for no version control, or a
+     string that appears in the mode line.
+
+
+File: lispref.info,  Node: %-Constructs,  Prev: Modeline Variables,  Up: Modeline Format
+
+`%'-Constructs in the ModeLine
+------------------------------
+
+   The following table lists the recognized `%'-constructs and what
+they mean.  In any construct except `%%', you can add a decimal integer
+after the `%' to specify how many characters to display.
+
+`%b'
+     The current buffer name, obtained with the `buffer-name' function.
+     *Note Buffer Names::.
+
+`%f'
+     The visited file name, obtained with the `buffer-file-name'
+     function.  *Note Buffer File Name::.
+
+`%F'
+     The name of the selected frame.
+
+`%c'
+     The current column number of point.
+
+`%l'
+     The current line number of point.
+
+`%*'
+     `%' if the buffer is read only (see `buffer-read-only');
+     `*' if the buffer is modified (see `buffer-modified-p');
+     `-' otherwise.  *Note Buffer Modification::.
+
+`%+'
+     `*' if the buffer is modified (see `buffer-modified-p');
+     `%' if the buffer is read only (see `buffer-read-only');
+     `-' otherwise.  This differs from `%*' only for a modified
+     read-only buffer.  *Note Buffer Modification::.
+
+`%&'
+     `*' if the buffer is modified, and `-' otherwise.
+
+`%s'
+     The status of the subprocess belonging to the current buffer,
+     obtained with `process-status'.  *Note Process Information::.
+
+`%l'
+     The current line number.
+
+`%S'
+     The name of the selected frame; this is only meaningful under the
+     X Window System.  *Note Frame Name::.
+
+`%t'
+     Whether the visited file is a text file or a binary file.  (This
+     is a meaningful distinction only on certain operating systems.)
+
+`%p'
+     The percentage of the buffer text above the *top* of window, or
+     `Top', `Bottom' or `All'.
+
+`%P'
+     The percentage of the buffer text that is above the *bottom* of
+     the window (which includes the text visible in the window, as well
+     as the text above the top), plus `Top' if the top of the buffer is
+     visible on screen; or `Bottom' or `All'.
+
+`%n'
+     `Narrow' when narrowing is in effect; nothing otherwise (see
+     `narrow-to-region' in *Note Narrowing::).
+
+`%C'
+     Under XEmacs/mule, the mnemonic for `buffer-file-coding-system'.
+
+`%['
+     An indication of the depth of recursive editing levels (not
+     counting minibuffer levels): one `[' for each editing level.
+     *Note Recursive Editing::.
+
+`%]'
+     One `]' for each recursive editing level (not counting minibuffer
+     levels).
+
+`%%'
+     The character `%'--this is how to include a literal `%' in a
+     string in which `%'-constructs are allowed.
+
+`%-'
+     Dashes sufficient to fill the remainder of the modeline.
+
+   The following two `%'-constructs are still supported, but they are
+obsolete, since you can get the same results with the variables
+`mode-name' and `global-mode-string'.
+
+`%m'
+     The value of `mode-name'.
+
+`%M'
+     The value of `global-mode-string'.  Currently, only `display-time'
+     modifies the value of `global-mode-string'.
+
+
+File: lispref.info,  Node: Hooks,  Prev: Modeline Format,  Up: Modes
+
+Hooks
+=====
+
+   A "hook" is a variable where you can store a function or functions
+to be called on a particular occasion by an existing program.  XEmacs
+provides hooks for the sake of customization.  Most often, hooks are set
+up in the `.emacs' file, but Lisp programs can set them also.  *Note
+Standard Hooks::, for a list of standard hook variables.
+
+   Most of the hooks in XEmacs are "normal hooks".  These variables
+contain lists of functions to be called with no arguments.  The reason
+most hooks are normal hooks is so that you can use them in a uniform
+way.  You can usually tell when a hook is a normal hook, because its
+name ends in `-hook'.
+
+   The recommended way to add a hook function to a normal hook is by
+calling `add-hook' (see below).  The hook functions may be any of the
+valid kinds of functions that `funcall' accepts (*note What Is a
+Function::).  Most normal hook variables are initially void; `add-hook'
+knows how to deal with this.
+
+   As for abnormal hooks, those whose names end in `-function' have a
+value that is a single function.  Those whose names end in `-hooks'
+have a value that is a list of functions.  Any hook that is abnormal is
+abnormal because a normal hook won't do the job; either the functions
+are called with arguments, or their values are meaningful.  The name
+shows you that the hook is abnormal and that you should look at its
+documentation string to see how to use it properly.
+
+   Major mode functions are supposed to run a hook called the "mode
+hook" as the last step of initialization.  This makes it easy for a user
+to customize the behavior of the mode, by overriding the local variable
+assignments already made by the mode.  But hooks are used in other
+contexts too.  For example, the hook `suspend-hook' runs just before
+XEmacs suspends itself (*note Suspending XEmacs::).
+
+   Here's an expression that uses a mode hook to turn on Auto Fill mode
+when in Lisp Interaction mode:
+
+     (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
+
+   The next example shows how to use a hook to customize the way XEmacs
+formats C code.  (People often have strong personal preferences for one
+format or another.)  Here the hook function is an anonymous lambda
+expression.
+
+     (add-hook 'c-mode-hook
+       (function (lambda ()
+                   (setq c-indent-level 4
+                         c-argdecl-indent 0
+                         c-label-offset -4
+                         c-continued-statement-indent 0
+                         c-brace-offset 0
+                         comment-column 40))))
+     
+     (setq c++-mode-hook c-mode-hook)
+
+   The final example shows how the appearance of the modeline can be
+modified for a particular class of buffers only.
+
+     (add-hook 'text-mode-hook
+       (function (lambda ()
+                   (setq modeline-format
+                         '(modeline-modified
+                           "Emacs: %14b"
+                           "  "
+                           default-directory
+                           " "
+                           global-mode-string
+                           "%[("
+                           mode-name
+                           minor-mode-alist
+                           "%n"
+                           modeline-process
+                           ") %]---"
+                           (-3 . "%p")
+                           "-%-")))))
+
+   At the appropriate time, XEmacs uses the `run-hooks' function to run
+particular hooks.  This function calls the hook functions you have
+added with `add-hooks'.
+
+ - Function: run-hooks &rest hookvar
+     This function takes one or more hook variable names as arguments,
+     and runs each hook in turn.  Each HOOKVAR argument should be a
+     symbol that is a hook variable.  These arguments are processed in
+     the order specified.
+
+     If a hook variable has a non-`nil' value, that value may be a
+     function or a list of functions.  If the value is a function
+     (either a lambda expression or a symbol with a function
+     definition), it is called.  If it is a list, the elements are
+     called, in order.  The hook functions are called with no arguments.
+
+     For example, here's how `emacs-lisp-mode' runs its mode hook:
+
+          (run-hooks 'emacs-lisp-mode-hook)
+
+ - Function: add-hook hook function &optional append local
+     This function is the handy way to add function FUNCTION to hook
+     variable HOOK.  The argument FUNCTION may be any valid Lisp
+     function with the proper number of arguments.  For example,
+
+          (add-hook 'text-mode-hook 'my-text-hook-function)
+
+     adds `my-text-hook-function' to the hook called `text-mode-hook'.
+
+     You can use `add-hook' for abnormal hooks as well as for normal
+     hooks.
+
+     It is best to design your hook functions so that the order in
+     which they are executed does not matter.  Any dependence on the
+     order is "asking for trouble."  However, the order is predictable:
+     normally, FUNCTION goes at the front of the hook list, so it will
+     be executed first (barring another `add-hook' call).
+
+     If the optional argument APPEND is non-`nil', the new hook
+     function goes at the end of the hook list and will be executed
+     last.
+
+     If LOCAL is non-`nil', that says to make the new hook function
+     local to the current buffer.  Before you can do this, you must
+     make the hook itself buffer-local by calling `make-local-hook'
+     (*not* `make-local-variable').  If the hook itself is not
+     buffer-local, then the value of LOCAL makes no difference--the
+     hook function is always global.
+
+ - Function: remove-hook hook function &optional local
+     This function removes FUNCTION from the hook variable HOOK.
+
+     If LOCAL is non-`nil', that says to remove FUNCTION from the local
+     hook list instead of from the global hook list.  If the hook
+     itself is not buffer-local, then the value of LOCAL makes no
+     difference.
+
+ - Function: make-local-hook hook
+     This function makes the hook variable HOOK local to the current
+     buffer.  When a hook variable is local, it can have local and
+     global hook functions, and `run-hooks' runs all of them.
+
+     This function works by making `t' an element of the buffer-local
+     value.  That serves as a flag to use the hook functions in the
+     default value of the hook variable as well as those in the local
+     value.  Since `run-hooks' understands this flag, `make-local-hook'
+     works with all normal hooks.  It works for only some non-normal
+     hooks--those whose callers have been updated to understand this
+     meaning of `t'.
+
+     Do not use `make-local-variable' directly for hook variables; it is
+     not sufficient.
+
+
+File: lispref.info,  Node: Documentation,  Next: Files,  Prev: Modes,  Up: Top
+
+Documentation
+*************
+
+   XEmacs Lisp has convenient on-line help facilities, most of which
+derive their information from the documentation strings associated with
+functions and variables.  This chapter describes how to write good
+documentation strings for your Lisp programs, as well as how to write
+programs to access documentation.
+
+   Note that the documentation strings for XEmacs are not the same thing
+as the XEmacs manual.  Manuals have their own source files, written in
+the Texinfo language; documentation strings are specified in the
+definitions of the functions and variables they apply to.  A collection
+of documentation strings is not sufficient as a manual because a good
+manual is not organized in that fashion; it is organized in terms of
+topics of discussion.
+
+* Menu:
+
+* Documentation Basics::      Good style for doc strings.
+                                Where to put them.  How XEmacs stores them.
+* Accessing Documentation::   How Lisp programs can access doc strings.
+* Keys in Documentation::     Substituting current key bindings.
+* Describing Characters::     Making printable descriptions of
+                                non-printing characters and key sequences.
+* Help Functions::            Subroutines used by XEmacs help facilities.
+* Obsoleteness::	      Upgrading Lisp functionality over time.
+
+
+File: lispref.info,  Node: Documentation Basics,  Next: Accessing Documentation,  Up: Documentation
+
+Documentation Basics
+====================
+
+   A documentation string is written using the Lisp syntax for strings,
+with double-quote characters surrounding the text of the string.  This
+is because it really is a Lisp string object.  The string serves as
+documentation when it is written in the proper place in the definition
+of a function or variable.  In a function definition, the documentation
+string follows the argument list.  In a variable definition, the
+documentation string follows the initial value of the variable.
+
+   When you write a documentation string, make the first line a complete
+sentence (or two complete sentences) since some commands, such as
+`apropos', show only the first line of a multi-line documentation
+string.  Also, you should not indent the second line of a documentation
+string, if you have one, because that looks odd when you use `C-h f'
+(`describe-function') or `C-h v' (`describe-variable').  *Note
+Documentation Tips::.
+
+   Documentation strings may contain several special substrings, which
+stand for key bindings to be looked up in the current keymaps when the
+documentation is displayed.  This allows documentation strings to refer
+to the keys for related commands and be accurate even when a user
+rearranges the key bindings.  (*Note Accessing Documentation::.)
+
+   Within the Lisp world, a documentation string is accessible through
+the function or variable that it describes:
+
+   * The documentation for a function is stored in the function
+     definition itself (*note Lambda Expressions::).  The function
+     `documentation' knows how to extract it.
+
+   * The documentation for a variable is stored in the variable's
+     property list under the property name `variable-documentation'.
+     The function `documentation-property' knows how to extract it.
+
+   To save space, the documentation for preloaded functions and
+variables (including primitive functions and autoloaded functions) is
+stored in the "internal doc file" `DOC'.  The documentation for
+functions and variables loaded during the XEmacs session from
+byte-compiled files is stored in those very same byte-compiled files
+(*note Docs and Compilation::).
+
+   XEmacs does not keep documentation strings in memory unless
+necessary.  Instead, XEmacs maintains, for preloaded symbols, an
+integer offset into the internal doc file, and for symbols loaded from
+byte-compiled files, a list containing the filename of the
+byte-compiled file and an integer offset, in place of the documentation
+string.  The functions `documentation' and `documentation-property' use
+that information to read the documentation from the appropriate file;
+this is transparent to the user.
+
+   For information on the uses of documentation strings, see *Note
+Help: (xemacs)Help.
+
+   The `emacs/lib-src' directory contains two utilities that you can
+use to print nice-looking hardcopy for the file
+`emacs/etc/DOC-VERSION'.  These are `sorted-doc.c' and `digest-doc.c'.
+
+
+File: lispref.info,  Node: Accessing Documentation,  Next: Keys in Documentation,  Prev: Documentation Basics,  Up: Documentation
+
+Access to Documentation Strings
+===============================
+
+ - Function: documentation-property symbol property &optional verbatim
+     This function returns the documentation string that is recorded in
+     SYMBOL's property list under property PROPERTY.  It retrieves the
+     text from a file if necessary, and runs `substitute-command-keys'
+     to substitute actual key bindings.  (This substitution is not done
+     if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
+     Emacs 19.)
+
+          (documentation-property 'command-line-processed
+             'variable-documentation)
+               => "t once command line has been processed"
+          (symbol-plist 'command-line-processed)
+               => (variable-documentation 188902)
+
+ - Function: documentation function &optional verbatim
+     This function returns the documentation string of FUNCTION.  It
+     reads the text from a file if necessary.  Then (unless VERBATIM is
+     non-`nil') it calls `substitute-command-keys', to return a value
+     containing the actual (current) key bindings.
+
+     The function `documentation' signals a `void-function' error if
+     FUNCTION has no function definition.  However, it is ok if the
+     function definition has no documentation string.  In that case,
+     `documentation' returns `nil'.
+
+   Here is an example of using the two functions, `documentation' and
+`documentation-property', to display the documentation strings for
+several symbols in a `*Help*' buffer.
+
+     (defun describe-symbols (pattern)
+       "Describe the XEmacs Lisp symbols matching PATTERN.
+     All symbols that have PATTERN in their name are described
+     in the `*Help*' buffer."
+       (interactive "sDescribe symbols matching: ")
+       (let ((describe-func
+              (function
+               (lambda (s)
+                 ;; Print description of symbol.
+                 (if (fboundp s)             ; It is a function.
+                     (princ
+                      (format "%s\t%s\n%s\n\n" s
+                        (if (commandp s)
+                            (let ((keys (where-is-internal s)))
+                              (if keys
+                                  (concat
+                                   "Keys: "
+                                   (mapconcat 'key-description
+                                              keys " "))
+                                "Keys: none"))
+                          "Function")
+                        (or (documentation s)
+                            "not documented"))))
+     
+                 (if (boundp s)              ; It is a variable.
+                     (princ
+                      (format "%s\t%s\n%s\n\n" s
+                        (if (user-variable-p s)
+                            "Option " "Variable")
+                        (or (documentation-property
+                              s 'variable-documentation)
+                            "not documented")))))))
+             sym-list)
+     
+         ;; Build a list of symbols that match pattern.
+         (mapatoms (function
+                    (lambda (sym)
+                      (if (string-match pattern (symbol-name sym))
+                          (setq sym-list (cons sym sym-list))))))
+     
+         ;; Display the data.
+         (with-output-to-temp-buffer "*Help*"
+           (mapcar describe-func (sort sym-list 'string<))
+           (print-help-return-message))))
+
+   The `describe-symbols' function works like `apropos', but provides
+more information.
+
+     (describe-symbols "goal")
+     
+     ---------- Buffer: *Help* ----------
+     goal-column     Option
+     *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
+     
+     set-goal-column Command: C-x C-n
+     Set the current horizontal position as a goal for C-n and C-p.
+     Those commands will move to this position in the line moved to
+     rather than trying to keep the same horizontal position.
+     With a non-`nil' argument, clears out the goal column
+     so that C-n and C-p resume vertical motion.
+     The goal column is stored in the variable `goal-column'.
+     
+     temporary-goal-column   Variable
+     Current goal column for vertical motion.
+     It is the column where point was
+     at the start of current run of vertical motion commands.
+     When the `track-eol' feature is doing its job, the value is 9999.
+     ---------- Buffer: *Help* ----------
+
+ - Function: Snarf-documentation filename
+     This function is used only during XEmacs initialization, just
+     before the runnable XEmacs is dumped.  It finds the file offsets
+     of the documentation strings stored in the file FILENAME, and
+     records them in the in-core function definitions and variable
+     property lists in place of the actual strings.  *Note Building
+     XEmacs::.
+
+     XEmacs finds the file FILENAME in the `lib-src' directory.  When
+     the dumped XEmacs is later executed, the same file is found in the
+     directory `doc-directory'.  The usual value for FILENAME is `DOC',
+     but this can be changed by modifying the variable
+     `internal-doc-file-name'.
+
+ - Variable: internal-doc-file-name
+     This variable holds the name of the file containing documentation
+     strings of built-in symbols, usually `DOC'.  The full pathname of
+     the internal doc file is `(concat doc-directory
+     internal-doc-file-name)'.
+
+ - Variable: doc-directory
+     This variable holds the name of the directory which contains the
+     "internal doc file" that contains documentation strings for
+     built-in and preloaded functions and variables.
+
+     In most cases, this is the same as `exec-directory'.  They may be
+     different when you run XEmacs from the directory where you built
+     it, without actually installing it.  See `exec-directory' in *Note
+     Help Functions::.
+
+     In older Emacs versions, `exec-directory' was used for this.
+
+ - Variable: data-directory
+     This variable holds the name of the directory in which XEmacs finds
+     certain system independent documentation and text files that come
+     with XEmacs.  In older Emacs versions, `exec-directory' was used
+     for this.
+
+
+File: lispref.info,  Node: Keys in Documentation,  Next: Describing Characters,  Prev: Accessing Documentation,  Up: Documentation
+
+Substituting Key Bindings in Documentation
+==========================================
+
+   When documentation strings refer to key sequences, they should use
+the current, actual key bindings.  They can do so using certain special
+text sequences described below.  Accessing documentation strings in the
+usual way substitutes current key binding information for these special
+sequences.  This works by calling `substitute-command-keys'.  You can
+also call that function yourself.
+
+   Here is a list of the special sequences and what they mean:
+
+`\[COMMAND]'
+     stands for a key sequence that will invoke COMMAND, or `M-x
+     COMMAND' if COMMAND has no key bindings.
+
+`\{MAPVAR}'
+     stands for a summary of the value of MAPVAR, which should be a
+     keymap.  The summary is made by `describe-bindings'.
+
+`\<MAPVAR>'
+     stands for no text itself.  It is used for a side effect: it
+     specifies MAPVAR as the keymap for any following `\[COMMAND]'
+     sequences in this documentation string.
+
+`\='
+     quotes the following character and is discarded; this `\=\=' puts
+     `\=' into the output, and `\=\[' puts `\[' into the output.
+
+   *Please note:* Each `\' must be doubled when written in a string in
+XEmacs Lisp.
+
+ - Function: substitute-command-keys string
+     This function scans STRING for the above special sequences and
+     replaces them by what they stand for, returning the result as a
+     string.  This permits display of documentation that refers
+     accurately to the user's own customized key bindings.
+
+   Here are examples of the special sequences:
+
+     (substitute-command-keys
+        "To abort recursive edit, type: \\[abort-recursive-edit]")
+     => "To abort recursive edit, type: C-]"
+     
+     (substitute-command-keys
+        "The keys that are defined for the minibuffer here are:
+       \\{minibuffer-local-must-match-map}")
+     => "The keys that are defined for the minibuffer here are:
+     
+     ?               minibuffer-completion-help
+     SPC             minibuffer-complete-word
+     TAB             minibuffer-complete
+     LFD             minibuffer-complete-and-exit
+     RET             minibuffer-complete-and-exit
+     C-g             abort-recursive-edit
+     "
+     
+     (substitute-command-keys
+        "To abort a recursive edit from the minibuffer, type\
+     \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
+     => "To abort a recursive edit from the minibuffer, type C-g."
+     
+     (substitute-command-keys
+       "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
+     \(made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
+     Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
+     as the keymap for future \\=\\[COMMAND] substrings.
+     \\=\\= quotes the following character and is discarded;
+     thus, \\=\\=\\=\\= puts \\=\\= into the output,
+     and \\=\\=\\=\\[ puts \\=\\[ into the output.")
+     => "Substrings of the form \{MAPVAR} are replaced by summaries
+     (made by `describe-bindings') of the value of MAPVAR, taken as a keymap.
+     Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
+     as the keymap for future \[COMMAND] substrings.
+     \= quotes the following character and is discarded;
+     thus, \=\= puts \= into the output,
+     and \=\[ puts \[ into the output."
+
+
+File: lispref.info,  Node: Describing Characters,  Next: Help Functions,  Prev: Keys in Documentation,  Up: Documentation
+
+Describing Characters for Help Messages
+=======================================
+
+   These functions convert events, key sequences or characters to
+textual descriptions.  These descriptions are useful for including
+arbitrary text characters or key sequences in messages, because they
+convert non-printing and whitespace characters to sequences of printing
+characters.  The description of a non-whitespace printing character is
+the character itself.
+
+ - Function: key-description sequence
+     This function returns a string containing the XEmacs standard
+     notation for the input events in SEQUENCE.  The argument SEQUENCE
+     may be a string, vector or list.  *Note Events::, for more
+     information about valid events.  See also the examples for
+     `single-key-description', below.
+
+ - Function: single-key-description key
+     This function returns a string describing KEY in the standard
+     XEmacs notation for keyboard input.  A normal printing character
+     appears as itself, but a control character turns into a string
+     starting with `C-', a meta character turns into a string starting
+     with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
+     A symbol appears as the name of the symbol.  An event that is a
+     list appears as the name of the symbol in the CAR of the list.
+
+          (single-key-description ?\C-x)
+               => "C-x"
+          (key-description "\C-x \M-y \n \t \r \f123")
+               => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
+          (single-key-description 'kp-next)
+               => "kp-next"
+          (single-key-description '(shift button1))
+               => "Sh-button1"
+
+ - Function: text-char-description character
+     This function returns a string describing CHARACTER in the
+     standard XEmacs notation for characters that appear in text--like
+     `single-key-description', except that control characters are
+     represented with a leading caret (which is how control characters
+     in XEmacs buffers are usually displayed).
+
+          (text-char-description ?\C-c)
+               => "^C"
+          (text-char-description ?\M-m)
+               => "M-m"
+          (text-char-description ?\C-\M-m)
+               => "M-^M"
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-23'
Index: ././info/lispref.info-23
--- ././info/lispref.info-23	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-23	Thu May 17 23:26:54 2001
@@ -0,0 +1,1138 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Help Functions,  Next: Obsoleteness,  Prev: Describing Characters,  Up: Documentation
+
+Help Functions
+==============
+
+   XEmacs provides a variety of on-line help functions, all accessible
+to the user as subcommands of the prefix `C-h', or on some keyboards,
+`help'.  For more information about them, see *Note Help: (emacs)Help.
+Here we describe some program-level interfaces to the same information.
+
+ - Command: apropos regexp &optional do-all predicate
+     This function finds all symbols whose names contain a match for the
+     regular expression REGEXP, and returns a list of them (*note
+     Regular Expressions::).  It also displays the symbols in a buffer
+     named `*Help*', each with a one-line description.
+
+     If DO-ALL is non-`nil', then `apropos' also shows key bindings for
+     the functions that are found.
+
+     If PREDICATE is non-`nil', it should be a function to be called on
+     each symbol that has matched REGEXP.  Only symbols for which
+     PREDICATE returns a non-`nil' value are listed or displayed.
+
+     In the first of the following examples, `apropos' finds all the
+     symbols with names containing `exec'.  In the second example, it
+     finds and returns only those symbols that are also commands.  (We
+     don't show the output that results in the `*Help*' buffer.)
+
+          (apropos "exec")
+               => (Buffer-menu-execute command-execute exec-directory
+              exec-path execute-extended-command execute-kbd-macro
+              executing-kbd-macro executing-macro)
+          
+          (apropos "exec" nil 'commandp)
+               => (Buffer-menu-execute execute-extended-command)
+
+     `apropos' is used by various user-level commands, such as `C-h a'
+     (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
+     (`command-apropos'), which does an apropos over only those
+     functions which are user commands.  `command-apropos' calls
+     `apropos', specifying a PREDICATE to restrict the output to
+     symbols that are commands.  The call to `apropos' looks like this:
+
+          (apropos string t 'commandp)
+
+ - Variable: help-map
+     The value of this variable is a local keymap for characters
+     following the Help key, `C-h'.
+
+ - Prefix Command: help-command
+     This symbol is not a function; its function definition is actually
+     the keymap known as `help-map'.  It is defined in `help.el' as
+     follows:
+
+          (define-key global-map "\C-h" 'help-command)
+          (fset 'help-command help-map)
+
+ - Function: print-help-return-message &optional function
+     This function builds a string that explains how to restore the
+     previous state of the windows after a help command.  After
+     building the message, it applies FUNCTION to it if FUNCTION is
+     non-`nil'.  Otherwise it calls `message' to display it in the echo
+     area.
+
+     This function expects to be called inside a
+     `with-output-to-temp-buffer' special form, and expects
+     `standard-output' to have the value bound by that special form.
+     For an example of its use, see the long example in *Note Accessing
+     Documentation::.
+
+ - Variable: help-char
+     The value of this variable is the help character--the character
+     that XEmacs recognizes as meaning Help.  By default, it is the
+     character `?\^H' (ASCII 8), which is `C-h'.  When XEmacs reads this
+     character, if `help-form' is non-`nil' Lisp expression, it
+     evaluates that expression, and displays the result in a window if
+     it is a string.
+
+     `help-char' can be a character or a key description such as `help'
+     or `(meta h)'.
+
+     Usually the value of `help-form''s value is `nil'.  Then the help
+     character has no special meaning at the level of command input, and
+     it becomes part of a key sequence in the normal way.  The standard
+     key binding of `C-h' is a prefix key for several general-purpose
+     help features.
+
+     The help character is special after prefix keys, too.  If it has no
+     binding as a subcommand of the prefix key, it runs
+     `describe-prefix-bindings', which displays a list of all the
+     subcommands of the prefix key.
+
+ - Variable: help-form
+     If this variable is non-`nil', its value is a form to evaluate
+     whenever the character `help-char' is read.  If evaluating the form
+     produces a string, that string is displayed.
+
+     A command that calls `next-command-event' or `next-event' probably
+     should bind `help-form' to a non-`nil' expression while it does
+     input.  (The exception is when `C-h' is meaningful input.)
+     Evaluating this expression should result in a string that explains
+     what the input is for and how to enter it properly.
+
+     Entry to the minibuffer binds this variable to the value of
+     `minibuffer-help-form' (*note Minibuffer Misc::).
+
+ - Variable: prefix-help-command
+     This variable holds a function to print help for a prefix
+     character.  The function is called when the user types a prefix
+     key followed by the help character, and the help character has no
+     binding after that prefix.  The variable's default value is
+     `describe-prefix-bindings'.
+
+ - Command: describe-prefix-bindings
+     This function calls `describe-bindings' to display a list of all
+     the subcommands of the prefix key of the most recent key sequence.
+     The prefix described consists of all but the last event of that
+     key sequence.  (The last event is, presumably, the help character.)
+
+   The following two functions are found in the library `helper'.  They
+are for modes that want to provide help without relinquishing control,
+such as the "electric" modes.  You must load that library with
+`(require 'helper)' in order to use them.  Their names begin with
+`Helper' to distinguish them from the ordinary help functions.
+
+ - Command: Helper-describe-bindings
+     This command pops up a window displaying a help buffer containing a
+     listing of all of the key bindings from both the local and global
+     keymaps.  It works by calling `describe-bindings'.
+
+ - Command: Helper-help
+     This command provides help for the current mode.  It prompts the
+     user in the minibuffer with the message `Help (Type ? for further
+     options)', and then provides assistance in finding out what the key
+     bindings are, and what the mode is intended for.  It returns `nil'.
+
+     This can be customized by changing the map `Helper-help-map'.
+
+
+File: lispref.info,  Node: Obsoleteness,  Prev: Help Functions,  Up: Documentation
+
+Obsoleteness
+============
+
+   As you add functionality to a package, you may at times want to
+replace an older function with a new one.  To preserve compatibility
+with existing code, the older function needs to still exist; but users
+of that function should be told to use the newer one instead.  XEmacs
+Lisp lets you mark a function or variable as "obsolete", and indicate
+what should be used instead.
+
+ - Command: make-obsolete function new
+     This function indicates that FUNCTION is an obsolete function, and
+     the function NEW should be used instead.  The byte compiler will
+     issue a warning to this effect when it encounters a usage of the
+     older function, and the help system will also note this in the
+     function's documentation.  NEW can also be a string (if there is
+     not a single function with the same functionality any more), and
+     should be a descriptive statement, such as "use FOO or BAR
+     instead" or "this function is unnecessary".
+
+ - Command: make-obsolete-variable variable new
+     This is like `make-obsolete' but is for variables instead of
+     functions.
+
+ - Function: define-obsolete-function-alias oldfun newfun
+     This function combines `make-obsolete' and `define-function',
+     declaring OLDFUN to be an obsolete variant of NEWFUN and defining
+     OLDFUN as an alias for NEWFUN.
+
+ - Function: define-obsolete-variable-alias oldvar newvar
+     This is like `define-obsolete-function-alias' but for variables.
+
+   Note that you should not normally put obsoleteness information
+explicitly in a function or variable's doc string.  The obsoleteness
+information that you specify using the above functions will be displayed
+whenever the doc string is displayed, and by adding it explicitly the
+result is redundancy.
+
+   Also, if an obsolete function is substantially the same as a newer
+one but is not actually an alias, you should consider omitting the doc
+string entirely (use a null string `""' as the doc string).  That way,
+the user is told about the obsoleteness and is forced to look at the
+documentation of the new function, making it more likely that he will
+use the new function.
+
+ - Function: function-obsoleteness-doc function
+     If FUNCTION is obsolete, this function returns a string describing
+     this.  This is the message that is printed out during byte
+     compilation or in the function's documentation.  If FUNCTION is
+     not obsolete, `nil' is returned.
+
+ - Function: variable-obsoleteness-doc variable
+     This is like `function-obsoleteness-doc' but for variables.
+
+   The obsoleteness information is stored internally by putting a
+property `byte-obsolete-info' (for functions) or
+`byte-obsolete-variable' (for variables) on the symbol that specifies
+the obsolete function or variable.  For more information, see the
+implementation of `make-obsolete' and `make-obsolete-variable' in
+`lisp/bytecomp/bytecomp-runtime.el'.
+
+
+File: lispref.info,  Node: Files,  Next: Backups and Auto-Saving,  Prev: Documentation,  Up: Top
+
+Files
+*****
+
+   In XEmacs, you can find, create, view, save, and otherwise work with
+files and file directories.  This chapter describes most of the
+file-related functions of XEmacs Lisp, but a few others are described in
+*Note Buffers::, and those related to backups and auto-saving are
+described in *Note Backups and Auto-Saving::.
+
+   Many of the file functions take one or more arguments that are file
+names.  A file name is actually a string.  Most of these functions
+expand file name arguments using `expand-file-name', so that `~' is
+handled correctly, as are relative file names (including `../').  These
+functions don't recognize environment variable substitutions such as
+`$HOME'.  *Note File Name Expansion::.
+
+* Menu:
+
+* Visiting Files::           Reading files into Emacs buffers for editing.
+* Saving Buffers::           Writing changed buffers back into files.
+* Reading from Files::       Reading files into buffers without visiting.
+* Writing to Files::         Writing new files from parts of buffers.
+* File Locks::               Locking and unlocking files, to prevent
+                               simultaneous editing by two people.
+* Information about Files::  Testing existence, accessibility, size of files.
+* Changing File Attributes:: Renaming files, changing protection, etc.
+* File Names::               Decomposing and expanding file names.
+* Contents of Directories::  Getting a list of the files in a directory.
+* Create/Delete Dirs::	     Creating and Deleting Directories.
+* Magic File Names::	     Defining "magic" special handling
+			       for certain file names.
+* Partial Files::            Treating a section of a buffer as a file.
+* Format Conversion::        Conversion to and from various file formats.
+* Files and MS-DOS::         Distinguishing text and binary files on MS-DOS.
+
+
+File: lispref.info,  Node: Visiting Files,  Next: Saving Buffers,  Up: Files
+
+Visiting Files
+==============
+
+   Visiting a file means reading a file into a buffer.  Once this is
+done, we say that the buffer is "visiting" that file, and call the file
+"the visited file" of the buffer.
+
+   A file and a buffer are two different things.  A file is information
+recorded permanently in the computer (unless you delete it).  A buffer,
+on the other hand, is information inside of XEmacs that will vanish at
+the end of the editing session (or when you kill the buffer).  Usually,
+a buffer contains information that you have copied from a file; then we
+say the buffer is visiting that file.  The copy in the buffer is what
+you modify with editing commands.  Such changes to the buffer do not
+change the file; therefore, to make the changes permanent, you must
+"save" the buffer, which means copying the altered buffer contents back
+into the file.
+
+   In spite of the distinction between files and buffers, people often
+refer to a file when they mean a buffer and vice-versa.  Indeed, we say,
+"I am editing a file," rather than, "I am editing a buffer that I will
+soon save as a file of the same name."  Humans do not usually need to
+make the distinction explicit.  When dealing with a computer program,
+however, it is good to keep the distinction in mind.
+
+* Menu:
+
+* Visiting Functions::         The usual interface functions for visiting.
+* Subroutines of Visiting::    Lower-level subroutines that they use.
+
+
+File: lispref.info,  Node: Visiting Functions,  Next: Subroutines of Visiting,  Up: Visiting Files
+
+Functions for Visiting Files
+----------------------------
+
+   This section describes the functions normally used to visit files.
+For historical reasons, these functions have names starting with
+`find-' rather than `visit-'.  *Note Buffer File Name::, for functions
+and variables that access the visited file name of a buffer or that
+find an existing buffer by its visited file name.
+
+   In a Lisp program, if you want to look at the contents of a file but
+not alter it, the fastest way is to use `insert-file-contents' in a
+temporary buffer.  Visiting the file is not necessary and takes longer.
+*Note Reading from Files::.
+
+ - Command: find-file filename
+     This command selects a buffer visiting the file FILENAME, using an
+     existing buffer if there is one, and otherwise creating a new
+     buffer and reading the file into it.  It also returns that buffer.
+
+     The body of the `find-file' function is very simple and looks like
+     this:
+
+          (switch-to-buffer (find-file-noselect filename))
+
+     (See `switch-to-buffer' in *Note Displaying Buffers::.)
+
+     When `find-file' is called interactively, it prompts for FILENAME
+     in the minibuffer.
+
+ - Function: find-file-noselect filename &optional nowarn
+     This function is the guts of all the file-visiting functions.  It
+     finds or creates a buffer visiting the file FILENAME, and returns
+     it.  It uses an existing buffer if there is one, and otherwise
+     creates a new buffer and reads the file into it.  You may make the
+     buffer current or display it in a window if you wish, but this
+     function does not do so.
+
+     When `find-file-noselect' uses an existing buffer, it first
+     verifies that the file has not changed since it was last visited or
+     saved in that buffer.  If the file has changed, then this function
+     asks the user whether to reread the changed file.  If the user says
+     `yes', any changes previously made in the buffer are lost.
+
+     If `find-file-noselect' needs to create a buffer, and there is no
+     file named FILENAME, it displays the message `New file' in the
+     echo area, and leaves the buffer empty.
+
+     If NOWARN is non-`nil', various warnings that XEmacs normally
+     gives (e.g. if another buffer is already visiting FILENAME but
+     FILENAME has been removed from disk since that buffer was created)
+     are suppressed.
+
+     The `find-file-noselect' function calls `after-find-file' after
+     reading the file (*note Subroutines of Visiting::).  That function
+     sets the buffer major mode, parses local variables, warns the user
+     if there exists an auto-save file more recent than the file just
+     visited, and finishes by running the functions in
+     `find-file-hooks'.
+
+     The `find-file-noselect' function returns the buffer that is
+     visiting the file FILENAME.
+
+          (find-file-noselect "/etc/fstab")
+               => #<buffer fstab>
+
+ - Command: find-file-other-window filename
+     This command selects a buffer visiting the file FILENAME, but does
+     so in a window other than the selected window.  It may use another
+     existing window or split a window; see *Note Displaying Buffers::.
+
+     When this command is called interactively, it prompts for FILENAME.
+
+ - Command: find-file-read-only filename
+     This command selects a buffer visiting the file FILENAME, like
+     `find-file', but it marks the buffer as read-only.  *Note Read
+     Only Buffers::, for related functions and variables.
+
+     When this command is called interactively, it prompts for FILENAME.
+
+ - Command: view-file filename &optional other-window-p
+     This command visits FILENAME in View mode, and displays it in a
+     recursive edit, returning to the previous buffer when done.  View
+     mode is a mode that allows you to skim rapidly through the file
+     but does not let you modify it.  Entering View mode runs the
+     normal hook `view-mode-hook'.  *Note Hooks::.
+
+     When `view-file' is called interactively, it prompts for FILENAME.
+
+     With non-`nil' prefix arg OTHER-WINDOW-P, visit FILENAME in
+     another window.
+
+ - Variable: find-file-hooks
+     The value of this variable is a list of functions to be called
+     after a file is visited.  The file's local-variables specification
+     (if any) will have been processed before the hooks are run.  The
+     buffer visiting the file is current when the hook functions are
+     run.
+
+     This variable works just like a normal hook, but we think that
+     renaming it would not be advisable.
+
+ - Variable: find-file-not-found-hooks
+     The value of this variable is a list of functions to be called when
+     `find-file' or `find-file-noselect' is passed a nonexistent file
+     name.  `find-file-noselect' calls these functions as soon as it
+     detects a nonexistent file.  It calls them in the order of the
+     list, until one of them returns non-`nil'.  `buffer-file-name' is
+     already set up.
+
+     This is not a normal hook because the values of the functions are
+     used and they may not all be called.
+
+
+File: lispref.info,  Node: Subroutines of Visiting,  Prev: Visiting Functions,  Up: Visiting Files
+
+Subroutines of Visiting
+-----------------------
+
+   The `find-file-noselect' function uses the `create-file-buffer' and
+`after-find-file' functions as subroutines.  Sometimes it is useful to
+call them directly.
+
+ - Function: create-file-buffer filename
+     This function creates a suitably named buffer for visiting
+     FILENAME, and returns it.  It uses FILENAME (sans directory) as
+     the name if that name is free; otherwise, it appends a string such
+     as `<2>' to get an unused name.  See also *Note Creating Buffers::.
+
+     *Please note:* `create-file-buffer' does _not_ associate the new
+     buffer with a file and does not select the buffer.  It also does
+     not use the default major mode.
+
+          (create-file-buffer "foo")
+               => #<buffer foo>
+          (create-file-buffer "foo")
+               => #<buffer foo<2>>
+          (create-file-buffer "foo")
+               => #<buffer foo<3>>
+
+     This function is used by `find-file-noselect'.  It uses
+     `generate-new-buffer' (*note Creating Buffers::).
+
+ - Function: after-find-file &optional error warn noauto
+     This function sets the buffer major mode, and parses local
+     variables (*note Auto Major Mode::).  It is called by
+     `find-file-noselect' and by the default revert function (*note
+     Reverting::).
+
+     If reading the file got an error because the file does not exist,
+     but its directory does exist, the caller should pass a non-`nil'
+     value for ERROR.  In that case, `after-find-file' issues a warning:
+     `(New File)'.  For more serious errors, the caller should usually
+     not call `after-find-file'.
+
+     If WARN is non-`nil', then this function issues a warning if an
+     auto-save file exists and is more recent than the visited file.
+
+     If NOAUTO is non-`nil', then this function does not turn on
+     auto-save mode; otherwise, it does.
+
+     The last thing `after-find-file' does is call all the functions in
+     `find-file-hooks'.
+
+
+File: lispref.info,  Node: Saving Buffers,  Next: Reading from Files,  Prev: Visiting Files,  Up: Files
+
+Saving Buffers
+==============
+
+   When you edit a file in XEmacs, you are actually working on a buffer
+that is visiting that file--that is, the contents of the file are
+copied into the buffer and the copy is what you edit.  Changes to the
+buffer do not change the file until you "save" the buffer, which means
+copying the contents of the buffer into the file.
+
+ - Command: save-buffer &optional backup-option
+     This function saves the contents of the current buffer in its
+     visited file if the buffer has been modified since it was last
+     visited or saved.  Otherwise it does nothing.
+
+     `save-buffer' is responsible for making backup files.  Normally,
+     BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
+     if this is the first save since visiting the file.  Other values
+     for BACKUP-OPTION request the making of backup files in other
+     circumstances:
+
+        * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
+          `save-buffer' function marks this version of the file to be
+          backed up when the buffer is next saved.
+
+        * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
+          `save-buffer' function unconditionally backs up the previous
+          version of the file before saving it.
+
+ - Command: save-some-buffers &optional save-silently-p exiting
+     This command saves some modified file-visiting buffers.  Normally
+     it asks the user about each buffer.  But if SAVE-SILENTLY-P is
+     non-`nil', it saves all the file-visiting buffers without querying
+     the user.
+
+     The optional EXITING argument, if non-`nil', requests this
+     function to offer also to save certain other buffers that are not
+     visiting files.  These are buffers that have a non-`nil' local
+     value of `buffer-offer-save'.  (A user who says yes to saving one
+     of these is asked to specify a file name to use.)  The
+     `save-buffers-kill-emacs' function passes a non-`nil' value for
+     this argument.
+
+ - Variable: buffer-offer-save
+     When this variable is non-`nil' in a buffer, XEmacs offers to save
+     the buffer on exit even if the buffer is not visiting a file.  The
+     variable is automatically local in all buffers.  Normally, Mail
+     mode (used for editing outgoing mail) sets this to `t'.
+
+ - Command: write-file filename
+     This function writes the current buffer into file FILENAME, makes
+     the buffer visit that file, and marks it not modified.  Then it
+     renames the buffer based on FILENAME, appending a string like `<2>'
+     if necessary to make a unique buffer name.  It does most of this
+     work by calling `set-visited-file-name' and `save-buffer'.
+
+ - Variable: write-file-hooks
+     The value of this variable is a list of functions to be called
+     before writing out a buffer to its visited file.  If one of them
+     returns non-`nil', the file is considered already written and the
+     rest of the functions are not called, nor is the usual code for
+     writing the file executed.
+
+     If a function in `write-file-hooks' returns non-`nil', it is
+     responsible for making a backup file (if that is appropriate).  To
+     do so, execute the following code:
+
+          (or buffer-backed-up (backup-buffer))
+
+     You might wish to save the file modes value returned by
+     `backup-buffer' and use that to set the mode bits of the file that
+     you write.  This is what `save-buffer' normally does.
+
+     Even though this is not a normal hook, you can use `add-hook' and
+     `remove-hook' to manipulate the list.  *Note Hooks::.
+
+ - Variable: local-write-file-hooks
+     This works just like `write-file-hooks', but it is intended to be
+     made local to particular buffers.  It's not a good idea to make
+     `write-file-hooks' local to a buffer--use this variable instead.
+
+     The variable is marked as a permanent local, so that changing the
+     major mode does not alter a buffer-local value.  This is
+     convenient for packages that read "file" contents in special ways,
+     and set up hooks to save the data in a corresponding way.
+
+ - Variable: write-contents-hooks
+     This works just like `write-file-hooks', but it is intended for
+     hooks that pertain to the contents of the file, as opposed to
+     hooks that pertain to where the file came from.  Such hooks are
+     usually set up by major modes, as buffer-local bindings for this
+     variable.  Switching to a new major mode always resets this
+     variable.
+
+ - Variable: after-save-hook
+     This normal hook runs after a buffer has been saved in its visited
+     file.
+
+ - Variable: file-precious-flag
+     If this variable is non-`nil', then `save-buffer' protects against
+     I/O errors while saving by writing the new file to a temporary
+     name instead of the name it is supposed to have, and then renaming
+     it to the intended name after it is clear there are no errors.
+     This procedure prevents problems such as a lack of disk space from
+     resulting in an invalid file.
+
+     As a side effect, backups are necessarily made by copying.  *Note
+     Rename or Copy::.  Yet, at the same time, saving a precious file
+     always breaks all hard links between the file you save and other
+     file names.
+
+     Some modes set this variable non-`nil' locally in particular
+     buffers.
+
+ - User Option: require-final-newline
+     This variable determines whether files may be written out that do
+     _not_ end with a newline.  If the value of the variable is `t',
+     then `save-buffer' silently adds a newline at the end of the file
+     whenever the buffer being saved does not already end in one.  If
+     the value of the variable is non-`nil', but not `t', then
+     `save-buffer' asks the user whether to add a newline each time the
+     case arises.
+
+     If the value of the variable is `nil', then `save-buffer' doesn't
+     add newlines at all.  `nil' is the default value, but a few major
+     modes set it to `t' in particular buffers.
+
+
+File: lispref.info,  Node: Reading from Files,  Next: Writing to Files,  Prev: Saving Buffers,  Up: Files
+
+Reading from Files
+==================
+
+   You can copy a file from the disk and insert it into a buffer using
+the `insert-file-contents' function.  Don't use the user-level command
+`insert-file' in a Lisp program, as that sets the mark.
+
+ - Function: insert-file-contents filename &optional visit start end
+          replace
+     This function inserts the contents of file FILENAME into the
+     current buffer after point.  It returns a list of the absolute
+     file name and the length of the data inserted.  An error is
+     signaled if FILENAME is not the name of a file that can be read.
+
+     The function `insert-file-contents' checks the file contents
+     against the defined file formats, and converts the file contents if
+     appropriate.  *Note Format Conversion::.  It also calls the
+     functions in the list `after-insert-file-functions'; see *Note
+     Saving Properties::.
+
+     If VISIT is non-`nil', this function additionally marks the buffer
+     as unmodified and sets up various fields in the buffer so that it
+     is visiting the file FILENAME: these include the buffer's visited
+     file name and its last save file modtime.  This feature is used by
+     `find-file-noselect' and you probably should not use it yourself.
+
+     If START and END are non-`nil', they should be integers specifying
+     the portion of the file to insert.  In this case, VISIT must be
+     `nil'.  For example,
+
+          (insert-file-contents filename nil 0 500)
+
+     inserts the first 500 characters of a file.
+
+     If the argument REPLACE is non-`nil', it means to replace the
+     contents of the buffer (actually, just the accessible portion)
+     with the contents of the file.  This is better than simply
+     deleting the buffer contents and inserting the whole file, because
+     (1) it preserves some marker positions and (2) it puts less data
+     in the undo list.
+
+   If you want to pass a file name to another process so that another
+program can read the file, use the function `file-local-copy'; see
+*Note Magic File Names::.
+
+
+File: lispref.info,  Node: Writing to Files,  Next: File Locks,  Prev: Reading from Files,  Up: Files
+
+Writing to Files
+================
+
+   You can write the contents of a buffer, or part of a buffer, directly
+to a file on disk using the `append-to-file' and `write-region'
+functions.  Don't use these functions to write to files that are being
+visited; that could cause confusion in the mechanisms for visiting.
+
+ - Command: append-to-file start end filename
+     This function appends the contents of the region delimited by
+     START and END in the current buffer to the end of file FILENAME.
+     If that file does not exist, it is created.  If that file exists
+     it is overwritten.  This function returns `nil'.
+
+     An error is signaled if FILENAME specifies a nonwritable file, or
+     a nonexistent file in a directory where files cannot be created.
+
+ - Command: write-region start end filename &optional append visit
+     This function writes the region delimited by START and END in the
+     current buffer into the file specified by FILENAME.
+
+     If START is a string, then `write-region' writes or appends that
+     string, rather than text from the buffer.
+
+     If APPEND is non-`nil', then the specified text is appended to the
+     existing file contents (if any).
+
+     If VISIT is `t', then XEmacs establishes an association between
+     the buffer and the file: the buffer is then visiting that file.
+     It also sets the last file modification time for the current
+     buffer to FILENAME's modtime, and marks the buffer as not
+     modified.  This feature is used by `save-buffer', but you probably
+     should not use it yourself.
+
+     If VISIT is a string, it specifies the file name to visit.  This
+     way, you can write the data to one file (FILENAME) while recording
+     the buffer as visiting another file (VISIT).  The argument VISIT
+     is used in the echo area message and also for file locking; VISIT
+     is stored in `buffer-file-name'.  This feature is used to
+     implement `file-precious-flag'; don't use it yourself unless you
+     really know what you're doing.
+
+     The function `write-region' converts the data which it writes to
+     the appropriate file formats specified by `buffer-file-format'.
+     *Note Format Conversion::.  It also calls the functions in the list
+     `write-region-annotate-functions'; see *Note Saving Properties::.
+
+     Normally, `write-region' displays a message `Wrote file FILENAME'
+     in the echo area.  If VISIT is neither `t' nor `nil' nor a string,
+     then this message is inhibited.  This feature is useful for
+     programs that use files for internal purposes, files that the user
+     does not need to know about.
+
+
+File: lispref.info,  Node: File Locks,  Next: Information about Files,  Prev: Writing to Files,  Up: Files
+
+File Locks
+==========
+
+   When two users edit the same file at the same time, they are likely
+to interfere with each other.  XEmacs tries to prevent this situation
+from arising by recording a "file lock" when a file is being modified.
+XEmacs can then detect the first attempt to modify a buffer visiting a
+file that is locked by another XEmacs process, and ask the user what to
+do.
+
+   File locks do not work properly when multiple machines can share
+file systems, such as with NFS.  Perhaps a better file locking system
+will be implemented in the future.  When file locks do not work, it is
+possible for two users to make changes simultaneously, but XEmacs can
+still warn the user who saves second.  Also, the detection of
+modification of a buffer visiting a file changed on disk catches some
+cases of simultaneous editing; see *Note Modification Time::.
+
+ - Function: file-locked-p &optional filename
+     This function returns `nil' if the file FILENAME is not locked by
+     this XEmacs process.  It returns `t' if it is locked by this
+     XEmacs, and it returns the name of the user who has locked it if it
+     is locked by someone else.
+
+          (file-locked-p "foo")
+               => nil
+
+ - Function: lock-buffer &optional filename
+     This function locks the file FILENAME, if the current buffer is
+     modified.  The argument FILENAME defaults to the current buffer's
+     visited file.  Nothing is done if the current buffer is not
+     visiting a file, or is not modified.
+
+ - Function: unlock-buffer
+     This function unlocks the file being visited in the current buffer,
+     if the buffer is modified.  If the buffer is not modified, then
+     the file should not be locked, so this function does nothing.  It
+     also does nothing if the current buffer is not visiting a file.
+
+ - Function: ask-user-about-lock filename other-user
+     This function is called when the user tries to modify FILENAME,
+     but it is locked by another user named OTHER-USER.  The value it
+     returns determines what happens next:
+
+        * A value of `t' says to grab the lock on the file.  Then this
+          user may edit the file and OTHER-USER loses the lock.
+
+        * A value of `nil' says to ignore the lock and let this user
+          edit the file anyway.
+
+        * This function may instead signal a `file-locked' error, in
+          which case the change that the user was about to make does
+          not take place.
+
+          The error message for this error looks like this:
+
+               error--> File is locked: FILENAME OTHER-USER
+
+          where FILENAME is the name of the file and OTHER-USER is the
+          name of the user who has locked the file.
+
+     The default definition of this function asks the user to choose
+     what to do.  If you wish, you can replace the `ask-user-about-lock'
+     function with your own version that decides in another way.  The
+     code for its usual definition is in `userlock.el'.
+
+
+File: lispref.info,  Node: Information about Files,  Next: Changing File Attributes,  Prev: File Locks,  Up: Files
+
+Information about Files
+=======================
+
+   The functions described in this section all operate on strings that
+designate file names.  All the functions have names that begin with the
+word `file'.  These functions all return information about actual files
+or directories, so their arguments must all exist as actual files or
+directories unless otherwise noted.
+
+* Menu:
+
+* Testing Accessibility::   Is a given file readable?  Writable?
+* Kinds of Files::          Is it a directory?  A symbolic link?
+* Truenames::		    Eliminating symbolic links from a file name.
+* File Attributes::         How large is it?  Any other names?  Etc.
+
+
+File: lispref.info,  Node: Testing Accessibility,  Next: Kinds of Files,  Up: Information about Files
+
+Testing Accessibility
+---------------------
+
+   These functions test for permission to access a file in specific
+ways.
+
+ - Function: file-exists-p filename
+     This function returns `t' if a file named FILENAME appears to
+     exist.  This does not mean you can necessarily read the file, only
+     that you can find out its attributes.  (On Unix, this is true if
+     the file exists and you have execute permission on the containing
+     directories, regardless of the protection of the file itself.)
+
+     If the file does not exist, or if fascist access control policies
+     prevent you from finding the attributes of the file, this function
+     returns `nil'.
+
+ - Function: file-readable-p filename
+     This function returns `t' if a file named FILENAME exists and you
+     can read it.  It returns `nil' otherwise.
+
+          (file-readable-p "files.texi")
+               => t
+          (file-exists-p "/usr/spool/mqueue")
+               => t
+          (file-readable-p "/usr/spool/mqueue")
+               => nil
+
+ - Function: file-executable-p filename
+     This function returns `t' if a file named FILENAME exists and you
+     can execute it.  It returns `nil' otherwise.  If the file is a
+     directory, execute permission means you can check the existence and
+     attributes of files inside the directory, and open those files if
+     their modes permit.
+
+ - Function: file-writable-p filename
+     This function returns `t' if the file FILENAME can be written or
+     created by you, and `nil' otherwise.  A file is writable if the
+     file exists and you can write it.  It is creatable if it does not
+     exist, but the specified directory does exist and you can write in
+     that directory.
+
+     In the third example below, `foo' is not writable because the
+     parent directory does not exist, even though the user could create
+     such a directory.
+
+          (file-writable-p "~/foo")
+               => t
+          (file-writable-p "/foo")
+               => nil
+          (file-writable-p "~/no-such-dir/foo")
+               => nil
+
+ - Function: file-accessible-directory-p dirname
+     This function returns `t' if you have permission to open existing
+     files in the directory whose name as a file is DIRNAME; otherwise
+     (or if there is no such directory), it returns `nil'.  The value
+     of DIRNAME may be either a directory name or the file name of a
+     directory.
+
+     Example: after the following,
+
+          (file-accessible-directory-p "/foo")
+               => nil
+
+     we can deduce that any attempt to read a file in `/foo/' will give
+     an error.
+
+ - Function: file-ownership-preserved-p filename
+     This function returns `t' if deleting the file FILENAME and then
+     creating it anew would keep the file's owner unchanged.
+
+ - Function: file-newer-than-file-p filename1 filename2
+     This function returns `t' if the file FILENAME1 is newer than file
+     FILENAME2.  If FILENAME1 does not exist, it returns `nil'.  If
+     FILENAME2 does not exist, it returns `t'.
+
+     In the following example, assume that the file `aug-19' was written
+     on the 19th, `aug-20' was written on the 20th, and the file
+     `no-file' doesn't exist at all.
+
+          (file-newer-than-file-p "aug-19" "aug-20")
+               => nil
+          (file-newer-than-file-p "aug-20" "aug-19")
+               => t
+          (file-newer-than-file-p "aug-19" "no-file")
+               => t
+          (file-newer-than-file-p "no-file" "aug-19")
+               => nil
+
+     You can use `file-attributes' to get a file's last modification
+     time as a list of two numbers.  *Note File Attributes::.
+
+
+File: lispref.info,  Node: Kinds of Files,  Next: Truenames,  Prev: Testing Accessibility,  Up: Information about Files
+
+Distinguishing Kinds of Files
+-----------------------------
+
+   This section describes how to distinguish various kinds of files,
+such as directories, symbolic links, and ordinary files.
+
+ - Function: file-symlink-p filename
+     If the file FILENAME is a symbolic link, the `file-symlink-p'
+     function returns the file name to which it is linked.  This may be
+     the name of a text file, a directory, or even another symbolic
+     link, or it may be a nonexistent file name.
+
+     If the file FILENAME is not a symbolic link (or there is no such
+     file), `file-symlink-p' returns `nil'.
+
+          (file-symlink-p "foo")
+               => nil
+          (file-symlink-p "sym-link")
+               => "foo"
+          (file-symlink-p "sym-link2")
+               => "sym-link"
+          (file-symlink-p "/bin")
+               => "/pub/bin"
+
+
+ - Function: file-directory-p filename
+     This function returns `t' if FILENAME is the name of an existing
+     directory, `nil' otherwise.
+
+          (file-directory-p "~rms")
+               => t
+          (file-directory-p "~rms/lewis/files.texi")
+               => nil
+          (file-directory-p "~rms/lewis/no-such-file")
+               => nil
+          (file-directory-p "$HOME")
+               => nil
+          (file-directory-p
+           (substitute-in-file-name "$HOME"))
+               => t
+
+ - Function: file-regular-p filename
+     This function returns `t' if the file FILENAME exists and is a
+     regular file (not a directory, symbolic link, named pipe,
+     terminal, or other I/O device).
+
+
+File: lispref.info,  Node: Truenames,  Next: File Attributes,  Prev: Kinds of Files,  Up: Information about Files
+
+Truenames
+---------
+
+   The "truename" of a file is the name that you get by following
+symbolic links until none remain, then expanding to get rid of `.' and
+`..' as components.  Strictly speaking, a file need not have a unique
+truename; the number of distinct truenames a file has is equal to the
+number of hard links to the file.  However, truenames are useful
+because they eliminate symbolic links as a cause of name variation.
+
+ - Function: file-truename filename &optional default
+     The function `file-truename' returns the true name of the file
+     FILENAME.  This is the name that you get by following symbolic
+     links until none remain.
+
+     If the filename is relative, DEFAULT is the directory to start
+     with.  If DEFAULT is `nil' or missing, the current buffer's value
+     of `default-directory' is used.
+
+   *Note Buffer File Name::, for related information.
+
+
+File: lispref.info,  Node: File Attributes,  Prev: Truenames,  Up: Information about Files
+
+Other Information about Files
+-----------------------------
+
+   This section describes the functions for getting detailed information
+about a file, other than its contents.  This information includes the
+mode bits that control access permission, the owner and group numbers,
+the number of names, the inode number, the size, and the times of access
+and modification.
+
+ - Function: file-modes filename
+     This function returns the mode bits of FILENAME, as an integer.
+     The mode bits are also called the file permissions, and they
+     specify access control in the usual Unix fashion.  If the
+     low-order bit is 1, then the file is executable by all users, if
+     the second-lowest-order bit is 1, then the file is writable by all
+     users, etc.
+
+     The highest value returnable is 4095 (7777 octal), meaning that
+     everyone has read, write, and execute permission, that the SUID bit
+     is set for both others and group, and that the sticky bit is set.
+
+          (file-modes "~/junk/diffs")
+               => 492               ; Decimal integer.
+          (format "%o" 492)
+               => "754"             ; Convert to octal.
+          
+          (set-file-modes "~/junk/diffs" 438)
+               => nil
+          
+          (format "%o" 438)
+               => "666"             ; Convert to octal.
+          
+          % ls -l diffs
+            -rw-rw-rw-  1 lewis 0 3063 Oct 30 16:00 diffs
+
+ - Function: file-nlinks filename
+     This functions returns the number of names (i.e., hard links) that
+     file FILENAME has.  If the file does not exist, then this function
+     returns `nil'.  Note that symbolic links have no effect on this
+     function, because they are not considered to be names of the files
+     they link to.
+
+          % ls -l foo*
+          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo
+          -rw-rw-rw-  2 rms       4 Aug 19 01:27 foo1
+          
+          (file-nlinks "foo")
+               => 2
+          (file-nlinks "doesnt-exist")
+               => nil
+
+ - Function: file-attributes filename
+     This function returns a list of attributes of file FILENAME.  If
+     the specified file cannot be opened, it returns `nil'.
+
+     The elements of the list, in order, are:
+
+       0. `t' for a directory, a string for a symbolic link (the name
+          linked to), or `nil' for a text file.
+
+       1. The number of names the file has.  Alternate names, also
+          known as hard links, can be created by using the
+          `add-name-to-file' function (*note Changing File
+          Attributes::).
+
+       2. The file's UID.
+
+       3. The file's GID.
+
+       4. The time of last access, as a list of two integers.  The
+          first integer has the high-order 16 bits of time, the second
+          has the low 16 bits.  (This is similar to the value of
+          `current-time'; see *Note Time of Day::.)
+
+       5. The time of last modification as a list of two integers (as
+          above).
+
+       6. The time of last status change as a list of two integers (as
+          above).
+
+       7. The size of the file in bytes.
+
+       8. The file's modes, as a string of ten letters or dashes, as in
+          `ls -l'.
+
+       9. `t' if the file's GID would change if file were deleted and
+          recreated; `nil' otherwise.
+
+      10. The file's inode number.
+
+      11. The file system number of the file system that the file is
+          in.  This element and the file's inode number together give
+          enough information to distinguish any two files on the
+          system--no two files can have the same values for both of
+          these numbers.
+
+     For example, here are the file attributes for `files.texi':
+
+          (file-attributes "files.texi")
+               =>  (nil
+                    1
+                    2235
+                    75
+                    (8489 20284)
+                    (8489 20284)
+                    (8489 20285)
+                    14906
+                    "-rw-rw-rw-"
+                    nil
+                    129500
+                    -32252)
+
+     and here is how the result is interpreted:
+
+    `nil'
+          is neither a directory nor a symbolic link.
+
+    `1'
+          has only one name (the name `files.texi' in the current
+          default directory).
+
+    `2235'
+          is owned by the user with UID 2235.
+
+    `75'
+          is in the group with GID 75.
+
+    `(8489 20284)'
+          was last accessed on Aug 19 00:09. Use `format-time-string' to
+          ! convert this number into a time string.  *Note Time
+          Conversion::.
+
+    `(8489 20284)'
+          was last modified on Aug 19 00:09.
+
+    `(8489 20285)'
+          last had its inode changed on Aug 19 00:09.
+
+    `14906'
+          is 14906 characters long.
+
+    `"-rw-rw-rw-"'
+          has a mode of read and write access for the owner, group, and
+          world.
+
+    `nil'
+          would retain the same GID if it were recreated.
+
+    `129500'
+          has an inode number of 129500.
+
+    `-32252'
+          is on file system number -32252.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-24'
Index: ././info/lispref.info-24
--- ././info/lispref.info-24	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-24	Thu May 17 23:26:54 2001
@@ -0,0 +1,1228 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Changing File Attributes,  Next: File Names,  Prev: Information about Files,  Up: Files
+
+Changing File Names and Attributes
+==================================
+
+   The functions in this section rename, copy, delete, link, and set the
+modes of files.
+
+   In the functions that have arguments NEWNAME and
+OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
+the actions taken depend on the value of OK-IF-ALREADY-EXISTS:
+
+   * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
+     `nil'.
+
+   * Request confirmation if OK-IF-ALREADY-EXISTS is a number.  This is
+     what happens when the function is invoked interactively.
+
+   * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
+     is any other value.
+
+ - Command: add-name-to-file filename newname &optional
+          ok-if-already-exists
+     This function gives the file named FILENAME the additional name
+     NEWNAME.  This means that NEWNAME becomes a new "hard link" to
+     FILENAME.  Both these arguments must be strings.
+
+     In the first part of the following example, we list two files,
+     `foo' and `foo3'.
+
+          % ls -l fo*
+          -rw-rw-rw-  1 rms       29 Aug 18 20:32 foo
+          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+
+     Then we evaluate the form `(add-name-to-file "~/lewis/foo"
+     "~/lewis/foo2")'.  Again we list the files.  This shows two names,
+     `foo' and `foo2'.
+
+          (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
+               => nil
+          
+          % ls -l fo*
+          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo
+          -rw-rw-rw-  2 rms       29 Aug 18 20:32 foo2
+          -rw-rw-rw-  1 rms       24 Aug 18 20:31 foo3
+
+     Finally, we evaluate the following:
+
+          (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
+
+     and list the files again.  Now there are three names for one file:
+     `foo', `foo2', and `foo3'.  The old contents of `foo3' are lost.
+
+          (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+               => nil
+          
+          % ls -l fo*
+          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo
+          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo2
+          -rw-rw-rw-  3 rms       29 Aug 18 20:32 foo3
+
+     This function is meaningless on non-Unix systems, where multiple
+     names for one file are not allowed.
+
+     See also `file-nlinks' in *Note File Attributes::.
+
+ - Command: rename-file filename newname &optional ok-if-already-exists
+     This command renames the file FILENAME as NEWNAME.
+
+     If FILENAME has additional names aside from FILENAME, it continues
+     to have those names.  In fact, adding the name NEWNAME with
+     `add-name-to-file' and then deleting FILENAME has the same effect
+     as renaming, aside from momentary intermediate states.
+
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.
+
+ - Command: copy-file filename newname &optional ok-if-already-exists
+          time
+     This command copies the file FILENAME to NEWNAME.  An error is
+     signaled if FILENAME does not exist.
+
+     If TIME is non-`nil', then this functions gives the new file the
+     same last-modified time that the old one has.  (This works on only
+     some operating systems.)
+
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.
+
+ - Command: delete-file filename
+     This command deletes the file FILENAME, like the shell command `rm
+     FILENAME'.  If the file has multiple names, it continues to exist
+     under the other names.
+
+     A suitable kind of `file-error' error is signaled if the file does
+     not exist, or is not deletable.  (On Unix, a file is deletable if
+     its directory is writable.)
+
+     See also `delete-directory' in *Note Create/Delete Dirs::.
+
+ - Command: make-symbolic-link filename newname &optional
+          ok-if-already-exists
+     This command makes a symbolic link to FILENAME, named NEWNAME.
+     This is like the shell command `ln -s FILENAME NEWNAME'.
+
+     In an interactive call, this function prompts for FILENAME and
+     NEWNAME in the minibuffer; also, it requests confirmation if
+     NEWNAME already exists.
+
+ - Function: set-file-modes filename mode
+     This function sets mode bits of FILENAME to MODE (which must be an
+     integer).  Only the low 12 bits of MODE are used.
+
+ - Function: set-default-file-modes mode
+     This function sets the default file protection for new files
+     created by XEmacs and its subprocesses.  Every file created with
+     XEmacs initially has this protection.  On Unix, the default
+     protection is the bitwise complement of the "umask" value.
+
+     The argument MODE must be an integer.  Only the low 9 bits of MODE
+     are used.
+
+     Saving a modified version of an existing file does not count as
+     creating the file; it does not change the file's mode, and does
+     not use the default file protection.
+
+ - Function: default-file-modes
+     This function returns the current default protection value.
+
+   On MS-DOS, there is no such thing as an "executable" file mode bit.
+So Emacs considers a file executable if its name ends in `.com', `.bat'
+or `.exe'.  This is reflected in the values returned by `file-modes'
+and `file-attributes'.
+
+
+File: lispref.info,  Node: File Names,  Next: Contents of Directories,  Prev: Changing File Attributes,  Up: Files
+
+File Names
+==========
+
+   Files are generally referred to by their names, in XEmacs as
+elsewhere.  File names in XEmacs are represented as strings.  The
+functions that operate on a file all expect a file name argument.
+
+   In addition to operating on files themselves, XEmacs Lisp programs
+often need to operate on the names; i.e., to take them apart and to use
+part of a name to construct related file names.  This section describes
+how to manipulate file names.
+
+   The functions in this section do not actually access files, so they
+can operate on file names that do not refer to an existing file or
+directory.
+
+   On MS-DOS, these functions understand MS-DOS file-name syntax as
+well as Unix syntax. This is so that all the standard Lisp libraries
+can specify file names in Unix syntax and work properly on all systems
+without change.  Similarly for other operating systems.
+
+* Menu:
+
+* File Name Components::  The directory part of a file name, and the rest.
+* Directory Names::       A directory's name as a directory
+                            is different from its name as a file.
+* Relative File Names::   Some file names are relative to a current directory.
+* File Name Expansion::   Converting relative file names to absolute ones.
+* Unique File Names::     Generating names for temporary files.
+* File Name Completion::  Finding the completions for a given file name.
+* User Name Completion::  Finding the completions for a given user name.
+
+
+File: lispref.info,  Node: File Name Components,  Next: Directory Names,  Up: File Names
+
+File Name Components
+--------------------
+
+   The operating system groups files into directories.  To specify a
+file, you must specify the directory and the file's name within that
+directory.  Therefore, XEmacs considers a file name as having two main
+parts: the "directory name" part, and the "nondirectory" part (or "file
+name within the directory").  Either part may be empty.  Concatenating
+these two parts reproduces the original file name.
+
+   On Unix, the directory part is everything up to and including the
+last slash; the nondirectory part is the rest.
+
+   For some purposes, the nondirectory part is further subdivided into
+the name proper and the "version number".  On Unix, only backup files
+have version numbers in their names.
+
+ - Function: file-name-directory filename
+     This function returns the directory part of FILENAME (or `nil' if
+     FILENAME does not include a directory part).  On Unix, the
+     function returns a string ending in a slash.
+
+          (file-name-directory "lewis/foo")  ; Unix example
+               => "lewis/"
+          (file-name-directory "foo")        ; Unix example
+               => nil
+
+ - Function: file-name-nondirectory filename
+     This function returns the nondirectory part of FILENAME.
+
+          (file-name-nondirectory "lewis/foo")
+               => "foo"
+          (file-name-nondirectory "foo")
+               => "foo"
+
+ - Function: file-name-sans-versions filename &optional
+          keep-backup-version
+     This function returns FILENAME without any file version numbers,
+     backup version numbers, or trailing tildes.
+
+     If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
+     version numbers, only true file version numbers.
+
+          (file-name-sans-versions "~rms/foo.~1~")
+               => "~rms/foo"
+          (file-name-sans-versions "~rms/foo~")
+               => "~rms/foo"
+          (file-name-sans-versions "~rms/foo")
+               => "~rms/foo"
+
+ - Function: file-name-sans-extension filename
+     This function returns FILENAME minus its "extension," if any.  The
+     extension, in a file name, is the part that starts with the last
+     `.' in the last name component.  For example,
+
+          (file-name-sans-extension "foo.lose.c")
+               => "foo.lose"
+          (file-name-sans-extension "big.hack/foo")
+               => "big.hack/foo"
+
+
+File: lispref.info,  Node: Directory Names,  Next: Relative File Names,  Prev: File Name Components,  Up: File Names
+
+Directory Names
+---------------
+
+   A "directory name" is the name of a directory.  A directory is a
+kind of file, and it has a file name, which is related to the directory
+name but not identical to it.  (This is not quite the same as the usual
+Unix terminology.)  These two different names for the same entity are
+related by a syntactic transformation.  On Unix, this is simple: a
+directory name ends in a slash, whereas the directory's name as a file
+lacks that slash.
+
+   The difference between a directory name and its name as a file is
+subtle but crucial.  When an XEmacs variable or function argument is
+described as being a directory name, a file name of a directory is not
+acceptable.
+
+   The following two functions convert between directory names and file
+names.  They do nothing special with environment variable substitutions
+such as `$HOME', and the constructs `~', and `..'.
+
+ - Function: file-name-as-directory filename
+     This function returns a string representing FILENAME in a form
+     that the operating system will interpret as the name of a
+     directory.  In Unix, this means appending a slash to the string.
+
+          (file-name-as-directory "~rms/lewis")
+               => "~rms/lewis/"
+
+ - Function: directory-file-name dirname
+     This function returns a string representing DIRNAME in a form that
+     the operating system will interpret as the name of a file.  On
+     Unix, this means removing a final slash from the string.
+
+          (directory-file-name "~lewis/")
+               => "~lewis"
+
+   Directory name abbreviations are useful for directories that are
+normally accessed through symbolic links.  Sometimes the users recognize
+primarily the link's name as "the name" of the directory, and find it
+annoying to see the directory's "real" name.  If you define the link
+name as an abbreviation for the "real" name, XEmacs shows users the
+abbreviation instead.
+
+   If you wish to convert a directory name to its abbreviation, use this
+function:
+
+ - Function: abbreviate-file-name filename &optional hack-homedir
+     This function applies abbreviations from `directory-abbrev-alist'
+     to its argument, and substitutes `~' for the user's home directory.
+
+     If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
+     the user's home directory.
+
+
+ - Variable: directory-abbrev-alist
+     The variable `directory-abbrev-alist' contains an alist of
+     abbreviations to use for file directories.  Each element has the
+     form `(FROM . TO)', and says to replace FROM with TO when it
+     appears in a directory name.  The FROM string is actually a
+     regular expression; it should always start with `^'.  The function
+     `abbreviate-file-name' performs these substitutions.
+
+     You can set this variable in `site-init.el' to describe the
+     abbreviations appropriate for your site.
+
+     Here's an example, from a system on which file system `/home/fsf'
+     and so on are normally accessed through symbolic links named `/fsf'
+     and so on.
+
+          (("^/home/fsf" . "/fsf")
+           ("^/home/gp" . "/gp")
+           ("^/home/gd" . "/gd"))
+
+
+File: lispref.info,  Node: Relative File Names,  Next: File Name Expansion,  Prev: Directory Names,  Up: File Names
+
+Absolute and Relative File Names
+--------------------------------
+
+   All the directories in the file system form a tree starting at the
+root directory.  A file name can specify all the directory names
+starting from the root of the tree; then it is called an "absolute"
+file name.  Or it can specify the position of the file in the tree
+relative to a default directory; then it is called a "relative" file
+name.  On Unix, an absolute file name starts with a slash or a tilde
+(`~'), and a relative one does not.
+
+ - Function: file-name-absolute-p filename
+     This function returns `t' if file FILENAME is an absolute file
+     name, `nil' otherwise.
+
+          (file-name-absolute-p "~rms/foo")
+               => t
+          (file-name-absolute-p "rms/foo")
+               => nil
+          (file-name-absolute-p "/user/rms/foo")
+               => t
+
+
+File: lispref.info,  Node: File Name Expansion,  Next: Unique File Names,  Prev: Relative File Names,  Up: File Names
+
+Functions that Expand Filenames
+-------------------------------
+
+   "Expansion" of a file name means converting a relative file name to
+an absolute one.  Since this is done relative to a default directory,
+you must specify the default directory name as well as the file name to
+be expanded.  Expansion also simplifies file names by eliminating
+redundancies such as `./' and `NAME/../'.
+
+ - Function: expand-file-name filename &optional directory
+     This function converts FILENAME to an absolute file name.  If
+     DIRECTORY is supplied, it is the directory to start with if
+     FILENAME is relative.  (The value of DIRECTORY should itself be an
+     absolute directory name; it may start with `~'.)  Otherwise, the
+     current buffer's value of `default-directory' is used.  For
+     example:
+
+          (expand-file-name "foo")
+               => "/xcssun/users/rms/lewis/foo"
+          (expand-file-name "../foo")
+               => "/xcssun/users/rms/foo"
+          (expand-file-name "foo" "/usr/spool/")
+               => "/usr/spool/foo"
+          (expand-file-name "$HOME/foo")
+               => "/xcssun/users/rms/lewis/$HOME/foo"
+
+     Filenames containing `.' or `..' are simplified to their canonical
+     form:
+
+          (expand-file-name "bar/../foo")
+               => "/xcssun/users/rms/lewis/foo"
+
+     `~/' at the beginning is expanded into the user's home directory.
+     A `/' or `~' following a `/'.
+
+     Note that `expand-file-name' does _not_ expand environment
+     variables; only `substitute-in-file-name' does that.
+
+ - Function: file-relative-name filename &optional directory
+     This function does the inverse of expansion--it tries to return a
+     relative name that is equivalent to FILENAME when interpreted
+     relative to DIRECTORY.
+
+     If DIRECTORY is `nil' or omitted, the value of `default-directory'
+     is used.
+
+          (file-relative-name "/foo/bar" "/foo/")
+               => "bar")
+          (file-relative-name "/foo/bar" "/hack/")
+               => "../foo/bar")
+
+ - Variable: default-directory
+     The value of this buffer-local variable is the default directory
+     for the current buffer.  It should be an absolute directory name;
+     it may start with `~'.  This variable is local in every buffer.
+
+     `expand-file-name' uses the default directory when its second
+     argument is `nil'.
+
+     On Unix systems, the value is always a string ending with a slash.
+
+          default-directory
+               => "/user/lewis/manual/"
+
+ - Function: substitute-in-file-name filename
+     This function replaces environment variable references in FILENAME
+     with the environment variable values.  Following standard Unix
+     shell syntax, `$' is the prefix to substitute an environment
+     variable value.
+
+     The environment variable name is the series of alphanumeric
+     characters (including underscores) that follow the `$'.  If the
+     character following the `$' is a `{', then the variable name is
+     everything up to the matching `}'.
+
+     Here we assume that the environment variable `HOME', which holds
+     the user's home directory name, has value `/xcssun/users/rms'.
+
+          (substitute-in-file-name "$HOME/foo")
+               => "/xcssun/users/rms/foo"
+
+     After substitution, a `/' or `~' following a `/' is taken to be
+     the start of an absolute file name that overrides what precedes
+     it, so everything before that `/' or `~' is deleted.  For example:
+
+          (substitute-in-file-name "bar/~/foo")
+               => "~/foo"
+          (substitute-in-file-name "/usr/local/$HOME/foo")
+               => "/xcssun/users/rms/foo"
+
+
+File: lispref.info,  Node: Unique File Names,  Next: File Name Completion,  Prev: File Name Expansion,  Up: File Names
+
+Generating Unique File Names
+----------------------------
+
+   Some programs need to write temporary files.  Here is the usual way
+to construct a name for such a file:
+
+     (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
+
+Here we use `(temp-directory)' to specify a directory for temporary
+files--under Unix, it will normally evaluate to `"/tmp/"'.  The job of
+`make-temp-name' is to prevent two different users or two different
+processes from trying to use the same name.
+
+ - Function: temp-directory
+     This function returns the name of the directory to use for
+     temporary files.  Under Unix, this will be the value of `TMPDIR',
+     defaulting to `/tmp'.  On Windows, this will be obtained from the
+     `TEMP' or `TMP' environment variables, defaulting to `/'.
+
+     Note that the `temp-directory' function does not exist under FSF
+     Emacs.
+
+ - Function: make-temp-name prefix
+     This function generates a temporary file name starting with
+     PREFIX.  The Emacs process number forms part of the result, so
+     there is no danger of generating a name being used by another
+     process.
+
+          (make-temp-name "/tmp/foo")
+               => "/tmp/fooGaAQjC"
+
+     In addition, this function makes an attempt to choose a name that
+     does not specify an existing file.  To make this work, PREFIX
+     should be an absolute file name.
+
+     To avoid confusion, each Lisp application should preferably use a
+     unique PREFIX to `make-temp-name'.
+
+
+File: lispref.info,  Node: File Name Completion,  Next: User Name Completion,  Prev: Unique File Names,  Up: File Names
+
+File Name Completion
+--------------------
+
+   This section describes low-level subroutines for completing a file
+name.  For other completion functions, see *Note Completion::.
+
+ - Function: file-name-all-completions partial-filename directory
+     This function returns a list of all possible completions for files
+     whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
+     The order of the completions is the order of the files in the
+     directory, which is unpredictable and conveys no useful
+     information.
+
+     The argument PARTIAL-FILENAME must be a file name containing no
+     directory part and no slash.  The current buffer's default
+     directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
+
+     File names which end with any member of
+     `completion-ignored-extensions' are not considered as possible
+     completions for PARTIAL-FILENAME unless there is no other possible
+     completion. `completion-ignored-extensions' is not applied to the
+     names of directories.
+
+     In the following example, suppose that the current default
+     directory, `~rms/lewis', has five files whose names begin with `f':
+     `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
+
+          (file-name-all-completions "f" "")
+               => ("foo" "file~" "file.c.~2~"
+                          "file.c.~1~" "file.c")
+          
+          (file-name-all-completions "fo" "")
+               => ("foo")
+
+ - Function: file-name-completion partial-filename directory
+     This function completes the file name PARTIAL-FILENAME in directory
+     DIRECTORY.  It returns the longest prefix common to all file names
+     in directory DIRECTORY that start with PARTIAL-FILENAME.
+
+     If only one match exists and PARTIAL-FILENAME matches it exactly,
+     the function returns `t'.  The function returns `nil' if directory
+     DIRECTORY contains no name starting with PARTIAL-FILENAME.
+
+     File names which end with any member of
+     `completion-ignored-extensions' are not considered as possible
+     completions for PARTIAL-FILENAME unless there is no other possible
+     completion. `completion-ignored-extensions' is not applied to the
+     names of directories.
+
+     In the following example, suppose that the current default
+     directory has five files whose names begin with `f': `foo',
+     `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
+
+          (file-name-completion "fi" "")
+               => "file"
+          
+          (file-name-completion "file.c.~1" "")
+               => "file.c.~1~"
+          
+          (file-name-completion "file.c.~1~" "")
+               => t
+          
+          (file-name-completion "file.c.~3" "")
+               => nil
+
+ - User Option: completion-ignored-extensions
+     `file-name-completion' usually ignores file names that end in any
+     string in this list.  It does not ignore them when all the possible
+     completions end in one of these suffixes or when a buffer showing
+     all possible completions is displayed.
+
+     A typical value might look like this:
+
+          completion-ignored-extensions
+               => (".o" ".elc" "~" ".dvi")
+
+
+File: lispref.info,  Node: User Name Completion,  Prev: File Name Completion,  Up: File Names
+
+User Name Completion
+--------------------
+
+   This section describes low-level subroutines for completing a user
+name.  For other completion functions, see *Note Completion::.
+
+ - Function: user-name-all-completions partial-username
+     This function returns a list of all possible completions for a
+     user name starting with PARTIAL-USERNAME.  The order of the
+     completions is unpredictable and conveys no useful information.
+
+     The argument PARTIAL-USERNAME must be a partial user name
+     containing no tilde character and no slash.
+
+ - Function: user-name-completion partial-username
+     This function completes a user name from PARTIAL-USERNAME.  It
+     returns the longest prefix common to all user names that start with
+     PARTIAL-USERNAME.
+
+     If only one match exists and PARTIAL-USERNAME matches it exactly,
+     the function returns `t'.  The function returns `nil' if no user
+     name starting with PARTIAL-USERNAME exists.
+
+ - Function: user-name-completion-1 partial-username
+     This function completes the partial user name PARTIAL-USERNAME,
+     like `user-name-completion', differing only in the return value.
+     This function returns the cons of the completion returned by
+     `user-name-completion', and a boolean indicating whether that
+     completion was unique.
+
+
+File: lispref.info,  Node: Contents of Directories,  Next: Create/Delete Dirs,  Prev: File Names,  Up: Files
+
+Contents of Directories
+=======================
+
+   A directory is a kind of file that contains other files entered under
+various names.  Directories are a feature of the file system.
+
+   XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command.  In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ - Function: directory-files directory &optional full-name match-regexp
+          nosort files-only
+     This function returns a list of the names of the files in the
+     directory DIRECTORY.  By default, the list is in alphabetical
+     order.
+
+     If FULL-NAME is non-`nil', the function returns the files'
+     absolute file names.  Otherwise, it returns just the names
+     relative to the specified directory.
+
+     If MATCH-REGEXP is non-`nil', this function returns only those
+     file names that contain that regular expression--the other file
+     names are discarded from the list.
+
+     If NOSORT is non-`nil', `directory-files' does not sort the list,
+     so you get the file names in no particular order.  Use this if you
+     want the utmost possible speed and don't care what order the files
+     are processed in.  If the order of processing is visible to the
+     user, then the user will probably be happier if you do sort the
+     names.
+
+     If FILES-ONLY is the symbol `t', then only the "files" in the
+     directory will be returned; subdirectories will be excluded.  If
+     FILES-ONLY is not `nil' and not `t', then only the subdirectories
+     will be returned.  Otherwise, if FILES-ONLY is `nil' (the default)
+     then both files and subdirectories will be returned.
+
+          (directory-files "~lewis")
+               => ("#foo#" "#foo.el#" "." ".."
+                   "dired-mods.el" "files.texi"
+                   "files.texi.~1~")
+
+     An error is signaled if DIRECTORY is not the name of a directory
+     that can be read.
+
+ - Function: insert-directory file switches &optional wildcard
+          full-directory-p
+     This function inserts (in the current buffer) a directory listing
+     for directory FILE, formatted with `ls' according to SWITCHES.  It
+     leaves point after the inserted text.
+
+     The argument FILE may be either a directory name or a file
+     specification including wildcard characters.  If WILDCARD is
+     non-`nil', that means treat FILE as a file specification with
+     wildcards.
+
+     If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+     and switches do not contain `-d', so that the listing should show
+     the full contents of the directory.  (The `-d' option to `ls' says
+     to describe a directory itself rather than its contents.)
+
+     This function works by running a directory listing program whose
+     name is in the variable `insert-directory-program'.  If WILDCARD is
+     non-`nil', it also runs the shell specified by `shell-file-name',
+     to expand the wildcards.
+
+ - Variable: insert-directory-program
+     This variable's value is the program to run to generate a
+     directory listing for the function `insert-directory'.
+
+
+File: lispref.info,  Node: Create/Delete Dirs,  Next: Magic File Names,  Prev: Contents of Directories,  Up: Files
+
+Creating and Deleting Directories
+=================================
+
+   Most XEmacs Lisp file-manipulation functions get errors when used on
+files that are directories.  For example, you cannot delete a directory
+with `delete-file'.  These special functions exist to create and delete
+directories.
+
+ - Command: make-directory dirname &optional parents
+     This function creates a directory named DIRNAME.  Interactively,
+     the default choice of directory to create is the current default
+     directory for file names.  That is useful when you have visited a
+     file in a nonexistent directory.
+
+     Non-interactively, optional argument PARENTS says whether to
+     create parent directories if they don't exist. (Interactively, this
+     always happens.)
+
+ - Command: delete-directory dirname
+     This function deletes the directory named DIRNAME.  The function
+     `delete-file' does not work for files that are directories; you
+     must use `delete-directory' in that case.
+
+
+File: lispref.info,  Node: Magic File Names,  Next: Partial Files,  Prev: Create/Delete Dirs,  Up: Files
+
+Making Certain File Names "Magic"
+=================================
+
+   You can implement special handling for certain file names.  This is
+called making those names "magic".  You must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+XEmacs file operations for file names that do match.
+
+   The variable `file-name-handler-alist' holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler.  Each element has this form:
+
+     (REGEXP . HANDLER)
+
+All the XEmacs primitives for file access and file name transformation
+check the given file name against `file-name-handler-alist'.  If the
+file name matches REGEXP, the primitives handle that file by calling
+HANDLER.
+
+   The first argument given to HANDLER is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation.  (The first of these arguments is typically the file name
+itself.)  For example, if you do this:
+
+     (file-exists-p FILENAME)
+
+and FILENAME has handler HANDLER, then HANDLER is called like this:
+
+     (funcall HANDLER 'file-exists-p FILENAME)
+
+   Here are the operations that a magic file name handler gets to
+handle:
+
+`add-name-to-file', `copy-file', `delete-directory', `delete-file',
+`diff-latest-backup-file', `directory-file-name', `directory-files',
+`dired-compress-file', `dired-uncache', `expand-file-name',
+`file-accessible-directory-p', `file-attributes', `file-directory-p',
+`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
+`file-name-all-completions', `file-name-as-directory',
+`file-name-completion', `file-name-directory', `file-name-nondirectory',
+`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
+`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
+`get-file-buffer', `insert-directory', `insert-file-contents', `load',
+`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
+`set-visited-file-modtime', `unhandled-file-name-directory',
+`verify-visited-file-modtime', `write-region'.
+
+   Handlers for `insert-file-contents' typically need to clear the
+buffer's modified flag, with `(set-buffer-modified-p nil)', if the
+VISIT argument is non-`nil'.  This also has the effect of unlocking the
+buffer if it is locked.
+
+   The handler function must handle all of the above operations, and
+possibly others to be added in the future.  It need not implement all
+these operations itself--when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation "in the usual way".  It should always reinvoke the primitive
+for an operation it does not recognize.  Here's one way to do this:
+
+     (defun my-file-handler (operation &rest args)
+       ;; First check for the specific operations
+       ;; that we have special handling for.
+       (cond ((eq operation 'insert-file-contents) ...)
+             ((eq operation 'write-region) ...)
+             ...
+             ;; Handle any operation we don't know about.
+             (t (let ((inhibit-file-name-handlers
+                      (cons 'my-file-handler
+                            (and (eq inhibit-file-name-operation operation)
+                                 inhibit-file-name-handlers)))
+                     (inhibit-file-name-operation operation))
+                  (apply operation args)))))
+
+   When a handler function decides to call the ordinary Emacs primitive
+for the operation at hand, it needs to prevent the primitive from
+calling the same handler once again, thus leading to an infinite
+recursion.  The example above shows how to do this, with the variables
+`inhibit-file-name-handlers' and `inhibit-file-name-operation'.  Be
+careful to use them exactly as shown above; the details are crucial for
+proper behavior in the case of multiple handlers, and for operations
+that have two file names that may each have handlers.
+
+ - Variable: inhibit-file-name-handlers
+     This variable holds a list of handlers whose use is presently
+     inhibited for a certain operation.
+
+ - Variable: inhibit-file-name-operation
+     The operation for which certain handlers are presently inhibited.
+
+ - Function: find-file-name-handler filename &optional operation
+     This function returns the handler function for file name FILENAME,
+     or `nil' if there is none.  The argument OPERATION should be the
+     operation to be performed on the file--the value you will pass to
+     the handler as its first argument when you call it.  The operation
+     is needed for comparison with `inhibit-file-name-operation'.
+
+ - Function: file-local-copy filename
+     This function copies file FILENAME to an ordinary non-magic file,
+     if it isn't one already.
+
+     If FILENAME specifies a "magic" file name, which programs outside
+     Emacs cannot directly read or write, this copies the contents to
+     an ordinary file and returns that file's name.
+
+     If FILENAME is an ordinary file name, not magic, then this function
+     does nothing and returns `nil'.
+
+ - Function: unhandled-file-name-directory filename
+     This function returns the name of a directory that is not magic.
+     It uses the directory part of FILENAME if that is not magic.
+     Otherwise, it asks the handler what to do.
+
+     This is useful for running a subprocess; every subprocess must
+     have a non-magic directory to serve as its current directory, and
+     this function is a good way to come up with one.
+
+
+File: lispref.info,  Node: Partial Files,  Next: Format Conversion,  Prev: Magic File Names,  Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+
+File: lispref.info,  Node: Intro to Partial Files,  Next: Creating a Partial File,  Up: Partial Files
+
+Intro to Partial Files
+----------------------
+
+   A "partial file" is a section of a buffer (called the "master
+buffer") that is placed in its own buffer and treated as its own file.
+Changes made to the partial file are not reflected in the master buffer
+until the partial file is "saved" using the standard buffer save
+commands.  Partial files can be "reverted" (from the master buffer)
+just like normal files.  When a file part is active on a master buffer,
+that section of the master buffer is marked as read-only.  Two file
+parts on the same master buffer are not allowed to overlap.  Partial
+file buffers are indicated by the words `File Part' in the modeline.
+
+   The master buffer knows about all the partial files that are active
+on it, and thus killing or reverting the master buffer will be handled
+properly.  When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+   When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+
+File: lispref.info,  Node: Creating a Partial File,  Next: Detached Partial Files,  Prev: Intro to Partial Files,  Up: Partial Files
+
+Creating a Partial File
+-----------------------
+
+ - Command: make-file-part &optional start end name buffer
+     Make a file part on buffer BUFFER out of the region.  Call it
+     NAME.  This command creates a new buffer containing the contents
+     of the region and marks the buffer as referring to the specified
+     buffer, called the "master buffer".  When the file-part buffer is
+     saved, its changes are integrated back into the master buffer.
+     When the master buffer is deleted, all file parts are deleted with
+     it.
+
+     When called from a function, expects four arguments, START, END,
+     NAME, and BUFFER, all of which are optional and default to the
+     beginning of BUFFER, the end of BUFFER, a name generated from
+     BUFFER's name, and the current buffer, respectively.
+
+
+File: lispref.info,  Node: Detached Partial Files,  Prev: Creating a Partial File,  Up: Partial Files
+
+Detached Partial Files
+----------------------
+
+   Every partial file has an extent in the master buffer associated
+with it (called the "master extent"), marking where in the master
+buffer the partial file begins and ends.  If the text in master buffer
+that is contained by the extent is deleted, then the extent becomes
+"detached", meaning that it no longer refers to a specific region of
+the master buffer.  This can happen either when the text is deleted
+directly or when the master buffer is reverted.  Neither of these should
+happen in normal usage because the master buffer should generally not be
+edited directly.
+
+   Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached.  If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part.  The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+
+File: lispref.info,  Node: Format Conversion,  Next: Files and MS-DOS,  Prev: Partial Files,  Up: Files
+
+File Format Conversion
+======================
+
+   The variable `format-alist' defines a list of "file formats", which
+describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+ - Variable: format-alist
+     This list contains one format definition for each defined file
+     format.
+
+   Each format definition is a list of this form:
+
+     (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
+
+   Here is what the elements in a format definition mean:
+
+NAME
+     The name of this format.
+
+DOC-STRING
+     A documentation string for the format.
+
+REGEXP
+     A regular expression which is used to recognize files represented
+     in this format.
+
+FROM-FN
+     A function to call to decode data in this format (to convert file
+     data into the usual Emacs data representation).
+
+     The FROM-FN is called with two args, BEGIN and END, which specify
+     the part of the buffer it should convert.  It should convert the
+     text by editing it in place.  Since this can change the length of
+     the text, FROM-FN should return the modified end position.
+
+     One responsibility of FROM-FN is to make sure that the beginning
+     of the file no longer matches REGEXP.  Otherwise it is likely to
+     get called again.
+
+TO-FN
+     A function to call to encode data in this format (to convert the
+     usual Emacs data representation into this format).
+
+     The TO-FN is called with two args, BEGIN and END, which specify
+     the part of the buffer it should convert.  There are two ways it
+     can do the conversion:
+
+        * By editing the buffer in place.  In this case, TO-FN should
+          return the end-position of the range of text, as modified.
+
+        * By returning a list of annotations.  This is a list of
+          elements of the form `(POSITION . STRING)', where POSITION is
+          an integer specifying the relative position in the text to be
+          written, and STRING is the annotation to add there.  The list
+          must be sorted in order of position when TO-FN returns it.
+
+          When `write-region' actually writes the text from the buffer
+          to the file, it intermixes the specified annotations at the
+          corresponding positions.  All this takes place without
+          modifying the buffer.
+
+MODIFY
+     A flag, `t' if the encoding function modifies the buffer, and
+     `nil' if it works by returning a list of annotations.
+
+MODE
+     A mode function to call after visiting a file converted from this
+     format.
+
+   The function `insert-file-contents' automatically recognizes file
+formats when it reads the specified file.  It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format.  Then it checks all the known formats over again.  It
+keeps checking them until none of them is applicable.
+
+   Visiting a file, with `find-file-noselect' or the commands that use
+it, performs conversion likewise (because it calls
+`insert-file-contents'); it also calls the mode function for each
+format that it decodes.  It stores a list of the format names in the
+buffer-local variable `buffer-file-format'.
+
+ - Variable: buffer-file-format
+     This variable states the format of the visited file.  More
+     precisely, this is a list of the file format names that were
+     decoded in the course of visiting the current buffer's file.  It
+     is always local in all buffers.
+
+   When `write-region' writes data into a file, it first calls the
+encoding functions for the formats listed in `buffer-file-format', in
+the order of appearance in the list.
+
+ - Command: format-write-file file format
+     This command writes the current buffer contents into the file FILE
+     in format FORMAT, and makes that format the default for future
+     saves of the buffer.  The argument FORMAT is a list of format
+     names.
+
+ - Command: format-find-file file format
+     This command finds the file FILE, converting it according to
+     format FORMAT.  It also makes FORMAT the default if the buffer is
+     saved later.
+
+     The argument FORMAT is a list of format names.  If FORMAT is
+     `nil', no conversion takes place.  Interactively, typing just
+     <RET> for FORMAT specifies `nil'.
+
+ - Command: format-insert-file file format &optional start end
+     This command inserts the contents of file FILE, converting it
+     according to format FORMAT.  If START and END are non-`nil', they
+     specify which part of the file to read, as in
+     `insert-file-contents' (*note Reading from Files::).
+
+     The return value is like what `insert-file-contents' returns: a
+     list of the absolute file name and the length of the data inserted
+     (after conversion).
+
+     The argument FORMAT is a list of format names.  If FORMAT is
+     `nil', no conversion takes place.  Interactively, typing just
+     <RET> for FORMAT specifies `nil'.
+
+ - Variable: auto-save-file-format
+     This variable specifies the format to use for auto-saving.  Its
+     value is a list of format names, just like the value of
+     `buffer-file-format'; but it is used instead of
+     `buffer-file-format' for writing auto-save files.  This variable
+     is always local in all buffers.
+
+
+File: lispref.info,  Node: Files and MS-DOS,  Prev: Format Conversion,  Up: Files
+
+Files and MS-DOS
+================
+
+   Emacs on MS-DOS makes a distinction between text files and binary
+files.  This is necessary because ordinary text files on MS-DOS use a
+two character sequence between lines: carriage-return and linefeed
+(CRLF).  Emacs expects just a newline character (a linefeed) between
+lines.  When Emacs reads or writes a text file on MS-DOS, it needs to
+convert the line separators.  This means it needs to know which files
+are text files and which are binary.  It makes this decision when
+visiting a file, and records the decision in the variable
+`buffer-file-type' for use when the file is saved.
+
+   *Note MS-DOS Subprocesses::, for a related feature for subprocesses.
+
+ - Variable: buffer-file-type
+     This variable, automatically local in each buffer, records the
+     file type of the buffer's visited file.  The value is `nil' for
+     text, `t' for binary.
+
+ - Function: find-buffer-file-type filename
+     This function determines whether file FILENAME is a text file or a
+     binary file.  It returns `nil' for text, `t' for binary.
+
+ - User Option: file-name-buffer-file-type-alist
+     This variable holds an alist for distinguishing text files from
+     binary files.  Each element has the form (REGEXP . TYPE), where
+     REGEXP is matched against the file name, and TYPE may be is `nil'
+     for text, `t' for binary, or a function to call to compute which.
+     If it is a function, then it is called with a single argument (the
+     file name) and should return `t' or `nil'.
+
+ - User Option: default-buffer-file-type
+     This variable specifies the default file type for files whose names
+     don't indicate anything in particular.  Its value should be `nil'
+     for text, or `t' for binary.
+
+ - Command: find-file-text filename
+     Like `find-file', but treat the file as text regardless of its
+     name.
+
+ - Command: find-file-binary filename
+     Like `find-file', but treat the file as binary regardless of its
+     name.
+
+
+File: lispref.info,  Node: Backups and Auto-Saving,  Next: Buffers,  Prev: Files,  Up: Top
+
+Backups and Auto-Saving
+***********************
+
+   Backup files and auto-save files are two methods by which XEmacs
+tries to protect the user from the consequences of crashes or of the
+user's own errors.  Auto-saving preserves the text from earlier in the
+current editing session; backup files preserve file contents prior to
+the current session.
+
+* Menu:
+
+* Backup Files::   How backup files are made; how their names are chosen.
+* Auto-Saving::    How auto-save files are made; how their names are chosen.
+* Reverting::      `revert-buffer', and how to customize what it does.
+
+
+File: lispref.info,  Node: Backup Files,  Next: Auto-Saving,  Up: Backups and Auto-Saving
+
+Backup Files
+============
+
+   A "backup file" is a copy of the old contents of a file you are
+editing.  XEmacs makes a backup file the first time you save a buffer
+into its visited file.  Normally, this means that the backup file
+contains the contents of the file as it was before the current editing
+session.  The contents of the backup file normally remain unchanged once
+it exists.
+
+   Backups are usually made by renaming the visited file to a new name.
+Optionally, you can specify that backup files should be made by copying
+the visited file.  This choice makes a difference for files with
+multiple names; it also can affect whether the edited file remains owned
+by the original owner or becomes owned by the user editing it.
+
+   By default, XEmacs makes a single backup file for each file edited.
+You can alternatively request numbered backups; then each new backup
+file gets a new name.  You can delete old numbered backups when you
+don't want them any more, or XEmacs can delete them automatically.
+
+* Menu:
+
+* Making Backups::     How XEmacs makes backup files, and when.
+* Rename or Copy::     Two alternatives: renaming the old file or copying it.
+* Numbered Backups::   Keeping multiple backups for each source file.
+* Backup Names::       How backup file names are computed; customization.
+
+
+File: lispref.info,  Node: Making Backups,  Next: Rename or Copy,  Up: Backup Files
+
+Making Backup Files
+-------------------
+
+ - Function: backup-buffer
+     This function makes a backup of the file visited by the current
+     buffer, if appropriate.  It is called by `save-buffer' before
+     saving the buffer the first time.
+
+ - Variable: buffer-backed-up
+     This buffer-local variable indicates whether this buffer's file has
+     been backed up on account of this buffer.  If it is non-`nil', then
+     the backup file has been written.  Otherwise, the file should be
+     backed up when it is next saved (if backups are enabled).  This is
+     a permanent local; `kill-local-variables' does not alter it.
+
+ - User Option: make-backup-files
+     This variable determines whether or not to make backup files.  If
+     it is non-`nil', then XEmacs creates a backup of each file when it
+     is saved for the first time--provided that `backup-inhibited' is
+     `nil' (see below).
+
+     The following example shows how to change the `make-backup-files'
+     variable only in the `RMAIL' buffer and not elsewhere.  Setting it
+     `nil' stops XEmacs from making backups of the `RMAIL' file, which
+     may save disk space.  (You would put this code in your `.emacs'
+     file.)
+
+          (add-hook 'rmail-mode-hook
+                    (function (lambda ()
+                                (make-local-variable
+                                 'make-backup-files)
+                                (setq make-backup-files nil))))
+
+ - Variable: backup-enable-predicate
+     This variable's value is a function to be called on certain
+     occasions to decide whether a file should have backup files.  The
+     function receives one argument, a file name to consider.  If the
+     function returns `nil', backups are disabled for that file.
+     Otherwise, the other variables in this section say whether and how
+     to make backups.
+
+     The default value is this:
+
+          (lambda (name)
+            (or (< (length name) 5)
+                (not (string-equal "/tmp/"
+                                   (substring name 0 5)))))
+
+ - Variable: backup-inhibited
+     If this variable is non-`nil', backups are inhibited.  It records
+     the result of testing `backup-enable-predicate' on the visited file
+     name.  It can also coherently be used by other mechanisms that
+     inhibit backups based on which file is visited.  For example, VC
+     sets this variable non-`nil' to prevent making backups for files
+     managed with a version control system.
+
+     This is a permanent local, so that changing the major mode does
+     not lose its value.  Major modes should not set this
+     variable--they should set `make-backup-files' instead.
+
diff --text -u /dev/null 'xemacs-21.4.3/info/lispref.info-25'
Index: ././info/lispref.info-25
--- ././info/lispref.info-25	Thu Jan  1 09:00:00 1970
+++ ././info/lispref.info-25	Thu May 17 23:26:54 2001
@@ -0,0 +1,1147 @@
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
+
+INFO-DIR-SECTION XEmacs Editor
+START-INFO-DIR-ENTRY
+* Lispref: (lispref).		XEmacs Lisp Reference Manual.
+END-INFO-DIR-ENTRY
+
+   Edition History:
+
+   GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
+Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
+Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
+XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
+GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
+Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
+Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
+Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
+November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
+
+   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
+Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
+Copyright (C) 1995, 1996 Ben Wing.
+
+   Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that this permission notice may be stated in a
+translation approved by the Foundation.
+
+   Permission is granted to copy and distribute modified versions of
+this manual under the conditions for verbatim copying, provided also
+that the section entitled "GNU General Public License" is included
+exactly as in the original, and provided that the entire resulting
+derived work is distributed under the terms of a permission notice
+identical to this one.
+
+   Permission is granted to copy and distribute translations of this
+manual into another language, under the above conditions for modified
+versions, except that the section entitled "GNU General Public License"
+may be included in a translation approved by the Free Software
+Foundation instead of in the original English.
+
+
+File: lispref.info,  Node: Rename or Copy,  Next: Numbered Backups,  Prev: Making Backups,  Up: Backup Files
+
+Backup by Renaming or by Copying?
+---------------------------------
+
+   There are two ways that XEmacs can make a backup file:
+
+   * XEmacs can rename the original file so that it becomes a backup
+     file, and then write the buffer being saved into a new file.
+     After this procedure, any other names (i.e., hard links) of the
+     original file now refer to the backup file.  The new file is owned
+     by the user doing the editing, and its group is the default for
+     new files written by the user in that directory.
+
+   * XEmacs can copy the original file into a backup file, and then
+     overwrite the original file with new contents.  After this
+     procedure, any other names (i.e., hard links) of the original file
+     still refer to the current version of the file.  The file's owner
+     and group will be unchanged.
+
+   The first method, renaming, is the default.
+
+   The variable `backup-by-copying', if non-`nil', says to use the
+second method, which is to copy the original file and overwrite it with
+the new buffer contents.  The variable `file-precious-flag', if
+non-`nil', also has this effect (as a sideline of its main
+significance).  *Note Saving Buffers::.
+
+ - Variable: backup-by-copying
+     If this variable is non-`nil', XEmacs always makes backup files by
+     copying.
+
+   The following two variables, when non-`nil', cause the second method
+to be used in certain special cases.  They have no effect on the
+treatment of files that don't fall into the special cases.
+
+ - Variable: backup-by-copying-when-linked
+     If this variable is non-`nil', XEmacs makes backups by copying for
+     files with multiple names (hard links).
+
+     This variable is significant only if `backup-by-copying' is `nil',
+     since copying is always used when that variable is non-`nil'.
+
+ - Variable: backup-by-copying-when-mismatch
+     If this variable is non-`nil', XEmacs makes backups by copying in
+     cases where renaming would change either the owner or the group of
+     the file.
+
+     The value has no effect when renaming would not alter the owner or
+     group of the file; that is, for files which are owned by the user
+     and whose group matches the default for a new file created there
+     by the user.
+
+     This variable is significant only if `backup-by-copying' is `nil',
+     since copying is always used when that variable is non-`nil'.
+
+
+File: lispref.info,  Node: Numbered Backups,  Next: Backup Names,  Prev: Rename or Copy,  Up: Backup Files
+
+Making and Deleting Numbered Backup Files
+-----------------------------------------
+
+   If a file's name is `foo', the names of its numbered backup versions
+are `foo.~V~', for various integers V, like this: `foo.~1~', `foo.~2~',
+`foo.~3~', ..., `foo.~259~', and so on.
+
+ - User Option: version-control
+     This variable controls whether to make a single non-numbered backup
+     file or multiple numbered backups.
+
+    `nil'
+          Make numbered backups if the visited file already has
+          numbered backups; otherwise, do not.
+
+    `never'
+          Do not make numbered backups.
+
+    ANYTHING ELSE
+          Make numbered backups.
+
+   The use of numbered backups ultimately leads to a large number of
+backup versions, which must then be deleted.  XEmacs can do this
+automatically or it can ask the user whether to delete them.
+
+ - User Option: kept-new-versions
+     The value of this variable is the number of newest versions to keep
+     when a new numbered backup is made.  The newly made backup is
+     included in the count.  The default value is 2.
+
+ - User Option: kept-old-versions
+     The value of this variable is the number of oldest versions to keep
+     when a new numbered backup is made.  The default value is 2.
+
+   If there are backups numbered 1, 2, 3, 5, and 7, and both of these
+variables have the value 2, then the backups numbered 1 and 2 are kept
+as old versions and those numbered 5 and 7 are kept as new versions;
+backup version 3 is excess.  The function `find-backup-file-name'
+(*note Backup Names::) is responsible for determining which backup
+versions to delete, but does not delete them itself.
+
+ - User Option: delete-old-versions
+     If this variable is non-`nil', then saving a file deletes excess
+     backup versions silently.  Otherwise, it asks the user whether to
+     delete them.
+
+ - User Option: dired-kept-versions
+     This variable specifies how many of the newest backup versions to
+     keep in the Dired command `.' (`dired-clean-directory').  That's
+     the same thing `kept-new-versions' specifies when you make a new
+     backup file.  The default value is 2.
+
+
+File: lispref.info,  Node: Backup Names,  Prev: Numbered Backups,  Up: Backup Files
+
+Naming Backup Files
+-------------------
+
+   The functions in this section are documented mainly because you can
+customize the naming conventions for backup files by redefining them.
+If you change one, you probably need to change the rest.
+
+ - Function: backup-file-name-p filename
+     This function returns a non-`nil' value if FILENAME is a possible
+     name for a backup file.  A file with the name FILENAME need not
+     exist; the function just checks the name.
+
+          (backup-file-name-p "foo")
+               => nil
+          (backup-file-name-p "foo~")
+               => 3
+
+     The standard definition of this function is as follows:
+
+          (defun backup-file-name-p (file)
+            "Return non-nil if FILE is a backup file \
+          name (numeric or not)..."
+            (string-match "~$" file))
+
+     Thus, the function returns a non-`nil' value if the file name ends
+     with a `~'.  (We use a backslash to split the documentation
+     string's first line into two lines in the text, but produce just
+     one line in the string itself.)
+
+     This simple expression is placed in a separate function to make it
+     easy to redefine for customization.
+
+ - Function: make-backup-file-name filename
+     This function returns a string that is the name to use for a
+     non-numbered backup file for file FILENAME.  On Unix, this is just
+     FILENAME with a tilde appended.
+
+     The standard definition of this function is as follows:
+
+          (defun make-backup-file-name (file)
+            "Create the non-numeric backup file name for FILE.
+          ..."
+            (concat file "~"))
+
+     You can change the backup-file naming convention by redefining this
+     function.  The following example redefines `make-backup-file-name'
+     to prepend a `.' in addition to appending a tilde:
+
+          (defun make-backup-file-name (filename)
+            (concat "." filename "~"))
+          
+          (make-backup-file-name "backups.texi")
+               => ".backups.texi~"
+
+ - Function: find-backup-file-name filename
+     This function computes the file name for a new backup file for
+     FILENAME.  It may also propose certain existing backup files for
+     deletion.  `find-backup-file-name' returns a list whose CAR is the
+     name for the new backup file and whose CDR is a list of backup
+     files whose deletion is proposed.
+
+     Two variables, `kept-old-versions' and `kept-new-versions',
+     determine which backup versions should be kept.  This function
+     keeps those versions by excluding them from the CDR of the value.
+     *Note Numbered Backups::.
+
+     In this example, the value says that `~rms/foo.~5~' is the name to
+     use for the new backup file, and `~rms/foo.~3~' is an "excess"
+     version that the caller should consider deleting now.
+
+          (find-backup-file-name "~rms/foo")
+               => ("~rms/foo.~5~" "~rms/foo.~3~")
+
+ - Function: file-newest-backup filename
+     This function returns the name of the most recent backup file for
+     FILENAME, or `nil' if that file has no backup files.
+
+     Some file comparison commands use this function so that they can
+     automatically compare a file with its most recent backup.
+
+
+File: lispref.info,  Node: Auto-Saving,  Next: Reverting,  Prev: Backup Files,  Up: Backups and Auto-Saving
+
+Auto-Saving
+===========
+
+   XEmacs periodically saves all files that you are visiting; this is
+called "auto-saving".  Auto-saving prevents you from losing more than a
+limited amount of work if the system crashes.  By default, auto-saves
+happen every 300 keystrokes, or after around 30 seconds of idle time.
+*Note Auto-Save: (xemacs)Auto-Save, for information on auto-save for
+users.  Here we describe the functions used to implement auto-saving
+and the variables that control them.
+
+ - Variable: buffer-auto-save-file-name
+     This buffer-local variable is the name of the file used for
+     auto-saving the current buffer.  It is `nil' if the buffer should
+     not be auto-saved.
+
+          buffer-auto-save-file-name
+          => "/xcssun/users/rms/lewis/#files.texi#"
+
+ - Command: auto-save-mode arg
+     When used interactively without an argument, this command is a
+     toggle switch: it turns on auto-saving of the current buffer if it
+     is off, and vice-versa.  With an argument ARG, the command turns
+     auto-saving on if the value of ARG is `t', a nonempty list, or a
+     positive integer.  Otherwise, it turns auto-saving off.
+
+ - Function: auto-save-file-name-p filename
+     This function returns a non-`nil' value if FILENAME is a string
+     that could be the name of an auto-save file.  It works based on
+     knowledge of the naming convention for auto-save files: a name that
+     begins and ends with hash marks (`#') is a possible auto-save file
+     name.  The argument FILENAME should not contain a directory part.
+
+          (make-auto-save-file-name)
+               => "/xcssun/users/rms/lewis/#files.texi#"
+          (auto-save-file-name-p "#files.texi#")
+               => 0
+          (auto-save-file-name-p "files.texi")
+               => nil
+
+     The standard definition of this function is as follows:
+
+          (defun auto-save-file-name-p (filename)
+            "Return non-nil if FILENAME can be yielded by..."
+            (string-match "^#.*#$" filename))
+
+     This function exists so that you can customize it if you wish to
+     change the naming convention for auto-save files.  If you redefine
+     it, be sure to redefine the function `make-auto-save-file-name'
+     correspondingly.
+
+ - Function: make-auto-save-file-name &optional filename
+     This function returns the file name to use for auto-saving the
+     current buffer.  This is just the file name with hash marks (`#')
+     appended and prepended to it.  This function does not look at the
+     variable `auto-save-visited-file-name' (described below); you
+     should check that before calling this function.
+
+          (make-auto-save-file-name)
+               => "/xcssun/users/rms/lewis/#backup.texi#"
+
+     The standard definition of this function is as follows:
+
+          (defun make-auto-save-file-name ()
+            "Return file name to use for auto-saves \
+          of current buffer.
+          ..."
+            (if buffer-file-name
+                (concat
+                 (file-name-directory buffer-file-name)
+                 "#"
+                 (file-name-nondirectory buffer-file-name)
+                 "#")
+              (expand-file-name
+               (concat "#%" (buffer-name) "#"))))
+
+     This exists as a separate function so that you can redefine it to
+     customize the naming convention for auto-save files.  Be sure to
+     change `auto-save-file-name-p' in a corresponding way.
+
+ - Variable: auto-save-visited-file-name
+     If this variable is non-`nil', XEmacs auto-saves buffers in the
+     files they are visiting.  That is, the auto-save is done in the
+     same file that you are editing.  Normally, this variable is `nil',
+     so auto-save files have distinct names that are created by
+     `make-auto-save-file-name'.
+
+     When you change the value of this variable, the value does not take
+     effect until the next time auto-save mode is reenabled in any given
+     buffer.  If auto-save mode is already enabled, auto-saves continue
+     to go in the same file name until `auto-save-mode' is called again.
+
+ - Function: recent-auto-save-p
+     This function returns `t' if the current buffer has been
+     auto-saved since the last time it was read in or saved.
+
+ - Function: set-buffer-auto-saved
+     This function marks the current buffer as auto-saved.  The buffer
+     will not be auto-saved again until the buffer text is changed
+     again.  The function returns `nil'.
+
+ - User Option: auto-save-interval
+     The value of this variable is the number of characters that XEmacs
+     reads from the keyboard between auto-saves.  Each time this many
+     more characters are read, auto-saving is done for all buffers in
+     which it is enabled.
+
+ - User Option: auto-save-timeout
+     The value of this variable is the number of seconds of idle time
+     that should cause auto-saving.  Each time the user pauses for this
+     long, XEmacs auto-saves any buffers that need it.  (Actually, the
+     specified timeout is multiplied by a factor depending on the size
+     of the current buffer.)
+
+ - Variable: auto-save-hook
+     This normal hook is run whenever an auto-save is about to happen.
+
+ - User Option: auto-save-default
+     If this variable is non-`nil', buffers that are visiting files
+     have auto-saving enabled by default.  Otherwise, they do not.
+
+ - Command: do-auto-save &optional no-message current-only
+     This function auto-saves all buffers that need to be auto-saved.
+     It saves all buffers for which auto-saving is enabled and that
+     have been changed since the previous auto-save.
+
+     Normally, if any buffers are auto-saved, a message that says
+     `Auto-saving...' is displayed in the echo area while auto-saving is
+     going on.  However, if NO-MESSAGE is non-`nil', the message is
+     inhibited.
+
+     If CURRENT-ONLY is non-`nil', only the current buffer is
+     auto-saved.
+
+ - Function: delete-auto-save-file-if-necessary
+     This function deletes the current buffer's auto-save file if
+     `delete-auto-save-files' is non-`nil'.  It is called every time a
+     buffer is saved.
+
+ - Variable: delete-auto-save-files
+     This variable is used by the function
+     `delete-auto-save-file-if-necessary'.  If it is non-`nil', Emacs
+     deletes auto-save files when a true save is done (in the visited
+     file).  This saves disk space and unclutters your directory.
+
+ - Function: rename-auto-save-file
+     This function adjusts the current buffer's auto-save file name if
+     the visited file name has changed.  It also renames an existing
+     auto-save file.  If the visited file name has not changed, this
+     function does nothing.
+
+ - Variable: buffer-saved-size
+     The value of this buffer-local variable is the length of the
+     current buffer as of the last time it was read in, saved, or
+     auto-saved.  This is used to detect a substantial decrease in
+     size, and turn off auto-saving in response.
+
+     If it is -1, that means auto-saving is temporarily shut off in this
+     buffer due to a substantial deletion.  Explicitly saving the buffer
+     stores a positive value in this variable, thus reenabling
+     auto-saving.  Turning auto-save mode off or on also alters this
+     variable.
+
+ - Variable: auto-save-list-file-name
+     This variable (if non-`nil') specifies a file for recording the
+     names of all the auto-save files.  Each time XEmacs does
+     auto-saving, it writes two lines into this file for each buffer
+     that has auto-saving enabled.  The first line gives the name of
+     the visited file (it's empty if the buffer has none), and the
+     second gives the name of the auto-save file.
+
+     If XEmacs exits normally, it deletes this file.  If XEmacs
+     crashes, you can look in the file to find all the auto-save files
+     that might contain work that was otherwise lost.  The
+     `recover-session' command uses these files.
+
+     The default name for this file is in your home directory and
+     starts with `.saves-'.  It also contains the XEmacs process ID and
+     the host name.
+
+
+File: lispref.info,  Node: Reverting,  Prev: Auto-Saving,  Up: Backups and Auto-Saving
+
+Reverting
+=========
+
+   If you have made extensive changes to a file and then change your
+mind about them, you can get rid of them by reading in the previous
+version of the file with the `revert-buffer' command.  *Note Reverting
+a Buffer: (xemacs)Reverting.
+
+ - Command: revert-buffer &optional check-auto-save noconfirm
+          preserve-modes
+     This command replaces the buffer text with the text of the visited
+     file on disk.  This action undoes all changes since the file was
+     visited or saved.
+
+     If the argument CHECK-AUTO-SAVE is non-`nil', and the latest
+     auto-save file is more recent than the visited file,
+     `revert-buffer' asks the user whether to use that instead.
+     Otherwise, it always uses the text of the visited file itself.
+     Interactively, CHECK-AUTO-SAVE is set if there is a numeric prefix
+     argument.
+
+     Normally, `revert-buffer' asks for confirmation before it changes
+     the buffer; but if the argument NOCONFIRM is non-`nil',
+     `revert-buffer' does not ask for confirmation.
+
+     Optional third argument PRESERVE-MODES non-`nil' means don't alter
+     the files modes.  Normally we reinitialize them using
+     `normal-mode'.
+
+     Reverting tries to preserve marker positions in the buffer by
+     using the replacement feature of `insert-file-contents'.  If the
+     buffer contents and the file contents are identical before the
+     revert operation, reverting preserves all the markers.  If they
+     are not identical, reverting does change the buffer; then it
+     preserves the markers in the unchanged text (if any) at the
+     beginning and end of the buffer.  Preserving any additional
+     markers would be problematical.
+
+   You can customize how `revert-buffer' does its work by setting these
+variables--typically, as buffer-local variables.
+
+ - Variable: revert-buffer-function
+     The value of this variable is the function to use to revert this
+     buffer.  If non-`nil', it is called as a function with no
+     arguments to do the work of reverting.  If the value is `nil',
+     reverting works the usual way.
+
+     Modes such as Dired mode, in which the text being edited does not
+     consist of a file's contents but can be regenerated in some other
+     fashion, give this variable a buffer-local value that is a
+     function to regenerate the contents.
+
+ - Variable: revert-buffer-insert-file-contents-function
+     The value of this variable, if non-`nil', is the function to use to
+     insert the updated contents when reverting this buffer.  The
+     function receives two arguments: first the file name to use;
+     second, `t' if the user has asked to read the auto-save file.
+
+ - Variable: before-revert-hook
+     This normal hook is run by `revert-buffer' before actually
+     inserting the modified contents--but only if
+     `revert-buffer-function' is `nil'.
+
+     Font Lock mode uses this hook to record that the buffer contents
+     are no longer fontified.
+
+ - Variable: after-revert-hook
+     This normal hook is run by `revert-buffer' after actually inserting
+     the modified contents--but only if `revert-buffer-function' is
+     `nil'.
+
+     Font Lock mode uses this hook to recompute the fonts for the
+     updated buffer contents.
+
+
+File: lispref.info,  Node: Buffers,  Next: Windows,  Prev: Backups and Auto-Saving,  Up: Top
+
+Buffers
+*******
+
+   A "buffer" is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any window.
+
+* Menu:
+
+* Buffer Basics::       What is a buffer?
+* Current Buffer::      Designating a buffer as current
+                          so primitives will access its contents.
+* Buffer Names::        Accessing and changing buffer names.
+* Buffer File Name::    The buffer file name indicates which file is visited.
+* Buffer Modification:: A buffer is "modified" if it needs to be saved.
+* Modification Time::   Determining whether the visited file was changed
+                         ``behind XEmacs's back''.
+* Read Only Buffers::   Modifying text is not allowed in a read-only buffer.
+* The Buffer List::     How to look at all the existing buffers.
+* Creating Buffers::    Functions that create buffers.
+* Killing Buffers::     Buffers exist until explicitly killed.
+* Indirect Buffers::    An indirect buffer shares text with some other buffer.
+
+
+File: lispref.info,  Node: Buffer Basics,  Next: Current Buffer,  Up: Buffers
+
+Buffer Basics
+=============
+
+   A "buffer" is a Lisp object containing text to be edited.  Buffers
+are used to hold the contents of files that are being visited; there may
+also be buffers that are not visiting files.  While several buffers may
+exist at one time, exactly one buffer is designated the "current
+buffer" at any time.  Most editing commands act on the contents of the
+current buffer.  Each buffer, including the current buffer, may or may
+not be displayed in any windows.
+
+   Buffers in Emacs editing are objects that have distinct names and
+hold text that can be edited.  Buffers appear to Lisp programs as a
+special data type.  You can think of the contents of a buffer as an
+extendible string; insertions and deletions may occur in any part of
+the buffer.  *Note Text::.
+
+   A Lisp buffer object contains numerous pieces of information.  Some
+of this information is directly accessible to the programmer through
+variables, while other information is accessible only through
+special-purpose functions.  For example, the visited file name is
+directly accessible through a variable, while the value of point is
+accessible only through a primitive function.
+
+   Buffer-specific information that is directly accessible is stored in
+"buffer-local" variable bindings, which are variable values that are
+effective only in a particular buffer.  This feature allows each buffer
+to override the values of certain variables.  Most major modes override
+variables such as `fill-column' or `comment-column' in this way.  For
+more information about buffer-local variables and functions related to
+them, see *Note Buffer-Local Variables::.
+
+   For functions and variables related to visiting files in buffers, see
+*Note Visiting Files:: and *Note Saving Buffers::.  For functions and
+variables related to the display of buffers in windows, see *Note
+Buffers and Windows::.
+
+ - Function: bufferp object
+     This function returns `t' if OBJECT is a buffer, `nil' otherwise.
+
+
+File: lispref.info,  Node: Current Buffer,  Next: Buffer Names,  Prev: Buffer Basics,  Up: Buffers
+
+The Current Buffer
+==================
+
+   There are, in general, many buffers in an Emacs session.  At any
+time, one of them is designated as the "current buffer".  This is the
+buffer in which most editing takes place, because most of the primitives
+for examining or changing text in a buffer operate implicitly on the
+current buffer (*note Text::).  Normally the buffer that is displayed on
+the screen in the selected window is the current buffer, but this is not
+always so: a Lisp program can designate any buffer as current
+temporarily in order to operate on its contents, without changing what
+is displayed on the screen.
+
+   The way to designate a current buffer in a Lisp program is by calling
+`set-buffer'.  The specified buffer remains current until a new one is
+designated.
+
+   When an editing command returns to the editor command loop, the
+command loop designates the buffer displayed in the selected window as
+current, to prevent confusion: the buffer that the cursor is in when
+Emacs reads a command is the buffer that the command will apply to.
+(*Note Command Loop::.)  Therefore, `set-buffer' is not the way to
+switch visibly to a different buffer so that the user can edit it.  For
+this, you must use the functions described in *Note Displaying
+Buffers::.
+
+   However, Lisp functions that change to a different current buffer
+should not depend on the command loop to set it back afterwards.
+Editing commands